Rulvar API reference / @rulvar/core / InvoiceExport
Interface: InvoiceExport
Defined in: packages/core/src/engine/invoice.ts:221
The machine-readable invoice: rows plus the ledger totals.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
abandonedUsd | number | The abandoned share: totalUsd - netUsd, equals CostReport.abandoned.usd. | packages/core/src/engine/invoice.ts:228 |
cardinality | InvoiceCardinality | Dispatch rows against the provider requests they represent (RV1210). | packages/core/src/engine/invoice.ts:252 |
executionScope? | { account?: string; legalDomain?: string; project?: string; providerAccount?: string; region?: string; sponsor?: string; tenant?: string; } | The run's bounded execution scope (RV4007), lifted from the genesis execution_scope decision: who this run executed for, as the host named it, on the money document a FinOps pipeline actually consumes. Absent on unscoped runs, so their exports keep their bytes. The RV4205 dimensions ride the same object, and executionScopeDigest beside it is the fixed-length join column (present exactly when the genesis decision recorded one). | packages/core/src/engine/invoice.ts:339 |
executionScope.account? | string | - | packages/core/src/engine/invoice.ts:341 |
executionScope.legalDomain? | string | - | packages/core/src/engine/invoice.ts:343 |
executionScope.project? | string | - | packages/core/src/engine/invoice.ts:342 |
executionScope.providerAccount? | string | - | packages/core/src/engine/invoice.ts:345 |
executionScope.region? | string | - | packages/core/src/engine/invoice.ts:344 |
executionScope.sponsor? | string | - | packages/core/src/engine/invoice.ts:346 |
executionScope.tenant? | string | - | packages/core/src/engine/invoice.ts:340 |
executionScopeDigest? | string | The canonical scope digest (RV4205), lifted from the same decision. | packages/core/src/engine/invoice.ts:349 |
netUsd | number | The net ledger (abandoned subtrees contribute zero): equals CostReport.totalUsd. | packages/core/src/engine/invoice.ts:226 |
openIntents? | { count: number; rows: { agentRef: number; attempt: number; ordinal: number; requestFingerprint?: string; scope: string; seq: number; servedBy: string; }[]; } | The unknown-outcome intent lane (RV4006): provider-intent decisions (the 'intent' receipt posture journals one before every dispatched wire attempt) that neither a receipt row nor a settled terminal's record set covers. Each row is a wire the provider may have billed while this process never learned the outcome: no dollars ride the lane, because inventing them would be the exact lie the posture exists to prevent; reconcile against the provider statement by fingerprint and coordinates instead. Absent when no intent is open, so every other invoice keeps its bytes. | packages/core/src/engine/invoice.ts:361 |
openIntents.count | number | - | packages/core/src/engine/invoice.ts:362 |
openIntents.rows | { agentRef: number; attempt: number; ordinal: number; requestFingerprint?: string; scope: string; seq: number; servedBy: string; }[] | - | packages/core/src/engine/invoice.ts:363 |
orphanedReceipts? | { rows: { agentRef: number; attempt: number; ordinal: number; outcome: string; responseId?: string; role: string; scope: string; servedBy: `${string}:${string}`; usage: Usage; usd?: number; }[]; usd: number; wireRequests: number; } | The orphaned receipt lane (RV3405): incremental provider-call rows of agents whose TERMINAL entry does not cover them. The window is real: the loop journals a receipt as each wire settles (RV2008), the turn checkpoint lands later, and a crash between the two resumes from a checkpoint that never saw the paid wire, so the settled terminal's record set forgets the payment while the receipt lane remembers it. Real money, priced and summed apart from the settled totals exactly like unsettled (run_settle stays the billing boundary); this lane is why a provider statement billing that wire is explainable to the cent instead of reading as a foreign row. Coverage is decided by response id when either side carries one, else by the full (ordinal, servedBy, attempt, outcome) coordinate plus byte equal usage: after a resume the redispatched wire REUSES the ordinal, and reading the replacement as the orphan would silently absorb the double payment the resume honestly made. Present only when such rows exist; a journal without a mid turn crash never carries it. | packages/core/src/engine/invoice.ts:314 |
orphanedReceipts.rows | { agentRef: number; attempt: number; ordinal: number; outcome: string; responseId?: string; role: string; scope: string; servedBy: `${string}:${string}`; usage: Usage; usd?: number; }[] | - | packages/core/src/engine/invoice.ts:317 |
orphanedReceipts.usd | number | - | packages/core/src/engine/invoice.ts:315 |
orphanedReceipts.wireRequests | number | - | packages/core/src/engine/invoice.ts:316 |
pricing? | InvoicePricingProvenance | The rates provenance (RV407); present when the caller declared it. | packages/core/src/engine/invoice.ts:268 |
pricingBasis | "per-call" | How per-row usd was computed: each call priced individually at the current table's rates. Always 'per-call' today; declared so finance tooling never has to guess the basis. | packages/core/src/engine/invoice.ts:234 |
reconciliationFailures | number | Rows whose reconciliation is not 'provider-id-present'. | packages/core/src/engine/invoice.ts:250 |
rows | InvoiceRow[] | - | packages/core/src/engine/invoice.ts:222 |
rowUsdNonAdditive | boolean | False exactly when every contributing entry's providerCalls fully cover its usage (RV504): the totals are then the per-call fold itself, each row's usd agrees with its allocatedUsd, and the flat usd sum reproduces totalUsd up to IEEE association of the last bits. True when any entry folded on the aggregate basis (no records, or records that do not cover its usage): a nonlinear price table then prices an aggregate differently from the sum of its parts, so sum allocatedUsd instead; it exists precisely so a column sums to the total exactly in every case. | packages/core/src/engine/invoice.ts:246 |
totalUsd | number | Every priced terminal slice, abandonment included: equals CostReport.grossUsd. | packages/core/src/engine/invoice.ts:224 |
unallocatedUsd? | number | USD of allocation pools that had a target and no row to carry it (RV605). The dust pass refuses to move such dollars onto another model's rows just to make the column sum, so on the (pathological) journals where this happens the flat allocatedUsd sum reproduces totalUsd minus this amount. Absent when zero, which is every well-formed journal: the per-slice remainder rows guarantee a row wherever a slice has usage. | packages/core/src/engine/invoice.ts:262 |
unpriced | { model: string; usage: Usage; }[] | Usage on models absent from pricing, net and abandoned alike; never a silent zero. | packages/core/src/engine/invoice.ts:248 |
unsettled? | { rows: { agentRef: number; attempt: number; ordinal: number; outcome: string; responseId?: string; role: string; scope: string; servedBy: `${string}:${string}`; usage: Usage; usd?: number; }[]; usd: number; wireRequests: number; } | The unsettled lane (RV2008): dispatches whose agent is still RUNNING at the journal's edge, recovered from the incremental provider-call rows the loop journals as each wire call settles. Deliberately OUTSIDE the settled totals above: run_settle stays the billing boundary, and this section prices what the crash window preserved anyway, the ~$0.99 of parity root dispatches that used to live only in process memory. Present only when such rows exist; a journal whose roster is closed never carries it. | packages/core/src/engine/invoice.ts:279 |
unsettled.rows | { agentRef: number; attempt: number; ordinal: number; outcome: string; responseId?: string; role: string; scope: string; servedBy: `${string}:${string}`; usage: Usage; usd?: number; }[] | - | packages/core/src/engine/invoice.ts:282 |
unsettled.usd | number | - | packages/core/src/engine/invoice.ts:280 |
unsettled.wireRequests | number | - | packages/core/src/engine/invoice.ts:281 |
usageApprox? | boolean | Present and true when any contributing entry carried approximate usage. | packages/core/src/engine/invoice.ts:266 |
usageUnknownRows? | number | Rows carrying usageUnknown; present when at least one does. | packages/core/src/engine/invoice.ts:264 |