Rulvar API reference / @rulvar/rulvar / TerminalEnvelope
Interface: TerminalEnvelope
Defined in: packages/core/dist/index.d.ts
One run terminal, the same on every surface (RV1105).
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
acceptedArtifactRef? | number | The journal seq of the decision entry recording the acceptance of the artifact this terminal carries (RV2506); same mirror, absent unless the acceptance actually rendered. Read it with rulvar inspect to see WHICH validators accepted WHICH hash. | packages/core/dist/index.d.ts |
agentsSpawned | number | Agents admitted over the run's lifetime, resume seed included. | packages/core/dist/index.d.ts |
citationAuditMeta? | Record<string, unknown> | The citation audit meta, detached (RV4403): sampled, supported, partial, unsupported, auditedHash and the per-section split, mirrored beside the claim meta so the surface a consumer gates on carries the audit's own numbers on failed terminals too. Same posture as claimConsistencyMeta. | packages/core/dist/index.d.ts |
claimConsistencyMeta? | Record<string, unknown> | The claim consistency pass meta, detached (RV3304): judgedStage, judgedHash, the coverage grade and the findings count, so the surface a consumer gates on says WHAT was semantically verified, over WHICH document, and what the judge found, without reaching into the workflow value. Mutating this copy never touches the outcome the engine owns. | packages/core/dist/index.d.ts |
completion? | "partial" | "rejected" | "complete" | The semantic completion claim, when the workflow made one. | packages/core/dist/index.d.ts |
configFingerprint? | string | The host declared config identity the run was started under (RV3210), echoed here since RV3304 so a decision consumer binds the verdict above to the configuration that produced it without a second read of the run record. Absent when the run declared none. | packages/core/dist/index.d.ts |
costBasis | "locally-estimated" | Where the dollars above come from (RV1413): journaled usage priced at the CALLER'S pricing table (declared rates or adapter caps), never a provider statement. Always 'locally-estimated' today, declared as a literal so finance tooling never has to guess, mirroring InvoiceExport.pricingBasis; reconcile real bills through the invoice export and reconcileStatement, which carry their own provenance. | packages/core/dist/index.d.ts |
costByModel | Record<string, number> | The per-model split of totalUsd, keyed by canonical ModelRef. | packages/core/dist/index.d.ts |
deliverableAccepted? | boolean | Whether the artifact this terminal carries passed the declared finish contract (RV2506), mirrored onto the envelope since RV3304: the 2026-08-12 comparison run settled ok/complete over a retained contradiction, and neither the HTTP response nor the persisted rebuild could say whether anything ever judged the deliverable. Absent when no contract judged anything; absence means NOT RECORDED, never "accepted". | packages/core/dist/index.d.ts |
error? | WireError | The typed error, exactly the outcome's, when status is 'error'. | packages/core/dist/index.d.ts |
grossUsd | number | The gross figure with abandoned subtrees included (P1.3). | packages/core/dist/index.d.ts |
provenance? | "journal" | Where THIS copy of the envelope was assembled (RV1209). Absent, the historical byte contract, means the settlement chokepoint built it from the live outcome, so every field above is the run's own report. 'journal' means a process that never held the run rebuilt it from the journal that recorded the settle (a restart, a second replica, an offline reader): the money, the usage, the agent count and the settlement verdict are the SAME facts. completion is present exactly when the settle recorded the semantic lift beside its output digest (the persisted-terminal tail); a settle written before the lift rode it stays absent. error is ABSENT because the journal does not record the run's own wire error, and absence under this provenance means "not recorded", never "the workflow claimed nothing" or "the run did not fail". A consumer that needs the error reads it from the live outcome or the run:end event. | packages/core/dist/index.d.ts |
resultAvailable? | boolean | Whether this terminal carries a deliverable to read at all (RV2506); same mirror and posture. Distinct from deliverableAccepted: an unjudged artifact still EXISTS, and a run with no artifact still has a completion claim. | packages/core/dist/index.d.ts |
runId | string | The run this terminal speaks for. | packages/core/dist/index.d.ts |
semanticTerminalVerdict? | Record<string, unknown> | The one-word semantic verdict (RV4209), mirrored beside the meta it was folded from: 'clean' | 'findings' |
settled | boolean | Whether anything durable records this terminal (RV907). False only on the event stream: handle.result rejects typed instead of resolving an unsettled outcome. | packages/core/dist/index.d.ts |
settledReason? | "superseded" | Present only beside settled: false when a successor owns settlement (RV1009). | packages/core/dist/index.d.ts |
status | "ok" | "error" | "cancelled" | "exhausted" | "suspended" | The computed transport status of the run. | packages/core/dist/index.d.ts |
totalUsd | number | The NET settled fold: what the run recorded as spent. | packages/core/dist/index.d.ts |
usage | Usage | The run's usage aggregate, TTL attribution included. | packages/core/dist/index.d.ts |
usageApprox | boolean | True when any priced usage is approximate: totalUsd is a lower bound. | packages/core/dist/index.d.ts |
wireRequests? | number | Provider wire requests recorded by the per-dispatch ledger (RV1904), the same journal-derived figure CostReport.wireRequests carries: on ledger-covered runs it equals the invoice cardinality, so the terminal a consumer gates on and the invoice a finance pipeline folds finally share one denominator. Absent when the producing fold did not count wires (a pre-RV1904 live accumulation a host fed into buildCostReport). | packages/core/dist/index.d.ts |
workflow | string | The workflow name the run was started (or resumed) under. | packages/core/dist/index.d.ts |