Skip to content
OWP

10. The Cost Record

The Cost Record is the structural representation of cost in the protocol. Every Capability invocation produces one. Cost Records aggregate up the provenance chain to provide cost visibility at every level of the organisational hierarchy.

10.1 Cost Record Schema

A Cost Record MUST contain:

  • cost_record_id — unique within the runtime.
  • envelope_id — Envelope to which the record belongs.
  • event_id — the CapabilityInvoked event the record is bound to.
  • provider_id — the Capability Provider.
  • capability_kind — the Capability kind URI.
  • units — typed cost units (see §10.3).
  • amount — numeric cost in the declared units.
  • attribution — the chain of accountability: Worker → Role → Intent → Function → Workforce.
  • model_or_sku — the Provider-specific model or product identifier, if applicable.
  • is_estimate — boolean, true if the record is a defensible estimate per §8.3.

10.2 Attribution and Aggregation

Cost Records are designed to be aggregable along any prefix of the attribution chain. A conforming runtime MUST support aggregation queries over:

  • A specific Intent and its sub-Intents.
  • A specific Worker over a time window.
  • A specific Role across all Workers holding it.
  • A specific Function across all Workforces.
  • A specific Capability Provider across all uses.

The protocol does not prescribe a query language. It prescribes that aggregation MUST be possible.

10.3 Currency and Unit Normalisation

Cost units are typed. Recognised unit kinds include:

  • Currency units (e.g. aud-cents, usd-cents).
  • Token units (e.g. tokens.input, tokens.output, tokens.cache-read).
  • Time units (e.g. seconds, minutes).
  • Discrete units (e.g. decisions, messages).

A Capability’s Cost Record MAY contain multiple unit entries. For example, an LLM invocation may report both tokens.input and tokens.output, plus a derived usd-cents if the Provider supports currency normalisation.

Implementations SHOULD provide currency normalisation as a runtime service: given a cost in tokens or seconds and a Provider’s pricing schedule, compute the currency cost. The pricing schedule itself is a Provider-furnished artefact, not a protocol-level constant.