instar 1.3.782 → 1.3.784

package/dist/core/RenderedPlanStore.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RenderedPlanStore — the S2-3/C3-4/C5-3 canonical rendered-plan machinery of
+ * the Routing Control Room PIN surfaces (docs/specs/routing-control-room-
+ * spend-alerts.md, Increment B, Surface 2).
+ *
+ * The PIN authorizes a CANONICAL SERVER-RENDERED PLAN — nothing else applies:
+ *  - render(): takes the structured request, enumerates EVERY field the commit
+ *    will change into an immutable plan snapshot (plain language + typed
+ *    fields), pins the version(s) of every governed store the plan touches,
+ *    mints a single-use nonce, stamps a short TTL.
+ *  - commit(): validates plan exists / not consumed / not expired / nonce
+ *    matches / pinned versions still current — then returns EXACTLY the
+ *    snapshot's fields. A request field absent from the render can never be
+ *    committed (the smuggled-field gap is closed by construction: the commit
+ *    path never sees the original request).
+ *  - The nonce is consumed on commit (no replay); an expired plan must be
+ *    re-rendered; a version drift refuses deterministically ("re-rendered —
+ *    here's the fresh plan" is the caller's UX).
+ *
+ * No separable "approved-plan token" outlives the single commit — a captured
+ * approval is worthless (C3-4).
+ */
+export declare const PLAN_TTL_MS: number;
+export type PlanAction = 'caps-adjust' | 'go-live' | 'unfreeze' | 'price-promote';
+export interface RenderedPlan {
+    planId: string;
+    nonce: string;
+    action: PlanAction;
+    /** The plain-language enumeration the operator PIN-approves. */
+    renderedText: string;
+    /** The EXACT typed fields the commit will apply — the ONLY commit input. */
+    fields: Record<string, unknown>;
+    /** Store-version pins (e.g. { capsStore: 3 }) checked at commit (C5-3). */
+    versionsPinned: Record<string, number>;
+    expiresAt: number;
+    consumed: boolean;
+    renderedAt: number;
+}
+export declare class PlanCommitError extends Error {
+    code: 'unknown-plan' | 'consumed' | 'expired' | 'bad-nonce' | 'version-drift';
+    constructor(code: 'unknown-plan' | 'consumed' | 'expired' | 'bad-nonce' | 'version-drift', msg: string);
+}
+export declare class RenderedPlanStore {
+    private plans;
+    private readonly now;
+    private readonly ttlMs;
+    constructor(opts?: {
+        now?: () => number;
+        ttlMs?: number;
+    });
+    /** Render an immutable plan snapshot. The caller provides the plain-language text and the exact typed fields. */
+    render(action: PlanAction, renderedText: string, fields: Record<string, unknown>, versionsPinned: Record<string, number>): RenderedPlan;
+    /**
+     * Validate + consume. `currentVersions` supplies the LIVE version of every
+     * governed store; commit refuses on a mismatch of any store the plan pinned.
+     * Returns the immutable snapshot fields — the SOLE commit input.
+     */
+    commit(planId: string, nonce: string, currentVersions: Record<string, number>): RenderedPlan;
+    private prune;
+}
+//# sourceMappingURL=RenderedPlanStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RenderedPlanStore.d.ts","sourceRoot":"","sources":["../../src/core/RenderedPlanStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,eAAO,MAAM,WAAW,QAAiB,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,CAAC;AAElF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACrB,IAAI,EAAE,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe;gBAA7E,IAAI,EAAE,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,EAAE,GAAG,EAAE,MAAM;CAI9G;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAKzD,iHAAiH;IACjH,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY;IAiBvI;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY;IAmB5F,OAAO,CAAC,KAAK;CAMd"}

package/dist/core/RenderedPlanStore.js

@@ -0,0 +1,92 @@
+/**
+ * RenderedPlanStore — the S2-3/C3-4/C5-3 canonical rendered-plan machinery of
+ * the Routing Control Room PIN surfaces (docs/specs/routing-control-room-
+ * spend-alerts.md, Increment B, Surface 2).
+ *
+ * The PIN authorizes a CANONICAL SERVER-RENDERED PLAN — nothing else applies:
+ *  - render(): takes the structured request, enumerates EVERY field the commit
+ *    will change into an immutable plan snapshot (plain language + typed
+ *    fields), pins the version(s) of every governed store the plan touches,
+ *    mints a single-use nonce, stamps a short TTL.
+ *  - commit(): validates plan exists / not consumed / not expired / nonce
+ *    matches / pinned versions still current — then returns EXACTLY the
+ *    snapshot's fields. A request field absent from the render can never be
+ *    committed (the smuggled-field gap is closed by construction: the commit
+ *    path never sees the original request).
+ *  - The nonce is consumed on commit (no replay); an expired plan must be
+ *    re-rendered; a version drift refuses deterministically ("re-rendered —
+ *    here's the fresh plan" is the caller's UX).
+ *
+ * No separable "approved-plan token" outlives the single commit — a captured
+ * approval is worthless (C3-4).
+ */
+import crypto from 'node:crypto';
+export const PLAN_TTL_MS = 10 * 60 * 1000;
+export class PlanCommitError extends Error {
+    code;
+    constructor(code, msg) {
+        super(msg);
+        this.code = code;
+        this.name = 'PlanCommitError';
+    }
+}
+export class RenderedPlanStore {
+    plans = new Map();
+    now;
+    ttlMs;
+    constructor(opts) {
+        this.now = opts?.now ?? (() => Date.now());
+        this.ttlMs = opts?.ttlMs ?? PLAN_TTL_MS;
+    }
+    /** Render an immutable plan snapshot. The caller provides the plain-language text and the exact typed fields. */
+    render(action, renderedText, fields, versionsPinned) {
+        this.prune();
+        const plan = {
+            planId: crypto.randomBytes(8).toString('hex'),
+            nonce: crypto.randomBytes(16).toString('hex'),
+            action,
+            renderedText,
+            fields: structuredClone(fields),
+            versionsPinned: { ...versionsPinned },
+            expiresAt: this.now() + this.ttlMs,
+            consumed: false,
+            renderedAt: this.now(),
+        };
+        this.plans.set(plan.planId, plan);
+        return plan;
+    }
+    /**
+     * Validate + consume. `currentVersions` supplies the LIVE version of every
+     * governed store; commit refuses on a mismatch of any store the plan pinned.
+     * Returns the immutable snapshot fields — the SOLE commit input.
+     */
+    commit(planId, nonce, currentVersions) {
+        const plan = this.plans.get(planId);
+        if (!plan)
+            throw new PlanCommitError('unknown-plan', 'no such plan — render one first');
+        if (plan.consumed)
+            throw new PlanCommitError('consumed', 'plan already committed (single-use nonce)');
+        if (this.now() > plan.expiresAt)
+            throw new PlanCommitError('expired', 'plan expired — re-render');
+        const a = crypto.createHash('sha256').update(String(nonce)).digest();
+        const b = crypto.createHash('sha256').update(plan.nonce).digest();
+        if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+            throw new PlanCommitError('bad-nonce', 'nonce mismatch');
+        }
+        for (const [store, pinned] of Object.entries(plan.versionsPinned)) {
+            if (currentVersions[store] !== pinned) {
+                throw new PlanCommitError('version-drift', `store '${store}' changed since the plan was rendered (pinned ${pinned}, is ${currentVersions[store]}) — re-rendered plan required`);
+            }
+        }
+        plan.consumed = true; // consume BEFORE returning — no replay even on a downstream failure
+        return plan;
+    }
+    prune() {
+        const now = this.now();
+        for (const [id, p] of this.plans) {
+            if (p.consumed || now > p.expiresAt + this.ttlMs)
+                this.plans.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=RenderedPlanStore.js.map

package/dist/core/RenderedPlanStore.js.map

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

package/dist/core/RoutingSpendCapsStore.d.ts

@@ -0,0 +1,113 @@
+/**
+ * RoutingSpendCapsStore — the DEDICATED PIN-only money-authority store of the
+ * Routing Control Room (docs/specs/routing-control-room-spend-alerts.md,
+ * Increment B, Surface 2 / S-F2).
+ *
+ * Caps + go-live + metered-lease designation live in
+ * `<stateDir>/state/routing-spend-caps.json`, written ONLY through this store's
+ * typed mutators — which the PIN routes (and the Bearer set-true-only freeze)
+ * call. The file is NEVER under any `PATCHABLE_CONFIG_KEYS` key, so a Bearer
+ * `PATCH /config` can structurally never arm a door, unfreeze a key, or raise a
+ * cap (regression-tested).
+ *
+ * Concurrency/authority discipline:
+ *  - Every write is atomic (tmp+rename) and bumps the store VERSION — the
+ *    optimistic-concurrency anchor the rendered-plan commit checks (C5-3):
+ *    a plan pins the version it read; commit refuses on mismatch.
+ *  - Every committed mutation ADDITIONALLY passes a schema-level validator
+ *    independent of the plan machinery (C4-4) — a plan-renderer bug can never
+ *    become the sole authority boundary.
+ *  - Every change appends a BEFORE+AFTER audit row (never just the delta).
+ *  - STOP is cheap: `freeze()` is set-TRUE-only (the Bearer surface); unfreeze
+ *    goes through the PIN plan path like every other money-releasing action.
+ *  - Deny-by-default: with no go-live record every metered door stays skipped.
+ */
+export interface KeyCapsRecord {
+    provider: string;
+    lifetimeCapUsd: number;
+    dailyCapUsd: number;
+    frozen: boolean;
+    frozenBy?: string;
+    frozenAt?: string;
+}
+export interface GoLiveRecord {
+    enabled: boolean;
+    keyRef: string;
+    /** The PIN-designated metered-lease machine (FD-13). */
+    designatedMachineId: string;
+    designatedAt: string;
+    /** Bumped on every designation/cap-lowering (A-M9/A-B4) — the gate re-validates against it. */
+    epoch: number;
+}
+export interface CapsStoreFile {
+    /** Optimistic-concurrency version — bumped on EVERY write (C5-3). */
+    version: number;
+    caps: Record<string, KeyCapsRecord>;
+    goLive: Record<string, GoLiveRecord>;
+    /** Metered-lease epoch — bumped on designation change and cap-lowering. */
+    leaseEpoch: number;
+}
+export interface CapsAuditRow {
+    ts: string;
+    action: string;
+    actor: string;
+    before: CapsStoreFile;
+    after: CapsStoreFile;
+}
+/** Schema-level validator, independent of the rendered-plan machinery (C4-4). */
+export declare function validateCapsFile(f: unknown, knownKeyRefs?: ReadonlySet<string>, knownDoors?: ReadonlySet<string>): string | null;
+export interface RoutingSpendCapsStoreOptions {
+    /** The agent's `.instar/` dir. */
+    stateDir: string;
+    /** Where audit rows append (default `<stateDir>/state/routing-spend-caps-audit.jsonl`). */
+    auditPath?: string;
+    knownKeyRefs?: ReadonlySet<string>;
+    knownDoors?: ReadonlySet<string>;
+    now?: () => number;
+}
+export declare class RoutingSpendCapsStore {
+    private readonly filePath;
+    private readonly auditPath;
+    private readonly knownKeyRefs?;
+    private readonly knownDoors?;
+    private readonly now;
+    constructor(opts: RoutingSpendCapsStoreOptions);
+    /** Read the store. A missing file is the deny-by-default EMPTY store; a corrupt file throws (fail closed — money state must never be silently defaulted). */
+    read(): CapsStoreFile;
+    /** Current optimistic-concurrency version (0 when absent). */
+    version(): number;
+    /**
+     * Apply a typed mutation. `expectedVersion` is the optimistic-concurrency check
+     * (pass null to skip ONLY for the Bearer freeze path — halting money must never
+     * be blocked by a concurrent PIN plan).
+     */
+    private mutate;
+    /** PIN path: adjust caps for a key (raise or lower; lowering bumps the lease epoch — A-M9). */
+    adjustCaps(actor: string, expectedVersion: number, keyRef: string, provider: string, caps: {
+        lifetimeCapUsd: number;
+        dailyCapUsd: number;
+    }): CapsStoreFile;
+    /** PIN path: arm/disarm a door + designate the metered-lease machine (FD-13). */
+    setGoLive(actor: string, expectedVersion: number, door: string, rec: {
+        enabled: boolean;
+        keyRef: string;
+        designatedMachineId: string;
+    }): CapsStoreFile;
+    /** PIN path: unfreeze (releasing money is always the operator's). */
+    unfreeze(actor: string, expectedVersion: number, keyRef: string): CapsStoreFile;
+    /**
+     * Bearer path: FREEZE a key — set-TRUE-only (S-F5/X-C5); records the actor; never
+     * takes an expectedVersion (halting money is never blocked by a concurrent plan).
+     * Creates the caps record from defaults if absent so an un-adjusted key can still
+     * be frozen instantly.
+     */
+    freeze(actor: string, keyRef: string, defaults?: {
+        provider: string;
+        lifetimeCapUsd: number;
+        dailyCapUsd: number;
+    }): CapsStoreFile;
+    /** Bearer-read audit trail (most recent last; bounded by the caller's limit). */
+    auditLog(limit?: number): CapsAuditRow[];
+    private appendAudit;
+}
+//# sourceMappingURL=RoutingSpendCapsStore.d.ts.map

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

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

package/dist/core/RoutingSpendCapsStore.js

@@ -0,0 +1,241 @@
+/**
+ * RoutingSpendCapsStore — the DEDICATED PIN-only money-authority store of the
+ * Routing Control Room (docs/specs/routing-control-room-spend-alerts.md,
+ * Increment B, Surface 2 / S-F2).
+ *
+ * Caps + go-live + metered-lease designation live in
+ * `<stateDir>/state/routing-spend-caps.json`, written ONLY through this store's
+ * typed mutators — which the PIN routes (and the Bearer set-true-only freeze)
+ * call. The file is NEVER under any `PATCHABLE_CONFIG_KEYS` key, so a Bearer
+ * `PATCH /config` can structurally never arm a door, unfreeze a key, or raise a
+ * cap (regression-tested).
+ *
+ * Concurrency/authority discipline:
+ *  - Every write is atomic (tmp+rename) and bumps the store VERSION — the
+ *    optimistic-concurrency anchor the rendered-plan commit checks (C5-3):
+ *    a plan pins the version it read; commit refuses on mismatch.
+ *  - Every committed mutation ADDITIONALLY passes a schema-level validator
+ *    independent of the plan machinery (C4-4) — a plan-renderer bug can never
+ *    become the sole authority boundary.
+ *  - Every change appends a BEFORE+AFTER audit row (never just the delta).
+ *  - STOP is cheap: `freeze()` is set-TRUE-only (the Bearer surface); unfreeze
+ *    goes through the PIN plan path like every other money-releasing action.
+ *  - Deny-by-default: with no go-live record every metered door stays skipped.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const EMPTY = { version: 0, caps: {}, goLive: {}, leaseEpoch: 0 };
+/** Schema-level validator, independent of the rendered-plan machinery (C4-4). */
+export function validateCapsFile(f, knownKeyRefs, knownDoors) {
+    if (!f || typeof f !== 'object')
+        return 'not an object';
+    const file = f;
+    if (!Number.isInteger(file.version) || file.version < 0)
+        return 'version must be a non-negative integer';
+    if (!Number.isInteger(file.leaseEpoch) || file.leaseEpoch < 0)
+        return 'leaseEpoch must be a non-negative integer';
+    if (!file.caps || typeof file.caps !== 'object')
+        return 'caps must be an object';
+    if (!file.goLive || typeof file.goLive !== 'object')
+        return 'goLive must be an object';
+    for (const [keyRef, c] of Object.entries(file.caps)) {
+        if (knownKeyRefs && !knownKeyRefs.has(keyRef))
+            return `unknown keyRef '${keyRef}'`;
+        if (!c || typeof c !== 'object')
+            return `caps['${keyRef}'] not an object`;
+        if (typeof c.provider !== 'string' || !c.provider.trim())
+            return `caps['${keyRef}'].provider missing`;
+        for (const capField of ['lifetimeCapUsd', 'dailyCapUsd']) {
+            const v = c[capField];
+            if (typeof v !== 'number' || !Number.isFinite(v) || v < 0)
+                return `caps['${keyRef}'].${capField} must be ≥ 0`;
+        }
+        if (typeof c.frozen !== 'boolean')
+            return `caps['${keyRef}'].frozen must be boolean`;
+    }
+    for (const [door, g] of Object.entries(file.goLive)) {
+        if (knownDoors && !knownDoors.has(door))
+            return `unknown door '${door}'`;
+        if (!g || typeof g !== 'object')
+            return `goLive['${door}'] not an object`;
+        if (typeof g.enabled !== 'boolean')
+            return `goLive['${door}'].enabled must be boolean`;
+        if (typeof g.keyRef !== 'string' || !g.keyRef.trim())
+            return `goLive['${door}'].keyRef missing`;
+        if (typeof g.designatedMachineId !== 'string' || !g.designatedMachineId.trim())
+            return `goLive['${door}'].designatedMachineId missing`;
+        if (!Number.isInteger(g.epoch) || g.epoch < 0)
+            return `goLive['${door}'].epoch must be a non-negative integer`;
+    }
+    return null;
+}
+export class RoutingSpendCapsStore {
+    filePath;
+    auditPath;
+    knownKeyRefs;
+    knownDoors;
+    now;
+    constructor(opts) {
+        const stateSub = path.join(opts.stateDir, 'state');
+        fs.mkdirSync(stateSub, { recursive: true });
+        this.filePath = path.join(stateSub, 'routing-spend-caps.json');
+        this.auditPath = opts.auditPath ?? path.join(stateSub, 'routing-spend-caps-audit.jsonl');
+        this.knownKeyRefs = opts.knownKeyRefs;
+        this.knownDoors = opts.knownDoors;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Read the store. A missing file is the deny-by-default EMPTY store; a corrupt file throws (fail closed — money state must never be silently defaulted). */
+    read() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.filePath, 'utf-8');
+        }
+        catch {
+            // @silent-fallback-ok: an ABSENT store is the legitimate pre-go-live state —
+            // deny-by-default (no caps overrides, no doors armed). Only absence is safe
+            // to default; a PRESENT-but-corrupt file throws below.
+            return structuredClone(EMPTY);
+        }
+        const parsed = JSON.parse(raw); // throws on corrupt → caller fails closed
+        const err = validateCapsFile(parsed, this.knownKeyRefs, this.knownDoors);
+        if (err)
+            throw new Error(`routing-spend caps store invalid (fail-closed): ${err}`);
+        return parsed;
+    }
+    /** Current optimistic-concurrency version (0 when absent). */
+    version() {
+        try {
+            return this.read().version;
+        }
+        catch {
+            // A corrupt store has no usable version; surface a sentinel the plan path
+            // will fail to match (commit then refuses — the safe direction).
+            return -1;
+        }
+    }
+    /**
+     * Apply a typed mutation. `expectedVersion` is the optimistic-concurrency check
+     * (pass null to skip ONLY for the Bearer freeze path — halting money must never
+     * be blocked by a concurrent PIN plan).
+     */
+    mutate(action, actor, expectedVersion, fn) {
+        const before = this.read();
+        if (expectedVersion !== null && before.version !== expectedVersion) {
+            throw new Error(`caps store version drift (expected ${expectedVersion}, is ${before.version}) — re-render the plan`);
+        }
+        const after = structuredClone(before);
+        fn(after);
+        after.version = before.version + 1;
+        const err = validateCapsFile(after, this.knownKeyRefs, this.knownDoors);
+        if (err)
+            throw new Error(`caps mutation rejected by schema validator (C4-4): ${err}`);
+        const tmp = this.filePath + '.tmp';
+        fs.writeFileSync(tmp, JSON.stringify(after, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, this.filePath);
+        this.appendAudit({ ts: new Date(this.now()).toISOString(), action, actor, before, after });
+        return after;
+    }
+    /** PIN path: adjust caps for a key (raise or lower; lowering bumps the lease epoch — A-M9). */
+    adjustCaps(actor, expectedVersion, keyRef, provider, caps) {
+        return this.mutate('caps-adjust', actor, expectedVersion, (f) => {
+            const prev = f.caps[keyRef];
+            const lowered = prev !== undefined &&
+                (caps.lifetimeCapUsd < prev.lifetimeCapUsd || caps.dailyCapUsd < prev.dailyCapUsd);
+            f.caps[keyRef] = {
+                provider,
+                lifetimeCapUsd: caps.lifetimeCapUsd,
+                dailyCapUsd: caps.dailyCapUsd,
+                frozen: prev?.frozen ?? false,
+                ...(prev?.frozenBy ? { frozenBy: prev.frozenBy } : {}),
+                ...(prev?.frozenAt ? { frozenAt: prev.frozenAt } : {}),
+            };
+            if (lowered)
+                f.leaseEpoch += 1; // fenced cap-lowering — the gate re-reads and clamps
+        });
+    }
+    /** PIN path: arm/disarm a door + designate the metered-lease machine (FD-13). */
+    setGoLive(actor, expectedVersion, door, rec) {
+        return this.mutate('go-live', actor, expectedVersion, (f) => {
+            const prevEpoch = f.goLive[door]?.epoch ?? 0;
+            f.goLive[door] = {
+                enabled: rec.enabled,
+                keyRef: rec.keyRef,
+                designatedMachineId: rec.designatedMachineId,
+                designatedAt: new Date(this.now()).toISOString(),
+                epoch: prevEpoch + 1,
+            };
+            f.leaseEpoch += 1;
+        });
+    }
+    /** PIN path: unfreeze (releasing money is always the operator's). */
+    unfreeze(actor, expectedVersion, keyRef) {
+        return this.mutate('unfreeze', actor, expectedVersion, (f) => {
+            const c = f.caps[keyRef];
+            if (!c)
+                throw new Error(`unfreeze: no caps record for '${keyRef}'`);
+            c.frozen = false;
+            delete c.frozenBy;
+            delete c.frozenAt;
+        });
+    }
+    /**
+     * Bearer path: FREEZE a key — set-TRUE-only (S-F5/X-C5); records the actor; never
+     * takes an expectedVersion (halting money is never blocked by a concurrent plan).
+     * Creates the caps record from defaults if absent so an un-adjusted key can still
+     * be frozen instantly.
+     */
+    freeze(actor, keyRef, defaults) {
+        return this.mutate('freeze', actor, null, (f) => {
+            const c = f.caps[keyRef];
+            if (c) {
+                c.frozen = true;
+                c.frozenBy = actor;
+                c.frozenAt = new Date(this.now()).toISOString();
+            }
+            else {
+                f.caps[keyRef] = {
+                    provider: defaults?.provider ?? 'unknown',
+                    lifetimeCapUsd: defaults?.lifetimeCapUsd ?? 0,
+                    dailyCapUsd: defaults?.dailyCapUsd ?? 0,
+                    frozen: true,
+                    frozenBy: actor,
+                    frozenAt: new Date(this.now()).toISOString(),
+                };
+            }
+        });
+    }
+    /** Bearer-read audit trail (most recent last; bounded by the caller's limit). */
+    auditLog(limit = 100) {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.auditPath, 'utf-8');
+        }
+        catch {
+            // @silent-fallback-ok: no audit yet — an empty log is the fresh-store state.
+            return [];
+        }
+        const rows = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                rows.push(JSON.parse(line));
+            }
+            catch {
+                // Malformed-row-skip (torn trailing append).
+                continue;
+            }
+        }
+        return rows.slice(-Math.max(1, limit));
+    }
+    appendAudit(row) {
+        try {
+            fs.appendFileSync(this.auditPath, JSON.stringify(row) + '\n', { mode: 0o600 });
+        }
+        catch {
+            // @silent-fallback-ok: the audit append is observability riding a mutation that
+            // already landed atomically; a failed append never rolls back money state.
+        }
+    }
+}
+//# sourceMappingURL=RoutingSpendCapsStore.js.map

package/dist/core/RoutingSpendCapsStore.js.map

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

package/dist/core/SpendAlertDispatcher.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SpendAlertDispatcher — the Increment-C channel-abstracted alert layer of the
+ * Routing Control Room (docs/specs/routing-control-room-spend-alerts.md,
+ * §Surface 2 Alerts / FD-6 / Amendment 2).
+ *
+ * ONE dedicated topic, message-INTO not topic-PER: every spend alert lands in
+ * the single "💰 Routing & Spend Alerts" topic (the `burnDetection.alertTopicId`
+ * sendToTopic precedent) — deliberately NEVER `POST /attention` (topic-per-item
+ * is the flood the operator directive forbids). The lifeline is the single
+ * NAMED emergency exception (unresolvable topic / failed money-critical
+ * delivery), never a second routine destination.
+ *
+ * Discipline (all BEFORE any channel send):
+ *  - LANE-SCOPED dedup (S-F8): money-critical kinds (cap-hit, holder-dead)
+ *    ride a DISTINCT dedupe lane from informational kinds (door-dark,
+ *    fallback-spike, price/recon drift), so a flapping door's volume can never
+ *    coalesce a money-critical cap alert into a digest line. Lanes govern
+ *    COALESCING, never the destination.
+ *  - EDGE latch per dedupeKey: latches ONLY on CONFIRMED delivery, so a
+ *    transient failure stays eligible for re-send instead of permanently
+ *    suppressed.
+ *  - COALESCING: informational alerts within the digest window aggregate into
+ *    ONE message per episode; money-critical alerts are never digested.
+ *  - dryRun-FIRST (FD-16: Increment C ships dryRun-first live-on-dev): while
+ *    dryRun holds, every decision is recorded to the scrubbed jsonl and
+ *    NOTHING is delivered.
+ *  - Scrubbed jsonl audit (S-F7): kind / lane / dedupeKey / decision / door /
+ *    counts — NEVER a provider response/error body, never a key-shaped
+ *    substring, never a token.
+ */
+export type SpendAlertKind = 'stale-price' | 'observed-drift' | 'cap-approach' | 'cap-hit' | 'door-dark' | 'fallback-spike' | 'recon-drift' | 'holder-dead';
+/** Money-critical kinds ride their own dedupe lane + the durable relay (S-F8/G5). */
+export declare const MONEY_CRITICAL_KINDS: ReadonlySet<SpendAlertKind>;
+export interface SpendAlert {
+    kind: SpendAlertKind;
+    /** Stable idempotency key — see the spec's per-kind dedupe-key shapes. */
+    dedupeKey: string;
+    /** Metadata-only, plain-English text (already scrubbed by the emitter). */
+    text: string;
+    /** Re-arm window override; default 24h informational / 6h money-critical. */
+    reArmMs?: number;
+}
+export type DispatchDecision = 'sent' | 'sent-lifeline' | 'queued-durable' | 'coalesced' | 'suppressed' | 'dry-run' | 'failed';
+export interface DispatchResult {
+    decision: DispatchDecision;
+    lane: 'money-critical' | 'informational';
+}
+/**
+ * A delivery channel (FD-6). Increment C ships TelegramSpendTopicChannel; a
+ * future SlackSpendChannel is a registry entry + `alerts.channels` config add —
+ * no dispatcher/emitter rework.
+ */
+export interface AlertChannel {
+    readonly id: string;
+    /**
+     * Deliver one already-deduped, already-coalesced message. Returns true on
+     * CONFIRMED delivery (the latch condition). `moneyCritical` lets the channel
+     * pick the durable path.
+     */
+    deliver(text: string, moneyCritical: boolean): Promise<'sent' | 'sent-lifeline' | 'queued-durable' | 'failed'>;
+}
+export interface SpendAlertDispatcherOptions {
+    channels: AlertChannel[];
+    /** dryRun-first (FD-16): default TRUE — decisions audited, nothing delivered. */
+    dryRun?: boolean;
+    /** Digest window for informational coalescing (default 15 min). */
+    digestWindowMs?: number;
+    /** Scrubbed audit sink path (default `<logsDir>/routing-spend-alerts.jsonl`). */
+    auditPath?: string;
+    now?: () => number;
+}
+export declare class SpendAlertDispatcher {
+    private readonly channels;
+    private readonly dryRun;
+    private readonly digestWindowMs;
+    private readonly auditPath;
+    private readonly now;
+    /** Edge latches per lane (S-F8: distinct lanes so volumes can't cross-suppress). */
+    private latched;
+    /** Pending informational digest: texts accumulated within the window. */
+    private digestPending;
+    private digestTimer;
+    private digestFlushInFlight;
+    constructor(opts: SpendAlertDispatcherOptions);
+    laneOf(kind: SpendAlertKind): 'money-critical' | 'informational';
+    /** Dispatch one alert through dedup → coalescing → channels. Never throws. */
+    dispatch(alert: SpendAlert): Promise<DispatchResult>;
+    /** Flush any pending digest immediately (test hook + shutdown path). */
+    flushDigest(): Promise<void>;
+    private scheduleDigestFlush;
+    private deliverThroughChannels;
+    private audit;
+}
+//# sourceMappingURL=SpendAlertDispatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SpendAlertDispatcher.d.ts","sourceRoot":"","sources":["../../src/core/SpendAlertDispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,SAAS,GACT,WAAW,GACX,gBAAgB,GAChB,aAAa,GACb,aAAa,CAAC;AAElB,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,cAAc,CAAuC,CAAC;AAErG,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,YAAY,GACZ,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,GAAG,gBAAgB,GAAG,QAAQ,CAAC,CAAC;CAChH;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAMD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,oFAAoF;IACpF,OAAO,CAAC,OAAO,CAA6B;IAC5C,yEAAyE;IACzE,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,mBAAmB,CAAS;gBAExB,IAAI,EAAE,2BAA2B;IAQ7C,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,eAAe;IAIhE,8EAA8E;IACxE,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAwC1D,wEAAwE;IAClE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBlC,OAAO,CAAC,mBAAmB;YASb,sBAAsB;IAgBpC,OAAO,CAAC,KAAK;CAUd"}