Economic contracts
The V1 economic contract lets an extension declare what it knows about costs and observe the usage or amounts that are actually available. It provides the economic memory of execution; it does not yet create a universal budget or approval engine.
What V1 covers
The optional field economics belongs to the contract of the executable that carries the intent: Node or Tool. It is not inherited automatically from another interface even when both use the same service.
The current schema is versioned with schema_version: 1 and can describe three complementary capabilities: declaration, observation et resolution.
The absence of an economic contract or observation never means zero cost.
Economic declaration
The declaration describes what can be known before, or independently from, the actual observed cost.
| Item | Contrat |
|---|---|
perspectives | Named economic views. Their knowledge is unknown, zero, amount or upper_bound. |
amount | Safe integer in the currency's minor unit, only for amount et upper_bound. |
currency | Uppercase currency code associated with the declared amount. |
usage | Couples metric/unit that the executable may be able to observe. |
upper_bound means a declared maximum exposure, not an absolute guarantee of the maximum invoice.
Cost observations
An observation may carry usage, amounts, or a provider reference that enables later reconciliation.
factdescribes an independent fact;deltadescribes a variation to apply to a series;cumulativedescribes the cumulative value of a series and requires aseries_keystable.
Observed amounts indicate a basis engaged or observed, a perspective, an integer amount, and a currency. A provider_reference may link the fact to the partner's billing identity; a provider timestamp may specify when the fact occurred.
Causality and attribution
Each cost has one causal owner: the operation that consumes the resource or creates the economic obligation. Process or Agent totals are aggregations of their descendants, not new expenses.
Parents aggregate the costs of their descendants; the operation that actually consumes the resource remains the single causal owner of the cost.
Do not count the same cost twice because a Tool aggregates a child operation. Declare close to the intent; observe close to the effect that is actually known.
Corrections and late facts
A provider may send a cost or correction after functional execution has ended. V1 preserves economic parentage so those facts remain attributable without reopening the Process or Agent Run.
A late observation corrects economic projections; it does not retroactively change the business result or decision snapshots of the execution.
What V1 does not promise
- no mandatory universal budget;
- no automatic approval before every expense;
- no computable maximum for every operation;
- no implicit zero cost when data is missing;
- no policy that an extension could choose to bypass that of a parent.
Cost declarations do not automatically trigger spending caps or approval. Explicitly plan the required controls before a paid operation.