@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/signal-ingestion/significance.js

@@ -0,0 +1,555 @@
+/**
+ * RFC-0030 Phase 4 — Tier 2 significance threshold, SA resonance filter,
+ * flooding detection (z-score on rolling per-source baseline), residency-
+ * violation gate.
+ *
+ * This module operates on Phase 3 `DemandCluster[]` output and produces:
+ *
+ *   1. **Tier 2 significance gate** (RFC-0030 §8): clusters must meet
+ *      `minSignalCount` + `minUniqueSources` + `minTier1SignalCount` +
+ *      `minClusterAgeDays` before they qualify for D1 scoring. Below-threshold
+ *      clusters are marked `monitored` (not silently dropped — they remain
+ *      visible for operator review).
+ *
+ *   2. **SA resonance filter** (RFC-0030 §9 + RFC-0029 Principle 4): clusters
+ *      are bucketed by SA resonance score against the current Soul DID:
+ *        - `>= fullWeight`           → `full`        (no D1 weight discount)
+ *        - `>= discounted`           → `discounted`  (D1 weight × 0.7)
+ *        - `>= excluded` (exclusive) → `low-sa-review` (D1 weight × 0.3 +
+ *          Decision logged for Product Lead batch review per AC #3)
+ *        - `<= excluded` (== 0.0)    → `out-of-scope` (excluded from D1;
+ *          logged as out-of-scope demand)
+ *
+ *   3. **OQ-13.5 flooding detection (AISDLC-433 v0.3 refinement)** — REPLACES
+ *      the previous fixed-multiplier detector with z-score on the same
+ *      per-source rolling baseline:
+ *        - For every source in the detection window, compute its
+ *          `windowCount` (signals in the last `windowMinutes`) and compare
+ *          to the per-source baseline `{mean, stddev}` computed from the
+ *          rolling `baselineDays`-day history.
+ *        - Trigger condition (RFC-0030 §13.5):
+ *            `windowCount > (mean + zScoreThreshold × stddev)`
+ *            AND `uniqueSources_in_window < minUniqueSourcesForSuspicion`
+ *          → emit `Decision: signal-flooding-detected`.
+ *        - **Cold-start handling** (AC #4): when the rolling baseline has
+ *          fewer than `baselineDays` of history, the detector returns the
+ *          `calibrating` status and emits NO Decision — Tier 2 significance
+ *          is the sole defense during the calibration window.
+ *        - **Quarantine** (AC #6, #7): flooding signals are tagged
+ *          `quarantined: true` with an `expiresAt` timestamp; quarantined
+ *          signals do NOT feed D1 (D1 path filters them out). Default
+ *          duration 24h; per-org `flooding.quarantineDurationHours`
+ *          override. Auto-expiry releases signals back to D1 candidacy.
+ *        - **Operator one-click unquarantine** (AC #8, #9): the surface
+ *          composes with RFC-0023 Blockers pane via the `QuarantineStore`
+ *          API + the `unquarantineFlooded()` helper. Unquarantine emits
+ *          `Decision: signal-flooding-false-positive` referencing the
+ *          original flooding Decision (feedback signal for v2
+ *          reputation-weighting calibration).
+ *      Pipeline NEVER halts on flooding (G0 non-blocking contract).
+ *
+ *   4. **OQ-13.3 residency-violation gate** (adapter-level): per `checkSignalResidency`,
+ *      a signal whose `region` falls outside the adopter's declared regime
+ *      `allowedRegions` is refused at adapter level. Pipeline never halts.
+ *
+ * @module signal-ingestion/significance
+ */
+import { DEFAULT_SIGNAL_INGESTION_CONFIG } from './config.js';
+/** Per-bucket D1 weight multiplier per RFC-0030 §9. */
+export const SA_WEIGHT_MULTIPLIERS = Object.freeze({
+    full: 1.0,
+    discounted: 0.7,
+    'low-sa-review': 0.3,
+    'out-of-scope': 0.0,
+    pending: 0.0,
+});
+/**
+ * Re-export of the live default for back-compat with the previous shipped
+ * surface. Phase 4 originally exposed `DEFAULT_FLOODING_DETECTION_CONFIG`
+ * as a frozen object; AISDLC-433 routes the same name to the v0.3 z-score
+ * defaults (sourced from `DEFAULT_SIGNAL_INGESTION_CONFIG.flooding.detection`)
+ * so downstream callers continue to import a working default object.
+ */
+export const DEFAULT_FLOODING_DETECTION_CONFIG = Object.freeze({
+    ...DEFAULT_SIGNAL_INGESTION_CONFIG.flooding.detection,
+});
+// ── Tier 2 significance gate (§8) ───────────────────────────────────────────
+/**
+ * Apply the RFC-0030 §8 Tier 2 significance threshold to a single cluster.
+ *
+ * The four conditions are evaluated independently so reasons can be reported
+ * back; the cluster `qualified` IFF all four pass.
+ *
+ * `asOf` defaults to `new Date()` for cluster-age computation.
+ */
+export function assessTier2Significance(cluster, threshold = DEFAULT_SIGNAL_INGESTION_CONFIG.tier2SignificanceThreshold, asOf = new Date()) {
+    const reasons = {
+        signalCount: cluster.signalCount < threshold.minSignalCount,
+        uniqueSources: cluster.uniqueSources < threshold.minUniqueSources,
+        tier1SignalCount: cluster.tier1SignalCount < threshold.minTier1SignalCount,
+        clusterAgeDays: clusterAgeDays(cluster, asOf) < threshold.minClusterAgeDays,
+    };
+    const qualified = !reasons.signalCount &&
+        !reasons.uniqueSources &&
+        !reasons.tier1SignalCount &&
+        !reasons.clusterAgeDays;
+    return { state: qualified ? 'qualified' : 'monitored', reasons };
+}
+/** Days elapsed between cluster.oldestSignalAt and `asOf`. */
+function clusterAgeDays(cluster, asOf) {
+    const ageMs = asOf.getTime() - cluster.oldestSignalAt.getTime();
+    return ageMs / (1000 * 60 * 60 * 24);
+}
+// ── SA resonance filter (§9) ────────────────────────────────────────────────
+/**
+ * Classify a cluster's SA resonance into one of five buckets per RFC-0030 §9.
+ *
+ * When `cluster.saResonance` is `undefined`, returns `pending` — the caller
+ * is expected to populate the field via the Soul DID adapter before
+ * invocation. Fail-closed: `pending` results in `eligibleForD1 = false`.
+ */
+export function classifySaResonance(cluster, thresholds = DEFAULT_SIGNAL_INGESTION_CONFIG.saResonanceThresholds) {
+    if (cluster.saResonance === undefined)
+        return 'pending';
+    const sa = cluster.saResonance;
+    if (sa >= thresholds.fullWeight)
+        return 'full';
+    if (sa >= thresholds.discounted)
+        return 'discounted';
+    if (sa > thresholds.excluded)
+        return 'low-sa-review';
+    return 'out-of-scope';
+}
+/**
+ * Apply Phase 4 significance + SA filter to a batch of `DemandCluster`s.
+ *
+ * The resulting `assessments` carry the final `d1WeightMultiplier` that
+ * Phase 5 multiplies into the D1 formula. Below-threshold clusters retain
+ * `eligibleForD1 = false` (not silently dropped) per RFC-0030 §8.
+ *
+ * `lowSaDecisions` are emitted for every cluster whose SA bucket is
+ * `low-sa-review` — these are the AC #3 "low-SA-but-high-volume" Decisions.
+ */
+export function assessClusterSignificance(clusters, options = {}) {
+    const config = options.config ?? DEFAULT_SIGNAL_INGESTION_CONFIG;
+    const asOf = options.asOf ?? new Date();
+    const assessments = [];
+    const lowSaDecisions = [];
+    const outOfScopeDecisions = [];
+    for (const cluster of clusters) {
+        const { state: tier2Significance, reasons: tier2Reasons } = assessTier2Significance(cluster, config.tier2SignificanceThreshold, asOf);
+        const saResonanceBucket = classifySaResonance(cluster, config.saResonanceThresholds);
+        const significanceMultiplier = tier2Significance === 'qualified' ? 1.0 : 0.0;
+        const saMultiplier = SA_WEIGHT_MULTIPLIERS[saResonanceBucket];
+        const d1WeightMultiplier = significanceMultiplier * saMultiplier;
+        const eligibleForD1 = tier2Significance === 'qualified' &&
+            saResonanceBucket !== 'out-of-scope' &&
+            saResonanceBucket !== 'pending';
+        assessments.push({
+            cluster,
+            tier2Significance,
+            tier2Reasons,
+            saResonanceBucket,
+            eligibleForD1,
+            d1WeightMultiplier,
+        });
+        // AC #3 — low-SA demand surfaces via Decision for Product Lead review.
+        // Emitted even when the cluster is `monitored` (below significance) — the
+        // operator should see that low-SA demand IS accumulating, regardless of
+        // whether the Tier 2 threshold has been met.
+        if (saResonanceBucket === 'low-sa-review' && cluster.saResonance !== undefined) {
+            lowSaDecisions.push({
+                type: 'Decision',
+                decision: 'signal-low-sa-for-review',
+                clusterId: cluster.clusterId,
+                saResonance: cluster.saResonance,
+                signalCount: cluster.signalCount,
+                message: `Cluster ${cluster.clusterId} has SA resonance ${cluster.saResonance.toFixed(3)} ` +
+                    `(below 'discounted' threshold ${config.saResonanceThresholds.discounted.toFixed(2)}); ` +
+                    `flagging for Product Lead batch review.`,
+            });
+        }
+        if (saResonanceBucket === 'out-of-scope' && cluster.saResonance !== undefined) {
+            outOfScopeDecisions.push({
+                type: 'Decision',
+                decision: 'signal-out-of-scope',
+                clusterId: cluster.clusterId,
+                saResonance: cluster.saResonance,
+                signalCount: cluster.signalCount,
+                message: `Cluster ${cluster.clusterId} has SA resonance ${cluster.saResonance.toFixed(3)} ` +
+                    `(at or below 'excluded' threshold ${config.saResonanceThresholds.excluded.toFixed(2)}); ` +
+                    `logging as out-of-scope demand for separate triage.`,
+            });
+        }
+    }
+    return { assessments, lowSaDecisions, outOfScopeDecisions };
+}
+/**
+ * Z-score detector — RFC-0030 §13.5 v0.3 trigger condition is
+ * `windowCount > (mean + zScoreThreshold × stddev) AND uniqueSources_in_window
+ * < minUniqueSourcesForSuspicion`.
+ *
+ * Returns a `FloodingDetectionResult` whose `status` discriminates the four
+ * outcomes (flooded / clean / calibrating / empty-window). The caller routes
+ * `result.decision` to the catalog when `status === 'flooded'`.
+ *
+ * Cold-start (AC #4): when the maximum per-source `baselineDays` observed
+ * across all in-window sources is < `config.baselineDays`, the detector
+ * returns `status: 'calibrating'` with no Decision — Tier 2 significance is
+ * the sole defense until the rolling baseline has built up.
+ *
+ * Quarantine (AC #6, #7): when `quarantineConfig.enabled`, every in-window
+ * signal from a flagged source is tagged in the supplied `quarantineStore`
+ * with `expiresAt = asOf + quarantineDurationHours`. Auto-expiry happens
+ * lazily on read (see `isSignalQuarantined()`).
+ */
+export function detectFlooding(signals, options = {}) {
+    const config = options.config ?? DEFAULT_FLOODING_DETECTION_CONFIG;
+    const quarantineConfig = options.quarantineConfig ?? DEFAULT_SIGNAL_INGESTION_CONFIG.flooding.quarantine;
+    const asOf = options.asOf ?? new Date();
+    const perSourceBaselines = options.perSourceBaselines ?? {};
+    const generateDecisionId = options.generateDecisionId ?? defaultDecisionIdFactory(asOf);
+    const windowStartMs = asOf.getTime() - config.windowMinutes * 60 * 1000;
+    const windowEndMs = asOf.getTime();
+    const windowSignals = signals.filter((s) => {
+        const ts = s.sourceTimestamp.getTime();
+        return ts >= windowStartMs && ts <= windowEndMs;
+    });
+    if (windowSignals.length === 0) {
+        return { status: 'empty-window', signalCount: 0, uniqueSources: 0, baselineDaysObserved: 0 };
+    }
+    // Group window signals by source.
+    const perSourceWindowCounts = new Map();
+    const perSourceWindowSignals = new Map();
+    for (const s of windowSignals) {
+        const src = resolveSourceName(s);
+        perSourceWindowCounts.set(src, (perSourceWindowCounts.get(src) ?? 0) + 1);
+        const bucket = perSourceWindowSignals.get(src) ?? [];
+        bucket.push(s);
+        perSourceWindowSignals.set(src, bucket);
+    }
+    const signalCount = windowSignals.length;
+    const uniqueSources = perSourceWindowCounts.size;
+    // Cold-start: take max baselineDays across all in-window sources. When ANY
+    // source has the full window observed, the detector is calibrated for that
+    // source; when NO source has the full window, we're calibrating overall.
+    let maxBaselineDays = 0;
+    for (const src of perSourceWindowCounts.keys()) {
+        const samples = perSourceBaselines[src] ?? [];
+        if (samples.length > maxBaselineDays)
+            maxBaselineDays = samples.length;
+    }
+    if (maxBaselineDays < config.baselineDays) {
+        return {
+            status: 'calibrating',
+            signalCount,
+            uniqueSources,
+            baselineDaysObserved: maxBaselineDays,
+        };
+    }
+    // Trigger condition guard #2: uniqueSources_in_window < minUniqueSourcesForSuspicion.
+    // When uniqueSources >= threshold, a "many sources contributing" pattern is
+    // healthy organic traffic — z-score alone is not enough to call it flooding.
+    // RFC-0030 §13.5: "trigger when volume > 3σ AND uniqueSources < 3".
+    if (uniqueSources >= config.minUniqueSourcesForSuspicion) {
+        return {
+            status: 'clean',
+            signalCount,
+            uniqueSources,
+            baselineDaysObserved: maxBaselineDays,
+        };
+    }
+    // Per-source z-score check.
+    const flaggedSources = [];
+    for (const [src, windowCount] of perSourceWindowCounts) {
+        const samples = perSourceBaselines[src] ?? [];
+        if (samples.length < config.baselineDays)
+            continue; // skip cold per-source
+        const stats = computeBaselineStat(samples);
+        const zScore = computeZScore(windowCount, stats);
+        if (zScore > config.zScoreThreshold) {
+            flaggedSources.push({
+                sourceId: src,
+                zScore,
+                windowCount,
+                baselineMean: stats.mean,
+                baselineStddev: stats.stddev,
+                baselineDays: stats.sampleCount,
+            });
+        }
+    }
+    if (flaggedSources.length === 0) {
+        return {
+            status: 'clean',
+            signalCount,
+            uniqueSources,
+            baselineDaysObserved: maxBaselineDays,
+        };
+    }
+    // Build Decision + apply quarantine.
+    const decisionId = generateDecisionId();
+    const detectedAt = asOf.toISOString();
+    const quarantinedSourceIds = [];
+    const quarantineDurationHours = quarantineConfig.enabled ? quarantineConfig.durationHours : 0;
+    if (quarantineConfig.enabled) {
+        const expiresAt = new Date(asOf.getTime() + quarantineDurationHours * 60 * 60 * 1000);
+        for (const flag of flaggedSources) {
+            quarantinedSourceIds.push(flag.sourceId);
+            const sourceSignals = perSourceWindowSignals.get(flag.sourceId) ?? [];
+            if (options.quarantineStore !== undefined) {
+                for (const sig of sourceSignals) {
+                    options.quarantineStore.quarantine({
+                        sourceId: sig.sourceId,
+                        adapterSource: flag.sourceId,
+                        decisionId,
+                        quarantinedAt: asOf,
+                        expiresAt,
+                        reason: `z-score ${flag.zScore.toFixed(2)}σ (baseline mean=${flag.baselineMean.toFixed(2)}, stddev=${flag.baselineStddev.toFixed(2)})`,
+                    });
+                }
+            }
+        }
+    }
+    const decision = {
+        type: 'Decision',
+        decision: 'signal-flooding-detected',
+        decisionId,
+        detectedAt,
+        signalCount,
+        uniqueSources,
+        flaggedSources,
+        quarantinedSourceIds,
+        quarantineDurationHours,
+        message: floodingMessage(flaggedSources, signalCount, uniqueSources, quarantineDurationHours),
+    };
+    return {
+        status: 'flooded',
+        decision,
+        signalCount,
+        uniqueSources,
+        baselineDaysObserved: maxBaselineDays,
+    };
+}
+/**
+ * Population-standard-deviation baseline stat. Exposed for unit testing.
+ * Returns `{mean: 0, stddev: 0, sampleCount: 0}` on empty input — caller's
+ * cold-start gate should prevent that from reaching `computeZScore()`.
+ */
+export function computeBaselineStat(samples) {
+    if (samples.length === 0)
+        return { mean: 0, stddev: 0, sampleCount: 0 };
+    const sum = samples.reduce((acc, n) => acc + n, 0);
+    const mean = sum / samples.length;
+    const sqSum = samples.reduce((acc, n) => acc + (n - mean) ** 2, 0);
+    const stddev = Math.sqrt(sqSum / samples.length);
+    return { mean, stddev, sampleCount: samples.length };
+}
+/**
+ * Z-score of a single observation against `BaselineStat`. When `stddev === 0`
+ * (degenerate baseline — every sample identical), returns `+Infinity` if the
+ * observation exceeds the mean, `0` if it equals the mean — matches the
+ * statistical convention that any deviation from a zero-variance baseline is
+ * infinitely surprising. Exposed for unit testing.
+ */
+export function computeZScore(observation, stats) {
+    if (stats.stddev === 0) {
+        if (observation > stats.mean)
+            return Number.POSITIVE_INFINITY;
+        return 0;
+    }
+    return (observation - stats.mean) / stats.stddev;
+}
+function floodingMessage(flaggedSources, signalCount, uniqueSources, quarantineDurationHours) {
+    const flaggedNames = flaggedSources.map((f) => `${f.sourceId} (z=${f.zScore.toFixed(2)}σ)`);
+    const quarantinePart = quarantineDurationHours > 0
+        ? ` Quarantine applied for ${quarantineDurationHours}h.`
+        : ' Quarantine disabled — signals stay live.';
+    return (`Flooding detected: ${signalCount} signals over ${uniqueSources} sources in the detection window; ` +
+        `flagged sources [${flaggedNames.join(', ')}].${quarantinePart}`);
+}
+/**
+ * Resolve a source identifier for a signal — prefers `metadata.adapterName`,
+ * falls back to a `sourceId` prefix (the segment before the first `-`).
+ */
+function resolveSourceName(signal) {
+    const fromMeta = signal.metadata?.['adapterName'];
+    if (typeof fromMeta === 'string' && fromMeta.length > 0)
+        return fromMeta;
+    const dashIdx = signal.sourceId.indexOf('-');
+    if (dashIdx > 0)
+        return signal.sourceId.slice(0, dashIdx);
+    return signal.sourceId;
+}
+function defaultDecisionIdFactory(asOf) {
+    let counter = 0;
+    return () => {
+        counter += 1;
+        const suffix = counter > 1 ? `-${counter}` : '';
+        return `flooding-${asOf.toISOString().replace(/[:.]/g, '')}${suffix}`;
+    };
+}
+/**
+ * Default in-memory store. Tests use this directly; production callers should
+ * implement a persistent variant satisfying the same interface.
+ */
+export class InMemoryQuarantineStore {
+    entries = [];
+    released = new Set();
+    quarantine(entry) {
+        this.entries.push(entry);
+    }
+    isQuarantined(sourceId, asOf = new Date()) {
+        const ms = asOf.getTime();
+        for (const e of this.entries) {
+            if (e.sourceId !== sourceId)
+                continue;
+            if (this.released.has(e.decisionId))
+                continue;
+            if (e.expiresAt.getTime() <= ms)
+                continue;
+            return true;
+        }
+        return false;
+    }
+    getActiveEntries(asOf = new Date()) {
+        const ms = asOf.getTime();
+        return this.entries.filter((e) => !this.released.has(e.decisionId) && e.expiresAt.getTime() > ms);
+    }
+    getEntryByDecisionId(decisionId) {
+        return this.entries.filter((e) => e.decisionId === decisionId);
+    }
+    release(decisionId, _releasedAt = new Date()) {
+        const matched = this.getEntryByDecisionId(decisionId);
+        if (matched.length === 0)
+            return [];
+        this.released.add(decisionId);
+        return matched;
+    }
+}
+/**
+ * Convenience: check whether a single `RawSignal` is currently quarantined by
+ * looking up its `sourceId` in the store. The D1 path calls this when
+ * computing `eligibleForD1` — quarantined signals are excluded from the
+ * D1(cluster) formula per AC #6.
+ *
+ * Returns `false` when no store is supplied (back-compat — pre-AISDLC-433
+ * D1 paths didn't have a quarantine layer to consult).
+ */
+export function isSignalQuarantined(signal, store, asOf = new Date()) {
+    if (store === undefined)
+        return false;
+    return store.isQuarantined(signal.sourceId, asOf);
+}
+/**
+ * Operator one-click unquarantine — releases every signal entry tagged with
+ * `originalDecisionId` and emits the `signal-flooding-false-positive`
+ * Decision per RFC-0030 §13.5 + AC #8 + AC #9.
+ *
+ * Returns `null` when no active entries match the Decision ID (idempotent —
+ * the operator's second click on the same row is a no-op + null result).
+ */
+export function unquarantineFlooded(options) {
+    const asOf = options.asOf ?? new Date();
+    const generateDecisionId = options.generateDecisionId ?? falsePositiveDecisionIdFactory(asOf, options.originalDecisionId);
+    const released = options.store.release(options.originalDecisionId, asOf);
+    if (released.length === 0)
+        return null;
+    const releasedSourceIds = Array.from(new Set(released.map((e) => e.sourceId)));
+    const decisionId = generateDecisionId();
+    return {
+        type: 'Decision',
+        decision: 'signal-flooding-false-positive',
+        decisionId,
+        originalDecisionId: options.originalDecisionId,
+        releasedAt: asOf.toISOString(),
+        releasedSourceIds,
+        operatorNote: options.operatorNote,
+        message: `Operator marked flooding Decision ${options.originalDecisionId} as false-positive; ` +
+            `released ${releasedSourceIds.length} source(s) back to D1 candidacy. ` +
+            `v2 reputation-weighting layer will use this Decision as calibration signal.`,
+    };
+}
+function falsePositiveDecisionIdFactory(asOf, originalDecisionId) {
+    return () => `flooding-fp-${asOf.toISOString().replace(/[:.]/g, '')}-${originalDecisionId.slice(-8)}`;
+}
+/**
+ * Check a single signal against the adopter's declared residency regimes.
+ *
+ * **Behaviour**:
+ *   - When `declaration.regimes` is empty → signal is permitted (no regime
+ *     constraints declared). Adopters not declaring a regime are not subject
+ *     to residency gating.
+ *   - When `signal.region` is `undefined` AND at least one regime is active →
+ *     signal is permitted (the adapter didn't surface region metadata, which
+ *     is treated as "not subject to gating" rather than "fails the gate" to
+ *     avoid false-positives on adapters that don't yet plumb region — a
+ *     visible-gap metric for the operator's regime config rollout).
+ *   - When `signal.region` is present AND at least one active regime's
+ *     `allowedRegions` does NOT include it → signal is REFUSED and the
+ *     `Decision` records every regime that rejected the signal.
+ *
+ * The adapter SHOULD NOT call `fetchSignals` for refused signals — the
+ * return-value pattern lets the adapter short-circuit per-signal.
+ */
+export function checkSignalResidency(signal, declaration, adapterName) {
+    if (declaration.regimes.length === 0)
+        return { permitted: true };
+    if (signal.region === undefined)
+        return { permitted: true };
+    const region = signal.region.toLowerCase();
+    const violatedRegimes = [];
+    const allowedAcrossAllRegimes = new Set();
+    for (const regime of declaration.regimes) {
+        const allowed = declaration.allowedRegionsByRegime[regime] ?? [];
+        if (allowed.length === 0) {
+            // Active regime with no allowed regions = all signals violate.
+            violatedRegimes.push(regime);
+            continue;
+        }
+        const allowedLower = allowed.map((r) => r.toLowerCase());
+        for (const r of allowedLower)
+            allowedAcrossAllRegimes.add(r);
+        if (!allowedLower.includes(region)) {
+            violatedRegimes.push(regime);
+        }
+    }
+    if (violatedRegimes.length === 0)
+        return { permitted: true };
+    return {
+        permitted: false,
+        decision: {
+            type: 'Decision',
+            decision: 'signal-residency-violation',
+            adapter: adapterName,
+            sourceId: signal.sourceId,
+            signalRegion: signal.region,
+            violatedRegimes,
+            allowedRegions: Array.from(allowedAcrossAllRegimes).sort(),
+            message: `Signal ${signal.sourceId} from adapter '${adapterName}' has region '${signal.region}' ` +
+                `which violates the residency constraint(s) of active regime(s) [${violatedRegimes.join(', ')}]; ` +
+                `signal refused. Emit clarification task to update compliance.yaml regimeOverrides if ` +
+                `the regime declaration is incorrect, or drop the source if non-compliant.`,
+        },
+    };
+}
+/**
+ * Convenience wrapper: filter a batch of signals against the residency gate,
+ * returning the (possibly empty) list of permitted signals + the list of
+ * Decision records for refused signals. Adapter implementations can call this
+ * in their `fetchSignals()` body to enforce residency before returning.
+ */
+export function filterSignalsByResidency(signals, declaration, adapterName) {
+    const permitted = [];
+    const decisions = [];
+    for (const s of signals) {
+        const result = checkSignalResidency(s, declaration, adapterName);
+        if (result.permitted) {
+            permitted.push(s);
+        }
+        else {
+            decisions.push(result.decision);
+        }
+    }
+    return { permitted, decisions };
+}
+//# sourceMappingURL=significance.js.map