instar 1.3.782 → 1.3.784

package/dist/core/SpendAlertDispatcher.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Money-critical kinds ride their own dedupe lane + the durable relay (S-F8/G5). */
+export const MONEY_CRITICAL_KINDS = new Set(['cap-hit', 'holder-dead']);
+const DEFAULT_REARM_INFORMATIONAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_REARM_MONEY_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_DIGEST_WINDOW_MS = 15 * 60 * 1000;
+export class SpendAlertDispatcher {
+    channels;
+    dryRun;
+    digestWindowMs;
+    auditPath;
+    now;
+    /** Edge latches per lane (S-F8: distinct lanes so volumes can't cross-suppress). */
+    latched = new Map(); // `${lane}|${dedupeKey}` → confirmed-at ms
+    /** Pending informational digest: texts accumulated within the window. */
+    digestPending = [];
+    digestTimer = null;
+    digestFlushInFlight = false;
+    constructor(opts) {
+        this.channels = opts.channels;
+        this.dryRun = opts.dryRun !== false; // default TRUE (FD-16 dryRun-first)
+        this.digestWindowMs = opts.digestWindowMs ?? DEFAULT_DIGEST_WINDOW_MS;
+        this.auditPath = opts.auditPath ?? null;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    laneOf(kind) {
+        return MONEY_CRITICAL_KINDS.has(kind) ? 'money-critical' : 'informational';
+    }
+    /** Dispatch one alert through dedup → coalescing → channels. Never throws. */
+    async dispatch(alert) {
+        const lane = this.laneOf(alert.kind);
+        try {
+            const latchKey = `${lane}|${alert.dedupeKey}`;
+            const reArm = alert.reArmMs ?? (lane === 'money-critical' ? DEFAULT_REARM_MONEY_MS : DEFAULT_REARM_INFORMATIONAL_MS);
+            const last = this.latched.get(latchKey);
+            if (last !== undefined && this.now() - last < reArm) {
+                this.audit({ decision: 'suppressed', kind: alert.kind, lane, dedupeKey: alert.dedupeKey });
+                return { decision: 'suppressed', lane };
+            }
+            if (this.dryRun) {
+                // FD-16 soak: record the WOULD-send (with the latch set, so the soak
+                // telemetry measures the real post-dedup volume) — deliver nothing.
+                this.latched.set(latchKey, this.now());
+                this.audit({ decision: 'dry-run', kind: alert.kind, lane, dedupeKey: alert.dedupeKey });
+                return { decision: 'dry-run', lane };
+            }
+            if (lane === 'informational') {
+                // Coalesce into ONE digest message per window (never for money-critical).
+                this.digestPending.push({ key: alert.dedupeKey, text: alert.text });
+                this.latched.set(latchKey, this.now()); // digested = handled; window re-arms it
+                this.scheduleDigestFlush();
+                this.audit({ decision: 'coalesced', kind: alert.kind, lane, dedupeKey: alert.dedupeKey, pending: this.digestPending.length });
+                return { decision: 'coalesced', lane };
+            }
+            // Money-critical: immediate, never digested, durable path preferred.
+            const outcome = await this.deliverThroughChannels(alert.text, true);
+            if (outcome === 'sent' || outcome === 'sent-lifeline' || outcome === 'queued-durable') {
+                this.latched.set(latchKey, this.now());
+            }
+            this.audit({ decision: outcome, kind: alert.kind, lane, dedupeKey: alert.dedupeKey });
+            return { decision: outcome, lane };
+        }
+        catch (err) {
+            // The dispatcher is a notifier — it must never throw into an emitter's
+            // (or the gate's) call path. Audit and move on.
+            this.audit({ decision: 'failed', kind: alert.kind, lane, dedupeKey: alert.dedupeKey, error: String(err).slice(0, 200) });
+            return { decision: 'failed', lane };
+        }
+    }
+    /** Flush any pending digest immediately (test hook + shutdown path). */
+    async flushDigest() {
+        if (this.digestTimer) {
+            clearTimeout(this.digestTimer);
+            this.digestTimer = null;
+        }
+        if (this.digestFlushInFlight || this.digestPending.length === 0)
+            return;
+        this.digestFlushInFlight = true;
+        try {
+            const items = this.digestPending.splice(0);
+            const text = items.length === 1
+                ? items[0].text
+                : `📋 Routing spend digest (${items.length} notices):\n` + items.map((i) => `• ${i.text}`).join('\n');
+            const outcome = await this.deliverThroughChannels(text, false);
+            if (outcome === 'failed') {
+                // Stay eligible: un-latch the digested keys so the next occurrence retries.
+                for (const i of items)
+                    this.latched.delete(`informational|${i.key}`);
+            }
+            this.audit({ decision: `digest-${outcome}`, count: items.length });
+        }
+        finally {
+            this.digestFlushInFlight = false;
+        }
+    }
+    scheduleDigestFlush() {
+        if (this.digestTimer)
+            return;
+        this.digestTimer = setTimeout(() => {
+            this.digestTimer = null;
+            void this.flushDigest();
+        }, this.digestWindowMs);
+        this.digestTimer.unref?.();
+    }
+    async deliverThroughChannels(text, moneyCritical) {
+        let best = 'failed';
+        for (const ch of this.channels) {
+            try {
+                const r = await ch.deliver(text, moneyCritical);
+                if (r === 'sent')
+                    return 'sent';
+                if (r === 'queued-durable' && best === 'failed')
+                    best = 'queued-durable';
+                if (r === 'sent-lifeline' && best === 'failed')
+                    best = 'sent-lifeline';
+            }
+            catch {
+                // @silent-fallback-ok: one channel throwing must not break the others;
+                // the terminal outcome (incl. all-failed) is audited by the caller.
+            }
+        }
+        return best;
+    }
+    audit(entry) {
+        if (!this.auditPath)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.auditPath), { recursive: true });
+            fs.appendFileSync(this.auditPath, JSON.stringify({ ts: new Date(this.now()).toISOString(), ...entry }) + '\n', { mode: 0o600 });
+        }
+        catch {
+            // @silent-fallback-ok: the audit line is observability riding a
+            // notification decision that already happened — never blocks dispatch.
+        }
+    }
+}
+//# sourceMappingURL=SpendAlertDispatcher.js.map

package/dist/core/SpendAlertDispatcher.js.map

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

package/dist/core/SpendAlertEmitters.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SpendAlertEmitters — the Increment-C trigger set of the Routing Control Room
+ * (docs/specs/routing-control-room-spend-alerts.md, §Surface 2 Alerts —
+ * Triggers, "Self-Heal Before Notify").
+ *
+ * Every emitter is a SIGNAL consumer feeding the SpendAlertDispatcher: it
+ * blocks nothing, gates nothing, and throw-swallows so a notifier failure can
+ * never disturb the gate/router path it observes.
+ *
+ * Kinds produced here:
+ *  - cap-approach — 50%/80% on BOTH daily AND lifetime (G4), edge-triggered per
+ *    (capKind, threshold, window); coalesced into the digest.
+ *  - cap-hit — ONE edge-triggered money-critical alert, worded honestly
+ *    ("a reservation would exceed key X's daily cap", actual vs reserved —
+ *    A-Min13). Protective; the adjust action is the operator's.
+ *  - door-dark — downstream of swap-tail self-heal; escalates only on
+ *    whole-chain exhaustion (RouterFailClosedError plans). P19 brakes:
+ *    max-attempts = chain length per episode bucket, widening backoff, a
+ *    flapping breaker (N exhaustions/window → critical wording, bypasses
+ *    coalescing via the money-critical lane), scrubbed jsonl (the dispatcher's).
+ *  - fallback-spike — routine self-healed fallback churn is NOT an operator
+ *    event (Near-Silent): every fallback is counted; a digest line fires ONLY
+ *    when the hourly rate crosses an absolute ceiling (code constant).
+ *  - holder-dead — the ONE named exception to holder-single-voice (A2-2): a
+ *    SURVIVING machine emits when the pool observes the metered-lease holder
+ *    offline past the mesh-death threshold while any door is live. Stable
+ *    pool-wide dedupe key `spend-holder-dead:<keyEpoch>`. Single-machine:
+ *    strict no-op (there is no surviving other voice).
+ *  - recon-drift — the emit surface for the Layer-1c provider-reconciliation
+ *    sweep (lands next PR); wording per Amendment 1.
+ */
+import type { SpendAlertDispatcher } from './SpendAlertDispatcher.js';
+/** Cap-approach thresholds (G4) — code-defined, both cap kinds. */
+export declare const CAP_APPROACH_THRESHOLDS: readonly [0.5, 0.8];
+/** Fallback-spike absolute per-hour ceiling (code constant — Near-Silent default). */
+export declare const FALLBACK_SPIKE_PER_HOUR_CEILING = 60;
+/** Door-dark flapping breaker: N exhaustions inside the window escalate the wording. */
+export declare const DOOR_DARK_FLAP_THRESHOLD = 5;
+export declare const DOOR_DARK_FLAP_WINDOW_MS: number;
+/** Door-dark per-episode widening backoff base + episode bucket size. */
+export declare const DOOR_DARK_BACKOFF_BASE_MS: number;
+export declare const DOOR_DARK_EPISODE_BUCKET_MS: number;
+export interface GateAdmitEvent {
+    type: 'admit';
+    keyRef: string;
+    door: string;
+    committedLifetimeUsd: number;
+    committedDayUsd: number;
+    lifetimeCapUsd: number;
+    dailyCapUsd: number;
+}
+export interface GateRefusalEvent {
+    type: 'refusal';
+    reason: string;
+    keyRef?: string;
+    door?: string;
+    detail: string;
+}
+export type GateEvent = GateAdmitEvent | GateRefusalEvent;
+export interface NatureRoutePlanEvent {
+    component?: string;
+    dryRun: boolean;
+    failClosed?: boolean;
+    resolution?: {
+        outcome?: string;
+        resolvedChain?: string;
+        swapTail?: unknown[];
+        primary?: {
+            door?: string;
+        };
+    };
+    /** True when the served position was NOT the chain primary (a fallback served). */
+    servedFallback?: boolean;
+}
+export interface SpendAlertEmittersOptions {
+    dispatcher: SpendAlertDispatcher;
+    machineId: string;
+    now?: () => number;
+}
+export declare class SpendAlertEmitters {
+    private readonly dispatcher;
+    private readonly machineId;
+    private readonly now;
+    /** door-dark per-episode state: chain → { bucket, attempts, nextAllowedAtMs, exhaustionsWindow } */
+    private doorDark;
+    /** fallback counter: hour-bucket → count (bounded: only the current bucket is kept). */
+    private fallbackBucket;
+    constructor(opts: SpendAlertEmittersOptions);
+    /**
+     * Observer-isolated dispatch: the real dispatcher never throws/rejects, but
+     * the observer CONTRACT must hold against any implementation — a sync throw
+     * OR an async rejection here can never reach the gate/router path, and can
+     * never surface as an unhandled rejection.
+     */
+    private fire;
+    /** The MeteredSpendGate observer (onGateEvent). NEVER throws into the gate path. */
+    onGateEvent(ev: GateEvent): void;
+    private checkCapApproach;
+    /**
+     * The router-signal consumer (fed by the onNatureRoutePlan fan-out, I-9).
+     * Counts every served fallback (Near-Silent: jsonl only via the dispatcher's
+     * audit); emits a digest line ONLY on a rate spike; escalates door-dark on
+     * whole-chain exhaustion with P19 brakes.
+     */
+    onNatureRoutePlan(plan: NatureRoutePlanEvent): void;
+    private onChainExhausted;
+    private onFallbackServed;
+    /**
+     * holder-dead (A2-2): call from pool observation when the metered-lease
+     * holder is offline past the mesh-death threshold while any door is live.
+     * The caller (a SURVIVING machine) supplies the keyEpoch for the stable
+     * pool-wide dedupe key. Single-machine installs never call this.
+     */
+    onMeteredLeaseHolderDead(holderNickname: string, keyEpoch: number): void;
+    /** recon-drift emit surface (Layer 1c feeds this next PR — Amendment 1 wording). */
+    onReconciliationDrift(keyRef: string, door: string, driftPct: number): void;
+}
+//# sourceMappingURL=SpendAlertEmitters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SpendAlertEmitters.d.ts","sourceRoot":"","sources":["../../src/core/SpendAlertEmitters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,qBAAsB,CAAC;AAE3D,sFAAsF;AACtF,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AACvD,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,QAAgB,CAAC;AACvD,eAAO,MAAM,2BAA2B,QAAqB,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC7G,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,oBAAoB,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAMD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAA2G;IAC3H,wFAAwF;IACxF,OAAO,CAAC,cAAc,CAA0B;gBAEpC,IAAI,EAAE,yBAAyB;IAM3C;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IASZ,oFAAoF;IACpF,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAmBhC,OAAO,CAAC,gBAAgB;IAuBxB;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAanD,OAAO,CAAC,gBAAgB;IAiCxB,OAAO,CAAC,gBAAgB;IAiBxB;;;;;OAKG;IACH,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgBxE,oFAAoF;IACpF,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAc5E"}

package/dist/core/SpendAlertEmitters.js

@@ -0,0 +1,220 @@
+/**
+ * SpendAlertEmitters — the Increment-C trigger set of the Routing Control Room
+ * (docs/specs/routing-control-room-spend-alerts.md, §Surface 2 Alerts —
+ * Triggers, "Self-Heal Before Notify").
+ *
+ * Every emitter is a SIGNAL consumer feeding the SpendAlertDispatcher: it
+ * blocks nothing, gates nothing, and throw-swallows so a notifier failure can
+ * never disturb the gate/router path it observes.
+ *
+ * Kinds produced here:
+ *  - cap-approach — 50%/80% on BOTH daily AND lifetime (G4), edge-triggered per
+ *    (capKind, threshold, window); coalesced into the digest.
+ *  - cap-hit — ONE edge-triggered money-critical alert, worded honestly
+ *    ("a reservation would exceed key X's daily cap", actual vs reserved —
+ *    A-Min13). Protective; the adjust action is the operator's.
+ *  - door-dark — downstream of swap-tail self-heal; escalates only on
+ *    whole-chain exhaustion (RouterFailClosedError plans). P19 brakes:
+ *    max-attempts = chain length per episode bucket, widening backoff, a
+ *    flapping breaker (N exhaustions/window → critical wording, bypasses
+ *    coalescing via the money-critical lane), scrubbed jsonl (the dispatcher's).
+ *  - fallback-spike — routine self-healed fallback churn is NOT an operator
+ *    event (Near-Silent): every fallback is counted; a digest line fires ONLY
+ *    when the hourly rate crosses an absolute ceiling (code constant).
+ *  - holder-dead — the ONE named exception to holder-single-voice (A2-2): a
+ *    SURVIVING machine emits when the pool observes the metered-lease holder
+ *    offline past the mesh-death threshold while any door is live. Stable
+ *    pool-wide dedupe key `spend-holder-dead:<keyEpoch>`. Single-machine:
+ *    strict no-op (there is no surviving other voice).
+ *  - recon-drift — the emit surface for the Layer-1c provider-reconciliation
+ *    sweep (lands next PR); wording per Amendment 1.
+ */
+/** Cap-approach thresholds (G4) — code-defined, both cap kinds. */
+export const CAP_APPROACH_THRESHOLDS = [0.5, 0.8];
+/** Fallback-spike absolute per-hour ceiling (code constant — Near-Silent default). */
+export const FALLBACK_SPIKE_PER_HOUR_CEILING = 60;
+/** Door-dark flapping breaker: N exhaustions inside the window escalate the wording. */
+export const DOOR_DARK_FLAP_THRESHOLD = 5;
+export const DOOR_DARK_FLAP_WINDOW_MS = 60 * 60 * 1000;
+/** Door-dark per-episode widening backoff base + episode bucket size. */
+export const DOOR_DARK_BACKOFF_BASE_MS = 5 * 60 * 1000;
+export const DOOR_DARK_EPISODE_BUCKET_MS = 6 * 60 * 60 * 1000;
+function utcDay(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+export class SpendAlertEmitters {
+    dispatcher;
+    machineId;
+    now;
+    /** door-dark per-episode state: chain → { bucket, attempts, nextAllowedAtMs, exhaustionsWindow } */
+    doorDark = new Map();
+    /** fallback counter: hour-bucket → count (bounded: only the current bucket is kept). */
+    fallbackBucket = { hour: -1, count: 0 };
+    constructor(opts) {
+        this.dispatcher = opts.dispatcher;
+        this.machineId = opts.machineId;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Observer-isolated dispatch: the real dispatcher never throws/rejects, but
+     * the observer CONTRACT must hold against any implementation — a sync throw
+     * OR an async rejection here can never reach the gate/router path, and can
+     * never surface as an unhandled rejection.
+     */
+    fire(alert) {
+        try {
+            void Promise.resolve(this.dispatcher.dispatch(alert)).catch(() => { });
+        }
+        catch {
+            // @silent-fallback-ok: observer isolation — a throwing dispatcher is the
+            // notifier's failure, never the observed path's.
+        }
+    }
+    /** The MeteredSpendGate observer (onGateEvent). NEVER throws into the gate path. */
+    onGateEvent(ev) {
+        try {
+            if (ev.type === 'admit') {
+                this.checkCapApproach(ev);
+            }
+            else if (ev.reason === 'cap-exceeded') {
+                this.fire({
+                    kind: 'cap-hit',
+                    dedupeKey: `spend-cap-hit:${ev.keyRef ?? 'unknown'}:${utcDay(this.now())}`,
+                    text: `🛑 Spending cap hit: a reservation would exceed key '${ev.keyRef ?? 'unknown'}'s cap — ${ev.detail}. ` +
+                        `The call fell to a free door (paid routing on this key is refusing new spend). ` +
+                        `Raising the cap is your PIN action on the Spend tab; the freeze/disarm levers are one tap.`,
+                });
+            }
+        }
+        catch {
+            // @silent-fallback-ok: a notifier failure must never disturb the gate path.
+        }
+    }
+    checkCapApproach(ev) {
+        const checks = [
+            { capKind: 'daily', committed: ev.committedDayUsd, cap: ev.dailyCapUsd, window: utcDay(this.now()) },
+            { capKind: 'lifetime', committed: ev.committedLifetimeUsd, cap: ev.lifetimeCapUsd, window: 'lifetime' },
+        ];
+        for (const c of checks) {
+            if (!(c.cap > 0))
+                continue;
+            const frac = c.committed / c.cap;
+            for (const threshold of CAP_APPROACH_THRESHOLDS) {
+                if (frac >= threshold) {
+                    // Edge per (capKind, threshold, window) — the dispatcher's latch dedupes.
+                    this.fire({
+                        kind: 'cap-approach',
+                        dedupeKey: `spend-approach:${ev.keyRef}:${c.capKind}:${threshold}:${c.window}`,
+                        text: `📊 Key '${ev.keyRef}' is at ${Math.round(frac * 100)}% of its ${c.capKind} cap ` +
+                            `($${c.committed.toFixed(2)} of $${c.cap.toFixed(2)} committed).`,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * The router-signal consumer (fed by the onNatureRoutePlan fan-out, I-9).
+     * Counts every served fallback (Near-Silent: jsonl only via the dispatcher's
+     * audit); emits a digest line ONLY on a rate spike; escalates door-dark on
+     * whole-chain exhaustion with P19 brakes.
+     */
+    onNatureRoutePlan(plan) {
+        try {
+            if (plan.failClosed) {
+                this.onChainExhausted(plan.resolution?.resolvedChain ?? 'unknown', Array.isArray(plan.resolution?.swapTail) ? plan.resolution.swapTail.length + 1 : 3);
+                return;
+            }
+            if (plan.servedFallback)
+                this.onFallbackServed();
+        }
+        catch {
+            // @silent-fallback-ok: observer isolation (I-9) — a notifier failure never
+            // breaks the LLM call path or the sibling fan-out subscribers.
+        }
+    }
+    onChainExhausted(chain, chainLength) {
+        const nowMs = this.now();
+        const bucket = Math.floor(nowMs / DOOR_DARK_EPISODE_BUCKET_MS);
+        let st = this.doorDark.get(chain);
+        if (!st || st.bucket !== bucket) {
+            st = { bucket, attempts: 0, nextAllowedAtMs: 0, exhaustions: st?.exhaustions ?? [] };
+            this.doorDark.set(chain, st);
+        }
+        // Flapping breaker window bookkeeping (kept small: prune outside the window).
+        st.exhaustions.push(nowMs);
+        st.exhaustions = st.exhaustions.filter((t) => nowMs - t <= DOOR_DARK_FLAP_WINDOW_MS);
+        const flapping = st.exhaustions.length >= DOOR_DARK_FLAP_THRESHOLD;
+        // P19 brakes: max-attempts = chain length per episode bucket + widening backoff.
+        if (st.attempts >= chainLength)
+            return; // episode budget spent — the bucket rolling re-arms
+        if (nowMs < st.nextAllowedAtMs)
+            return; // inside the widening backoff window
+        st.attempts += 1;
+        st.nextAllowedAtMs = nowMs + DOOR_DARK_BACKOFF_BASE_MS * Math.pow(2, st.attempts - 1);
+        this.fire({
+            kind: 'door-dark',
+            dedupeKey: `spend-door-dark:${this.machineId}:${chain}:${bucket}:${st.attempts}`,
+            text: flapping
+                ? `🚨 Routing chain '${chain}' is FLAPPING dark (${st.exhaustions.length} full exhaustions in the last hour) — ` +
+                    `every door including the free tails failed repeatedly. Gated work on this chain is failing closed.`
+                : `⚠️ Routing chain '${chain}' went dark — every door including the free tails was unavailable ` +
+                    `(attempt ${st.attempts}/${chainLength} this episode). Self-heal continues; this is the whole-chain escalation.`,
+            // The flapping escalation must not sit in a digest: shorten its re-arm instead
+            // of switching lanes (kinds keep their lane — S-F8).
+            ...(flapping ? { reArmMs: 30 * 60 * 1000 } : {}),
+        });
+    }
+    onFallbackServed() {
+        const hour = Math.floor(this.now() / 3_600_000);
+        if (this.fallbackBucket.hour !== hour)
+            this.fallbackBucket = { hour, count: 0 };
+        this.fallbackBucket.count += 1;
+        if (this.fallbackBucket.count === FALLBACK_SPIKE_PER_HOUR_CEILING) {
+            // Edge exactly at the ceiling crossing — once per hour bucket by construction.
+            this.fire({
+                kind: 'fallback-spike',
+                dedupeKey: `spend-fallback-spike:${this.machineId}:${hour}`,
+                text: `📈 Routing fallback rate spiked: ${this.fallbackBucket.count} fallback-served calls this hour ` +
+                    `(ceiling ${FALLBACK_SPIKE_PER_HOUR_CEILING}). Primaries are degrading — the chains are self-healing, ` +
+                    `but persistent churn is worth a look at the Routing Map.`,
+            });
+        }
+    }
+    /**
+     * holder-dead (A2-2): call from pool observation when the metered-lease
+     * holder is offline past the mesh-death threshold while any door is live.
+     * The caller (a SURVIVING machine) supplies the keyEpoch for the stable
+     * pool-wide dedupe key. Single-machine installs never call this.
+     */
+    onMeteredLeaseHolderDead(holderNickname, keyEpoch) {
+        try {
+            this.fire({
+                kind: 'holder-dead',
+                dedupeKey: `spend-holder-dead:${keyEpoch}`,
+                text: `🚨 Paid routing is frozen — the metered-lease machine '${holderNickname}' is offline past the ` +
+                    `mesh-death threshold while paid doors are live. Free doors still serve. Reclaim/re-designate from ` +
+                    `the dashboard Spend tab (PIN) when you've confirmed the machine is really gone.`,
+            });
+        }
+        catch {
+            // @silent-fallback-ok: the surviving-voice alert is best-effort — pool
+            // observation re-fires it on its next tick if this dispatch failed.
+        }
+    }
+    /** recon-drift emit surface (Layer 1c feeds this next PR — Amendment 1 wording). */
+    onReconciliationDrift(keyRef, door, driftPct) {
+        try {
+            const bucket = driftPct >= 0 ? Math.floor(driftPct / 10) : Math.ceil(driftPct / 10);
+            this.fire({
+                kind: 'recon-drift',
+                dedupeKey: `spend-recon-drift:${keyRef}:${door}:${bucket}`,
+                text: `🧾 ${door} reports ~${Math.abs(Math.round(driftPct))}% ${driftPct > 0 ? 'more' : 'less'} than we booked ` +
+                    `for key '${keyRef}' — your reviewed price may be stale; consider promoting the observed price (PIN).`,
+            });
+        }
+        catch {
+            // @silent-fallback-ok: reporting-side observability; the sweep re-fires next pass.
+        }
+    }
+}
+//# sourceMappingURL=SpendAlertEmitters.js.map

package/dist/core/SpendAlertEmitters.js.map

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

package/dist/core/SpendAlertResolver.d.ts

@@ -0,0 +1,89 @@
+/**
+ * SpendAlertResolver — the MINIMAL topic-resolver foundation + the two
+ * Increment-B alert kinds (stale-price / observed-drift) of the Routing Control
+ * Room (docs/specs/routing-control-room-spend-alerts.md, §Surface 2 Alerts,
+ * C5-5 sequencing: stale pricing changes money ADMISSION behavior, so its alarm
+ * ships WITH the money increment; the full channel abstraction + the remaining
+ * emitter set are Increment C).
+ *
+ * Resolution LADDER (first hit wins; only the last rung creates):
+ *  1. Operator-configured `routingSpend.alerts.telegramTopicId` — that id IS the
+ *     topic; nothing is ever created.
+ *  2. The machine-local persisted record (the `persistLifelineTopicId` pattern).
+ *     (The pool-published half of rung 2 rides the machine-registry heartbeat
+ *     surface and lands with Increment C — tracked: CMT-1929.)
+ *  3. Create ONCE — ONLY when this machine is the CONFIRMED serving-lease holder
+ *     (fenced; lease re-confirmed within the same bounded staleness window the
+ *     money gate uses) — as a bounded create-once SYSTEM topic. In-process
+ *     single-flight guards a burst of first-alerts.
+ *  Anyone who cannot resolve/create falls back to the LIFELINE — fail toward
+ *  the lifeline, never toward a possible duplicate.
+ *
+ * Emission discipline: edge-triggered per dedupe key (an alert latches only on
+ * a CONFIRMED send, so a transient failure stays eligible for re-send);
+ * metadata-only text (door / age-days / threshold — NEVER a provider body or a
+ * key-shaped substring).
+ */
+export interface SpendAlert {
+    /** Informational lane in B (stale-price / observed-drift). Money-critical lanes land in C. */
+    kind: 'stale-price' | 'observed-drift';
+    dedupeKey: string;
+    text: string;
+}
+export interface SpendAlertResolverDeps {
+    /** Rung 1: the operator-configured topic id (config-read, live). */
+    configuredTopicId: () => number | undefined;
+    /** Rung 2 (machine-local half): read/persist the auto-created id. */
+    readPersistedTopicId: () => number | undefined;
+    persistTopicId: (topicId: number) => void;
+    /**
+     * Rung 2 (POOL-PUBLISHED half, Increment C — FD-6): read the id any pool
+     * machine published on the replicated machine registry, and publish this
+     * machine's created id there — so a FUTURE serving-lease holder INHERITS the
+     * id instead of re-creating (Telegram mints a fresh id per createForumTopic,
+     * so last-writer-wins can never merge two creations). Optional: absent on
+     * single-machine installs (the machine-local record suffices there).
+     */
+    readPoolPublishedTopicId?: () => number | undefined;
+    publishTopicId?: (topicId: number) => void;
+    /** Rung 3 gate: ms since the serving lease was POSITIVELY re-confirmed (null = not holder / unconfirmed). */
+    servingLeaseConfirmedAgoMs: () => number | null;
+    /** Create the bounded create-once system topic; returns its id. */
+    createTopic: () => Promise<number>;
+    /** Deliver one message into a topic; resolves true on CONFIRMED send. */
+    sendToTopic: (topicId: number, text: string) => Promise<boolean>;
+    /** The lifeline fallback topic id (always-existing system topic), if resolvable. */
+    lifelineTopicId: () => number | undefined;
+    /** Scrubbed observability sink (jsonl line per emission/decision). */
+    audit?: (entry: Record<string, unknown>) => void;
+    now?: () => number;
+}
+/** The same bounded staleness window the money gate uses (N-2). */
+export declare const SERVING_LEASE_WINDOW_MS = 60000;
+export declare class SpendAlertResolver {
+    private readonly d;
+    private readonly now;
+    /** Edge-trigger latch: dedupeKey → last CONFIRMED emission ms. */
+    private latched;
+    /** In-process single-flight for topic creation. */
+    private creating;
+    constructor(deps: SpendAlertResolverDeps);
+    /** Rung-1 accessor for the channel's repoint detection (G5) — never resolves/creates. */
+    configuredTopicIdForRepointCheck(): number | undefined;
+    /** Resolve the dedicated topic id via the ladder — or undefined (caller falls back to lifeline). */
+    resolveTopicId(): Promise<number | undefined>;
+    /**
+     * Emit one alert: dedicated topic first, lifeline on ANY failure (unset,
+     * create-refused, send-failed). Edge-triggered — a dedupe key that already
+     * emitted (confirmed) within `reArmMs` is suppressed; the latch only sets on
+     * CONFIRMED delivery, so a transient failure stays eligible.
+     */
+    emit(alert: SpendAlert, reArmMs?: number): Promise<'sent' | 'sent-lifeline' | 'suppressed' | 'failed'>;
+}
+/**
+ * Build the two Increment-B alert kinds from the price authority's staleness /
+ * drift view for the metered doors. Metadata-only wording (S-F7).
+ */
+export declare function buildStalePriceAlert(door: string, ageDays: number, slaDays: number): SpendAlert;
+export declare function buildObservedDriftAlert(door: string, modelId: string, driftPct: number): SpendAlert;
+//# sourceMappingURL=SpendAlertResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SpendAlertResolver.d.ts","sourceRoot":"","sources":["../../src/core/SpendAlertResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,UAAU;IACzB,8FAA8F;IAC9F,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC5C,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC/C,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C;;;;;;;OAOG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACpD,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,6GAA6G;IAC7G,0BAA0B,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAChD,mEAAmE;IACnE,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,yEAAyE;IACzE,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,oFAAoF;IACpF,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC1C,sEAAsE;IACtE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAyB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,kEAAkE;IAClE,OAAO,CAAC,OAAO,CAA6B;IAC5C,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAA4C;gBAEhD,IAAI,EAAE,sBAAsB;IAKxC,yFAAyF;IACzF,gCAAgC,IAAI,MAAM,GAAG,SAAS;IAKtD,oGAAoG;IAC9F,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAyDnD;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,SAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,GAAG,YAAY,GAAG,QAAQ,CAAC;CAmC1H;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAS/F;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CASnG"}