@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/spend/liveness.d.ts

@@ -0,0 +1,131 @@
+import type { SpendBoxLiveness, SpendBoxRecord, SpendExpectationSummary, SpendReport, SpendWindow } from './types';
+/**
+ * Expectation liveness: what the product BELIEVES it should have been billed for.
+ *
+ * ## The hole this closes
+ *
+ * `reconcileSpend` compares settlements against expectations, and every one of
+ * its rules is driven by a settlement row. That makes it able to answer exactly
+ * one direction of the question:
+ *
+ * > were we billed for something we did not ask for, or for more than allowed?
+ *
+ * It cannot answer the other direction — *were we NOT billed for something we
+ * DID ask for* — because with no row there is nothing to iterate. Three real
+ * shapes fall straight through that hole and every one of them renders as a
+ * clean bill:
+ *
+ * - the expectation ledger names no box, so the pass examines nobody → `ok:true`;
+ * - the billing endpoint quietly starts returning zero rows → `ok:true`,
+ *   `rowsExamined:0`;
+ * - a stale or rotated key list excludes every box → `ok:true` with everything
+ *   `foreign`.
+ *
+ * In all three the check stopped checking while looking green. That is the exact
+ * failure class the module exists to prevent, reproduced inside the module.
+ *
+ * ## The discriminator, and why it is not a new store
+ *
+ * The expectation ledger already records the only fact needed: when the product
+ * first saw a box (`createdAt`), the last work it observed (`lastActivityAt`),
+ * and any stop or delete it knows about. Those are precisely the inputs
+ * {@link computeExpectedCeiling} already folds into a horizon — the latest
+ * instant a box could still have been billable. So a box's LIVE INTERVAL is
+ * `[createdAt, horizon]`, derived from the same fold the ceiling uses rather
+ * than from a second, drift-prone definition of "running".
+ *
+ * A box whose live interval overlaps the reconciliation window is a box the
+ * product expected to be billed for. The absence of a settlement against it is
+ * then a first-class outcome, not silence.
+ *
+ * ## Why the grace period is load-bearing
+ *
+ * Settlement lags provisioning. A box that came up ninety seconds before the
+ * window closed has no settlement yet and never should have — expecting one
+ * would manufacture a finding out of the platform's ordinary queue behaviour.
+ * So expectation is asserted only for boxes with at least
+ * {@link DEFAULT_EXPECTATION_GRACE_MS} of live time INSIDE the window, which is
+ * the platform's own declared-normal settlement lag (see the constant).
+ *
+ * The asymmetry the rest of the module runs on holds here too, but it points the
+ * other way and that is deliberate: an over-tight liveness derivation produces a
+ * false ALARM about the check, never a false clean bill. Nothing in this file
+ * can make a report cleaner than it would otherwise be.
+ */
+/**
+ * How much live time a box needs inside the window before a settlement is
+ * EXPECTED for it. 15 minutes.
+ *
+ * Same number and same justification as {@link DEFAULT_CEILING_TOLERANCE_MS},
+ * arrived at from the other side: the platform's runbook clears a compute
+ * settlement incident when `/health computeSettlement.oldestAgeSeconds` is "back
+ * under 900", so 900 s is lag the platform has already declared normal. A box
+ * live for less than that inside the window may legitimately have settled
+ * nothing yet, and demanding a row for it would report the platform's own queue
+ * as a defect.
+ *
+ * A caller parameter, because a product reconciling a very short window must
+ * shrink it or the window expects nothing at all.
+ */
+export declare const DEFAULT_EXPECTATION_GRACE_MS = 900000;
+/** Options for {@link boxLivenessInWindow}. */
+export interface BoxLivenessOptions {
+    /** Live ms inside the window before a settlement is expected. Default {@link DEFAULT_EXPECTATION_GRACE_MS}. */
+    readonly graceMs?: number;
+}
+/** Reject a window that cannot be reconciled, rather than examining nobody inside it. */
+export declare function assertSpendWindow(window: SpendWindow): void;
+/**
+ * One box's live interval, and whether the product should have been billed for
+ * it inside this window.
+ *
+ * The live interval's end is {@link computeExpectedCeiling}'s horizon evaluated
+ * at the window's end — the SAME derivation the ceiling check uses, so a box
+ * cannot be considered live here and dead there. `toleranceMs` is zero because
+ * tolerance is slack allowed to the PLATFORM's clock, and widening a box's life
+ * by it would expect settlements for boxes that were already gone.
+ */
+export declare function boxLivenessInWindow(record: SpendBoxRecord, window: SpendWindow, options?: BoxLivenessOptions): SpendBoxLiveness;
+/** Why {@link assessAllExcluded} answered the way it did. */
+export type AllExcludedBasis = 
+/** Not every box was excluded — the pass examined some of this product's own. */
+'not-all-excluded'
+/** Boxes of this product's were live in the window, so an all-foreign pass is wrong. */
+ | 'expected-boxes-live'
+/** Expectation was declared and nothing was live: an idle product, not a defect. */
+ | 'nothing-expected'
+/** No expectation was declared, so the question cannot be answered. Fails closed. */
+ | 'not-declared';
+/** {@link assessAllExcluded}'s verdict, with the reason a pager message needs. */
+export interface AllExcludedAssessment {
+    /** True when the caller should raise. */
+    readonly pathological: boolean;
+    readonly basis: AllExcludedBasis;
+    /** One sentence naming the numbers behind the verdict. */
+    readonly reason: string;
+}
+/**
+ * Should "we saw settlements but none of them were ours" page a human?
+ *
+ * Consumers raise this pathology on `boxesExamined > 0 && ownedBoxes === 0`.
+ * That shape has two completely different causes and the naive test cannot tell
+ * them apart:
+ *
+ * - an ownership rule that has gone stale — a rotated key, a new deployment key
+ *   nobody added — so every one of the product's OWN boxes now reads as a
+ *   sibling's. The check has stopped checking.
+ * - a product that was legitimately idle while a sibling settled on the same
+ *   wallet. Nothing is wrong, and paging on it pages EVERY day the product is
+ *   quiet, which is how a real alert gets muted.
+ *
+ * The discriminator is expectation liveness: did this product have a box alive
+ * during the window? Only then is an all-excluded pass pathological.
+ *
+ * Fails closed when no expectation was declared — that is today's behaviour, and
+ * a pass that cannot answer the question must not answer it optimistically. The
+ * `reason` says so, and the fix (declare `window`, implement `listLiveBetween`)
+ * is in the string a human reads.
+ */
+export declare function assessAllExcluded(report: SpendReport): AllExcludedAssessment;
+/** The expectation summary a pass that declared none reports. Loud, never absent. */
+export declare function undeclaredExpectation(graceMs: number): SpendExpectationSummary;

package/dist/spend/ownership.d.ts

@@ -0,0 +1,87 @@
+import type { SettlementRow, SpendOwnershipRule, SpendOwnershipVerdict } from './types';
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function decideBoxOwnership(rule: SpendOwnershipRule, sandboxId: string, rows: readonly SettlementRow[]): SpendOwnershipVerdict;

package/dist/spend/reconcile.d.ts

@@ -0,0 +1,109 @@
+import type { SpendLedgerStorePort } from './store';
+import { type SettlementRow, type SpendBoxRecord, type SpendCheckId, type SpendOwnershipRule, type SpendReport, type SpendWindow } from './types';
+export interface VelocityOptions {
+    /** Bucket width for a spend window, ms. Default 24 h. */
+    readonly windowMs?: number;
+    /** Fire when a window exceeds this multiple of the trailing median. Default 5. */
+    readonly multiple?: number;
+    /**
+     * Windows of history required before a median means anything. Default 3.
+     * Below this the rule stays silent, so a product's genuine first days of
+     * usage are not reported as an anomaly.
+     */
+    readonly minTrailingWindows?: number;
+    /**
+     * A window under this never fires, whatever the ratio. Default $1.00.
+     *
+     * Without a floor the rule is useless: a trailing median of a tenth of a cent
+     * makes every ordinary day a 5x outlier. $1.00 is set from the incident's own
+     * distribution — the smallest of the eight affected wallets took $1.98, and
+     * the two rows in the same window that were GENUINE were sub-cent. So the
+     * floor sits above the noise and below every real finding.
+     */
+    readonly minAbsoluteNanoUsd?: number;
+}
+/** The balance the product observes, and the floor it must not cross. */
+export interface ObservedBalance {
+    /** Signed nanodollars, as the platform reports it. */
+    readonly nanoUsd: number;
+    /** Below this is a finding. Default 0. */
+    readonly floorNanoUsd?: number;
+}
+/**
+ * A box's price, nanodollars per hour, used to derive an EXACT billed duration
+ * from a charge. Return null when the product does not know the box's rate; the
+ * reconciler then falls back to the reference span.
+ */
+export type BoxRateResolver = (record: SpendBoxRecord | null, sandboxId: string) => number | null | undefined;
+export interface ReconcileSpendOptions {
+    /**
+     * Settled ledger rows, supplied by the product's own authenticated fetch.
+     *
+     * 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}. */
+    readonly toleranceMs?: number;
+    /** Box price, for the exact duration basis. A number applies to every box. */
+    readonly nanoUsdPerHour?: number | BoxRateResolver;
+    /** Velocity tuning, or `false` to skip the rule. */
+    readonly velocity?: VelocityOptions | false;
+    /** The workspace balance, when the product can see one. Omitted skips the rule. */
+    readonly balance?: ObservedBalance;
+    /** Stamped onto findings so an alert names the tenant. */
+    readonly workspaceId?: string;
+    /** Checks to leave out of this pass. */
+    readonly skip?: readonly SpendCheckId[];
+    /**
+     * The stretch of time these `rows` were fetched for.
+     *
+     * Declaring it — together with a store that implements `listLiveBetween` — is
+     * what lets the pass answer the direction every settlement-driven rule is
+     * blind to: *were we NOT billed for something we DID ask for*. The expectation
+     * ledger already holds the answer; nothing new is stored for it.
+     *
+     * Omitting it is additive and changes no existing finding. It is not silent:
+     * `report.expectation.declared` is `false`, `formatSpendReport` prints
+     * `expectation: NOT DECLARED` above the findings, and a pass that also
+     * examined none of this product's settlements reports `coverage: 'unverified'`
+     * and cannot render as a clean bill.
+     */
+    readonly window?: SpendWindow;
+    /**
+     * Live ms a box needs inside the window before a settlement is EXPECTED of it.
+     * Default {@link DEFAULT_EXPECTATION_GRACE_MS} (15 min — the platform's own
+     * declared-normal settlement lag). Shrink it for a short window.
+     */
+    readonly expectationGraceMs?: number;
+}
+/**
+ * Diff what the platform charged against what the product believes it asked for.
+ *
+ * Never disputes anything and never writes: the output is a report a human acts
+ * on. The platform's ledger stays authoritative — this only ever produces the
+ * evidence for a conversation with it.
+ */
+export declare function reconcileSpend(options: ReconcileSpendOptions): Promise<SpendReport>;

package/dist/spend/reference.d.ts

@@ -0,0 +1,42 @@
+import type { SettlementReference, SettlementRow } from './types';
+/**
+ * Parse the platform's settlement idempotency key.
+ *
+ * The platform mints it as `sandbox:<kind>:<resourceId>:<intervalStart>`
+ * (`d1-usage-service.ts`), where `intervalStart` is the interval cursor in epoch
+ * ms — the SAME `last_started_at` the settlement subtracts from to get its
+ * billed duration. That makes this string the only place a consumer can read the
+ * billed interval's start, because the ledger row itself stores no duration.
+ *
+ * Kinds seen in production: `stop` (an interval closing), `compute` (a heartbeat
+ * claim), `egress`, `gpu-lease`. `stop` deliberately covers both a settle and a
+ * late stop racing over the same claim, so the two derive one reference id and
+ * the ledger's uniqueness constraint makes the overlap safe.
+ *
+ * Returns null for anything that is not a sandbox reference — a router
+ * inference row, a grant, a refund — rather than guessing.
+ */
+export declare function parseSettlementReference(referenceId: string | null | undefined): SettlementReference | null;
+/**
+ * Read the sandbox id out of the platform's aggregation key, `sandbox:<id>`.
+ *
+ * Distinct from the reference id: `groupKey` is the unit a billing statement
+ * groups by and is deliberately NOT unique per row, while `referenceId` is
+ * unique per interval. A null group key means "do not aggregate" (grants,
+ * top-ups, refunds, transfers) and is not an error.
+ */
+export declare function parseSandboxGroupKey(groupKey: string | null | undefined): string | null;
+/**
+ * The sandbox a settlement row is attributable to.
+ *
+ * The reference id wins over the group key because it is the field the platform
+ * dedups on, so it is the one guaranteed present and correct on a compute
+ * settlement; the group key is the fallback for rows written before a producer
+ * stamped a reference, and for kinds whose reference names something else (a GPU
+ * lease id, not a box).
+ */
+export declare function settlementSandboxId(row: SettlementRow): string | null;
+/** True when a row is a charge (the ledger stores charges as negative amounts). */
+export declare function isCharge(row: SettlementRow): boolean;
+/** A charge's magnitude in unsigned nanodollars; 0 for credits. */
+export declare function chargeNanoUsd(row: SettlementRow): number;

package/dist/spend/report.d.ts

@@ -0,0 +1,12 @@
+import type { SpendReport } from './types';
+/**
+ * Render a reconciliation for a human deciding whether to open a dispute.
+ *
+ * Every finding prints its numbers, not a summary of them: the reader's next
+ * action is a conversation with the platform about specific reference ids, and a
+ * report that made them re-derive the durations would just be re-read alongside
+ * the raw rows anyway.
+ */
+export declare function formatSpendReport(report: SpendReport): string;
+/** The report as a plain JSON value, for an alerting pipeline. */
+export declare function spendReportToJson(report: SpendReport): string;

package/dist/spend/store.d.ts

@@ -0,0 +1,123 @@
+import type { SpendBoxPatch, SpendBoxRecord, SpendWindow } from './types';
+/**
+ * Persistence seam for the expectation ledger — the product implements it over
+ * its own tables.
+ *
+ * Deliberately NOT compare-and-set, unlike `MissionStorePort`. A mission has one
+ * serialized owner and a lost write corrupts a state machine; a box record is a
+ * MONOTONIC FOLD (activity takes a max, a detached-run id joins or leaves a set,
+ * delete is set-once) so concurrent writers converge no matter what order they
+ * land in. The worst a lost race can do here is leave `lastActivityAt` behind
+ * the truth — which makes the derived ceiling TIGHTER, so the failure mode is a
+ * false alarm a human dismisses, never a missed charge. That asymmetry is the
+ * whole reason the fold is shaped this way.
+ *
+ * `update` returns null when the row does not exist, never a throw.
+ */
+export interface SpendLedgerStorePort {
+    load(sandboxId: string): Promise<SpendBoxRecord | null>;
+    /** `extras` are the opaque product-column values — write them in the SAME
+     *  statement as the record, or ignore them if the table has no extra columns. */
+    insert(record: SpendBoxRecord, extras?: Record<string, unknown>): Promise<SpendBoxRecord>;
+    update(sandboxId: string, patch: SpendBoxPatch): Promise<SpendBoxRecord | null>;
+    /**
+     * OPTIONAL — every box that could have been live during the window.
+     *
+     * This is the one capability that lets a reconciliation answer "were we NOT
+     * billed for something we DID ask for". Without it the pass is driven entirely
+     * by settlement rows, so a feed that returns nothing fires nothing and reads
+     * as a clean bill. Omitting it is safe and additive: the pass reports
+     * `expectation.declared: false` and refuses to certify a bill it could not
+     * check (see {@link SpendReport.coverage}).
+     *
+     * **It may over-return.** The reconciler re-derives liveness itself with
+     * `boxLivenessInWindow`, so a store that returns every row it has is correct,
+     * merely slower. That is deliberate: the definition of "live" must live in one
+     * place, not once per product's SQL. The intended predicate is the coarse one
+     * a WHERE clause can express —
+     *
+     * ```sql
+     * WHERE created_at <= :endAt AND (deleted_at IS NULL OR deleted_at >= :startAt)
+     * ```
+     *
+     * — and the exact answer (idle timeout, max lifetime, stop, open detached run)
+     * is the reconciler's.
+     */
+    listLiveBetween?(window: SpendWindow): Promise<readonly SpendBoxRecord[]>;
+}
+/**
+ * Apply one fold step. Exported so a SQL implementation and an in-memory one
+ * reach the same record, and so a product can unit-test its own store against
+ * the canonical answer.
+ *
+ * The two rules worth stating out loud:
+ *
+ * - `observedActivityAt` only ever moves `lastActivityAt` FORWARD. A replayed
+ *   or out-of-order event cannot rewind the ceiling.
+ * - activity later than a recorded `stoppedAt` CLEARS the stop. A box that
+ *   worked after the product thought it stopped is running again, and keeping
+ *   the stale stop would make the ceiling too tight — inventing an over-ceiling
+ *   finding out of the product's own bookkeeping rather than the platform's.
+ */
+export declare function foldSpendBoxRecord(record: SpendBoxRecord, patch: SpendBoxPatch): SpendBoxRecord;
+/** An in-memory store that also lets a test inspect and force state. */
+export interface InMemorySpendLedgerStore extends SpendLedgerStorePort {
+    /** Every record, insertion order. */
+    records(): SpendBoxRecord[];
+    /** Unguarded direct write — simulates a crash-shaped or platform-seeded row. */
+    put(record: SpendBoxRecord): void;
+}
+/** Create an in-memory expectation ledger. Production writers use the same port. */
+export declare function createInMemorySpendLedgerStore(): InMemorySpendLedgerStore;
+/** What the product tells the ledger when it first sees a box. */
+export interface ObserveSandboxInput {
+    readonly sandboxId: string;
+    readonly workspaceId: string;
+    /** The idle timeout the product asked the platform for, seconds. */
+    readonly idleTimeoutSeconds: number;
+    /** The max lifetime the product asked for, seconds, when it asked for one. */
+    readonly maxLifetimeSeconds?: number | null;
+    /** Defaults to the ledger's clock. */
+    readonly at?: number;
+}
+export interface SpendLedgerOptions {
+    readonly store: SpendLedgerStorePort;
+    /** Injectable clock (epoch ms). Default `Date.now`. */
+    readonly now?: () => number;
+    /** Product columns written verbatim on every insert. */
+    readonly extras?: Record<string, unknown>;
+}
+/**
+ * The recording half of spend verification: the product's own account of what
+ * it asked the platform for.
+ *
+ * Every method is best-effort from the caller's point of view — a product wires
+ * these into paths that must not fail because bookkeeping failed. They still
+ * reject on a store error rather than swallowing it, so a caller that wants
+ * fire-and-forget says so at the call site (`/sandbox`'s hook does).
+ */
+export interface SpendLedger {
+    /**
+     * Record that a box exists and is billable from now. Inserts on first sight,
+     * and otherwise records activity — reuse and resume are both "the platform is
+     * charging for this box again", and the record's own existence is what
+     * distinguishes them, so no caller has to know which happened.
+     */
+    observeSandbox(input: ObserveSandboxInput): Promise<SpendBoxRecord>;
+    /** Record that the product saw this box do work. */
+    recordActivity(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>;
+    /**
+     * Record that the product handed the platform work it will NOT watch finish.
+     * Until the matching end is recorded, this box's ceiling cannot rest on
+     * observed activity — see `computeExpectedCeiling`.
+     */
+    recordDetachedRunStarted(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>;
+    /** Record that a detached run was confirmed finished. */
+    recordDetachedRunEnded(sandboxId: string, runId: string, at?: number): Promise<SpendBoxRecord | null>;
+    /** Record that the product knows this box stopped. */
+    recordStopped(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>;
+    /** Record that the product knows this box was deleted. */
+    recordDeleted(sandboxId: string, at?: number): Promise<SpendBoxRecord | null>;
+}
+/** Create the recording half over a product-supplied store. */
+export declare function createSpendLedger(options: SpendLedgerOptions): SpendLedger;