@rulvar/core 1.102.0 → 1.103.0

package/dist/index.d.ts

@@ -828,14 +828,18 @@ interface EntryBillingFold {
 /**
 * The billing fold over one terminal entry (RV504), shared by the
 * CostReport and invoice folds so the total, every breakdown, and the
-* per-row prices can never disagree. When the entry's per-dispatch
-* `providerCalls` exactly cover its usage, each call is priced
+* per-row prices can never disagree. Coverage is decided per MODEL with
+* the symmetric key (RV604): for every model whose per-dispatch
+* `providerCalls` sum to exactly its usage, each call is priced
 * individually, so a nonlinear long-context tier fires per REQUEST,
 * which is the pricing contract's stated semantics; an aggregate that
 * crossed a threshold no single request crossed no longer re-prices
-* the whole entry (the ninth-experiment 52% overreport). An entry with
-* no records, or records that do not cover its usage, folds exactly as
-* before: the per-model aggregate slices of {@link priceEntryUsage}.
+* that model (the ninth-experiment 52% overreport, and the round-52
+* multi-role default). A model with no records, or records that do not
+* cover its usage, folds exactly as before: the per-model aggregate
+* slices of {@link priceEntryUsage}. `fullyAttributed` is true only
+* when every slice model is covered and no record names a model absent
+* from the slices.
 */
 declare function priceEntryBilling(entry: JournalEntry, priceUsd: (servedBy: ModelRef, usage: Usage, seq?: number) => number | undefined): EntryBillingFold;
 /**
@@ -9563,6 +9567,16 @@ interface InvoiceExport {
   }>;
   /** Rows whose reconciliation is not 'provider-id-present'. */
   reconciliationFailures: 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.
+  */
+  unallocatedUsd?: number;
   /** Rows carrying `usageUnknown`; present when at least one does. */
   usageUnknownRows?: number;
   /** Present and true when any contributing entry carried approximate usage. */

package/dist/index.js

@@ -2401,12 +2401,11 @@ const BILLING_FIELDS = [
 	"cacheReadTokens",
 	"cacheWriteTokens"
 ];
-/** Exact per-model coverage: records sum to every slice, counter for counter. */
-function callsCoverSlices(slices, records) {
-	if (slices.length === 0 || records.length === 0) return false;
+/** Per-model billing-counter sums of either side of the coverage test. */
+function sumUsageByModel(items) {
 	const sums = /* @__PURE__ */ new Map();
-	for (const record of records) {
-		let sum = sums.get(record.servedBy);
+	for (const item of items) {
+		let sum = sums.get(item.servedBy);
 		if (sum === void 0) {
 			sum = {
 				fields: {
@@ -2417,54 +2416,61 @@ function callsCoverSlices(slices, records) {
 				},
 				reasoning: 0
 			};
-			sums.set(record.servedBy, sum);
+			sums.set(item.servedBy, sum);
 		}
-		for (const field of BILLING_FIELDS) sum.fields[field] = (sum.fields[field] ?? 0) + record.usage[field];
-		sum.reasoning += record.usage.reasoningTokens ?? 0;
+		for (const field of BILLING_FIELDS) sum.fields[field] = (sum.fields[field] ?? 0) + item.usage[field];
+		sum.reasoning += item.usage.reasoningTokens ?? 0;
 	}
-	for (const slice of slices) {
-		const sum = sums.get(slice.servedBy);
-		if (sum === void 0) return false;
-		for (const field of BILLING_FIELDS) if (sum.fields[field] !== slice.usage[field]) return false;
-		if (sum.reasoning !== (slice.usage.reasoningTokens ?? 0)) return false;
+	return sums;
+}
+/**
+* The models whose records exactly cover their usage, counter for
+* counter. BOTH sides aggregate by `servedBy` (RV604): the usage slices
+* split one model's spend by role (a schema fires a same-model extract
+* by default, so several slices of one model are the ordinary shape),
+* and comparing a per-role slice against the per-model record sum
+* refused coverage on exactly that default, re-tiering aggregates no
+* single request crossed. The symmetric key compares model sum against
+* model sum, so coverage is per model: a covered model prices per call
+* while an uncovered one honestly keeps the aggregate basis.
+*/
+function coveredModels(slices, records) {
+	const covered = /* @__PURE__ */ new Set();
+	if (slices.length === 0 || records.length === 0) return covered;
+	const recordSums = sumUsageByModel(records);
+	const sliceSums = sumUsageByModel(slices);
+	for (const [model, sliceSum] of sliceSums) {
+		const recordSum = recordSums.get(model);
+		if (recordSum === void 0) continue;
+		if (BILLING_FIELDS.every((field) => recordSum.fields[field] === sliceSum.fields[field]) && recordSum.reasoning === sliceSum.reasoning) covered.add(model);
 	}
-	for (const model of sums.keys()) if (!slices.some((slice) => slice.servedBy === model)) return false;
-	return true;
+	return covered;
 }
 /**
 * The billing fold over one terminal entry (RV504), shared by the
 * CostReport and invoice folds so the total, every breakdown, and the
-* per-row prices can never disagree. When the entry's per-dispatch
-* `providerCalls` exactly cover its usage, each call is priced
+* per-row prices can never disagree. Coverage is decided per MODEL with
+* the symmetric key (RV604): for every model whose per-dispatch
+* `providerCalls` sum to exactly its usage, each call is priced
 * individually, so a nonlinear long-context tier fires per REQUEST,
 * which is the pricing contract's stated semantics; an aggregate that
 * crossed a threshold no single request crossed no longer re-prices
-* the whole entry (the ninth-experiment 52% overreport). An entry with
-* no records, or records that do not cover its usage, folds exactly as
-* before: the per-model aggregate slices of {@link priceEntryUsage}.
+* that model (the ninth-experiment 52% overreport, and the round-52
+* multi-role default). A model with no records, or records that do not
+* cover its usage, folds exactly as before: the per-model aggregate
+* slices of {@link priceEntryUsage}. `fullyAttributed` is true only
+* when every slice model is covered and no record names a model absent
+* from the slices.
 */
 function priceEntryBilling(entry, priceUsd) {
 	const slices = entryUsageSlices(entry);
 	const records = entry.providerCalls ?? [];
-	if (!callsCoverSlices(slices, records)) {
-		const aggregate = priceEntryUsage(entry, priceUsd);
-		return {
-			units: aggregate.priced.map((slice) => ({
-				source: "slice",
-				servedBy: slice.servedBy,
-				usage: slice.usage,
-				...slice.role === void 0 ? {} : { role: slice.role },
-				usd: slice.usd
-			})),
-			usd: aggregate.usd,
-			unpriced: aggregate.unpriced,
-			fullyAttributed: false
-		};
-	}
+	const covered = coveredModels(slices, records);
 	const units = [];
 	const unpricedByModel = /* @__PURE__ */ new Map();
 	let usd = 0;
 	for (const record of records) {
+		if (!covered.has(record.servedBy)) continue;
 		const price = priceUsd(record.servedBy, record.usage, entry.seq);
 		if (price === void 0 || !Number.isFinite(price) || price < 0) {
 			const sum = unpricedByModel.get(record.servedBy) ?? {
@@ -2489,6 +2495,32 @@ function priceEntryBilling(entry, priceUsd) {
 			usd: price
 		});
 	}
+	for (const slice of slices) {
+		if (covered.has(slice.servedBy)) continue;
+		const price = priceUsd(slice.servedBy, slice.usage, entry.seq);
+		if (price === void 0 || !Number.isFinite(price) || price < 0) {
+			const sum = unpricedByModel.get(slice.servedBy) ?? {
+				inputTokens: 0,
+				outputTokens: 0,
+				cacheReadTokens: 0,
+				cacheWriteTokens: 0
+			};
+			for (const field of BILLING_FIELDS) sum[field] += slice.usage[field];
+			const reasoning = (sum.reasoningTokens ?? 0) + (slice.usage.reasoningTokens ?? 0);
+			if (reasoning > 0) sum.reasoningTokens = reasoning;
+			unpricedByModel.set(slice.servedBy, sum);
+			continue;
+		}
+		usd += price;
+		units.push({
+			source: "slice",
+			servedBy: slice.servedBy,
+			usage: slice.usage,
+			...slice.role === void 0 ? {} : { role: slice.role },
+			usd: price
+		});
+	}
+	const fullyAttributed = slices.length > 0 && slices.every((slice) => covered.has(slice.servedBy)) && records.every((record) => slices.some((slice) => slice.servedBy === record.servedBy));
 	return {
 		units,
 		usd,
@@ -2496,7 +2528,7 @@ function priceEntryBilling(entry, priceUsd) {
 			servedBy,
 			usage
 		})),
-		fullyAttributed: true
+		fullyAttributed
 	};
 }
 /**
@@ -8404,16 +8436,29 @@ const USAGE_FIELDS = [
 	"cacheReadTokens",
 	"cacheWriteTokens"
 ];
-/** entry.usage minus the records' sum, clamped at zero per field. */
-function usageRemainder(total, records) {
+/**
+* One usage slice minus ITS OWN records' sum, clamped at zero per field
+* (RV605). A record belongs to a slice when it names the same serving
+* model, and the same role when the slice carries one; a slice written
+* without a role (the legacy whole-entry fallback) absorbs every record
+* of its model, which is exactly the pre-RV605 arithmetic for
+* single-model entries. Computing the remainder per slice instead of
+* per entry is what keeps an orphaned model's spend on a row of that
+* model: the whole-entry remainder was published under `entry.servedBy`,
+* so a slice with no records left its allocation pool rowless and the
+* dust pass moved its dollars onto another model's row.
+*/
+function sliceRemainder(slice, records) {
 	const remainder = {
-		inputTokens: total.inputTokens,
-		outputTokens: total.outputTokens,
-		cacheReadTokens: total.cacheReadTokens,
-		cacheWriteTokens: total.cacheWriteTokens
+		inputTokens: slice.usage.inputTokens,
+		outputTokens: slice.usage.outputTokens,
+		cacheReadTokens: slice.usage.cacheReadTokens,
+		cacheWriteTokens: slice.usage.cacheWriteTokens
 	};
-	let reasoning = total.reasoningTokens ?? 0;
+	let reasoning = slice.usage.reasoningTokens ?? 0;
 	for (const record of records) {
+		if (record.servedBy !== slice.servedBy) continue;
+		if (slice.role !== void 0 && record.role !== slice.role) continue;
 		for (const field of USAGE_FIELDS) remainder[field] = Math.max(0, remainder[field] - record.usage[field]);
 		reasoning = Math.max(0, reasoning - (record.usage.reasoningTokens ?? 0));
 	}
@@ -8437,9 +8482,16 @@ function totalTokens(usage) {
 * association so the flat sum over `rows` reproduces `totalUsd`
 * exactly. Rows on unpriced models keep zero: their spend is in
 * `unpriced`, not in `totalUsd`.
+*
+* A pool with a target and NO rows refuses the transfer (RV605): its
+* dollars are excluded from the dust reconciliation and returned as the
+* unallocated share, because dumping them on the globally largest row
+* moved one model's spend onto another model's line just to make the
+* column sum. The returned amount is zero on every well-formed journal
+* (the per-slice remainder rows above guarantee a row wherever a slice
+* has usage), so the flat sum still reproduces `totalUsd` exactly there.
 */
 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;
@@ -8455,6 +8507,9 @@ function allocateRows(rows, entries, priceUsd, totalUsd) {
 		if (pool === void 0) pools.set(key, [row]);
 		else pool.push(row);
 	}
+	let unallocated = 0;
+	for (const [key, target] of targets) if (target !== 0 && !pools.has(key)) unallocated += target;
+	if (rows.length === 0) return unallocated;
 	for (const [key, members] of pools) {
 		const target = targets.get(key) ?? 0;
 		if (target === 0) continue;
@@ -8471,12 +8526,14 @@ function allocateRows(rows, entries, priceUsd, totalUsd) {
 	}
 	let absorber;
 	for (const row of rows) if (absorber === void 0 || row.allocatedUsd > absorber.allocatedUsd) absorber = row;
-	if (absorber === void 0) return;
+	if (absorber === void 0) return unallocated;
+	const goal = totalUsd - unallocated;
 	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;
+		if (flat === goal) break;
+		absorber.allocatedUsd += goal - flat;
 	}
+	return unallocated;
 }
 /** A single row priced at its own model's rate; broken rates fold as unpriced. */
 function rowUsd(priceUsd, servedBy, usage, seq) {
@@ -8548,13 +8605,16 @@ function invoiceFromJournal(entries, priceUsd, options) {
 			});
 			continue;
 		}
-		const remainder = usageRemainder(entry.usage, records);
-		if (remainder !== void 0 && entry.servedBy !== void 0) {
-			const usd = rowUsd(priceUsd, entry.servedBy, remainder, entry.seq);
+		let remainderOrdinal = records.length + 1;
+		for (const slice of entryUsageSlices(entry)) {
+			const remainder = sliceRemainder(slice, records);
+			if (remainder === void 0) continue;
+			const usd = rowUsd(priceUsd, slice.servedBy, remainder, entry.seq);
 			rows.push({
 				...base,
-				ordinal: records.length + 1,
-				servedBy: entry.servedBy,
+				ordinal: remainderOrdinal,
+				servedBy: slice.servedBy,
+				...slice.role === void 0 ? {} : { role: slice.role },
 				outcome: "unattributed",
 				usage: remainder,
 				...entry.usageApprox === true ? { usageApprox: true } : {},
@@ -8563,9 +8623,10 @@ function invoiceFromJournal(entries, priceUsd, options) {
 				...mark,
 				reconciliation: "unattributed"
 			});
+			remainderOrdinal += 1;
 		}
 	}
-	allocateRows(rows, entries, priceUsd, report.grossUsd);
+	const unallocatedUsd = allocateRows(rows, entries, priceUsd, report.grossUsd);
 	const usageApprox = report.usageApprox === true || report.abandoned.usageApprox === true;
 	return {
 		rows,
@@ -8574,6 +8635,7 @@ function invoiceFromJournal(entries, priceUsd, options) {
 		abandonedUsd: report.abandoned.usd,
 		pricingBasis: "per-call",
 		rowUsdNonAdditive: !everyEntryFullyAttributed,
+		...unallocatedUsd === 0 ? {} : { unallocatedUsd },
 		unpriced: [...report.unpriced, ...report.abandoned.unpriced],
 		reconciliationFailures: rows.filter((row) => row.reconciliation !== "provider-id-present").length,
 		...(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.102.0",
+  "version": "1.103.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",