# COST-001 evidence pack — measured production usage and monetary accounting

> **Status: repository-complete / closed.** The V1 execution plane reserves
> monetary headroom before dispatch, settles measured provider/tool/media usage,
> persists reservation and receipt state, enforces scoped caps, and reconciles
> provider invoices. This status does not claim live provider invoices,
> production billing traffic, external approval decisions, or production unit
> economics.

## Work-package charter

- **Task ID:** `COST-001`
- **Owner:** Oshun creative-orchestration, autonomy, and BFF maintainers;
  implementation owner: Elikem Agudogo
- **Accountable product:** V1 autonomous content execution plane
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** Critical spend-control, provider-billing, recovery, and release
  evidence risk
- **Audit finding:** token-only and report-after-dispatch accounting could omit
  tool/media/provider spend, lose attribution or receipts across restart, race
  past caps, or treat a caller-provided approval string as recovery authority
- **Dependencies:** `AUTH-002`, `AUTH-003`, canonical RUN protocol, durable V1
  plane persistence, scoped release authority, configured price/cap policy, and
  provider usage receipts
- **Affected schemas and content slots:** reservation, receipt, settlement,
  price-table, cap, recovery, estimate-feedback, reconciliation, and persisted
  autonomy-plane records for `veritas.story-explainer`, `nyx.sky-event-brief`,
  `nisaba.study-passage`, and `tara.seasonal-ritual`. No rendered UI or database
  migration changed in this refresh.
- **Linked task IDs:** `COST-001`, `COST-002`, `AUTH-002`, `AUTH-003`,
  `RUN-001`, `REL-002`, `PROOF-001`, and `OBS-001`
- **Rollout strategy:** additive versioned accounting snapshots, then
  pre-dispatch reservations and post-dispatch settlement at every covered
  operation. Deployment rates, caps, and recovery policy remain explicit
  `OSHUN_AUTONOMY_*` configuration.
- **Rollback strategy:** revert the original accounting boundary and subsequent
  persistence/restart hardening together. Partial rollback can strand durable
  reservations or let current callers bypass expected settlement semantics.
- **Evidence-pack location:** this file

## Closure matrix

| Ledger requirement                       | Repository closure proof                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Preserve and label existing token record | The cycle token record remains `realTokenUsage.coverage: producer-planner-only`; it is not relabelled end-to-end. The separate `usageAccounting` summary is `end-to-end-measured` and contains receipts, estimated/actual USD micros, estimate error, and operation totals.                                                                    |
| Instrument all named operations          | The common boundary covers planner, generator, research, structured-output retry, critic, judge sample, reconciliation, media provider, TTS, ASR, translation, embedding, tool, render, GPU, storage, and egress. Owning orchestrator, autonomy, and BFF flows compose those operations through the accountant.                                |
| Exact attribution                        | Every receipt carries tenant, slot, cycle, run, step, attempt, artifact, model, provider, region, and quality-tier attribution. Required identities reject empty values; optional dimensions are explicit `null`; UUID reservation/receipt IDs avoid process-restart reuse.                                                                    |
| Versioned pricing and raw receipts       | Immutable price-table and cost-policy snapshots select the most-specific operation/provider/model/region/quality rate. Provider-billed USD micros are authoritative at an enforced 1:1 basis. Raw non-content usage/billing payload, provider request ID, versions, measured units, reservation, charge, and error remain attached.            |
| Estimate feedback                        | An operation-scoped EWMA learns actual/estimated ratios. Subsequent reservation estimates and the director's `estimatedCostUnits` calibration consume that measured error.                                                                                                                                                                     |
| Eight hard-cap scopes and recovery       | Atomic reservation evaluates per-call, run, cycle, day, month, tenant, provider, and portfolio caps. Normal work cannot consume recovery reserve; approval headroom requires an injected authoritative validator. Stop/degrade/require-approval is decided before dispatch.                                                                    |
| Durable restart behavior                 | Reservations and receipts are serialized with the plane. Restore rejects duplicate receipts, invalid counters, non-quiescent snapshots, and live reservations; reconstructs spent/cap state; and issues fresh UUIDs. Later restart hardening preserves publication/review state beside accounting rather than silently replaying settled work. |
| Provider reconciliation                  | Reconciliation matches immutable internal receipts by provider/invoice period, compares integer USD micros, retains the raw invoice, reports drift/basis points, and alerts above policy threshold. Reconciliation itself is admitted and metered.                                                                                             |

## Authoritative measured accounting boundary

`ProductionUsageAccountant` is the common pre-dispatch admission and
post-dispatch settlement boundary. An accounted operation cannot dispatch until
its monetary reservation succeeds. It covers the director, common-run and agent
loops, critique/retry paths, Yemaya rendering, BFF producers/judges/publisher,
media generation, narration, and dub-faithfulness processing.

Every receipt carries tenant, slot, cycle, run, step, attempt, artifact, model,
provider, region, and quality-tier attribution. Missing optional dimensions are
explicitly `null`; required identity dimensions fail validation when empty.
Reservation and receipt IDs are UUIDs, so a fresh process cannot reuse an
earlier process's identity.

The original cycle token record remains available as
`realTokenUsage.coverage: producer-planner-only`. It is not relabelled as full
coverage. `usageAccounting` is separately labelled `end-to-end-measured` and
reports receipt count, estimated/actual USD micros, error, operation totals, and
the underlying measured receipts.

## Pricing, receipts, and estimate feedback

The checked-in production transfer table defaults to
`oshun-autonomy-2026-07-16.v1`, USD, with an independently versioned cost
policy. The accountant makes immutable copies of both. Measured units use the
most-specific operation/provider/model/region/quality rate. A provider-reported
billed amount is authoritative and uses an enforced 1:1 rate instead of being
added to fallback unit pricing.

Receipts retain the immutable raw non-content provider usage/billing payload,
provider request ID, price-table version, policy version, cost basis, measured
units, reserved estimate, actual charge, and estimate error. Media accepts
provider-billed cost and GPU milliseconds when supplied; narration records
actual audio duration; dub faithfulness measures ASR, translation, and both
embedding calls; publishing records storage byte-seconds and egress bytes.

An operation-scoped EWMA learns actual/estimated ratios. Subsequent admission
estimates and the director's `estimatedCostUnits` calibration consume that
error, so measured experience changes routing rather than only a dashboard.

## Hard caps, durability, and recovery authority

The ledger atomically reserves against all eight requested scopes: per call,
run, cycle, day, month, tenant, provider, and portfolio. Normal work cannot
consume the configured recovery reserve. Recovery work can use it, while
`require-approval` headroom is available only when the injected authoritative
validator accepts the supplied reference; an arbitrary string grants nothing.

Policy actions are `stop`, `degrade`, or `require-approval`, and are produced
before provider/tool/render/publication dispatch. Tests cover cap denial with
zero dispatch, simultaneous reservation races, measured settlement for failed
calls, and isolation of recovery/approval headroom.

Reservations and receipts are now first-class durable snapshot records. Restore
validates receipt uniqueness, counter integrity, and quiescence, rejects live
reservations, reconstructs spend/cap state, and creates new UUID identities
after restart. A forked run/cycle has a local receipt view while settlement
bubbles to ancestors, so one run cannot leak another run's receipts. Later
publication restart hardening preserves the surrounding release/review state
without replaying already-settled operations.

## Provider reconciliation and proof boundary

`reconcileProviderInvoice` matches immutable internal receipts by provider and
invoice period, compares integer USD micros, reports drift and basis points,
retains the raw provider invoice, and invokes the alert sink above threshold.
Reconciliation is itself admitted and metered.

Cost receipts do not substitute for content-release proof. The current narration
regression explicitly proves that real local disclosure, watermark, and
cryptographic signature signals still block when no exact, evidence-bound proof
records exist. A score, boolean, raw signature, or cost receipt cannot
impersonate a C2PA trust-policy verdict, rights receipt, observation, or human
approval.

## Adversarial fixture matrix

| Fixture                                      | Result                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| Any of the 17 operation names                | Measured receipt retains operation and every attribution dimension         |
| Provider returns billed USD micros           | Provider amount is authoritative; fallback unit cost is not double-counted |
| Simultaneous reservations approach a cap     | Atomic admission prevents aggregate overspend                              |
| Normal work reaches recovery reserve         | Denied before dispatch                                                     |
| Unvalidated approval string is supplied      | No approval headroom is granted                                            |
| Provider/tool call fails after dispatch      | Measured charge settles and reservation remainder releases                 |
| Snapshot has live reservation or bad counter | Restore rejects the snapshot                                               |
| Duplicate receipt appears after restart      | Restore rejects duplicate identity                                         |
| Run/cycle session is forked                  | Child summary remains isolated while settlement reaches ancestors          |
| Provider invoice materially drifts           | Reconciliation retains invoice and invokes alert sink                      |
| Real media governance flags lack proof       | Release remains blocked; raw signals cannot substitute for proof records   |

## Automated verification

### Current admitted value ledger

The owning suites were rerun sequentially with `VITEST_MAX_WORKERS=1`. The BFF
row was rerun from the exact source later published as
`73d9e3b8aae38781713effad2203304614fca1b4`.

| UTC interval                                      |  Files |      Result | Surface                                                                |
| ------------------------------------------------- | -----: | ----------: | ---------------------------------------------------------------------- |
| 2026-07-29T14:57:29.722Z–2026-07-29T14:57:33.275Z |     13 | **138/138** | full creative-orchestrator package                                     |
| 2026-07-29T14:57:37.483Z–2026-07-29T14:58:05.593Z |     19 | **289/289** | full creative-autonomy package                                         |
| 2026-07-29T15:00:42.067Z–2026-07-29T15:01:06.405Z |      8 |   **97/97** | BFF accounting, persistence, autonomy, route, dub, and narration slice |
| **Unique total**                                  | **40** | **524/524** | no full-package or focused assertion is counted twice                  |

The former **454/454** total accurately described the smaller historical suite
set.

Representative commands:

```text
VITEST_MAX_WORKERS=1 pnpm --dir libs/oshun/creative-orchestrator exec vitest run
VITEST_MAX_WORKERS=1 pnpm --dir libs/oshun/creative-autonomy exec vitest run
VITEST_MAX_WORKERS=1 pnpm exec vitest run --config apps/oshun/bff/vitest.config.ts <eight COST-001 BFF files>
pnpm exec tsc -p libs/oshun/creative-orchestrator/tsconfig.json --noEmit
pnpm exec tsc -p libs/oshun/creative-autonomy/tsconfig.json --noEmit
node tools/typecheck/ratchet.mjs --app apps/oshun/bff --tsconfig tsconfig.typecheck.json
node scripts/build.mjs                                  # apps/oshun/bff
```

### Type, lint, build, and compatibility gates

- current creative-orchestrator and creative-autonomy root TypeScript
  configurations passed;
- the official BFF baseline ratchet passed twice, including the publication
  hook, with **0 known** and **0 new** app-owned errors;
- the hook's prompt-injection evaluation typecheck also passed;
- the direct BFF Node ESM production bundle passed and emitted `dist/server.js`;
- official package lint targets passed with zero errors and current
  non-task-owned warning backlogs of 8 in creative-orchestrator and 79 in
  creative-autonomy;
- exact ESLint over the changed narration fixture passed with zero warnings;
  Prettier and `git diff --check` passed.

### Refresh-discovered regression and bounded exclusions

The first eight-file BFF run was intentionally retained as red evidence:
**96/97** passed. Its “fully governed narration” fixture still expected raw
scan/C2PA/watermark/disclosure fields to clear release after PROOF-001 made
exact proof records non-substitutable. Production correctly blocked because the
measurement's proof list was empty.

The remediation does not weaken the gate or fabricate fixture proof. It asserts
that the real local disclosure, delivered-byte watermark, and signature signals
are retained, then requires the release to remain blocked with exact
`provenance-c2pa`, `watermark-coverage`, `synthesis-disclosure`, and
`proof rejected` reasons. The full affected slice then passed **97/97**.

The full BFF lint target was not rerun: its historical app-wide baseline is
outside this test-only remediation, while the changed file has zero errors or
warnings. The Nx BFF build target would fan into hundreds of dependencies, so
the target's direct production build command was used. No full-workspace sweep
or AUD-003's separate 54-config refresh was attempted or claimed.

## Artifact identity

These hashes were recomputed from current published implementation tip
`73d9e3b8aae38781713effad2203304614fca1b4`.

| Artifact                             | SHA-256                                                            |
| ------------------------------------ | ------------------------------------------------------------------ |
| Production accounting boundary       | `e33ede124baae843f7588d175fc8d532b5b8fcd3e30c401a4963dc751be743d3` |
| Accounting unit fixtures             | `422fd3c62cffc29cd90831d40549304803ebc1cc1596a8fe4a74ff67098e5b5e` |
| Accounting integration fixtures      | `b555f92efee2537bfb0dfcf5fa39920f2e8843670ae5bfa876ac29a688917d24` |
| BFF accounting composition           | `35bf417eed9acd04f9f3d806037907885fa3af5f4815050b324a29c9f48a67e1` |
| BFF accounting fixtures              | `acf7d0ee00b7d9ca6edc34ccad1715e78b503a272c5ee7e8aed9b931a4588f08` |
| V1 plane composition                 | `2c816b0f29794a2868e383251d2e9e6bbb3c769e2db74b1b4bd4c987f1307ca3` |
| V1 plane integration fixture         | `72c4f8423b3b74cfdd71966cc958169a335584ab795ca4dd0cb64ca362da2f4e` |
| Autonomy director                    | `07ad37afd64d60a268cbc3a0272383a88ebabe4ac0093ca9d67bf1e4c3456256` |
| Common-run adapter                   | `0928901944a1e8430b3fe0df24f1ddadaedd70c8756731f68f234a5dd779865d` |
| Dub-faithfulness measurement         | `2cf4cd68d8faf722877436edd18bcf3594d771a6ce2fd8a9858a5e2afa2ce828` |
| Narration proof-semantics regression | `e7e6f0269ebb6de2184e904d34ac163744f783f3a00d1ae7ce6f1d265b592be6` |
| Workspace dependency lock            | `08b055786e9b8a6104d5313601d7eef3205dedcf395066fd9a8264c9859d690f` |

## Human authority and external deployment boundary

Repository publication of deterministic accounting policy and fixtures requires
no fabricated human signoff, and none is claimed.

- scripted and boundary providers supply automated raw receipts; no live
  OpenRouter credential, production provider invoice, or external provider that
  always reports GPU time is claimed;
- provider GPU and billed-cost fields are recorded when the provider returns
  them. Required missing usage fails closed at governed boundaries;
- approval headroom requires a configured authoritative validator. Tests prove
  that an arbitrary approval reference cannot grant it, but do not claim a live
  human approval;
- the checked-in transfer table and environment policy are repository
  configuration, not proof of production business-unit economics;
- cost receipts do not replace rights, consent, C2PA trust, human approval, or
  other release evidence;
- no production traffic, provider reconciliation, billing outcome, human
  decision, or deployment is claimed.

## Resource-safe verification and UI scope

The refresh host was `app-dev-server`, Ubuntu 24.04.4 LTS, Linux
`6.8.0-134-generic` x86_64, with 15 GiB RAM, 31 GiB swap, and 16 GiB free disk.
The toolchain was Node.js `v24.15.0`, pnpm `10.25.0`, TypeScript `6.0.3`, and
Vitest `4.1.7`.

An unrelated checkout's long-running Vitest worker and this checkout's Nx daemon
were active. Tests, typechecks, lint, and the direct bundle ran sequentially
except for the repository hook's two-project typecheck. The supervised BFF
ratchet peaked near 6.3 GiB RSS with at least 6.5 GiB available. No full
workspace gate was started.

This refresh changes a backend test fixture and evidence only. It does not
change customer/admin/PWA/mobile/Unreal UI, so the frontend skill, Playwright,
mobile automation, screenshots, and Unreal verification are inapplicable.

## Publication identity

- **Original source commit on the current graph:**
  `a34012d3da4750c86d8f7c0346a52f64caf4defa`
- **Historical equivalent source identity (identical tree):**
  `f0441eda501f459fbb85bfb28bf761c919bbee63`
- **Historical evidence-pack commit on the current graph:**
  `acbc6a7846e38d0e190df7088f26018bdbff399c`
- **Historical equivalent evidence identity (identical tree):**
  `e9306497762fb729531d250610497d70e79157f9`
- **Historical ledger closure commit:**
  `0aaeeb369ff273e71f92c4c259dcc538657adc11`
- **Lifecycle cost-economics hardening:**
  `fce8641f0487b82bebd8052c7886efef8658bc2b`
- **Non-substitutable release-proof hardening:**
  `526d2b7d3abf6c1ab84345e9163e8f74488ca62a`
- **Durable reservation/receipt hardening:**
  `42dac7a43ac9362213e15f08d0843e991930f3c2`
- **Restart-safe publication hardening:**
  `c5aa83ecd11a5dfc7611258cd3777027f1543a13`
- **Scoped release-authority hardening:**
  `e3480d2eb708ebdb9374045908a68efc48ed819d`
- **Current test remediation and admitted verification tip:**
  `73d9e3b8aae38781713effad2203304614fca1b4`
- **Current evidence-refresh commit:** recorded by the task-scoped commit that
  contains this file.
