@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/signal-ingestion/significance.d.ts

@@ -0,0 +1,554 @@
+/**
+ * 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 type { DemandCluster } from './clustering.js';
+import type { FloodingDetectionConfig, FloodingQuarantineConfig, SignalIngestionConfig, Tier2SignificanceThreshold, SaResonanceThresholds } from './config.js';
+import type { RawSignal, SignalResidencyViolationDecision, SignalSourceName } from './types.js';
+/**
+ * Outcome of running the Tier 2 significance gate on a single cluster.
+ *   - `qualified`  — meets all four threshold conditions; eligible for D1.
+ *   - `monitored`  — at least one condition unmet; cluster persisted but
+ *                    does NOT feed D1 (RFC-0030 §8).
+ */
+export type Tier2SignificanceState = 'qualified' | 'monitored';
+/**
+ * Which threshold conditions failed, when the cluster is `monitored`.
+ * `[]` when the cluster is `qualified`.
+ */
+export interface Tier2SignificanceReasons {
+    signalCount: boolean;
+    uniqueSources: boolean;
+    tier1SignalCount: boolean;
+    clusterAgeDays: boolean;
+}
+/**
+ * Per RFC-0030 §9: cluster SA resonance bucket. The bucket directly determines
+ * the D1 weight multiplier (see `SA_WEIGHT_MULTIPLIERS`).
+ *
+ *   - `full`           — `saResonance >= fullWeight` (default 0.7). Full D1 weight.
+ *   - `discounted`     — `>= discounted` (default 0.4) and `< fullWeight`.
+ *                        D1 weight × 0.7.
+ *   - `low-sa-review`  — `> excluded` (default 0.0, exclusive) and `< discounted`.
+ *                        D1 weight × 0.3 + logged via Decision for Product Lead
+ *                        batch review (AC #3).
+ *   - `out-of-scope`   — `<= excluded` (default 0.0). Excluded from D1; logged
+ *                        as out-of-scope demand for separate triage.
+ *   - `pending`        — `cluster.saResonance` is `undefined` (Phase 3 default).
+ *                        Caller must populate `saResonance` before invoking
+ *                        the filter (typically via the Soul DID adapter); the
+ *                        bucket reports `pending` and the cluster is excluded
+ *                        from D1 by default (fail-closed).
+ */
+export type SaResonanceBucket = 'full' | 'discounted' | 'low-sa-review' | 'out-of-scope' | 'pending';
+/** Per-bucket D1 weight multiplier per RFC-0030 §9. */
+export declare const SA_WEIGHT_MULTIPLIERS: Readonly<Record<SaResonanceBucket, number>>;
+/**
+ * A `DemandCluster` annotated with its Phase 4 verdict on significance + SA.
+ * The augmented record is what downstream Phase 5 D1 reformulation consumes.
+ *
+ * `eligibleForD1` is `true` IFF the cluster `qualified` for the significance
+ * threshold AND its SA bucket is NOT `out-of-scope` / `pending`.
+ *
+ * `d1WeightMultiplier` is the combined product of:
+ *   - significance flag (qualified → 1.0, monitored → 0.0)
+ *   - SA bucket multiplier (per SA_WEIGHT_MULTIPLIERS)
+ * Downstream Phase 5 multiplies this against the existing `baseWeight ×
+ * tierMultiplier × icpResonanceWeight × recencyDecay` chain.
+ */
+export interface SignificanceAssessedCluster {
+    cluster: DemandCluster;
+    tier2Significance: Tier2SignificanceState;
+    tier2Reasons: Tier2SignificanceReasons;
+    saResonanceBucket: SaResonanceBucket;
+    eligibleForD1: boolean;
+    d1WeightMultiplier: number;
+}
+/**
+ * Emitted when a cluster's SA resonance bucket is `low-sa-review` per AC #3 —
+ * the demand is real but adjacent-to-soul, and Product Lead should review it
+ * (NOT silently dropped). Routes via the RFC-0035 G0 catalog.
+ */
+export interface SignalLowSaForReviewDecision {
+    type: 'Decision';
+    decision: 'signal-low-sa-for-review';
+    clusterId: string;
+    saResonance: number;
+    signalCount: number;
+    message: string;
+}
+/**
+ * Emitted when the SA bucket is `out-of-scope` (saResonance <= excluded
+ * threshold, default 0.0). Per RFC-0030 §9 the demand is logged for separate
+ * triage rather than fed into D1. Distinct from `low-sa-review` so operators
+ * can prioritise reviewing soul-adjacent demand over fully-out-of-scope
+ * demand.
+ */
+export interface SignalOutOfScopeDecision {
+    type: 'Decision';
+    decision: 'signal-out-of-scope';
+    clusterId: string;
+    saResonance: number;
+    signalCount: number;
+    message: string;
+}
+/**
+ * Detection status returned by `detectFlooding()`.
+ *   - `flooded`     — the trigger condition fired; a Decision was emitted.
+ *   - `clean`       — detector ran, baseline sufficient, no trigger.
+ *   - `calibrating` — rolling baseline has <`baselineDays` of history; no
+ *                     Decisions emitted (Tier 2 significance is sole defense
+ *                     during calibration). Per AC #4.
+ *   - `empty-window`— the detection window contains zero signals.
+ */
+export type FloodingDetectionStatus = 'flooded' | 'clean' | 'calibrating' | 'empty-window';
+/**
+ * Z-score detector output for one detection window.
+ *
+ * `status` describes the outcome (cold-start / clean / flooded / empty).
+ * `decision` is populated iff `status === 'flooded'`; it's the Decision the
+ * caller routes to the RFC-0035 catalog.
+ */
+export interface FloodingDetectionResult {
+    status: FloodingDetectionStatus;
+    /** Populated when `status === 'flooded'`. */
+    decision?: SignalFloodingDetectedDecision;
+    /** Number of signals in the detection window. */
+    signalCount: number;
+    /** Distinct sources in the detection window. */
+    uniqueSources: number;
+    /** Days of baseline data the detector had access to. */
+    baselineDaysObserved: number;
+}
+/**
+ * Per-source baseline samples. Each entry is the daily signal-count
+ * observation for that source over the rolling baseline window. The detector
+ * computes `{mean, stddev}` from the samples.
+ *
+ * Operators wire this map from their historical-data substrate; persistence
+ * is the caller's responsibility (orchestrator events.jsonl roll-up, etc.).
+ * AISDLC-433 ships the detection algorithm; the substrate plumbing is the
+ * caller's domain.
+ */
+export type PerSourceBaseline = Record<string, number[]>;
+/**
+ * Per-source baseline statistic. Internal — exposed for unit testing.
+ */
+export interface BaselineStat {
+    /** Mean of the samples. */
+    mean: number;
+    /** Population standard deviation of the samples. */
+    stddev: number;
+    /** Number of samples (days observed). */
+    sampleCount: number;
+}
+/**
+ * Source-level flooding flag — surfaces in the Decision so the operator
+ * sees which source tripped the trigger.
+ */
+export interface FloodingSourceFlag {
+    /** Source identifier (adapter name when available, falls back to sourceId prefix). */
+    sourceId: string;
+    /** Z-score for this source's window count vs its baseline. */
+    zScore: number;
+    /** Window signal count. */
+    windowCount: number;
+    /** Baseline mean signals/day. */
+    baselineMean: number;
+    /** Baseline standard deviation signals/day. */
+    baselineStddev: number;
+    /** Days of baseline data observed for this source. */
+    baselineDays: number;
+}
+/**
+ * Decision emitted when the z-score detector trips per RFC-0030 §13.5
+ * (AISDLC-433 v0.3 refinement). Replaces the legacy multi-indicator Decision.
+ */
+export interface SignalFloodingDetectedDecision {
+    type: 'Decision';
+    decision: 'signal-flooding-detected';
+    /** Stable Decision ID — the operator unquarantine path references this. */
+    decisionId: string;
+    /** Detection-window cutoff used when this Decision was emitted. */
+    detectedAt: string;
+    /** Total signal count in the detection window. */
+    signalCount: number;
+    /** Number of distinct sources contributing to the window. */
+    uniqueSources: number;
+    /** Per-source z-scores + baseline stats for sources that exceeded threshold. */
+    flaggedSources: FloodingSourceFlag[];
+    /** Source IDs of signals quarantined as a result of this Decision (empty when quarantine disabled). */
+    quarantinedSourceIds: string[];
+    /** Quarantine duration applied (hours; 0 when disabled). */
+    quarantineDurationHours: number;
+    message: string;
+}
+/**
+ * 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 declare const DEFAULT_FLOODING_DETECTION_CONFIG: FloodingDetectionConfig;
+/**
+ * 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 declare function assessTier2Significance(cluster: DemandCluster, threshold?: Tier2SignificanceThreshold, asOf?: Date): {
+    state: Tier2SignificanceState;
+    reasons: Tier2SignificanceReasons;
+};
+/**
+ * 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 declare function classifySaResonance(cluster: DemandCluster, thresholds?: SaResonanceThresholds): SaResonanceBucket;
+/**
+ * Options for `assessClusterSignificance()`.
+ */
+export interface AssessClusterSignificanceOptions {
+    config?: SignalIngestionConfig;
+    asOf?: Date;
+}
+/**
+ * Result returned by `assessClusterSignificance()`.
+ */
+export interface AssessClusterSignificanceResult {
+    assessments: SignificanceAssessedCluster[];
+    /**
+     * `signal-low-sa-for-review` Decisions emitted for clusters whose SA bucket
+     * is `low-sa-review` — surfaces low-SA demand to the catalog for Product
+     * Lead batch review (AC #3).
+     */
+    lowSaDecisions: SignalLowSaForReviewDecision[];
+    /**
+     * `signal-out-of-scope` Decisions emitted for clusters whose SA bucket is
+     * `out-of-scope` — the demand is logged for separate triage rather than
+     * fed into D1.
+     */
+    outOfScopeDecisions: SignalOutOfScopeDecision[];
+}
+/**
+ * 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 declare function assessClusterSignificance(clusters: DemandCluster[], options?: AssessClusterSignificanceOptions): AssessClusterSignificanceResult;
+/**
+ * Options for `detectFlooding()`. The z-score detector REPLACES the
+ * multiplier-based path that shipped with AISDLC-346.
+ */
+export interface DetectFloodingOptions {
+    /**
+     * Detection thresholds. Defaults to the loaded config's `flooding.detection`
+     * block (or `DEFAULT_FLOODING_DETECTION_CONFIG` when no config supplied).
+     */
+    config?: FloodingDetectionConfig;
+    /**
+     * Quarantine sub-config. When omitted defaults to the framework default
+     * (`enabled: true`, `durationHours: 24`). Used to populate the Decision's
+     * `quarantineDurationHours` field + the `QuarantineStore` entries.
+     */
+    quarantineConfig?: FloodingQuarantineConfig;
+    /**
+     * Per-source rolling baseline. Each entry is a list of daily signal-count
+     * observations for that source over the rolling `baselineDays` window.
+     * The detector computes `{mean, stddev}` from the samples.
+     *
+     * Source key resolution (matches the pre-AISDLC-433 contract): prefers
+     * `metadata.adapterName`, falls back to the `sourceId` prefix before the
+     * first `-`.
+     */
+    perSourceBaselines?: PerSourceBaseline;
+    /** Detection-window cutoff. Defaults to `new Date()`. */
+    asOf?: Date;
+    /**
+     * Optional quarantine store the detector writes to. When supplied, every
+     * flooded source has its signals tagged in the store. When omitted, the
+     * Decision still carries the `quarantinedSourceIds` list but no
+     * persistence happens — useful for pure unit testing.
+     */
+    quarantineStore?: QuarantineStore;
+    /**
+     * Decision ID factory. Defaults to a UTC timestamp + 8-char random suffix.
+     * Tests override this to make assertions deterministic.
+     */
+    generateDecisionId?: () => string;
+}
+/**
+ * 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 declare function detectFlooding(signals: RawSignal[], options?: DetectFloodingOptions): FloodingDetectionResult;
+/**
+ * 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 declare function computeBaselineStat(samples: readonly number[]): BaselineStat;
+/**
+ * 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 declare function computeZScore(observation: number, stats: BaselineStat): number;
+/**
+ * A single entry in the quarantine store. Created by `detectFlooding()` when
+ * a flooded source's signals are quarantined; consumed by:
+ *   - The D1 path, to exclude quarantined signals from cluster scoring
+ *     (`isSignalQuarantined()`).
+ *   - The operator unquarantine flow (`unquarantineFlooded()`) for one-click
+ *     release after a false-positive review.
+ *   - The RFC-0023 Blockers pane, which renders pending Decisions + offers
+ *     the unquarantine action.
+ */
+export interface QuarantineEntry {
+    /** Signal `sourceId` quarantined. */
+    sourceId: string;
+    /** Adapter-level source key (the key used by the detector + baselines). */
+    adapterSource: string;
+    /** Originating Decision ID. The false-positive Decision references this. */
+    decisionId: string;
+    quarantinedAt: Date;
+    /** When quarantine auto-expires. */
+    expiresAt: Date;
+    /** Free-form rationale (z-score + baseline stats). */
+    reason: string;
+}
+/**
+ * Minimal in-memory `QuarantineStore` implementation. Production deployments
+ * persist to events.jsonl + a sidecar quarantine state file; the in-memory
+ * shape is the contract the persistent implementation honours.
+ *
+ * The store is intentionally narrow: `quarantine`, `isQuarantined`,
+ * `getActiveEntries`, `getEntryByDecisionId`, `release`. No batch
+ * operations — operators unquarantine one Decision at a time per the
+ * RFC-0023 one-click model.
+ */
+export interface QuarantineStore {
+    /** Record a new quarantine entry. */
+    quarantine(entry: QuarantineEntry): void;
+    /** Whether a signal sourceId is currently quarantined (NOT auto-expired). */
+    isQuarantined(sourceId: string, asOf?: Date): boolean;
+    /**
+     * All currently-active quarantine entries (auto-expired entries excluded).
+     * Used by the TUI Blockers pane to render pending decisions.
+     */
+    getActiveEntries(asOf?: Date): QuarantineEntry[];
+    /** Entries created by a specific Decision (for unquarantine routing). */
+    getEntryByDecisionId(decisionId: string): QuarantineEntry[];
+    /** Release all entries for the given Decision (idempotent). */
+    release(decisionId: string, releasedAt?: Date): QuarantineEntry[];
+}
+/**
+ * Default in-memory store. Tests use this directly; production callers should
+ * implement a persistent variant satisfying the same interface.
+ */
+export declare class InMemoryQuarantineStore implements QuarantineStore {
+    private readonly entries;
+    private readonly released;
+    quarantine(entry: QuarantineEntry): void;
+    isQuarantined(sourceId: string, asOf?: Date): boolean;
+    getActiveEntries(asOf?: Date): QuarantineEntry[];
+    getEntryByDecisionId(decisionId: string): QuarantineEntry[];
+    release(decisionId: string, _releasedAt?: Date): QuarantineEntry[];
+}
+/**
+ * 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 declare function isSignalQuarantined(signal: RawSignal, store: QuarantineStore | undefined, asOf?: Date): boolean;
+/**
+ * Operator unquarantine Decision — emitted by `unquarantineFlooded()` per
+ * AC #9. References the original flooding Decision so the v2
+ * reputation-weighting layer can calibrate against false-positive feedback.
+ */
+export interface SignalFloodingFalsePositiveDecision {
+    type: 'Decision';
+    decision: 'signal-flooding-false-positive';
+    /** Stable ID for this false-positive Decision (audit trail). */
+    decisionId: string;
+    /** Original `signal-flooding-detected` Decision ID. */
+    originalDecisionId: string;
+    releasedAt: string;
+    /** Source IDs released back to D1 candidacy. */
+    releasedSourceIds: string[];
+    /** Free-form operator note explaining the false-positive call. */
+    operatorNote?: string;
+    message: string;
+}
+/**
+ * Options for `unquarantineFlooded()`.
+ */
+export interface UnquarantineFloodedOptions {
+    store: QuarantineStore;
+    /** Decision ID of the original `signal-flooding-detected` Decision. */
+    originalDecisionId: string;
+    /** Optional operator note (free-form rationale). */
+    operatorNote?: string;
+    /** Clock override for the `releasedAt` timestamp. */
+    asOf?: Date;
+    /** Decision-ID factory for the false-positive Decision (tests override). */
+    generateDecisionId?: () => string;
+}
+/**
+ * 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 declare function unquarantineFlooded(options: UnquarantineFloodedOptions): SignalFloodingFalsePositiveDecision | null;
+/**
+ * Per-adopter regime declaration consumed by `checkSignalResidency`. Composes
+ * with RFC-0022 Compliance Posture per RFC-0030 OQ-13.3 — the adopter declares
+ * which regimes are active and the allowed regions per regime; signal-ingestion
+ * refuses signals from outside those regions.
+ *
+ * `regimes` is the active regime set (e.g. `['gdpr']`, `['hipaa', 'gdpr']`).
+ * `allowedRegionsByRegime` maps each regime to the set of region tags that
+ * regime permits (e.g. `gdpr: ['eu', 'gb']`, `hipaa: ['us']`). A signal is
+ * permitted IFF its `region` is in EVERY active regime's allowed-regions list.
+ *
+ * `allowedRegionsByRegime` keys not present in `regimes` are ignored (the
+ * regime isn't active for this adopter).
+ *
+ * `allowedRegionsByRegime` of `{}` (empty) for an active regime means NO
+ * regions are explicitly permitted → all signals are refused for that regime.
+ * Operators should declare regions OR remove the regime from the active set.
+ */
+export interface ResidencyRegimeDeclaration {
+    regimes: string[];
+    allowedRegionsByRegime: Record<string, string[]>;
+}
+/**
+ * Outcome of residency-check on a single signal.
+ *   - `{ permitted: true }` — signal MAY pass; adapter may emit it.
+ *   - `{ permitted: false, decision }` — signal MUST be refused; adapter logs
+ *     the Decision + emits the regimeOverrides clarification task.
+ */
+export type SignalResidencyCheck = {
+    permitted: true;
+} | {
+    permitted: false;
+    decision: SignalResidencyViolationDecision;
+};
+/**
+ * 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 declare function checkSignalResidency(signal: RawSignal, declaration: ResidencyRegimeDeclaration, adapterName: SignalSourceName): SignalResidencyCheck;
+/**
+ * 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 declare function filterSignalsByResidency(signals: RawSignal[], declaration: ResidencyRegimeDeclaration, adapterName: SignalSourceName): {
+    permitted: RawSignal[];
+    decisions: SignalResidencyViolationDecision[];
+};
+//# sourceMappingURL=significance.d.ts.map