Developer documentation API v1
Architecture and service boundaries
Separate the control, data and action paths while preserving end-to-end provenance.
From agent intent to financial state
Responsibility decomposition
Hosted agents and external runtimes are clients of the same financial domain. The gateway authenticates principals, evaluates capability access and admits work. Domain services own business invariants; an admitted request still undergoes operation-specific validation.
Evidence services own source and revision semantics. Quantitative services own computation artifacts. Portfolio services own candidate allocations. Policy services determine admissibility. Execution and reconciliation services track external effects. Economic services account for service usage, credit obligations and reward allocations.
Logical request graph
The request path separates evidence and computation from the authority that admits financial effects. Resource references connect the stages without making them one distributed transaction.
Seer agent / external runtime
→ gateway: identity · entitlement · budget
→ evidence → computation / Aura → portfolio proposal
→ policy + action-bound authorization
→ execution adapter → external venue
→ reconciliation → settlement / account projection
Persistent records connect each stage by immutable references.
Research may terminate before the action path.State ownership
| Object | Authoritative owner | Consumer constraint |
|---|---|---|
| Evidence revision | Evidence service, with source attribution | Do not replace an old revision with today’s corrected record. |
| Forecast artifact | Quantitative service | Preserve target, horizon, origin and model revision. |
| Authorization decision | Policy and approval boundary | Bind to an exact action revision and current permissions. |
| Order and fill | Execution service informed by venue records | An internal dispatch log is not a venue-confirmed fill. |
| Settled movement | Relevant account or network confirmation | Do not infer delivery from an order acknowledgment. |
| SCC journal | Economic service | Balance projections derive from attributable postings. |
Consistency boundaries
Within a financial aggregate, state transitions are atomic and conditional on its current revision. A command either advances that revision with its associated journal/event records or leaves the aggregate unchanged. Cross-service work progresses through explicit intermediate states; a failure does not implicitly roll back an effect already accepted by an external venue.
Derived activity views are eventually consistent. They describe recorded work but do not authorize capital allocation. Admission uses the authoritative account, grant and reservation state. This distinction prevents a delayed activity projection from making already-committed funds appear spendable.
Contract stability
Service contracts define input schemas, preconditions, failure semantics and externally observable state transitions. Adapters normalize source-specific representations into these contracts while preserving provenance and coverage.
Changing an adapter does not change the financial meaning of its output. Schema revisions and calculation revisions identify changes that affect clients or reproducibility.
Aggregate consistency and causal order
An aggregate is the smallest record whose invariants change atomically: an action, reservation or reward allocation. Its monotonically increasing revision orders accepted transitions for that record. A projection can lag this revision without changing the authoritative state.
Causality is therefore expressed through references and revisions rather than wall-clock order alone. A forecast references its evidence snapshot; a proposal references its forecast and account snapshot; an authorization references the exact proposal revision. Concurrent work on unrelated accounts has no implied global ordering. This partial order permits independent computation while preserving the dependencies required to explain a financial decision.
Conditional state transition
S_r is the authoritative aggregate at revision r and c a command. The predicate defines logical admission eligibility; a successful atomic commit applies the transition and advances the revision. Storage failure can still prevent a commit. Matching a revision alone is not authorization.