@avi770/testteam 3.0.0 → 3.2.0

package/dist/core/data-integrity/data-integrity.js

@@ -0,0 +1,892 @@
+/**
+ * Data Integrity ("The Notary") — Agent #9 operational layer implementation.
+ *
+ * This is a CONTINUOUS / COMPOSITE layer. It does NOT re-implement anything that
+ * engine agents #14 (DataIntegrityAuditor), #43 (DataConsistencyChecker),
+ * #44 (BackupRecoveryTester), or #45 (DataPrivacyScanner) already do. Instead,
+ * it COMPOSES their Finding outputs and adds the net-new concerns:
+ *   - referential-integrity violation detection
+ *   - cross-store consistency checking
+ *   - reconciliation engine (ledger-balance, count-match)
+ *   - backup RPO verification + restore-test enforcement (wraps #44 output shape)
+ *   - tamper-evident audit log (immudb-style hash-chain, in-process for testing)
+ *   - data-lineage correlation / corruption tracing
+ *   - distribution anomaly detection (null-spikes, dup-spikes, count-drift)
+ *   - read-only proof (the constitution: never mutates production data)
+ *
+ * Engine-reuse layering boundary:
+ *   Engine agents (#14/#43/#44/#45) execute live against the real app and return
+ *   Finding[]. This module ingests those Finding arrays verbatim (see
+ *   ingestEngineFindings) — it is the AGGREGATION + NET-NEW layer, not a replacement.
+ *   The integration tests (see __tests__/data-integrity.test.ts) drive the session
+ *   with Finding objects whose agentId matches the real engine agents (14, 43, 44, 45)
+ *   to prove the composition contract.
+ *
+ * Operating principles (load-bearing):
+ *   - READ-ONLY on production data — never auto-repairs; any repair recommendation
+ *     routes via the Harness + human approval.
+ *   - Frugal: all check methods are pure / fixture-driven (no DB connections at this layer).
+ *   - Honest: no gameable scoring; never round up severity; show-the-math deltas.
+ *   - Deterministic under fixed inputs (clock is injectable for tests).
+ *   - FAIL-CLOSED: unknown / thin / ambiguous states BLOCK or are flagged incomplete.
+ *
+ * Spec: blueprint/agents/09-data-integrity.md
+ */
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+const GENESIS_HASH = '0'.repeat(64);
+const AGENT_ID = 9;
+const MODULE = 'data-integrity';
+/** Any null-fraction above this threshold signals a null-spike anomaly. */
+const NULL_SPIKE_THRESHOLD = 0.1; // 10 %
+/** Any dup-fraction above this signals a dup-spike anomaly. */
+const DUP_SPIKE_THRESHOLD = 0.05; // 5 %
+// ---------------------------------------------------------------------------
+// Engine-agent composition contract (must-fix #5)
+// ---------------------------------------------------------------------------
+/**
+ * The real engine agents this Notary composes — the engine "Data Squad".
+ * These ids are registered engine agents (bridge/agent-registry, squad 'data');
+ * an integration test asserts they still exist and are grouped as 'data', so an
+ * engine renumber/regroup breaks the build rather than silently de-coupling.
+ * This module ingests their Finding[] output verbatim — it does NOT re-implement them.
+ */
+export const COMPOSED_ENGINE_AGENTS = {
+    dataIntegrityAuditor: 14,
+    dataConsistencyChecker: 43,
+    backupRecoveryTester: 44,
+    dataPrivacyScanner: 45,
+};
+// ---------------------------------------------------------------------------
+// Engine-agent → IntegrityEventType mapping (must-fix #3)
+// ---------------------------------------------------------------------------
+/**
+ * Map an ingested engine-agent finding to the correct IntegrityEventType.
+ *
+ * Must-fix #3: every finding is logged under its true event category, never
+ * uniformly mislabelled. Honest mapping (no over-claiming):
+ *   - #45 DataPrivacyScanner     → 'pii-exposure'
+ *   - #43 DataConsistencyChecker → 'cross-store-inconsistency'
+ *   - #14 DataIntegrityAuditor   → 'ref-integrity-violation'
+ *   - #44 BackupRecoveryTester   → 'engine-finding' (recorded verbatim; we do NOT
+ *        assume 'backup-missing' — a #44 finding may be a benign skip)
+ *   - any other agent            → 'engine-finding' (honest neutral; NOT a
+ *        'ref-integrity-violation' mislabel for an uncategorised source)
+ */
+function engineFindingToEventType(finding) {
+    switch (finding.agentId) {
+        case COMPOSED_ENGINE_AGENTS.dataPrivacyScanner:
+            return 'pii-exposure';
+        case COMPOSED_ENGINE_AGENTS.dataConsistencyChecker:
+            return 'cross-store-inconsistency';
+        case COMPOSED_ENGINE_AGENTS.dataIntegrityAuditor:
+            return 'ref-integrity-violation';
+        case COMPOSED_ENGINE_AGENTS.backupRecoveryTester:
+        default:
+            return 'engine-finding';
+    }
+}
+// ---------------------------------------------------------------------------
+// Audit-log helpers (hash-chain, no external deps)
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic canonical form for an audit entry.
+ * Fixed-tuple — key-order changes cannot weaken the chain.
+ */
+function canonicalAuditTuple(entry) {
+    return JSON.stringify([
+        entry.seq,
+        entry.at,
+        entry.eventType,
+        entry.subject,
+        entry.severity,
+        entry.summary,
+        entry.prevHash,
+    ]);
+}
+function hashAuditEntry(entry) {
+    return createHash('sha256').update(canonicalAuditTuple(entry)).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// TamperEvidentLog — in-process immudb-style hash chain
+// ---------------------------------------------------------------------------
+/**
+ * Append-only, hash-chained audit log. Each entry's hash commits to its
+ * predecessor's hash. `verify()` re-derives every hash end-to-end; any
+ * tampering (seq mutation, field edit, insertion, deletion) breaks the chain.
+ */
+export class TamperEvidentLog {
+    entries = [];
+    now;
+    constructor(options) {
+        this.now = options?.clock ?? (() => Date.now());
+    }
+    append(eventType, subject, severity, summary) {
+        const seq = this.entries.length;
+        const prevHash = seq === 0 ? GENESIS_HASH : this.entries[seq - 1].hash;
+        const at = new Date(this.now()).toISOString();
+        const partial = {
+            seq,
+            at,
+            eventType,
+            subject,
+            severity,
+            summary,
+            prevHash,
+        };
+        const entry = { ...partial, hash: hashAuditEntry(partial) };
+        this.entries.push(entry);
+        return entry;
+    }
+    get log() {
+        return this.entries.slice();
+    }
+    get length() {
+        return this.entries.length;
+    }
+    /**
+     * Hash of the latest entry — commits transitively to the whole chain (or the
+     * genesis hash for an empty log). Capture {length, headHash} as an anchor to
+     * detect later tail-truncation (which `verify()` alone cannot — see below).
+     */
+    get headHash() {
+        return this.entries.length === 0
+            ? GENESIS_HASH
+            : this.entries[this.entries.length - 1].hash;
+    }
+    /**
+     * Recompute every hash end-to-end. Returns `false` if any entry's seq, prevHash,
+     * or content was altered (edit / reorder / insertion).
+     *
+     * LIMITATION (honest): deleting the NEWEST entries leaves a shorter chain that
+     * still verifies — `verify()` cannot detect tail-truncation on its own. Use
+     * `verifyAgainstAnchor` with a previously captured {length, headHash} to catch it.
+     */
+    verify() {
+        let prev = GENESIS_HASH;
+        for (let i = 0; i < this.entries.length; i++) {
+            const entry = this.entries[i];
+            if (entry.seq !== i || entry.prevHash !== prev)
+                return false;
+            const { hash, ...partial } = entry;
+            if (hashAuditEntry(partial) !== hash)
+                return false;
+            prev = hash;
+        }
+        return true;
+    }
+    /**
+     * Detect tampering INCLUDING tail-truncation by comparing against a previously
+     * captured anchor. Returns true only when the chain verifies AND the length and
+     * head hash exactly match the anchor — so any dropped/added/edited entry fails.
+     */
+    verifyAgainstAnchor(anchor) {
+        return this.verify() && this.length === anchor.length && this.headHash === anchor.headHash;
+    }
+}
+// ---------------------------------------------------------------------------
+// Referential-integrity checks
+// ---------------------------------------------------------------------------
+/**
+ * Given a set of ref-integrity assertions and a lookup function that returns
+ * `true` when the referenced target EXISTS, return all violations.
+ *
+ * The lookup is synchronous and provided by the caller (never touches DB here).
+ * In production tests, the caller wraps the engine-agent snapshot.
+ *
+ * @param assertions   Assertions to validate.
+ * @param keyExists    Pure: returns true iff targetEntity has an entry for key.
+ * @param keys         The set of keys to verify (from the source collection sample).
+ */
+export function detectRefIntegrityViolations(assertions, keyExists, keys, clock = Date.now) {
+    const violations = [];
+    for (const assertion of assertions) {
+        const keysToCheck = keys.get(assertion.description) ?? [];
+        for (const key of keysToCheck) {
+            if (!keyExists(assertion.targetEntity, key)) {
+                violations.push({
+                    assertion,
+                    orphanedKey: key,
+                    detectedAtMs: clock(),
+                });
+            }
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Cross-store consistency checks
+// ---------------------------------------------------------------------------
+/**
+ * Compare a list of cross-store check results and return those that are inconsistent.
+ * "Consistent" means `JSON.stringify(primary)` equals `JSON.stringify(secondary)`.
+ * This deterministic serialisation comparison is intentionally conservative:
+ * structural differences in types (number vs string "42") ARE flagged.
+ */
+export function detectCrossStoreInconsistencies(checks, clock = Date.now) {
+    const inconsistencies = [];
+    for (const check of checks) {
+        const primary = JSON.stringify(check.primaryValue);
+        const secondary = JSON.stringify(check.secondaryValue);
+        if (primary !== secondary) {
+            inconsistencies.push({ check, detectedAtMs: clock() });
+        }
+    }
+    return inconsistencies;
+}
+// ---------------------------------------------------------------------------
+// Reconciliation engine
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate a reconciliation assertion by comparing expected vs observed values.
+ * The `tolerance` parameter is the maximum allowed absolute delta (default 0 —
+ * exact match required for financial values).
+ *
+ * Never rounds the delta: show-the-math transparency.
+ */
+export function reconcile(assertion, expectedValue, observedValue, toleranceAbsolute = 0, clock = Date.now) {
+    // Fail-closed on non-finite inputs: a NaN/Infinity expected or observed value is
+    // an unknown/ambiguous state and must be treated as a BREAK, never silently passed
+    // (NaN > tolerance === false would let a corrupt reconciliation slip through).
+    const bothFinite = Number.isFinite(expectedValue) && Number.isFinite(observedValue);
+    const delta = bothFinite ? Math.abs(expectedValue - observedValue) : NaN;
+    // Never round delta — the caller sees the exact number.
+    return {
+        assertion,
+        expectedValue,
+        observedValue,
+        delta,
+        isBreak: !bothFinite || delta > toleranceAbsolute,
+        capturedAtMs: clock(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Backup / RPO verification (must-fix #2)
+// ---------------------------------------------------------------------------
+/**
+ * Verify a backup against an RPO target.
+ *
+ * Must-fix #2: a backup is only fully verified when a restore-test has been
+ * performed. A backup with status='verified' but no restoreTestedAtMs is flagged
+ * as restoreVerified=false — the Notary cannot assume a backup is usable until
+ * restore has been confirmed.
+ *
+ * @param name              Logical backup name.
+ * @param backupTimestampMs When the backup was taken (epoch ms), or undefined if unknown.
+ * @param status            The status resolved by engine agent #44 or the caller.
+ * @param rpoTargetMs       Recovery-point objective in milliseconds.
+ * @param restoreTestedAtMs Optional: when a restore-test was last confirmed (epoch ms).
+ *                          When absent the backup is NOT considered restore-verified.
+ * @param clock             Injectable for deterministic tests.
+ */
+export function verifyBackup(name, backupTimestampMs, status, rpoTargetMs, restoreTestedAtMs, clock = Date.now) {
+    const nowMs = clock();
+    let rpoSatisfied;
+    if (status !== 'verified' || backupTimestampMs === undefined) {
+        rpoSatisfied = false;
+    }
+    else {
+        const ageMs = nowMs - backupTimestampMs;
+        rpoSatisfied = ageMs <= rpoTargetMs;
+    }
+    // must-fix #2: restoreVerified requires BOTH rpoSatisfied AND a confirmed restore-test.
+    // A backup with no restoreTestedAtMs is fail-closed — we cannot assume it is restorable.
+    const restoreVerified = rpoSatisfied && restoreTestedAtMs !== undefined && restoreTestedAtMs <= nowMs;
+    return {
+        name,
+        status,
+        backupTimestampMs,
+        rpoTargetMs,
+        rpoSatisfied,
+        verifiedAtMs: nowMs,
+        restoreVerified,
+        ...(restoreTestedAtMs !== undefined ? { restoreTestedAtMs } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Distribution anomaly detection
+// ---------------------------------------------------------------------------
+/**
+ * Analyse field-level distribution stats and return anomalies found.
+ * Never modifies the input; purely derives anomalies from the stats.
+ */
+export function detectDistributionAnomalies(stats, options, clock = Date.now) {
+    const nullThresh = options?.nullSpikeThreshold ?? NULL_SPIKE_THRESHOLD;
+    const dupThresh = options?.dupSpikeThreshold ?? DUP_SPIKE_THRESHOLD;
+    const expectedCounts = options?.expectedCountsByField;
+    const driftTolerance = options?.countDriftToleranceFraction ?? 0.05;
+    const anomalies = [];
+    const nowMs = clock();
+    for (const stat of stats) {
+        if (stat.totalCount > 0 && stat.nullFraction > nullThresh) {
+            anomalies.push({
+                stats: stat,
+                anomalyType: 'null-spike',
+                detail: `${stat.field} on ${stat.entityType}: null fraction ${(stat.nullFraction * 100).toFixed(2)}% ` +
+                    `exceeds threshold ${(nullThresh * 100).toFixed(2)}%`,
+                detectedAtMs: nowMs,
+            });
+        }
+        if (stat.totalCount > 0 && stat.dupFraction > dupThresh) {
+            anomalies.push({
+                stats: stat,
+                anomalyType: 'dup-spike',
+                detail: `${stat.field} on ${stat.entityType}: duplicate fraction ${(stat.dupFraction * 100).toFixed(2)}% ` +
+                    `exceeds threshold ${(dupThresh * 100).toFixed(2)}%`,
+                detectedAtMs: nowMs,
+            });
+        }
+        if (expectedCounts !== undefined) {
+            const expectedCount = expectedCounts.get(stat.field);
+            if (expectedCount !== undefined && expectedCount > 0) {
+                const driftFraction = Math.abs(stat.totalCount - expectedCount) / expectedCount;
+                if (driftFraction > driftTolerance) {
+                    anomalies.push({
+                        stats: stat,
+                        anomalyType: 'count-drift',
+                        detail: `${stat.field} on ${stat.entityType}: count ${stat.totalCount} vs expected ${expectedCount} ` +
+                            `(${(driftFraction * 100).toFixed(2)}% drift, tolerance ${(driftTolerance * 100).toFixed(2)}%)`,
+                        detectedAtMs: nowMs,
+                    });
+                }
+            }
+        }
+    }
+    return anomalies;
+}
+// ---------------------------------------------------------------------------
+// Data lineage — corruption tracing (must-fix #6)
+// ---------------------------------------------------------------------------
+/**
+ * Trace a corruption (observed at `corruptedNodeId`) back to its most-upstream
+ * source(s) in the lineage graph via breadth-first traversal.
+ *
+ * Must-fix #6: when multiple source nodes (upstreamIds.length === 0) are reachable,
+ * ALL candidates are returned in `rootCauseCandidates`. The `rootCauseNode` field
+ * is a DETERMINISTIC HEURISTIC (lexicographically first candidate id) — it is
+ * explicitly NOT an authoritative single-root determination. Callers must inspect
+ * `rootCauseCandidates` for the full picture in branching lineage graphs.
+ *
+ * Returns `undefined` if `corruptedNodeId` is not found in the graph.
+ */
+export function traceCorruption(graph, corruptedNodeId) {
+    const nodeById = new Map();
+    for (const node of graph.nodes) {
+        nodeById.set(node.id, node);
+    }
+    const startNode = nodeById.get(corruptedNodeId);
+    if (startNode === undefined)
+        return undefined;
+    // BFS upstream: follow upstreamIds edges
+    const visited = new Set();
+    const queue = [startNode];
+    const pathOrder = [];
+    while (queue.length > 0) {
+        // Pop the front (BFS — deterministic processing order)
+        const current = queue.shift();
+        if (visited.has(current.id))
+            continue;
+        visited.add(current.id);
+        pathOrder.push(current);
+        // Sort upstream ids for deterministic traversal
+        const upstreams = [...current.upstreamIds].sort();
+        for (const upId of upstreams) {
+            const up = nodeById.get(upId);
+            if (up && !visited.has(up.id)) {
+                queue.push(up);
+            }
+        }
+    }
+    // Collect ALL source nodes (no upstream) — these are the candidates.
+    const rootCauseCandidates = pathOrder
+        .filter((n) => n.upstreamIds.length === 0)
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    // Deterministic heuristic tie-break: lex-first candidate.
+    // HEURISTIC: not authoritative in branching graphs; see rootCauseCandidates.
+    const rootCauseNode = rootCauseCandidates.length > 0 ? rootCauseCandidates[0] : startNode;
+    // The lineage path is ordered most-upstream first
+    const lineagePath = [...pathOrder].reverse();
+    return {
+        observedAt: corruptedNodeId,
+        lineagePath,
+        rootCauseNode,
+        rootCauseCandidates,
+    };
+}
+// ---------------------------------------------------------------------------
+// Summary builder
+// ---------------------------------------------------------------------------
+/**
+ * Canonical severity-by-class — the single documented source of truth for the
+ * Notary-layer violation classes. These classes carry an inherent risk level (a
+ * referential-integrity break or cross-store divergence IS a high-severity data
+ * hazard; a reconciliation break IS critical; a backup that fails RPO OR is within
+ * RPO but never restore-tested IS high). Ingested engine findings keep their OWN
+ * severity (assigned by the engine agent), never overridden here.
+ */
+const SEVERITY_BY_CLASS = {
+    refViolation: 'high',
+    crossStoreInconsistency: 'high',
+    reconciliationBreak: 'critical',
+    backupRpoFail: 'high',
+    backupRestoreUntested: 'high',
+    distributionAnomaly: 'medium',
+};
+function buildSummary(refViolations, crossStoreInconsistencies, reconciliationBreaks, backupVerifications, distributionAnomalies, engineFindings) {
+    const counts = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        info: 0,
+    };
+    for (const _ of refViolations)
+        counts[SEVERITY_BY_CLASS.refViolation] += 1;
+    for (const _ of crossStoreInconsistencies)
+        counts[SEVERITY_BY_CLASS.crossStoreInconsistency] += 1;
+    // reconciliationBreaks is already the isBreak-filtered list (see buildReport).
+    for (const _ of reconciliationBreaks)
+        counts[SEVERITY_BY_CLASS.reconciliationBreak] += 1;
+    // must-fix #2: a backup that fails RPO OR is within RPO but never restore-tested is a
+    // violation and MUST roll up to escalation — restore-untested no longer scores 0.
+    let backupViolations = 0;
+    for (const bv of backupVerifications) {
+        if (!bv.rpoSatisfied) {
+            counts[SEVERITY_BY_CLASS.backupRpoFail] += 1;
+            backupViolations += 1;
+        }
+        else if (!bv.restoreVerified) {
+            counts[SEVERITY_BY_CLASS.backupRestoreUntested] += 1;
+            backupViolations += 1;
+        }
+    }
+    for (const _ of distributionAnomalies)
+        counts[SEVERITY_BY_CLASS.distributionAnomaly] += 1;
+    // Ingested engine findings keep their own (engine-assigned) severity.
+    for (const f of engineFindings) {
+        counts[f.severity] += 1;
+    }
+    const totalViolations = refViolations.length +
+        crossStoreInconsistencies.length +
+        reconciliationBreaks.length +
+        backupViolations +
+        distributionAnomalies.length +
+        engineFindings.length;
+    return {
+        totalViolations,
+        critical: counts.critical,
+        high: counts.high,
+        medium: counts.medium,
+        low: counts.low,
+        requiresEscalation: counts.critical > 0 || counts.high > 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Read-only guard + proof (must-fix #1 / AC-5)
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a caller-supplied data source in a read-only Proxy. Any write — property
+ * set, delete, or defineProperty — is RECORDED (the attempt count increments) and
+ * then THROWN, so production data cannot be mutated through the handle. This is the
+ * real enforcement primitive behind the Notary's read-only proof: `mutated` is
+ * COMPUTED from observed write attempts, not asserted as a hardcoded literal.
+ */
+export function createReadOnlyGuard(target, onAttempt) {
+    let attempts = 0;
+    const block = (operation) => {
+        attempts += 1;
+        onAttempt?.(operation);
+        throw new TypeError(`[Notary] read-only violation: ${operation} is forbidden on guarded production data`);
+    };
+    const handle = new Proxy(target, {
+        set: (_t, prop) => block(`set ${String(prop)}`),
+        deleteProperty: (_t, prop) => block(`delete ${String(prop)}`),
+        defineProperty: (_t, prop) => block(`defineProperty ${String(prop)}`),
+    });
+    return { handle, mutationAttempts: () => attempts };
+}
+/**
+ * Build the read-only proof from the number of write attempts the session observed
+ * through its guard(s). `mutated` is true iff a write was attempted (and blocked);
+ * the object is frozen so the proof itself cannot be altered after the fact.
+ */
+function makeReadOnlyProof(mutationAttempts) {
+    const proof = {
+        mutated: mutationAttempts > 0,
+        mutationAttempts,
+        frozen: true,
+    };
+    Object.freeze(proof);
+    return proof;
+}
+/**
+ * A single data-integrity assessment session.
+ *
+ * Design intent:
+ *   - The session is the "composing layer": callers feed it the outputs of engine
+ *     agents (#14/#43/#44/#45) plus domain-specific fixtures/snapshots.
+ *   - The session itself is pure / event-driven — it holds no database connections.
+ *   - All methods are read-only with respect to production data. The session
+ *     accumulates observations then produces a final report.
+ *
+ * Read-only contract: every method observes but does not write. The `readOnlyProof`
+ * on the report is a frozen object — any runtime mutation attempt throws.
+ *
+ * Engine-reuse boundary: callers (or integration tests) supply Finding[] from the
+ * real engine agents via ingestEngineFindings(). This module composes, not replaces.
+ */
+export class DataIntegritySession {
+    sessionId;
+    startedAtMs;
+    clock;
+    auditLog;
+    // Accumulated observations
+    _refViolations = [];
+    _crossStoreInconsistencies = [];
+    _reconciliationSnapshots = [];
+    _backupVerifications = [];
+    _distributionAnomalies = [];
+    _engineFindings = [];
+    _corruptionTraces = [];
+    /** Count of write attempts observed (and blocked) through guard() — backs the read-only proof. */
+    _mutationAttempts = 0;
+    constructor(options) {
+        this.clock = options?.clock ?? (() => Date.now());
+        this.sessionId = options?.sessionId ?? `notary-${this.clock()}`;
+        this.startedAtMs = this.clock();
+        this.auditLog = new TamperEvidentLog({ clock: this.clock });
+    }
+    // ------------------------------------------------------------------
+    // Ingest engine-agent findings (composition — not re-implementation)
+    // ------------------------------------------------------------------
+    /**
+     * Ingest Finding[] from engine agents #14, #43, #44, or #45.
+     * Findings are never mutated; they are stored by reference and
+     * surfaced verbatim in the report.
+     *
+     * Must-fix #3: each finding is logged under its correct IntegrityEventType
+     * based on the source engine agent's ID, not uniformly as 'ref-integrity-violation'.
+     *
+     * Engine-reuse proof: the agentId on each finding must match the originating
+     * engine agent (14, 43, 44, or 45). The audit log records the correct category.
+     */
+    ingestEngineFindings(findings) {
+        for (const f of findings) {
+            this._engineFindings.push(f);
+            const eventType = engineFindingToEventType(f);
+            this.auditLog.append(eventType, `agent:${f.agentId}:${f.id}`, f.severity, f.description);
+        }
+    }
+    /**
+     * Wrap a live production data source in a read-only guard before the session reads
+     * from it. Any write attempted through the returned handle is blocked (throws) and
+     * recorded — surfacing as readOnlyProof.mutated=true on the report. The Notary
+     * itself never writes, so a clean run reports mutated=false honestly.
+     */
+    guard(source) {
+        return createReadOnlyGuard(source, () => {
+            this._mutationAttempts += 1;
+        }).handle;
+    }
+    // ------------------------------------------------------------------
+    // Ref-integrity
+    // ------------------------------------------------------------------
+    checkRefIntegrity(assertions, keyExists, keys) {
+        const violations = detectRefIntegrityViolations(assertions, keyExists, keys, this.clock);
+        for (const v of violations) {
+            this._refViolations.push(v);
+            this.auditLog.append('ref-integrity-violation', `${v.assertion.sourceEntity}.${v.assertion.sourceField}=${v.orphanedKey}`, 'high', `Orphaned key "${v.orphanedKey}" has no matching ${v.assertion.targetEntity} record`);
+        }
+        return violations;
+    }
+    // ------------------------------------------------------------------
+    // Cross-store consistency
+    // ------------------------------------------------------------------
+    checkCrossStoreConsistency(checks) {
+        const inconsistencies = detectCrossStoreInconsistencies(checks, this.clock);
+        for (const inc of inconsistencies) {
+            this._crossStoreInconsistencies.push(inc);
+            this.auditLog.append('cross-store-inconsistency', `${inc.check.entityType}:${inc.check.entityId} vs ${inc.check.secondaryStore}`, 'high', `Primary and secondary store values differ for entity ${inc.check.entityId}`);
+        }
+        return inconsistencies;
+    }
+    // ------------------------------------------------------------------
+    // Reconciliation
+    // ------------------------------------------------------------------
+    runReconciliation(assertion, expectedValue, observedValue, toleranceAbsolute = 0) {
+        const snapshot = reconcile(assertion, expectedValue, observedValue, toleranceAbsolute, this.clock);
+        this._reconciliationSnapshots.push(snapshot);
+        if (snapshot.isBreak) {
+            this.auditLog.append('reconciliation-break', assertion.label, 'critical', `Reconciliation break: expected=${expectedValue} observed=${observedValue} delta=${snapshot.delta}`);
+        }
+        return snapshot;
+    }
+    // ------------------------------------------------------------------
+    // Backup verification (must-fix #2)
+    // ------------------------------------------------------------------
+    /**
+     * Verify a backup against RPO and restore-test requirements.
+     *
+     * Must-fix #2: if no restoreTestedAtMs is provided, the backup is logged as
+     * 'backup-restore-untested' in the audit trail regardless of status. A backup
+     * with no confirmed restore-test is NOT considered fully verified.
+     */
+    verifyBackup(name, backupTimestampMs, status, rpoTargetMs, restoreTestedAtMs) {
+        const result = verifyBackup(name, backupTimestampMs, status, rpoTargetMs, restoreTestedAtMs, this.clock);
+        this._backupVerifications.push(result);
+        if (restoreTestedAtMs === undefined && status === 'verified') {
+            // Fail-closed: backup claims to be verified but was never restore-tested.
+            // Log as an explicit warning — this is an incomplete verification.
+            this.auditLog.append('backup-restore-untested', `backup:${name}`, 'high', `Backup "${name}" status=verified but NO restore-test has been performed. ` +
+                `RPO verification is INCOMPLETE without a confirmed restore.`);
+        }
+        else {
+            const eventType = status === 'verified'
+                ? 'backup-verified'
+                : status === 'missing'
+                    ? 'backup-missing'
+                    : 'backup-stale';
+            this.auditLog.append(eventType, `backup:${name}`, result.rpoSatisfied ? 'info' : 'high', result.rpoSatisfied
+                ? `Backup "${name}" verified and within RPO (${rpoTargetMs}ms)`
+                : `Backup "${name}" FAILS RPO — status=${status}`);
+        }
+        return result;
+    }
+    // ------------------------------------------------------------------
+    // Distribution anomalies
+    // ------------------------------------------------------------------
+    checkDistribution(stats, options) {
+        const anomalies = detectDistributionAnomalies(stats, options, this.clock);
+        for (const anomaly of anomalies) {
+            this._distributionAnomalies.push(anomaly);
+            this.auditLog.append('distribution-anomaly', `${anomaly.stats.entityType}.${anomaly.stats.field}`, 'medium', anomaly.detail);
+        }
+        return anomalies;
+    }
+    // ------------------------------------------------------------------
+    // Lineage / corruption tracing
+    // ------------------------------------------------------------------
+    traceCorruption(graph, corruptedNodeId) {
+        const trace = traceCorruption(graph, corruptedNodeId);
+        if (trace !== undefined) {
+            this._corruptionTraces.push(trace);
+            const candidateIds = trace.rootCauseCandidates.map((n) => n.id).join(', ');
+            this.auditLog.append('lineage-corruption-traced', corruptedNodeId, 'critical', `Corruption at "${corruptedNodeId}" traced; root-cause candidates: [${candidateIds}]. ` +
+                `Heuristic primary: "${trace.rootCauseNode.id}"`);
+        }
+        return trace;
+    }
+    // ------------------------------------------------------------------
+    // Audit-chain integrity check
+    // ------------------------------------------------------------------
+    /**
+     * Verify the internal hash chain. Returns `true` if intact.
+     * Call this after all checks to detect any in-process tampering.
+     */
+    verifyAuditChain() {
+        return this.auditLog.verify();
+    }
+    /**
+     * Expose the raw audit log entries (for tests and dashboards).
+     */
+    get auditEntries() {
+        return this.auditLog.log;
+    }
+    /**
+     * Expose the TamperEvidentLog instance for direct tampering in tests.
+     * Must-fix #4: integration tests need to tamper a REAL audit entry and
+     * assert buildReport().auditChainIntact === false.
+     */
+    get _auditLog() {
+        return this.auditLog;
+    }
+    // ------------------------------------------------------------------
+    // Report
+    // ------------------------------------------------------------------
+    /**
+     * Finalise the session and return the integrity report.
+     *
+     * The returned report is a snapshot. It is deeply immutable by convention:
+     * all arrays are sliced, and `readOnlyProof` is a frozen object with mutated:false.
+     *
+     * Must-fix #1: readOnlyProof is produced by makeReadOnlyProof() which freezes the
+     * object — runtime write attempts throw in strict mode.
+     *
+     * Escalation guidance:
+     *   - If `report.summary.requiresEscalation` is true, route to the Harness.
+     *   - NEVER auto-repair; the Notary only observes and alerts.
+     */
+    buildReport() {
+        const reconciliationBreaks = this._reconciliationSnapshots.filter((s) => s.isBreak);
+        const summary = buildSummary(this._refViolations, this._crossStoreInconsistencies, reconciliationBreaks, this._backupVerifications, this._distributionAnomalies, this._engineFindings);
+        // Read-only proof computed from observed (and blocked) write attempts — frozen.
+        const readOnlyProof = makeReadOnlyProof(this._mutationAttempts);
+        return {
+            sessionId: this.sessionId,
+            startedAtMs: this.startedAtMs,
+            completedAtMs: this.clock(),
+            refViolations: this._refViolations.slice(),
+            crossStoreInconsistencies: this._crossStoreInconsistencies.slice(),
+            reconciliationSnapshots: this._reconciliationSnapshots.slice(),
+            backupVerifications: this._backupVerifications.slice(),
+            distributionAnomalies: this._distributionAnomalies.slice(),
+            engineFindings: this._engineFindings.slice(),
+            corruptionTraces: this._corruptionTraces.slice(),
+            auditChainIntact: this.verifyAuditChain(),
+            readOnlyProof,
+            summary,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Tamper-detection helper for external audit logs
+// ---------------------------------------------------------------------------
+/**
+ * Re-verify an externally provided audit-log snapshot (e.g. loaded from immudb
+ * or serialised from a previous run). Returns `false` if any entry was altered.
+ *
+ * This function is pure: it has no side effects and makes no mutations.
+ */
+export function verifyAuditLogSnapshot(entries, expectedAnchor) {
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.seq !== i || entry.prevHash !== prev)
+            return false;
+        const { hash, ...partial } = entry;
+        if (hashAuditEntry(partial) !== hash)
+            return false;
+        prev = hash;
+    }
+    // Anchor check catches tail-truncation (a shorter still-valid chain) and head drift
+    // that the per-entry loop alone cannot detect.
+    if (expectedAnchor !== undefined) {
+        const headHash = entries.length === 0 ? GENESIS_HASH : entries[entries.length - 1].hash;
+        if (entries.length !== expectedAnchor.length || headHash !== expectedAnchor.headHash) {
+            return false;
+        }
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Finding builder (for integration with the Finding pipeline)
+// ---------------------------------------------------------------------------
+/**
+ * Convert a DataIntegrityReport into a flat Finding[] for ingestion into the
+ * pipeline's standard reporting layer (#1 dashboard, #7 financial, #25 knowledge).
+ *
+ * Only violations / breaks / failures generate findings; "all-clear" observations
+ * are omitted to keep the findings list signal-only.
+ */
+export function reportToFindings(report) {
+    const findings = [];
+    for (const v of report.refViolations) {
+        findings.push({
+            id: `${AGENT_ID}-ref-violation-${v.orphanedKey}`,
+            type: 'code-bug-logic',
+            severity: 'high',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: `Referential-integrity violation: ${v.assertion.sourceEntity}.${v.assertion.sourceField} ` +
+                `"${v.orphanedKey}" has no matching ${v.assertion.targetEntity} record`,
+            suggestedFix: 'Identify and remediate orphaned foreign-key references via the Harness (gated, human-approved).',
+        });
+    }
+    for (const inc of report.crossStoreInconsistencies) {
+        findings.push({
+            id: `${AGENT_ID}-cross-store-${inc.check.entityType}-${inc.check.entityId}-${inc.check.secondaryStore}`,
+            type: 'code-bug-logic',
+            severity: 'high',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: `Cross-store inconsistency: ${inc.check.entityType} id=${inc.check.entityId} ` +
+                `differs between primary and ${inc.check.secondaryStore}`,
+            suggestedFix: 'Investigate cache/index invalidation; do not auto-repair without human approval via the Harness.',
+        });
+    }
+    for (const snap of report.reconciliationSnapshots) {
+        if (!snap.isBreak)
+            continue;
+        findings.push({
+            id: `${AGENT_ID}-reconciliation-break-${snap.assertion.label}`,
+            type: 'code-bug-logic',
+            severity: 'critical',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: `Reconciliation break on "${snap.assertion.label}": ` +
+                `expected=${snap.expectedValue} observed=${snap.observedValue} delta=${snap.delta}`,
+            suggestedFix: 'Route to financial reconciliation agent #7 and escalate via the Harness for human review.',
+        });
+    }
+    for (const bv of report.backupVerifications) {
+        if (bv.rpoSatisfied && bv.restoreVerified)
+            continue;
+        if (!bv.rpoSatisfied) {
+            findings.push({
+                id: `${AGENT_ID}-backup-rpo-${bv.name}`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: AGENT_ID,
+                module: MODULE,
+                description: `Backup "${bv.name}" fails RPO: status=${bv.status} rpoTarget=${bv.rpoTargetMs}ms`,
+                suggestedFix: 'Verify backup pipeline and confirm restore-test. Escalate to DR agent #23 via the Harness.',
+            });
+        }
+        else if (!bv.restoreVerified) {
+            // must-fix #2: RPO is satisfied but no restore-test was performed
+            findings.push({
+                id: `${AGENT_ID}-backup-restore-untested-${bv.name}`,
+                type: 'infra-issue',
+                severity: 'high',
+                agentId: AGENT_ID,
+                module: MODULE,
+                description: `Backup "${bv.name}" is within RPO but has no confirmed restore-test. ` +
+                    `Cannot assert recoverability without a restore-test.`,
+                suggestedFix: 'Perform a restore-test to a timestamped snapshot. Confirm the restore via DR agent #23.',
+            });
+        }
+    }
+    for (const anomaly of report.distributionAnomalies) {
+        findings.push({
+            id: `${AGENT_ID}-distribution-${anomaly.anomalyType}-${anomaly.stats.entityType}-${anomaly.stats.field}`,
+            type: 'code-bug-logic',
+            severity: 'medium',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: anomaly.detail,
+            suggestedFix: 'Investigate data pipelines for the affected field; review recent migrations or ingestion jobs.',
+        });
+    }
+    for (const trace of report.corruptionTraces) {
+        const candidateNote = trace.rootCauseCandidates.length > 1
+            ? ` (${trace.rootCauseCandidates.length} candidates: ${trace.rootCauseCandidates.map((n) => n.id).join(', ')}; heuristic primary selected)`
+            : '';
+        findings.push({
+            id: `${AGENT_ID}-lineage-corruption-${trace.observedAt}`,
+            type: 'code-bug-logic',
+            severity: 'critical',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: `Data corruption at "${trace.observedAt}" traced to root-cause node "${trace.rootCauseNode.id}"` +
+                `${candidateNote} via ${trace.lineagePath.length}-step lineage path`,
+            suggestedFix: `Investigate data origin node "${trace.rootCauseNode.label}". ` +
+                'Route remediation through the Harness with human approval.',
+        });
+    }
+    if (!report.auditChainIntact) {
+        findings.push({
+            id: `${AGENT_ID}-audit-tampering`,
+            type: 'code-bug-security',
+            severity: 'critical',
+            agentId: AGENT_ID,
+            module: MODULE,
+            description: 'AUDIT LOG TAMPERING DETECTED: the hash chain is broken. ' +
+                'One or more audit entries have been altered since they were written.',
+            suggestedFix: 'Immediately escalate to security (#2/#18). Preserve the raw log for forensic analysis.',
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=data-integrity.js.map