@ai-sdlc/orchestrator 0.10.0 → 0.14.0

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

@@ -0,0 +1,351 @@
+/**
+ * Signal ingestion configuration loader for RFC-0030 Phase 2.
+ *
+ * Reads `.ai-sdlc/signal-ingestion.yaml`, validates its shape, and returns a
+ * fully-resolved `SignalIngestionConfig` with all defaults applied.
+ *
+ * Design decisions:
+ *  - Missing file → returns the default config (pipeline is disabled by default).
+ *  - Invalid YAML or schema mismatch → throws `SignalIngestionConfigError`.
+ *  - All numeric fields are validated to be non-negative finite numbers.
+ *  - `acceptedLanguages` defaults to `['en']` per RFC-0030 OQ-13.2 resolution.
+ *  - Tier multipliers and ICP resonance weights are read from the config; the
+ *    defaults match RFC-0030 §11.
+ *  - `flooding` block (RFC-0030 OQ-13.5 v0.3 re-walkthrough refinement,
+ *    AISDLC-433) replaces the legacy `sourceBaselineDriftMultiplier` knob
+ *    with a z-score detector on per-source rolling 7d baseline + quarantine.
+ *    The legacy `flooding.detection.sourceBaselineDriftMultiplier` field at
+ *    the LOADER level emits a `signal-ingestion-config-deprecated-field`
+ *    Decision; the loader translates it to the closest z-score equivalent
+ *    for one release window then hard-errors after the soak.
+ */
+export declare const DEFAULT_SIGNAL_INGESTION_CONFIG_PATH = ".ai-sdlc/signal-ingestion.yaml";
+/** Tier multipliers keyed by CustomerTier. All values must be non-negative. */
+export interface TierMultipliers {
+    enterprise: number;
+    mid: number;
+    smb: number;
+    free: number;
+    churned: number;
+}
+/** ICP resonance weights keyed by ICPResonance level. All values must be non-negative. */
+export interface IcpResonanceWeights {
+    strong: number;
+    partial: number;
+    weak: number;
+}
+/** Tier 2 significance threshold parameters. */
+export interface Tier2SignificanceThreshold {
+    /** Minimum number of signals in the cluster to qualify. */
+    minSignalCount: number;
+    /** Minimum number of distinct sources in the cluster. */
+    minUniqueSources: number;
+    /** Minimum number of Tier 1 signals required in the cluster. */
+    minTier1SignalCount: number;
+    /** Minimum cluster age in days. */
+    minClusterAgeDays: number;
+}
+/** SA resonance threshold configuration for D1 weight bands. */
+export interface SaResonanceThresholds {
+    /** Clusters at or above this score receive full weight. */
+    fullWeight: number;
+    /** Clusters at or above this score (but below fullWeight) receive discounted weight. */
+    discounted: number;
+    /** Clusters at or above this score (but below discounted) are flagged for review. */
+    excluded: number;
+}
+/** Clustering algorithm and parameters. */
+export interface ClusteringConfig {
+    algorithm: 'bm25' | 'embedding';
+    similarityThreshold: number;
+}
+/**
+ * Language-detection configuration (RFC-0030 OQ-13.2 re-walkthrough v0.3).
+ *
+ * v0.3 adds explicit `franc` library specification + behaviour controls.
+ * The previous v0.2 implementation used a script-block heuristic that
+ * conflated "non-Latin script" with "non-English", causing false drops on
+ * legitimate English payloads containing CJK identifiers (e.g. office names)
+ * and false accepts on legitimate French / Spanish / German payloads
+ * (Latin script but not English). `franc` is deterministic, MIT-licensed,
+ * JS-native, runs in <10ms per signal on text >50 chars at 95%+ accuracy.
+ */
+export interface LanguageDetectionConfig {
+    /**
+     * Detection library identifier. Currently always `'franc'` — the field
+     * exists as a forward-compat hook for swapping the detector (e.g. LLM-based
+     * detection in v2). Configuring `'none'` disables the gate entirely,
+     * useful for testing or for adopters that pre-filter signals upstream.
+     */
+    library: 'franc' | 'none';
+    /**
+     * Minimum character count below which `franc` returns 'und' (undetermined).
+     * Below this length, signals are accepted without language gating to avoid
+     * dropping legitimate short payloads (e.g. "Bug: crash on save" — 18 chars).
+     * Default 50 — the practical lower bound for franc accuracy.
+     */
+    minDetectionLength: number;
+    /**
+     * Behaviour when franc returns 'und' (text too short OR no script matched).
+     * `'accept'` (default) is conservative — pass through to the rest of the
+     * pipeline since short payloads + ambiguous scripts have low false-positive
+     * risk. `'drop'` is strict — drop and log as `signal-language-unsupported`.
+     */
+    onUndetermined: 'accept' | 'drop';
+}
+/**
+ * Phase 5 — non-replacement weighting between signal-pipeline-derived demand
+ * and human-authored backlog-item demand when both feed D1 (RFC-0030 §10).
+ *
+ * **Backward compat (AC #4)**: when `enabled: false` at the top level, only
+ * `backlogItemWeight` is in effect — `signalPipelineWeight` is irrelevant
+ * because no pipeline-derived demand exists. When `enabled: true`, both
+ * weights blend the two demand streams; default 50/50 keeps neither stream
+ * dominant out of the box.
+ *
+ * The weights are normalised to sum to 1 inside `composeD1Inputs()` so any
+ * positive pair is meaningful (e.g. `{1, 3}` becomes `{0.25, 0.75}`).
+ */
+export interface D1CompositionWeights {
+    /**
+     * Weight applied to the signal-pipeline-derived (cluster-aggregate) D1
+     * input. Default 0.5 — even blend with backlog-derived demand.
+     */
+    signalPipelineWeight: number;
+    /**
+     * Weight applied to the human-authored backlog-item demand input.
+     * Default 0.5 — even blend with signal-pipeline demand.
+     */
+    backlogItemWeight: number;
+}
+/**
+ * Per-stage residency enforcement toggles per RFC-0030 v0.3 OQ-13.3
+ * re-walkthrough. Each flag corresponds to an enforcement point in the
+ * pipeline:
+ *
+ *   - `fetchSignals`: adapter-level signal tag check against allowed regions
+ *     (already implemented via `checkSignalResidency`).
+ *   - `clustering`: partition signals by residencyRegion before similarity
+ *     computation; cross-region cluster merge is structurally impossible.
+ *   - `storage`: persist `residencyRegion` field on every stored record;
+ *     cross-region reads emit elevated audit-log entries.
+ *   - `unifiedCostReport`: group cost attribution rows by region so per-region
+ *     totals are visible in the unified cost report.
+ *
+ * `multiPostureBehavior` controls how the pipeline composes multiple regimes
+ * declared by the adopter. `'union'` is the v0.3 default — UNION of regime
+ * constraints, strictest applies (when an adopter declares HIPAA AND GDPR,
+ * a signal must satisfy BOTH regimes' allowed-region constraints).
+ *
+ * Defaults match RFC-0030 §11 v0.3 (all enforcement points ON; multi-posture
+ * = UNION).
+ */
+export interface ResidencyEnforcementConfig {
+    sourceFromCompliancePosture: boolean;
+    enforcementPoints: {
+        fetchSignals: boolean;
+        clustering: boolean;
+        storage: boolean;
+        unifiedCostReport: boolean;
+    };
+    multiPostureBehavior: 'union';
+}
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough — manual-entry anti-gaming hardening.
+ *
+ * Layered on top of the shipped audit-trail pattern (RFC-0022 OQ-2: forced
+ * `attestedBy` + auto-filled `attestedAt`):
+ *
+ *  - `dailyCapPerOperator`: per-operator UTC-day rate limit on manual entries
+ *    (default 10/day). Above cap → `Decision: manual-signal-rate-limit-exceeded`.
+ *  - `evidenceUrlOptional`: when `true`, manual signals MAY carry an
+ *    `evidenceUrl` field (call recording URL, ticket URL, transcript link).
+ *    The field is preserved through the pipeline + visible in audit export.
+ *  - `qualityMetric`: rolling manual/total share metric. When the share
+ *    exceeds `shareWarningThreshold` over `windowDays` → `Decision:
+ *    manual-signal-share-elevated` (warning, not block — surfaces
+ *    architectural anti-pattern).
+ */
+export interface ManualEntryQualityMetricConfig {
+    enabled: boolean;
+    windowDays: number;
+    shareWarningThreshold: number;
+}
+export interface ManualEntryConfig {
+    /** Per-operator UTC-day cap. Default 10. Set to `0` to disable. */
+    dailyCapPerOperator: number;
+    /** Whether the optional `evidenceUrl` field on manual signals is accepted. */
+    evidenceUrlOptional: boolean;
+    /** Rolling manual-share quality metric configuration. */
+    qualityMetric: ManualEntryQualityMetricConfig;
+}
+/**
+ * Flooding-detection block (RFC-0030 OQ-13.5 v0.3 re-walkthrough refinement).
+ *
+ * REPLACES the legacy fixed-multiplier detector with z-score on a rolling
+ * per-source baseline. The trigger condition is
+ * `volume_in_window > (baseline_mean + zScoreThreshold × baseline_stddev)
+ *   AND uniqueSources_in_window < minUniqueSourcesForSuspicion`.
+ *
+ * Cold-start handling (per AC #4): when the rolling baseline has fewer than
+ * `baselineDays` of history, the detector returns the special `calibrating`
+ * status and emits NO `signal-flooding-detected` Decision — Tier 2
+ * significance is the sole defense during the calibration window.
+ */
+export interface FloodingDetectionConfig {
+    /** Z-score threshold (σ multiples) above baseline mean. Default 3.0. */
+    zScoreThreshold: number;
+    /** Detection window in minutes. Default 60. */
+    windowMinutes: number;
+    /** `uniqueSources < this` is part of the trigger condition. Default 3. */
+    minUniqueSourcesForSuspicion: number;
+    /** Rolling-baseline window in days. Default 7. */
+    baselineDays: number;
+}
+/**
+ * Quarantine sub-block (RFC-0030 §13.5 v0.3). Quarantined signals are NOT
+ * fed to D1; quarantine auto-expires after `durationHours`. Operators can
+ * unquarantine before expiry via `unquarantineFlooded()`.
+ */
+export interface FloodingQuarantineConfig {
+    /** Master switch. When false, flooding Decisions emit but signals stay live. */
+    enabled: boolean;
+    /** How long quarantine lasts before auto-expiry. Default 24h. */
+    durationHours: number;
+}
+/** Combined flooding config (detection + quarantine). */
+export interface FloodingConfig {
+    detection: FloodingDetectionConfig;
+    quarantine: FloodingQuarantineConfig;
+}
+/** Fully-resolved signal ingestion configuration. */
+export interface SignalIngestionConfig {
+    enabled: boolean;
+    tierMultipliers: TierMultipliers;
+    icpResonanceWeights: IcpResonanceWeights;
+    recencyHalfLifeDays: number;
+    tier2SignificanceThreshold: Tier2SignificanceThreshold;
+    saResonanceThresholds: SaResonanceThresholds;
+    clustering: ClusteringConfig;
+    d1Composition: D1CompositionWeights;
+    adapters: string[];
+    /**
+     * Per-org list of accepted BCP-47 (or ISO 639-1 / 639-3) language tags.
+     * Default: `['en']`.
+     *
+     * Signals whose detected language is NOT in this list are dropped and logged
+     * as `Decision: signal-language-unsupported` (RFC-0030 OQ-13.2 v0.3
+     * resolution). Multi-language opt-in (e.g. `['en', 'fr', 'es']`) accepts
+     * signals in any listed language; adopters take on documented BM25 quality
+     * degradation (~15-30% precision drop without per-language stopwords /
+     * stemming — Robertson & Zaragoza §3.5) in exchange for non-English signal
+     * coverage.
+     *
+     * Tags are normalised to lowercase. The detector returns ISO 639-3
+     * three-letter codes (`'eng'`, `'fra'`, `'spa'`); the config matcher
+     * accepts the common forms (`'en'`, `'eng'`, `'en-US'`) and maps them
+     * to the 639-3 family.
+     */
+    acceptedLanguages: string[];
+    /**
+     * Language-detection runtime config (RFC-0030 §11 v0.3). The default
+     * specifies `franc` per the OQ-13.2 re-walkthrough resolution.
+     */
+    languageDetection: LanguageDetectionConfig;
+    /**
+     * Per-stage residency enforcement configuration per RFC-0030 OQ-13.3
+     * re-walkthrough (v0.3). Defaults to all enforcement points ON with
+     * `multiPostureBehavior: 'union'`.
+     */
+    residencyEnforcement: ResidencyEnforcementConfig;
+    /**
+     * RFC-0030 OQ-13.4 v0.3 — manual-entry anti-gaming config block.
+     */
+    manualEntry: ManualEntryConfig;
+    /**
+     * Flooding-detection + quarantine block (RFC-0030 OQ-13.5 v0.3
+     * re-walkthrough refinement, AISDLC-433). REPLACES the legacy
+     * multiplier-based detector path; the loader emits a
+     * `signal-ingestion-config-deprecated-field` Decision when the legacy
+     * `flooding.detection.sourceBaselineDriftMultiplier` key is still present
+     * AND translates it to the closest z-score equivalent for one release
+     * window (then hard-errors).
+     */
+    flooding: FloodingConfig;
+}
+/**
+ * Decision emitted by the config loader when a deprecated field is still
+ * present in `.ai-sdlc/signal-ingestion.yaml`. Translated to the closest
+ * z-score equivalent for one release window; after the soak, the loader
+ * hard-errors instead of translating (controlled by
+ * `AI_SDLC_SIGNAL_INGESTION_LEGACY_HARD_ERROR=1`).
+ *
+ * Returned alongside the resolved config from
+ * `loadSignalIngestionConfigWithDeprecations()` so the caller can route the
+ * Decision to the catalog without coupling the loader to event emission.
+ */
+export interface SignalIngestionConfigDeprecatedFieldDecision {
+    type: 'Decision';
+    decision: 'signal-ingestion-config-deprecated-field';
+    /** Deprecated field path, e.g. `flooding.detection.sourceBaselineDriftMultiplier`. */
+    field: string;
+    /** What the operator should switch to. */
+    replacement: string;
+    /** Legacy value the loader translated from (for audit). */
+    legacyValue: unknown;
+    /** Z-score equivalent the loader translated to (for audit). */
+    translatedTo: unknown;
+    message: string;
+}
+export declare const DEFAULT_SIGNAL_INGESTION_CONFIG: SignalIngestionConfig;
+export declare class SignalIngestionConfigError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface LoadSignalIngestionConfigOptions {
+    /** Absolute path to the project root. Defaults to `process.cwd()`. */
+    projectRoot?: string;
+    /** Explicit path to the config file. Overrides the default location. */
+    configPath?: string;
+}
+/**
+ * Load and resolve the signal ingestion configuration from
+ * `.ai-sdlc/signal-ingestion.yaml`.
+ *
+ * Returns `DEFAULT_SIGNAL_INGESTION_CONFIG` when the file is absent.
+ * Throws `SignalIngestionConfigError` on parse or validation failure.
+ */
+export declare function loadSignalIngestionConfig(options?: LoadSignalIngestionConfigOptions): SignalIngestionConfig;
+/**
+ * Result of `loadSignalIngestionConfigWithDeprecations()`. `config` is the
+ * fully-resolved config (with any legacy fields already translated to their
+ * z-score equivalents). `deprecations` is the list of
+ * `signal-ingestion-config-deprecated-field` Decisions the caller MUST route
+ * to the RFC-0035 Decision Catalog so the operator sees the deprecation
+ * surface and can migrate.
+ */
+export interface LoadSignalIngestionConfigWithDeprecationsResult {
+    config: SignalIngestionConfig;
+    deprecations: SignalIngestionConfigDeprecatedFieldDecision[];
+}
+/**
+ * Load + resolve config, AND surface every deprecated-field Decision the
+ * loader detected. Wraps `loadSignalIngestionConfig()` so callers that want
+ * the deprecation audit trail can opt in without changing the existing
+ * Pure-load callers (which keep using `loadSignalIngestionConfig`).
+ *
+ * Behaviour:
+ *  - When the legacy `flooding.detection.sourceBaselineDriftMultiplier` key
+ *    is present in the YAML AND `LEGACY_HARD_ERROR_ENV_VAR` is unset, the
+ *    loader translates it to `zScoreThreshold = legacyMultiplier × 0.6` (an
+ *    empirical mapping documented in the operator runbook — a 5× multiplier
+ *    over a per-source baseline corresponds approximately to a 3σ spike on
+ *    most production datasets) and emits one
+ *    `signal-ingestion-config-deprecated-field` Decision.
+ *  - When `LEGACY_HARD_ERROR_ENV_VAR=1`, the loader throws
+ *    `SignalIngestionConfigError` with a migration message.
+ *  - When neither legacy key nor v0.3 z-score key is present, the loader
+ *    fills in defaults silently (no deprecation noise).
+ */
+export declare function loadSignalIngestionConfigWithDeprecations(options?: LoadSignalIngestionConfigOptions): LoadSignalIngestionConfigWithDeprecationsResult;
+//# sourceMappingURL=config.d.ts.map