instar 0.28.107 → 0.28.109

package/dist/monitoring/BurnAlertButtons.d.ts

@@ -0,0 +1,107 @@
+/**
+ * BurnAlertButtons — principal-bound Telegram inline-button surface for the
+ * burn-detection auto-heal system.
+ *
+ * Phase 5 of docs/specs/token-burn-detection-and-self-heal.md.
+ *
+ * The convergence audit identified that the original spec's "tap to throttle"
+ * button could be tapped by anyone in any Telegram chat the bot was in. The
+ * Phase 5 callback handler closes that vector with three layers:
+ *
+ *   1. **Principal verification**: every callback's `from.id` must be in the
+ *      agent's `authorizedUserIds` list (the same list `MessagingToneGate`
+ *      and other principal-aware code paths consult).
+ *   2. **HMAC signature**: every `callback_data` is signed by the agent's
+ *      capability key over the canonical action payload. Forged callback
+ *      data fails verification.
+ *   3. **Signal-id freshness**: each button carries the signal-id that
+ *      produced it; once consumed, the same signal-id cannot be tapped
+ *      twice (the spec's "replay reject" requirement).
+ *
+ * This module is pure logic over a tiny callback_data string. The actual
+ * Telegram-wire integration (sending the inline_keyboard with reply_markup,
+ * receiving the callback from TelegramAdapter, dispatching to handle())
+ * is wired in a follow-up alongside the existing CallbackRegistry pattern
+ * in TelegramAdapter.ts.
+ */
+import type { LlmRateGate } from './LlmRateGate.js';
+/** The four actions a user can take from a burn alert. */
+export type BurnAlertAction = 'release' | 'snooze-24h' | 'extend' | 'investigate';
+export interface BurnAlertCallback {
+    /** What the user tapped. */
+    action: BurnAlertAction;
+    /** Which attribution key this button refers to. */
+    attributionKey: string;
+    /** Signal-id from the originating burn signal (replay prevention). */
+    signalId: string;
+}
+export interface BurnAlertCallbackResult {
+    ok: boolean;
+    action: BurnAlertAction;
+    attributionKey: string;
+    reason: 'accepted' | 'principal-not-authorized' | 'invalid-signature' | 'signal-id-replayed' | 'malformed-payload' | 'snooze-recorded' | 'extend-failed-not-throttled';
+    /** Human-readable status to feed back to the Telegram user. */
+    userMessage: string;
+}
+export interface BurnAlertButtonsDeps {
+    /** HMAC key to sign + verify callback_data. */
+    capabilityKey: Buffer;
+    /** Authorized user IDs — same list MessagingToneGate consults. */
+    authorizedUserIds: number[];
+    /** The LlmRateGate; release/extend mutate throttles. */
+    gate: LlmRateGate;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Snooze TTL (default 24h). */
+    snoozeDurationMs?: number;
+}
+export declare class BurnAlertButtons {
+    private readonly capabilityKey;
+    private readonly authorizedUserIds;
+    private readonly gate;
+    private readonly now;
+    private readonly snoozeDurationMs;
+    /** Consumed signal-ids per button — guards against replay. */
+    private readonly consumed;
+    /** Snoozed attribution keys → snooze-expires-at (ms). Inspected by the runbook before throttling. */
+    private readonly snoozed;
+    constructor(deps: BurnAlertButtonsDeps);
+    /**
+     * Generate the signed payload for one button. The opaque callback_data
+     * string is what the Telegram inline button carries. The button shape
+     * itself (text label, button row layout) is the caller's job — they get
+     * the payload, they pass it to Telegram's reply_markup.
+     */
+    encodeCallbackData(payload: BurnAlertCallback): string;
+    /**
+     * Build a four-button keyboard row for a burn alert. Returns the inline
+     * objects the caller can pass to Telegram's reply_markup.inline_keyboard.
+     */
+    buildKeyboard(attributionKey: string, signalId: string): Array<{
+        text: string;
+        callback_data: string;
+    }>;
+    /**
+     * Handle a Telegram callback. Returns a structured result the caller can
+     * use to log the audit trail and answer the Telegram callback query.
+     */
+    handle(input: {
+        callbackData: string;
+        fromUserId: number;
+    }): BurnAlertCallbackResult;
+    /**
+     * Read-side: is this attribution key currently snoozed? Called by the
+     * runbook before installing a throttle. Auto-expires entries.
+     */
+    isSnoozed(attributionKey: string): boolean;
+    /** For tests + dashboard. */
+    listSnoozes(): Array<{
+        attributionKey: string;
+        expiresAt: string;
+    }>;
+    private canonicalize;
+    private parseCallbackData;
+    /** GC consumed signal-id-action pairs older than 24h. */
+    private gcConsumed;
+}
+//# sourceMappingURL=BurnAlertButtons.d.ts.map

package/dist/monitoring/BurnAlertButtons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BurnAlertButtons.d.ts","sourceRoot":"","sources":["../../src/monitoring/BurnAlertButtons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,aAAa,CAAC;AAElB,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EACF,UAAU,GACV,0BAA0B,GAC1B,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,6BAA6B,CAAC;IAClC,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,wDAAwD;IACxD,IAAI,EAAE,WAAW,CAAC;IAClB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;gBAEzC,IAAI,EAAE,oBAAoB;IAQtC;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAYtD;;;OAGG;IACH,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IASvG;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,uBAAuB;IA4IpF;;;OAGG;IACH,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAU1C,6BAA6B;IAC7B,WAAW,IAAI,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAYnE,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAczB,yDAAyD;IACzD,OAAO,CAAC,UAAU;CAMnB"}

package/dist/monitoring/BurnAlertButtons.js

@@ -0,0 +1,270 @@
+/**
+ * BurnAlertButtons — principal-bound Telegram inline-button surface for the
+ * burn-detection auto-heal system.
+ *
+ * Phase 5 of docs/specs/token-burn-detection-and-self-heal.md.
+ *
+ * The convergence audit identified that the original spec's "tap to throttle"
+ * button could be tapped by anyone in any Telegram chat the bot was in. The
+ * Phase 5 callback handler closes that vector with three layers:
+ *
+ *   1. **Principal verification**: every callback's `from.id` must be in the
+ *      agent's `authorizedUserIds` list (the same list `MessagingToneGate`
+ *      and other principal-aware code paths consult).
+ *   2. **HMAC signature**: every `callback_data` is signed by the agent's
+ *      capability key over the canonical action payload. Forged callback
+ *      data fails verification.
+ *   3. **Signal-id freshness**: each button carries the signal-id that
+ *      produced it; once consumed, the same signal-id cannot be tapped
+ *      twice (the spec's "replay reject" requirement).
+ *
+ * This module is pure logic over a tiny callback_data string. The actual
+ * Telegram-wire integration (sending the inline_keyboard with reply_markup,
+ * receiving the callback from TelegramAdapter, dispatching to handle())
+ * is wired in a follow-up alongside the existing CallbackRegistry pattern
+ * in TelegramAdapter.ts.
+ */
+import crypto from 'node:crypto';
+const DEFAULT_SNOOZE_MS = 24 * 60 * 60 * 1000;
+export class BurnAlertButtons {
+    capabilityKey;
+    authorizedUserIds;
+    gate;
+    now;
+    snoozeDurationMs;
+    /** Consumed signal-ids per button — guards against replay. */
+    consumed = new Map();
+    /** Snoozed attribution keys → snooze-expires-at (ms). Inspected by the runbook before throttling. */
+    snoozed = new Map();
+    constructor(deps) {
+        this.capabilityKey = deps.capabilityKey;
+        this.authorizedUserIds = new Set(deps.authorizedUserIds);
+        this.gate = deps.gate;
+        this.now = deps.now ?? (() => Date.now());
+        this.snoozeDurationMs = deps.snoozeDurationMs ?? DEFAULT_SNOOZE_MS;
+    }
+    /**
+     * Generate the signed payload for one button. The opaque callback_data
+     * string is what the Telegram inline button carries. The button shape
+     * itself (text label, button row layout) is the caller's job — they get
+     * the payload, they pass it to Telegram's reply_markup.
+     */
+    encodeCallbackData(payload) {
+        const canonical = this.canonicalize(payload);
+        const sig = crypto
+            .createHmac('sha256', this.capabilityKey)
+            .update(canonical)
+            .digest('hex')
+            .slice(0, 16);
+        // Compact encoding for Telegram's 64-byte callback_data limit. Format:
+        // <action>|<attributionKey>|<signalId>|<sig>
+        return `${payload.action}|${payload.attributionKey}|${payload.signalId}|${sig}`;
+    }
+    /**
+     * Build a four-button keyboard row for a burn alert. Returns the inline
+     * objects the caller can pass to Telegram's reply_markup.inline_keyboard.
+     */
+    buildKeyboard(attributionKey, signalId) {
+        return [
+            { text: 'Release', callback_data: this.encodeCallbackData({ action: 'release', attributionKey, signalId }) },
+            { text: 'Snooze 24h', callback_data: this.encodeCallbackData({ action: 'snooze-24h', attributionKey, signalId }) },
+            { text: 'Extend +1h', callback_data: this.encodeCallbackData({ action: 'extend', attributionKey, signalId }) },
+            { text: 'Investigate', callback_data: this.encodeCallbackData({ action: 'investigate', attributionKey, signalId }) },
+        ];
+    }
+    /**
+     * Handle a Telegram callback. Returns a structured result the caller can
+     * use to log the audit trail and answer the Telegram callback query.
+     */
+    handle(input) {
+        const parsed = this.parseCallbackData(input.callbackData);
+        if (!parsed) {
+            return {
+                ok: false,
+                action: 'investigate',
+                attributionKey: '',
+                reason: 'malformed-payload',
+                userMessage: 'I could not parse that button.',
+            };
+        }
+        // 1. Principal check.
+        if (!this.authorizedUserIds.has(input.fromUserId)) {
+            return {
+                ok: false,
+                action: parsed.action,
+                attributionKey: parsed.attributionKey,
+                reason: 'principal-not-authorized',
+                userMessage: 'You are not authorized to act on this agent.',
+            };
+        }
+        // 2. Signature check.
+        const expectedSig = crypto
+            .createHmac('sha256', this.capabilityKey)
+            .update(this.canonicalize(parsed))
+            .digest('hex')
+            .slice(0, 16);
+        if (parsed.sig !== expectedSig) {
+            return {
+                ok: false,
+                action: parsed.action,
+                attributionKey: parsed.attributionKey,
+                reason: 'invalid-signature',
+                userMessage: 'That button signature did not match. Refusing.',
+            };
+        }
+        // 3. Freshness check. The same signal-id-action pair can fire at most once.
+        const consumptionKey = `${parsed.action}|${parsed.signalId}`;
+        if (this.consumed.has(consumptionKey)) {
+            return {
+                ok: false,
+                action: parsed.action,
+                attributionKey: parsed.attributionKey,
+                reason: 'signal-id-replayed',
+                userMessage: 'That button has already been used.',
+            };
+        }
+        this.consumed.set(consumptionKey, this.now());
+        this.gcConsumed();
+        // 4. Apply the action.
+        switch (parsed.action) {
+            case 'release': {
+                const released = this.gate.revokeThrottle(parsed.attributionKey);
+                return {
+                    ok: true,
+                    action: 'release',
+                    attributionKey: parsed.attributionKey,
+                    reason: 'accepted',
+                    userMessage: released
+                        ? `Released the throttle on ${parsed.attributionKey}.`
+                        : `No throttle was active for ${parsed.attributionKey} — nothing to release.`,
+                };
+            }
+            case 'snooze-24h': {
+                this.snoozed.set(parsed.attributionKey, this.now() + this.snoozeDurationMs);
+                this.gate.revokeThrottle(parsed.attributionKey);
+                return {
+                    ok: true,
+                    action: 'snooze-24h',
+                    attributionKey: parsed.attributionKey,
+                    reason: 'snooze-recorded',
+                    userMessage: `Snoozed ${parsed.attributionKey} for 24 hours. The runbook will not throttle this key during that window.`,
+                };
+            }
+            case 'extend': {
+                // Re-install throttle for another hour using a fresh signalId derived
+                // from "extend|<existing signalId>". Returns a structured error if no
+                // throttle is currently active.
+                const active = this.gate.listActiveThrottles().find((t) => t.attributionKey === parsed.attributionKey);
+                if (!active) {
+                    return {
+                        ok: false,
+                        action: 'extend',
+                        attributionKey: parsed.attributionKey,
+                        reason: 'extend-failed-not-throttled',
+                        userMessage: `Cannot extend — no active throttle on ${parsed.attributionKey}.`,
+                    };
+                }
+                const extendSignalId = `extend:${parsed.signalId}:${this.now()}`;
+                const extendDurationMs = 60 * 60 * 1000;
+                const tok = this.gate.computeCapabilityToken({
+                    attributionKey: parsed.attributionKey,
+                    durationMs: extendDurationMs,
+                    issuer: active.issuer,
+                    signalId: extendSignalId,
+                }) ?? undefined;
+                try {
+                    this.gate.installThrottle({
+                        attributionKey: parsed.attributionKey,
+                        durationMs: extendDurationMs,
+                        reason: `User-initiated extension via Telegram button.`,
+                        issuer: active.issuer,
+                        signalId: extendSignalId,
+                        capabilityToken: tok,
+                    });
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        action: 'extend',
+                        attributionKey: parsed.attributionKey,
+                        reason: 'extend-failed-not-throttled',
+                        userMessage: `Could not extend: ${err.message}`,
+                    };
+                }
+                return {
+                    ok: true,
+                    action: 'extend',
+                    attributionKey: parsed.attributionKey,
+                    reason: 'accepted',
+                    userMessage: `Extended the throttle on ${parsed.attributionKey} for another hour.`,
+                };
+            }
+            case 'investigate': {
+                // No state change; this is purely for audit. The user is saying "I'm
+                // looking at this one". The agent records it but otherwise stands by.
+                return {
+                    ok: true,
+                    action: 'investigate',
+                    attributionKey: parsed.attributionKey,
+                    reason: 'accepted',
+                    userMessage: `Logged. ${parsed.attributionKey} marked for follow-up.`,
+                };
+            }
+        }
+    }
+    /**
+     * Read-side: is this attribution key currently snoozed? Called by the
+     * runbook before installing a throttle. Auto-expires entries.
+     */
+    isSnoozed(attributionKey) {
+        const expires = this.snoozed.get(attributionKey);
+        if (!expires)
+            return false;
+        if (this.now() >= expires) {
+            this.snoozed.delete(attributionKey);
+            return false;
+        }
+        return true;
+    }
+    /** For tests + dashboard. */
+    listSnoozes() {
+        const out = [];
+        for (const [key, expires] of this.snoozed.entries()) {
+            if (this.now() < expires) {
+                out.push({ attributionKey: key, expiresAt: new Date(expires).toISOString() });
+            }
+            else {
+                this.snoozed.delete(key);
+            }
+        }
+        return out;
+    }
+    canonicalize(payload) {
+        return `${payload.action}|${payload.attributionKey}|${payload.signalId}`;
+    }
+    parseCallbackData(s) {
+        const parts = s.split('|');
+        if (parts.length !== 4)
+            return null;
+        const action = parts[0];
+        if (!['release', 'snooze-24h', 'extend', 'investigate'].includes(action))
+            return null;
+        if (!parts[1] || !parts[2] || !parts[3])
+            return null;
+        return {
+            action,
+            attributionKey: parts[1],
+            signalId: parts[2],
+            sig: parts[3],
+        };
+    }
+    /** GC consumed signal-id-action pairs older than 24h. */
+    gcConsumed() {
+        const cutoff = this.now() - 24 * 60 * 60 * 1000;
+        for (const [key, ts] of this.consumed.entries()) {
+            if (ts < cutoff)
+                this.consumed.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=BurnAlertButtons.js.map

package/dist/monitoring/BurnAlertButtons.js.map

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

package/dist/monitoring/BurnDetectionSubscriber.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BurnDetectionSubscriber — wires the BurnThrottleRunbook into the
+ * DegradationReporter as a self-healer for feature='token-burn-detection'.
+ *
+ * Phase 5 of docs/specs/token-burn-detection-and-self-heal.md. The
+ * DegradationReporter already supports a `registerHealer(feature, healer)`
+ * surface (per Remediator V2 spec). The runbook's `handle()` is sync and
+ * returns RunbookOutcome; the healer signature is async + returns boolean.
+ * This module is the small adapter between them.
+ *
+ * Returns true to DegradationReporter when the runbook installed a
+ * throttle (the healer "succeeded" by acting on the signal); returns false
+ * when only an alert was sent (the runbook chose alert-only) so the
+ * reporter's own audit log records the partial-action correctly.
+ */
+import type { DegradationEvent, DegradationReporter } from './DegradationReporter.js';
+import type { BurnThrottleRunbook, RunbookOutcome } from './BurnThrottleRunbook.js';
+export declare const BURN_DETECTION_FEATURE = "token-burn-detection";
+export declare function registerBurnDetectionSubscriber(reporter: Pick<DegradationReporter, 'registerHealer'>, runbook: BurnThrottleRunbook, 
+/**
+ * Optional sink for outcomes — the verification step (Phase 6) will
+ * subscribe here to re-sample telemetry post-throttle and emit a follow-up.
+ */
+onOutcome?: (outcome: RunbookOutcome, event: DegradationEvent) => void): void;
+//# sourceMappingURL=BurnDetectionSubscriber.d.ts.map

package/dist/monitoring/BurnDetectionSubscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BurnDetectionSubscriber.d.ts","sourceRoot":"","sources":["../../src/monitoring/BurnDetectionSubscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEpF,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,EACrD,OAAO,EAAE,mBAAmB;AAC5B;;;GAGG;AACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,GACrE,IAAI,CAUN"}

package/dist/monitoring/BurnDetectionSubscriber.js

@@ -0,0 +1,34 @@
+/**
+ * BurnDetectionSubscriber — wires the BurnThrottleRunbook into the
+ * DegradationReporter as a self-healer for feature='token-burn-detection'.
+ *
+ * Phase 5 of docs/specs/token-burn-detection-and-self-heal.md. The
+ * DegradationReporter already supports a `registerHealer(feature, healer)`
+ * surface (per Remediator V2 spec). The runbook's `handle()` is sync and
+ * returns RunbookOutcome; the healer signature is async + returns boolean.
+ * This module is the small adapter between them.
+ *
+ * Returns true to DegradationReporter when the runbook installed a
+ * throttle (the healer "succeeded" by acting on the signal); returns false
+ * when only an alert was sent (the runbook chose alert-only) so the
+ * reporter's own audit log records the partial-action correctly.
+ */
+export const BURN_DETECTION_FEATURE = 'token-burn-detection';
+export function registerBurnDetectionSubscriber(reporter, runbook, 
+/**
+ * Optional sink for outcomes — the verification step (Phase 6) will
+ * subscribe here to re-sample telemetry post-throttle and emit a follow-up.
+ */
+onOutcome) {
+    reporter.registerHealer(BURN_DETECTION_FEATURE, async (event) => {
+        const outcome = runbook.handle(event);
+        try {
+            onOutcome?.(outcome, event);
+        }
+        catch (err) {
+            console.warn(`[burn-detection-subscriber] onOutcome threw: ${err.message}`);
+        }
+        return outcome.kind === 'throttle-installed';
+    });
+}
+//# sourceMappingURL=BurnDetectionSubscriber.js.map

package/dist/monitoring/BurnDetectionSubscriber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BurnDetectionSubscriber.js","sourceRoot":"","sources":["../../src/monitoring/BurnDetectionSubscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,UAAU,+BAA+B,CAC7C,QAAqD,EACrD,OAA4B;AAC5B;;;GAGG;AACH,SAAsE;IAEtE,QAAQ,CAAC,cAAc,CAAC,sBAAsB,EAAE,KAAK,EAAE,KAAuB,EAAE,EAAE;QAChF,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,SAAS,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,gDAAiD,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,KAAK,oBAAoB,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/monitoring/BurnDetector.d.ts

@@ -0,0 +1,84 @@
+/**
+ * BurnDetector — emits a structured signal when a single attribution_key
+ * crosses configured spend thresholds.
+ *
+ * Phase 3 of docs/specs/token-burn-detection-and-self-heal.md.
+ *
+ * Signal-only (per umbrella spec §"Signal-vs-Authority Decomposition"): the
+ * detector emits to the existing DegradationReporter. The Phase 4 runbook
+ * (Tier-2 Remediator surface) is the only authority that decides whether
+ * to alert / throttle / both. The BurnDetector cannot decide anything.
+ *
+ * Triggers (OR'd):
+ *   1. Absolute share — a single attribution_key consumed > absoluteShareThreshold
+ *      of total 24h spend.
+ *   2. Baseline divergence — the key's last-1h rate is > rollingBaselineMultiplier ×
+ *      its trailing-7-day median rate, AND the 1h rate exceeds rollingBaselineFloor
+ *      tokens/h.
+ *
+ * Cold-start (per umbrella spec §"Threshold logic"): the baseline-divergence
+ * trigger only fires after a key has been observed for 7 days. Until then,
+ * absolute-share is the only signal — that's the trigger that would have
+ * caught the 2026-05-15 incident.
+ *
+ * Polling cadence: 60s, decoupled from the ledger writer. The detector does
+ * its own clock (injected `now`) so tests don't need to fake timers globally.
+ */
+import type { TokenLedger } from './TokenLedger.js';
+import type { DegradationReporter } from './DegradationReporter.js';
+export interface BurnDetectionConfig {
+    enabled: boolean;
+    /** Default 0.25 (25%). */
+    absoluteShareThreshold: number;
+    /** Default 2 (2x). */
+    rollingBaselineMultiplier: number;
+    /** Default 10_000_000 tokens/hour. */
+    rollingBaselineFloor: number;
+    /** Per-key alert cooldown (default 3_600_000ms = 1h). */
+    perKeyAlertCooldownMs: number;
+    /** Poll interval (default 60_000ms = 60s). */
+    pollIntervalMs: number;
+    /** Cold-start duration (default 7d). Baseline-divergence trigger disabled until elapsed. */
+    coldStartMs: number;
+}
+export declare const DEFAULT_BURN_DETECTION_CONFIG: BurnDetectionConfig;
+export interface BurnSignal {
+    attributionKey: string;
+    trigger: 'absolute-share' | 'baseline-divergence';
+    emittedAt: string;
+    observed: {
+        tokens24h: number;
+        share24h: number;
+        tokensLast1h: number;
+        projectedDaily: number;
+    };
+    /** Trailing-7d median tokens/h. Only populated for `baseline-divergence`. */
+    baselineMedian7d?: number;
+}
+export interface BurnDetectorDeps {
+    ledger: Pick<TokenLedger, 'byAttributionKey' | 'summary'>;
+    reporter: Pick<DegradationReporter, 'report'>;
+    config?: Partial<BurnDetectionConfig>;
+    /** Injectable clock for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+export declare class BurnDetector {
+    private readonly ledger;
+    private readonly reporter;
+    private readonly config;
+    private readonly now;
+    /** First time a given attribution_key was seen. Used for cold-start cutoff. */
+    private readonly firstSeen;
+    /** Last alert emit time per key — gates per-key alert cooldown. */
+    private readonly lastAlertAt;
+    private timer;
+    constructor(deps: BurnDetectorDeps);
+    start(): void;
+    stop(): void;
+    /**
+     * One detector cycle. Returns the signals emitted on this tick — useful
+     * for tests, and the production loop ignores the return.
+     */
+    tick(): BurnSignal[];
+}
+//# sourceMappingURL=BurnDetector.d.ts.map

package/dist/monitoring/BurnDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BurnDetector.d.ts","sourceRoot":"","sources":["../../src/monitoring/BurnDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB;IACtB,yBAAyB,EAAE,MAAM,CAAC;IAClC,sCAAsC;IACtC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBAQ3C,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,gBAAgB,GAAG,qBAAqB,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC1D,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,KAAK,CAA+C;gBAEhD,IAAI,EAAE,gBAAgB;IAOlC,KAAK,IAAI,IAAI;IAgBb,IAAI,IAAI,IAAI;IAOZ;;;OAGG;IACH,IAAI,IAAI,UAAU,EAAE;CAkGrB"}