@animalabs/agent-framework 0.9.0 → 0.11.0

package/dist/src/gate/event-gate.d.ts

@@ -11,12 +11,24 @@
  * inference tokens, not whether the agent should know about the event.
  */
 import type { ToolDefinition } from '../types/events.js';
-import type { GateConfig, GatePolicy, GateDecision, GateEventInfo, GateStatus } from './types.js';
+import type { GateConfig, GatePolicy, GateDecision, GateEventInfo, GateStatus, ShadowWarning, GateProbeRow } from './types.js';
 export type { GateConfig, GateOptions, GateDecision, GateEventInfo } from './types.js';
 interface TraceEventLike {
     type: string;
     [key: string]: unknown;
 }
+/**
+ * Find rules made unreachable by earlier, broader rules (first match wins).
+ * The 2026-08-08 Mythos incident is the canonical catch: a prepended
+ * `{scope:[mcpl:channel-incoming]}` sampler silently made the
+ * direct-address and mention rules dead for the whole incoming lane.
+ * `passthrough` observers shadow nothing — non-firing matches fall through.
+ */
+export declare function findShadowedPolicies(policies: GatePolicy[]): ShadowWarning[];
+/** Human-readable one-liner for a ShadowWarning, used in tool results,
+ *  traces, and gate_status alike so the same hazard reads the same way
+ *  everywhere. */
+export declare function formatShadowWarning(w: ShadowWarning): string;
 export declare class EventGate {
     private configPath;
     private config;
@@ -36,6 +48,8 @@ export declare class EventGate {
     private inferring;
     private inferenceBuffer;
     private stats;
+    private shadowWarningsCache;
+    private shadowWarningsFingerprint;
     private totalEvaluations;
     private defaultTriggered;
     private defaultSkipped;
@@ -87,13 +101,21 @@ export declare class EventGate {
      * without waiting for the throttled mtime reload.
      *
      * The freshest on-disk config is re-read first, so a concurrent operator edit
-     * isn't clobbered. A policy with the same `name` is replaced IN PLACE (order
-     * preserved); otherwise it is appended, or prepended when `position:'prepend'`
-     * — first match wins, so a wake rule that must beat a broad defer/debounce
-     * belongs at the front.
+     * isn't clobbered. A policy with the same `name` is replaced IN PLACE when no
+     * `position` is given (order preserved); WITH a `position` it is moved there
+     * — so re-issuing a rule is also how you reposition it. New policies append
+     * by default; `'prepend'` puts one at the very front (ahead of EVERYTHING,
+     * including addressed-message wake rules — see the shadow lint), and the
+     * anchored forms `{before: name}` / `{after: name}` insert relative to an
+     * existing rule, which is almost always the safer way to order a sampler
+     * or debounce against a specific catch-all.
      */
     addPolicy(rawPolicy: unknown, options?: {
-        position?: 'append' | 'prepend';
+        position?: 'append' | 'prepend' | {
+            before: string;
+        } | {
+            after: string;
+        };
     }): GatePolicy;
     /**
      * Remove a policy by name from gate.json and clear its live state. Any pending
@@ -115,7 +137,6 @@ export declare class EventGate {
      * if the write fails (disk/permission) — callers surface it as a tool error.
      */
     private writeConfig;
-    private matchPolicy;
     private compiledMatches;
     evaluate(info: GateEventInfo): GateDecision;
     private computeDecision;
@@ -137,6 +158,40 @@ export declare class EventGate {
      * — those are historical and shouldn't reset on a config edit.
      */
     private clearPolicyState;
+    /**
+     * Non-mutating twin of the behavior decision: would this policy trigger for
+     * this event, given CURRENT counter/bucket state? Reads state, never writes
+     * it — no stats, no traces, no counter increments, no debounce batching.
+     */
+    private wouldTrigger;
+    /**
+     * Evaluate an event against the declarative policy table WITHOUT side
+     * effects: no counters advance, no debounce batches form, no stats or
+     * traces are recorded, and sleep suppression is ignored (a probe asks
+     * about the table, not the moment). gate.js is not consulted — a script
+     * may be stateful, and a probe must never perturb state.
+     */
+    probe(info: GateEventInfo): GateDecision;
+    /**
+     * Probe a canonical set of synthetic chat/heartbeat events and report which
+     * rule wins each and whether it would wake. Backs the before/after table in
+     * the wake_add_rule result — the point where a rule change's real semantics
+     * must become legible (af#105; the Mythos stand-back-density incident would
+     * have been visible as `dm: discord-direct-address → stand-back-density`).
+     * Probes are representative shapes, not an exhaustive event space — rules
+     * keyed on specific channels/mounts may not match any probe.
+     */
+    probeTable(): GateProbeRow[];
+    /** Current shadow-lint findings for the live policy order. Fresh compute —
+     *  cheap (policy lists are tens of entries at most). */
+    lintShadows(): ShadowWarning[];
+    /**
+     * Recompute shadow warnings and, when the set changed and is non-empty,
+     * emit a `gate:shadow-warnings` trace so the hazard lands in ops
+     * observability at the moment the order changed — not at the next missed
+     * DM. Called from writeConfig and reloadIfChanged.
+     */
+    private refreshShadowWarnings;
     /**
      * Returns a callback compatible with McplServerConfig.shouldTriggerInference.
      * Used by the framework to wire the gate into PushHandler and ChannelRegistry.

package/dist/src/gate/event-gate.d.ts.map

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

package/dist/src/gate/event-gate.js

@@ -238,12 +238,138 @@ function validatePolicy(raw) {
         if (names.length > 0)
             resets = names;
     }
+    // Validate passthrough — only meaningful on the counting behaviors, where
+    // "matched but didn't fire" is a distinct outcome that can fall through.
+    // On always/defer/skip/debounce the flag would be a no-op at best and a
+    // misleading promise at worst, so reject it loudly instead of ignoring it.
+    let passthrough;
+    if (obj.passthrough !== undefined) {
+        if (typeof obj.passthrough !== 'boolean') {
+            throw new Error(`Policy "${obj.name}": passthrough must be a boolean`);
+        }
+        if (obj.passthrough) {
+            const counting = typeof behavior === 'object'
+                && ('rate_limit' in behavior || 'passive_sample' in behavior);
+            if (!counting) {
+                throw new Error(`Policy "${obj.name}": passthrough is only valid with rate_limit or `
+                    + `passive_sample behaviors — for "${formatBehavior(behavior)}" there is `
+                    + 'no non-firing match to fall through on');
+            }
+            passthrough = true;
+        }
+    }
     const policy = { name: obj.name, match, behavior };
     if (resets)
         policy.resets = resets;
+    if (passthrough)
+        policy.passthrough = passthrough;
     return policy;
 }
 // ---------------------------------------------------------------------------
+// Shadow lint — prove (conservatively) when rule ordering makes a rule dead
+// ---------------------------------------------------------------------------
+/** Set-inclusion helper for exact-string lists. */
+function subsetOf(a, b) {
+    return a.every((x) => b.includes(x));
+}
+/** A glob field on the EARLIER rule is at least as broad as the LATER rule's
+ *  when it's absent, the universal "*", or literally identical. Anything
+ *  cleverer (real glob subsumption) is out of conservative scope. */
+function globAtLeastAsBroad(earlier, later) {
+    if (earlier === undefined || earlier === '*')
+        return true;
+    return earlier === later;
+}
+/**
+ * Event types for which `earlier` provably matches EVERY event that `later`
+ * would match — i.e. the types for which `later` is unreachable when
+ * `earlier` sits before it and consumes its matches. Returns null when
+ * subsumption can't be proven (which is not proof of safety — the lint is
+ * deliberately one-sided so every warning it emits is true).
+ */
+function subsumedEventTypes(earlier, later) {
+    const e = earlier.match;
+    const l = later.match;
+    // Scope: which of `later`'s event types does `earlier` cover?
+    let covered;
+    if (!e.scope || e.scope.length === 0) {
+        covered = l.scope && l.scope.length > 0 ? l.scope : 'all';
+    }
+    else if (!l.scope || l.scope.length === 0) {
+        // `later` matches all types; `earlier` only consumes its own scope, so
+        // the shadow is partial — exactly those types.
+        covered = e.scope;
+    }
+    else {
+        const overlap = l.scope.filter((t) => e.scope.includes(t));
+        if (overlap.length === 0)
+            return null;
+        covered = overlap;
+    }
+    // Every remaining discriminator on `earlier` must be at least as broad as
+    // `later`'s, otherwise some `later` events slip past `earlier`.
+    if (!globAtLeastAsBroad(e.source, l.source))
+        return null;
+    if (!globAtLeastAsBroad(e.channel, l.channel))
+        return null;
+    if (!globAtLeastAsBroad(e.mount, l.mount))
+        return null;
+    if (!globAtLeastAsBroad(e.pathGlob, l.pathGlob))
+        return null;
+    if (e.filter) {
+        if (!l.filter || e.filter.type !== l.filter.type || e.filter.pattern !== l.filter.pattern) {
+            return null;
+        }
+    }
+    // metadataTrue / tagsAny are OR-lists: earlier subsumes when later's list
+    // is a subset of earlier's (any event satisfying later then satisfies
+    // earlier too). tagsAll / tagsNone are AND/NOT constraints: earlier
+    // subsumes when its constraints are a subset of later's.
+    if (e.metadataTrue && e.metadataTrue.length > 0) {
+        if (!l.metadataTrue || !subsetOf(l.metadataTrue, e.metadataTrue))
+            return null;
+    }
+    if (e.tagsAny && e.tagsAny.length > 0) {
+        if (!l.tagsAny || !subsetOf(l.tagsAny, e.tagsAny))
+            return null;
+    }
+    if (e.tagsAll && !subsetOf(e.tagsAll, l.tagsAll ?? []))
+        return null;
+    if (e.tagsNone && !subsetOf(e.tagsNone, l.tagsNone ?? []))
+        return null;
+    return covered;
+}
+/**
+ * Find rules made unreachable by earlier, broader rules (first match wins).
+ * The 2026-08-08 Mythos incident is the canonical catch: a prepended
+ * `{scope:[mcpl:channel-incoming]}` sampler silently made the
+ * direct-address and mention rules dead for the whole incoming lane.
+ * `passthrough` observers shadow nothing — non-firing matches fall through.
+ */
+export function findShadowedPolicies(policies) {
+    const out = [];
+    for (let i = 0; i < policies.length; i++) {
+        const earlier = policies[i];
+        if (earlier.passthrough)
+            continue;
+        for (let j = i + 1; j < policies.length; j++) {
+            const covered = subsumedEventTypes(earlier, policies[j]);
+            if (covered) {
+                out.push({ earlier: earlier.name, later: policies[j].name, eventTypes: covered });
+            }
+        }
+    }
+    return out;
+}
+/** Human-readable one-liner for a ShadowWarning, used in tool results,
+ *  traces, and gate_status alike so the same hazard reads the same way
+ *  everywhere. */
+export function formatShadowWarning(w) {
+    const types = w.eventTypes === 'all' ? 'ALL event types' : w.eventTypes.join(', ');
+    return `rule "${w.earlier}" makes "${w.later}" unreachable for ${types} `
+        + `(first match wins — every event "${w.later}" would match is consumed by "${w.earlier}" first)`;
+}
+// ---------------------------------------------------------------------------
 // EventGate
 // ---------------------------------------------------------------------------
 export class EventGate {
@@ -271,6 +397,10 @@ export class EventGate {
     inferenceBuffer = [];
     // Per-policy stats
     stats = new Map();
+    // Shadow-lint cache (see refreshShadowWarnings) — recomputed on every
+    // config change, fingerprinted so an unchanged hazard set doesn't re-trace.
+    shadowWarningsCache = [];
+    shadowWarningsFingerprint = '[]';
     // Observability counters for events that didn't match any policy
     totalEvaluations = 0;
     defaultTriggered = 0;
@@ -360,6 +490,7 @@ export class EventGate {
         // Load config
         this.config = this.loadConfig() ?? opts.initialConfig ?? { ...DEFAULT_CONFIG };
         this.compiledPolicies = this.compilePolicies(this.config);
+        this.refreshShadowWarnings('startup');
         // Programmable gate: an optional agent-authored `gate.js` next to gate.json.
         // Absent ⇒ inactive (zero overhead beyond a throttled stat check).
         this.gateScript = new GateScript(join(dirname(this.configPath), 'gate.js'), opts.scriptTimeoutMs ?? 50, this.now);
@@ -470,6 +601,7 @@ export class EventGate {
             this.config = newConfig;
             this.compiledPolicies = this.compilePolicies(newConfig);
             this.lastReloadTimestamp = now;
+            this.refreshShadowWarnings('reload');
             this.emitTrace({
                 type: 'gate:config-reloaded',
                 configPath: this.configPath,
@@ -497,24 +629,42 @@ export class EventGate {
      * without waiting for the throttled mtime reload.
      *
      * The freshest on-disk config is re-read first, so a concurrent operator edit
-     * isn't clobbered. A policy with the same `name` is replaced IN PLACE (order
-     * preserved); otherwise it is appended, or prepended when `position:'prepend'`
-     * — first match wins, so a wake rule that must beat a broad defer/debounce
-     * belongs at the front.
+     * isn't clobbered. A policy with the same `name` is replaced IN PLACE when no
+     * `position` is given (order preserved); WITH a `position` it is moved there
+     * — so re-issuing a rule is also how you reposition it. New policies append
+     * by default; `'prepend'` puts one at the very front (ahead of EVERYTHING,
+     * including addressed-message wake rules — see the shadow lint), and the
+     * anchored forms `{before: name}` / `{after: name}` insert relative to an
+     * existing rule, which is almost always the safer way to order a sampler
+     * or debounce against a specific catch-all.
      */
     addPolicy(rawPolicy, options) {
         const policy = validatePolicy(rawPolicy);
         const current = this.loadConfig() ?? this.config;
         const policies = [...current.policies];
         const idx = policies.findIndex((p) => p.name === policy.name);
-        if (idx >= 0) {
-            policies[idx] = policy;
-        }
-        else if (options?.position === 'prepend') {
-            policies.unshift(policy);
+        const position = options?.position;
+        if (idx >= 0 && position === undefined) {
+            policies[idx] = policy; // replace in place, order preserved
         }
         else {
-            policies.push(policy);
+            if (idx >= 0)
+                policies.splice(idx, 1); // repositioning a known rule
+            if (position === 'prepend') {
+                policies.unshift(policy);
+            }
+            else if (position !== undefined && typeof position === 'object') {
+                const anchorName = 'before' in position ? position.before : position.after;
+                const anchorIdx = policies.findIndex((p) => p.name === anchorName);
+                if (anchorIdx < 0) {
+                    throw new Error(`addPolicy: no policy named "${anchorName}" to anchor on — `
+                        + `have: [${policies.map((p) => p.name).join(', ')}]`);
+                }
+                policies.splice('before' in position ? anchorIdx : anchorIdx + 1, 0, policy);
+            }
+            else {
+                policies.push(policy);
+            }
         }
         this.writeConfig({ ...current, policies });
         this.emitTrace({
@@ -570,6 +720,7 @@ export class EventGate {
         writeFileSync(this.configPath, JSON.stringify(config, null, 2) + '\n');
         this.config = config;
         this.compiledPolicies = this.compilePolicies(config);
+        this.refreshShadowWarnings('policy-mutation');
         this.configSource = 'file';
         this.configErrors = [];
         this.lastReloadTimestamp = Date.now();
@@ -581,16 +732,9 @@ export class EventGate {
         }
     }
     // =========================================================================
-    // Policy matching — first match wins
+    // Policy matching — first match wins (passthrough observers excepted; the
+    // match/decide loop lives inline in evaluate() and probe())
     // =========================================================================
-    matchPolicy(info) {
-        for (const compiled of this.compiledPolicies) {
-            if (this.compiledMatches(compiled, info)) {
-                return compiled.policy;
-            }
-        }
-        return null;
-    }
     compiledMatches(compiled, info) {
         const match = compiled.policy.match;
         // Scope check
@@ -694,11 +838,33 @@ export class EventGate {
         // Programmable gate (gate.js) takes precedence when present and returns a
         // behavior; null/undefined (inactive, error, or a deliberate pass) falls
         // through to the declarative gate.json policies below.
+        //
+        // Declarative policies: first match wins — EXCEPT `passthrough` observers,
+        // which consume the event only when their counting behavior actually
+        // fires. A passthrough policy that matched-but-didn't-fire records its
+        // count and evaluation continues, so a density sampler placed early can
+        // no longer swallow the addressed-message rules behind it.
         const scripted = this.gateScript.evaluate(info);
-        const policy = scripted != null ? { name: 'gate.js', match: {}, behavior: scripted } : this.matchPolicy(info);
-        const decision = this.computeDecision(policy, info);
+        let decision = null;
+        const observed = [];
+        if (scripted != null) {
+            decision = this.computeDecision({ name: 'gate.js', match: {}, behavior: scripted }, info);
+        }
+        else {
+            for (const compiled of this.compiledPolicies) {
+                if (!this.compiledMatches(compiled, info))
+                    continue;
+                const candidate = this.computeDecision(compiled.policy, info);
+                if (candidate.trigger || !compiled.policy.passthrough) {
+                    decision = candidate;
+                    break;
+                }
+                observed.push(compiled.policy.name); // counted, didn't fire, fell through
+            }
+        }
         this.totalEvaluations++;
-        if (!policy) {
+        if (!decision) {
+            decision = this.computeDecision(null, info);
             const bucket = this.defaultByEventType.get(info.eventType)
                 ?? { triggered: 0, skipped: 0 };
             if (decision.trigger) {
@@ -711,6 +877,8 @@ export class EventGate {
             }
             this.defaultByEventType.set(info.eventType, bucket);
         }
+        if (observed.length > 0)
+            decision.observed = observed;
         this.emitTrace({
             type: 'gate:decision',
             eventType: info.eventType,
@@ -719,6 +887,7 @@ export class EventGate {
             matchedPolicy: decision.policyName,
             trigger: decision.trigger,
             behavior: formatBehavior(decision.behavior),
+            ...(observed.length > 0 ? { observed } : {}),
             timestamp: this.now(),
         });
         return decision;
@@ -866,6 +1035,147 @@ export class EventGate {
         this.passiveSampleFires.delete(name);
     }
     // =========================================================================
+    // Dry-run probes — side-effect-free "what would this event do right now"
+    // =========================================================================
+    /**
+     * Non-mutating twin of the behavior decision: would this policy trigger for
+     * this event, given CURRENT counter/bucket state? Reads state, never writes
+     * it — no stats, no traces, no counter increments, no debounce batching.
+     */
+    wouldTrigger(policy, info) {
+        const b = policy.behavior;
+        if (b === 'always')
+            return true;
+        if (b === 'defer' || b === 'skip')
+            return false;
+        if (typeof b === 'object') {
+            if ('debounce' in b)
+                return false; // batches; never triggers inline
+            if ('rate_limit' in b) {
+                const cfg = b.rate_limit;
+                const key = this.resolveKey(info.metadata, cfg.keyBy);
+                const bucket = this.rateLimitBuckets.get(policy.name)?.get(key);
+                if (!bucket)
+                    return true; // fresh bucket starts full
+                let tokens = bucket.tokens;
+                if (tokens < cfg.tokens) {
+                    const elapsed = Math.max(0, this.now() - bucket.lastRefill);
+                    tokens = Math.min(cfg.tokens, tokens + Math.floor(elapsed / cfg.refillIntervalMs));
+                }
+                return tokens > 0;
+            }
+            if ('passive_sample' in b) {
+                const cfg = b.passive_sample;
+                const key = this.resolveKey(info.metadata, cfg.keyBy);
+                const count = this.passiveSampleCounters.get(policy.name)?.get(key) ?? 0;
+                return count + 1 >= cfg.every;
+            }
+        }
+        return false;
+    }
+    /**
+     * Evaluate an event against the declarative policy table WITHOUT side
+     * effects: no counters advance, no debounce batches form, no stats or
+     * traces are recorded, and sleep suppression is ignored (a probe asks
+     * about the table, not the moment). gate.js is not consulted — a script
+     * may be stateful, and a probe must never perturb state.
+     */
+    probe(info) {
+        for (const compiled of this.compiledPolicies) {
+            if (!this.compiledMatches(compiled, info))
+                continue;
+            const trigger = this.wouldTrigger(compiled.policy, info);
+            if (trigger || !compiled.policy.passthrough) {
+                return { trigger, policyName: compiled.policy.name, behavior: compiled.policy.behavior };
+            }
+        }
+        const trigger = (this.config.default ?? 'always') === 'always';
+        return { trigger, policyName: null, behavior: this.config.default ?? 'always' };
+    }
+    /**
+     * Probe a canonical set of synthetic chat/heartbeat events and report which
+     * rule wins each and whether it would wake. Backs the before/after table in
+     * the wake_add_rule result — the point where a rule change's real semantics
+     * must become legible (af#105; the Mythos stand-back-density incident would
+     * have been visible as `dm: discord-direct-address → stand-back-density`).
+     * Probes are representative shapes, not an exhaustive event space — rules
+     * keyed on specific channels/mounts may not match any probe.
+     */
+    probeTable() {
+        const chat = (label, eventType, metadata, tags) => ({
+            label,
+            info: {
+                content: `[probe] ${label}`,
+                eventType,
+                serverId: 'discord',
+                channelId: '',
+                metadata: { ...metadata, eventType },
+                tags,
+            },
+        });
+        const probes = [
+            chat('dm (open channel)', 'mcpl:channel-incoming', { isDM: true, isMention: true }, ['chat:dm', 'chat:private', 'chat:addressed', 'chat:from-human']),
+            chat('dm (closed channel)', 'mcpl:push-event', { isDM: true, isMention: true }, ['chat:dm', 'chat:private', 'chat:addressed', 'chat:from-human']),
+            chat('explicit mention (open channel)', 'mcpl:channel-incoming', { isMention: true, isExplicitMention: true }, ['chat:mention', 'chat:addressed', 'chat:from-human']),
+            chat('explicit mention (closed channel)', 'mcpl:push-event', { isMention: true, isExplicitMention: true }, ['chat:mention', 'chat:addressed', 'chat:from-human']),
+            chat('reply to you', 'mcpl:channel-incoming', { isMention: true, isReplyToBot: true }, ['chat:reply', 'chat:addressed', 'chat:from-human']),
+            chat('ambient (human)', 'mcpl:channel-incoming', {}, ['chat:ambient', 'chat:from-human']),
+            chat('ambient (bot)', 'mcpl:channel-incoming', { isBot: true }, ['chat:ambient', 'chat:from-bot']),
+            {
+                label: 'heartbeat',
+                info: {
+                    content: '[probe] heartbeat',
+                    eventType: 'mcpl:push-event',
+                    serverId: 'heartbeat',
+                    channelId: '',
+                    metadata: { source: 'heartbeat', eventType: 'mcpl:push-event' },
+                },
+            },
+        ];
+        return probes.map(({ label, info }) => {
+            const d = this.probe(info);
+            return {
+                probe: label,
+                eventType: info.eventType,
+                policy: d.policyName,
+                behavior: d.policyName === null
+                    ? `default:${formatBehavior(d.behavior)}`
+                    : formatBehavior(d.behavior),
+                wouldWake: d.trigger,
+            };
+        });
+    }
+    // =========================================================================
+    // Shadow lint surface
+    // =========================================================================
+    /** Current shadow-lint findings for the live policy order. Fresh compute —
+     *  cheap (policy lists are tens of entries at most). */
+    lintShadows() {
+        return findShadowedPolicies(this.config.policies);
+    }
+    /**
+     * Recompute shadow warnings and, when the set changed and is non-empty,
+     * emit a `gate:shadow-warnings` trace so the hazard lands in ops
+     * observability at the moment the order changed — not at the next missed
+     * DM. Called from writeConfig and reloadIfChanged.
+     */
+    refreshShadowWarnings(reason) {
+        const warnings = this.lintShadows();
+        const fingerprint = JSON.stringify(warnings);
+        if (fingerprint === this.shadowWarningsFingerprint)
+            return;
+        this.shadowWarningsFingerprint = fingerprint;
+        this.shadowWarningsCache = warnings;
+        if (warnings.length > 0) {
+            this.emitTrace({
+                type: 'gate:shadow-warnings',
+                reason,
+                warnings: warnings.map(formatShadowWarning),
+                timestamp: this.now(),
+            });
+        }
+    }
+    // =========================================================================
     // shouldTriggerInference callback adapter
     // =========================================================================
     /**
@@ -1269,6 +1579,7 @@ export class EventGate {
             script: this.gateScript.status(),
             policies,
             errors: [...this.configErrors],
+            shadowWarnings: this.shadowWarningsCache.map(formatShadowWarning),
             totalEvaluations: this.totalEvaluations,
             defaultDecisions: {
                 triggered: this.defaultTriggered,