instar 1.3.782 → 1.3.784

package/dist/core/MeteredSpendLedger.d.ts

@@ -0,0 +1,154 @@
+/**
+ * MeteredSpendLedger — Layer 3 of the Routing Control Room
+ * (docs/specs/routing-control-room-spend-alerts.md, Increment B).
+ *
+ * The AUTHORITATIVE money truth: an append-only, booking-priced ledger of every
+ * metered-door reservation/settlement, plus a maintained O(1) committed total the
+ * fail-closed gate reads. This ledger — NOT `feature_metrics`, NOT the Layer-1c
+ * provider-report store — is the ONLY rebuild source for committed spend
+ * (FD-3/FD-9): rebuilding from Layer 0 joined to current prices is FORBIDDEN at
+ * the gate (a downward `corrects` would re-open capped headroom).
+ *
+ * Write discipline (adopted from DriftSpendLedger, upgraded per spec C4-2):
+ *  - Rows are APPEND-ONLY JSONL, fsync'd, written FIRST; the totals file is a
+ *    regenerable CACHE of the fold, rewritten atomically (tmp+rename) SECOND.
+ *    A crash between the two leaves totals STALE-LOW by at most one booking; the
+ *    next gate read runs a cheap high-water check (file size) and re-folds.
+ *  - Writes are FAIL-CLOSED and NON-SWALLOWING: a booking that cannot be durably
+ *    persisted throws, and the caller must refuse the metered call.
+ *  - Boot: fold all rows, REWRITE the totals cache from row truth (torn totals
+ *    rename / totals-without-append are always corrected; the append-first
+ *    ordering makes totals-without-append impossible, asserted in tests).
+ *  - A torn trailing append (partial last line) is the malformed-row-skip case.
+ *
+ * Reserve/settle lifecycle (A-B2/A2-1):
+ *  - reserve(): books the worst-case estimate (cached tokens as FULL input,
+ *    FD-19; output at the REQUIRED max-tokens ceiling). Outstanding reserves are
+ *    INSIDE the committed total (concurrent reservations see each other).
+ *  - settle(): idempotent terminal `reserved → settled`; books ACTUAL cost.
+ *    A settle after expiry books the actual cost as a fresh ABSOLUTE row
+ *    (expiry-aware settle) — the late-settle race can never under-count.
+ *  - expire(): the reserve-expiry sweep (takes the per-key mutex) expires only
+ *    reserves older than the TTL still in `reserved` state.
+ *  - First terminal transition wins; the loser is a no-op.
+ *
+ * Concurrency: metered calls funnel through the single server process, so the
+ * booking critical sections are guarded by an in-process async mutex per keyRef
+ * (held only for the booking, RELEASED during the LLM round-trip) plus a
+ * proper-lockfile advisory lock for defence against a second process.
+ */
+/** Default reserve TTL — pinned comfortably above the metered-call latency ceiling (spec: 15 min vs a 5-min call ceiling). */
+export declare const DEFAULT_RESERVE_TTL_MS: number;
+export type MeteredBookingKind = 'reserve' | 'settle' | 'expire';
+/** One append-only booking row. NEVER mutated; corrections are new rows. */
+export interface MeteredBookingRow {
+    ts: string;
+    keyRef: string;
+    door: string;
+    modelId: string;
+    kind: MeteredBookingKind;
+    /** The per-call id (=== meteredCallId) minted at reserve time. */
+    reserveId: string;
+    /** Reserve: worst-case estimate. Settle: ACTUAL booked cost. Expire: 0. */
+    costUsd: number;
+    /** The metered-lease epoch the booking was made under (A-B4). */
+    leaseEpoch: number;
+    /** Set on a settle that arrived after its reserve was expired (books absolute). */
+    lateAfterExpire?: boolean;
+}
+/** The maintained O(1) running totals (a regenerable cache of the fold). */
+export interface MeteredCommittedTotals {
+    keyRef: string;
+    committedLifetimeUsd: number;
+    committedDayUsd: number;
+    /** UTC day (YYYY-MM-DD) the day total belongs to; a new day resets it. */
+    dayEpoch: string;
+    updatedAt: string;
+}
+export interface ReserveRequest {
+    keyRef: string;
+    door: string;
+    modelId: string;
+    /** Worst-case reserve in USD (computed by the gate at canonical BASE price). */
+    reserveUsd: number;
+    leaseEpoch: number;
+    /**
+     * When set, the cap comparison happens ATOMICALLY inside the per-key booking
+     * critical section (`committed + reserve > cap` strict `>`, both caps) — the
+     * only ordering under which two concurrent reservations are guaranteed to see
+     * each other (spec Layer 3). Refusal throws CapExceededError; nothing books.
+     */
+    admitOnlyUnderCaps?: {
+        lifetimeCapUsd: number;
+        dailyCapUsd: number;
+    };
+}
+/** Thrown by reserve() when admitOnlyUnderCaps would be breached — nothing was booked. */
+export declare class CapExceededError extends Error {
+    capKind: 'lifetime' | 'daily';
+    committedUsd: number;
+    reserveUsd: number;
+    capUsd: number;
+    constructor(capKind: 'lifetime' | 'daily', committedUsd: number, reserveUsd: number, capUsd: number);
+}
+export interface ReserveHandle {
+    reserveId: string;
+    /** Committed lifetime total AFTER this reservation (outstanding reserves included). */
+    committedLifetimeUsd: number;
+    committedDayUsd: number;
+}
+export declare class MeteredLedgerWriteError extends Error {
+    cause?: unknown | undefined;
+    constructor(msg: string, cause?: unknown | undefined);
+}
+export interface MeteredSpendLedgerOptions {
+    /** The agent's `.instar/` dir; rows/totals live under `state/`, the lock under `local/`. */
+    stateDir: string;
+    reserveTtlMs?: number;
+    now?: () => number;
+}
+export declare class MeteredSpendLedger {
+    private readonly rowsPath;
+    private readonly totalsPath;
+    private readonly lockTarget;
+    private readonly ttlMs;
+    private readonly now;
+    /** In-memory fold state, authoritative in-process. Rebuilt on construction. */
+    private reserves;
+    private totals;
+    /** Byte length of the rows file as of our last append/fold (the high-water mark). */
+    private rowsBytes;
+    /** In-process per-key mutex tail. */
+    private mutexTail;
+    constructor(opts: MeteredSpendLedgerOptions);
+    /** O(1) committed totals for a key, day-rolled to NOW. High-water-checked against external appends. */
+    committed(keyRef: string): MeteredCommittedTotals;
+    /** Reserve worst-case cost. FAIL-CLOSED: any persistence failure throws. */
+    reserve(req: ReserveRequest): Promise<ReserveHandle>;
+    /**
+     * Terminal settle at ACTUAL cost. Idempotent: a second settle is a no-op.
+     * A settle after expiry books the actual as a fresh ABSOLUTE row (late-settle).
+     */
+    settle(keyRef: string, reserveId: string, actualUsd: number): Promise<void>;
+    /** Reserve-expiry sweep (Layer 3 — takes the per-key mutex). Expires only TTL-stale `reserved` states. */
+    sweepExpired(): Promise<number>;
+    /** All totals (for the caps view). Day-rolled to now. */
+    allCommitted(): MeteredCommittedTotals[];
+    /** Apply one row to the in-memory fold. */
+    private applyRow;
+    /** Contribution of one reserve state to committed totals. */
+    private contribution;
+    private recomputeTotalsForKey;
+    /** Day-rolled view of a key's totals (a new UTC day resets the day figure). */
+    private currentTotals;
+    /** Full refold from row truth (the fold is canon; the totals file is a cache). */
+    private refoldFromRows;
+    /** Cheap external-append detection: rows-file byte length vs our high-water mark. */
+    private checkHighWater;
+    /** Append one row, fsync'd, under the advisory file lock. NON-SWALLOWING. */
+    private appendDurable;
+    /** Atomic (tmp+rename) rewrite of the totals cache. Best-effort — rows are canon. */
+    private rewriteTotalsCache;
+    private withKeyMutex;
+}
+//# sourceMappingURL=MeteredSpendLedger.d.ts.map

package/dist/core/MeteredSpendLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeteredSpendLedger.d.ts","sourceRoot":"","sources":["../../src/core/MeteredSpendLedger.ts"],"names":[],"mappings":"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"}

package/dist/core/MeteredSpendLedger.js

@@ -0,0 +1,434 @@
+/**
+ * MeteredSpendLedger — Layer 3 of the Routing Control Room
+ * (docs/specs/routing-control-room-spend-alerts.md, Increment B).
+ *
+ * The AUTHORITATIVE money truth: an append-only, booking-priced ledger of every
+ * metered-door reservation/settlement, plus a maintained O(1) committed total the
+ * fail-closed gate reads. This ledger — NOT `feature_metrics`, NOT the Layer-1c
+ * provider-report store — is the ONLY rebuild source for committed spend
+ * (FD-3/FD-9): rebuilding from Layer 0 joined to current prices is FORBIDDEN at
+ * the gate (a downward `corrects` would re-open capped headroom).
+ *
+ * Write discipline (adopted from DriftSpendLedger, upgraded per spec C4-2):
+ *  - Rows are APPEND-ONLY JSONL, fsync'd, written FIRST; the totals file is a
+ *    regenerable CACHE of the fold, rewritten atomically (tmp+rename) SECOND.
+ *    A crash between the two leaves totals STALE-LOW by at most one booking; the
+ *    next gate read runs a cheap high-water check (file size) and re-folds.
+ *  - Writes are FAIL-CLOSED and NON-SWALLOWING: a booking that cannot be durably
+ *    persisted throws, and the caller must refuse the metered call.
+ *  - Boot: fold all rows, REWRITE the totals cache from row truth (torn totals
+ *    rename / totals-without-append are always corrected; the append-first
+ *    ordering makes totals-without-append impossible, asserted in tests).
+ *  - A torn trailing append (partial last line) is the malformed-row-skip case.
+ *
+ * Reserve/settle lifecycle (A-B2/A2-1):
+ *  - reserve(): books the worst-case estimate (cached tokens as FULL input,
+ *    FD-19; output at the REQUIRED max-tokens ceiling). Outstanding reserves are
+ *    INSIDE the committed total (concurrent reservations see each other).
+ *  - settle(): idempotent terminal `reserved → settled`; books ACTUAL cost.
+ *    A settle after expiry books the actual cost as a fresh ABSOLUTE row
+ *    (expiry-aware settle) — the late-settle race can never under-count.
+ *  - expire(): the reserve-expiry sweep (takes the per-key mutex) expires only
+ *    reserves older than the TTL still in `reserved` state.
+ *  - First terminal transition wins; the loser is a no-op.
+ *
+ * Concurrency: metered calls funnel through the single server process, so the
+ * booking critical sections are guarded by an in-process async mutex per keyRef
+ * (held only for the booking, RELEASED during the LLM round-trip) plus a
+ * proper-lockfile advisory lock for defence against a second process.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import lockfile from 'proper-lockfile';
+const LOCK_OPTIONS = {
+    retries: { retries: 50, factor: 1.2, minTimeout: 50, maxTimeout: 500 },
+    stale: 10_000,
+    realpath: false,
+};
+/** Default reserve TTL — pinned comfortably above the metered-call latency ceiling (spec: 15 min vs a 5-min call ceiling). */
+export const DEFAULT_RESERVE_TTL_MS = 15 * 60 * 1000;
+/** Thrown by reserve() when admitOnlyUnderCaps would be breached — nothing was booked. */
+export class CapExceededError extends Error {
+    capKind;
+    committedUsd;
+    reserveUsd;
+    capUsd;
+    constructor(capKind, committedUsd, reserveUsd, capUsd) {
+        super(`${capKind}: committed ${committedUsd.toFixed(4)} + reserve ${reserveUsd.toFixed(4)} > cap ${capUsd.toFixed(2)}`);
+        this.capKind = capKind;
+        this.committedUsd = committedUsd;
+        this.reserveUsd = reserveUsd;
+        this.capUsd = capUsd;
+        this.name = 'CapExceededError';
+    }
+}
+export class MeteredLedgerWriteError extends Error {
+    cause;
+    constructor(msg, cause) {
+        super(`metered-spend ledger write failed (fail-closed): ${msg}`);
+        this.cause = cause;
+        this.name = 'MeteredLedgerWriteError';
+    }
+}
+function utcDay(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+export class MeteredSpendLedger {
+    rowsPath;
+    totalsPath;
+    lockTarget;
+    ttlMs;
+    now;
+    /** In-memory fold state, authoritative in-process. Rebuilt on construction. */
+    reserves = new Map();
+    totals = new Map();
+    /** Byte length of the rows file as of our last append/fold (the high-water mark). */
+    rowsBytes = 0;
+    /** In-process per-key mutex tail. */
+    mutexTail = new Map();
+    constructor(opts) {
+        const stateSub = path.join(opts.stateDir, 'state');
+        const localSub = path.join(opts.stateDir, 'local');
+        fs.mkdirSync(stateSub, { recursive: true });
+        fs.mkdirSync(localSub, { recursive: true });
+        this.rowsPath = path.join(stateSub, 'metered-spend-ledger.jsonl');
+        this.totalsPath = path.join(stateSub, 'metered-spend-totals.json');
+        this.lockTarget = path.join(localSub, 'metered-spend.lock');
+        if (!fs.existsSync(this.lockTarget))
+            fs.writeFileSync(this.lockTarget, '');
+        this.ttlMs = opts.reserveTtlMs ?? DEFAULT_RESERVE_TTL_MS;
+        this.now = opts.now ?? (() => Date.now());
+        // Boot: the fold is canon — rebuild from rows and REWRITE the totals cache.
+        this.refoldFromRows();
+        this.rewriteTotalsCache();
+    }
+    // ── Public API ─────────────────────────────────────────────────────
+    /** O(1) committed totals for a key, day-rolled to NOW. High-water-checked against external appends. */
+    committed(keyRef) {
+        this.checkHighWater();
+        return this.currentTotals(keyRef);
+    }
+    /** Reserve worst-case cost. FAIL-CLOSED: any persistence failure throws. */
+    async reserve(req) {
+        if (!Number.isFinite(req.reserveUsd) || req.reserveUsd < 0) {
+            throw new MeteredLedgerWriteError(`invalid reserveUsd ${req.reserveUsd}`);
+        }
+        return this.withKeyMutex(req.keyRef, async () => {
+            this.checkHighWater();
+            if (req.admitOnlyUnderCaps) {
+                // ATOMIC check-and-reserve: this runs inside the per-key mutex, so every
+                // outstanding concurrent reservation is already in the committed total.
+                const t = this.currentTotals(req.keyRef);
+                if (t.committedLifetimeUsd + req.reserveUsd > req.admitOnlyUnderCaps.lifetimeCapUsd) {
+                    throw new CapExceededError('lifetime', t.committedLifetimeUsd, req.reserveUsd, req.admitOnlyUnderCaps.lifetimeCapUsd);
+                }
+                if (t.committedDayUsd + req.reserveUsd > req.admitOnlyUnderCaps.dailyCapUsd) {
+                    throw new CapExceededError('daily', t.committedDayUsd, req.reserveUsd, req.admitOnlyUnderCaps.dailyCapUsd);
+                }
+            }
+            const nowMs = this.now();
+            const reserveId = crypto.randomBytes(12).toString('hex');
+            const row = {
+                ts: new Date(nowMs).toISOString(),
+                keyRef: req.keyRef,
+                door: req.door,
+                modelId: req.modelId,
+                kind: 'reserve',
+                reserveId,
+                costUsd: round6(req.reserveUsd),
+                leaseEpoch: req.leaseEpoch,
+            };
+            await this.appendDurable(row);
+            this.applyRow(row);
+            this.rewriteTotalsCache();
+            const t = this.currentTotals(req.keyRef);
+            return { reserveId, committedLifetimeUsd: t.committedLifetimeUsd, committedDayUsd: t.committedDayUsd };
+        });
+    }
+    /**
+     * Terminal settle at ACTUAL cost. Idempotent: a second settle is a no-op.
+     * A settle after expiry books the actual as a fresh ABSOLUTE row (late-settle).
+     */
+    async settle(keyRef, reserveId, actualUsd) {
+        if (!Number.isFinite(actualUsd) || actualUsd < 0) {
+            throw new MeteredLedgerWriteError(`invalid actualUsd ${actualUsd}`);
+        }
+        return this.withKeyMutex(keyRef, async () => {
+            const st = this.reserves.get(reserveId);
+            if (st && st.state === 'settled')
+                return; // first terminal wins — no-op
+            const lateAfterExpire = st?.state === 'expired';
+            const row = {
+                ts: new Date(this.now()).toISOString(),
+                keyRef,
+                door: st?.door ?? 'unknown',
+                modelId: st?.modelId ?? 'unknown',
+                kind: 'settle',
+                reserveId,
+                costUsd: round6(actualUsd),
+                leaseEpoch: 0,
+                ...(lateAfterExpire ? { lateAfterExpire: true } : {}),
+            };
+            await this.appendDurable(row);
+            this.applyRow(row);
+            this.rewriteTotalsCache();
+        });
+    }
+    /** Reserve-expiry sweep (Layer 3 — takes the per-key mutex). Expires only TTL-stale `reserved` states. */
+    async sweepExpired() {
+        const nowMs = this.now();
+        let expired = 0;
+        // Group stale reserves by key so each key's bookings stay serialized.
+        const byKey = new Map();
+        for (const [id, st] of this.reserves) {
+            if (st.state !== 'reserved')
+                continue;
+            if (nowMs - st.reservedAtMs <= this.ttlMs)
+                continue;
+            const arr = byKey.get(st.keyRef) ?? [];
+            arr.push({ id, st });
+            byKey.set(st.keyRef, arr);
+        }
+        for (const [keyRef, stales] of byKey) {
+            await this.withKeyMutex(keyRef, async () => {
+                for (const { id, st } of stales) {
+                    if (st.state !== 'reserved')
+                        continue; // settled while we waited — first terminal wins
+                    const row = {
+                        ts: new Date(this.now()).toISOString(),
+                        keyRef,
+                        door: st.door,
+                        modelId: st.modelId,
+                        kind: 'expire',
+                        reserveId: id,
+                        costUsd: 0,
+                        leaseEpoch: 0,
+                    };
+                    await this.appendDurable(row);
+                    this.applyRow(row);
+                    expired++;
+                }
+                this.rewriteTotalsCache();
+            });
+        }
+        return expired;
+    }
+    /** All totals (for the caps view). Day-rolled to now. */
+    allCommitted() {
+        this.checkHighWater();
+        const keys = new Set();
+        for (const st of this.reserves.values())
+            keys.add(st.keyRef);
+        for (const k of this.totals.keys())
+            keys.add(k);
+        return [...keys].map((k) => this.currentTotals(k));
+    }
+    // ── Fold internals ─────────────────────────────────────────────────
+    /** Apply one row to the in-memory fold. */
+    applyRow(row, opts) {
+        const day = utcDay(Date.parse(row.ts));
+        if (row.kind === 'reserve') {
+            this.reserves.set(row.reserveId, {
+                keyRef: row.keyRef,
+                door: row.door,
+                modelId: row.modelId,
+                reserveUsd: row.costUsd,
+                day,
+                reservedAtMs: Date.parse(row.ts),
+                state: 'reserved',
+            });
+        }
+        else if (row.kind === 'settle') {
+            const st = this.reserves.get(row.reserveId);
+            if (st) {
+                if (st.state === 'settled')
+                    return; // idempotent
+                st.state = 'settled';
+                st.settledUsd = row.costUsd;
+                // A late settle books on the SETTLE's own day when the reserve day already
+                // contributed nothing (it was expired); otherwise the contribution keeps
+                // the reserve's day.
+                if (row.lateAfterExpire)
+                    st.day = day;
+            }
+            else {
+                // Settle with no known reserve (e.g. rows pruned): book absolute on its own day.
+                this.reserves.set(row.reserveId, {
+                    keyRef: row.keyRef,
+                    door: row.door,
+                    modelId: row.modelId,
+                    reserveUsd: 0,
+                    day,
+                    reservedAtMs: Date.parse(row.ts),
+                    state: 'settled',
+                    settledUsd: row.costUsd,
+                });
+            }
+        }
+        else if (row.kind === 'expire') {
+            const st = this.reserves.get(row.reserveId);
+            if (st && st.state === 'reserved')
+                st.state = 'expired';
+        }
+        if (!opts?.skipTotals)
+            this.recomputeTotalsForKey(row.keyRef);
+    }
+    /** Contribution of one reserve state to committed totals. */
+    contribution(st) {
+        if (st.state === 'settled')
+            return st.settledUsd ?? 0;
+        if (st.state === 'expired')
+            return 0;
+        return st.reserveUsd; // outstanding reserve — inside the committed total
+    }
+    recomputeTotalsForKey(keyRef) {
+        const today = utcDay(this.now());
+        let lifetime = 0;
+        let dayUsd = 0;
+        for (const st of this.reserves.values()) {
+            if (st.keyRef !== keyRef)
+                continue;
+            const c = this.contribution(st);
+            lifetime += c;
+            if (st.day === today)
+                dayUsd += c;
+        }
+        this.totals.set(keyRef, {
+            keyRef,
+            committedLifetimeUsd: round6(lifetime),
+            committedDayUsd: round6(dayUsd),
+            dayEpoch: today,
+            updatedAt: new Date(this.now()).toISOString(),
+        });
+    }
+    /** Day-rolled view of a key's totals (a new UTC day resets the day figure). */
+    currentTotals(keyRef) {
+        const today = utcDay(this.now());
+        const t = this.totals.get(keyRef);
+        if (!t) {
+            return { keyRef, committedLifetimeUsd: 0, committedDayUsd: 0, dayEpoch: today, updatedAt: new Date(this.now()).toISOString() };
+        }
+        if (t.dayEpoch !== today) {
+            this.recomputeTotalsForKey(keyRef);
+            return this.totals.get(keyRef);
+        }
+        return t;
+    }
+    /** Full refold from row truth (the fold is canon; the totals file is a cache). */
+    refoldFromRows() {
+        this.reserves = new Map();
+        this.totals = new Map();
+        let raw = '';
+        try {
+            raw = fs.readFileSync(this.rowsPath, 'utf-8');
+            this.rowsBytes = Buffer.byteLength(raw);
+        }
+        catch {
+            // @silent-fallback-ok: no rows file yet — a fresh ledger folds to zero.
+            this.rowsBytes = 0;
+            return;
+        }
+        const keys = new Set();
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            let row;
+            try {
+                row = JSON.parse(line);
+            }
+            catch {
+                // Malformed-row-skip: a torn trailing append is expected crash residue.
+                continue;
+            }
+            if (typeof row?.reserveId !== 'string' ||
+                typeof row?.keyRef !== 'string' ||
+                typeof row?.costUsd !== 'number' ||
+                !Number.isFinite(row.costUsd) ||
+                row.costUsd < 0 ||
+                !['reserve', 'settle', 'expire'].includes(row?.kind)) {
+                continue;
+            }
+            // Inline apply without per-row totals recompute (batched below).
+            keys.add(row.keyRef);
+            this.applyRow(row, { skipTotals: true });
+        }
+        for (const k of keys)
+            this.recomputeTotalsForKey(k);
+    }
+    /** Cheap external-append detection: rows-file byte length vs our high-water mark. */
+    checkHighWater() {
+        let size = 0;
+        try {
+            size = fs.statSync(this.rowsPath).size;
+        }
+        catch {
+            // @silent-fallback-ok: rows file absent — nothing appended externally.
+            size = 0;
+        }
+        if (size !== this.rowsBytes) {
+            this.refoldFromRows();
+            this.rewriteTotalsCache();
+        }
+    }
+    // ── Durable write internals ────────────────────────────────────────
+    /** Append one row, fsync'd, under the advisory file lock. NON-SWALLOWING. */
+    async appendDurable(row) {
+        let release = null;
+        try {
+            release = await lockfile.lock(this.lockTarget, LOCK_OPTIONS);
+            const line = JSON.stringify(row) + '\n';
+            const fd = fs.openSync(this.rowsPath, 'a', 0o600);
+            try {
+                fs.writeSync(fd, line);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            this.rowsBytes += Buffer.byteLength(line);
+        }
+        catch (err) {
+            throw new MeteredLedgerWriteError(String(err), err);
+        }
+        finally {
+            if (release)
+                await release().catch(() => { });
+        }
+    }
+    /** Atomic (tmp+rename) rewrite of the totals cache. Best-effort — rows are canon. */
+    rewriteTotalsCache() {
+        try {
+            const file = { rowsBytes: this.rowsBytes, totals: Object.fromEntries(this.totals) };
+            const tmp = this.totalsPath + '.tmp';
+            fs.writeFileSync(tmp, JSON.stringify(file, null, 2), { mode: 0o600 });
+            fs.renameSync(tmp, this.totalsPath);
+        }
+        catch {
+            // @silent-fallback-ok: the totals file is a regenerable CACHE of the fold —
+            // a failed cache write never blocks a booking (rows are already durable) and
+            // is corrected by the next boot-time refold.
+        }
+    }
+    // ── In-process per-key mutex ───────────────────────────────────────
+    withKeyMutex(keyRef, fn) {
+        const tail = this.mutexTail.get(keyRef) ?? Promise.resolve();
+        let done;
+        const next = new Promise((r) => (done = r));
+        this.mutexTail.set(keyRef, next);
+        return tail.then(async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                done();
+                if (this.mutexTail.get(keyRef) === next)
+                    this.mutexTail.delete(keyRef);
+            }
+        });
+    }
+}
+//# sourceMappingURL=MeteredSpendLedger.js.map

package/dist/core/MeteredSpendLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeteredSpendLedger.js","sourceRoot":"","sources":["../../src/core/MeteredSpendLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AAEvC,MAAM,YAAY,GAAyB;IACzC,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE;IACtE,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;CAChB,CAAC;AAEF,8HAA8H;AAC9H,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAqDrD,0FAA0F;AAC1F,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEhC;IACA;IACA;IACA;IAJT,YACS,OAA6B,EAC7B,YAAoB,EACpB,UAAkB,EAClB,MAAc;QAErB,KAAK,CAAC,GAAG,OAAO,eAAe,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QALjH,YAAO,GAAP,OAAO,CAAsB;QAC7B,iBAAY,GAAZ,YAAY,CAAQ;QACpB,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAAQ;QAGrB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AASD,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChB;IAAhC,YAAY,GAAW,EAAS,KAAe;QAC7C,KAAK,CAAC,oDAAoD,GAAG,EAAE,CAAC,CAAC;QADnC,UAAK,GAAL,KAAK,CAAU;QAE7C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAcD,SAAS,MAAM,CAAC,EAAU;IACxB,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,MAAM,CAAC,CAAS;IACvB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACnC,CAAC;AASD,MAAM,OAAO,kBAAkB;IACZ,QAAQ,CAAS;IACjB,UAAU,CAAS;IACnB,UAAU,CAAS;IACnB,KAAK,CAAS;IACd,GAAG,CAAe;IAEnC,+EAA+E;IACvE,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC3C,MAAM,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC3D,qFAAqF;IAC7E,SAAS,GAAG,CAAC,CAAC;IACtB,qCAAqC;IAC7B,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IAErD,YAAY,IAA+B;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,4BAA4B,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC;QACnE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;QAC5D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;QACzD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1C,4EAA4E;QAC5E,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;IAED,sEAAsE;IAEtE,uGAAuG;IACvG,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,OAAO,CAAC,GAAmB;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,uBAAuB,CAAC,sBAAsB,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;YAC9C,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,GAAG,CAAC,kBAAkB,EAAE,CAAC;gBAC3B,yEAAyE;gBACzE,wEAAwE;gBACxE,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACzC,IAAI,CAAC,CAAC,oBAAoB,GAAG,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,kBAAkB,CAAC,cAAc,EAAE,CAAC;oBACpF,MAAM,IAAI,gBAAgB,CAAC,UAAU,EAAE,CAAC,CAAC,oBAAoB,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC;gBACxH,CAAC;gBACD,IAAI,CAAC,CAAC,eAAe,GAAG,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,kBAAkB,CAAC,WAAW,EAAE,CAAC;oBAC5E,MAAM,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,eAAe,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;gBAC7G,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACzD,MAAM,GAAG,GAAsB;gBAC7B,EAAE,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;gBACjC,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,IAAI,EAAE,SAAS;gBACf,SAAS;gBACT,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;gBAC/B,UAAU,EAAE,GAAG,CAAC,UAAU;aAC3B,CAAC;YACF,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACzC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC,CAAC,oBAAoB,EAAE,eAAe,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC;QACzG,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,SAAiB,EAAE,SAAiB;QAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,uBAAuB,CAAC,qBAAqB,SAAS,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;YAC1C,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACxC,IAAI,EAAE,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;gBAAE,OAAO,CAAC,8BAA8B;YACxE,MAAM,eAAe,GAAG,EAAE,EAAE,KAAK,KAAK,SAAS,CAAC;YAChD,MAAM,GAAG,GAAsB;gBAC7B,EAAE,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;gBACtC,MAAM;gBACN,IAAI,EAAE,EAAE,EAAE,IAAI,IAAI,SAAS;gBAC3B,OAAO,EAAE,EAAE,EAAE,OAAO,IAAI,SAAS;gBACjC,IAAI,EAAE,QAAQ;gBACd,SAAS;gBACT,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC;gBAC1B,UAAU,EAAE,CAAC;gBACb,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,CAAC;YACF,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,0GAA0G;IAC1G,KAAK,CAAC,YAAY;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,sEAAsE;QACtE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmD,CAAC;QACzE,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrC,IAAI,EAAE,CAAC,KAAK,KAAK,UAAU;gBAAE,SAAS;YACtC,IAAI,KAAK,GAAG,EAAE,CAAC,YAAY,IAAI,IAAI,CAAC,KAAK;gBAAE,SAAS;YACpD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACvC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;YACrB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACrC,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;gBACzC,KAAK,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,MAAM,EAAE,CAAC;oBAChC,IAAI,EAAE,CAAC,KAAK,KAAK,UAAU;wBAAE,SAAS,CAAC,gDAAgD;oBACvF,MAAM,GAAG,GAAsB;wBAC7B,EAAE,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;wBACtC,MAAM;wBACN,IAAI,EAAE,EAAE,CAAC,IAAI;wBACb,OAAO,EAAE,EAAE,CAAC,OAAO;wBACnB,IAAI,EAAE,QAAQ;wBACd,SAAS,EAAE,EAAE;wBACb,OAAO,EAAE,CAAC;wBACV,UAAU,EAAE,CAAC;qBACd,CAAC;oBACF,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;oBAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;oBACnB,OAAO,EAAE,CAAC;gBACZ,CAAC;gBACD,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,yDAAyD;IACzD,YAAY;QACV,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,sEAAsE;IAEtE,2CAA2C;IACnC,QAAQ,CAAC,GAAsB,EAAE,IAA+B;QACtE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE;gBAC/B,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,UAAU,EAAE,GAAG,CAAC,OAAO;gBACvB,GAAG;gBACH,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBAChC,KAAK,EAAE,UAAU;aAClB,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC5C,IAAI,EAAE,EAAE,CAAC;gBACP,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;oBAAE,OAAO,CAAC,aAAa;gBACjD,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC;gBACrB,EAAE,CAAC,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;gBAC5B,2EAA2E;gBAC3E,yEAAyE;gBACzE,qBAAqB;gBACrB,IAAI,GAAG,CAAC,eAAe;oBAAE,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACN,iFAAiF;gBACjF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE;oBAC/B,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,UAAU,EAAE,CAAC;oBACb,GAAG;oBACH,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;oBAChC,KAAK,EAAE,SAAS;oBAChB,UAAU,EAAE,GAAG,CAAC,OAAO;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC5C,IAAI,EAAE,IAAI,EAAE,CAAC,KAAK,KAAK,UAAU;gBAAE,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,UAAU;YAAE,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChE,CAAC;IAED,6DAA6D;IACrD,YAAY,CAAC,EAAgB;QACnC,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC,UAAU,IAAI,CAAC,CAAC;QACtD,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;QACrC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC,mDAAmD;IAC3E,CAAC;IAEO,qBAAqB,CAAC,MAAc;QAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACjC,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,IAAI,EAAE,CAAC,MAAM,KAAK,MAAM;gBAAE,SAAS;YACnC,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;YAChC,QAAQ,IAAI,CAAC,CAAC;YACd,IAAI,EAAE,CAAC,GAAG,KAAK,KAAK;gBAAE,MAAM,IAAI,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE;YACtB,MAAM;YACN,oBAAoB,EAAE,MAAM,CAAC,QAAQ,CAAC;YACtC,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;YAC/B,QAAQ,EAAE,KAAK;YACf,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IACvE,aAAa,CAAC,MAAc;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACjC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACjI,CAAC;QACD,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,kFAAkF;IAC1E,cAAc;QACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9C,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;YACxE,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,IAAI,GAAsB,CAAC;YAC3B,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;gBACxE,SAAS;YACX,CAAC;YACD,IACE,OAAO,GAAG,EAAE,SAAS,KAAK,QAAQ;gBAClC,OAAO,GAAG,EAAE,MAAM,KAAK,QAAQ;gBAC/B,OAAO,GAAG,EAAE,OAAO,KAAK,QAAQ;gBAChC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;gBAC7B,GAAG,CAAC,OAAO,GAAG,CAAC;gBACf,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EACpD,CAAC;gBACD,SAAS;YACX,CAAC;YACD,iEAAiE;YACjE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,qFAAqF;IAC7E,cAAc;QACpB,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,sEAAsE;IAEtE,6EAA6E;IACrE,KAAK,CAAC,aAAa,CAAC,GAAsB;QAChD,IAAI,OAAO,GAAiC,IAAI,CAAC;QACjD,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;YAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YACxC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAClD,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;gBACvB,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;oBAAS,CAAC;gBACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;YACD,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;gBAAS,CAAC;YACT,IAAI,OAAO;gBAAE,MAAM,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,qFAAqF;IAC7E,kBAAkB;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,GAAe,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAChG,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;YACrC,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACtE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;YAC5E,6EAA6E;YAC7E,6CAA6C;QAC/C,CAAC;IACH,CAAC;IAED,sEAAsE;IAE9D,YAAY,CAAI,MAAc,EAAE,EAAoB;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7D,IAAI,IAAiB,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,IAAI,EAAE,CAAC;gBACP,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI;oBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/core/PinAttemptStore.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PinAttemptStore — durable write-through behind the PIN routes' per-IP
+ * brute-force lockout (docs/specs/routing-control-room-spend-alerts.md,
+ * Surface 2, S2-1 hardening).
+ *
+ * `checkMandatePin`'s attempt counter was an in-memory Map, so a server restart
+ * reset the lockout. This store persists the counters to
+ * `<stateDir>/state/pin-attempts.json` (atomic tmp+rename) and is shared by the
+ * PIN routes. Semantics unchanged: N attempts per window per IP; the window
+ * expiry clears the entry. Express `trust proxy` is off fleet-wide, so req.ip
+ * already ignores X-Forwarded-For.
+ */
+export declare class PinAttemptStore {
+    private readonly filePath;
+    private entries;
+    private readonly maxAttempts;
+    private readonly windowMs;
+    private readonly now;
+    constructor(opts: {
+        stateDir: string;
+        maxAttempts?: number;
+        windowMs?: number;
+        now?: () => number;
+    });
+    /** True when the IP is currently locked out. */
+    blocked(ip: string): boolean;
+    /** Record a FAILED attempt; returns attempts remaining (≥ 0). */
+    recordFailure(ip: string): number;
+    /** Clear an IP's counter on a successful PIN entry. */
+    recordSuccess(ip: string): void;
+    private current;
+    private load;
+    private persist;
+}
+//# sourceMappingURL=PinAttemptStore.d.ts.map

package/dist/core/PinAttemptStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PinAttemptStore.d.ts","sourceRoot":"","sources":["../../src/core/PinAttemptStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAUnG,gDAAgD;IAChD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK5B,iEAAiE;IACjE,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAWjC,uDAAuD;IACvD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI/B,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,OAAO;CAUhB"}