Module usage 

ADR-103 Amendment 2: dispatch-scoped executed-usage counters.

A closed seven-counter vocabulary of work a dispatch actually executed, collected by a dispatch-accounting context armed around each verb dispatch and surfaced (a) as a per-op usage object in the response envelope and (b) as resource.units payload enrichment on the per-dispatch audit row.

Propagation contract (Amendment 2 Part 2): the context is an Arc-shared accumulator carried in a task-local scope. Futures the dispatch awaits or join!s directly observe it automatically; a request-owned spawned child (a tokio::spawn whose JoinHandle is awaited before the response is produced) must capture the handle with current before the spawn and re-enter it with scope inside the child, because Tokio task-locals do not cross tokio::spawn. Detached background work receives no context and is attributed via phase-span events instead.

Reporting is best-effort and can never fail a verb: every increment path is a no-op when no context is armed, and a dispatch whose counters cannot be trusted ships no usage object at all — never a partial one.

Issued vs returned. Each counter’s doc below says which it is, and the distinction decides where its increment goes relative to the ? on the fallible call. An issued counter (embed_calls, fts_passes, vector_passes, db_round_trips) counts work handed to an engine or store, so it must be incremented whether or not the call resolved Ok — a request that ran real work and then failed reporting zero is the exact case a consumer of these numbers cannot afford. A returned counter (graph_hops, ann_jobs_consumed, event_rows) counts what came back, so a failed call legitimately contributes nothing. Increment an issued counter after the resource is resolved (so a lookup that never reached the engine counts nothing) and before the error propagates.

Structs

UsageContext

The Arc-shared dispatch-accounting context (Amendment 2 Part 2).

Enums

UsageUnit

One executed-work counter in the closed Amendment 2 vocabulary.

Functions

account_event_write

Publish event rows only after a write has a known committed outcome. An unknown writer-task outcome makes the entire shipping snapshot unavailable, even if earlier work already produced measured counters. The original result and error remain unchanged.

count

Add n to one counter of the currently armed context. No-op when no context is armed (background work, tests, un-instrumented entry points) — reporting can never fail or perturb the verb itself.

current

The currently armed context, if any. Request-owned spawned children capture this before tokio::spawn and re-enter it with scope inside the child; every other caller should prefer count.

scope

Run fut with ctx armed as the current dispatch-accounting context.