@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/sa-scoring/did-compiler.d.ts

@@ -0,0 +1,122 @@
+/**
+ * DID compilation pipeline (RFC-0008 Addendum B §B.3.3).
+ *
+ * Consumes a `DesignIntentDocument` and produces six deterministic
+ * artifacts consumed by the three-layer SA scorer:
+ *
+ *   1. scopeLists          — flattened in/out scope synonyms
+ *   2. constraintRules     — detection patterns per soul constraint
+ *   3. antiPatternLists    — product + per-principle + voice + visual
+ *   4. measurableSignals   — principle signals + visual constraints
+ *   5. bm25Corpus          — SA-1 corpus (mission + experientialTargets,
+ *                            core fields weighted 2×, evolving 1×)
+ *   6. principleCorpora    — one SA-2 corpus per designPrinciple
+ *
+ * The output is stable given identical input (canonical JSON + sha256
+ * hash) so `did_compiled_artifacts.source_hash` can be used to detect
+ * DID changes cheaply.
+ */
+import type { Constraint, DesignIntentDocument, IdentityClass, MeasurableOperator } from '@ai-sdlc/reference';
+export interface CompiledScopeEntry {
+    label: string;
+    synonyms: string[];
+    identityClass: IdentityClass;
+}
+export interface CompiledScopeLists {
+    inScope: CompiledScopeEntry[];
+    outOfScope: CompiledScopeEntry[];
+}
+export interface CompiledConstraintRule {
+    id: string;
+    concept: string;
+    relationship: Constraint['relationship'];
+    detectionPatterns: string[];
+    identityClass: IdentityClass;
+}
+export interface CompiledAntiPattern {
+    id: string;
+    label: string;
+    detectionPatterns: string[];
+    identityClass: IdentityClass;
+}
+export interface CompiledAntiPatternLists {
+    product: CompiledAntiPattern[];
+    /** Keyed by `designPrinciple.id`. */
+    perPrinciple: Record<string, CompiledAntiPattern[]>;
+    voice: CompiledAntiPattern[];
+    visual: CompiledAntiPattern[];
+}
+export interface CompiledMeasurableSignal {
+    id: string;
+    metric: string;
+    threshold: number;
+    operator: MeasurableOperator;
+    scope?: string;
+    /** Present when derived from a specific principle's signals list. */
+    sourcePrinciple?: string;
+    /** Present when derived from a visual constraint rule. */
+    sourceVisual?: string;
+    identityClass: IdentityClass;
+}
+export interface Bm25Document {
+    id: string;
+    tokens: string[];
+    /** 2 when derived from `identityClass: 'core'`, else 1. */
+    weight: number;
+}
+export interface Bm25Corpus {
+    documents: Bm25Document[];
+}
+export type PrincipleCorpora = Record<string, Bm25Corpus>;
+export interface CompiledDid {
+    didName: string;
+    namespace?: string;
+    sourceHash: string;
+    scopeLists: CompiledScopeLists;
+    constraintRules: CompiledConstraintRule[];
+    antiPatternLists: CompiledAntiPatternLists;
+    measurableSignals: CompiledMeasurableSignal[];
+    bm25Corpus: Bm25Corpus;
+    principleCorpora: PrincipleCorpora;
+}
+export declare function tokenize(text: string): string[];
+/**
+ * Stable JSON: keys sorted alphabetically at every depth. Matches the
+ * Python json.dumps(sort_keys=True) output so cross-language consumers
+ * agree on the source hash.
+ */
+export declare function canonicalJson(value: unknown): string;
+export declare function hashDidSpec(did: DesignIntentDocument): string;
+export declare function compileDid(did: DesignIntentDocument): CompiledDid;
+export interface ReadinessResult {
+    ready: boolean;
+    gaps: string[];
+}
+/**
+ * Enforce the §B.10.2 minimums a DID must meet before Phase-2b scoring
+ * is safe to enable. Returns a list of gaps; empty ⇒ ready.
+ */
+export declare function validatePhase2bReadiness(compiled: CompiledDid): ReadinessResult;
+export declare function serializeForStore(compiled: CompiledDid): {
+    didName: string;
+    namespace?: string;
+    sourceHash: string;
+    scopeListsJson: string;
+    constraintRulesJson: string;
+    antiPatternListsJson: string;
+    measurableSignalsJson: string;
+    bm25CorpusBlob: Buffer;
+    principleCorporaBlob: Buffer;
+};
+export declare function deserializeFromStore(record: {
+    didName: string;
+    namespace?: string;
+    sourceHash: string;
+    scopeListsJson?: string;
+    constraintRulesJson?: string;
+    antiPatternListsJson?: string;
+    measurableSignalsJson?: string;
+    bm25CorpusBlob?: Buffer;
+    principleCorporaBlob?: Buffer;
+}): CompiledDid;
+//# sourceMappingURL=did-compiler.d.ts.map

package/dist/sa-scoring/did-compiler.js

@@ -0,0 +1,286 @@
+/**
+ * DID compilation pipeline (RFC-0008 Addendum B §B.3.3).
+ *
+ * Consumes a `DesignIntentDocument` and produces six deterministic
+ * artifacts consumed by the three-layer SA scorer:
+ *
+ *   1. scopeLists          — flattened in/out scope synonyms
+ *   2. constraintRules     — detection patterns per soul constraint
+ *   3. antiPatternLists    — product + per-principle + voice + visual
+ *   4. measurableSignals   — principle signals + visual constraints
+ *   5. bm25Corpus          — SA-1 corpus (mission + experientialTargets,
+ *                            core fields weighted 2×, evolving 1×)
+ *   6. principleCorpora    — one SA-2 corpus per designPrinciple
+ *
+ * The output is stable given identical input (canonical JSON + sha256
+ * hash) so `did_compiled_artifacts.source_hash` can be used to detect
+ * DID changes cheaply.
+ */
+import { createHash } from 'node:crypto';
+// ── Tokenization ─────────────────────────────────────────────────────
+const STOPWORDS = new Set([
+    'the',
+    'and',
+    'for',
+    'are',
+    'with',
+    'from',
+    'that',
+    'this',
+    'will',
+    'have',
+    'has',
+    'been',
+    'were',
+    'your',
+    'our',
+    'their',
+    'they',
+    'must',
+    'may',
+    'not',
+    'into',
+    'onto',
+    'than',
+    'but',
+    'any',
+    'all',
+]);
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+// ── Canonical JSON + hash ────────────────────────────────────────────
+/**
+ * Stable JSON: keys sorted alphabetically at every depth. Matches the
+ * Python json.dumps(sort_keys=True) output so cross-language consumers
+ * agree on the source hash.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const sorted = {};
+            for (const k of Object.keys(v).sort()) {
+                sorted[k] = v[k];
+            }
+            return sorted;
+        }
+        return v;
+    });
+}
+export function hashDidSpec(did) {
+    return createHash('sha256').update(canonicalJson(did.spec)).digest('hex');
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function ic(input) {
+    return input?.identityClass ?? 'evolving';
+}
+function compileScopeEntry(term) {
+    return {
+        label: term.label,
+        synonyms: term.synonyms ? Array.from(new Set(term.synonyms)) : [],
+        identityClass: ic(term),
+    };
+}
+function compileConstraint(c) {
+    return {
+        id: c.id,
+        concept: c.concept,
+        relationship: c.relationship,
+        detectionPatterns: [...c.detectionPatterns],
+        identityClass: ic(c),
+    };
+}
+function compileAntiPattern(a) {
+    return {
+        id: a.id,
+        label: a.label,
+        detectionPatterns: [...a.detectionPatterns],
+        identityClass: ic(a),
+    };
+}
+function buildBm25Document(id, text, identityClass) {
+    const tokens = tokenize(text);
+    if (tokens.length === 0)
+        return undefined;
+    return { id, tokens, weight: identityClass === 'core' ? 2 : 1 };
+}
+// ── Compilation entry point ──────────────────────────────────────────
+export function compileDid(did) {
+    const spec = did.spec;
+    // 1. Scope lists
+    const scopeLists = {
+        inScope: (spec.soulPurpose.scopeBoundaries?.inScope ?? []).map(compileScopeEntry),
+        outOfScope: (spec.soulPurpose.scopeBoundaries?.outOfScope ?? []).map(compileScopeEntry),
+    };
+    // 2. Constraint rules
+    const constraintRules = (spec.soulPurpose.constraints ?? []).map(compileConstraint);
+    // 3. Anti-pattern lists
+    const productAntiPatterns = (spec.soulPurpose.antiPatterns ?? []).map(compileAntiPattern);
+    const perPrinciple = {};
+    for (const p of spec.soulPurpose.designPrinciples) {
+        perPrinciple[p.id] = (p.antiPatterns ?? []).map(compileAntiPattern);
+    }
+    const voiceAntiPatterns = (spec.brandIdentity?.voiceAntiPatterns ?? []).map(compileAntiPattern);
+    const visualAntiPatterns = (spec.brandIdentity?.visualIdentity?.visualAntiPatterns ?? []).map(compileAntiPattern);
+    const antiPatternLists = {
+        product: productAntiPatterns,
+        perPrinciple,
+        voice: voiceAntiPatterns,
+        visual: visualAntiPatterns,
+    };
+    // 4. Measurable signals (principle + visual)
+    const measurableSignals = [];
+    for (const principle of spec.soulPurpose.designPrinciples) {
+        for (const sig of principle.measurableSignals ?? []) {
+            measurableSignals.push({
+                id: sig.id,
+                metric: sig.metric,
+                threshold: sig.threshold,
+                operator: sig.operator,
+                scope: sig.scope,
+                sourcePrinciple: principle.id,
+                identityClass: sig.identityClass ?? principle.identityClass ?? 'evolving',
+            });
+        }
+    }
+    for (const vc of spec.brandIdentity?.visualIdentity?.visualConstraints ?? []) {
+        measurableSignals.push(compileVisualConstraintSignal(vc));
+    }
+    // 5. SA-1 BM25 corpus (mission + experientialTargets)
+    const bm25Docs = [];
+    const missionDoc = buildBm25Document('mission', spec.soulPurpose.mission.value, ic(spec.soulPurpose.mission));
+    if (missionDoc)
+        bm25Docs.push(missionDoc);
+    for (const [name, target] of Object.entries(spec.experientialTargets ?? {})) {
+        if (!target)
+            continue;
+        const doc = buildBm25Document(`experientialTargets.${name}`, JSON.stringify(target), ic(target));
+        if (doc)
+            bm25Docs.push(doc);
+    }
+    const bm25Corpus = { documents: bm25Docs };
+    // 6. SA-2 principle corpora
+    const principleCorpora = {};
+    for (const principle of spec.soulPurpose.designPrinciples) {
+        principleCorpora[principle.id] = buildPrincipleCorpus(principle);
+    }
+    return {
+        didName: did.metadata.name,
+        namespace: did.metadata.namespace,
+        sourceHash: hashDidSpec(did),
+        scopeLists,
+        constraintRules,
+        antiPatternLists,
+        measurableSignals,
+        bm25Corpus,
+        principleCorpora,
+    };
+}
+function compileVisualConstraintSignal(vc) {
+    return {
+        id: vc.id,
+        metric: vc.rule.metric,
+        threshold: vc.rule.threshold,
+        operator: vc.rule.operator,
+        sourceVisual: vc.id,
+        identityClass: ic(vc),
+    };
+}
+function buildPrincipleCorpus(principle) {
+    const pic = principle.identityClass ?? 'evolving';
+    const docs = [];
+    const nameDoc = buildBm25Document(`${principle.id}.name`, principle.name, pic);
+    if (nameDoc)
+        docs.push(nameDoc);
+    const descDoc = buildBm25Document(`${principle.id}.description`, principle.description, pic);
+    if (descDoc)
+        docs.push(descDoc);
+    for (const sig of principle.measurableSignals ?? []) {
+        const doc = buildBm25Document(`${principle.id}.signal.${sig.id}`, `${sig.metric} ${sig.operator} ${sig.threshold}`, sig.identityClass ?? pic);
+        if (doc)
+            docs.push(doc);
+    }
+    for (const ap of principle.antiPatterns ?? []) {
+        const doc = buildBm25Document(`${principle.id}.antipattern.${ap.id}`, `${ap.label} ${ap.detectionPatterns.join(' ')}`, ap.identityClass ?? pic);
+        if (doc)
+            docs.push(doc);
+    }
+    return { documents: docs };
+}
+/**
+ * Enforce the §B.10.2 minimums a DID must meet before Phase-2b scoring
+ * is safe to enable. Returns a list of gaps; empty ⇒ ready.
+ */
+export function validatePhase2bReadiness(compiled) {
+    const gaps = [];
+    // ≥ 2 constraints with ≥ 3 detection patterns
+    const qualifyingConstraints = compiled.constraintRules.filter((c) => c.detectionPatterns.length >= 3);
+    if (qualifyingConstraints.length < 2) {
+        gaps.push(`Need ≥2 constraints with ≥3 detection patterns each (got ${qualifyingConstraints.length})`);
+    }
+    // ≥ 3 outOfScope entries with ≥ 2 synonyms
+    const outOfScopeOk = compiled.scopeLists.outOfScope.filter((s) => s.synonyms.length >= 2);
+    if (outOfScopeOk.length < 3) {
+        gaps.push(`Need ≥3 outOfScope entries with ≥2 synonyms each (got ${outOfScopeOk.length})`);
+    }
+    // ≥ 3 product-level antiPatterns with ≥ 3 patterns
+    const productAntiOk = compiled.antiPatternLists.product.filter((a) => a.detectionPatterns.length >= 3);
+    if (productAntiOk.length < 3) {
+        gaps.push(`Need ≥3 product-level antiPatterns with ≥3 detection patterns each (got ${productAntiOk.length})`);
+    }
+    // ≥ 1 principle with ≥ 2 antiPatterns having ≥ 2 patterns each
+    const principlesWithAnti = Object.entries(compiled.antiPatternLists.perPrinciple).filter(([, list]) => list.filter((a) => a.detectionPatterns.length >= 2).length >= 2);
+    if (principlesWithAnti.length < 1) {
+        gaps.push('Need ≥1 designPrinciple with ≥2 antiPatterns (each with ≥2 detection patterns)');
+    }
+    // ≥ 2 voice antiPatterns with ≥ 2 patterns
+    const voiceOk = compiled.antiPatternLists.voice.filter((a) => a.detectionPatterns.length >= 2);
+    if (voiceOk.length < 2) {
+        gaps.push(`Need ≥2 voice antiPatterns with ≥2 detection patterns each (got ${voiceOk.length})`);
+    }
+    // ≥ 2 visual antiPatterns with ≥ 2 patterns
+    const visualOk = compiled.antiPatternLists.visual.filter((a) => a.detectionPatterns.length >= 2);
+    if (visualOk.length < 2) {
+        gaps.push(`Need ≥2 visual antiPatterns with ≥2 detection patterns each (got ${visualOk.length})`);
+    }
+    return { ready: gaps.length === 0, gaps };
+}
+// ── State-store serialization helpers ────────────────────────────────
+export function serializeForStore(compiled) {
+    return {
+        didName: compiled.didName,
+        namespace: compiled.namespace,
+        sourceHash: compiled.sourceHash,
+        scopeListsJson: canonicalJson(compiled.scopeLists),
+        constraintRulesJson: canonicalJson(compiled.constraintRules),
+        antiPatternListsJson: canonicalJson(compiled.antiPatternLists),
+        measurableSignalsJson: canonicalJson(compiled.measurableSignals),
+        bm25CorpusBlob: Buffer.from(canonicalJson(compiled.bm25Corpus), 'utf-8'),
+        principleCorporaBlob: Buffer.from(canonicalJson(compiled.principleCorpora), 'utf-8'),
+    };
+}
+export function deserializeFromStore(record) {
+    const parse = (json, fallback) => json ? JSON.parse(json) : fallback;
+    const parseBuffer = (buf, fallback) => buf ? JSON.parse(buf.toString('utf-8')) : fallback;
+    return {
+        didName: record.didName,
+        namespace: record.namespace,
+        sourceHash: record.sourceHash,
+        scopeLists: parse(record.scopeListsJson, { inScope: [], outOfScope: [] }),
+        constraintRules: parse(record.constraintRulesJson, []),
+        antiPatternLists: parse(record.antiPatternListsJson, {
+            product: [],
+            perPrinciple: {},
+            voice: [],
+            visual: [],
+        }),
+        measurableSignals: parse(record.measurableSignalsJson, []),
+        bm25Corpus: parseBuffer(record.bm25CorpusBlob, { documents: [] }),
+        principleCorpora: parseBuffer(record.principleCorporaBlob, {}),
+    };
+}
+//# sourceMappingURL=did-compiler.js.map

package/dist/sa-scoring/drift-monitor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SA Drift Monitor (RFC-0008 Addendum B §B.9.2).
+ *
+ * Periodically inspects `did_scoring_events` and triggers a
+ * `SoulDriftDetected` event when SA-1 or SA-2 rolling statistics
+ * indicate the scorer is drifting. Separately reports structural vs
+ * LLM means so operators can tell whether the drift is coming from
+ * the product (DID review needed) or the LLM layer (exemplar bank
+ * recalibration needed).
+ *
+ * Trigger (per dimension):
+ *   mean < 0.4  OR  stddev > 0.15   — for 3 consecutive windows
+ *
+ * Hysteresis: caller supplies `lastTriggerAt`; the monitor won't fire
+ * again within `recoveryMs` (default 7d) of the previous emission.
+ */
+import type { DesignSystemBinding } from '@ai-sdlc/reference';
+import type { StateStore } from '../state/store.js';
+import type { DidScoringEventRecord, SaDimension } from '../state/types.js';
+export declare const DEFAULT_MEAN_THRESHOLD = 0.4;
+export declare const DEFAULT_STDDEV_THRESHOLD = 0.15;
+/** Number of consecutive windows that must violate to trigger. */
+export declare const DEFAULT_CONSECUTIVE_WINDOWS = 3;
+export declare const DEFAULT_WINDOW_DAYS = 30;
+export declare const DEFAULT_RECOVERY_MS: number;
+export interface WindowStats {
+    count: number;
+    mean: number;
+    stddev: number;
+    structuralMean: number;
+    llmMean: number;
+    deterministicFlags: number;
+    /** Inclusive window range — [start, end) in ms. */
+    windowStartMs: number;
+    windowEndMs: number;
+    /** True if this window violated the drift threshold. */
+    violates: boolean;
+}
+export type DriftTrend = 'increasing' | 'decreasing' | 'stable';
+export interface SoulDriftDetectedEvent {
+    type: 'SoulDriftDetected';
+    dimension: SaDimension;
+    rollingMean: number;
+    rollingStdDev: number;
+    sprintsInViolation: number;
+    trend: DriftTrend;
+    driftSource: {
+        deterministicFlags: number;
+        structuralScoreMean: number;
+        llmScoreMean: number;
+        note: string;
+    };
+    notifiedPrincipals: string[];
+    triggeredAt: string;
+}
+export declare function mean(values: readonly number[]): number;
+export declare function stddev(values: readonly number[]): number;
+export declare function computeWindowStats(events: readonly DidScoringEventRecord[], windowStartMs: number, windowEndMs: number, meanThreshold: number, stddevThreshold: number): WindowStats;
+export declare function computeTrend(windows: readonly WindowStats[]): DriftTrend;
+export declare function describeDriftSource(windows: readonly WindowStats[]): {
+    structuralScoreMean: number;
+    llmScoreMean: number;
+    note: string;
+    deterministicFlags: number;
+};
+export interface DriftDetectorDeps {
+    stateStore: StateStore;
+    /** Resolve the DSB that owns this DID (for notification principals). */
+    getBinding?: (dimension: SaDimension) => DesignSystemBinding | undefined;
+    /** Previous trigger timestamp (for hysteresis). */
+    getLastTriggerAt?: (dimension: SaDimension) => string | undefined;
+    /** Clock injection for tests. */
+    now?: () => number;
+    /** Configuration overrides. */
+    config?: Partial<{
+        meanThreshold: number;
+        stddevThreshold: number;
+        consecutiveWindows: number;
+        windowDays: number;
+        recoveryMs: number;
+    }>;
+}
+export declare function detectSoulDrift(dimension: SaDimension, deps: DriftDetectorDeps): SoulDriftDetectedEvent | undefined;
+//# sourceMappingURL=drift-monitor.d.ts.map

package/dist/sa-scoring/drift-monitor.js

@@ -0,0 +1,186 @@
+/**
+ * SA Drift Monitor (RFC-0008 Addendum B §B.9.2).
+ *
+ * Periodically inspects `did_scoring_events` and triggers a
+ * `SoulDriftDetected` event when SA-1 or SA-2 rolling statistics
+ * indicate the scorer is drifting. Separately reports structural vs
+ * LLM means so operators can tell whether the drift is coming from
+ * the product (DID review needed) or the LLM layer (exemplar bank
+ * recalibration needed).
+ *
+ * Trigger (per dimension):
+ *   mean < 0.4  OR  stddev > 0.15   — for 3 consecutive windows
+ *
+ * Hysteresis: caller supplies `lastTriggerAt`; the monitor won't fire
+ * again within `recoveryMs` (default 7d) of the previous emission.
+ */
+// ── Constants ───────────────────────────────────────────────────────
+export const DEFAULT_MEAN_THRESHOLD = 0.4;
+export const DEFAULT_STDDEV_THRESHOLD = 0.15;
+/** Number of consecutive windows that must violate to trigger. */
+export const DEFAULT_CONSECUTIVE_WINDOWS = 3;
+export const DEFAULT_WINDOW_DAYS = 30;
+export const DEFAULT_RECOVERY_MS = 7 * 24 * 60 * 60 * 1000;
+// ── Pure helpers ────────────────────────────────────────────────────
+export function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+export function stddev(values) {
+    if (values.length === 0)
+        return 0;
+    const m = mean(values);
+    const variance = values.reduce((acc, v) => acc + (v - m) * (v - m), 0) / values.length;
+    return Math.sqrt(variance);
+}
+export function computeWindowStats(events, windowStartMs, windowEndMs, meanThreshold, stddevThreshold) {
+    const composites = [];
+    const structural = [];
+    const llm = [];
+    let deterministicFlags = 0;
+    for (const e of events) {
+        if (typeof e.compositeScore === 'number')
+            composites.push(e.compositeScore);
+        if (e.layer2ResultJson) {
+            try {
+                const parsed = JSON.parse(e.layer2ResultJson);
+                if (typeof parsed.score === 'number')
+                    structural.push(parsed.score);
+            }
+            catch {
+                // ignore malformed entry
+            }
+        }
+        if (e.layer3ResultJson) {
+            try {
+                const parsed = JSON.parse(e.layer3ResultJson);
+                const candidate = parsed.domainIntent ?? parsed.principleAlignment;
+                if (typeof candidate === 'number')
+                    llm.push(candidate);
+            }
+            catch {
+                // ignore malformed entry
+            }
+        }
+        if (e.layer1ResultJson) {
+            try {
+                const parsed = JSON.parse(e.layer1ResultJson);
+                if (parsed.hardGated)
+                    deterministicFlags++;
+            }
+            catch {
+                // ignore malformed entry
+            }
+        }
+    }
+    const m = mean(composites);
+    const s = stddev(composites);
+    return {
+        count: composites.length,
+        mean: m,
+        stddev: s,
+        structuralMean: mean(structural),
+        llmMean: mean(llm),
+        deterministicFlags,
+        windowStartMs,
+        windowEndMs,
+        violates: composites.length > 0 && (m < meanThreshold || s > stddevThreshold),
+    };
+}
+export function computeTrend(windows) {
+    if (windows.length < 2)
+        return 'stable';
+    // Windows ordered newest-first; trend is the direction of mean over time.
+    const newestMean = windows[0].mean;
+    const oldestMean = windows[windows.length - 1].mean;
+    const delta = newestMean - oldestMean;
+    if (Math.abs(delta) < 0.05)
+        return 'stable';
+    return delta > 0 ? 'increasing' : 'decreasing';
+}
+export function describeDriftSource(windows) {
+    const structural = mean(windows.map((w) => w.structuralMean));
+    const llm = mean(windows.map((w) => w.llmMean));
+    const flags = windows.reduce((acc, w) => acc + w.deterministicFlags, 0);
+    let note;
+    if (llm < structural - 0.15)
+        note = 'LLM-layer drift (consider recalibrating exemplar bank)';
+    else if (structural < llm - 0.15)
+        note = 'Structural drift (review DID corpus + compile artifacts)';
+    else if (flags > 0)
+        note = `Mixed drift with ${flags} hard-gated events (review DID scope)`;
+    else
+        note = 'Uniform drift across layers (product review recommended)';
+    return {
+        structuralScoreMean: structural,
+        llmScoreMean: llm,
+        note,
+        deterministicFlags: flags,
+    };
+}
+export function detectSoulDrift(dimension, deps) {
+    const cfg = deps.config ?? {};
+    const meanThreshold = cfg.meanThreshold ?? DEFAULT_MEAN_THRESHOLD;
+    const stddevThreshold = cfg.stddevThreshold ?? DEFAULT_STDDEV_THRESHOLD;
+    const consecutive = cfg.consecutiveWindows ?? DEFAULT_CONSECUTIVE_WINDOWS;
+    const windowDays = cfg.windowDays ?? DEFAULT_WINDOW_DAYS;
+    const recoveryMs = cfg.recoveryMs ?? DEFAULT_RECOVERY_MS;
+    const nowMs = (deps.now ?? (() => Date.now()))();
+    // Hysteresis
+    const lastTriggerAt = deps.getLastTriggerAt?.(dimension);
+    if (lastTriggerAt) {
+        const lastMs = Date.parse(lastTriggerAt);
+        if (!Number.isNaN(lastMs) && nowMs - lastMs < recoveryMs)
+            return undefined;
+    }
+    const windowMs = windowDays * 24 * 60 * 60 * 1000;
+    const earliestMs = nowMs - consecutive * windowMs;
+    // Fetch events for the combined range.
+    const since = new Date(earliestMs).toISOString();
+    const events = deps.stateStore.getDidScoringEvents({
+        saDimension: dimension,
+        since,
+        limit: 10_000,
+    });
+    // Partition into consecutive windows (newest → oldest).
+    const windows = [];
+    for (let i = 0; i < consecutive; i++) {
+        const endMs = nowMs - i * windowMs;
+        const startMs = endMs - windowMs;
+        const inWindow = events.filter((e) => {
+            const t = e.createdAt ? Date.parse(e.createdAt) : NaN;
+            return !Number.isNaN(t) && t >= startMs && t < endMs;
+        });
+        windows.push(computeWindowStats(inWindow, startMs, endMs, meanThreshold, stddevThreshold));
+    }
+    const allViolate = windows.every((w) => w.violates);
+    if (!allViolate)
+        return undefined;
+    // All windows violated — fire the event.
+    const compositeMeans = windows.map((w) => w.mean);
+    const compositeStddevs = windows.map((w) => w.stddev);
+    const rollingMean = mean(compositeMeans);
+    const rollingStdDev = mean(compositeStddevs);
+    const trend = computeTrend(windows);
+    const driftSource = describeDriftSource(windows);
+    const binding = deps.getBinding?.(dimension);
+    const principals = binding ? collectPrincipals(binding) : [];
+    return {
+        type: 'SoulDriftDetected',
+        dimension,
+        rollingMean,
+        rollingStdDev,
+        sprintsInViolation: consecutive,
+        trend,
+        driftSource,
+        notifiedPrincipals: principals,
+        triggeredAt: new Date(nowMs).toISOString(),
+    };
+}
+function collectPrincipals(binding) {
+    const design = binding.spec.stewardship.designAuthority.principals;
+    const engineering = binding.spec.stewardship.engineeringAuthority.principals;
+    return Array.from(new Set([...design, ...engineering]));
+}
+//# sourceMappingURL=drift-monitor.js.map