@rulvar/core 1.66.0 → 1.67.0

package/dist/index.d.ts

@@ -8416,8 +8416,17 @@ declare class FileTranscriptStore implements TranscriptStore {
 }
 //#endregion
 //#region src/engine/invoice.d.ts
-/** How a row lines up against a provider invoice. */
-type InvoiceReconciliation = "matched" | "missing-provider-id" | "unconfirmed" | "unattributed";
+/**
+* How far a row's identity goes toward provider-side reconciliation.
+* `provider-id-present` asserts exactly what it names: the adapter
+* surfaced the provider's response id for this call, the join key a
+* host needs to line the row up against a provider statement. It does
+* NOT assert any statement, amount, or usage match: the library never
+* sees provider billing data, so those deeper reconciliation tiers are
+* host-side joins keyed on `responseId`, not verdicts this export can
+* make.
+*/
+type InvoiceReconciliation = "provider-id-present" | "missing-provider-id" | "unconfirmed" | "unattributed";
 /** One billable provider call (or an unattributed usage remainder). */
 interface InvoiceRow {
   /** The terminal journal entry the row folds from. */
@@ -8436,6 +8445,15 @@ interface InvoiceRow {
   usageApprox?: boolean;
   /** This row priced at its own model's rate; absent when no price row covers it. */
   usd?: number;
+  /**
+  * The additive FinOps column: this row's share of `totalUsd`, always
+  * present (zero for rows on unpriced models). Shares are computed
+  * within the row's own (entry, serving model) slice of the same
+  * gross fold the totals run, proportional to per-row `usd`, and one
+  * row absorbs the IEEE rounding dust, so summing `allocatedUsd` over
+  * `rows` reproduces `totalUsd` exactly where summing `usd` does not.
+  */
+  allocatedUsd: number;
   /** The row lies under an abandoned subtree: in grossUsd, not in netUsd. */
   abandoned?: true;
   reconciliation: InvoiceReconciliation;
@@ -8449,12 +8467,25 @@ interface InvoiceExport {
   netUsd: number;
   /** The abandoned share: totalUsd - netUsd, equals CostReport.abandoned.usd. */
   abandonedUsd: number;
+  /**
+  * 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.
+  */
+  pricingBasis: "per-call";
+  /**
+  * Always true: per-call `usd` values need not sum to `totalUsd`,
+  * because a nonlinear price table prices an aggregate differently
+  * from the sum of its parts. Sum `allocatedUsd` instead; it exists
+  * precisely so a column sums to the total.
+  */
+  rowUsdNonAdditive: true;
   /** Usage on models absent from pricing, net and abandoned alike; never a silent zero. */
   unpriced: Array<{
     model: string;
     usage: Usage;
   }>;
-  /** Rows whose reconciliation is not 'matched'. */
+  /** Rows whose reconciliation is not 'provider-id-present'. */
   reconciliationFailures: number;
   /** Present and true when any contributing entry carried approximate usage. */
   usageApprox?: boolean;

package/dist/index.js

@@ -8233,9 +8233,12 @@ function costReportFromJournal(entries, priceUsd) {
 * against the provider's invoice. The totals are the SAME slice fold
 * `costReportFromJournal` runs, so `totalUsd` here equals
 * `CostReport.grossUsd` (and `netUsd` equals `CostReport.totalUsd`)
-* exactly, never approximately; per-row `usd` prices each call
-* individually and is informational, since a nonlinear price table
-* (long-context tiers) prices a split differently from its sum.
+* exactly, never approximately. The export is self-describing about
+* its pricing: `pricingBasis` says per-row `usd` prices each call
+* individually, `rowUsdNonAdditive` says those values need not sum to
+* `totalUsd` (a nonlinear price table, long-context tiers, prices a
+* split differently from its sum), and per-row `allocatedUsd` is the
+* additive column whose flat sum reproduces `totalUsd` exactly.
 *
 * Coverage is loss-free by construction: an entry whose records do not
 * cover its usage total (a resume restored from a checkpoint written
@@ -8274,6 +8277,64 @@ function usageRemainder(total, records) {
 	if (reasoning > 0) remainder.reasoningTokens = reasoning;
 	return USAGE_FIELDS.some((field) => remainder[field] > 0) || (remainder.reasoningTokens ?? 0) > 0 ? remainder : void 0;
 }
+/** One allocation pool per (entry, serving model) slice of the gross fold. */
+function allocationKey(entrySeq, servedBy) {
+	return `${String(entrySeq)} ${servedBy}`;
+}
+/** The token-count fallback weight when every row of a pool priced to zero. */
+function totalTokens(usage) {
+	return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens + (usage.reasoningTokens ?? 0);
+}
+/**
+* The additive allocation pass: distributes each (entry, model) slice
+* total of the SAME gross fold the invoice totals run across that
+* slice's rows, proportional to per-row `usd` (token counts when every
+* row priced to zero, equal shares when even those are zero), then
+* lets the largest row absorb the IEEE rounding dust of the fold's own
+* association so the flat sum over `rows` reproduces `totalUsd`
+* exactly. Rows on unpriced models keep zero: their spend is in
+* `unpriced`, not in `totalUsd`.
+*/
+function allocateRows(rows, entries, priceUsd, totalUsd) {
+	if (rows.length === 0) return;
+	const targets = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.status === "running" || entry.usage === void 0) continue;
+		for (const slice of priceEntryUsage(entry, priceUsd).priced) {
+			const key = allocationKey(entry.seq, slice.servedBy);
+			targets.set(key, (targets.get(key) ?? 0) + slice.usd);
+		}
+	}
+	const pools = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = allocationKey(row.entrySeq, row.servedBy);
+		const pool = pools.get(key);
+		if (pool === void 0) pools.set(key, [row]);
+		else pool.push(row);
+	}
+	for (const [key, members] of pools) {
+		const target = targets.get(key) ?? 0;
+		if (target === 0) continue;
+		let weights = members.map((row) => row.usd ?? 0);
+		let sum = weights.reduce((acc, weight) => acc + weight, 0);
+		if (sum === 0) {
+			weights = members.map((row) => totalTokens(row.usage));
+			sum = weights.reduce((acc, weight) => acc + weight, 0);
+		}
+		members.forEach((row, index) => {
+			const weight = weights[index] ?? 0;
+			row.allocatedUsd = sum === 0 ? target / members.length : target * (weight / sum);
+		});
+	}
+	let absorber;
+	for (const row of rows) if (absorber === void 0 || row.allocatedUsd > absorber.allocatedUsd) absorber = row;
+	if (absorber === void 0) return;
+	for (let pass = 0; pass < 8; pass += 1) {
+		const flat = rows.reduce((acc, row) => acc + row.allocatedUsd, 0);
+		if (flat === totalUsd) break;
+		absorber.allocatedUsd += totalUsd - flat;
+	}
+}
 /** A single row priced at its own model's rate; broken rates fold as unpriced. */
 function rowUsd(priceUsd, servedBy, usage) {
 	const usd = priceUsd(servedBy, usage);
@@ -8311,8 +8372,9 @@ function invoiceFromJournal(entries, priceUsd) {
 				usage: record.usage,
 				...record.usageApprox === true ? { usageApprox: true } : {},
 				...usd === void 0 ? {} : { usd },
+				allocatedUsd: 0,
 				...mark,
-				reconciliation: record.responseId !== void 0 ? "matched" : record.outcome === "ok" ? "missing-provider-id" : "unconfirmed"
+				reconciliation: record.responseId !== void 0 ? "provider-id-present" : record.outcome === "ok" ? "missing-provider-id" : "unconfirmed"
 			});
 		}
 		if (records.length === 0) {
@@ -8327,6 +8389,7 @@ function invoiceFromJournal(entries, priceUsd) {
 					usage: slice.usage,
 					...entry.usageApprox === true ? { usageApprox: true } : {},
 					...usd === void 0 ? {} : { usd },
+					allocatedUsd: 0,
 					...mark,
 					reconciliation: "unattributed"
 				});
@@ -8344,19 +8407,23 @@ function invoiceFromJournal(entries, priceUsd) {
 				usage: remainder,
 				...entry.usageApprox === true ? { usageApprox: true } : {},
 				...usd === void 0 ? {} : { usd },
+				allocatedUsd: 0,
 				...mark,
 				reconciliation: "unattributed"
 			});
 		}
 	}
+	allocateRows(rows, entries, priceUsd, report.grossUsd);
 	const usageApprox = report.usageApprox === true || report.abandoned.usageApprox === true;
 	return {
 		rows,
 		totalUsd: report.grossUsd,
 		netUsd: report.totalUsd,
 		abandonedUsd: report.abandoned.usd,
+		pricingBasis: "per-call",
+		rowUsdNonAdditive: true,
 		unpriced: [...report.unpriced, ...report.abandoned.unpriced],
-		reconciliationFailures: rows.filter((row) => row.reconciliation !== "matched").length,
+		reconciliationFailures: rows.filter((row) => row.reconciliation !== "provider-id-present").length,
 		...usageApprox ? { usageApprox: true } : {}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",