instar 1.3.71 → 1.3.73

package/dist/core/UsherActedCorrelator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * UsherActedCorrelator — the precision-numerator wiring for the Usher (rung 4 of
+ * continuous-working-awareness).
+ *
+ * The Usher FIRES re-surface signals (UsherSignalStore.recordSignal). Until this
+ * module, nothing ever called markActed — so `precision = acted/fired` was pinned
+ * at 0 and the rung-5 (mid-task injection) gate could never be satisfied by data.
+ * This closes that loop via TWO correlation paths, both reducing to "does some
+ * probe text COVER a fired signal's contextText?":
+ *
+ *   (a) auto-use   — the agent's next reply on the topic uses the re-surfaced
+ *                    context. creditUsherOnOutbound(). The nudge was useful: the
+ *                    agent acted on it.
+ *   (b) miss-map   — the user later had to CORRECT the agent (a HumanAsDetector
+ *                    signal) on that same context. creditUsherOnMiss(). The nudge
+ *                    was a genuine catch the agent ignored — still a true positive
+ *                    for the Usher's precision.
+ *
+ * Matching is deliberately PRECISION-OVER-RECALL: precision gates whether the
+ * Usher earns the right to interrupt (rung 5), so a falsely-HIGH precision is the
+ * dangerous direction. We require a meaningful salient-term overlap (≥ MIN_SHARED
+ * shared content words AND ≥ MIN_COVERAGE of the context's terms) and only credit
+ * recently-fired signals. Under-crediting a fast reply is acceptable; inflating
+ * the gate is not.
+ *
+ * All exported integration fns are best-effort and NEVER throw into the
+ * message/delivery path — mirroring the Usher's own degrade-safety invariants.
+ */
+import type { UsherSignal, UsherSignalStore } from './UsherSignalStore.js';
+/** Minimal inbound-entry shape the miss path reads (matches InboundMessageEntry). */
+export interface MissEntry {
+    topicId?: number | null;
+    text?: string;
+}
+export declare const MIN_SHARED = 2;
+export declare const MIN_COVERAGE = 0.5;
+/** Window in which the agent's reply still counts as "using" a just-fired nudge. */
+export declare const USE_WINDOW_MS: number;
+/** Window in which a later user correction still credits a prior nudge. */
+export declare const MISS_WINDOW_MS: number;
+/**
+ * Salient content tokens of a text: lowercased, alphanumeric-split, ≥3 chars,
+ * stopwords removed. Pure + deterministic.
+ */
+export declare function salientTerms(text: string): Set<string>;
+/**
+ * Does `probeText` cover enough of `contextText`'s salient terms to count as a
+ * genuine reference to it? Requires ≥ minShared shared terms AND ≥ minCoverage
+ * fraction of the context's terms (so single-coincidental-word matches fail, and
+ * a long context needs proportionally more overlap).
+ */
+export declare function contextCoveredBy(contextText: string, probeText: string, opts?: {
+    minShared?: number;
+    minCoverage?: number;
+}): boolean;
+/**
+ * Pure: among NOT-yet-acted signals, which ones does `probeText` cover? Returns
+ * their ids. `maxAgeMs`+`nowMs` optionally drop signals older than the window.
+ */
+export declare function findCoveredSignalIds(signals: UsherSignal[], probeText: string, opts?: {
+    minShared?: number;
+    minCoverage?: number;
+    maxAgeMs?: number;
+    nowMs?: number;
+}): string[];
+/**
+ * Core integration: correlate `probeText` against a topic's fired signals and
+ * mark the matches acted (stamped with `via`). Best-effort, never throws.
+ * Returns the ids actually marked.
+ */
+export declare function markActedByCoverage(store: UsherSignalStore, topicId: number, probeText: string, via: 'use' | 'miss', opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+    minShared?: number;
+    minCoverage?: number;
+    onMarked?: (id: string) => void;
+}): string[];
+/**
+ * Path (a): the agent's reply just went out on `topicId`. Credit any recent
+ * faded-context nudge the reply actually used. Wire on the outbound-reply path.
+ */
+export declare function creditUsherOnOutbound(store: UsherSignalStore | null | undefined, topicId: number, replyText: string, opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+}): string[];
+/**
+ * Path (b): the user just had to correct the agent (`missSignal` non-null). If a
+ * recent nudge on this topic covers what they're correcting, that nudge was a
+ * real catch the agent ignored → credit it. Wire on the inbound human-detector
+ * seam. No-op when there was no miss, no topic, or no text.
+ */
+export declare function creditUsherOnMiss(store: UsherSignalStore | null | undefined, missSignal: unknown, entry: MissEntry, opts?: {
+    now?: () => number;
+    maxAgeMs?: number;
+}): string[];
+//# sourceMappingURL=UsherActedCorrelator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UsherActedCorrelator.d.ts","sourceRoot":"","sources":["../../src/core/UsherActedCorrelator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,qFAAqF;AACrF,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAqB,CAAC;AAChD,2EAA2E;AAC3E,eAAO,MAAM,cAAc,QAAsB,CAAC;AAgBlD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAStD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAST;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF,MAAM,EAAE,CAaV;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,KAAK,GAAG,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC1H,MAAM,EAAE,CAyBV;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,EAAE,CAMV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC1C,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,EAAE,CASV"}

package/dist/core/UsherActedCorrelator.js

@@ -0,0 +1,175 @@
+/**
+ * UsherActedCorrelator — the precision-numerator wiring for the Usher (rung 4 of
+ * continuous-working-awareness).
+ *
+ * The Usher FIRES re-surface signals (UsherSignalStore.recordSignal). Until this
+ * module, nothing ever called markActed — so `precision = acted/fired` was pinned
+ * at 0 and the rung-5 (mid-task injection) gate could never be satisfied by data.
+ * This closes that loop via TWO correlation paths, both reducing to "does some
+ * probe text COVER a fired signal's contextText?":
+ *
+ *   (a) auto-use   — the agent's next reply on the topic uses the re-surfaced
+ *                    context. creditUsherOnOutbound(). The nudge was useful: the
+ *                    agent acted on it.
+ *   (b) miss-map   — the user later had to CORRECT the agent (a HumanAsDetector
+ *                    signal) on that same context. creditUsherOnMiss(). The nudge
+ *                    was a genuine catch the agent ignored — still a true positive
+ *                    for the Usher's precision.
+ *
+ * Matching is deliberately PRECISION-OVER-RECALL: precision gates whether the
+ * Usher earns the right to interrupt (rung 5), so a falsely-HIGH precision is the
+ * dangerous direction. We require a meaningful salient-term overlap (≥ MIN_SHARED
+ * shared content words AND ≥ MIN_COVERAGE of the context's terms) and only credit
+ * recently-fired signals. Under-crediting a fast reply is acceptable; inflating
+ * the gate is not.
+ *
+ * All exported integration fns are best-effort and NEVER throw into the
+ * message/delivery path — mirroring the Usher's own degrade-safety invariants.
+ */
+// ── Matching knobs (precision-over-recall) ───────────────────────────────────
+export const MIN_SHARED = 2; // a single coincidental word can't credit a signal
+export const MIN_COVERAGE = 0.5; // must cover at least half the context's salient terms
+/** Window in which the agent's reply still counts as "using" a just-fired nudge. */
+export const USE_WINDOW_MS = 6 * 60 * 60 * 1000; // 6h
+/** Window in which a later user correction still credits a prior nudge. */
+export const MISS_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
+// English stopwords + a few instar-conversation fillers. Kept small and stable:
+// the goal is to drop function words so overlap reflects real subject matter.
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'your', 'with', 'that', 'this',
+    'have', 'has', 'had', 'was', 'were', 'will', 'would', 'should', 'could', 'can',
+    'its', 'it', 'is', 'be', 'been', 'being', 'from', 'into', 'over', 'under', 'about',
+    'they', 'them', 'their', 'there', 'here', 'what', 'when', 'where', 'which', 'who',
+    'how', 'why', 'all', 'any', 'some', 'one', 'two', 'now', 'then', 'than', 'just',
+    'out', 'off', 'too', 'very', 'our', 'his', 'her', 'him', 'she', 'his', 'we',
+    'get', 'got', 'let', 'see', 'use', 'used', 'make', 'made', 'want', 'need',
+    'yes', 'yeah', 'okay', 'sure', 'thing', 'things', 'stuff', 'like', 'also',
+    'going', 'gonna', 'really', 'much', 'more', 'most', 'still', 'back', 'done',
+]);
+/**
+ * Salient content tokens of a text: lowercased, alphanumeric-split, ≥3 chars,
+ * stopwords removed. Pure + deterministic.
+ */
+export function salientTerms(text) {
+    const out = new Set();
+    if (!text || typeof text !== 'string')
+        return out;
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 3)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        out.add(raw);
+    }
+    return out;
+}
+/**
+ * Does `probeText` cover enough of `contextText`'s salient terms to count as a
+ * genuine reference to it? Requires ≥ minShared shared terms AND ≥ minCoverage
+ * fraction of the context's terms (so single-coincidental-word matches fail, and
+ * a long context needs proportionally more overlap).
+ */
+export function contextCoveredBy(contextText, probeText, opts) {
+    const ctx = salientTerms(contextText);
+    if (ctx.size === 0)
+        return false;
+    const probe = salientTerms(probeText);
+    if (probe.size === 0)
+        return false;
+    let shared = 0;
+    for (const t of ctx)
+        if (probe.has(t))
+            shared++;
+    const coverage = shared / ctx.size;
+    return shared >= (opts?.minShared ?? MIN_SHARED) && coverage >= (opts?.minCoverage ?? MIN_COVERAGE);
+}
+/**
+ * Pure: among NOT-yet-acted signals, which ones does `probeText` cover? Returns
+ * their ids. `maxAgeMs`+`nowMs` optionally drop signals older than the window.
+ */
+export function findCoveredSignalIds(signals, probeText, opts) {
+    const ids = [];
+    const maxAgeMs = opts?.maxAgeMs;
+    const nowMs = opts?.nowMs ?? Date.now();
+    for (const s of signals) {
+        if (!s || s.acted)
+            continue;
+        if (maxAgeMs !== undefined) {
+            const firedMs = Date.parse(s.at);
+            if (!Number.isNaN(firedMs) && nowMs - firedMs > maxAgeMs)
+                continue;
+        }
+        if (contextCoveredBy(s.contextText, probeText, opts))
+            ids.push(s.id);
+    }
+    return ids;
+}
+/**
+ * Core integration: correlate `probeText` against a topic's fired signals and
+ * mark the matches acted (stamped with `via`). Best-effort, never throws.
+ * Returns the ids actually marked.
+ */
+export function markActedByCoverage(store, topicId, probeText, via, opts) {
+    try {
+        if (!probeText || typeof probeText !== 'string')
+            return [];
+        if (typeof topicId !== 'number' || !Number.isFinite(topicId))
+            return [];
+        const nowMs = (opts?.now ?? (() => Date.now()))();
+        const signals = store.getSignals(topicId, 50);
+        const ids = findCoveredSignalIds(signals, probeText, {
+            minShared: opts?.minShared,
+            minCoverage: opts?.minCoverage,
+            maxAgeMs: opts?.maxAgeMs,
+            nowMs,
+        });
+        if (ids.length === 0)
+            return [];
+        const at = new Date(nowMs).toISOString();
+        const marked = [];
+        for (const id of ids) {
+            if (store.markActed(topicId, id, { via, at })) {
+                marked.push(id);
+                try {
+                    opts?.onMarked?.(id);
+                }
+                catch { /* observability hook must not break */ }
+            }
+        }
+        return marked;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Path (a): the agent's reply just went out on `topicId`. Credit any recent
+ * faded-context nudge the reply actually used. Wire on the outbound-reply path.
+ */
+export function creditUsherOnOutbound(store, topicId, replyText, opts) {
+    if (!store)
+        return [];
+    return markActedByCoverage(store, topicId, replyText, 'use', {
+        now: opts?.now,
+        maxAgeMs: opts?.maxAgeMs ?? USE_WINDOW_MS,
+    });
+}
+/**
+ * Path (b): the user just had to correct the agent (`missSignal` non-null). If a
+ * recent nudge on this topic covers what they're correcting, that nudge was a
+ * real catch the agent ignored → credit it. Wire on the inbound human-detector
+ * seam. No-op when there was no miss, no topic, or no text.
+ */
+export function creditUsherOnMiss(store, missSignal, entry, opts) {
+    if (!store || !missSignal)
+        return [];
+    const topicId = entry?.topicId;
+    const text = entry?.text;
+    if (typeof topicId !== 'number' || !text)
+        return [];
+    return markActedByCoverage(store, topicId, text, 'miss', {
+        now: opts?.now,
+        maxAgeMs: opts?.maxAgeMs ?? MISS_WINDOW_MS,
+    });
+}
+//# sourceMappingURL=UsherActedCorrelator.js.map

package/dist/core/UsherActedCorrelator.js.map

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

package/dist/core/UsherSignalStore.d.ts

@@ -23,11 +23,24 @@ export interface UsherSignal {
     at: string;
     /** True once the re-surfaced context was actually used (precision numerator). */
     acted: boolean;
+    /**
+     * Which path confirmed the signal was useful (set when `acted` flips true):
+     *   'use'  — the agent's next reply actually used the re-surfaced context.
+     *   'miss' — the user later had to correct the agent on that same context, so
+     *            the nudge was a genuine catch the agent ignored.
+     * Optional for backward-compat with signals/callers that pre-date the split.
+     */
+    actedVia?: 'use' | 'miss';
+    /** ISO timestamp when the signal was marked acted. */
+    actedAt?: string;
 }
 export interface UsherMetrics {
     fired: number;
     acted: number;
     last_fired_at: string | null;
+    /** Precision numerator, split by which path confirmed usefulness (observability). */
+    acted_by_use?: number;
+    acted_by_miss?: number;
 }
 interface UsherTopicFile {
     topicId: number;
@@ -49,8 +62,19 @@ export declare class UsherSignalStore {
         turn: number;
         at?: string;
     }): string | null;
-    /** Mark a signal as acted-on (precision numerator). Best-effort. */
-    markActed(topicId: number, signalId: string): boolean;
+    /**
+     * Mark a signal as acted-on (precision numerator). Best-effort, idempotent
+     * (a second call on the same signal is a no-op returning false).
+     *
+     * `opts.via` records WHICH correlation path confirmed usefulness ('use' =
+     * the agent used it in a reply; 'miss' = the user had to correct on it) and
+     * is reflected in the split metrics. `opts.at` lets callers stamp a
+     * deterministic timestamp (tests); defaults to now.
+     */
+    markActed(topicId: number, signalId: string, opts?: {
+        via?: 'use' | 'miss';
+        at?: string;
+    }): boolean;
     getSignals(topicId: number, limit?: number): UsherSignal[];
     getMetrics(topicId: number): UsherMetrics;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"UsherSignalStore.d.ts","sourceRoot":"","sources":["../../src/core/UsherSignalStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,CAAC,CAAC;CAClB;AAQD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAS;gBAER,QAAQ,EAAE,MAAM;IAO5B,OAAO,CAAC,QAAQ;IAIhB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc;IAerC,OAAO,CAAC,IAAI;IAWZ,yFAAyF;IACzF,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI;IA0BvI,oEAAoE;IACpE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAcrD,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,WAAW,EAAE;IAKtD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;CAG1C"}
+{"version":3,"file":"UsherSignalStore.d.ts","sourceRoot":"","sources":["../../src/core/UsherSignalStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,CAAC,CAAC;CAClB;AAQD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAS;gBAER,QAAQ,EAAE,MAAM;IAO5B,OAAO,CAAC,QAAQ;IAIhB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc;IAerC,OAAO,CAAC,IAAI;IAWZ,yFAAyF;IACzF,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI;IA0BvI;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAkBnG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,WAAW,EAAE;IAKtD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;CAG1C"}

package/dist/core/UsherSignalStore.js

@@ -86,15 +86,30 @@ export class UsherSignalStore {
             return null;
         }
     }
-    /** Mark a signal as acted-on (precision numerator). Best-effort. */
-    markActed(topicId, signalId) {
+    /**
+     * Mark a signal as acted-on (precision numerator). Best-effort, idempotent
+     * (a second call on the same signal is a no-op returning false).
+     *
+     * `opts.via` records WHICH correlation path confirmed usefulness ('use' =
+     * the agent used it in a reply; 'miss' = the user had to correct on it) and
+     * is reflected in the split metrics. `opts.at` lets callers stamp a
+     * deterministic timestamp (tests); defaults to now.
+     */
+    markActed(topicId, signalId, opts) {
         try {
             const file = this.load(topicId);
             const sig = file.signals.find(x => x.id === signalId);
             if (!sig || sig.acted)
                 return false;
             sig.acted = true;
+            if (opts?.via)
+                sig.actedVia = opts.via;
+            sig.actedAt = opts?.at ?? new Date().toISOString();
             file.metrics.acted += 1;
+            if (opts?.via === 'use')
+                file.metrics.acted_by_use = (file.metrics.acted_by_use ?? 0) + 1;
+            else if (opts?.via === 'miss')
+                file.metrics.acted_by_miss = (file.metrics.acted_by_miss ?? 0) + 1;
             this.save(file);
             return true;
         }

package/dist/core/UsherSignalStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"UsherSignalStore.js","sourceRoot":"","sources":["../../src/core/UsherSignalStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"UsherSignalStore.js","sourceRoot":"","sources":["../../src/core/UsherSignalStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2CzC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;AAC1G,CAAC;AAED,MAAM,OAAO,gBAAgB;IACnB,GAAG,CAAS;IAEpB,YAAY,QAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC;YAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAAC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YAChE,OAAO,CAAC,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,OAAe;QAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;gBACtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAmB,CAAC;gBAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;oBAAE,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC;gBACxD,IAAI,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC;gBACjE,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,uCAAuC,OAAO,YAAY,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAEO,IAAI,CAAC,IAAoB;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvC,MAAM,GAAG,GAAG,GAAG,EAAE,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACrD,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACrD,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,GAAG,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,yFAAyF;IACzF,YAAY,CAAC,OAAe,EAAE,CAAyF;QACrH,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChC,MAAM,MAAM,GAAgB;gBAC1B,EAAE,EAAE,QAAQ,UAAU,EAAE,EAAE;gBAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACpC,KAAK,EAAE,KAAK;aACb,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;gBAChD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,OAAO,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,MAAM,CAAC,EAAE,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,2CAA2C,GAAG,EAAE,CAAC,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAe,EAAE,QAAgB,EAAE,IAA4C;QACvF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;YACtD,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK;gBAAE,OAAO,KAAK,CAAC;YACpC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;YACjB,IAAI,IAAI,EAAE,GAAG;gBAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC;YACvC,GAAG,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACnD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;YACxB,IAAI,IAAI,EAAE,GAAG,KAAK,KAAK;gBAAE,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;iBACrF,IAAI,IAAI,EAAE,GAAG,KAAK,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAClG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,KAAK,GAAG,EAAE;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9C,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC;IACpC,CAAC;CACF"}

package/dist/messaging/AttentionTopicGuard.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AttentionTopicGuard — a per-source + global circuit breaker for forum-topic
+ * creation. NOT a blocker: it is a DELIVERY SHAPER (same class as
+ * SentinelNotifier), never a gate. It holds no authority over agent behavior or
+ * information flow — it only changes the FORM of delivery (one coalesced topic +
+ * a log line) for non-critical, high-volume notices, and never withholds a
+ * critical notice or drops an item. See docs/signal-vs-authority.md (the rate-
+ * counter / transport-dedup carve-outs).
+ *
+ * Built in response to the 2026-05-28 topic-spam flood (the SECOND such flood;
+ * the first, 2026-05-22, produced the SentinelNotifier fix). Root cause both
+ * times: `TelegramAdapter.createAttentionItem` spawns a BRAND-NEW forum topic
+ * per attention item, and there was no structural gate stopping a housekeeping
+ * feature from raising attention items at volume.
+ *
+ * It sits at the one chokepoint (createAttentionItem) and caps how many NEW
+ * topics may be spawned in a rolling window — BOTH per source AND globally. Past
+ * the budget, items are COALESCED into one running notice topic + logged. The
+ * GLOBAL cap is load-bearing: a mis-wired feature that varies its `sourceContext`
+ * per item would dodge a per-source-only budget, so once total topic creation in
+ * the window exceeds the global ceiling, every further non-critical item — of any
+ * source — coalesces into ONE shared global bucket. That makes the "a brand-new
+ * mis-wired feature gets auto-throttled" guarantee hold regardless of source
+ * cardinality.
+ *
+ * Invariants:
+ *  - HIGH / URGENT (case-insensitive; CRITICAL treated as URGENT) ALWAYS get
+ *    their own topic and are never counted. Critical messages are never coalesced.
+ *  - No item is ever DROPPED. A coalesced item is still recorded in the attention
+ *    store and written to the suppression audit log; only its per-item TOPIC is
+ *    withheld.
+ *
+ * Pure logic, injectable clock, bounded memory — unit-testable in isolation.
+ */
+export interface AttentionTopicGuardConfig {
+    /** When false, every item is allowed its own topic (pre-guard behavior). */
+    enabled: boolean;
+    /** Rolling window over which topic creations are counted. */
+    windowMs: number;
+    /** Max NEW topics a single source may spawn within `windowMs`. */
+    maxTopicsPerSource: number;
+    /**
+     * Max NEW topics across ALL sources within `windowMs`. Backstop against a
+     * source that varies its key per item to dodge the per-source budget. Past
+     * this, non-critical items coalesce into one shared global bucket regardless
+     * of source. Must be >= maxTopicsPerSource to be meaningful.
+     */
+    maxTopicsGlobal: number;
+    /** Hard cap on distinct source keys tracked (memory bound). */
+    maxTrackedSources: number;
+}
+export declare const DEFAULT_ATTENTION_TOPIC_GUARD: AttentionTopicGuardConfig;
+/** The shared key used when the GLOBAL cap (not a per-source cap) trips. */
+export declare const GLOBAL_BUCKET = "*";
+export type GuardDecision = {
+    action: 'allow';
+} | {
+    action: 'coalesce';
+    firstInEpisode: boolean;
+    suppressedCount: number;
+    bucket: string;
+};
+export declare class AttentionTopicGuard {
+    private readonly cfg;
+    private readonly now;
+    /** source key -> timestamps of recent topic-relevant events within the window. */
+    private readonly events;
+    /** bucket key -> count of items coalesced in the CURRENT (uninterrupted) episode. */
+    private readonly episode;
+    /** Global rolling timeline of topic-relevant events (all sources). */
+    private globalEvents;
+    constructor(cfg?: Partial<AttentionTopicGuardConfig>, now?: () => number);
+    get config(): Readonly<AttentionTopicGuardConfig>;
+    /**
+     * Decide whether an item from `source` at `priority` may spawn its own topic.
+     * Returns the coalesce `bucket` (the source key, or GLOBAL_BUCKET when only the
+     * global cap tripped) so the adapter routes all global-flood notices into ONE
+     * shared topic rather than one-per-varying-source.
+     */
+    decide(source: string | undefined, priority: string | undefined): GuardDecision;
+    /** Drop source keys whose events have all aged out, and hard-cap map size. */
+    private evictStaleSources;
+    /** Test/inspection seam. */
+    episodeCount(bucket: string): number;
+    /** Test/inspection seam — number of distinct source keys currently tracked. */
+    get trackedSourceCount(): number;
+}
+//# sourceMappingURL=AttentionTopicGuard.d.ts.map

package/dist/messaging/AttentionTopicGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttentionTopicGuard.d.ts","sourceRoot":"","sources":["../../src/messaging/AttentionTopicGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,6BAA6B,EAAE,yBAM3C,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAW7F,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAgB;gBAExB,GAAG,GAAE,OAAO,CAAC,yBAAyB,CAAM,EAAE,GAAG,GAAE,MAAM,MAAyB;IAmB9F,IAAI,MAAM,IAAI,QAAQ,CAAC,yBAAyB,CAAC,CAEhD;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa;IAqC/E,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB;IAuBzB,4BAA4B;IAC5B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIpC,+EAA+E;IAC/E,IAAI,kBAAkB,IAAI,MAAM,CAE/B;CACF"}

package/dist/messaging/AttentionTopicGuard.js

@@ -0,0 +1,154 @@
+/**
+ * AttentionTopicGuard — a per-source + global circuit breaker for forum-topic
+ * creation. NOT a blocker: it is a DELIVERY SHAPER (same class as
+ * SentinelNotifier), never a gate. It holds no authority over agent behavior or
+ * information flow — it only changes the FORM of delivery (one coalesced topic +
+ * a log line) for non-critical, high-volume notices, and never withholds a
+ * critical notice or drops an item. See docs/signal-vs-authority.md (the rate-
+ * counter / transport-dedup carve-outs).
+ *
+ * Built in response to the 2026-05-28 topic-spam flood (the SECOND such flood;
+ * the first, 2026-05-22, produced the SentinelNotifier fix). Root cause both
+ * times: `TelegramAdapter.createAttentionItem` spawns a BRAND-NEW forum topic
+ * per attention item, and there was no structural gate stopping a housekeeping
+ * feature from raising attention items at volume.
+ *
+ * It sits at the one chokepoint (createAttentionItem) and caps how many NEW
+ * topics may be spawned in a rolling window — BOTH per source AND globally. Past
+ * the budget, items are COALESCED into one running notice topic + logged. The
+ * GLOBAL cap is load-bearing: a mis-wired feature that varies its `sourceContext`
+ * per item would dodge a per-source-only budget, so once total topic creation in
+ * the window exceeds the global ceiling, every further non-critical item — of any
+ * source — coalesces into ONE shared global bucket. That makes the "a brand-new
+ * mis-wired feature gets auto-throttled" guarantee hold regardless of source
+ * cardinality.
+ *
+ * Invariants:
+ *  - HIGH / URGENT (case-insensitive; CRITICAL treated as URGENT) ALWAYS get
+ *    their own topic and are never counted. Critical messages are never coalesced.
+ *  - No item is ever DROPPED. A coalesced item is still recorded in the attention
+ *    store and written to the suppression audit log; only its per-item TOPIC is
+ *    withheld.
+ *
+ * Pure logic, injectable clock, bounded memory — unit-testable in isolation.
+ */
+export const DEFAULT_ATTENTION_TOPIC_GUARD = {
+    enabled: true,
+    windowMs: 10 * 60 * 1000,
+    maxTopicsPerSource: 3,
+    maxTopicsGlobal: 8,
+    maxTrackedSources: 512,
+};
+/** The shared key used when the GLOBAL cap (not a per-source cap) trips. */
+export const GLOBAL_BUCKET = '*';
+/** Priorities that always get their own topic and are never counted. */
+const CRITICAL_PRIORITIES = new Set(['HIGH', 'URGENT', 'CRITICAL']);
+function coerceNum(v, fallback, { int = false, min = 0 } = {}) {
+    const n = typeof v === 'number' ? v : NaN;
+    if (!Number.isFinite(n) || n < min)
+        return fallback;
+    return int ? Math.floor(n) : n;
+}
+export class AttentionTopicGuard {
+    cfg;
+    now;
+    /** source key -> timestamps of recent topic-relevant events within the window. */
+    events = new Map();
+    /** bucket key -> count of items coalesced in the CURRENT (uninterrupted) episode. */
+    episode = new Map();
+    /** Global rolling timeline of topic-relevant events (all sources). */
+    globalEvents = [];
+    constructor(cfg = {}, now = () => Date.now()) {
+        // Validate/coerce: a fat-fingered NaN/negative must NOT silently disable the
+        // guard (NaN comparisons are always false → it would never trip).
+        const d = DEFAULT_ATTENTION_TOPIC_GUARD;
+        const windowMs = coerceNum(cfg.windowMs, d.windowMs, { min: 1 });
+        const maxTopicsPerSource = coerceNum(cfg.maxTopicsPerSource, d.maxTopicsPerSource, { int: true, min: 0 });
+        this.cfg = {
+            enabled: cfg.enabled !== false,
+            windowMs,
+            maxTopicsPerSource,
+            // Independent global ceiling. A LOW global with a HIGH per-source budget is
+            // the intended high-cardinality config (cap total topics regardless of how
+            // many distinct source keys appear), so we do NOT clamp it up to per-source.
+            maxTopicsGlobal: coerceNum(cfg.maxTopicsGlobal, d.maxTopicsGlobal, { int: true, min: 1 }),
+            maxTrackedSources: coerceNum(cfg.maxTrackedSources, d.maxTrackedSources, { int: true, min: 1 }),
+        };
+        this.now = now;
+    }
+    get config() {
+        return this.cfg;
+    }
+    /**
+     * Decide whether an item from `source` at `priority` may spawn its own topic.
+     * Returns the coalesce `bucket` (the source key, or GLOBAL_BUCKET when only the
+     * global cap tripped) so the adapter routes all global-flood notices into ONE
+     * shared topic rather than one-per-varying-source.
+     */
+    decide(source, priority) {
+        if (!this.cfg.enabled)
+            return { action: 'allow' };
+        const p = (priority ?? '').toUpperCase();
+        if (CRITICAL_PRIORITIES.has(p))
+            return { action: 'allow' };
+        const key = source && source.trim() ? source : 'unknown';
+        const now = this.now();
+        const cutoff = now - this.cfg.windowMs;
+        const perRecent = (this.events.get(key) ?? []).filter((t) => t >= cutoff);
+        this.globalEvents = this.globalEvents.filter((t) => t >= cutoff);
+        const perTripped = perRecent.length >= this.cfg.maxTopicsPerSource;
+        const globalTripped = this.globalEvents.length >= this.cfg.maxTopicsGlobal;
+        // Record this event in both timelines so a sustained flood keeps the window
+        // full and stays in a single coalesce episode.
+        perRecent.push(now);
+        this.events.set(key, perRecent);
+        this.globalEvents.push(now);
+        this.evictStaleSources(cutoff);
+        if (perTripped || globalTripped) {
+            // Per-source flood → coalesce under the source (one topic per flooding
+            // source). Global-only flood (many low-volume sources) → coalesce under the
+            // shared global bucket (one topic total), defeating key-variation dodges.
+            const bucket = perTripped ? key : GLOBAL_BUCKET;
+            const count = (this.episode.get(bucket) ?? 0) + 1;
+            this.episode.set(bucket, count);
+            return { action: 'coalesce', firstInEpisode: count === 1, suppressedCount: count, bucket };
+        }
+        // Under both budgets: own topic, and any prior episode for this source is over.
+        this.episode.set(key, 0);
+        return { action: 'allow' };
+    }
+    /** Drop source keys whose events have all aged out, and hard-cap map size. */
+    evictStaleSources(cutoff) {
+        if (this.events.size <= this.cfg.maxTrackedSources) {
+            // cheap path: nothing to do until we approach the cap.
+            return;
+        }
+        for (const [k, ts] of this.events) {
+            const live = ts.filter((t) => t >= cutoff);
+            if (live.length === 0) {
+                this.events.delete(k);
+                this.episode.delete(k);
+            }
+            else {
+                this.events.set(k, live);
+            }
+        }
+        // If still over the cap (many genuinely-active sources), drop the oldest.
+        while (this.events.size > this.cfg.maxTrackedSources) {
+            const oldest = this.events.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.events.delete(oldest);
+            this.episode.delete(oldest);
+        }
+    }
+    /** Test/inspection seam. */
+    episodeCount(bucket) {
+        return this.episode.get(bucket && bucket.trim() ? bucket : 'unknown') ?? 0;
+    }
+    /** Test/inspection seam — number of distinct source keys currently tracked. */
+    get trackedSourceCount() {
+        return this.events.size;
+    }
+}
+//# sourceMappingURL=AttentionTopicGuard.js.map