@tangle-network/agent-app 0.45.25 → 0.45.27

package/dist/spend/index.d.ts

@@ -0,0 +1,640 @@
+/**
+ * The vocabulary of consumer-side spend verification.
+ *
+ * Kept in its own module with ZERO imports so a product can type its storage
+ * rows and its reconciliation config without pulling in `node:fs` through the
+ * CLI half.
+ *
+ * The model in one paragraph: the platform's ledger is authoritative about what
+ * was CHARGED. A product knows something the ledger does not — what it ASKED
+ * for. Recording that second view, and diffing it against the first, is what
+ * turns a platform billing defect from silent money into an alert. Nothing here
+ * lets a product self-certify a charge away; the output is a discrepancy a human
+ * disputes.
+ */
+/**
+ * One box, as the PRODUCT understands it. Folded, not an append-only log: a
+ * product runs one row per sandbox, and every field below is derived by a
+ * monotonic fold (see `foldSpendBoxRecord`) so two concurrent writers cannot
+ * produce a wrong answer, only a stale one.
+ *
+ * Timestamps are epoch ms throughout, matching the platform's own
+ * `sandbox_meta.last_started_at`.
+ */
+interface SpendBoxRecord {
+    /** The platform's sandbox id — the join key to every settlement row. */
+    readonly sandboxId: string;
+    /** The product's own tenancy unit, which the platform does not model. */
+    readonly workspaceId: string;
+    /** First moment the product knew this box existed. */
+    readonly createdAt: number;
+    /**
+     * The idle timeout the product ASKED the platform for, seconds. This is the
+     * width of the grace window between the last thing the product saw and the
+     * moment the platform should have stopped billing.
+     */
+    readonly idleTimeoutSeconds: number;
+    /**
+     * The maximum lifetime the product asked for, seconds, when it asked for one.
+     * This is the strongest bound a product holds: the platform destroys the box
+     * at `createdAt + maxLifetimeSeconds` regardless of what the product observed,
+     * so it caps the ceiling even when nothing else can (see `computeExpectedCeiling`).
+     */
+    readonly maxLifetimeSeconds: number | null;
+    /** Latest moment the product OBSERVED the box doing work. */
+    readonly lastActivityAt: number;
+    /**
+     * Detached runs dispatched but never observed to finish, by run id.
+     *
+     * Non-empty means the product genuinely cannot bound this box from its own
+     * observations: it handed the platform work and disconnected. The ceiling
+     * degrades accordingly rather than pretending to a tightness it did not earn.
+     */
+    readonly openDetachedRunIds: readonly string[];
+    /** When the product knows the box stopped. Cleared by later activity. */
+    readonly stoppedAt: number | null;
+    /** When the product knows the box was deleted. Set once — a deleted id never returns. */
+    readonly deletedAt: number | null;
+    /** Opaque product-column values, written verbatim and never read here. */
+    readonly extras?: Record<string, unknown>;
+}
+/**
+ * A fold step. Every field states its own merge rule, so a SQL implementation
+ * can apply it in one statement and reach the same record an in-memory
+ * read-modify-write reaches.
+ */
+interface SpendBoxPatch {
+    /** Advance `lastActivityAt` to the max of stored and this. Never moves backward. */
+    readonly observedActivityAt?: number;
+    /** Add a run id to `openDetachedRunIds` (set semantics — re-adding is a no-op). */
+    readonly openDetachedRunAdd?: string;
+    /** Remove a run id from `openDetachedRunIds`. Removing an absent id is a no-op. */
+    readonly openDetachedRunRemove?: string;
+    /**
+     * Latest-wins. Activity observed AFTER a recorded stop clears it: a box that
+     * worked after we thought it stopped is running again, and a stale stop would
+     * make the ceiling too tight.
+     */
+    readonly stoppedAt?: number;
+    /** Set-once. A later delete observation does not move the first one. */
+    readonly deletedAt?: number;
+}
+/** Which fact bounds a box's billable time, weakest last. */
+type CeilingBasis = 
+/** The product observed deletion. Billing cannot run past a box that is gone. */
+'deleted'
+/** The product observed a stop. Billing should have closed there. */
+ | 'stopped'
+/** No stop seen, but the platform destroys the box at its max lifetime. */
+ | 'max-lifetime'
+/** No stop seen; the platform's idle timer is what should have closed billing. */
+ | 'idle-timeout'
+/**
+ * An unfinished detached run and no max lifetime — the product cannot bound
+ * this box at all, so the ceiling degrades to the reconciliation instant.
+ * A finding on this basis is weak evidence and says so.
+ */
+ | 'open-detached-run';
+/** The upper bound on one box's billable duration, and what earned it. */
+interface ExpectedCeiling {
+    readonly sandboxId: string;
+    readonly basis: CeilingBasis;
+    /** The latest instant this box could still have been billable, epoch ms. */
+    readonly horizonAt: number;
+    /** `horizonAt - createdAt + toleranceMs`. The upper bound on billable ms. */
+    readonly ceilingMs: number;
+    readonly toleranceMs: number;
+    /**
+     * False when the basis is `open-detached-run` — the ceiling then rests on the
+     * reconciliation instant rather than on anything the product observed, so an
+     * overage means the platform billed outside the box's own lifetime, not merely
+     * longer than expected.
+     */
+    readonly bounded: boolean;
+}
+/**
+ * One settled ledger row, in the shape the platform's `credit_transactions`
+ * table stores it. The product supplies these through its own fetch (the
+ * platform's credit-history API, an export, a mirror) — this package never
+ * 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.
+ */
+interface SettlementRow {
+    /** The ledger row id, for the dispute. */
+    readonly id: string;
+    /**
+     * `sandbox:<kind>:<sandboxId>:<intervalStartMs>` — the platform's idempotency
+     * key, and the only place the billed interval's START is recorded.
+     */
+    readonly referenceId: string | null;
+    /**
+     * Signed nanodollars, exactly as the ledger stores it: negative is a charge,
+     * positive is a credit or refund.
+     */
+    readonly amountNanoUsd: number;
+    /** `compute` | `refund` | `inference` | … */
+    readonly type: string;
+    /** `sandbox` | `router` | … */
+    readonly product: string | null;
+    /** `sandbox:<sandboxId>` — the platform's aggregation unit. */
+    readonly groupKey: string | null;
+    /** Settlement instant, epoch ms. The product normalizes the stored text. */
+    readonly createdAt: number;
+    readonly description: string | null;
+    /** Provider at-cost basis, unsigned nanodollars. Null when unattributed. */
+    readonly costBasisNanoUsd: number | null;
+    /**
+     * The billed duration, when the product's ledger view exposes it directly.
+     * Null is the common case: the platform does not store duration on the row.
+     */
+    readonly billedMs: number | null;
+}
+/** The parts of a settlement reference id, once parsed. */
+interface SettlementReference {
+    /** `stop` | `compute` | `egress` | `gpu-lease` | anything the platform adds. */
+    readonly kind: string;
+    /** For compute kinds, the sandbox id. For `gpu-lease`, the lease id. */
+    readonly resourceId: string;
+    /** The interval's start, epoch ms. Null for kinds that carry no interval. */
+    readonly intervalStartMs: number | null;
+}
+/** How a settled duration was arrived at — every duration finding carries one. */
+type BilledDurationBasis = 
+/** The ledger row carried the duration. Exact. */
+'reported'
+/** `amount ÷ the product's stated hourly rate`. Exact when the rate is right. */
+ | 'rate'
+/**
+ * `settledAt - intervalStart`. An UPPER bound, not the billed duration: a
+ * correct settlement posted late by the platform's durable settlement queue
+ * reads longer here than it billed. Findings on this basis say so.
+ */
+ | 'reference-span'
+/** No basis available — duration rules are skipped for this row. */
+ | 'unknown';
+/** The checks this reconciler runs. Each is individually skippable, by name. */
+type SpendCheckId = 
+/** A settlement against a box the product has no record of ever asking for. */
+'unknown-box'
+/** A settled duration longer than the product's own upper bound allows. */
+ | 'over-ceiling'
+/** A spend window far above the trailing median — the burst shape of a defect. */
+ | 'velocity'
+/** The balance the product observes has gone below its floor. */
+ | 'negative-balance';
+declare const SPEND_CHECKS: readonly SpendCheckId[];
+/**
+ * One discrepancy, with every number the rule compared.
+ *
+ * Nullable fields are per-check and deliberately present-but-null rather than
+ * absent: a reader scanning a JSON dump can tell "this rule does not measure
+ * that" from "that measurement is missing".
+ */
+interface SpendFinding {
+    readonly check: SpendCheckId;
+    /** What is wrong, in one sentence, with the numbers in it. */
+    readonly message: string;
+    /** What to do about it. A finding without a remedy is a complaint. */
+    readonly remedy: string;
+    readonly sandboxId: string | null;
+    readonly workspaceId: string | null;
+    /** The ledger rows that evidence this finding — the dispute's exhibit list. */
+    readonly referenceIds: readonly string[];
+    /** Nanodollars this finding puts in question, unsigned. */
+    readonly settledNanoUsd: number;
+    /** `over-ceiling` — the duration actually settled, and how that was derived. */
+    readonly settledMs: number | null;
+    readonly durationBasis: BilledDurationBasis | null;
+    /** `over-ceiling` — the bound it broke, and what earned that bound. */
+    readonly ceilingMs: number | null;
+    readonly overageMs: number | null;
+    readonly ceilingBasis: CeilingBasis | null;
+    /** `velocity` — the window, its trailing median, and the ratio between them. */
+    readonly windowNanoUsd: number | null;
+    readonly trailingMedianNanoUsd: number | null;
+    readonly velocityRatio: number | null;
+    readonly windowStartAt: number | null;
+    /** `negative-balance` — the observed balance and the floor it broke. */
+    readonly balanceNanoUsd: number | null;
+    readonly balanceFloorNanoUsd: number | null;
+}
+/** What one reconciliation pass concluded. */
+interface SpendReport {
+    /** True when nothing fired. `ok === findings.length === 0`. */
+    readonly ok: boolean;
+    readonly findings: readonly SpendFinding[];
+    readonly checksRun: readonly SpendCheckId[];
+    /** Rows the pass read, including the ones no rule looked at. */
+    readonly rowsExamined: number;
+    /** Distinct boxes those rows settled against. */
+    readonly boxesExamined: number;
+    /** Total charged across every examined row, unsigned nanodollars. */
+    readonly settledNanoUsd: number;
+    /** Total credited back across every examined row, unsigned nanodollars. */
+    readonly creditedNanoUsd: number;
+    /** The instant the pass treated as "now". */
+    readonly asOf: number;
+}
+
+/**
+ * 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.
+ */
+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>;
+}
+/**
+ * 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.
+ */
+declare function foldSpendBoxRecord(record: SpendBoxRecord, patch: SpendBoxPatch): SpendBoxRecord;
+/** An in-memory store that also lets a test inspect and force state. */
+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. */
+declare function createInMemorySpendLedgerStore(): InMemorySpendLedgerStore;
+/** What the product tells the ledger when it first sees a box. */
+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;
+}
+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).
+ */
+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. */
+declare function createSpendLedger(options: SpendLedgerOptions): SpendLedger;
+
+/**
+ * Slack allowed between the product's bound and what the platform settled,
+ * before an overage is called a discrepancy. 15 minutes.
+ *
+ * Not a guess: it is the platform's OWN staleness threshold for compute
+ * settlement. Its runbook clears an incident when
+ * `/health computeSettlement.oldestAgeSeconds` is "back under 900" — so 900 s is
+ * the age the platform itself treats as normal settlement lag, and anything
+ * inside it is drift the platform has already declared acceptable. Below that a
+ * product would alert on the platform's ordinary queue behaviour; far above it
+ * the tolerance starts eating the signal, because the idle window it must stay
+ * well under is 3600 s in every shipped product.
+ *
+ * It is a caller parameter because a product that asks for a shorter idle
+ * timeout must shrink this with it.
+ */
+declare const DEFAULT_CEILING_TOLERANCE_MS = 900000;
+interface ComputeExpectedCeilingOptions {
+    /** The instant the reconciliation treats as "now", epoch ms. */
+    readonly asOf: number;
+    /** Slack before an overage counts. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */
+    readonly toleranceMs?: number;
+}
+/**
+ * The upper bound on how long one box could honestly have been billable.
+ *
+ * The whole design constraint is that this must stay an UPPER bound under
+ * everything the product cannot see. Three such blind spots exist, and they
+ * pull in different directions:
+ *
+ * - **Platform-side suspends.** The platform can park a box the product never
+ *   hears about. That only ever REDUCES real billable time, so an upper bound
+ *   is unaffected and nothing here widens for it.
+ * - **Detached runs.** The product dispatches work and disconnects. The box
+ *   keeps working — and billing — after the last activity the product saw, so
+ *   `lastActivityAt` understates the truth. An unfinished detached run
+ *   therefore abandons the activity-based bound entirely rather than reporting
+ *   a bound it cannot support.
+ * - **Reconnects.** A browser or worker re-attaches and work resumes. This
+ *   needs no special case: a reconnect is recorded as activity, the fold takes
+ *   the max, and the horizon moves out on its own.
+ *
+ * The bound that rescues the detached case is `maxLifetimeSeconds`. The platform
+ * destroys the box at `createdAt + maxLifetimeSeconds` no matter what anyone
+ * observed, so a product that asks for one holds a hard bound that survives
+ * every blind spot above. Both shipped products ask for 86 400 s, which is why
+ * the incident — 124 to 268 hours settled against boxes with a 24-hour
+ * lifetime — is detectable with no lifecycle bookkeeping at all.
+ */
+declare function computeExpectedCeiling(record: SpendBoxRecord, options: ComputeExpectedCeilingOptions): ExpectedCeiling;
+
+/**
+ * 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.
+ */
+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.
+ */
+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).
+ */
+declare function settlementSandboxId(row: SettlementRow): string | null;
+/** True when a row is a charge (the ledger stores charges as negative amounts). */
+declare function isCharge(row: SettlementRow): boolean;
+/** A charge's magnitude in unsigned nanodollars; 0 for credits. */
+declare function chargeNanoUsd(row: SettlementRow): number;
+
+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. */
+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.
+ */
+type BoxRateResolver = (record: SpendBoxRecord | null, sandboxId: string) => number | null | undefined;
+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.
+     */
+    readonly rows: readonly SettlementRow[];
+    /** The product's expectation ledger. */
+    readonly store: SpendLedgerStorePort;
+    /** 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[];
+}
+/**
+ * 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.
+ */
+declare function reconcileSpend(options: ReconcileSpendOptions): Promise<SpendReport>;
+
+/** Why provisioning was refused, with every number the decision used. */
+interface ComputeBudgetRefusal {
+    readonly workspaceId: string;
+    /** The cap, unsigned nanodollars. */
+    readonly limitNanoUsd: number;
+    /** Cumulative settled compute spend for this workspace, unsigned nanodollars. */
+    readonly settledNanoUsd: number;
+    /** How far past the cap it already is. */
+    readonly overageNanoUsd: number;
+    readonly at: number;
+}
+/**
+ * Provisioning refused because the workspace is already past its compute cap.
+ *
+ * Correctable by design: every number the decision used is on the error, so a
+ * product can render "this workspace has spent $X of its $Y compute budget" and
+ * an operator can raise the cap or investigate without reading logs.
+ *
+ * This is the failure mode the module exists to produce. A platform billing
+ * defect that used to end in a silent negative balance now ends in provisioning
+ * stopping and something loud happening instead.
+ */
+declare class ComputeBudgetExceededError extends Error {
+    readonly workspaceId: string;
+    readonly limitNanoUsd: number;
+    readonly settledNanoUsd: number;
+    readonly overageNanoUsd: number;
+    constructor(refusal: ComputeBudgetRefusal);
+}
+/**
+ * A per-workspace cap on sandbox compute.
+ *
+ * `/billing`'s budget primitive caps MODEL keys, and it works because the
+ * platform enforces the cap at the key it minted. Sandbox compute has no such
+ * key: a box bills the shared company wallet, so nothing upstream refuses. This
+ * carries the same shape to the one place a consumer can still act — the moment
+ * before it asks for another box.
+ *
+ * `settledNanoUsd` is a callback rather than a number because the authority is
+ * the platform ledger, not this package: the product reads the same rows it
+ * hands the reconciler. Cache it if the read is expensive; a cap is a
+ * coarse-grained control and a slightly stale total still refuses.
+ */
+interface ComputeBudget {
+    /** The cap, unsigned nanodollars. */
+    readonly limitNanoUsd: number;
+    /** Cumulative settled compute spend for the workspace, unsigned nanodollars. */
+    readonly settledNanoUsd: (workspaceId: string) => Promise<number> | number;
+    /**
+     * Called on every refusal, before the error is thrown. This is the alert
+     * seam: a refusal nobody hears is a product that silently stopped working.
+     */
+    readonly onRefusal?: (refusal: ComputeBudgetRefusal) => void;
+    /** Injectable clock (epoch ms). Default `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Throw {@link ComputeBudgetExceededError} when the workspace is already past
+ * its cap. Returns normally — and reads nothing — when no budget is configured.
+ *
+ * Deliberately a pre-check against spend ALREADY SETTLED, not a reservation
+ * against spend about to happen: settlement lags provisioning by design (the
+ * platform's durable settlement queue), so there is no instant at which a
+ * consumer could hold an accurate running total. The cap therefore overshoots by
+ * at most the unsettled tail, which is bounded by the box's own idle timeout.
+ * A cap that refuses one box late is worth far more than one that cannot be
+ * implemented honestly.
+ */
+declare function assertComputeBudget(budget: ComputeBudget | undefined, workspaceId: string): Promise<void>;
+/**
+ * What `/sandbox` reports once a box is provisioned, reused or resumed.
+ *
+ * Structurally identical to `SandboxProvisionedObservation` in `/sandbox`, and
+ * deliberately re-declared rather than imported: `/spend` composes `/sandbox`,
+ * so a type import in the other direction would invert the dependency. The two
+ * are pinned together by a compile-time assignment in this module's tests.
+ */
+interface SpendProvisionObservation {
+    readonly workspaceId: string;
+    readonly userId?: string;
+    readonly sandboxId: string;
+    readonly boxKey?: string | undefined;
+    readonly idleTimeoutSeconds: number;
+    readonly maxLifetimeSeconds?: number | undefined;
+    readonly at: number;
+}
+/**
+ * The optional seam `EnsureWorkspaceSandboxOptions.spend` and the turn
+ * primitives' `spend` option both accept. One object, wired in both places.
+ */
+interface SandboxSpendSeam {
+    beforeProvision?(input: {
+        workspaceId: string;
+        userId?: string;
+    }): Promise<void> | void;
+    onProvisioned?(observation: SpendProvisionObservation): Promise<void> | void;
+    /** Synchronous by contract — it sits on the turn path. See `createSandboxSpendHooks`. */
+    onActivity?(input: {
+        sandboxId: string;
+        at: number;
+    }): void;
+}
+interface SandboxSpendHooksOptions {
+    /** Records box lifecycle. Omit to run the budget guard alone. */
+    readonly ledger?: SpendLedger;
+    /** Refuses provisioning past a cap. Omit to record alone. */
+    readonly budget?: ComputeBudget;
+    /**
+     * Called when RECORDING fails. Recording is best-effort — a bookkeeping
+     * failure must never take down the provisioning it is bookkeeping — so this
+     * is the only place such a failure is visible. A refusal is NOT routed here;
+     * refusals throw, by design.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Build the object to hand `ensureWorkspaceSandbox`'s `spend` option.
+ *
+ * Wiring it is the entire adoption cost: one field, and the product's boxes are
+ * both budget-capped and recorded.
+ */
+declare function createSandboxSpendHooks(options: SandboxSpendHooksOptions): SandboxSpendSeam;
+
+/**
+ * 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.
+ */
+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 };