@tangle-network/agent-app 0.45.31 → 0.45.32

package/dist/{chunk-NEJ7OMQS.js → chunk-5LC2VXH5.js}

@@ -6,6 +6,34 @@ var SPEND_CHECKS = [
   "negative-balance"
 ];
 
+// src/spend/ownership.ts
+function ownedByBillingKeys(keyIds) {
+  const owned = new Set(keyIds.map((id) => id.trim()).filter(Boolean));
+  if (owned.size === 0) {
+    throw new Error(
+      "ownedByBillingKeys needs at least one key id: a rule that owns no key classifies every settlement as another product's and reports a clean bill for an unchecked account."
+    );
+  }
+  const label = `billing key ${[...owned].join(", ")}`;
+  return {
+    label,
+    decide({ row }) {
+      const keyId = row.keyId?.trim();
+      if (!keyId) return "undecidable";
+      return owned.has(keyId) ? "mine" : "foreign";
+    }
+  };
+}
+function decideBoxOwnership(rule, sandboxId, rows) {
+  let verdict = "foreign";
+  for (const row of rows) {
+    const rowVerdict = rule.decide({ row, sandboxId });
+    if (rowVerdict === "mine") return "mine";
+    if (rowVerdict === "undecidable") verdict = "undecidable";
+  }
+  return verdict;
+}
+
 // src/spend/ceiling.ts
 var DEFAULT_CEILING_TOLERANCE_MS = 9e5;
 function computeExpectedCeiling(record, options) {
@@ -116,6 +144,25 @@ function median(values) {
   if (sorted.length % 2 === 1) return sorted[mid];
   return (sorted[mid - 1] + sorted[mid]) / 2;
 }
+function unknownBoxAttribution(ownership, verdict) {
+  if (!ownership) {
+    return " No ownership rule was declared for this pass, so a sibling product's box on the same wallet reads exactly like a charge that is not ours \u2014 this finding could be either.";
+  }
+  if (verdict === "undecidable") {
+    return ` The ownership rule (${ownership.label}) could not decide it: the settlement carries no billing-key attribution to exclude it by, so it is reported rather than dropped.`;
+  }
+  return ` The ownership rule (${ownership.label}) attributes it to THIS product.`;
+}
+function unknownBoxRemedy(ownership, verdict, sandboxId) {
+  const lookup = `Look up ${sandboxId} on the platform before disputing.`;
+  if (!ownership) {
+    return `Declare \`ownership\` (see \`ownedByBillingKeys\`) so a sibling product's box stops reading as a discrepancy \u2014 without it this check cannot tell one from a charge that is not ours. Until then, treat this as one of three things: a sibling product on the same wallet, a box provisioned outside the recorded seam, or a box that is not ours at all. ${lookup}`;
+  }
+  if (verdict === "undecidable") {
+    return `An unattributable charge on a shared wallet is exactly what a phantom charge looks like, so it is reported by design rather than excluded. Confirm the row genuinely predates key attribution before dismissing it. ${lookup}`;
+  }
+  return `This box is inside this product's own billing attribution and the product never recorded it, so it is either a provision that bypassed the recorded seam or a charge that is not ours. ${lookup}`;
+}
 function emptyFinding(check) {
   return {
     check,
@@ -143,9 +190,15 @@ async function reconcileSpend(options) {
   const skip = new Set(options.skip ?? []);
   const checksRun = SPEND_CHECKS.filter((check) => !skip.has(check));
   const runs = (check) => !skip.has(check);
+  const ownership = options.ownership ?? null;
   const findings = [];
   let settledNanoUsd = 0;
   let creditedNanoUsd = 0;
+  let ownedBoxes = 0;
+  let ownedNanoUsd = 0;
+  let undecidableBoxes = 0;
+  let foreignNanoUsd = 0;
+  const foreignSandboxIds = [];
   const byBox = /* @__PURE__ */ new Map();
   for (const row of options.rows) {
     if (row.amountNanoUsd < 0) settledNanoUsd += -row.amountNanoUsd;
@@ -167,6 +220,15 @@ async function reconcileSpend(options) {
     const record = await options.store.load(sandboxId);
     const referenceIds = rows.map((row) => row.referenceId ?? row.id);
     const charged = rows.reduce((sum, row) => sum + chargeNanoUsd(row), 0);
+    const verdict = record ? "mine" : ownership ? decideBoxOwnership(ownership, sandboxId, rows) : "mine";
+    if (verdict === "foreign") {
+      foreignSandboxIds.push(sandboxId);
+      foreignNanoUsd += charged;
+      continue;
+    }
+    ownedBoxes += 1;
+    ownedNanoUsd += charged;
+    if (verdict === "undecidable") undecidableBoxes += 1;
     if (!record) {
       if (runs("unknown-box")) {
         findings.push({
@@ -175,8 +237,8 @@ async function reconcileSpend(options) {
           workspaceId,
           referenceIds,
           settledNanoUsd: charged,
-          message: `${usd(charged)} settled across ${rows.length} row(s) against sandbox ${sandboxId}, which this product has no record of ever asking for.`,
-          remedy: `Either the fetch is not scoped to this product's own boxes (fix the scope \u2014 a shared billing key returns every sibling product's settlements), or a box was provisioned outside the recorded seam, or the platform billed a box that is not ours. Identify which by looking up ${sandboxId} on the platform before disputing.`
+          message: `${usd(charged)} settled across ${rows.length} row(s) against sandbox ${sandboxId}, which this product has no record of ever asking for.` + unknownBoxAttribution(ownership, verdict),
+          remedy: unknownBoxRemedy(ownership, verdict, sandboxId)
         });
       }
       continue;
@@ -223,6 +285,9 @@ async function reconcileSpend(options) {
     for (const row of options.rows) {
       const charge = chargeNanoUsd(row);
       if (charge === 0) continue;
+      if (ownership && ownership.decide({ row, sandboxId: settlementSandboxId(row) }) === "foreign") {
+        continue;
+      }
       const bucketStart = Math.floor(row.createdAt / cfg.windowMs) * cfg.windowMs;
       const bucket = buckets.get(bucketStart);
       if (bucket) {
@@ -252,7 +317,7 @@ async function reconcileSpend(options) {
         trailingMedianNanoUsd: trailingMedian,
         velocityRatio: ratio,
         windowStartAt,
-        message: `${usd(bucket.nano)} settled in the window starting ${new Date(windowStartAt).toISOString()} across ${bucket.references.length} row(s), against a trailing median of ${usd(trailingMedian)} over ${trailing.length} prior window(s) \u2014 ${Number.isFinite(ratio) ? `${ratio.toFixed(1)}x` : "no prior spend to compare against"}, over the ${cfg.multiple}x threshold.`,
+        message: `${usd(bucket.nano)} settled in the window starting ${new Date(windowStartAt).toISOString()} across ${bucket.references.length} row(s), against a trailing median of ${usd(trailingMedian)} over ${trailing.length} prior window(s) \u2014 ${Number.isFinite(ratio) ? `${ratio.toFixed(1)}x` : "no prior spend to compare against"}, over the ${cfg.multiple}x threshold.` + (ownership ? ` Counted over this product's own rows only (${ownership.label}); the wallet total for the window is higher when a sibling product settled into it.` : " Counted over every row on the wallet, which on a shared account includes any sibling product's spend."),
         remedy: "A burst of this shape is what a settlement defect looks like from the consumer side: long-dormant intervals cashed out at once. Check whether these rows carry interval starts far older than the settlement instant before treating it as real usage."
       });
     }
@@ -271,6 +336,16 @@ async function reconcileSpend(options) {
       });
     }
   }
+  const ownershipSummary = {
+    declared: ownership !== null,
+    label: ownership?.label ?? null,
+    ownedBoxes,
+    ownedNanoUsd,
+    undecidableBoxes,
+    foreignBoxes: foreignSandboxIds.length,
+    foreignNanoUsd,
+    foreignSandboxIds
+  };
   return {
     ok: findings.length === 0,
     findings,
@@ -279,6 +354,7 @@ async function reconcileSpend(options) {
     boxesExamined: byBox.size,
     settledNanoUsd,
     creditedNanoUsd,
+    ownership: ownershipSummary,
     asOf
   };
 }
@@ -294,6 +370,7 @@ function formatSpendReport(report) {
     `spend reconciliation \u2014 ${report.rowsExamined} row(s), ${report.boxesExamined} box(es), ${usd2(report.settledNanoUsd)} charged, ${usd2(report.creditedNanoUsd)} credited, as of ${new Date(report.asOf).toISOString()}`
   );
   lines.push(`checks: ${report.checksRun.join(", ") || "(none)"}`);
+  for (const line of ownershipLines(report.ownership)) lines.push(line);
   if (report.ok) {
     lines.push("");
     lines.push("OK \u2014 no discrepancy between the product's expectations and the settled ledger.");
@@ -312,6 +389,25 @@ function formatSpendReport(report) {
   }
   return lines.join("\n");
 }
+function ownershipLines(ownership) {
+  if (!ownership.declared) {
+    return [
+      `scope: NOT DECLARED \u2014 all ${ownership.ownedBoxes} settled box(es) claimed as this product's. A sibling product's box on this wallet is reported as unknown-box; pass \`ownership\` (see \`ownedByBillingKeys\`) to tell the two apart.`
+    ];
+  }
+  const lines = [
+    `scope: ${ownership.label} \u2014 ${ownership.ownedBoxes} box(es) ${usd2(ownership.ownedNanoUsd)} owned, ${ownership.foreignBoxes} box(es) ${usd2(ownership.foreignNanoUsd)} excluded as another product's`
+  ];
+  if (ownership.undecidableBoxes > 0) {
+    lines.push(
+      `       ${ownership.undecidableBoxes} of the owned box(es) carried no billing-key attribution and were claimed fail-closed`
+    );
+  }
+  if (ownership.foreignSandboxIds.length > 0) {
+    lines.push(`       excluded: ${ownership.foreignSandboxIds.join(", ")}`);
+  }
+  return lines;
+}
 function measuredFields(finding) {
   const ms = (value) => value === null ? "\u2014" : `${(value / 36e5).toFixed(2)}h`;
   return [
@@ -337,6 +433,8 @@ function spendReportToJson(report) {
 
 export {
   SPEND_CHECKS,
+  ownedByBillingKeys,
+  decideBoxOwnership,
   DEFAULT_CEILING_TOLERANCE_MS,
   computeExpectedCeiling,
   parseSettlementReference,
@@ -348,4 +446,4 @@ export {
   formatSpendReport,
   spendReportToJson
 };
-//# sourceMappingURL=chunk-NEJ7OMQS.js.map
+//# sourceMappingURL=chunk-5LC2VXH5.js.map

package/dist/chunk-5LC2VXH5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spend/types.ts","../src/spend/ownership.ts","../src/spend/ceiling.ts","../src/spend/reference.ts","../src/spend/reconcile.ts","../src/spend/report.ts"],"sourcesContent":["/**\n * The vocabulary of consumer-side spend verification.\n *\n * Kept in its own module with ZERO imports so a product can type its storage\n * rows and its reconciliation config without pulling in `node:fs` through the\n * CLI half.\n *\n * The model in one paragraph: the platform's ledger is authoritative about what\n * was CHARGED. A product knows something the ledger does not — what it ASKED\n * for. Recording that second view, and diffing it against the first, is what\n * turns a platform billing defect from silent money into an alert. Nothing here\n * lets a product self-certify a charge away; the output is a discrepancy a human\n * disputes.\n */\n\n// ── the product's own view of a box's life ────────────────────────────────────\n\n/**\n * One box, as the PRODUCT understands it. Folded, not an append-only log: a\n * product runs one row per sandbox, and every field below is derived by a\n * monotonic fold (see `foldSpendBoxRecord`) so two concurrent writers cannot\n * produce a wrong answer, only a stale one.\n *\n * Timestamps are epoch ms throughout, matching the platform's own\n * `sandbox_meta.last_started_at`.\n */\nexport interface SpendBoxRecord {\n  /** The platform's sandbox id — the join key to every settlement row. */\n  readonly sandboxId: string\n  /** The product's own tenancy unit, which the platform does not model. */\n  readonly workspaceId: string\n  /** First moment the product knew this box existed. */\n  readonly createdAt: number\n  /**\n   * The idle timeout the product ASKED the platform for, seconds. This is the\n   * width of the grace window between the last thing the product saw and the\n   * moment the platform should have stopped billing.\n   */\n  readonly idleTimeoutSeconds: number\n  /**\n   * The maximum lifetime the product asked for, seconds, when it asked for one.\n   * This is the strongest bound a product holds: the platform destroys the box\n   * at `createdAt + maxLifetimeSeconds` regardless of what the product observed,\n   * so it caps the ceiling even when nothing else can (see `computeExpectedCeiling`).\n   */\n  readonly maxLifetimeSeconds: number | null\n  /** Latest moment the product OBSERVED the box doing work. */\n  readonly lastActivityAt: number\n  /**\n   * Detached runs dispatched but never observed to finish, by run id.\n   *\n   * Non-empty means the product genuinely cannot bound this box from its own\n   * observations: it handed the platform work and disconnected. The ceiling\n   * degrades accordingly rather than pretending to a tightness it did not earn.\n   */\n  readonly openDetachedRunIds: readonly string[]\n  /** When the product knows the box stopped. Cleared by later activity. */\n  readonly stoppedAt: number | null\n  /** When the product knows the box was deleted. Set once — a deleted id never returns. */\n  readonly deletedAt: number | null\n  /** Opaque product-column values, written verbatim and never read here. */\n  readonly extras?: Record<string, unknown>\n}\n\n/**\n * A fold step. Every field states its own merge rule, so a SQL implementation\n * can apply it in one statement and reach the same record an in-memory\n * read-modify-write reaches.\n */\nexport interface SpendBoxPatch {\n  /** Advance `lastActivityAt` to the max of stored and this. Never moves backward. */\n  readonly observedActivityAt?: number\n  /** Add a run id to `openDetachedRunIds` (set semantics — re-adding is a no-op). */\n  readonly openDetachedRunAdd?: string\n  /** Remove a run id from `openDetachedRunIds`. Removing an absent id is a no-op. */\n  readonly openDetachedRunRemove?: string\n  /**\n   * Latest-wins. Activity observed AFTER a recorded stop clears it: a box that\n   * worked after we thought it stopped is running again, and a stale stop would\n   * make the ceiling too tight.\n   */\n  readonly stoppedAt?: number\n  /** Set-once. A later delete observation does not move the first one. */\n  readonly deletedAt?: number\n}\n\n// ── what bounds a box's billable time ─────────────────────────────────────────\n\n/** Which fact bounds a box's billable time, weakest last. */\nexport type CeilingBasis =\n  /** The product observed deletion. Billing cannot run past a box that is gone. */\n  | 'deleted'\n  /** The product observed a stop. Billing should have closed there. */\n  | 'stopped'\n  /** No stop seen, but the platform destroys the box at its max lifetime. */\n  | 'max-lifetime'\n  /** No stop seen; the platform's idle timer is what should have closed billing. */\n  | 'idle-timeout'\n  /**\n   * An unfinished detached run and no max lifetime — the product cannot bound\n   * this box at all, so the ceiling degrades to the reconciliation instant.\n   * A finding on this basis is weak evidence and says so.\n   */\n  | 'open-detached-run'\n\n/** The upper bound on one box's billable duration, and what earned it. */\nexport interface ExpectedCeiling {\n  readonly sandboxId: string\n  readonly basis: CeilingBasis\n  /** The latest instant this box could still have been billable, epoch ms. */\n  readonly horizonAt: number\n  /** `horizonAt - createdAt + toleranceMs`. The upper bound on billable ms. */\n  readonly ceilingMs: number\n  readonly toleranceMs: number\n  /**\n   * False when the basis is `open-detached-run` — the ceiling then rests on the\n   * reconciliation instant rather than on anything the product observed, so an\n   * overage means the platform billed outside the box's own lifetime, not merely\n   * longer than expected.\n   */\n  readonly bounded: boolean\n}\n\n// ── what the platform actually emitted ────────────────────────────────────────\n\n/**\n * One settled ledger row, in the shape the platform's `credit_transactions`\n * table stores it. The product supplies these through its own fetch (the\n * platform's credit-history API, an export, a mirror) — this package never\n * reaches for them, because the ledger is the counterparty's record and reading\n * it is the product's authenticated business.\n *\n * The rows a product can fetch are scoped to the BILLING OWNER, not to the\n * product: `product: 'sandbox'` is the platform's service taxonomy and every\n * consumer app's compute wears it. So a wallet running two of our products\n * returns both products' settlements, and telling them apart is\n * {@link SpendOwnershipRule}'s job.\n */\nexport interface SettlementRow {\n  /** The ledger row id, for the dispute. */\n  readonly id: string\n  /**\n   * `sandbox:<kind>:<sandboxId>:<intervalStartMs>` — the platform's idempotency\n   * key, and the only place the billed interval's START is recorded.\n   */\n  readonly referenceId: string | null\n  /**\n   * Signed nanodollars, exactly as the ledger stores it: negative is a charge,\n   * positive is a credit or refund.\n   */\n  readonly amountNanoUsd: number\n  /** `compute` | `refund` | `inference` | … */\n  readonly type: string\n  /** `sandbox` | `router` | … */\n  readonly product: string | null\n  /** `sandbox:<sandboxId>` — the platform's aggregation unit. */\n  readonly groupKey: string | null\n  /** Settlement instant, epoch ms. The product normalizes the stored text. */\n  readonly createdAt: number\n  readonly description: string | null\n  /** Provider at-cost basis, unsigned nanodollars. Null when unattributed. */\n  readonly costBasisNanoUsd: number | null\n  /**\n   * The billed duration, when the product's ledger view exposes it directly.\n   * Null is the common case: the platform does not store duration on the row.\n   */\n  readonly billedMs: number | null\n  /**\n   * The platform API key the charge was triggered by — `credit_transactions.key_id`,\n   * stamped from the box's own creation metadata at settlement time and exposed\n   * by `/v1/billing/transactions` (which also filters on it).\n   *\n   * This is the ONLY field on a settlement row that can be attributed back to a\n   * PRODUCT rather than to a wallet or to the platform's service taxonomy, which\n   * is why {@link SpendOwnershipRule}'s shipped constructor is built on it. The\n   * sandbox id cannot do the job: the platform mints it as `sandbox-<12 hex>`\n   * from a hash of (owner, idempotency key), so a product's own box naming never\n   * reaches the ledger row.\n   *\n   * Optional, and `null` is a real answer: the platform leaves it null on legacy\n   * rows and an export may not carry the column at all. A missing key is\n   * `undecidable`, never `foreign` — see {@link SpendOwnershipVerdict}.\n   */\n  readonly keyId?: string | null\n}\n\n// ── whose box is this? ────────────────────────────────────────────────────────\n\n/**\n * What one settlement is attributable to, from inside ONE product.\n *\n * The distinction this type exists for: a sibling product's box and a charge\n * that is not ours at all look identical from inside a single product, because\n * both arrive as a settlement naming a sandbox this product's expectation ledger\n * has never heard of. Dropping both loses the check's whole purpose; reporting\n * both makes it noise. Only a platform-stamped attribution field separates them.\n */\nexport type SpendOwnershipVerdict =\n  /** Attributable to THIS product. An unrecorded one is a phantom-charge candidate. */\n  | 'mine'\n  /** Attributable to a DIFFERENT product on the same wallet. Reported, never a finding. */\n  | 'foreign'\n  /**\n   * The row carries nothing that decides it. Counted as `mine` — FAIL CLOSED.\n   * An unattributable charge on a shared wallet is precisely the shape of the\n   * thing this module exists to catch, so the ambiguous case costs a human five\n   * minutes rather than costing the product the detection.\n   */\n  | 'undecidable'\n\n/** One settlement, presented to an ownership rule. */\nexport interface SpendOwnershipCandidate {\n  readonly row: SettlementRow\n  /** The sandbox the row is attributable to, or null for a row naming none. */\n  readonly sandboxId: string | null\n}\n\n/**\n * The product's declaration of which settlements are its own.\n *\n * The one hard constraint on `decide`: it must answer from PROPERTIES OF THE\n * ROW. A rule that answers by looking the sandbox up in the product's own\n * expectation ledger deletes `unknown-box` entirely — every unrecorded box would\n * be `foreign` by construction, and \"we were billed for a box we never asked\n * for\" would become unrepresentable. The ledger already decides recorded-ness;\n * this decides ATTRIBUTION, and the two must stay independent.\n *\n * `decide` must not throw. If it does, the throw propagates and the whole pass\n * fails — a reconciliation whose ownership rule is broken has no verdict worth\n * printing, and swallowing it would turn a broken rule into a clean bill.\n */\nexport interface SpendOwnershipRule {\n  /** Named in the report and on every finding, so a reader knows what was excluded. */\n  readonly label: string\n  decide(candidate: SpendOwnershipCandidate): SpendOwnershipVerdict\n}\n\n/**\n * What this pass scoped itself to — present on every report, including a clean\n * one, because \"nothing fired\" and \"nothing was looked at\" are different\n * answers and a report that cannot tell them apart is the failure this closes.\n */\nexport interface SpendOwnershipSummary {\n  /**\n   * False when the caller declared no rule. The pass then treats every box as\n   * its own — today's behaviour, which over-reports rather than under-reports —\n   * and every `unknown-box` finding says on its face that a sibling product's\n   * box is indistinguishable from a charge that is not ours.\n   */\n  readonly declared: boolean\n  /** The rule's label, or null when none was declared. */\n  readonly label: string | null\n  /** Boxes this pass treated as this product's, and what they were charged. */\n  readonly ownedBoxes: number\n  readonly ownedNanoUsd: number\n  /**\n   * Of those, the boxes no rule could decide. Counted as owned (fail-closed) and\n   * reported separately so a product can see how much of its own verdict rests\n   * on rows that carried no attribution.\n   */\n  readonly undecidableBoxes: number\n  /** Boxes attributed to another product on the same wallet. Never findings. */\n  readonly foreignBoxes: number\n  readonly foreignNanoUsd: number\n  /**\n   * Their ids, in full — an exclusion a reader cannot audit is an exclusion\n   * they have to trust, and this module's whole posture is that nothing about\n   * money is taken on trust.\n   */\n  readonly foreignSandboxIds: readonly string[]\n}\n\n/** The parts of a settlement reference id, once parsed. */\nexport interface SettlementReference {\n  /** `stop` | `compute` | `egress` | `gpu-lease` | anything the platform adds. */\n  readonly kind: string\n  /** For compute kinds, the sandbox id. For `gpu-lease`, the lease id. */\n  readonly resourceId: string\n  /** The interval's start, epoch ms. Null for kinds that carry no interval. */\n  readonly intervalStartMs: number | null\n}\n\n/** How a settled duration was arrived at — every duration finding carries one. */\nexport type BilledDurationBasis =\n  /** The ledger row carried the duration. Exact. */\n  | 'reported'\n  /** `amount ÷ the product's stated hourly rate`. Exact when the rate is right. */\n  | 'rate'\n  /**\n   * `settledAt - intervalStart`. An UPPER bound, not the billed duration: a\n   * correct settlement posted late by the platform's durable settlement queue\n   * reads longer here than it billed. Findings on this basis say so.\n   */\n  | 'reference-span'\n  /** No basis available — duration rules are skipped for this row. */\n  | 'unknown'\n\n// ── findings ──────────────────────────────────────────────────────────────────\n\n/** The checks this reconciler runs. Each is individually skippable, by name. */\nexport type SpendCheckId =\n  /** A settlement against a box the product has no record of ever asking for. */\n  | 'unknown-box'\n  /** A settled duration longer than the product's own upper bound allows. */\n  | 'over-ceiling'\n  /** A spend window far above the trailing median — the burst shape of a defect. */\n  | 'velocity'\n  /** The balance the product observes has gone below its floor. */\n  | 'negative-balance'\n\nexport const SPEND_CHECKS: readonly SpendCheckId[] = [\n  'unknown-box',\n  'over-ceiling',\n  'velocity',\n  'negative-balance',\n]\n\n/**\n * One discrepancy, with every number the rule compared.\n *\n * Nullable fields are per-check and deliberately present-but-null rather than\n * absent: a reader scanning a JSON dump can tell \"this rule does not measure\n * that\" from \"that measurement is missing\".\n */\nexport interface SpendFinding {\n  readonly check: SpendCheckId\n  /** What is wrong, in one sentence, with the numbers in it. */\n  readonly message: string\n  /** What to do about it. A finding without a remedy is a complaint. */\n  readonly remedy: string\n  readonly sandboxId: string | null\n  readonly workspaceId: string | null\n  /** The ledger rows that evidence this finding — the dispute's exhibit list. */\n  readonly referenceIds: readonly string[]\n  /** Nanodollars this finding puts in question, unsigned. */\n  readonly settledNanoUsd: number\n  /** `over-ceiling` — the duration actually settled, and how that was derived. */\n  readonly settledMs: number | null\n  readonly durationBasis: BilledDurationBasis | null\n  /** `over-ceiling` — the bound it broke, and what earned that bound. */\n  readonly ceilingMs: number | null\n  readonly overageMs: number | null\n  readonly ceilingBasis: CeilingBasis | null\n  /** `velocity` — the window, its trailing median, and the ratio between them. */\n  readonly windowNanoUsd: number | null\n  readonly trailingMedianNanoUsd: number | null\n  readonly velocityRatio: number | null\n  readonly windowStartAt: number | null\n  /** `negative-balance` — the observed balance and the floor it broke. */\n  readonly balanceNanoUsd: number | null\n  readonly balanceFloorNanoUsd: number | null\n}\n\n/** What one reconciliation pass concluded. */\nexport interface SpendReport {\n  /** True when nothing fired. `ok === findings.length === 0`. */\n  readonly ok: boolean\n  readonly findings: readonly SpendFinding[]\n  readonly checksRun: readonly SpendCheckId[]\n  /** Rows the pass read, including the ones no rule looked at. */\n  readonly rowsExamined: number\n  /** Distinct boxes those rows settled against. */\n  readonly boxesExamined: number\n  /** Total charged across every examined row, unsigned nanodollars. */\n  readonly settledNanoUsd: number\n  /** Total credited back across every examined row, unsigned nanodollars. */\n  readonly creditedNanoUsd: number\n  /** What this pass claimed as its own, and what it excluded as another product's. */\n  readonly ownership: SpendOwnershipSummary\n  /** The instant the pass treated as \"now\". */\n  readonly asOf: number\n}\n","import type {\n  SettlementRow,\n  SpendOwnershipRule,\n  SpendOwnershipVerdict,\n} from './types'\n\n/**\n * Which settlements belong to the product running the reconciliation.\n *\n * ## The problem this module is the answer to\n *\n * A product fetches its settled rows from `/v1/billing/transactions`, scoped to\n * the BILLING OWNER — the wallet whose key paid. `product: 'sandbox'` narrows\n * that to compute, but `sandbox` is the PLATFORM's service taxonomy: every\n * consumer app's box compute wears it. So a Tangle account running two of our\n * products hands each product's reconciliation the other product's boxes, and\n * `unknown-box` — correctly, by its own rule — reports one finding per sibling\n * box. Two products on one wallet make each other's spend check useless.\n *\n * ## Why the obvious fix is the wrong fix\n *\n * The obvious fix is to reconcile only the boxes already in the product's\n * expectation ledger. That removes the false findings and removes the check:\n * `unknown-box` exists to catch \"we were billed for a box we never asked for\",\n * which is the 2026-08-05 incident's day-one signature and the ONLY thing a\n * product with no lifecycle bookkeeping can catch at all. Filtering to the\n * ledger makes a phantom charge unrepresentable — the ledger's own contents\n * would define the answer.\n *\n * So the residue — settlements against boxes with no ledger record — has to be\n * SPLIT, not dropped. A sibling's box and a phantom charge are indistinguishable\n * unless something outside the product's own bookkeeping tells them apart.\n *\n * ## What can tell them apart\n *\n * Exactly one field on a settlement row, and it is not the sandbox id. The\n * platform mints that id as `sandbox-<12 hex>` — a hash of (owner, idempotency\n * key) — so a product's own box naming never reaches the ledger row, and the\n * charge's `description` carries only the resource spec. What does survive is\n * `credit_transactions.key_id`: the platform API key the box was created under,\n * stamped from the box's own creation metadata at settlement and filterable on\n * the transactions endpoint. Each product deploys with its own key, so the key\n * is the product's billing identity as the PLATFORM recorded it — not as the\n * product asserts it after the fact.\n *\n * That asymmetry is what makes the split safe. A product cannot widen its own\n * claim by claiming; it can only recognise a stamp the platform already wrote.\n *\n * ## The three rules that keep the detection intact\n *\n * 1. **A recorded box is never excluded.** Ownership is consulted only for\n *    boxes with no ledger record. A rule that is wrong or over-narrow therefore\n *    cannot hide an `over-ceiling` finding on a box the product recorded — the\n *    incident's own 23 findings survive any rule at all.\n * 2. **Undecidable fails closed.** A row with no key attribution is `mine`, so\n *    an unattributable charge on a shared wallet is reported. Silence is never\n *    the answer to \"I don't know.\"\n * 3. **A box is claimed if ANY of its rows claims it.** The fold is\n *    `mine > undecidable > foreign`, which is the module's standing asymmetry:\n *    every derivation error pushes toward a false alarm, never toward a missed\n *    charge.\n */\n\n/**\n * Claim every settlement the platform stamped with one of these API keys.\n *\n * The shipped rule, because it is the only one built on a field the PLATFORM\n * writes. Give each product its own platform key and this separates them\n * exactly; give two products the same key and no consumer-side rule can tell\n * them apart, because after settlement there is nothing left that differs — the\n * fix then is a second key, not a cleverer predicate.\n *\n * A row with no `keyId` (a legacy row, or an export that drops the column) is\n * `undecidable`, never `foreign`: the absence of an attribution is not evidence\n * that the charge is someone else's.\n *\n * @param keyIds The product's own platform API key ids. Must be non-empty — a\n *   rule that owns nothing would classify every settlement as another product's\n *   and report a clean bill for an account nobody is checking.\n */\nexport function ownedByBillingKeys(keyIds: readonly string[]): SpendOwnershipRule {\n  const owned = new Set(keyIds.map((id) => id.trim()).filter(Boolean))\n  if (owned.size === 0) {\n    throw new Error(\n      'ownedByBillingKeys needs at least one key id: a rule that owns no key classifies every ' +\n        'settlement as another product\\'s and reports a clean bill for an unchecked account.',\n    )\n  }\n  const label = `billing key ${[...owned].join(', ')}`\n  return {\n    label,\n    decide({ row }) {\n      const keyId = row.keyId?.trim()\n      if (!keyId) return 'undecidable'\n      return owned.has(keyId) ? 'mine' : 'foreign'\n    },\n  }\n}\n\n/**\n * One box's verdict, folded over every row that settled against it.\n *\n * `mine` wins over `undecidable`, which wins over `foreign`: it takes one row\n * attributable to this product to make the box this product's problem, and one\n * unattributable row to stop the box being excluded. Both directions push\n * toward reporting, which is the only direction that cannot lose money.\n *\n * Exported because a product auditing its own scoping wants the same answer the\n * reconciler reached, not a re-derivation of it.\n */\nexport function decideBoxOwnership(\n  rule: SpendOwnershipRule,\n  sandboxId: string,\n  rows: readonly SettlementRow[],\n): SpendOwnershipVerdict {\n  let verdict: SpendOwnershipVerdict = 'foreign'\n  for (const row of rows) {\n    const rowVerdict = rule.decide({ row, sandboxId })\n    if (rowVerdict === 'mine') return 'mine'\n    if (rowVerdict === 'undecidable') verdict = 'undecidable'\n  }\n  return verdict\n}\n","import type { CeilingBasis, ExpectedCeiling, SpendBoxRecord } from './types'\n\n/**\n * Slack allowed between the product's bound and what the platform settled,\n * before an overage is called a discrepancy. 15 minutes.\n *\n * Not a guess: it is the platform's OWN staleness threshold for compute\n * settlement. Its runbook clears an incident when\n * `/health computeSettlement.oldestAgeSeconds` is \"back under 900\" — so 900 s is\n * the age the platform itself treats as normal settlement lag, and anything\n * inside it is drift the platform has already declared acceptable. Below that a\n * product would alert on the platform's ordinary queue behaviour; far above it\n * the tolerance starts eating the signal, because the idle window it must stay\n * well under is 3600 s in every shipped product.\n *\n * It is a caller parameter because a product that asks for a shorter idle\n * timeout must shrink this with it.\n */\nexport const DEFAULT_CEILING_TOLERANCE_MS = 900_000\n\nexport interface ComputeExpectedCeilingOptions {\n  /** The instant the reconciliation treats as \"now\", epoch ms. */\n  readonly asOf: number\n  /** Slack before an overage counts. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */\n  readonly toleranceMs?: number\n}\n\n/**\n * The upper bound on how long one box could honestly have been billable.\n *\n * The whole design constraint is that this must stay an UPPER bound under\n * everything the product cannot see. Three such blind spots exist, and they\n * pull in different directions:\n *\n * - **Platform-side suspends.** The platform can park a box the product never\n *   hears about. That only ever REDUCES real billable time, so an upper bound\n *   is unaffected and nothing here widens for it.\n * - **Detached runs.** The product dispatches work and disconnects. The box\n *   keeps working — and billing — after the last activity the product saw, so\n *   `lastActivityAt` understates the truth. An unfinished detached run\n *   therefore abandons the activity-based bound entirely rather than reporting\n *   a bound it cannot support.\n * - **Reconnects.** A browser or worker re-attaches and work resumes. This\n *   needs no special case: a reconnect is recorded as activity, the fold takes\n *   the max, and the horizon moves out on its own.\n *\n * The bound that rescues the detached case is `maxLifetimeSeconds`. The platform\n * destroys the box at `createdAt + maxLifetimeSeconds` no matter what anyone\n * observed, so a product that asks for one holds a hard bound that survives\n * every blind spot above. Both shipped products ask for 86 400 s, which is why\n * the incident — 124 to 268 hours settled against boxes with a 24-hour\n * lifetime — is detectable with no lifecycle bookkeeping at all.\n */\nexport function computeExpectedCeiling(\n  record: SpendBoxRecord,\n  options: ComputeExpectedCeilingOptions,\n): ExpectedCeiling {\n  const toleranceMs = options.toleranceMs ?? DEFAULT_CEILING_TOLERANCE_MS\n  const { asOf } = options\n\n  let basis: CeilingBasis\n  let horizonAt: number\n\n  if (record.deletedAt !== null) {\n    basis = 'deleted'\n    horizonAt = record.deletedAt\n  } else if (record.stoppedAt !== null) {\n    basis = 'stopped'\n    horizonAt = record.stoppedAt\n  } else if (record.openDetachedRunIds.length > 0) {\n    // Nothing the product observed bounds this box. Fall back to the\n    // reconciliation instant, and say so through `bounded: false`.\n    basis = 'open-detached-run'\n    horizonAt = asOf\n  } else {\n    basis = 'idle-timeout'\n    horizonAt = record.lastActivityAt + record.idleTimeoutSeconds * 1000\n  }\n\n  // The hard platform bound wins whenever it is tighter — including over an\n  // unfinished detached run, which is what turns an unbounded box back into a\n  // bounded one.\n  if (record.maxLifetimeSeconds !== null) {\n    const lifetimeHorizon = record.createdAt + record.maxLifetimeSeconds * 1000\n    if (lifetimeHorizon < horizonAt) {\n      basis = 'max-lifetime'\n      horizonAt = lifetimeHorizon\n    }\n  }\n\n  // Time that has not elapsed cannot have been billed, so an idle window\n  // reaching into the future does not widen the bound. This only ever tightens\n  // the ceiling, so it cannot mask a charge.\n  if (horizonAt > asOf) horizonAt = asOf\n  // A horizon before creation would produce a negative ceiling; a box is at\n  // minimum billable for the instant it existed.\n  if (horizonAt < record.createdAt) horizonAt = record.createdAt\n\n  return {\n    sandboxId: record.sandboxId,\n    basis,\n    horizonAt,\n    ceilingMs: horizonAt - record.createdAt + toleranceMs,\n    toleranceMs,\n    bounded: basis !== 'open-detached-run',\n  }\n}\n","import type { SettlementReference, SettlementRow } from './types'\n\n/**\n * Parse the platform's settlement idempotency key.\n *\n * The platform mints it as `sandbox:<kind>:<resourceId>:<intervalStart>`\n * (`d1-usage-service.ts`), where `intervalStart` is the interval cursor in epoch\n * ms — the SAME `last_started_at` the settlement subtracts from to get its\n * billed duration. That makes this string the only place a consumer can read the\n * billed interval's start, because the ledger row itself stores no duration.\n *\n * Kinds seen in production: `stop` (an interval closing), `compute` (a heartbeat\n * claim), `egress`, `gpu-lease`. `stop` deliberately covers both a settle and a\n * late stop racing over the same claim, so the two derive one reference id and\n * the ledger's uniqueness constraint makes the overlap safe.\n *\n * Returns null for anything that is not a sandbox reference — a router\n * inference row, a grant, a refund — rather than guessing.\n */\nexport function parseSettlementReference(referenceId: string | null | undefined): SettlementReference | null {\n  if (!referenceId) return null\n  const parts = referenceId.split(':')\n  if (parts.length < 3 || parts[0] !== 'sandbox') return null\n  const kind = parts[1]\n  if (!kind) return null\n\n  // The trailing segment is the interval cursor ONLY when it reads as an epoch\n  // instant. `sandbox:gpu-lease:<leaseId>` has no cursor, and a resource id that\n  // happened to contain a colon must not have its tail eaten as one.\n  const tail = parts[parts.length - 1] as string\n  const tailMs = /^\\d+$/.test(tail) ? Number(tail) : Number.NaN\n  const hasCursor = parts.length >= 4 && Number.isSafeInteger(tailMs) && tailMs > 0\n\n  const resourceId = hasCursor ? parts.slice(2, -1).join(':') : parts.slice(2).join(':')\n  if (!resourceId) return null\n\n  return { kind, resourceId, intervalStartMs: hasCursor ? tailMs : null }\n}\n\n/**\n * Read the sandbox id out of the platform's aggregation key, `sandbox:<id>`.\n *\n * Distinct from the reference id: `groupKey` is the unit a billing statement\n * groups by and is deliberately NOT unique per row, while `referenceId` is\n * unique per interval. A null group key means \"do not aggregate\" (grants,\n * top-ups, refunds, transfers) and is not an error.\n */\nexport function parseSandboxGroupKey(groupKey: string | null | undefined): string | null {\n  if (!groupKey) return null\n  const parts = groupKey.split(':')\n  if (parts.length < 2 || parts[0] !== 'sandbox') return null\n  const id = parts.slice(1).join(':')\n  return id || null\n}\n\n/**\n * The sandbox a settlement row is attributable to.\n *\n * The reference id wins over the group key because it is the field the platform\n * dedups on, so it is the one guaranteed present and correct on a compute\n * settlement; the group key is the fallback for rows written before a producer\n * stamped a reference, and for kinds whose reference names something else (a GPU\n * lease id, not a box).\n */\nexport function settlementSandboxId(row: SettlementRow): string | null {\n  const reference = parseSettlementReference(row.referenceId)\n  if (reference && reference.intervalStartMs !== null) return reference.resourceId\n  return parseSandboxGroupKey(row.groupKey) ?? (reference ? reference.resourceId : null)\n}\n\n/** True when a row is a charge (the ledger stores charges as negative amounts). */\nexport function isCharge(row: SettlementRow): boolean {\n  return row.amountNanoUsd < 0\n}\n\n/** A charge's magnitude in unsigned nanodollars; 0 for credits. */\nexport function chargeNanoUsd(row: SettlementRow): number {\n  return row.amountNanoUsd < 0 ? -row.amountNanoUsd : 0\n}\n","import { DEFAULT_CEILING_TOLERANCE_MS, computeExpectedCeiling } from './ceiling'\nimport { decideBoxOwnership } from './ownership'\nimport { chargeNanoUsd, parseSettlementReference, settlementSandboxId } from './reference'\nimport type { SpendLedgerStorePort } from './store'\nimport {\n  SPEND_CHECKS,\n  type BilledDurationBasis,\n  type CeilingBasis,\n  type SettlementRow,\n  type SpendBoxRecord,\n  type SpendCheckId,\n  type SpendFinding,\n  type SpendOwnershipRule,\n  type SpendOwnershipSummary,\n  type SpendOwnershipVerdict,\n  type SpendReport,\n} from './types'\n\n/** How many nanodollars in one US dollar. The ledger's unit. */\nconst NANO_PER_USD = 1_000_000_000\nconst MS_PER_HOUR = 3_600_000\n\nexport interface VelocityOptions {\n  /** Bucket width for a spend window, ms. Default 24 h. */\n  readonly windowMs?: number\n  /** Fire when a window exceeds this multiple of the trailing median. Default 5. */\n  readonly multiple?: number\n  /**\n   * Windows of history required before a median means anything. Default 3.\n   * Below this the rule stays silent, so a product's genuine first days of\n   * usage are not reported as an anomaly.\n   */\n  readonly minTrailingWindows?: number\n  /**\n   * A window under this never fires, whatever the ratio. Default $1.00.\n   *\n   * Without a floor the rule is useless: a trailing median of a tenth of a cent\n   * makes every ordinary day a 5x outlier. $1.00 is set from the incident's own\n   * distribution — the smallest of the eight affected wallets took $1.98, and\n   * the two rows in the same window that were GENUINE were sub-cent. So the\n   * floor sits above the noise and below every real finding.\n   */\n  readonly minAbsoluteNanoUsd?: number\n}\n\nconst DEFAULT_VELOCITY: Required<VelocityOptions> = {\n  windowMs: 86_400_000,\n  multiple: 5,\n  minTrailingWindows: 3,\n  minAbsoluteNanoUsd: NANO_PER_USD,\n}\n\n/** The balance the product observes, and the floor it must not cross. */\nexport interface ObservedBalance {\n  /** Signed nanodollars, as the platform reports it. */\n  readonly nanoUsd: number\n  /** Below this is a finding. Default 0. */\n  readonly floorNanoUsd?: number\n}\n\n/**\n * A box's price, nanodollars per hour, used to derive an EXACT billed duration\n * from a charge. Return null when the product does not know the box's rate; the\n * reconciler then falls back to the reference span.\n */\nexport type BoxRateResolver = (record: SpendBoxRecord | null, sandboxId: string) => number | null | undefined\n\nexport interface ReconcileSpendOptions {\n  /**\n   * Settled ledger rows, supplied by the product's own authenticated fetch.\n   *\n   * The fetch can only scope to a WALLET — `product: 'sandbox'` is the\n   * platform's service taxonomy, not this product's — so on an account running\n   * more than one of our products these rows carry the siblings' boxes too.\n   * {@link ReconcileSpendOptions.ownership} is what separates them.\n   */\n  readonly rows: readonly SettlementRow[]\n  /** The product's expectation ledger. */\n  readonly store: SpendLedgerStorePort\n  /**\n   * Which of those rows are THIS product's — see {@link SpendOwnershipRule} and\n   * the shipped `ownedByBillingKeys`.\n   *\n   * Omitting it is safe and changes nothing: the pass claims every box, which is\n   * the behaviour that shipped, and the direction that over-reports rather than\n   * under-reports. It is not silent about it — `report.ownership.declared` is\n   * `false`, `formatSpendReport` says so above the findings, and every\n   * `unknown-box` finding states on its face that a sibling product's box is\n   * indistinguishable from a charge that is not ours.\n   *\n   * Declaring it never weakens the ledger-backed checks: ownership is consulted\n   * ONLY for boxes with no expectation record, so `over-ceiling` on a recorded\n   * box fires whatever the rule says.\n   */\n  readonly ownership?: SpendOwnershipRule\n  /** Treated as \"now\". Default `Date.now()`. */\n  readonly asOf?: number\n  /** Ceiling slack. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */\n  readonly toleranceMs?: number\n  /** Box price, for the exact duration basis. A number applies to every box. */\n  readonly nanoUsdPerHour?: number | BoxRateResolver\n  /** Velocity tuning, or `false` to skip the rule. */\n  readonly velocity?: VelocityOptions | false\n  /** The workspace balance, when the product can see one. Omitted skips the rule. */\n  readonly balance?: ObservedBalance\n  /** Stamped onto findings so an alert names the tenant. */\n  readonly workspaceId?: string\n  /** Checks to leave out of this pass. */\n  readonly skip?: readonly SpendCheckId[]\n}\n\nfunction usd(nano: number): string {\n  return `$${(nano / NANO_PER_USD).toFixed(2)}`\n}\n\nfunction hours(ms: number): string {\n  return `${(ms / MS_PER_HOUR).toFixed(1)}h`\n}\n\n/** Trust order, least trustworthy first — a mixed aggregate reports the weakest. */\nconst BASIS_TRUST: readonly BilledDurationBasis[] = ['unknown', 'reference-span', 'rate', 'reported']\n\nfunction weakestBasis(a: BilledDurationBasis, b: BilledDurationBasis): BilledDurationBasis {\n  return BASIS_TRUST.indexOf(a) <= BASIS_TRUST.indexOf(b) ? a : b\n}\n\n/**\n * How long one settlement billed for, and how confidently we know it.\n *\n * The ledger row does not store a duration — this is the whole reason the check\n * is subtle. Three ways to recover it, best first:\n *\n * 1. `reported` — the product's ledger view exposed it. Exact.\n * 2. `rate` — `charge / pricePerHour`. Exact, because the platform computes the\n *    charge as `(durationMs / 3_600_000) * costPerHour` and nothing else enters\n *    it. Requires the product to know its box's price.\n * 3. `reference-span` — `settledAt - intervalStart`, both read off the row. An\n *    UPPER bound, not the duration: a correct settlement delayed by the\n *    platform's durable settlement queue reads longer here than it billed. It is\n *    exact for the failure this module exists to catch, because billing \"up to\n *    now\" makes the settlement instant and the interval end the same moment.\n */\nfunction resolveBilledMs(\n  row: SettlementRow,\n  ratePerHourNano: number | null,\n): { ms: number; basis: BilledDurationBasis } {\n  if (row.billedMs !== null) return { ms: row.billedMs, basis: 'reported' }\n\n  const charge = chargeNanoUsd(row)\n  if (ratePerHourNano !== null && ratePerHourNano > 0 && charge > 0) {\n    return { ms: (charge / ratePerHourNano) * MS_PER_HOUR, basis: 'rate' }\n  }\n\n  const reference = parseSettlementReference(row.referenceId)\n  if (reference?.intervalStartMs != null && row.createdAt > reference.intervalStartMs) {\n    return { ms: row.createdAt - reference.intervalStartMs, basis: 'reference-span' }\n  }\n\n  return { ms: 0, basis: 'unknown' }\n}\n\nfunction median(values: readonly number[]): number {\n  if (values.length === 0) return 0\n  const sorted = [...values].sort((a, b) => a - b)\n  const mid = Math.floor(sorted.length / 2)\n  if (sorted.length % 2 === 1) return sorted[mid] as number\n  return (((sorted[mid - 1] as number) + (sorted[mid] as number)) / 2)\n}\n\n/**\n * What an `unknown-box` finding can honestly claim about WHOSE box it is.\n *\n * Three different statements, because the reader's next action differs: chase a\n * charge inside our own billing identity, chase a charge nothing attributes,\n * or first go and declare an ownership rule so the question can be answered at\n * all. A single message covering all three would be the vaguest of the three.\n */\nfunction unknownBoxAttribution(\n  ownership: SpendOwnershipRule | null,\n  verdict: SpendOwnershipVerdict,\n): string {\n  if (!ownership) {\n    return (\n      ' No ownership rule was declared for this pass, so a sibling product\\'s box on the same ' +\n      'wallet reads exactly like a charge that is not ours — this finding could be either.'\n    )\n  }\n  if (verdict === 'undecidable') {\n    return (\n      ` The ownership rule (${ownership.label}) could not decide it: the settlement carries no ` +\n      'billing-key attribution to exclude it by, so it is reported rather than dropped.'\n    )\n  }\n  return ` The ownership rule (${ownership.label}) attributes it to THIS product.`\n}\n\nfunction unknownBoxRemedy(\n  ownership: SpendOwnershipRule | null,\n  verdict: SpendOwnershipVerdict,\n  sandboxId: string,\n): string {\n  const lookup = `Look up ${sandboxId} on the platform before disputing.`\n  if (!ownership) {\n    return (\n      'Declare `ownership` (see `ownedByBillingKeys`) so a sibling product\\'s box stops reading as ' +\n      'a discrepancy — without it this check cannot tell one from a charge that is not ours. ' +\n      'Until then, treat this as one of three things: a sibling product on the same wallet, a box ' +\n      `provisioned outside the recorded seam, or a box that is not ours at all. ${lookup}`\n    )\n  }\n  if (verdict === 'undecidable') {\n    return (\n      'An unattributable charge on a shared wallet is exactly what a phantom charge looks like, so ' +\n      'it is reported by design rather than excluded. Confirm the row genuinely predates key ' +\n      `attribution before dismissing it. ${lookup}`\n    )\n  }\n  return (\n    'This box is inside this product\\'s own billing attribution and the product never recorded it, ' +\n    'so it is either a provision that bypassed the recorded seam or a charge that is not ours. ' +\n    `${lookup}`\n  )\n}\n\nfunction emptyFinding(check: SpendCheckId): Omit<SpendFinding, 'message' | 'remedy'> {\n  return {\n    check,\n    sandboxId: null,\n    workspaceId: null,\n    referenceIds: [],\n    settledNanoUsd: 0,\n    settledMs: null,\n    durationBasis: null,\n    ceilingMs: null,\n    overageMs: null,\n    ceilingBasis: null,\n    windowNanoUsd: null,\n    trailingMedianNanoUsd: null,\n    velocityRatio: null,\n    windowStartAt: null,\n    balanceNanoUsd: null,\n    balanceFloorNanoUsd: null,\n  }\n}\n\n/**\n * Diff what the platform charged against what the product believes it asked for.\n *\n * Never disputes anything and never writes: the output is a report a human acts\n * on. The platform's ledger stays authoritative — this only ever produces the\n * evidence for a conversation with it.\n */\nexport async function reconcileSpend(options: ReconcileSpendOptions): Promise<SpendReport> {\n  const asOf = options.asOf ?? Date.now()\n  const toleranceMs = options.toleranceMs ?? DEFAULT_CEILING_TOLERANCE_MS\n  const workspaceId = options.workspaceId ?? null\n  const skip = new Set(options.skip ?? [])\n  const checksRun = SPEND_CHECKS.filter((check) => !skip.has(check))\n  const runs = (check: SpendCheckId): boolean => !skip.has(check)\n\n  const ownership = options.ownership ?? null\n\n  const findings: SpendFinding[] = []\n  let settledNanoUsd = 0\n  let creditedNanoUsd = 0\n  let ownedBoxes = 0\n  let ownedNanoUsd = 0\n  let undecidableBoxes = 0\n  let foreignNanoUsd = 0\n  const foreignSandboxIds: string[] = []\n\n  // ── group charges by the box they are attributable to ──────────────────────\n  const byBox = new Map<string, SettlementRow[]>()\n  for (const row of options.rows) {\n    if (row.amountNanoUsd < 0) settledNanoUsd += -row.amountNanoUsd\n    else creditedNanoUsd += row.amountNanoUsd\n    if (row.amountNanoUsd >= 0) continue\n    const sandboxId = settlementSandboxId(row)\n    if (!sandboxId) continue\n    const bucket = byBox.get(sandboxId)\n    if (bucket) bucket.push(row)\n    else byBox.set(sandboxId, [row])\n  }\n\n  const rateOf = (record: SpendBoxRecord | null, sandboxId: string): number | null => {\n    const rate = options.nanoUsdPerHour\n    if (rate === undefined) return null\n    if (typeof rate === 'number') return rate\n    return rate(record, sandboxId) ?? null\n  }\n\n  for (const [sandboxId, rows] of byBox) {\n    const record = await options.store.load(sandboxId)\n    const referenceIds = rows.map((row) => row.referenceId ?? row.id)\n    const charged = rows.reduce((sum, row) => sum + chargeNanoUsd(row), 0)\n\n    // A box the product RECORDED is this product's by construction, and no\n    // ownership rule may un-own it. That is what stops a wrong or over-narrow\n    // rule from hiding an over-ceiling finding: the ledger decides recorded-ness,\n    // the rule decides attribution, and the rule only ever gets a say about the\n    // residue neither of them has claimed.\n    const verdict: SpendOwnershipVerdict = record\n      ? 'mine'\n      : ownership\n        ? decideBoxOwnership(ownership, sandboxId, rows)\n        : 'mine'\n\n    if (verdict === 'foreign') {\n      foreignSandboxIds.push(sandboxId)\n      foreignNanoUsd += charged\n      continue\n    }\n    ownedBoxes += 1\n    ownedNanoUsd += charged\n    if (verdict === 'undecidable') undecidableBoxes += 1\n\n    // ── unknown-box ──────────────────────────────────────────────────────────\n    if (!record) {\n      if (runs('unknown-box')) {\n        findings.push({\n          ...emptyFinding('unknown-box'),\n          sandboxId,\n          workspaceId,\n          referenceIds,\n          settledNanoUsd: charged,\n          message:\n            `${usd(charged)} settled across ${rows.length} row(s) against sandbox ${sandboxId}, ` +\n            'which this product has no record of ever asking for.' +\n            unknownBoxAttribution(ownership, verdict),\n          remedy: unknownBoxRemedy(ownership, verdict, sandboxId),\n        })\n      }\n      continue\n    }\n\n    // ── over-ceiling ─────────────────────────────────────────────────────────\n    if (!runs('over-ceiling')) continue\n\n    const ceiling = computeExpectedCeiling(record, { asOf, toleranceMs })\n    const ratePerHourNano = rateOf(record, sandboxId)\n\n    let settledMs = 0\n    let basis: BilledDurationBasis = 'reported'\n    let anyMeasured = false\n    for (const row of rows) {\n      const resolved = resolveBilledMs(row, ratePerHourNano)\n      if (resolved.basis === 'unknown') {\n        basis = weakestBasis(basis, 'unknown')\n        continue\n      }\n      anyMeasured = true\n      settledMs += resolved.ms\n      basis = weakestBasis(basis, resolved.basis)\n    }\n    if (!anyMeasured) continue\n    if (settledMs <= ceiling.ceilingMs) continue\n\n    const overageMs = settledMs - ceiling.ceilingMs\n    const confidence = ceiling.bounded\n      ? ''\n      : ' The product could not bound this box from its own observations (an unfinished detached ' +\n        'run, and no max lifetime), so the ceiling rests on the reconciliation instant: this ' +\n        'settlement bills time outside the box\\'s own life, not merely more than expected.'\n    const spanCaveat =\n      basis === 'reference-span'\n        ? ' Duration is derived from the settlement instant minus the interval start, which ' +\n          'overstates a settlement the platform merely posted late — confirm before disputing.'\n        : ''\n\n    findings.push({\n      ...emptyFinding('over-ceiling'),\n      sandboxId,\n      workspaceId: record.workspaceId || workspaceId,\n      referenceIds,\n      settledNanoUsd: charged,\n      settledMs,\n      durationBasis: basis,\n      ceilingMs: ceiling.ceilingMs,\n      overageMs,\n      ceilingBasis: ceiling.basis,\n      message:\n        `Sandbox ${sandboxId} settled ${hours(settledMs)} (${usd(charged)}) across ${rows.length} ` +\n        `row(s), against an expected ceiling of ${hours(ceiling.ceilingMs)} — over by ` +\n        `${hours(overageMs)}. Ceiling basis: ${ceiling.basis}; duration basis: ${basis}.` +\n        confidence +\n        spanCaveat,\n      remedy:\n        `Dispute ${referenceIds.join(', ')} against the platform ledger with both numbers. ` +\n        (ceiling.basis === 'stopped' || ceiling.basis === 'deleted'\n          ? 'The product recorded this box as no longer running before the billed time ended, so ' +\n            'either the stop did not take or the interval was settled at the wrong boundary.'\n          : 'Freeze the open interval before anything deletes this box — deleting a box with an ' +\n            'open compute interval settles the whole gap at once.'),\n    })\n  }\n\n  // ── velocity ───────────────────────────────────────────────────────────────\n  if (runs('velocity') && options.velocity !== false) {\n    const cfg = { ...DEFAULT_VELOCITY, ...(options.velocity ?? {}) }\n    const buckets = new Map<number, { nano: number; references: string[] }>()\n    for (const row of options.rows) {\n      const charge = chargeNanoUsd(row)\n      if (charge === 0) continue\n      // Velocity is decided per ROW, not per box, because a row naming no\n      // sandbox at all still counts toward what this product spent. A sibling's\n      // burst is excluded rather than paged on: a product cannot dispute a\n      // charge it did not incur, and leaving them in makes one product's\n      // incident wake every product on the wallet.\n      if (ownership && ownership.decide({ row, sandboxId: settlementSandboxId(row) }) === 'foreign') {\n        continue\n      }\n      const bucketStart = Math.floor(row.createdAt / cfg.windowMs) * cfg.windowMs\n      const bucket = buckets.get(bucketStart)\n      if (bucket) {\n        bucket.nano += charge\n        bucket.references.push(row.referenceId ?? row.id)\n      } else {\n        buckets.set(bucketStart, { nano: charge, references: [row.referenceId ?? row.id] })\n      }\n    }\n\n    const ordered = [...buckets.entries()].sort((a, b) => a[0] - b[0])\n    for (let i = 0; i < ordered.length; i++) {\n      const entry = ordered[i]\n      if (!entry) continue\n      const [windowStartAt, bucket] = entry\n      if (i < cfg.minTrailingWindows) continue\n      const trailing = ordered.slice(0, i).map(([, prior]) => prior.nano)\n      const trailingMedian = median(trailing)\n      const threshold = Math.max(trailingMedian * cfg.multiple, cfg.minAbsoluteNanoUsd)\n      if (bucket.nano <= threshold) continue\n      const ratio = trailingMedian > 0 ? bucket.nano / trailingMedian : Number.POSITIVE_INFINITY\n\n      findings.push({\n        ...emptyFinding('velocity'),\n        workspaceId,\n        referenceIds: bucket.references,\n        settledNanoUsd: bucket.nano,\n        windowNanoUsd: bucket.nano,\n        trailingMedianNanoUsd: trailingMedian,\n        velocityRatio: ratio,\n        windowStartAt,\n        message:\n          `${usd(bucket.nano)} settled in the window starting ${new Date(windowStartAt).toISOString()} ` +\n          `across ${bucket.references.length} row(s), against a trailing median of ` +\n          `${usd(trailingMedian)} over ${trailing.length} prior window(s) — ` +\n          `${Number.isFinite(ratio) ? `${ratio.toFixed(1)}x` : 'no prior spend to compare against'}, ` +\n          `over the ${cfg.multiple}x threshold.` +\n          (ownership\n            ? ` Counted over this product's own rows only (${ownership.label}); the wallet total ` +\n              'for the window is higher when a sibling product settled into it.'\n            : ' Counted over every row on the wallet, which on a shared account includes any ' +\n              'sibling product\\'s spend.'),\n        remedy:\n          'A burst of this shape is what a settlement defect looks like from the consumer side: ' +\n          'long-dormant intervals cashed out at once. Check whether these rows carry interval ' +\n          'starts far older than the settlement instant before treating it as real usage.',\n      })\n    }\n  }\n\n  // ── negative-balance ───────────────────────────────────────────────────────\n  if (runs('negative-balance') && options.balance) {\n    const floor = options.balance.floorNanoUsd ?? 0\n    if (options.balance.nanoUsd < floor) {\n      findings.push({\n        ...emptyFinding('negative-balance'),\n        workspaceId,\n        settledNanoUsd: Math.max(0, floor - options.balance.nanoUsd),\n        balanceNanoUsd: options.balance.nanoUsd,\n        balanceFloorNanoUsd: floor,\n        message:\n          `Observed balance ${usd(options.balance.nanoUsd)} is below the floor ${usd(floor)}.`,\n        remedy:\n          'Stop provisioning new compute for this owner until the balance is explained. A negative ' +\n          'balance that nobody is watching is how a billing defect becomes settled money.',\n      })\n    }\n  }\n\n  const ownershipSummary: SpendOwnershipSummary = {\n    declared: ownership !== null,\n    label: ownership?.label ?? null,\n    ownedBoxes,\n    ownedNanoUsd,\n    undecidableBoxes,\n    foreignBoxes: foreignSandboxIds.length,\n    foreignNanoUsd,\n    foreignSandboxIds,\n  }\n\n  return {\n    ok: findings.length === 0,\n    findings,\n    checksRun,\n    rowsExamined: options.rows.length,\n    boxesExamined: byBox.size,\n    settledNanoUsd,\n    creditedNanoUsd,\n    ownership: ownershipSummary,\n    asOf,\n  }\n}\n","import type { SpendFinding, SpendOwnershipSummary, SpendReport } from './types'\n\nconst NANO_PER_USD = 1_000_000_000\n\nfunction usd(nano: number | null): string {\n  return nano === null ? '—' : `$${(nano / NANO_PER_USD).toFixed(2)}`\n}\n\n/**\n * Render a reconciliation for a human deciding whether to open a dispute.\n *\n * Every finding prints its numbers, not a summary of them: the reader's next\n * action is a conversation with the platform about specific reference ids, and a\n * report that made them re-derive the durations would just be re-read alongside\n * the raw rows anyway.\n */\nexport function formatSpendReport(report: SpendReport): string {\n  const lines: string[] = []\n  lines.push(\n    `spend reconciliation — ${report.rowsExamined} row(s), ${report.boxesExamined} box(es), ` +\n      `${usd(report.settledNanoUsd)} charged, ${usd(report.creditedNanoUsd)} credited, ` +\n      `as of ${new Date(report.asOf).toISOString()}`,\n  )\n  lines.push(`checks: ${report.checksRun.join(', ') || '(none)'}`)\n  for (const line of ownershipLines(report.ownership)) lines.push(line)\n\n  if (report.ok) {\n    lines.push('')\n    lines.push('OK — no discrepancy between the product\\'s expectations and the settled ledger.')\n    return lines.join('\\n')\n  }\n\n  lines.push('')\n  lines.push(`${report.findings.length} finding(s):`)\n  for (const finding of report.findings) {\n    lines.push('')\n    lines.push(`  [${finding.check}] ${finding.message}`)\n    for (const [label, value] of measuredFields(finding)) lines.push(`    ${label}: ${value}`)\n    if (finding.referenceIds.length > 0) {\n      lines.push(`    rows: ${finding.referenceIds.join(', ')}`)\n    }\n    lines.push(`    → ${finding.remedy}`)\n  }\n  return lines.join('\\n')\n}\n\n/**\n * What the pass claimed and what it set aside — printed on EVERY report,\n * clean ones included.\n *\n * A clean report that does not say what it looked at is the failure this\n * closes: an over-narrow ownership rule and a genuinely quiet account produce\n * the same \"OK\" line, and only the excluded numbers tell them apart. The\n * excluded box ids are printed in full for the same reason — an exclusion a\n * reader cannot audit is one they have to take on trust.\n */\nfunction ownershipLines(ownership: SpendOwnershipSummary): string[] {\n  if (!ownership.declared) {\n    return [\n      `scope: NOT DECLARED — all ${ownership.ownedBoxes} settled box(es) claimed as this ` +\n        'product\\'s. A sibling product\\'s box on this wallet is reported as unknown-box; pass ' +\n        '`ownership` (see `ownedByBillingKeys`) to tell the two apart.',\n    ]\n  }\n  const lines = [\n    `scope: ${ownership.label} — ${ownership.ownedBoxes} box(es) ${usd(ownership.ownedNanoUsd)} ` +\n      `owned, ${ownership.foreignBoxes} box(es) ${usd(ownership.foreignNanoUsd)} excluded as ` +\n      'another product\\'s',\n  ]\n  if (ownership.undecidableBoxes > 0) {\n    lines.push(\n      `       ${ownership.undecidableBoxes} of the owned box(es) carried no billing-key ` +\n        'attribution and were claimed fail-closed',\n    )\n  }\n  if (ownership.foreignSandboxIds.length > 0) {\n    lines.push(`       excluded: ${ownership.foreignSandboxIds.join(', ')}`)\n  }\n  return lines\n}\n\n/** Every measured field a finding carries, including the ones it left null. */\nfunction measuredFields(finding: SpendFinding): Array<[string, string]> {\n  const ms = (value: number | null): string =>\n    value === null ? '—' : `${(value / 3_600_000).toFixed(2)}h`\n  return [\n    ['sandbox', finding.sandboxId ?? '—'],\n    ['workspace', finding.workspaceId ?? '—'],\n    ['amount', usd(finding.settledNanoUsd)],\n    ['settled', ms(finding.settledMs)],\n    ['ceiling', ms(finding.ceilingMs)],\n    ['overage', ms(finding.overageMs)],\n    ['ceiling basis', finding.ceilingBasis ?? '—'],\n    ['duration basis', finding.durationBasis ?? '—'],\n    ['window', finding.windowStartAt === null ? '—' : new Date(finding.windowStartAt).toISOString()],\n    ['window spend', usd(finding.windowNanoUsd)],\n    ['trailing median', usd(finding.trailingMedianNanoUsd)],\n    ['ratio', finding.velocityRatio === null ? '—' : `${finding.velocityRatio.toFixed(1)}x`],\n    ['balance', usd(finding.balanceNanoUsd)],\n    ['balance floor', usd(finding.balanceFloorNanoUsd)],\n  ]\n}\n\n/** The report as a plain JSON value, for an alerting pipeline. */\nexport function spendReportToJson(report: SpendReport): string {\n  return JSON.stringify(report, null, 2)\n}\n"],"mappings":";AAsTO,IAAM,eAAwC;AAAA,EACnD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;AC3OO,SAAS,mBAAmB,QAA+C;AAChF,QAAM,QAAQ,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,EAAE,OAAO,OAAO,CAAC;AACnE,MAAI,MAAM,SAAS,GAAG;AACpB,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,QAAM,QAAQ,eAAe,CAAC,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC;AAClD,SAAO;AAAA,IACL;AAAA,IACA,OAAO,EAAE,IAAI,GAAG;AACd,YAAM,QAAQ,IAAI,OAAO,KAAK;AAC9B,UAAI,CAAC,MAAO,QAAO;AACnB,aAAO,MAAM,IAAI,KAAK,IAAI,SAAS;AAAA,IACrC;AAAA,EACF;AACF;AAaO,SAAS,mBACd,MACA,WACA,MACuB;AACvB,MAAI,UAAiC;AACrC,aAAW,OAAO,MAAM;AACtB,UAAM,aAAa,KAAK,OAAO,EAAE,KAAK,UAAU,CAAC;AACjD,QAAI,eAAe,OAAQ,QAAO;AAClC,QAAI,eAAe,cAAe,WAAU;AAAA,EAC9C;AACA,SAAO;AACT;;;ACxGO,IAAM,+BAA+B;AAmCrC,SAAS,uBACd,QACA,SACiB;AACjB,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,EAAE,KAAK,IAAI;AAEjB,MAAI;AACJ,MAAI;AAEJ,MAAI,OAAO,cAAc,MAAM;AAC7B,YAAQ;AACR,gBAAY,OAAO;AAAA,EACrB,WAAW,OAAO,cAAc,MAAM;AACpC,YAAQ;AACR,gBAAY,OAAO;AAAA,EACrB,WAAW,OAAO,mBAAmB,SAAS,GAAG;AAG/C,YAAQ;AACR,gBAAY;AAAA,EACd,OAAO;AACL,YAAQ;AACR,gBAAY,OAAO,iBAAiB,OAAO,qBAAqB;AAAA,EAClE;AAKA,MAAI,OAAO,uBAAuB,MAAM;AACtC,UAAM,kBAAkB,OAAO,YAAY,OAAO,qBAAqB;AACvE,QAAI,kBAAkB,WAAW;AAC/B,cAAQ;AACR,kBAAY;AAAA,IACd;AAAA,EACF;AAKA,MAAI,YAAY,KAAM,aAAY;AAGlC,MAAI,YAAY,OAAO,UAAW,aAAY,OAAO;AAErD,SAAO;AAAA,IACL,WAAW,OAAO;AAAA,IAClB;AAAA,IACA;AAAA,IACA,WAAW,YAAY,OAAO,YAAY;AAAA,IAC1C;AAAA,IACA,SAAS,UAAU;AAAA,EACrB;AACF;;;ACvFO,SAAS,yBAAyB,aAAoE;AAC3G,MAAI,CAAC,YAAa,QAAO;AACzB,QAAM,QAAQ,YAAY,MAAM,GAAG;AACnC,MAAI,MAAM,SAAS,KAAK,MAAM,CAAC,MAAM,UAAW,QAAO;AACvD,QAAM,OAAO,MAAM,CAAC;AACpB,MAAI,CAAC,KAAM,QAAO;AAKlB,QAAM,OAAO,MAAM,MAAM,SAAS,CAAC;AACnC,QAAM,SAAS,QAAQ,KAAK,IAAI,IAAI,OAAO,IAAI,IAAI,OAAO;AAC1D,QAAM,YAAY,MAAM,UAAU,KAAK,OAAO,cAAc,MAAM,KAAK,SAAS;AAEhF,QAAM,aAAa,YAAY,MAAM,MAAM,GAAG,EAAE,EAAE,KAAK,GAAG,IAAI,MAAM,MAAM,CAAC,EAAE,KAAK,GAAG;AACrF,MAAI,CAAC,WAAY,QAAO;AAExB,SAAO,EAAE,MAAM,YAAY,iBAAiB,YAAY,SAAS,KAAK;AACxE;AAUO,SAAS,qBAAqB,UAAoD;AACvF,MAAI,CAAC,SAAU,QAAO;AACtB,QAAM,QAAQ,SAAS,MAAM,GAAG;AAChC,MAAI,MAAM,SAAS,KAAK,MAAM,CAAC,MAAM,UAAW,QAAO;AACvD,QAAM,KAAK,MAAM,MAAM,CAAC,EAAE,KAAK,GAAG;AAClC,SAAO,MAAM;AACf;AAWO,SAAS,oBAAoB,KAAmC;AACrE,QAAM,YAAY,yBAAyB,IAAI,WAAW;AAC1D,MAAI,aAAa,UAAU,oBAAoB,KAAM,QAAO,UAAU;AACtE,SAAO,qBAAqB,IAAI,QAAQ,MAAM,YAAY,UAAU,aAAa;AACnF;AAGO,SAAS,SAAS,KAA6B;AACpD,SAAO,IAAI,gBAAgB;AAC7B;AAGO,SAAS,cAAc,KAA4B;AACxD,SAAO,IAAI,gBAAgB,IAAI,CAAC,IAAI,gBAAgB;AACtD;;;AC3DA,IAAM,eAAe;AACrB,IAAM,cAAc;AAyBpB,IAAM,mBAA8C;AAAA,EAClD,UAAU;AAAA,EACV,UAAU;AAAA,EACV,oBAAoB;AAAA,EACpB,oBAAoB;AACtB;AA6DA,SAAS,IAAI,MAAsB;AACjC,SAAO,KAAK,OAAO,cAAc,QAAQ,CAAC,CAAC;AAC7C;AAEA,SAAS,MAAM,IAAoB;AACjC,SAAO,IAAI,KAAK,aAAa,QAAQ,CAAC,CAAC;AACzC;AAGA,IAAM,cAA8C,CAAC,WAAW,kBAAkB,QAAQ,UAAU;AAEpG,SAAS,aAAa,GAAwB,GAA6C;AACzF,SAAO,YAAY,QAAQ,CAAC,KAAK,YAAY,QAAQ,CAAC,IAAI,IAAI;AAChE;AAkBA,SAAS,gBACP,KACA,iBAC4C;AAC5C,MAAI,IAAI,aAAa,KAAM,QAAO,EAAE,IAAI,IAAI,UAAU,OAAO,WAAW;AAExE,QAAM,SAAS,cAAc,GAAG;AAChC,MAAI,oBAAoB,QAAQ,kBAAkB,KAAK,SAAS,GAAG;AACjE,WAAO,EAAE,IAAK,SAAS,kBAAmB,aAAa,OAAO,OAAO;AAAA,EACvE;AAEA,QAAM,YAAY,yBAAyB,IAAI,WAAW;AAC1D,MAAI,WAAW,mBAAmB,QAAQ,IAAI,YAAY,UAAU,iBAAiB;AACnF,WAAO,EAAE,IAAI,IAAI,YAAY,UAAU,iBAAiB,OAAO,iBAAiB;AAAA,EAClF;AAEA,SAAO,EAAE,IAAI,GAAG,OAAO,UAAU;AACnC;AAEA,SAAS,OAAO,QAAmC;AACjD,MAAI,OAAO,WAAW,EAAG,QAAO;AAChC,QAAM,SAAS,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC;AAC/C,QAAM,MAAM,KAAK,MAAM,OAAO,SAAS,CAAC;AACxC,MAAI,OAAO,SAAS,MAAM,EAAG,QAAO,OAAO,GAAG;AAC9C,UAAU,OAAO,MAAM,CAAC,IAAgB,OAAO,GAAG,KAAgB;AACpE;AAUA,SAAS,sBACP,WACA,SACQ;AACR,MAAI,CAAC,WAAW;AACd,WACE;AAAA,EAGJ;AACA,MAAI,YAAY,eAAe;AAC7B,WACE,wBAAwB,UAAU,KAAK;AAAA,EAG3C;AACA,SAAO,wBAAwB,UAAU,KAAK;AAChD;AAEA,SAAS,iBACP,WACA,SACA,WACQ;AACR,QAAM,SAAS,WAAW,SAAS;AACnC,MAAI,CAAC,WAAW;AACd,WACE,iWAG4E,MAAM;AAAA,EAEtF;AACA,MAAI,YAAY,eAAe;AAC7B,WACE,uNAEqC,MAAM;AAAA,EAE/C;AACA,SACE,0LAEG,MAAM;AAEb;AAEA,SAAS,aAAa,OAA+D;AACnF,SAAO;AAAA,IACL;AAAA,IACA,WAAW;AAAA,IACX,aAAa;AAAA,IACb,cAAc,CAAC;AAAA,IACf,gBAAgB;AAAA,IAChB,WAAW;AAAA,IACX,eAAe;AAAA,IACf,WAAW;AAAA,IACX,WAAW;AAAA,IACX,cAAc;AAAA,IACd,eAAe;AAAA,IACf,uBAAuB;AAAA,IACvB,eAAe;AAAA,IACf,eAAe;AAAA,IACf,gBAAgB;AAAA,IAChB,qBAAqB;AAAA,EACvB;AACF;AASA,eAAsB,eAAe,SAAsD;AACzF,QAAM,OAAO,QAAQ,QAAQ,KAAK,IAAI;AACtC,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,OAAO,IAAI,IAAI,QAAQ,QAAQ,CAAC,CAAC;AACvC,QAAM,YAAY,aAAa,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,KAAK,CAAC;AACjE,QAAM,OAAO,CAAC,UAAiC,CAAC,KAAK,IAAI,KAAK;AAE9D,QAAM,YAAY,QAAQ,aAAa;AAEvC,QAAM,WAA2B,CAAC;AAClC,MAAI,iBAAiB;AACrB,MAAI,kBAAkB;AACtB,MAAI,aAAa;AACjB,MAAI,eAAe;AACnB,MAAI,mBAAmB;AACvB,MAAI,iBAAiB;AACrB,QAAM,oBAA8B,CAAC;AAGrC,QAAM,QAAQ,oBAAI,IAA6B;AAC/C,aAAW,OAAO,QAAQ,MAAM;AAC9B,QAAI,IAAI,gBAAgB,EAAG,mBAAkB,CAAC,IAAI;AAAA,QAC7C,oBAAmB,IAAI;AAC5B,QAAI,IAAI,iBAAiB,EAAG;AAC5B,UAAM,YAAY,oBAAoB,GAAG;AACzC,QAAI,CAAC,UAAW;AAChB,UAAM,SAAS,MAAM,IAAI,SAAS;AAClC,QAAI,OAAQ,QAAO,KAAK,GAAG;AAAA,QACtB,OAAM,IAAI,WAAW,CAAC,GAAG,CAAC;AAAA,EACjC;AAEA,QAAM,SAAS,CAAC,QAA+B,cAAqC;AAClF,UAAM,OAAO,QAAQ;AACrB,QAAI,SAAS,OAAW,QAAO;AAC/B,QAAI,OAAO,SAAS,SAAU,QAAO;AACrC,WAAO,KAAK,QAAQ,SAAS,KAAK;AAAA,EACpC;AAEA,aAAW,CAAC,WAAW,IAAI,KAAK,OAAO;AACrC,UAAM,SAAS,MAAM,QAAQ,MAAM,KAAK,SAAS;AACjD,UAAM,eAAe,KAAK,IAAI,CAAC,QAAQ,IAAI,eAAe,IAAI,EAAE;AAChE,UAAM,UAAU,KAAK,OAAO,CAAC,KAAK,QAAQ,MAAM,cAAc,GAAG,GAAG,CAAC;AAOrE,UAAM,UAAiC,SACnC,SACA,YACE,mBAAmB,WAAW,WAAW,IAAI,IAC7C;AAEN,QAAI,YAAY,WAAW;AACzB,wBAAkB,KAAK,SAAS;AAChC,wBAAkB;AAClB;AAAA,IACF;AACA,kBAAc;AACd,oBAAgB;AAChB,QAAI,YAAY,cAAe,qBAAoB;AAGnD,QAAI,CAAC,QAAQ;AACX,UAAI,KAAK,aAAa,GAAG;AACvB,iBAAS,KAAK;AAAA,UACZ,GAAG,aAAa,aAAa;AAAA,UAC7B;AAAA,UACA;AAAA,UACA;AAAA,UACA,gBAAgB;AAAA,UAChB,SACE,GAAG,IAAI,OAAO,CAAC,mBAAmB,KAAK,MAAM,2BAA2B,SAAS,2DAEjF,sBAAsB,WAAW,OAAO;AAAA,UAC1C,QAAQ,iBAAiB,WAAW,SAAS,SAAS;AAAA,QACxD,CAAC;AAAA,MACH;AACA;AAAA,IACF;AAGA,QAAI,CAAC,KAAK,cAAc,EAAG;AAE3B,UAAM,UAAU,uBAAuB,QAAQ,EAAE,MAAM,YAAY,CAAC;AACpE,UAAM,kBAAkB,OAAO,QAAQ,SAAS;AAEhD,QAAI,YAAY;AAChB,QAAI,QAA6B;AACjC,QAAI,cAAc;AAClB,eAAW,OAAO,MAAM;AACtB,YAAM,WAAW,gBAAgB,KAAK,eAAe;AACrD,UAAI,SAAS,UAAU,WAAW;AAChC,gBAAQ,aAAa,OAAO,SAAS;AACrC;AAAA,MACF;AACA,oBAAc;AACd,mBAAa,SAAS;AACtB,cAAQ,aAAa,OAAO,SAAS,KAAK;AAAA,IAC5C;AACA,QAAI,CAAC,YAAa;AAClB,QAAI,aAAa,QAAQ,UAAW;AAEpC,UAAM,YAAY,YAAY,QAAQ;AACtC,UAAM,aAAa,QAAQ,UACvB,KACA;AAGJ,UAAM,aACJ,UAAU,mBACN,8KAEA;AAEN,aAAS,KAAK;AAAA,MACZ,GAAG,aAAa,cAAc;AAAA,MAC9B;AAAA,MACA,aAAa,OAAO,eAAe;AAAA,MACnC;AAAA,MACA,gBAAgB;AAAA,MAChB;AAAA,MACA,eAAe;AAAA,MACf,WAAW,QAAQ;AAAA,MACnB;AAAA,MACA,cAAc,QAAQ;AAAA,MACtB,SACE,WAAW,SAAS,YAAY,MAAM,SAAS,CAAC,KAAK,IAAI,OAAO,CAAC,YAAY,KAAK,MAAM,2CAC9C,MAAM,QAAQ,SAAS,CAAC,mBAC/D,MAAM,SAAS,CAAC,oBAAoB,QAAQ,KAAK,qBAAqB,KAAK,MAC9E,aACA;AAAA,MACF,QACE,WAAW,aAAa,KAAK,IAAI,CAAC,sDACjC,QAAQ,UAAU,aAAa,QAAQ,UAAU,YAC9C,wKAEA;AAAA,IAER,CAAC;AAAA,EACH;AAGA,MAAI,KAAK,UAAU,KAAK,QAAQ,aAAa,OAAO;AAClD,UAAM,MAAM,EAAE,GAAG,kBAAkB,GAAI,QAAQ,YAAY,CAAC,EAAG;AAC/D,UAAM,UAAU,oBAAI,IAAoD;AACxE,eAAW,OAAO,QAAQ,MAAM;AAC9B,YAAM,SAAS,cAAc,GAAG;AAChC,UAAI,WAAW,EAAG;AAMlB,UAAI,aAAa,UAAU,OAAO,EAAE,KAAK,WAAW,oBAAoB,GAAG,EAAE,CAAC,MAAM,WAAW;AAC7F;AAAA,MACF;AACA,YAAM,cAAc,KAAK,MAAM,IAAI,YAAY,IAAI,QAAQ,IAAI,IAAI;AACnE,YAAM,SAAS,QAAQ,IAAI,WAAW;AACtC,UAAI,QAAQ;AACV,eAAO,QAAQ;AACf,eAAO,WAAW,KAAK,IAAI,eAAe,IAAI,EAAE;AAAA,MAClD,OAAO;AACL,gBAAQ,IAAI,aAAa,EAAE,MAAM,QAAQ,YAAY,CAAC,IAAI,eAAe,IAAI,EAAE,EAAE,CAAC;AAAA,MACpF;AAAA,IACF;AAEA,UAAM,UAAU,CAAC,GAAG,QAAQ,QAAQ,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;AACjE,aAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;AACvC,YAAM,QAAQ,QAAQ,CAAC;AACvB,UAAI,CAAC,MAAO;AACZ,YAAM,CAAC,eAAe,MAAM,IAAI;AAChC,UAAI,IAAI,IAAI,mBAAoB;AAChC,YAAM,WAAW,QAAQ,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,MAAM,MAAM,IAAI;AAClE,YAAM,iBAAiB,OAAO,QAAQ;AACtC,YAAM,YAAY,KAAK,IAAI,iBAAiB,IAAI,UAAU,IAAI,kBAAkB;AAChF,UAAI,OAAO,QAAQ,UAAW;AAC9B,YAAM,QAAQ,iBAAiB,IAAI,OAAO,OAAO,iBAAiB,OAAO;AAEzE,eAAS,KAAK;AAAA,QACZ,GAAG,aAAa,UAAU;AAAA,QAC1B;AAAA,QACA,cAAc,OAAO;AAAA,QACrB,gBAAgB,OAAO;AAAA,QACvB,eAAe,OAAO;AAAA,QACtB,uBAAuB;AAAA,QACvB,eAAe;AAAA,QACf;AAAA,QACA,SACE,GAAG,IAAI,OAAO,IAAI,CAAC,mCAAmC,IAAI,KAAK,aAAa,EAAE,YAAY,CAAC,WACjF,OAAO,WAAW,MAAM,yCAC/B,IAAI,cAAc,CAAC,SAAS,SAAS,MAAM,2BAC3C,OAAO,SAAS,KAAK,IAAI,GAAG,MAAM,QAAQ,CAAC,CAAC,MAAM,mCAAmC,cAC5E,IAAI,QAAQ,kBACvB,YACG,+CAA+C,UAAU,KAAK,yFAE9D;AAAA,QAEN,QACE;AAAA,MAGJ,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,KAAK,kBAAkB,KAAK,QAAQ,SAAS;AAC/C,UAAM,QAAQ,QAAQ,QAAQ,gBAAgB;AAC9C,QAAI,QAAQ,QAAQ,UAAU,OAAO;AACnC,eAAS,KAAK;AAAA,QACZ,GAAG,aAAa,kBAAkB;AAAA,QAClC;AAAA,QACA,gBAAgB,KAAK,IAAI,GAAG,QAAQ,QAAQ,QAAQ,OAAO;AAAA,QAC3D,gBAAgB,QAAQ,QAAQ;AAAA,QAChC,qBAAqB;AAAA,QACrB,SACE,oBAAoB,IAAI,QAAQ,QAAQ,OAAO,CAAC,uBAAuB,IAAI,KAAK,CAAC;AAAA,QACnF,QACE;AAAA,MAEJ,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,mBAA0C;AAAA,IAC9C,UAAU,cAAc;AAAA,IACxB,OAAO,WAAW,SAAS;AAAA,IAC3B;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc,kBAAkB;AAAA,IAChC;AAAA,IACA;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAI,SAAS,WAAW;AAAA,IACxB;AAAA,IACA;AAAA,IACA,cAAc,QAAQ,KAAK;AAAA,IAC3B,eAAe,MAAM;AAAA,IACrB;AAAA,IACA;AAAA,IACA,WAAW;AAAA,IACX;AAAA,EACF;AACF;;;ACpfA,IAAMA,gBAAe;AAErB,SAASC,KAAI,MAA6B;AACxC,SAAO,SAAS,OAAO,WAAM,KAAK,OAAOD,eAAc,QAAQ,CAAC,CAAC;AACnE;AAUO,SAAS,kBAAkB,QAA6B;AAC7D,QAAM,QAAkB,CAAC;AACzB,QAAM;AAAA,IACJ,+BAA0B,OAAO,YAAY,YAAY,OAAO,aAAa,aACxEC,KAAI,OAAO,cAAc,CAAC,aAAaA,KAAI,OAAO,eAAe,CAAC,oBAC5D,IAAI,KAAK,OAAO,IAAI,EAAE,YAAY,CAAC;AAAA,EAChD;AACA,QAAM,KAAK,WAAW,OAAO,UAAU,KAAK,IAAI,KAAK,QAAQ,EAAE;AAC/D,aAAW,QAAQ,eAAe,OAAO,SAAS,EAAG,OAAM,KAAK,IAAI;AAEpE,MAAI,OAAO,IAAI;AACb,UAAM,KAAK,EAAE;AACb,UAAM,KAAK,qFAAiF;AAC5F,WAAO,MAAM,KAAK,IAAI;AAAA,EACxB;AAEA,QAAM,KAAK,EAAE;AACb,QAAM,KAAK,GAAG,OAAO,SAAS,MAAM,cAAc;AAClD,aAAW,WAAW,OAAO,UAAU;AACrC,UAAM,KAAK,EAAE;AACb,UAAM,KAAK,MAAM,QAAQ,KAAK,KAAK,QAAQ,OAAO,EAAE;AACpD,eAAW,CAAC,OAAO,KAAK,KAAK,eAAe,OAAO,EAAG,OAAM,KAAK,OAAO,KAAK,KAAK,KAAK,EAAE;AACzF,QAAI,QAAQ,aAAa,SAAS,GAAG;AACnC,YAAM,KAAK,aAAa,QAAQ,aAAa,KAAK,IAAI,CAAC,EAAE;AAAA,IAC3D;AACA,UAAM,KAAK,cAAS,QAAQ,MAAM,EAAE;AAAA,EACtC;AACA,SAAO,MAAM,KAAK,IAAI;AACxB;AAYA,SAAS,eAAe,WAA4C;AAClE,MAAI,CAAC,UAAU,UAAU;AACvB,WAAO;AAAA,MACL,kCAA6B,UAAU,UAAU;AAAA,IAGnD;AAAA,EACF;AACA,QAAM,QAAQ;AAAA,IACZ,UAAU,UAAU,KAAK,WAAM,UAAU,UAAU,YAAYA,KAAI,UAAU,YAAY,CAAC,WAC9E,UAAU,YAAY,YAAYA,KAAI,UAAU,cAAc,CAAC;AAAA,EAE7E;AACA,MAAI,UAAU,mBAAmB,GAAG;AAClC,UAAM;AAAA,MACJ,UAAU,UAAU,gBAAgB;AAAA,IAEtC;AAAA,EACF;AACA,MAAI,UAAU,kBAAkB,SAAS,GAAG;AAC1C,UAAM,KAAK,oBAAoB,UAAU,kBAAkB,KAAK,IAAI,CAAC,EAAE;AAAA,EACzE;AACA,SAAO;AACT;AAGA,SAAS,eAAe,SAAgD;AACtE,QAAM,KAAK,CAAC,UACV,UAAU,OAAO,WAAM,IAAI,QAAQ,MAAW,QAAQ,CAAC,CAAC;AAC1D,SAAO;AAAA,IACL,CAAC,WAAW,QAAQ,aAAa,QAAG;AAAA,IACpC,CAAC,aAAa,QAAQ,eAAe,QAAG;AAAA,IACxC,CAAC,UAAUA,KAAI,QAAQ,cAAc,CAAC;AAAA,IACtC,CAAC,WAAW,GAAG,QAAQ,SAAS,CAAC;AAAA,IACjC,CAAC,WAAW,GAAG,QAAQ,SAAS,CAAC;AAAA,IACjC,CAAC,WAAW,GAAG,QAAQ,SAAS,CAAC;AAAA,IACjC,CAAC,iBAAiB,QAAQ,gBAAgB,QAAG;AAAA,IAC7C,CAAC,kBAAkB,QAAQ,iBAAiB,QAAG;AAAA,IAC/C,CAAC,UAAU,QAAQ,kBAAkB,OAAO,WAAM,IAAI,KAAK,QAAQ,aAAa,EAAE,YAAY,CAAC;AAAA,IAC/F,CAAC,gBAAgBA,KAAI,QAAQ,aAAa,CAAC;AAAA,IAC3C,CAAC,mBAAmBA,KAAI,QAAQ,qBAAqB,CAAC;AAAA,IACtD,CAAC,SAAS,QAAQ,kBAAkB,OAAO,WAAM,GAAG,QAAQ,cAAc,QAAQ,CAAC,CAAC,GAAG;AAAA,IACvF,CAAC,WAAWA,KAAI,QAAQ,cAAc,CAAC;AAAA,IACvC,CAAC,iBAAiBA,KAAI,QAAQ,mBAAmB,CAAC;AAAA,EACpD;AACF;AAGO,SAAS,kBAAkB,QAA6B;AAC7D,SAAO,KAAK,UAAU,QAAQ,MAAM,CAAC;AACvC;","names":["NANO_PER_USD","usd"]}

package/dist/spend/cli.js

@@ -3,7 +3,7 @@ import {
   formatSpendReport,
   reconcileSpend,
   spendReportToJson
-} from "../chunk-NEJ7OMQS.js";
+} from "../chunk-5LC2VXH5.js";
 
 // src/spend/cli-args.ts
 import { pathToFileURL } from "url";

package/dist/spend/index.d.ts

@@ -119,9 +119,11 @@ interface ExpectedCeiling {
  * reaches for them, because the ledger is the counterparty's record and reading
  * it is the product's authenticated business.
  *
- * The product's fetch MUST scope rows to boxes it owns. Products bill to a
- * shared company key, so an unscoped fetch returns every sibling product's
- * settlements and every one of them is a correct `unknown-box` finding.
+ * The rows a product can fetch are scoped to the BILLING OWNER, not to the
+ * product: `product: 'sandbox'` is the platform's service taxonomy and every
+ * consumer app's compute wears it. So a wallet running two of our products
+ * returns both products' settlements, and telling them apart is
+ * {@link SpendOwnershipRule}'s job.
  */
 interface SettlementRow {
     /** The ledger row id, for the dispute. */
@@ -152,6 +154,103 @@ interface SettlementRow {
      * Null is the common case: the platform does not store duration on the row.
      */
     readonly billedMs: number | null;
+    /**
+     * The platform API key the charge was triggered by — `credit_transactions.key_id`,
+     * stamped from the box's own creation metadata at settlement time and exposed
+     * by `/v1/billing/transactions` (which also filters on it).
+     *
+     * This is the ONLY field on a settlement row that can be attributed back to a
+     * PRODUCT rather than to a wallet or to the platform's service taxonomy, which
+     * is why {@link SpendOwnershipRule}'s shipped constructor is built on it. The
+     * sandbox id cannot do the job: the platform mints it as `sandbox-<12 hex>`
+     * from a hash of (owner, idempotency key), so a product's own box naming never
+     * reaches the ledger row.
+     *
+     * Optional, and `null` is a real answer: the platform leaves it null on legacy
+     * rows and an export may not carry the column at all. A missing key is
+     * `undecidable`, never `foreign` — see {@link SpendOwnershipVerdict}.
+     */
+    readonly keyId?: string | null;
+}
+/**
+ * What one settlement is attributable to, from inside ONE product.
+ *
+ * The distinction this type exists for: a sibling product's box and a charge
+ * that is not ours at all look identical from inside a single product, because
+ * both arrive as a settlement naming a sandbox this product's expectation ledger
+ * has never heard of. Dropping both loses the check's whole purpose; reporting
+ * both makes it noise. Only a platform-stamped attribution field separates them.
+ */
+type SpendOwnershipVerdict = 
+/** Attributable to THIS product. An unrecorded one is a phantom-charge candidate. */
+'mine'
+/** Attributable to a DIFFERENT product on the same wallet. Reported, never a finding. */
+ | 'foreign'
+/**
+ * The row carries nothing that decides it. Counted as `mine` — FAIL CLOSED.
+ * An unattributable charge on a shared wallet is precisely the shape of the
+ * thing this module exists to catch, so the ambiguous case costs a human five
+ * minutes rather than costing the product the detection.
+ */
+ | 'undecidable';
+/** One settlement, presented to an ownership rule. */
+interface SpendOwnershipCandidate {
+    readonly row: SettlementRow;
+    /** The sandbox the row is attributable to, or null for a row naming none. */
+    readonly sandboxId: string | null;
+}
+/**
+ * The product's declaration of which settlements are its own.
+ *
+ * The one hard constraint on `decide`: it must answer from PROPERTIES OF THE
+ * ROW. A rule that answers by looking the sandbox up in the product's own
+ * expectation ledger deletes `unknown-box` entirely — every unrecorded box would
+ * be `foreign` by construction, and "we were billed for a box we never asked
+ * for" would become unrepresentable. The ledger already decides recorded-ness;
+ * this decides ATTRIBUTION, and the two must stay independent.
+ *
+ * `decide` must not throw. If it does, the throw propagates and the whole pass
+ * fails — a reconciliation whose ownership rule is broken has no verdict worth
+ * printing, and swallowing it would turn a broken rule into a clean bill.
+ */
+interface SpendOwnershipRule {
+    /** Named in the report and on every finding, so a reader knows what was excluded. */
+    readonly label: string;
+    decide(candidate: SpendOwnershipCandidate): SpendOwnershipVerdict;
+}
+/**
+ * What this pass scoped itself to — present on every report, including a clean
+ * one, because "nothing fired" and "nothing was looked at" are different
+ * answers and a report that cannot tell them apart is the failure this closes.
+ */
+interface SpendOwnershipSummary {
+    /**
+     * False when the caller declared no rule. The pass then treats every box as
+     * its own — today's behaviour, which over-reports rather than under-reports —
+     * and every `unknown-box` finding says on its face that a sibling product's
+     * box is indistinguishable from a charge that is not ours.
+     */
+    readonly declared: boolean;
+    /** The rule's label, or null when none was declared. */
+    readonly label: string | null;
+    /** Boxes this pass treated as this product's, and what they were charged. */
+    readonly ownedBoxes: number;
+    readonly ownedNanoUsd: number;
+    /**
+     * Of those, the boxes no rule could decide. Counted as owned (fail-closed) and
+     * reported separately so a product can see how much of its own verdict rests
+     * on rows that carried no attribution.
+     */
+    readonly undecidableBoxes: number;
+    /** Boxes attributed to another product on the same wallet. Never findings. */
+    readonly foreignBoxes: number;
+    readonly foreignNanoUsd: number;
+    /**
+     * Their ids, in full — an exclusion a reader cannot audit is an exclusion
+     * they have to trust, and this module's whole posture is that nothing about
+     * money is taken on trust.
+     */
+    readonly foreignSandboxIds: readonly string[];
 }
 /** The parts of a settlement reference id, once parsed. */
 interface SettlementReference {
@@ -236,10 +335,99 @@ interface SpendReport {
     readonly settledNanoUsd: number;
     /** Total credited back across every examined row, unsigned nanodollars. */
     readonly creditedNanoUsd: number;
+    /** What this pass claimed as its own, and what it excluded as another product's. */
+    readonly ownership: SpendOwnershipSummary;
     /** The instant the pass treated as "now". */
     readonly asOf: number;
 }
 
+/**
+ * Which settlements belong to the product running the reconciliation.
+ *
+ * ## The problem this module is the answer to
+ *
+ * A product fetches its settled rows from `/v1/billing/transactions`, scoped to
+ * the BILLING OWNER — the wallet whose key paid. `product: 'sandbox'` narrows
+ * that to compute, but `sandbox` is the PLATFORM's service taxonomy: every
+ * consumer app's box compute wears it. So a Tangle account running two of our
+ * products hands each product's reconciliation the other product's boxes, and
+ * `unknown-box` — correctly, by its own rule — reports one finding per sibling
+ * box. Two products on one wallet make each other's spend check useless.
+ *
+ * ## Why the obvious fix is the wrong fix
+ *
+ * The obvious fix is to reconcile only the boxes already in the product's
+ * expectation ledger. That removes the false findings and removes the check:
+ * `unknown-box` exists to catch "we were billed for a box we never asked for",
+ * which is the 2026-08-05 incident's day-one signature and the ONLY thing a
+ * product with no lifecycle bookkeeping can catch at all. Filtering to the
+ * ledger makes a phantom charge unrepresentable — the ledger's own contents
+ * would define the answer.
+ *
+ * So the residue — settlements against boxes with no ledger record — has to be
+ * SPLIT, not dropped. A sibling's box and a phantom charge are indistinguishable
+ * unless something outside the product's own bookkeeping tells them apart.
+ *
+ * ## What can tell them apart
+ *
+ * Exactly one field on a settlement row, and it is not the sandbox id. The
+ * platform mints that id as `sandbox-<12 hex>` — a hash of (owner, idempotency
+ * key) — so a product's own box naming never reaches the ledger row, and the
+ * charge's `description` carries only the resource spec. What does survive is
+ * `credit_transactions.key_id`: the platform API key the box was created under,
+ * stamped from the box's own creation metadata at settlement and filterable on
+ * the transactions endpoint. Each product deploys with its own key, so the key
+ * is the product's billing identity as the PLATFORM recorded it — not as the
+ * product asserts it after the fact.
+ *
+ * That asymmetry is what makes the split safe. A product cannot widen its own
+ * claim by claiming; it can only recognise a stamp the platform already wrote.
+ *
+ * ## The three rules that keep the detection intact
+ *
+ * 1. **A recorded box is never excluded.** Ownership is consulted only for
+ *    boxes with no ledger record. A rule that is wrong or over-narrow therefore
+ *    cannot hide an `over-ceiling` finding on a box the product recorded — the
+ *    incident's own 23 findings survive any rule at all.
+ * 2. **Undecidable fails closed.** A row with no key attribution is `mine`, so
+ *    an unattributable charge on a shared wallet is reported. Silence is never
+ *    the answer to "I don't know."
+ * 3. **A box is claimed if ANY of its rows claims it.** The fold is
+ *    `mine > undecidable > foreign`, which is the module's standing asymmetry:
+ *    every derivation error pushes toward a false alarm, never toward a missed
+ *    charge.
+ */
+/**
+ * Claim every settlement the platform stamped with one of these API keys.
+ *
+ * The shipped rule, because it is the only one built on a field the PLATFORM
+ * writes. Give each product its own platform key and this separates them
+ * exactly; give two products the same key and no consumer-side rule can tell
+ * them apart, because after settlement there is nothing left that differs — the
+ * fix then is a second key, not a cleverer predicate.
+ *
+ * A row with no `keyId` (a legacy row, or an export that drops the column) is
+ * `undecidable`, never `foreign`: the absence of an attribution is not evidence
+ * that the charge is someone else's.
+ *
+ * @param keyIds The product's own platform API key ids. Must be non-empty — a
+ *   rule that owns nothing would classify every settlement as another product's
+ *   and report a clean bill for an account nobody is checking.
+ */
+declare function ownedByBillingKeys(keyIds: readonly string[]): SpendOwnershipRule;
+/**
+ * One box's verdict, folded over every row that settled against it.
+ *
+ * `mine` wins over `undecidable`, which wins over `foreign`: it takes one row
+ * attributable to this product to make the box this product's problem, and one
+ * unattributable row to stop the box being excluded. Both directions push
+ * toward reporting, which is the only direction that cannot lose money.
+ *
+ * Exported because a product auditing its own scoping wants the same answer the
+ * reconciler reached, not a re-derivation of it.
+ */
+declare function decideBoxOwnership(rule: SpendOwnershipRule, sandboxId: string, rows: readonly SettlementRow[]): SpendOwnershipVerdict;
+
 /**
  * Persistence seam for the expectation ledger — the product implements it over
  * its own tables.
@@ -471,13 +659,30 @@ interface ReconcileSpendOptions {
     /**
      * Settled ledger rows, supplied by the product's own authenticated fetch.
      *
-     * MUST be scoped to boxes this product owns. Products bill to a shared company
-     * key, so an unscoped fetch returns every sibling product's settlements and
-     * every one is a correct — and useless — `unknown-box` finding.
+     * The fetch can only scope to a WALLET — `product: 'sandbox'` is the
+     * platform's service taxonomy, not this product's — so on an account running
+     * more than one of our products these rows carry the siblings' boxes too.
+     * {@link ReconcileSpendOptions.ownership} is what separates them.
      */
     readonly rows: readonly SettlementRow[];
     /** The product's expectation ledger. */
     readonly store: SpendLedgerStorePort;
+    /**
+     * Which of those rows are THIS product's — see {@link SpendOwnershipRule} and
+     * the shipped `ownedByBillingKeys`.
+     *
+     * Omitting it is safe and changes nothing: the pass claims every box, which is
+     * the behaviour that shipped, and the direction that over-reports rather than
+     * under-reports. It is not silent about it — `report.ownership.declared` is
+     * `false`, `formatSpendReport` says so above the findings, and every
+     * `unknown-box` finding states on its face that a sibling product's box is
+     * indistinguishable from a charge that is not ours.
+     *
+     * Declaring it never weakens the ledger-backed checks: ownership is consulted
+     * ONLY for boxes with no expectation record, so `over-ceiling` on a recorded
+     * box fires whatever the rule says.
+     */
+    readonly ownership?: SpendOwnershipRule;
     /** Treated as "now". Default `Date.now()`. */
     readonly asOf?: number;
     /** Ceiling slack. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */
@@ -637,4 +842,4 @@ declare function formatSpendReport(report: SpendReport): string;
 /** The report as a plain JSON value, for an alerting pipeline. */
 declare function spendReportToJson(report: SpendReport): string;
 
-export { type BilledDurationBasis, type BoxRateResolver, type CeilingBasis, type ComputeBudget, ComputeBudgetExceededError, type ComputeBudgetRefusal, type ComputeExpectedCeilingOptions, DEFAULT_CEILING_TOLERANCE_MS, type ExpectedCeiling, type InMemorySpendLedgerStore, type ObserveSandboxInput, type ObservedBalance, type ReconcileSpendOptions, SPEND_CHECKS, type SandboxSpendHooksOptions, type SandboxSpendSeam, type SettlementReference, type SettlementRow, type SpendBoxPatch, type SpendBoxRecord, type SpendCheckId, type SpendFinding, type SpendLedger, type SpendLedgerOptions, type SpendLedgerStorePort, type SpendProvisionObservation, type SpendReport, type VelocityOptions, assertComputeBudget, chargeNanoUsd, computeExpectedCeiling, createInMemorySpendLedgerStore, createSandboxSpendHooks, createSpendLedger, foldSpendBoxRecord, formatSpendReport, isCharge, parseSandboxGroupKey, parseSettlementReference, reconcileSpend, settlementSandboxId, spendReportToJson };
+export { type BilledDurationBasis, type BoxRateResolver, type CeilingBasis, type ComputeBudget, ComputeBudgetExceededError, type ComputeBudgetRefusal, type ComputeExpectedCeilingOptions, DEFAULT_CEILING_TOLERANCE_MS, type ExpectedCeiling, type InMemorySpendLedgerStore, type ObserveSandboxInput, type ObservedBalance, type ReconcileSpendOptions, SPEND_CHECKS, type SandboxSpendHooksOptions, type SandboxSpendSeam, type SettlementReference, type SettlementRow, type SpendBoxPatch, type SpendBoxRecord, type SpendCheckId, type SpendFinding, type SpendLedger, type SpendLedgerOptions, type SpendLedgerStorePort, type SpendOwnershipCandidate, type SpendOwnershipRule, type SpendOwnershipSummary, type SpendOwnershipVerdict, type SpendProvisionObservation, type SpendReport, type VelocityOptions, assertComputeBudget, chargeNanoUsd, computeExpectedCeiling, createInMemorySpendLedgerStore, createSandboxSpendHooks, createSpendLedger, decideBoxOwnership, foldSpendBoxRecord, formatSpendReport, isCharge, ownedByBillingKeys, parseSandboxGroupKey, parseSettlementReference, reconcileSpend, settlementSandboxId, spendReportToJson };

package/dist/spend/index.js

@@ -3,14 +3,16 @@ import {
   SPEND_CHECKS,
   chargeNanoUsd,
   computeExpectedCeiling,
+  decideBoxOwnership,
   formatSpendReport,
   isCharge,
+  ownedByBillingKeys,
   parseSandboxGroupKey,
   parseSettlementReference,
   reconcileSpend,
   settlementSandboxId,
   spendReportToJson
-} from "../chunk-NEJ7OMQS.js";
+} from "../chunk-5LC2VXH5.js";
 
 // src/spend/store.ts
 function foldSpendBoxRecord(record, patch) {
@@ -184,9 +186,11 @@ export {
   createInMemorySpendLedgerStore,
   createSandboxSpendHooks,
   createSpendLedger,
+  decideBoxOwnership,
   foldSpendBoxRecord,
   formatSpendReport,
   isCharge,
+  ownedByBillingKeys,
   parseSandboxGroupKey,
   parseSettlementReference,
   reconcileSpend,

package/dist/spend/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/spend/store.ts","../../src/spend/budget.ts"],"sourcesContent":["import type { SpendBoxPatch, SpendBoxRecord } from './types'\n\n/**\n * Persistence seam for the expectation ledger — the product implements it over\n * its own tables.\n *\n * Deliberately NOT compare-and-set, unlike `MissionStorePort`. A mission has one\n * serialized owner and a lost write corrupts a state machine; a box record is a\n * MONOTONIC FOLD (activity takes a max, a detached-run id joins or leaves a set,\n * delete is set-once) so concurrent writers converge no matter what order they\n * land in. The worst a lost race can do here is leave `lastActivityAt` behind\n * the truth — which makes the derived ceiling TIGHTER, so the failure mode is a\n * false alarm a human dismisses, never a missed charge. That asymmetry is the\n * whole reason the fold is shaped this way.\n *\n * `update` returns null when the row does not exist, never a throw.\n */\nexport interface SpendLedgerStorePort {\n  load(sandboxId: string): Promise<SpendBoxRecord | null>\n  /** `extras` are the opaque product-column values — write them in the SAME\n   *  statement as the record, or ignore them if the table has no extra columns. */\n  insert(record: SpendBoxRecord, extras?: Record<string, unknown>): Promise<SpendBoxRecord>\n  update(sandboxId: string, patch: SpendBoxPatch): Promise<SpendBoxRecord | null>\n}\n\n/**\n * Apply one fold step. Exported so a SQL implementation and an in-memory one\n * reach the same record, and so a product can unit-test its own store against\n * the canonical answer.\n *\n * The two rules worth stating out loud:\n *\n * - `observedActivityAt` only ever moves `lastActivityAt` FORWARD. A replayed\n *   or out-of-order event cannot rewind the ceiling.\n * - activity later than a recorded `stoppedAt` CLEARS the stop. A box that\n *   worked after the product thought it stopped is running again, and keeping\n *   the stale stop would make the ceiling too tight — inventing an over-ceiling\n *   finding out of the product's own bookkeeping rather than the platform's.\n */\nexport function foldSpendBoxRecord(record: SpendBoxRecord, patch: SpendBoxPatch): SpendBoxRecord {\n  let lastActivityAt = record.lastActivityAt\n  let stoppedAt = record.stoppedAt\n  let openDetachedRunIds = record.openDetachedRunIds\n\n  if (patch.observedActivityAt !== undefined) {\n    lastActivityAt = Math.max(lastActivityAt, patch.observedActivityAt)\n    if (stoppedAt !== null && patch.observedActivityAt > stoppedAt) stoppedAt = null\n  }\n  if (patch.openDetachedRunAdd !== undefined && !openDetachedRunIds.includes(patch.openDetachedRunAdd)) {\n    openDetachedRunIds = [...openDetachedRunIds, patch.openDetachedRunAdd]\n  }\n  if (patch.openDetachedRunRemove !== undefined) {\n    openDetachedRunIds = openDetachedRunIds.filter((id) => id !== patch.openDetachedRunRemove)\n  }\n  if (patch.stoppedAt !== undefined) {\n    // Latest-wins, but never behind observed activity: a stop we are told about\n    // that predates work we watched is not the stop that closed this box.\n    stoppedAt = patch.stoppedAt >= lastActivityAt ? patch.stoppedAt : stoppedAt\n  }\n\n  return {\n    ...record,\n    lastActivityAt,\n    stoppedAt,\n    openDetachedRunIds,\n    // Set-once: a deleted sandbox id never comes back, so a second observation\n    // is a duplicate delivery, not a second deletion.\n    deletedAt: record.deletedAt ?? patch.deletedAt ?? null,\n  }\n}\n\n/** An in-memory store that also lets a test inspect and force state. */\nexport interface InMemorySpendLedgerStore extends SpendLedgerStorePort {\n  /** Every record, insertion order. */\n  records(): SpendBoxRecord[]\n  /** Unguarded direct write — simulates a crash-shaped or platform-seeded row. */\n  put(record: SpendBoxRecord): void\n}\n\n/** Create an in-memory expectation ledger. Production writers use the same port. */\nexport function createInMemorySpendLedgerStore(): InMemorySpendLedgerStore {\n  const rows = new Map<string, SpendBoxRecord>()\n  return {\n    async load(sandboxId) {\n      const row = rows.get(sandboxId)\n      return row ? structuredClone(row) : null\n    },\n    async insert(record) {\n      const stored = structuredClone(record)\n      rows.set(record.sandboxId, stored)\n      return structuredClone(stored)\n    },\n    async update(sandboxId, patch) {\n      const current = rows.get(sandboxId)\n      if (!current) return null\n      const next = foldSpendBoxRecord(current, patch)\n      rows.set(sandboxId, next)\n      return structuredClone(next)\n    },\n    records() {\n      return [...rows.values()].map((row) => structuredClone(row))\n    },\n    put(record) {\n      rows.set(record.sandboxId, structuredClone(record))\n    },\n  }\n}\n\n/** What the product tells the ledger when it first sees a box. */\nexport interface ObserveSandboxInput {\n  readonly sandboxId: string\n  readonly workspaceId: string\n  /** The idle timeout the product asked the platform for, seconds. */\n  readonly idleTimeoutSeconds: number\n  /** The max lifetime the product asked for, seconds, when it asked for one. */\n  readonly maxLifetimeSeconds?: number | null\n  /** Defaults to the ledger's clock. */\n  readonly at?: number\n}\n\nexport interface SpendLedgerOptions {\n  readonly store: SpendLedgerStorePort\n  /** Injectable clock (epoch ms). Default `Date.now`. */\n  readonly now?: () => number\n  /** Product columns written verbatim on every insert. */\n  readonly extras?: Record<string, unknown>\n}\n\n/**\n * The recording half of spend verification: the product's own account of what\n * it asked the platform for.\n *\n * Every method is best-effort from the caller's point of view — a product wires\n * these into paths that must not fail because bookkeeping failed. They still\n * reject on a store error rather than swallowing it, so a caller that wants\n * fire-and-forget says so at the call site (`/sandbox`'s hook does).\n */\nexport interface SpendLedger {\n  /**\n   * Record that a box exists and is billable from now. Inserts on first sight,\n   * and otherwise records activity — reuse and resume are both \"the platform is\n   * charging for this box again\", and the record's own existence is what\n   * distinguishes them, so no caller has to know which happened.\n   */\n  observeSandbox(input: ObserveSandboxInput): Promise<SpendBoxRecord>\n  /** Record that the product saw this box do work. */\n  recordActivity(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n  /**\n   * Record that the product handed the platform work it will NOT watch finish.\n   * Until the matching end is recorded, this box's ceiling cannot rest on\n   * observed activity — see `computeExpectedCeiling`.\n   */\n  recordDetachedRunStarted(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that a detached run was confirmed finished. */\n  recordDetachedRunEnded(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that the product knows this box stopped. */\n  recordStopped(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that the product knows this box was deleted. */\n  recordDeleted(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n}\n\n/** Create the recording half over a product-supplied store. */\nexport function createSpendLedger(options: SpendLedgerOptions): SpendLedger {\n  const { store } = options\n  const clock = options.now ?? Date.now\n\n  return {\n    async observeSandbox(input) {\n      const at = input.at ?? clock()\n      const existing = await store.load(input.sandboxId)\n      if (existing) {\n        const updated = await store.update(input.sandboxId, { observedActivityAt: at })\n        return updated ?? existing\n      }\n      return await store.insert(\n        {\n          sandboxId: input.sandboxId,\n          workspaceId: input.workspaceId,\n          createdAt: at,\n          idleTimeoutSeconds: input.idleTimeoutSeconds,\n          maxLifetimeSeconds: input.maxLifetimeSeconds ?? null,\n          lastActivityAt: at,\n          openDetachedRunIds: [],\n          stoppedAt: null,\n          deletedAt: null,\n        },\n        options.extras,\n      )\n    },\n    async recordActivity(sandboxId, at) {\n      return await store.update(sandboxId, { observedActivityAt: at ?? clock() })\n    },\n    async recordDetachedRunStarted(sandboxId, runId, at) {\n      return await store.update(sandboxId, {\n        observedActivityAt: at ?? clock(),\n        openDetachedRunAdd: runId,\n      })\n    },\n    async recordDetachedRunEnded(sandboxId, runId, at) {\n      return await store.update(sandboxId, {\n        observedActivityAt: at ?? clock(),\n        openDetachedRunRemove: runId,\n      })\n    },\n    async recordStopped(sandboxId, at) {\n      return await store.update(sandboxId, { stoppedAt: at ?? clock() })\n    },\n    async recordDeleted(sandboxId, at) {\n      return await store.update(sandboxId, { deletedAt: at ?? clock() })\n    },\n  }\n}\n","import type { SpendLedger } from './store'\n\n/** Why provisioning was refused, with every number the decision used. */\nexport interface ComputeBudgetRefusal {\n  readonly workspaceId: string\n  /** The cap, unsigned nanodollars. */\n  readonly limitNanoUsd: number\n  /** Cumulative settled compute spend for this workspace, unsigned nanodollars. */\n  readonly settledNanoUsd: number\n  /** How far past the cap it already is. */\n  readonly overageNanoUsd: number\n  readonly at: number\n}\n\n/**\n * Provisioning refused because the workspace is already past its compute cap.\n *\n * Correctable by design: every number the decision used is on the error, so a\n * product can render \"this workspace has spent $X of its $Y compute budget\" and\n * an operator can raise the cap or investigate without reading logs.\n *\n * This is the failure mode the module exists to produce. A platform billing\n * defect that used to end in a silent negative balance now ends in provisioning\n * stopping and something loud happening instead.\n */\nexport class ComputeBudgetExceededError extends Error {\n  readonly workspaceId: string\n  readonly limitNanoUsd: number\n  readonly settledNanoUsd: number\n  readonly overageNanoUsd: number\n\n  constructor(refusal: ComputeBudgetRefusal) {\n    super(\n      `Compute budget exceeded for workspace ${refusal.workspaceId}: ` +\n        `$${(refusal.settledNanoUsd / 1_000_000_000).toFixed(2)} settled against a cap of ` +\n        `$${(refusal.limitNanoUsd / 1_000_000_000).toFixed(2)} ` +\n        `(over by $${(refusal.overageNanoUsd / 1_000_000_000).toFixed(2)}). ` +\n        'No sandbox was provisioned. Raise the cap or reconcile the spend before retrying.',\n    )\n    this.name = 'ComputeBudgetExceededError'\n    this.workspaceId = refusal.workspaceId\n    this.limitNanoUsd = refusal.limitNanoUsd\n    this.settledNanoUsd = refusal.settledNanoUsd\n    this.overageNanoUsd = refusal.overageNanoUsd\n  }\n}\n\n/**\n * A per-workspace cap on sandbox compute.\n *\n * `/billing`'s budget primitive caps MODEL keys, and it works because the\n * platform enforces the cap at the key it minted. Sandbox compute has no such\n * key: a box bills the shared company wallet, so nothing upstream refuses. This\n * carries the same shape to the one place a consumer can still act — the moment\n * before it asks for another box.\n *\n * `settledNanoUsd` is a callback rather than a number because the authority is\n * the platform ledger, not this package: the product reads the same rows it\n * hands the reconciler. Cache it if the read is expensive; a cap is a\n * coarse-grained control and a slightly stale total still refuses.\n */\nexport interface ComputeBudget {\n  /** The cap, unsigned nanodollars. */\n  readonly limitNanoUsd: number\n  /** Cumulative settled compute spend for the workspace, unsigned nanodollars. */\n  readonly settledNanoUsd: (workspaceId: string) => Promise<number> | number\n  /**\n   * Called on every refusal, before the error is thrown. This is the alert\n   * seam: a refusal nobody hears is a product that silently stopped working.\n   */\n  readonly onRefusal?: (refusal: ComputeBudgetRefusal) => void\n  /** Injectable clock (epoch ms). Default `Date.now`. */\n  readonly now?: () => number\n}\n\n/**\n * Throw {@link ComputeBudgetExceededError} when the workspace is already past\n * its cap. Returns normally — and reads nothing — when no budget is configured.\n *\n * Deliberately a pre-check against spend ALREADY SETTLED, not a reservation\n * against spend about to happen: settlement lags provisioning by design (the\n * platform's durable settlement queue), so there is no instant at which a\n * consumer could hold an accurate running total. The cap therefore overshoots by\n * at most the unsettled tail, which is bounded by the box's own idle timeout.\n * A cap that refuses one box late is worth far more than one that cannot be\n * implemented honestly.\n */\nexport async function assertComputeBudget(\n  budget: ComputeBudget | undefined,\n  workspaceId: string,\n): Promise<void> {\n  if (!budget) return\n  const settledNanoUsd = await budget.settledNanoUsd(workspaceId)\n  if (settledNanoUsd < budget.limitNanoUsd) return\n\n  const refusal: ComputeBudgetRefusal = {\n    workspaceId,\n    limitNanoUsd: budget.limitNanoUsd,\n    settledNanoUsd,\n    overageNanoUsd: settledNanoUsd - budget.limitNanoUsd,\n    at: (budget.now ?? Date.now)(),\n  }\n  budget.onRefusal?.(refusal)\n  throw new ComputeBudgetExceededError(refusal)\n}\n\n// ── the /sandbox seam ─────────────────────────────────────────────────────────\n\n/**\n * What `/sandbox` reports once a box is provisioned, reused or resumed.\n *\n * Structurally identical to `SandboxProvisionedObservation` in `/sandbox`, and\n * deliberately re-declared rather than imported: `/spend` composes `/sandbox`,\n * so a type import in the other direction would invert the dependency. The two\n * are pinned together by a compile-time assignment in this module's tests.\n */\nexport interface SpendProvisionObservation {\n  readonly workspaceId: string\n  readonly userId?: string\n  readonly sandboxId: string\n  readonly boxKey?: string | undefined\n  readonly idleTimeoutSeconds: number\n  readonly maxLifetimeSeconds?: number | undefined\n  readonly at: number\n}\n\n/**\n * The optional seam `EnsureWorkspaceSandboxOptions.spend` and the turn\n * primitives' `spend` option both accept. One object, wired in both places.\n */\nexport interface SandboxSpendSeam {\n  beforeProvision?(input: { workspaceId: string; userId?: string }): Promise<void> | void\n  onProvisioned?(observation: SpendProvisionObservation): Promise<void> | void\n  /** Synchronous by contract — it sits on the turn path. See `createSandboxSpendHooks`. */\n  onActivity?(input: { sandboxId: string; at: number }): void\n}\n\nexport interface SandboxSpendHooksOptions {\n  /** Records box lifecycle. Omit to run the budget guard alone. */\n  readonly ledger?: SpendLedger\n  /** Refuses provisioning past a cap. Omit to record alone. */\n  readonly budget?: ComputeBudget\n  /**\n   * Called when RECORDING fails. Recording is best-effort — a bookkeeping\n   * failure must never take down the provisioning it is bookkeeping — so this\n   * is the only place such a failure is visible. A refusal is NOT routed here;\n   * refusals throw, by design.\n   */\n  readonly onError?: (error: unknown) => void\n}\n\n/**\n * Build the object to hand `ensureWorkspaceSandbox`'s `spend` option.\n *\n * Wiring it is the entire adoption cost: one field, and the product's boxes are\n * both budget-capped and recorded.\n */\nexport function createSandboxSpendHooks(options: SandboxSpendHooksOptions): SandboxSpendSeam {\n  const { ledger, budget, onError } = options\n  return {\n    async beforeProvision(input) {\n      await assertComputeBudget(budget, input.workspaceId)\n    },\n    async onProvisioned(observation) {\n      if (!ledger) return\n      try {\n        await ledger.observeSandbox({\n          sandboxId: observation.sandboxId,\n          workspaceId: observation.workspaceId,\n          idleTimeoutSeconds: observation.idleTimeoutSeconds,\n          maxLifetimeSeconds: observation.maxLifetimeSeconds ?? null,\n          at: observation.at,\n        })\n      } catch (err) {\n        onError?.(err)\n      }\n    },\n    onActivity(input) {\n      if (!ledger) return\n      // The turn path calls this synchronously and does not await it, so the\n      // promise is settled here rather than escaping as an unhandled rejection.\n      // Recording activity is a monotonic max, so a write that lands late — or\n      // out of order against another turn's — still converges.\n      void ledger.recordActivity(input.sandboxId, input.at).catch((err: unknown) => onError?.(err))\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuCO,SAAS,mBAAmB,QAAwB,OAAsC;AAC/F,MAAI,iBAAiB,OAAO;AAC5B,MAAI,YAAY,OAAO;AACvB,MAAI,qBAAqB,OAAO;AAEhC,MAAI,MAAM,uBAAuB,QAAW;AAC1C,qBAAiB,KAAK,IAAI,gBAAgB,MAAM,kBAAkB;AAClE,QAAI,cAAc,QAAQ,MAAM,qBAAqB,UAAW,aAAY;AAAA,EAC9E;AACA,MAAI,MAAM,uBAAuB,UAAa,CAAC,mBAAmB,SAAS,MAAM,kBAAkB,GAAG;AACpG,yBAAqB,CAAC,GAAG,oBAAoB,MAAM,kBAAkB;AAAA,EACvE;AACA,MAAI,MAAM,0BAA0B,QAAW;AAC7C,yBAAqB,mBAAmB,OAAO,CAAC,OAAO,OAAO,MAAM,qBAAqB;AAAA,EAC3F;AACA,MAAI,MAAM,cAAc,QAAW;AAGjC,gBAAY,MAAM,aAAa,iBAAiB,MAAM,YAAY;AAAA,EACpE;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH;AAAA,IACA;AAAA,IACA;AAAA;AAAA;AAAA,IAGA,WAAW,OAAO,aAAa,MAAM,aAAa;AAAA,EACpD;AACF;AAWO,SAAS,iCAA2D;AACzE,QAAM,OAAO,oBAAI,IAA4B;AAC7C,SAAO;AAAA,IACL,MAAM,KAAK,WAAW;AACpB,YAAM,MAAM,KAAK,IAAI,SAAS;AAC9B,aAAO,MAAM,gBAAgB,GAAG,IAAI;AAAA,IACtC;AAAA,IACA,MAAM,OAAO,QAAQ;AACnB,YAAM,SAAS,gBAAgB,MAAM;AACrC,WAAK,IAAI,OAAO,WAAW,MAAM;AACjC,aAAO,gBAAgB,MAAM;AAAA,IAC/B;AAAA,IACA,MAAM,OAAO,WAAW,OAAO;AAC7B,YAAM,UAAU,KAAK,IAAI,SAAS;AAClC,UAAI,CAAC,QAAS,QAAO;AACrB,YAAM,OAAO,mBAAmB,SAAS,KAAK;AAC9C,WAAK,IAAI,WAAW,IAAI;AACxB,aAAO,gBAAgB,IAAI;AAAA,IAC7B;AAAA,IACA,UAAU;AACR,aAAO,CAAC,GAAG,KAAK,OAAO,CAAC,EAAE,IAAI,CAAC,QAAQ,gBAAgB,GAAG,CAAC;AAAA,IAC7D;AAAA,IACA,IAAI,QAAQ;AACV,WAAK,IAAI,OAAO,WAAW,gBAAgB,MAAM,CAAC;AAAA,IACpD;AAAA,EACF;AACF;AAwDO,SAAS,kBAAkB,SAA0C;AAC1E,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,QAAQ,QAAQ,OAAO,KAAK;AAElC,SAAO;AAAA,IACL,MAAM,eAAe,OAAO;AAC1B,YAAM,KAAK,MAAM,MAAM,MAAM;AAC7B,YAAM,WAAW,MAAM,MAAM,KAAK,MAAM,SAAS;AACjD,UAAI,UAAU;AACZ,cAAM,UAAU,MAAM,MAAM,OAAO,MAAM,WAAW,EAAE,oBAAoB,GAAG,CAAC;AAC9E,eAAO,WAAW;AAAA,MACpB;AACA,aAAO,MAAM,MAAM;AAAA,QACjB;AAAA,UACE,WAAW,MAAM;AAAA,UACjB,aAAa,MAAM;AAAA,UACnB,WAAW;AAAA,UACX,oBAAoB,MAAM;AAAA,UAC1B,oBAAoB,MAAM,sBAAsB;AAAA,UAChD,gBAAgB;AAAA,UAChB,oBAAoB,CAAC;AAAA,UACrB,WAAW;AAAA,UACX,WAAW;AAAA,QACb;AAAA,QACA,QAAQ;AAAA,MACV;AAAA,IACF;AAAA,IACA,MAAM,eAAe,WAAW,IAAI;AAClC,aAAO,MAAM,MAAM,OAAO,WAAW,EAAE,oBAAoB,MAAM,MAAM,EAAE,CAAC;AAAA,IAC5E;AAAA,IACA,MAAM,yBAAyB,WAAW,OAAO,IAAI;AACnD,aAAO,MAAM,MAAM,OAAO,WAAW;AAAA,QACnC,oBAAoB,MAAM,MAAM;AAAA,QAChC,oBAAoB;AAAA,MACtB,CAAC;AAAA,IACH;AAAA,IACA,MAAM,uBAAuB,WAAW,OAAO,IAAI;AACjD,aAAO,MAAM,MAAM,OAAO,WAAW;AAAA,QACnC,oBAAoB,MAAM,MAAM;AAAA,QAChC,uBAAuB;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,IACA,MAAM,cAAc,WAAW,IAAI;AACjC,aAAO,MAAM,MAAM,OAAO,WAAW,EAAE,WAAW,MAAM,MAAM,EAAE,CAAC;AAAA,IACnE;AAAA,IACA,MAAM,cAAc,WAAW,IAAI;AACjC,aAAO,MAAM,MAAM,OAAO,WAAW,EAAE,WAAW,MAAM,MAAM,EAAE,CAAC;AAAA,IACnE;AAAA,EACF;AACF;;;AC1LO,IAAM,6BAAN,cAAyC,MAAM;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,SAA+B;AACzC;AAAA,MACE,yCAAyC,QAAQ,WAAW,OACrD,QAAQ,iBAAiB,KAAe,QAAQ,CAAC,CAAC,+BAClD,QAAQ,eAAe,KAAe,QAAQ,CAAC,CAAC,eACvC,QAAQ,iBAAiB,KAAe,QAAQ,CAAC,CAAC;AAAA,IAEpE;AACA,SAAK,OAAO;AACZ,SAAK,cAAc,QAAQ;AAC3B,SAAK,eAAe,QAAQ;AAC5B,SAAK,iBAAiB,QAAQ;AAC9B,SAAK,iBAAiB,QAAQ;AAAA,EAChC;AACF;AA0CA,eAAsB,oBACpB,QACA,aACe;AACf,MAAI,CAAC,OAAQ;AACb,QAAM,iBAAiB,MAAM,OAAO,eAAe,WAAW;AAC9D,MAAI,iBAAiB,OAAO,aAAc;AAE1C,QAAM,UAAgC;AAAA,IACpC;AAAA,IACA,cAAc,OAAO;AAAA,IACrB;AAAA,IACA,gBAAgB,iBAAiB,OAAO;AAAA,IACxC,KAAK,OAAO,OAAO,KAAK,KAAK;AAAA,EAC/B;AACA,SAAO,YAAY,OAAO;AAC1B,QAAM,IAAI,2BAA2B,OAAO;AAC9C;AAqDO,SAAS,wBAAwB,SAAqD;AAC3F,QAAM,EAAE,QAAQ,QAAQ,QAAQ,IAAI;AACpC,SAAO;AAAA,IACL,MAAM,gBAAgB,OAAO;AAC3B,YAAM,oBAAoB,QAAQ,MAAM,WAAW;AAAA,IACrD;AAAA,IACA,MAAM,cAAc,aAAa;AAC/B,UAAI,CAAC,OAAQ;AACb,UAAI;AACF,cAAM,OAAO,eAAe;AAAA,UAC1B,WAAW,YAAY;AAAA,UACvB,aAAa,YAAY;AAAA,UACzB,oBAAoB,YAAY;AAAA,UAChC,oBAAoB,YAAY,sBAAsB;AAAA,UACtD,IAAI,YAAY;AAAA,QAClB,CAAC;AAAA,MACH,SAAS,KAAK;AACZ,kBAAU,GAAG;AAAA,MACf;AAAA,IACF;AAAA,IACA,WAAW,OAAO;AAChB,UAAI,CAAC,OAAQ;AAKb,WAAK,OAAO,eAAe,MAAM,WAAW,MAAM,EAAE,EAAE,MAAM,CAAC,QAAiB,UAAU,GAAG,CAAC;AAAA,IAC9F;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/spend/store.ts","../../src/spend/budget.ts"],"sourcesContent":["import type { SpendBoxPatch, SpendBoxRecord } from './types'\n\n/**\n * Persistence seam for the expectation ledger — the product implements it over\n * its own tables.\n *\n * Deliberately NOT compare-and-set, unlike `MissionStorePort`. A mission has one\n * serialized owner and a lost write corrupts a state machine; a box record is a\n * MONOTONIC FOLD (activity takes a max, a detached-run id joins or leaves a set,\n * delete is set-once) so concurrent writers converge no matter what order they\n * land in. The worst a lost race can do here is leave `lastActivityAt` behind\n * the truth — which makes the derived ceiling TIGHTER, so the failure mode is a\n * false alarm a human dismisses, never a missed charge. That asymmetry is the\n * whole reason the fold is shaped this way.\n *\n * `update` returns null when the row does not exist, never a throw.\n */\nexport interface SpendLedgerStorePort {\n  load(sandboxId: string): Promise<SpendBoxRecord | null>\n  /** `extras` are the opaque product-column values — write them in the SAME\n   *  statement as the record, or ignore them if the table has no extra columns. */\n  insert(record: SpendBoxRecord, extras?: Record<string, unknown>): Promise<SpendBoxRecord>\n  update(sandboxId: string, patch: SpendBoxPatch): Promise<SpendBoxRecord | null>\n}\n\n/**\n * Apply one fold step. Exported so a SQL implementation and an in-memory one\n * reach the same record, and so a product can unit-test its own store against\n * the canonical answer.\n *\n * The two rules worth stating out loud:\n *\n * - `observedActivityAt` only ever moves `lastActivityAt` FORWARD. A replayed\n *   or out-of-order event cannot rewind the ceiling.\n * - activity later than a recorded `stoppedAt` CLEARS the stop. A box that\n *   worked after the product thought it stopped is running again, and keeping\n *   the stale stop would make the ceiling too tight — inventing an over-ceiling\n *   finding out of the product's own bookkeeping rather than the platform's.\n */\nexport function foldSpendBoxRecord(record: SpendBoxRecord, patch: SpendBoxPatch): SpendBoxRecord {\n  let lastActivityAt = record.lastActivityAt\n  let stoppedAt = record.stoppedAt\n  let openDetachedRunIds = record.openDetachedRunIds\n\n  if (patch.observedActivityAt !== undefined) {\n    lastActivityAt = Math.max(lastActivityAt, patch.observedActivityAt)\n    if (stoppedAt !== null && patch.observedActivityAt > stoppedAt) stoppedAt = null\n  }\n  if (patch.openDetachedRunAdd !== undefined && !openDetachedRunIds.includes(patch.openDetachedRunAdd)) {\n    openDetachedRunIds = [...openDetachedRunIds, patch.openDetachedRunAdd]\n  }\n  if (patch.openDetachedRunRemove !== undefined) {\n    openDetachedRunIds = openDetachedRunIds.filter((id) => id !== patch.openDetachedRunRemove)\n  }\n  if (patch.stoppedAt !== undefined) {\n    // Latest-wins, but never behind observed activity: a stop we are told about\n    // that predates work we watched is not the stop that closed this box.\n    stoppedAt = patch.stoppedAt >= lastActivityAt ? patch.stoppedAt : stoppedAt\n  }\n\n  return {\n    ...record,\n    lastActivityAt,\n    stoppedAt,\n    openDetachedRunIds,\n    // Set-once: a deleted sandbox id never comes back, so a second observation\n    // is a duplicate delivery, not a second deletion.\n    deletedAt: record.deletedAt ?? patch.deletedAt ?? null,\n  }\n}\n\n/** An in-memory store that also lets a test inspect and force state. */\nexport interface InMemorySpendLedgerStore extends SpendLedgerStorePort {\n  /** Every record, insertion order. */\n  records(): SpendBoxRecord[]\n  /** Unguarded direct write — simulates a crash-shaped or platform-seeded row. */\n  put(record: SpendBoxRecord): void\n}\n\n/** Create an in-memory expectation ledger. Production writers use the same port. */\nexport function createInMemorySpendLedgerStore(): InMemorySpendLedgerStore {\n  const rows = new Map<string, SpendBoxRecord>()\n  return {\n    async load(sandboxId) {\n      const row = rows.get(sandboxId)\n      return row ? structuredClone(row) : null\n    },\n    async insert(record) {\n      const stored = structuredClone(record)\n      rows.set(record.sandboxId, stored)\n      return structuredClone(stored)\n    },\n    async update(sandboxId, patch) {\n      const current = rows.get(sandboxId)\n      if (!current) return null\n      const next = foldSpendBoxRecord(current, patch)\n      rows.set(sandboxId, next)\n      return structuredClone(next)\n    },\n    records() {\n      return [...rows.values()].map((row) => structuredClone(row))\n    },\n    put(record) {\n      rows.set(record.sandboxId, structuredClone(record))\n    },\n  }\n}\n\n/** What the product tells the ledger when it first sees a box. */\nexport interface ObserveSandboxInput {\n  readonly sandboxId: string\n  readonly workspaceId: string\n  /** The idle timeout the product asked the platform for, seconds. */\n  readonly idleTimeoutSeconds: number\n  /** The max lifetime the product asked for, seconds, when it asked for one. */\n  readonly maxLifetimeSeconds?: number | null\n  /** Defaults to the ledger's clock. */\n  readonly at?: number\n}\n\nexport interface SpendLedgerOptions {\n  readonly store: SpendLedgerStorePort\n  /** Injectable clock (epoch ms). Default `Date.now`. */\n  readonly now?: () => number\n  /** Product columns written verbatim on every insert. */\n  readonly extras?: Record<string, unknown>\n}\n\n/**\n * The recording half of spend verification: the product's own account of what\n * it asked the platform for.\n *\n * Every method is best-effort from the caller's point of view — a product wires\n * these into paths that must not fail because bookkeeping failed. They still\n * reject on a store error rather than swallowing it, so a caller that wants\n * fire-and-forget says so at the call site (`/sandbox`'s hook does).\n */\nexport interface SpendLedger {\n  /**\n   * Record that a box exists and is billable from now. Inserts on first sight,\n   * and otherwise records activity — reuse and resume are both \"the platform is\n   * charging for this box again\", and the record's own existence is what\n   * distinguishes them, so no caller has to know which happened.\n   */\n  observeSandbox(input: ObserveSandboxInput): Promise<SpendBoxRecord>\n  /** Record that the product saw this box do work. */\n  recordActivity(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n  /**\n   * Record that the product handed the platform work it will NOT watch finish.\n   * Until the matching end is recorded, this box's ceiling cannot rest on\n   * observed activity — see `computeExpectedCeiling`.\n   */\n  recordDetachedRunStarted(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that a detached run was confirmed finished. */\n  recordDetachedRunEnded(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that the product knows this box stopped. */\n  recordStopped(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n  /** Record that the product knows this box was deleted. */\n  recordDeleted(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>\n}\n\n/** Create the recording half over a product-supplied store. */\nexport function createSpendLedger(options: SpendLedgerOptions): SpendLedger {\n  const { store } = options\n  const clock = options.now ?? Date.now\n\n  return {\n    async observeSandbox(input) {\n      const at = input.at ?? clock()\n      const existing = await store.load(input.sandboxId)\n      if (existing) {\n        const updated = await store.update(input.sandboxId, { observedActivityAt: at })\n        return updated ?? existing\n      }\n      return await store.insert(\n        {\n          sandboxId: input.sandboxId,\n          workspaceId: input.workspaceId,\n          createdAt: at,\n          idleTimeoutSeconds: input.idleTimeoutSeconds,\n          maxLifetimeSeconds: input.maxLifetimeSeconds ?? null,\n          lastActivityAt: at,\n          openDetachedRunIds: [],\n          stoppedAt: null,\n          deletedAt: null,\n        },\n        options.extras,\n      )\n    },\n    async recordActivity(sandboxId, at) {\n      return await store.update(sandboxId, { observedActivityAt: at ?? clock() })\n    },\n    async recordDetachedRunStarted(sandboxId, runId, at) {\n      return await store.update(sandboxId, {\n        observedActivityAt: at ?? clock(),\n        openDetachedRunAdd: runId,\n      })\n    },\n    async recordDetachedRunEnded(sandboxId, runId, at) {\n      return await store.update(sandboxId, {\n        observedActivityAt: at ?? clock(),\n        openDetachedRunRemove: runId,\n      })\n    },\n    async recordStopped(sandboxId, at) {\n      return await store.update(sandboxId, { stoppedAt: at ?? clock() })\n    },\n    async recordDeleted(sandboxId, at) {\n      return await store.update(sandboxId, { deletedAt: at ?? clock() })\n    },\n  }\n}\n","import type { SpendLedger } from './store'\n\n/** Why provisioning was refused, with every number the decision used. */\nexport interface ComputeBudgetRefusal {\n  readonly workspaceId: string\n  /** The cap, unsigned nanodollars. */\n  readonly limitNanoUsd: number\n  /** Cumulative settled compute spend for this workspace, unsigned nanodollars. */\n  readonly settledNanoUsd: number\n  /** How far past the cap it already is. */\n  readonly overageNanoUsd: number\n  readonly at: number\n}\n\n/**\n * Provisioning refused because the workspace is already past its compute cap.\n *\n * Correctable by design: every number the decision used is on the error, so a\n * product can render \"this workspace has spent $X of its $Y compute budget\" and\n * an operator can raise the cap or investigate without reading logs.\n *\n * This is the failure mode the module exists to produce. A platform billing\n * defect that used to end in a silent negative balance now ends in provisioning\n * stopping and something loud happening instead.\n */\nexport class ComputeBudgetExceededError extends Error {\n  readonly workspaceId: string\n  readonly limitNanoUsd: number\n  readonly settledNanoUsd: number\n  readonly overageNanoUsd: number\n\n  constructor(refusal: ComputeBudgetRefusal) {\n    super(\n      `Compute budget exceeded for workspace ${refusal.workspaceId}: ` +\n        `$${(refusal.settledNanoUsd / 1_000_000_000).toFixed(2)} settled against a cap of ` +\n        `$${(refusal.limitNanoUsd / 1_000_000_000).toFixed(2)} ` +\n        `(over by $${(refusal.overageNanoUsd / 1_000_000_000).toFixed(2)}). ` +\n        'No sandbox was provisioned. Raise the cap or reconcile the spend before retrying.',\n    )\n    this.name = 'ComputeBudgetExceededError'\n    this.workspaceId = refusal.workspaceId\n    this.limitNanoUsd = refusal.limitNanoUsd\n    this.settledNanoUsd = refusal.settledNanoUsd\n    this.overageNanoUsd = refusal.overageNanoUsd\n  }\n}\n\n/**\n * A per-workspace cap on sandbox compute.\n *\n * `/billing`'s budget primitive caps MODEL keys, and it works because the\n * platform enforces the cap at the key it minted. Sandbox compute has no such\n * key: a box bills the shared company wallet, so nothing upstream refuses. This\n * carries the same shape to the one place a consumer can still act — the moment\n * before it asks for another box.\n *\n * `settledNanoUsd` is a callback rather than a number because the authority is\n * the platform ledger, not this package: the product reads the same rows it\n * hands the reconciler. Cache it if the read is expensive; a cap is a\n * coarse-grained control and a slightly stale total still refuses.\n */\nexport interface ComputeBudget {\n  /** The cap, unsigned nanodollars. */\n  readonly limitNanoUsd: number\n  /** Cumulative settled compute spend for the workspace, unsigned nanodollars. */\n  readonly settledNanoUsd: (workspaceId: string) => Promise<number> | number\n  /**\n   * Called on every refusal, before the error is thrown. This is the alert\n   * seam: a refusal nobody hears is a product that silently stopped working.\n   */\n  readonly onRefusal?: (refusal: ComputeBudgetRefusal) => void\n  /** Injectable clock (epoch ms). Default `Date.now`. */\n  readonly now?: () => number\n}\n\n/**\n * Throw {@link ComputeBudgetExceededError} when the workspace is already past\n * its cap. Returns normally — and reads nothing — when no budget is configured.\n *\n * Deliberately a pre-check against spend ALREADY SETTLED, not a reservation\n * against spend about to happen: settlement lags provisioning by design (the\n * platform's durable settlement queue), so there is no instant at which a\n * consumer could hold an accurate running total. The cap therefore overshoots by\n * at most the unsettled tail, which is bounded by the box's own idle timeout.\n * A cap that refuses one box late is worth far more than one that cannot be\n * implemented honestly.\n */\nexport async function assertComputeBudget(\n  budget: ComputeBudget | undefined,\n  workspaceId: string,\n): Promise<void> {\n  if (!budget) return\n  const settledNanoUsd = await budget.settledNanoUsd(workspaceId)\n  if (settledNanoUsd < budget.limitNanoUsd) return\n\n  const refusal: ComputeBudgetRefusal = {\n    workspaceId,\n    limitNanoUsd: budget.limitNanoUsd,\n    settledNanoUsd,\n    overageNanoUsd: settledNanoUsd - budget.limitNanoUsd,\n    at: (budget.now ?? Date.now)(),\n  }\n  budget.onRefusal?.(refusal)\n  throw new ComputeBudgetExceededError(refusal)\n}\n\n// ── the /sandbox seam ─────────────────────────────────────────────────────────\n\n/**\n * What `/sandbox` reports once a box is provisioned, reused or resumed.\n *\n * Structurally identical to `SandboxProvisionedObservation` in `/sandbox`, and\n * deliberately re-declared rather than imported: `/spend` composes `/sandbox`,\n * so a type import in the other direction would invert the dependency. The two\n * are pinned together by a compile-time assignment in this module's tests.\n */\nexport interface SpendProvisionObservation {\n  readonly workspaceId: string\n  readonly userId?: string\n  readonly sandboxId: string\n  readonly boxKey?: string | undefined\n  readonly idleTimeoutSeconds: number\n  readonly maxLifetimeSeconds?: number | undefined\n  readonly at: number\n}\n\n/**\n * The optional seam `EnsureWorkspaceSandboxOptions.spend` and the turn\n * primitives' `spend` option both accept. One object, wired in both places.\n */\nexport interface SandboxSpendSeam {\n  beforeProvision?(input: { workspaceId: string; userId?: string }): Promise<void> | void\n  onProvisioned?(observation: SpendProvisionObservation): Promise<void> | void\n  /** Synchronous by contract — it sits on the turn path. See `createSandboxSpendHooks`. */\n  onActivity?(input: { sandboxId: string; at: number }): void\n}\n\nexport interface SandboxSpendHooksOptions {\n  /** Records box lifecycle. Omit to run the budget guard alone. */\n  readonly ledger?: SpendLedger\n  /** Refuses provisioning past a cap. Omit to record alone. */\n  readonly budget?: ComputeBudget\n  /**\n   * Called when RECORDING fails. Recording is best-effort — a bookkeeping\n   * failure must never take down the provisioning it is bookkeeping — so this\n   * is the only place such a failure is visible. A refusal is NOT routed here;\n   * refusals throw, by design.\n   */\n  readonly onError?: (error: unknown) => void\n}\n\n/**\n * Build the object to hand `ensureWorkspaceSandbox`'s `spend` option.\n *\n * Wiring it is the entire adoption cost: one field, and the product's boxes are\n * both budget-capped and recorded.\n */\nexport function createSandboxSpendHooks(options: SandboxSpendHooksOptions): SandboxSpendSeam {\n  const { ledger, budget, onError } = options\n  return {\n    async beforeProvision(input) {\n      await assertComputeBudget(budget, input.workspaceId)\n    },\n    async onProvisioned(observation) {\n      if (!ledger) return\n      try {\n        await ledger.observeSandbox({\n          sandboxId: observation.sandboxId,\n          workspaceId: observation.workspaceId,\n          idleTimeoutSeconds: observation.idleTimeoutSeconds,\n          maxLifetimeSeconds: observation.maxLifetimeSeconds ?? null,\n          at: observation.at,\n        })\n      } catch (err) {\n        onError?.(err)\n      }\n    },\n    onActivity(input) {\n      if (!ledger) return\n      // The turn path calls this synchronously and does not await it, so the\n      // promise is settled here rather than escaping as an unhandled rejection.\n      // Recording activity is a monotonic max, so a write that lands late — or\n      // out of order against another turn's — still converges.\n      void ledger.recordActivity(input.sandboxId, input.at).catch((err: unknown) => onError?.(err))\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.45.31",
+  "version": "0.45.32",
   "packageManager": "pnpm@11.17.0",
   "description": "Build agent applications with typed chat, tools, sandboxes, integrations, billing, and evaluation.",
   "keywords": [

package/dist/chunk-NEJ7OMQS.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/spend/types.ts","../src/spend/ceiling.ts","../src/spend/reference.ts","../src/spend/reconcile.ts","../src/spend/report.ts"],"sourcesContent":["/**\n * The vocabulary of consumer-side spend verification.\n *\n * Kept in its own module with ZERO imports so a product can type its storage\n * rows and its reconciliation config without pulling in `node:fs` through the\n * CLI half.\n *\n * The model in one paragraph: the platform's ledger is authoritative about what\n * was CHARGED. A product knows something the ledger does not — what it ASKED\n * for. Recording that second view, and diffing it against the first, is what\n * turns a platform billing defect from silent money into an alert. Nothing here\n * lets a product self-certify a charge away; the output is a discrepancy a human\n * disputes.\n */\n\n// ── the product's own view of a box's life ────────────────────────────────────\n\n/**\n * One box, as the PRODUCT understands it. Folded, not an append-only log: a\n * product runs one row per sandbox, and every field below is derived by a\n * monotonic fold (see `foldSpendBoxRecord`) so two concurrent writers cannot\n * produce a wrong answer, only a stale one.\n *\n * Timestamps are epoch ms throughout, matching the platform's own\n * `sandbox_meta.last_started_at`.\n */\nexport interface SpendBoxRecord {\n  /** The platform's sandbox id — the join key to every settlement row. */\n  readonly sandboxId: string\n  /** The product's own tenancy unit, which the platform does not model. */\n  readonly workspaceId: string\n  /** First moment the product knew this box existed. */\n  readonly createdAt: number\n  /**\n   * The idle timeout the product ASKED the platform for, seconds. This is the\n   * width of the grace window between the last thing the product saw and the\n   * moment the platform should have stopped billing.\n   */\n  readonly idleTimeoutSeconds: number\n  /**\n   * The maximum lifetime the product asked for, seconds, when it asked for one.\n   * This is the strongest bound a product holds: the platform destroys the box\n   * at `createdAt + maxLifetimeSeconds` regardless of what the product observed,\n   * so it caps the ceiling even when nothing else can (see `computeExpectedCeiling`).\n   */\n  readonly maxLifetimeSeconds: number | null\n  /** Latest moment the product OBSERVED the box doing work. */\n  readonly lastActivityAt: number\n  /**\n   * Detached runs dispatched but never observed to finish, by run id.\n   *\n   * Non-empty means the product genuinely cannot bound this box from its own\n   * observations: it handed the platform work and disconnected. The ceiling\n   * degrades accordingly rather than pretending to a tightness it did not earn.\n   */\n  readonly openDetachedRunIds: readonly string[]\n  /** When the product knows the box stopped. Cleared by later activity. */\n  readonly stoppedAt: number | null\n  /** When the product knows the box was deleted. Set once — a deleted id never returns. */\n  readonly deletedAt: number | null\n  /** Opaque product-column values, written verbatim and never read here. */\n  readonly extras?: Record<string, unknown>\n}\n\n/**\n * A fold step. Every field states its own merge rule, so a SQL implementation\n * can apply it in one statement and reach the same record an in-memory\n * read-modify-write reaches.\n */\nexport interface SpendBoxPatch {\n  /** Advance `lastActivityAt` to the max of stored and this. Never moves backward. */\n  readonly observedActivityAt?: number\n  /** Add a run id to `openDetachedRunIds` (set semantics — re-adding is a no-op). */\n  readonly openDetachedRunAdd?: string\n  /** Remove a run id from `openDetachedRunIds`. Removing an absent id is a no-op. */\n  readonly openDetachedRunRemove?: string\n  /**\n   * Latest-wins. Activity observed AFTER a recorded stop clears it: a box that\n   * worked after we thought it stopped is running again, and a stale stop would\n   * make the ceiling too tight.\n   */\n  readonly stoppedAt?: number\n  /** Set-once. A later delete observation does not move the first one. */\n  readonly deletedAt?: number\n}\n\n// ── what bounds a box's billable time ─────────────────────────────────────────\n\n/** Which fact bounds a box's billable time, weakest last. */\nexport type CeilingBasis =\n  /** The product observed deletion. Billing cannot run past a box that is gone. */\n  | 'deleted'\n  /** The product observed a stop. Billing should have closed there. */\n  | 'stopped'\n  /** No stop seen, but the platform destroys the box at its max lifetime. */\n  | 'max-lifetime'\n  /** No stop seen; the platform's idle timer is what should have closed billing. */\n  | 'idle-timeout'\n  /**\n   * An unfinished detached run and no max lifetime — the product cannot bound\n   * this box at all, so the ceiling degrades to the reconciliation instant.\n   * A finding on this basis is weak evidence and says so.\n   */\n  | 'open-detached-run'\n\n/** The upper bound on one box's billable duration, and what earned it. */\nexport interface ExpectedCeiling {\n  readonly sandboxId: string\n  readonly basis: CeilingBasis\n  /** The latest instant this box could still have been billable, epoch ms. */\n  readonly horizonAt: number\n  /** `horizonAt - createdAt + toleranceMs`. The upper bound on billable ms. */\n  readonly ceilingMs: number\n  readonly toleranceMs: number\n  /**\n   * False when the basis is `open-detached-run` — the ceiling then rests on the\n   * reconciliation instant rather than on anything the product observed, so an\n   * overage means the platform billed outside the box's own lifetime, not merely\n   * longer than expected.\n   */\n  readonly bounded: boolean\n}\n\n// ── what the platform actually emitted ────────────────────────────────────────\n\n/**\n * One settled ledger row, in the shape the platform's `credit_transactions`\n * table stores it. The product supplies these through its own fetch (the\n * platform's credit-history API, an export, a mirror) — this package never\n * reaches for them, because the ledger is the counterparty's record and reading\n * it is the product's authenticated business.\n *\n * The product's fetch MUST scope rows to boxes it owns. Products bill to a\n * shared company key, so an unscoped fetch returns every sibling product's\n * settlements and every one of them is a correct `unknown-box` finding.\n */\nexport interface SettlementRow {\n  /** The ledger row id, for the dispute. */\n  readonly id: string\n  /**\n   * `sandbox:<kind>:<sandboxId>:<intervalStartMs>` — the platform's idempotency\n   * key, and the only place the billed interval's START is recorded.\n   */\n  readonly referenceId: string | null\n  /**\n   * Signed nanodollars, exactly as the ledger stores it: negative is a charge,\n   * positive is a credit or refund.\n   */\n  readonly amountNanoUsd: number\n  /** `compute` | `refund` | `inference` | … */\n  readonly type: string\n  /** `sandbox` | `router` | … */\n  readonly product: string | null\n  /** `sandbox:<sandboxId>` — the platform's aggregation unit. */\n  readonly groupKey: string | null\n  /** Settlement instant, epoch ms. The product normalizes the stored text. */\n  readonly createdAt: number\n  readonly description: string | null\n  /** Provider at-cost basis, unsigned nanodollars. Null when unattributed. */\n  readonly costBasisNanoUsd: number | null\n  /**\n   * The billed duration, when the product's ledger view exposes it directly.\n   * Null is the common case: the platform does not store duration on the row.\n   */\n  readonly billedMs: number | null\n}\n\n/** The parts of a settlement reference id, once parsed. */\nexport interface SettlementReference {\n  /** `stop` | `compute` | `egress` | `gpu-lease` | anything the platform adds. */\n  readonly kind: string\n  /** For compute kinds, the sandbox id. For `gpu-lease`, the lease id. */\n  readonly resourceId: string\n  /** The interval's start, epoch ms. Null for kinds that carry no interval. */\n  readonly intervalStartMs: number | null\n}\n\n/** How a settled duration was arrived at — every duration finding carries one. */\nexport type BilledDurationBasis =\n  /** The ledger row carried the duration. Exact. */\n  | 'reported'\n  /** `amount ÷ the product's stated hourly rate`. Exact when the rate is right. */\n  | 'rate'\n  /**\n   * `settledAt - intervalStart`. An UPPER bound, not the billed duration: a\n   * correct settlement posted late by the platform's durable settlement queue\n   * reads longer here than it billed. Findings on this basis say so.\n   */\n  | 'reference-span'\n  /** No basis available — duration rules are skipped for this row. */\n  | 'unknown'\n\n// ── findings ──────────────────────────────────────────────────────────────────\n\n/** The checks this reconciler runs. Each is individually skippable, by name. */\nexport type SpendCheckId =\n  /** A settlement against a box the product has no record of ever asking for. */\n  | 'unknown-box'\n  /** A settled duration longer than the product's own upper bound allows. */\n  | 'over-ceiling'\n  /** A spend window far above the trailing median — the burst shape of a defect. */\n  | 'velocity'\n  /** The balance the product observes has gone below its floor. */\n  | 'negative-balance'\n\nexport const SPEND_CHECKS: readonly SpendCheckId[] = [\n  'unknown-box',\n  'over-ceiling',\n  'velocity',\n  'negative-balance',\n]\n\n/**\n * One discrepancy, with every number the rule compared.\n *\n * Nullable fields are per-check and deliberately present-but-null rather than\n * absent: a reader scanning a JSON dump can tell \"this rule does not measure\n * that\" from \"that measurement is missing\".\n */\nexport interface SpendFinding {\n  readonly check: SpendCheckId\n  /** What is wrong, in one sentence, with the numbers in it. */\n  readonly message: string\n  /** What to do about it. A finding without a remedy is a complaint. */\n  readonly remedy: string\n  readonly sandboxId: string | null\n  readonly workspaceId: string | null\n  /** The ledger rows that evidence this finding — the dispute's exhibit list. */\n  readonly referenceIds: readonly string[]\n  /** Nanodollars this finding puts in question, unsigned. */\n  readonly settledNanoUsd: number\n  /** `over-ceiling` — the duration actually settled, and how that was derived. */\n  readonly settledMs: number | null\n  readonly durationBasis: BilledDurationBasis | null\n  /** `over-ceiling` — the bound it broke, and what earned that bound. */\n  readonly ceilingMs: number | null\n  readonly overageMs: number | null\n  readonly ceilingBasis: CeilingBasis | null\n  /** `velocity` — the window, its trailing median, and the ratio between them. */\n  readonly windowNanoUsd: number | null\n  readonly trailingMedianNanoUsd: number | null\n  readonly velocityRatio: number | null\n  readonly windowStartAt: number | null\n  /** `negative-balance` — the observed balance and the floor it broke. */\n  readonly balanceNanoUsd: number | null\n  readonly balanceFloorNanoUsd: number | null\n}\n\n/** What one reconciliation pass concluded. */\nexport interface SpendReport {\n  /** True when nothing fired. `ok === findings.length === 0`. */\n  readonly ok: boolean\n  readonly findings: readonly SpendFinding[]\n  readonly checksRun: readonly SpendCheckId[]\n  /** Rows the pass read, including the ones no rule looked at. */\n  readonly rowsExamined: number\n  /** Distinct boxes those rows settled against. */\n  readonly boxesExamined: number\n  /** Total charged across every examined row, unsigned nanodollars. */\n  readonly settledNanoUsd: number\n  /** Total credited back across every examined row, unsigned nanodollars. */\n  readonly creditedNanoUsd: number\n  /** The instant the pass treated as \"now\". */\n  readonly asOf: number\n}\n","import type { CeilingBasis, ExpectedCeiling, SpendBoxRecord } from './types'\n\n/**\n * Slack allowed between the product's bound and what the platform settled,\n * before an overage is called a discrepancy. 15 minutes.\n *\n * Not a guess: it is the platform's OWN staleness threshold for compute\n * settlement. Its runbook clears an incident when\n * `/health computeSettlement.oldestAgeSeconds` is \"back under 900\" — so 900 s is\n * the age the platform itself treats as normal settlement lag, and anything\n * inside it is drift the platform has already declared acceptable. Below that a\n * product would alert on the platform's ordinary queue behaviour; far above it\n * the tolerance starts eating the signal, because the idle window it must stay\n * well under is 3600 s in every shipped product.\n *\n * It is a caller parameter because a product that asks for a shorter idle\n * timeout must shrink this with it.\n */\nexport const DEFAULT_CEILING_TOLERANCE_MS = 900_000\n\nexport interface ComputeExpectedCeilingOptions {\n  /** The instant the reconciliation treats as \"now\", epoch ms. */\n  readonly asOf: number\n  /** Slack before an overage counts. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */\n  readonly toleranceMs?: number\n}\n\n/**\n * The upper bound on how long one box could honestly have been billable.\n *\n * The whole design constraint is that this must stay an UPPER bound under\n * everything the product cannot see. Three such blind spots exist, and they\n * pull in different directions:\n *\n * - **Platform-side suspends.** The platform can park a box the product never\n *   hears about. That only ever REDUCES real billable time, so an upper bound\n *   is unaffected and nothing here widens for it.\n * - **Detached runs.** The product dispatches work and disconnects. The box\n *   keeps working — and billing — after the last activity the product saw, so\n *   `lastActivityAt` understates the truth. An unfinished detached run\n *   therefore abandons the activity-based bound entirely rather than reporting\n *   a bound it cannot support.\n * - **Reconnects.** A browser or worker re-attaches and work resumes. This\n *   needs no special case: a reconnect is recorded as activity, the fold takes\n *   the max, and the horizon moves out on its own.\n *\n * The bound that rescues the detached case is `maxLifetimeSeconds`. The platform\n * destroys the box at `createdAt + maxLifetimeSeconds` no matter what anyone\n * observed, so a product that asks for one holds a hard bound that survives\n * every blind spot above. Both shipped products ask for 86 400 s, which is why\n * the incident — 124 to 268 hours settled against boxes with a 24-hour\n * lifetime — is detectable with no lifecycle bookkeeping at all.\n */\nexport function computeExpectedCeiling(\n  record: SpendBoxRecord,\n  options: ComputeExpectedCeilingOptions,\n): ExpectedCeiling {\n  const toleranceMs = options.toleranceMs ?? DEFAULT_CEILING_TOLERANCE_MS\n  const { asOf } = options\n\n  let basis: CeilingBasis\n  let horizonAt: number\n\n  if (record.deletedAt !== null) {\n    basis = 'deleted'\n    horizonAt = record.deletedAt\n  } else if (record.stoppedAt !== null) {\n    basis = 'stopped'\n    horizonAt = record.stoppedAt\n  } else if (record.openDetachedRunIds.length > 0) {\n    // Nothing the product observed bounds this box. Fall back to the\n    // reconciliation instant, and say so through `bounded: false`.\n    basis = 'open-detached-run'\n    horizonAt = asOf\n  } else {\n    basis = 'idle-timeout'\n    horizonAt = record.lastActivityAt + record.idleTimeoutSeconds * 1000\n  }\n\n  // The hard platform bound wins whenever it is tighter — including over an\n  // unfinished detached run, which is what turns an unbounded box back into a\n  // bounded one.\n  if (record.maxLifetimeSeconds !== null) {\n    const lifetimeHorizon = record.createdAt + record.maxLifetimeSeconds * 1000\n    if (lifetimeHorizon < horizonAt) {\n      basis = 'max-lifetime'\n      horizonAt = lifetimeHorizon\n    }\n  }\n\n  // Time that has not elapsed cannot have been billed, so an idle window\n  // reaching into the future does not widen the bound. This only ever tightens\n  // the ceiling, so it cannot mask a charge.\n  if (horizonAt > asOf) horizonAt = asOf\n  // A horizon before creation would produce a negative ceiling; a box is at\n  // minimum billable for the instant it existed.\n  if (horizonAt < record.createdAt) horizonAt = record.createdAt\n\n  return {\n    sandboxId: record.sandboxId,\n    basis,\n    horizonAt,\n    ceilingMs: horizonAt - record.createdAt + toleranceMs,\n    toleranceMs,\n    bounded: basis !== 'open-detached-run',\n  }\n}\n","import type { SettlementReference, SettlementRow } from './types'\n\n/**\n * Parse the platform's settlement idempotency key.\n *\n * The platform mints it as `sandbox:<kind>:<resourceId>:<intervalStart>`\n * (`d1-usage-service.ts`), where `intervalStart` is the interval cursor in epoch\n * ms — the SAME `last_started_at` the settlement subtracts from to get its\n * billed duration. That makes this string the only place a consumer can read the\n * billed interval's start, because the ledger row itself stores no duration.\n *\n * Kinds seen in production: `stop` (an interval closing), `compute` (a heartbeat\n * claim), `egress`, `gpu-lease`. `stop` deliberately covers both a settle and a\n * late stop racing over the same claim, so the two derive one reference id and\n * the ledger's uniqueness constraint makes the overlap safe.\n *\n * Returns null for anything that is not a sandbox reference — a router\n * inference row, a grant, a refund — rather than guessing.\n */\nexport function parseSettlementReference(referenceId: string | null | undefined): SettlementReference | null {\n  if (!referenceId) return null\n  const parts = referenceId.split(':')\n  if (parts.length < 3 || parts[0] !== 'sandbox') return null\n  const kind = parts[1]\n  if (!kind) return null\n\n  // The trailing segment is the interval cursor ONLY when it reads as an epoch\n  // instant. `sandbox:gpu-lease:<leaseId>` has no cursor, and a resource id that\n  // happened to contain a colon must not have its tail eaten as one.\n  const tail = parts[parts.length - 1] as string\n  const tailMs = /^\\d+$/.test(tail) ? Number(tail) : Number.NaN\n  const hasCursor = parts.length >= 4 && Number.isSafeInteger(tailMs) && tailMs > 0\n\n  const resourceId = hasCursor ? parts.slice(2, -1).join(':') : parts.slice(2).join(':')\n  if (!resourceId) return null\n\n  return { kind, resourceId, intervalStartMs: hasCursor ? tailMs : null }\n}\n\n/**\n * Read the sandbox id out of the platform's aggregation key, `sandbox:<id>`.\n *\n * Distinct from the reference id: `groupKey` is the unit a billing statement\n * groups by and is deliberately NOT unique per row, while `referenceId` is\n * unique per interval. A null group key means \"do not aggregate\" (grants,\n * top-ups, refunds, transfers) and is not an error.\n */\nexport function parseSandboxGroupKey(groupKey: string | null | undefined): string | null {\n  if (!groupKey) return null\n  const parts = groupKey.split(':')\n  if (parts.length < 2 || parts[0] !== 'sandbox') return null\n  const id = parts.slice(1).join(':')\n  return id || null\n}\n\n/**\n * The sandbox a settlement row is attributable to.\n *\n * The reference id wins over the group key because it is the field the platform\n * dedups on, so it is the one guaranteed present and correct on a compute\n * settlement; the group key is the fallback for rows written before a producer\n * stamped a reference, and for kinds whose reference names something else (a GPU\n * lease id, not a box).\n */\nexport function settlementSandboxId(row: SettlementRow): string | null {\n  const reference = parseSettlementReference(row.referenceId)\n  if (reference && reference.intervalStartMs !== null) return reference.resourceId\n  return parseSandboxGroupKey(row.groupKey) ?? (reference ? reference.resourceId : null)\n}\n\n/** True when a row is a charge (the ledger stores charges as negative amounts). */\nexport function isCharge(row: SettlementRow): boolean {\n  return row.amountNanoUsd < 0\n}\n\n/** A charge's magnitude in unsigned nanodollars; 0 for credits. */\nexport function chargeNanoUsd(row: SettlementRow): number {\n  return row.amountNanoUsd < 0 ? -row.amountNanoUsd : 0\n}\n","import { DEFAULT_CEILING_TOLERANCE_MS, computeExpectedCeiling } from './ceiling'\nimport { chargeNanoUsd, parseSettlementReference, settlementSandboxId } from './reference'\nimport type { SpendLedgerStorePort } from './store'\nimport {\n  SPEND_CHECKS,\n  type BilledDurationBasis,\n  type CeilingBasis,\n  type SettlementRow,\n  type SpendBoxRecord,\n  type SpendCheckId,\n  type SpendFinding,\n  type SpendReport,\n} from './types'\n\n/** How many nanodollars in one US dollar. The ledger's unit. */\nconst NANO_PER_USD = 1_000_000_000\nconst MS_PER_HOUR = 3_600_000\n\nexport interface VelocityOptions {\n  /** Bucket width for a spend window, ms. Default 24 h. */\n  readonly windowMs?: number\n  /** Fire when a window exceeds this multiple of the trailing median. Default 5. */\n  readonly multiple?: number\n  /**\n   * Windows of history required before a median means anything. Default 3.\n   * Below this the rule stays silent, so a product's genuine first days of\n   * usage are not reported as an anomaly.\n   */\n  readonly minTrailingWindows?: number\n  /**\n   * A window under this never fires, whatever the ratio. Default $1.00.\n   *\n   * Without a floor the rule is useless: a trailing median of a tenth of a cent\n   * makes every ordinary day a 5x outlier. $1.00 is set from the incident's own\n   * distribution — the smallest of the eight affected wallets took $1.98, and\n   * the two rows in the same window that were GENUINE were sub-cent. So the\n   * floor sits above the noise and below every real finding.\n   */\n  readonly minAbsoluteNanoUsd?: number\n}\n\nconst DEFAULT_VELOCITY: Required<VelocityOptions> = {\n  windowMs: 86_400_000,\n  multiple: 5,\n  minTrailingWindows: 3,\n  minAbsoluteNanoUsd: NANO_PER_USD,\n}\n\n/** The balance the product observes, and the floor it must not cross. */\nexport interface ObservedBalance {\n  /** Signed nanodollars, as the platform reports it. */\n  readonly nanoUsd: number\n  /** Below this is a finding. Default 0. */\n  readonly floorNanoUsd?: number\n}\n\n/**\n * A box's price, nanodollars per hour, used to derive an EXACT billed duration\n * from a charge. Return null when the product does not know the box's rate; the\n * reconciler then falls back to the reference span.\n */\nexport type BoxRateResolver = (record: SpendBoxRecord | null, sandboxId: string) => number | null | undefined\n\nexport interface ReconcileSpendOptions {\n  /**\n   * Settled ledger rows, supplied by the product's own authenticated fetch.\n   *\n   * MUST be scoped to boxes this product owns. Products bill to a shared company\n   * key, so an unscoped fetch returns every sibling product's settlements and\n   * every one is a correct — and useless — `unknown-box` finding.\n   */\n  readonly rows: readonly SettlementRow[]\n  /** The product's expectation ledger. */\n  readonly store: SpendLedgerStorePort\n  /** Treated as \"now\". Default `Date.now()`. */\n  readonly asOf?: number\n  /** Ceiling slack. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */\n  readonly toleranceMs?: number\n  /** Box price, for the exact duration basis. A number applies to every box. */\n  readonly nanoUsdPerHour?: number | BoxRateResolver\n  /** Velocity tuning, or `false` to skip the rule. */\n  readonly velocity?: VelocityOptions | false\n  /** The workspace balance, when the product can see one. Omitted skips the rule. */\n  readonly balance?: ObservedBalance\n  /** Stamped onto findings so an alert names the tenant. */\n  readonly workspaceId?: string\n  /** Checks to leave out of this pass. */\n  readonly skip?: readonly SpendCheckId[]\n}\n\nfunction usd(nano: number): string {\n  return `$${(nano / NANO_PER_USD).toFixed(2)}`\n}\n\nfunction hours(ms: number): string {\n  return `${(ms / MS_PER_HOUR).toFixed(1)}h`\n}\n\n/** Trust order, least trustworthy first — a mixed aggregate reports the weakest. */\nconst BASIS_TRUST: readonly BilledDurationBasis[] = ['unknown', 'reference-span', 'rate', 'reported']\n\nfunction weakestBasis(a: BilledDurationBasis, b: BilledDurationBasis): BilledDurationBasis {\n  return BASIS_TRUST.indexOf(a) <= BASIS_TRUST.indexOf(b) ? a : b\n}\n\n/**\n * How long one settlement billed for, and how confidently we know it.\n *\n * The ledger row does not store a duration — this is the whole reason the check\n * is subtle. Three ways to recover it, best first:\n *\n * 1. `reported` — the product's ledger view exposed it. Exact.\n * 2. `rate` — `charge / pricePerHour`. Exact, because the platform computes the\n *    charge as `(durationMs / 3_600_000) * costPerHour` and nothing else enters\n *    it. Requires the product to know its box's price.\n * 3. `reference-span` — `settledAt - intervalStart`, both read off the row. An\n *    UPPER bound, not the duration: a correct settlement delayed by the\n *    platform's durable settlement queue reads longer here than it billed. It is\n *    exact for the failure this module exists to catch, because billing \"up to\n *    now\" makes the settlement instant and the interval end the same moment.\n */\nfunction resolveBilledMs(\n  row: SettlementRow,\n  ratePerHourNano: number | null,\n): { ms: number; basis: BilledDurationBasis } {\n  if (row.billedMs !== null) return { ms: row.billedMs, basis: 'reported' }\n\n  const charge = chargeNanoUsd(row)\n  if (ratePerHourNano !== null && ratePerHourNano > 0 && charge > 0) {\n    return { ms: (charge / ratePerHourNano) * MS_PER_HOUR, basis: 'rate' }\n  }\n\n  const reference = parseSettlementReference(row.referenceId)\n  if (reference?.intervalStartMs != null && row.createdAt > reference.intervalStartMs) {\n    return { ms: row.createdAt - reference.intervalStartMs, basis: 'reference-span' }\n  }\n\n  return { ms: 0, basis: 'unknown' }\n}\n\nfunction median(values: readonly number[]): number {\n  if (values.length === 0) return 0\n  const sorted = [...values].sort((a, b) => a - b)\n  const mid = Math.floor(sorted.length / 2)\n  if (sorted.length % 2 === 1) return sorted[mid] as number\n  return (((sorted[mid - 1] as number) + (sorted[mid] as number)) / 2)\n}\n\nfunction emptyFinding(check: SpendCheckId): Omit<SpendFinding, 'message' | 'remedy'> {\n  return {\n    check,\n    sandboxId: null,\n    workspaceId: null,\n    referenceIds: [],\n    settledNanoUsd: 0,\n    settledMs: null,\n    durationBasis: null,\n    ceilingMs: null,\n    overageMs: null,\n    ceilingBasis: null,\n    windowNanoUsd: null,\n    trailingMedianNanoUsd: null,\n    velocityRatio: null,\n    windowStartAt: null,\n    balanceNanoUsd: null,\n    balanceFloorNanoUsd: null,\n  }\n}\n\n/**\n * Diff what the platform charged against what the product believes it asked for.\n *\n * Never disputes anything and never writes: the output is a report a human acts\n * on. The platform's ledger stays authoritative — this only ever produces the\n * evidence for a conversation with it.\n */\nexport async function reconcileSpend(options: ReconcileSpendOptions): Promise<SpendReport> {\n  const asOf = options.asOf ?? Date.now()\n  const toleranceMs = options.toleranceMs ?? DEFAULT_CEILING_TOLERANCE_MS\n  const workspaceId = options.workspaceId ?? null\n  const skip = new Set(options.skip ?? [])\n  const checksRun = SPEND_CHECKS.filter((check) => !skip.has(check))\n  const runs = (check: SpendCheckId): boolean => !skip.has(check)\n\n  const findings: SpendFinding[] = []\n  let settledNanoUsd = 0\n  let creditedNanoUsd = 0\n\n  // ── group charges by the box they are attributable to ──────────────────────\n  const byBox = new Map<string, SettlementRow[]>()\n  for (const row of options.rows) {\n    if (row.amountNanoUsd < 0) settledNanoUsd += -row.amountNanoUsd\n    else creditedNanoUsd += row.amountNanoUsd\n    if (row.amountNanoUsd >= 0) continue\n    const sandboxId = settlementSandboxId(row)\n    if (!sandboxId) continue\n    const bucket = byBox.get(sandboxId)\n    if (bucket) bucket.push(row)\n    else byBox.set(sandboxId, [row])\n  }\n\n  const rateOf = (record: SpendBoxRecord | null, sandboxId: string): number | null => {\n    const rate = options.nanoUsdPerHour\n    if (rate === undefined) return null\n    if (typeof rate === 'number') return rate\n    return rate(record, sandboxId) ?? null\n  }\n\n  for (const [sandboxId, rows] of byBox) {\n    const record = await options.store.load(sandboxId)\n    const referenceIds = rows.map((row) => row.referenceId ?? row.id)\n    const charged = rows.reduce((sum, row) => sum + chargeNanoUsd(row), 0)\n\n    // ── unknown-box ──────────────────────────────────────────────────────────\n    if (!record) {\n      if (runs('unknown-box')) {\n        findings.push({\n          ...emptyFinding('unknown-box'),\n          sandboxId,\n          workspaceId,\n          referenceIds,\n          settledNanoUsd: charged,\n          message:\n            `${usd(charged)} settled across ${rows.length} row(s) against sandbox ${sandboxId}, ` +\n            'which this product has no record of ever asking for.',\n          remedy:\n            'Either the fetch is not scoped to this product\\'s own boxes (fix the scope — a shared ' +\n            'billing key returns every sibling product\\'s settlements), or a box was provisioned ' +\n            'outside the recorded seam, or the platform billed a box that is not ours. Identify ' +\n            `which by looking up ${sandboxId} on the platform before disputing.`,\n        })\n      }\n      continue\n    }\n\n    // ── over-ceiling ─────────────────────────────────────────────────────────\n    if (!runs('over-ceiling')) continue\n\n    const ceiling = computeExpectedCeiling(record, { asOf, toleranceMs })\n    const ratePerHourNano = rateOf(record, sandboxId)\n\n    let settledMs = 0\n    let basis: BilledDurationBasis = 'reported'\n    let anyMeasured = false\n    for (const row of rows) {\n      const resolved = resolveBilledMs(row, ratePerHourNano)\n      if (resolved.basis === 'unknown') {\n        basis = weakestBasis(basis, 'unknown')\n        continue\n      }\n      anyMeasured = true\n      settledMs += resolved.ms\n      basis = weakestBasis(basis, resolved.basis)\n    }\n    if (!anyMeasured) continue\n    if (settledMs <= ceiling.ceilingMs) continue\n\n    const overageMs = settledMs - ceiling.ceilingMs\n    const confidence = ceiling.bounded\n      ? ''\n      : ' The product could not bound this box from its own observations (an unfinished detached ' +\n        'run, and no max lifetime), so the ceiling rests on the reconciliation instant: this ' +\n        'settlement bills time outside the box\\'s own life, not merely more than expected.'\n    const spanCaveat =\n      basis === 'reference-span'\n        ? ' Duration is derived from the settlement instant minus the interval start, which ' +\n          'overstates a settlement the platform merely posted late — confirm before disputing.'\n        : ''\n\n    findings.push({\n      ...emptyFinding('over-ceiling'),\n      sandboxId,\n      workspaceId: record.workspaceId || workspaceId,\n      referenceIds,\n      settledNanoUsd: charged,\n      settledMs,\n      durationBasis: basis,\n      ceilingMs: ceiling.ceilingMs,\n      overageMs,\n      ceilingBasis: ceiling.basis,\n      message:\n        `Sandbox ${sandboxId} settled ${hours(settledMs)} (${usd(charged)}) across ${rows.length} ` +\n        `row(s), against an expected ceiling of ${hours(ceiling.ceilingMs)} — over by ` +\n        `${hours(overageMs)}. Ceiling basis: ${ceiling.basis}; duration basis: ${basis}.` +\n        confidence +\n        spanCaveat,\n      remedy:\n        `Dispute ${referenceIds.join(', ')} against the platform ledger with both numbers. ` +\n        (ceiling.basis === 'stopped' || ceiling.basis === 'deleted'\n          ? 'The product recorded this box as no longer running before the billed time ended, so ' +\n            'either the stop did not take or the interval was settled at the wrong boundary.'\n          : 'Freeze the open interval before anything deletes this box — deleting a box with an ' +\n            'open compute interval settles the whole gap at once.'),\n    })\n  }\n\n  // ── velocity ───────────────────────────────────────────────────────────────\n  if (runs('velocity') && options.velocity !== false) {\n    const cfg = { ...DEFAULT_VELOCITY, ...(options.velocity ?? {}) }\n    const buckets = new Map<number, { nano: number; references: string[] }>()\n    for (const row of options.rows) {\n      const charge = chargeNanoUsd(row)\n      if (charge === 0) continue\n      const bucketStart = Math.floor(row.createdAt / cfg.windowMs) * cfg.windowMs\n      const bucket = buckets.get(bucketStart)\n      if (bucket) {\n        bucket.nano += charge\n        bucket.references.push(row.referenceId ?? row.id)\n      } else {\n        buckets.set(bucketStart, { nano: charge, references: [row.referenceId ?? row.id] })\n      }\n    }\n\n    const ordered = [...buckets.entries()].sort((a, b) => a[0] - b[0])\n    for (let i = 0; i < ordered.length; i++) {\n      const entry = ordered[i]\n      if (!entry) continue\n      const [windowStartAt, bucket] = entry\n      if (i < cfg.minTrailingWindows) continue\n      const trailing = ordered.slice(0, i).map(([, prior]) => prior.nano)\n      const trailingMedian = median(trailing)\n      const threshold = Math.max(trailingMedian * cfg.multiple, cfg.minAbsoluteNanoUsd)\n      if (bucket.nano <= threshold) continue\n      const ratio = trailingMedian > 0 ? bucket.nano / trailingMedian : Number.POSITIVE_INFINITY\n\n      findings.push({\n        ...emptyFinding('velocity'),\n        workspaceId,\n        referenceIds: bucket.references,\n        settledNanoUsd: bucket.nano,\n        windowNanoUsd: bucket.nano,\n        trailingMedianNanoUsd: trailingMedian,\n        velocityRatio: ratio,\n        windowStartAt,\n        message:\n          `${usd(bucket.nano)} settled in the window starting ${new Date(windowStartAt).toISOString()} ` +\n          `across ${bucket.references.length} row(s), against a trailing median of ` +\n          `${usd(trailingMedian)} over ${trailing.length} prior window(s) — ` +\n          `${Number.isFinite(ratio) ? `${ratio.toFixed(1)}x` : 'no prior spend to compare against'}, ` +\n          `over the ${cfg.multiple}x threshold.`,\n        remedy:\n          'A burst of this shape is what a settlement defect looks like from the consumer side: ' +\n          'long-dormant intervals cashed out at once. Check whether these rows carry interval ' +\n          'starts far older than the settlement instant before treating it as real usage.',\n      })\n    }\n  }\n\n  // ── negative-balance ───────────────────────────────────────────────────────\n  if (runs('negative-balance') && options.balance) {\n    const floor = options.balance.floorNanoUsd ?? 0\n    if (options.balance.nanoUsd < floor) {\n      findings.push({\n        ...emptyFinding('negative-balance'),\n        workspaceId,\n        settledNanoUsd: Math.max(0, floor - options.balance.nanoUsd),\n        balanceNanoUsd: options.balance.nanoUsd,\n        balanceFloorNanoUsd: floor,\n        message:\n          `Observed balance ${usd(options.balance.nanoUsd)} is below the floor ${usd(floor)}.`,\n        remedy:\n          'Stop provisioning new compute for this owner until the balance is explained. A negative ' +\n          'balance that nobody is watching is how a billing defect becomes settled money.',\n      })\n    }\n  }\n\n  return {\n    ok: findings.length === 0,\n    findings,\n    checksRun,\n    rowsExamined: options.rows.length,\n    boxesExamined: byBox.size,\n    settledNanoUsd,\n    creditedNanoUsd,\n    asOf,\n  }\n}\n","import type { SpendFinding, SpendReport } from './types'\n\nconst NANO_PER_USD = 1_000_000_000\n\nfunction usd(nano: number | null): string {\n  return nano === null ? '—' : `$${(nano / NANO_PER_USD).toFixed(2)}`\n}\n\n/**\n * Render a reconciliation for a human deciding whether to open a dispute.\n *\n * Every finding prints its numbers, not a summary of them: the reader's next\n * action is a conversation with the platform about specific reference ids, and a\n * report that made them re-derive the durations would just be re-read alongside\n * the raw rows anyway.\n */\nexport function formatSpendReport(report: SpendReport): string {\n  const lines: string[] = []\n  lines.push(\n    `spend reconciliation — ${report.rowsExamined} row(s), ${report.boxesExamined} box(es), ` +\n      `${usd(report.settledNanoUsd)} charged, ${usd(report.creditedNanoUsd)} credited, ` +\n      `as of ${new Date(report.asOf).toISOString()}`,\n  )\n  lines.push(`checks: ${report.checksRun.join(', ') || '(none)'}`)\n\n  if (report.ok) {\n    lines.push('')\n    lines.push('OK — no discrepancy between the product\\'s expectations and the settled ledger.')\n    return lines.join('\\n')\n  }\n\n  lines.push('')\n  lines.push(`${report.findings.length} finding(s):`)\n  for (const finding of report.findings) {\n    lines.push('')\n    lines.push(`  [${finding.check}] ${finding.message}`)\n    for (const [label, value] of measuredFields(finding)) lines.push(`    ${label}: ${value}`)\n    if (finding.referenceIds.length > 0) {\n      lines.push(`    rows: ${finding.referenceIds.join(', ')}`)\n    }\n    lines.push(`    → ${finding.remedy}`)\n  }\n  return lines.join('\\n')\n}\n\n/** Every measured field a finding carries, including the ones it left null. */\nfunction measuredFields(finding: SpendFinding): Array<[string, string]> {\n  const ms = (value: number | null): string =>\n    value === null ? '—' : `${(value / 3_600_000).toFixed(2)}h`\n  return [\n    ['sandbox', finding.sandboxId ?? '—'],\n    ['workspace', finding.workspaceId ?? '—'],\n    ['amount', usd(finding.settledNanoUsd)],\n    ['settled', ms(finding.settledMs)],\n    ['ceiling', ms(finding.ceilingMs)],\n    ['overage', ms(finding.overageMs)],\n    ['ceiling basis', finding.ceilingBasis ?? '—'],\n    ['duration basis', finding.durationBasis ?? '—'],\n    ['window', finding.windowStartAt === null ? '—' : new Date(finding.windowStartAt).toISOString()],\n    ['window spend', usd(finding.windowNanoUsd)],\n    ['trailing median', usd(finding.trailingMedianNanoUsd)],\n    ['ratio', finding.velocityRatio === null ? '—' : `${finding.velocityRatio.toFixed(1)}x`],\n    ['balance', usd(finding.balanceNanoUsd)],\n    ['balance floor', usd(finding.balanceFloorNanoUsd)],\n  ]\n}\n\n/** The report as a plain JSON value, for an alerting pipeline. */\nexport function spendReportToJson(report: SpendReport): string {\n  return JSON.stringify(report, null, 2)\n}\n"],"mappings":"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","names":["NANO_PER_USD","usd"]}