@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.10

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -0,0 +1,814 @@
+import { readCommittedEvents, readTypedEventStoreFromJsonl, writeTypedEventStoreJsonl, } from "./frontend-typed-event-store.js";
+import { adoptTypedEventFact, stageTypedEventFact, } from "./frontend-typed-event-transaction.js";
+import { canonicalNodeOutput } from "./node-execution.js";
+import { createDagEventObserver } from "./event-observer.js";
+import { extractFrontendImplementationJson } from "./frontend-implementation-contract.js";
+/**
+ * M2 shadow dual write (AC-001 / AC-002).
+ *
+ * The three read-only frontend nodes keep their authoritative text/JSON output
+ * protocols untouched. This module derives schema-valid shadow facts from those
+ * outputs and submits them through the M1 typed event store for audit and
+ * deterministic difference comparison only. Shadow facts never participate in
+ * writer admission and never control a DAG branch (M3 is the authority switch).
+ *
+ * Failure isolation (AC-001): every parse, stage, and adopt is swallowed, so a
+ * shadow-channel failure can never fail the producing node. The canonical event
+ * JSONL, when requested, is delegated to `createDagEventObserver`.
+ */
+export const SHADOW_FACT_ORIGINS = ["contract", "scout", "plan"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => asString(item))
+        .filter((item) => item.length > 0);
+}
+/** Deterministic, sorted, de-duplicated string set. Lexicographic order only;
+ * never locale/Date-dependent so diff output is reproducible. */
+function canonicalStringSet(values) {
+    return [
+        ...new Set(values
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0)),
+    ].sort();
+}
+/* ------------------------------------------------------------------ *
+ * Contract Markdown parser (authoritative Markdown contract).         *
+ * ------------------------------------------------------------------ */
+const REQUIREMENT_ID_PATTERN = /(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*/i;
+function classifyContractHeading(heading) {
+    const normalized = heading.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ");
+    if (normalized.includes("non goal"))
+        return "non-goal";
+    if (normalized.includes("acceptance"))
+        return "acceptance";
+    if (normalized.includes("open question"))
+        return "open-question";
+    if (normalized.includes("risk"))
+        return "risk";
+    if (normalized.includes("constraint"))
+        return "constraint";
+    if (normalized.includes("split"))
+        return "split";
+    if (normalized.includes("scope"))
+        return "scope";
+    return undefined;
+}
+function extractRequirementId(text) {
+    const match = REQUIREMENT_ID_PATTERN.exec(text);
+    return match ? match[0].toUpperCase() : undefined;
+}
+function extractBulletItems(sectionText) {
+    const items = [];
+    for (const rawLine of sectionText.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const stripped = line.replace(/^(?:[-*+]|\d+[.)])\s*/, "").trim();
+        if (!stripped)
+            continue;
+        items.push(stripped);
+    }
+    return items;
+}
+function buildContractFact(section, item) {
+    switch (section) {
+        case "scope":
+        case "acceptance":
+            return {
+                kind: "requirement",
+                origin: "contract",
+                id: extractRequirementId(item) ?? item,
+                text: item,
+            };
+        case "non-goal":
+            return {
+                kind: "constraint",
+                origin: "contract",
+                category: "non-goal",
+                text: item,
+            };
+        case "constraint":
+            return {
+                kind: "constraint",
+                origin: "contract",
+                category: "constraint",
+                text: item,
+            };
+        case "risk":
+            return {
+                kind: "constraint",
+                origin: "contract",
+                category: "risk",
+                text: item,
+            };
+        case "open-question":
+            return { kind: "open-question", origin: "contract", text: item };
+        case "split":
+            return { kind: "split-proposal", origin: "contract", text: item };
+    }
+}
+export function parseContractFacts(text) {
+    const facts = [];
+    const lines = text.split("\n");
+    let current;
+    let buffer = [];
+    const flush = () => {
+        if (!current)
+            return;
+        for (const item of extractBulletItems(buffer.join("\n"))) {
+            facts.push(buildContractFact(current, item));
+        }
+        buffer = [];
+    };
+    for (const rawLine of lines) {
+        const line = rawLine.trimEnd();
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line.trim());
+        if (heading) {
+            flush();
+            current = classifyContractHeading(heading[1]);
+            continue;
+        }
+        if (current)
+            buffer.push(line);
+    }
+    flush();
+    return facts;
+}
+/* ------------------------------------------------------------------ *
+ * TARGET_SURFACE parser (authoritative scout text).                    *
+ * ------------------------------------------------------------------ */
+const TARGET_SURFACE_LABELS = [
+    "entrypoint",
+    "routeOrMount",
+    "implementationPaths",
+    "testPaths",
+    "dataSource",
+    "allowedPathConflicts",
+];
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function splitListValue(raw) {
+    const cleaned = raw.replace(/^\[|\]$/g, "").trim();
+    if (!cleaned)
+        return [];
+    return cleaned
+        .split(/[,\n]/)
+        .map((item) => item
+        .trim()
+        .replace(/^[-*+]\s+/, "")
+        .replace(/^["']|["']$/g, ""))
+        .filter((item) => item.length > 0);
+}
+function parseTargetSurfaceLabels(text) {
+    const result = {};
+    const sectionStart = text.indexOf("TARGET_SURFACE");
+    if (sectionStart < 0) {
+        for (const label of TARGET_SURFACE_LABELS)
+            result[label] = "";
+        return result;
+    }
+    const section = text.slice(sectionStart);
+    const positions = [];
+    for (const label of TARGET_SURFACE_LABELS) {
+        const match = new RegExp(`\\b${escapeRegex(label)}\\s*(?::|\\s)`).exec(section);
+        if (match && match.index !== undefined) {
+            positions.push({ label, index: match.index });
+        }
+    }
+    positions.sort((a, b) => a.index - b.index);
+    for (let i = 0; i < positions.length; i += 1) {
+        const current = positions[i];
+        const colon = section.indexOf(":", current.index);
+        const valueStart = colon >= 0 && colon < (positions[i + 1]?.index ?? section.length)
+            ? colon + 1
+            : current.index + current.label.length;
+        const valueEnd = i + 1 < positions.length ? positions[i + 1].index : section.length;
+        result[current.label] = section.slice(valueStart, valueEnd).trim();
+    }
+    for (const label of TARGET_SURFACE_LABELS) {
+        result[label] ??= "";
+    }
+    return result;
+}
+export function parseTargetSurfaceFacts(text) {
+    const values = parseTargetSurfaceLabels(text);
+    const implementationPaths = canonicalStringSet(splitListValue(values.implementationPaths));
+    const testPaths = canonicalStringSet(splitListValue(values.testPaths));
+    const allowedPathConflicts = canonicalStringSet(splitListValue(values.allowedPathConflicts));
+    return [
+        {
+            kind: "target-surface",
+            origin: "scout",
+            entrypoint: asString(values.entrypoint),
+            routeOrMount: asString(values.routeOrMount),
+            implementationPaths,
+            testPaths,
+            dataSource: asString(values.dataSource),
+            allowedPathConflicts,
+        },
+        {
+            kind: "design-evidence",
+            origin: "scout",
+            source: "TARGET_SURFACE",
+            paths: canonicalStringSet([...implementationPaths, ...testPaths]),
+            conflicts: allowedPathConflicts,
+        },
+    ];
+}
+export const PLAN_LEDGER_FACT_KINDS = [
+    "target-surface",
+    "component-choice",
+    "state-flow",
+    "data-flow",
+    "mock-api",
+    "design-deviation",
+    "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
+];
+function skeletonTargetFiles(skeleton) {
+    if (!isRecord(skeleton))
+        return [];
+    const targets = isRecord(skeleton.targets) ? skeleton.targets : undefined;
+    return canonicalStringSet(asStringArray(targets?.files));
+}
+/** Restore the editable RFC 7386 plan patch from a committed plan ledger.
+ * Production compile authority is the tool payload (`patch` on any committed
+ * plan fact, else a `target-surface.patch`). Text JSON is never the compile
+ * authority. */
+export function restorePlanPatchFromCommittedFacts(records) {
+    const planFacts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => isRecord(fact) &&
+        fact.origin === "plan" &&
+        typeof fact.kind === "string" &&
+        PLAN_LEDGER_FACT_KINDS.includes(fact.kind));
+    if (planFacts.length === 0)
+        return undefined;
+    for (const fact of planFacts) {
+        if (isRecord(fact.patch))
+            return fact.patch;
+    }
+    return undefined;
+}
+/**
+ * A+B (AC-004): reverse of `planLedgerFactsFromPatch` for the incremental
+ * `record_*` tool flow. Reconstructs the canonical editable patch from the raw
+ * fields each `record_*` tool committed. `finalize_plan` calls this and then
+ * re-publishes the assembled patch onto a `target-surface` fact so the
+ * writeSet-external compile authority (`frontend-implementation-contract.ts`)
+ * can still restore a plain `patch` object.
+ */
+export function assemblePlanPatchFromCommittedFacts(records, contractRequirements) {
+    const facts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => isRecord(fact) &&
+        fact.origin === "plan" &&
+        typeof fact.kind === "string" &&
+        PLAN_LEDGER_FACT_KINDS.includes(fact.kind));
+    if (facts.length === 0)
+        return undefined;
+    for (const fact of facts) {
+        if (isRecord(fact.patch))
+            return fact.patch;
+    }
+    const patch = {};
+    const targetSurface = facts.find((fact) => fact.kind === "target-surface");
+    if (targetSurface) {
+        const routes = canonicalStringSet(asStringArray(targetSurface.routes));
+        if (routes.length > 0)
+            patch.targets = { routes };
+    }
+    const componentChoices = facts.filter((fact) => fact.kind === "component-choice");
+    const collectedChoices = componentChoices.flatMap((fact) => Array.isArray(fact.uiComponentChoices)
+        ? fact.uiComponentChoices.filter(isRecord)
+        : []);
+    const stylingStrategy = componentChoices
+        .map((fact) => asString(fact.stylingStrategy))
+        .find((value) => value.length > 0);
+    if (collectedChoices.length > 0)
+        patch.uiComponentChoices = collectedChoices;
+    if (stylingStrategy)
+        patch.stylingStrategy = stylingStrategy;
+    const stateFlow = facts.find((fact) => fact.kind === "state-flow");
+    if (stateFlow) {
+        if (Array.isArray(stateFlow.uiStates)) {
+            patch.uiStates = stateFlow.uiStates.filter(isRecord);
+        }
+        if (Array.isArray(stateFlow.interactions)) {
+            patch.interactions = stateFlow.interactions.filter(isRecord);
+        }
+    }
+    const mockApi = facts.find((fact) => fact.kind === "mock-api");
+    if (mockApi && isRecord(mockApi.mockApi)) {
+        patch.mockApi = mockApi.mockApi;
+    }
+    const deviation = facts.find((fact) => fact.kind === "design-deviation");
+    if (deviation) {
+        const conflicts = canonicalStringSet(asStringArray(deviation.conflicts));
+        if (conflicts.length > 0)
+            patch.designEvidence = { conflicts };
+    }
+    const dependency = facts.find((fact) => fact.kind === "dependency");
+    const dependencyPolicy = asString(dependency?.policy);
+    if (dependencyPolicy)
+        patch.dependencyPolicy = dependencyPolicy;
+    // Requirements / verification targets / evidence gaps / implementation
+    // steps arrive as individual facts (one per record_plan_* call) so a large
+    // plan never exceeds a single model output budget. Aggregate them in
+    // ledger order.
+    const requirements = facts
+        .filter((fact) => fact.kind === "plan-requirement")
+        .map((fact) => fact.entry)
+        .filter(isRecord)
+        .map((entry) => {
+        // The canonical contract schema requires a non-empty
+        // expectedOutcome, but the plan should not be forced to re-write
+        // full outcome prose for every requirement (the contract node
+        // already captured requirement semantics). Derive a deterministic
+        // placeholder from the requirement id when omitted.
+        if (isRecord(entry) && !asString(entry.expectedOutcome)) {
+            const id = asString(entry.id) || "requirement";
+            return { ...entry, expectedOutcome: `implied by contract: ${id}` };
+        }
+        return entry;
+    })
+        // Source fidelity ledger (AC-005/AC-006): the contract node declared the
+        // authoritative sourceFragmentIds/sourceRefs for each requirement from
+        // the ledger's requirement→fragment mapping. The plan inherits them by
+        // requirement id so the compiled canonical contract carries the same
+        // provenance evidence without the plan re-deriving (or fabricating) it.
+        .map((entry) => {
+        if (!contractRequirements)
+            return entry;
+        const id = asString(entry.id);
+        if (!id)
+            return entry;
+        const inherited = contractRequirements.get(id);
+        if (!inherited)
+            return entry;
+        const merged = { ...entry };
+        // Inherit the contract-declared provenance only when the plan did
+        // not already declare it (model override wins; missing inherits).
+        if (!Array.isArray(entry.sourceFragmentIds)) {
+            if (inherited.sourceFragmentIds) {
+                merged.sourceFragmentIds = inherited.sourceFragmentIds;
+            }
+        }
+        if (!Array.isArray(entry.sourceRefs)) {
+            if (inherited.sourceRefs) {
+                merged.sourceRefs = inherited.sourceRefs;
+            }
+        }
+        return merged;
+    })
+        // A requirement id is a canonical identity; drop duplicates so the
+        // compiled patch never carries the same requirement twice (the
+        // record_plan_requirement tool rejects re-records, this dedupes any
+        // legacy/edge duplicates at the compile authority).
+        .filter((entry, index, all) => all.findIndex((other) => asString(other.id) === asString(entry.id)) === index);
+    if (requirements.length > 0)
+        patch.requirements = requirements;
+    const verificationTargets = facts
+        .filter((fact) => fact.kind === "plan-verification-target")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (verificationTargets.length > 0) {
+        patch.verificationTargets = verificationTargets;
+    }
+    const evidenceGaps = facts
+        .filter((fact) => fact.kind === "plan-evidence-gap")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (evidenceGaps.length > 0)
+        patch.evidenceGaps = evidenceGaps;
+    return Object.keys(patch).length > 0 ? patch : undefined;
+}
+/** Derive the 7 origin=plan ledger facts from an editable patch. Skeleton
+ * `targets.files` fills `target-surface.files` because the patch must not
+ * write that protected path. */
+export function planLedgerFactsFromPatch(patch, skeleton) {
+    const record = isRecord(patch) ? patch : undefined;
+    if (!record) {
+        throw new Error("frontend plan ledger requires an editable RFC 7386 patch object");
+    }
+    const facts = [];
+    const targets = isRecord(record.targets) ? record.targets : undefined;
+    const files = canonicalStringSet([
+        ...asStringArray(targets?.files),
+        ...skeletonTargetFiles(skeleton),
+    ]);
+    const routes = canonicalStringSet(asStringArray(targets?.routes));
+    facts.push({
+        kind: "target-surface",
+        origin: "plan",
+        files,
+        routes,
+        patch: record,
+    });
+    const uiComponentChoices = Array.isArray(record.uiComponentChoices)
+        ? record.uiComponentChoices.filter(isRecord)
+        : [];
+    const components = canonicalStringSet(uiComponentChoices.map((choice) => asString(choice.component)));
+    const stylingStrategy = asString(record.stylingStrategy);
+    if (components.length > 0 || stylingStrategy) {
+        facts.push({
+            kind: "component-choice",
+            origin: "plan",
+            components,
+            ...(stylingStrategy ? { stylingStrategy } : {}),
+        });
+    }
+    const uiStates = Array.isArray(record.uiStates)
+        ? record.uiStates.filter(isRecord)
+        : [];
+    const interactions = Array.isArray(record.interactions)
+        ? record.interactions.filter(isRecord)
+        : [];
+    const stateNames = canonicalStringSet(uiStates.map((state) => asString(state.name)));
+    const interactionNames = canonicalStringSet(interactions.map((interaction) => asString(interaction.name)));
+    if (stateNames.length > 0 || interactionNames.length > 0) {
+        facts.push({
+            kind: "state-flow",
+            origin: "plan",
+            states: stateNames,
+            interactions: interactionNames,
+        });
+    }
+    const mockApi = isRecord(record.mockApi) ? record.mockApi : undefined;
+    const endpoints = Array.isArray(mockApi?.endpoints)
+        ? mockApi.endpoints.filter(isRecord)
+        : [];
+    const endpointPaths = canonicalStringSet(endpoints.map((endpoint) => `${asString(endpoint.method)} ${asString(endpoint.path)}`.trim()));
+    if (interactionNames.length > 0 || endpointPaths.length > 0) {
+        facts.push({
+            kind: "data-flow",
+            origin: "plan",
+            interactions: interactionNames,
+            endpoints: endpointPaths,
+        });
+    }
+    if (mockApi) {
+        facts.push({
+            kind: "mock-api",
+            origin: "plan",
+            strategy: asString(mockApi.strategy),
+            endpoints: endpointPaths,
+        });
+    }
+    const designEvidence = isRecord(record.designEvidence)
+        ? record.designEvidence
+        : undefined;
+    const conflicts = canonicalStringSet(asStringArray(designEvidence?.conflicts));
+    if (conflicts.length > 0) {
+        facts.push({ kind: "design-deviation", origin: "plan", conflicts });
+    }
+    const dependencyPolicy = asString(record.dependencyPolicy);
+    if (dependencyPolicy) {
+        facts.push({ kind: "dependency", origin: "plan", policy: dependencyPolicy });
+    }
+    return facts;
+}
+/** Map committed plan facts, else a test-helper JSON patch, into the 7
+ * origin=plan kinds. Production compile authority is the committed ledger;
+ * a missing ledger/patch throws instead of returning a fake empty book. */
+export function parsePlanLedgerFacts(textOrRecords, skeleton) {
+    if (typeof textOrRecords !== "string") {
+        const fromFacts = planLedgerFactsFromCommittedRecords(textOrRecords);
+        if (fromFacts.length > 0)
+            return fromFacts;
+        throw new Error("frontend plan ledger missing: no committed origin=plan facts");
+    }
+    const text = textOrRecords;
+    const jsonlLines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const looksLikeJsonlLedger = jsonlLines.length > 0 &&
+        jsonlLines.every((line) => {
+            try {
+                const record = JSON.parse(line);
+                return (isRecord(record) &&
+                    record.phase === "committed" &&
+                    isRecord(record.fact) &&
+                    typeof record.eventId === "string");
+            }
+            catch {
+                return false;
+            }
+        });
+    if (looksLikeJsonlLedger) {
+        const records = jsonlLines.map((line) => JSON.parse(line));
+        const fromFacts = planLedgerFactsFromCommittedRecords(records);
+        if (fromFacts.length > 0)
+            return fromFacts;
+    }
+    let value;
+    try {
+        value = extractFrontendImplementationJson(text);
+    }
+    catch {
+        throw new Error("frontend plan ledger missing: no committed plan facts");
+    }
+    return planLedgerFactsFromPatch(value, skeleton);
+}
+function planLedgerFactsFromCommittedRecords(records) {
+    const restored = restorePlanPatchFromCommittedFacts(records);
+    if (restored)
+        return planLedgerFactsFromPatch(restored);
+    return records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => isRecord(fact) &&
+        fact.origin === "plan" &&
+        typeof fact.kind === "string" &&
+        PLAN_LEDGER_FACT_KINDS.includes(fact.kind))
+        .map((fact) => fact);
+}
+export async function loadCommittedPlanLedgerFacts(runDir, nodeId = "frontend-plan-pi") {
+    const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");
+    const pathMod = await import("node:path");
+    return readTypedEventStoreFromJsonl(pathMod.join(runDir, nodeId, "plan-typed-facts.jsonl"));
+}
+/** A+B (AC-001/003): read only the committed-phase origin facts from a node's
+ * typed event store JSONL. Staged/quarantined records never leak downstream. */
+export async function readCommittedOriginFacts(runDir, nodeId, fileName) {
+    const pathMod = await import("node:path");
+    const records = await readTypedEventStoreFromJsonl(pathMod.join(runDir, nodeId, fileName));
+    return records.filter((record) => record.phase === "committed");
+}
+function latestCommittedScoutTargetSurface(records) {
+    return records
+        .filter((record) => record.phase === "committed" &&
+        isRecord(record.fact) &&
+        record.fact.origin === "scout" &&
+        record.fact.kind === "target-surface")
+        .at(-1)?.fact;
+}
+/**
+ * Scout owns discovery. A complete fact must explicitly say so, name at least
+ * one target candidate, leave no unresolved paths, and include fresh runtime
+ * evidence for a named target file. This deliberately accepts an empty test
+ * path list: some small changes have no existing focused test file, but they
+ * still need a proven implementation entrypoint.
+ */
+export function readCompleteScoutTargetSurface(records) {
+    const fact = latestCommittedScoutTargetSurface(records);
+    if (!fact)
+        return {
+            ok: false,
+            reason: "frontend scout facts missing: no committed target-surface fact",
+        };
+    if (fact.completeness !== "complete")
+        return {
+            ok: false,
+            reason: "frontend scout target surface is not complete; resolve discovery gaps before Plan",
+        };
+    const unresolvedPaths = asStringArray(fact.unresolvedPaths);
+    if (unresolvedPaths.length > 0)
+        return {
+            ok: false,
+            reason: `frontend scout target surface has unresolved paths: ${unresolvedPaths.join(", ")}`,
+        };
+    const surface = {
+        entrypoint: asString(fact.entrypoint),
+        implementationPaths: canonicalStringSet(asStringArray(fact.implementationPaths)),
+        testPaths: canonicalStringSet(asStringArray(fact.testPaths)),
+    };
+    const namedPaths = canonicalStringSet([
+        ...(surface.entrypoint ? [surface.entrypoint] : []),
+        ...surface.implementationPaths,
+        ...surface.testPaths,
+    ]);
+    if (namedPaths.length === 0)
+        return {
+            ok: false,
+            reason: "frontend scout target surface is incomplete: name an entrypoint, implementation path, or test path",
+        };
+    const freshPaths = new Set(Array.isArray(fact.pathEvidence)
+        ? fact.pathEvidence
+            .filter(isRecord)
+            .filter((item) => item.fresh === true)
+            .map((item) => asString(item.path))
+            .filter(Boolean)
+        : []);
+    if (!namedPaths.some((candidate) => freshPaths.has(candidate)))
+        return {
+            ok: false,
+            reason: "frontend scout target surface lacks fresh runtime evidence for a named target path",
+        };
+    return { ok: true, surface };
+}
+/** Paths with Scout ownership that Plan may read for a specific decision. */
+export function scoutConfirmedReadPaths(records) {
+    const checked = readCompleteScoutTargetSurface(records);
+    if (!checked.ok)
+        return [];
+    return canonicalStringSet([
+        ...(checked.surface.entrypoint ? [checked.surface.entrypoint] : []),
+        ...checked.surface.implementationPaths,
+        ...checked.surface.testPaths,
+    ]);
+}
+/** A+B (AC-001/003): fail-closed committed contract/scout fact prerequisites.
+ * `contract` requires a committed `contract-finalized` terminal fact; `scout`
+ * requires a complete target-surface fact. Missing or incomplete facts block
+ * downstream consumption — never fall back to text parsing. */
+export function checkCommittedOriginFacts(input) {
+    const kinds = new Set(input.records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact.kind)
+        .filter((kind) => typeof kind === "string"));
+    if (input.origin === "contract") {
+        return kinds.has("contract-finalized")
+            ? { ok: true }
+            : {
+                ok: false,
+                reason: "frontend contract facts missing: no committed contract-finalized terminal fact",
+            };
+    }
+    if (input.origin === "scout") {
+        if (!kinds.has("target-surface"))
+            return {
+                ok: false,
+                reason: "frontend scout facts missing: no committed target-surface fact",
+            };
+        const checked = readCompleteScoutTargetSurface(input.records);
+        return checked.ok ? { ok: true } : { ok: false, reason: checked.reason };
+    }
+    return { ok: true };
+}
+/* ------------------------------------------------------------------ *
+ * Shadow observer factory.                                            *
+ * ------------------------------------------------------------------ */
+const SHADOW_NODE_PARSERS = {
+    "frontend-contract-pi": parseContractFacts,
+    "frontend-scout-pi": parseTargetSurfaceFacts,
+    "frontend-plan-pi": parsePlanLedgerFacts,
+};
+function isShadowNodeId(nodeId) {
+    return nodeId in SHADOW_NODE_PARSERS;
+}
+function reportError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[frontend-shadow-dual-write] ${context} failed: ${message}\n`);
+}
+export function createShadowDualWriteObserver(options) {
+    const base = options.eventsJsonlPath
+        ? createDagEventObserver({
+            eventsJsonlPath: options.eventsJsonlPath,
+            dagRunId: options.dagRunId,
+            spec: options.spec,
+        })
+        : null;
+    const recordNodeFacts = async (nodeId, state) => {
+        if (!isShadowNodeId(nodeId))
+            return;
+        const text = canonicalNodeOutput(state.nodes[nodeId]);
+        let facts;
+        try {
+            facts = options.parseNodeFacts
+                ? options.parseNodeFacts(nodeId, text)
+                : SHADOW_NODE_PARSERS[nodeId](text);
+        }
+        catch {
+            return;
+        }
+        for (const [index, fact] of facts.entries()) {
+            try {
+                // Deterministic requestId keeps replay idempotent within a node.
+                const requestId = `${options.requestId}:${nodeId}:${fact.kind}:${index}`;
+                const staged = stageTypedEventFact({
+                    store: options.store,
+                    requestId,
+                    attemptId: options.attemptId,
+                    fact,
+                });
+                await adoptTypedEventFact({
+                    store: options.store,
+                    requestId,
+                    attemptId: options.attemptId,
+                    fact,
+                    eventId: staged.eventId,
+                    expectedRevision: options.store.revision,
+                });
+            }
+            catch {
+                // A shadow commit failure never blocks the producing node (AC-001).
+            }
+        }
+    };
+    const observer = {
+        onRunStart: async (state) => {
+            await base?.observer.onRunStart?.(state);
+        },
+        onNodeStart: async (nodeId, state) => {
+            await base?.observer.onNodeStart?.(nodeId, state);
+        },
+        onNodeOutput: async (nodeId, chunk, state) => {
+            await base?.observer.onNodeOutput?.(nodeId, chunk, state);
+        },
+        onNodeFinish: async (nodeId, state) => {
+            try {
+                await recordNodeFacts(nodeId, state);
+            }
+            catch {
+                // Derived view; never affect canonical execution.
+            }
+            await base?.observer.onNodeFinish?.(nodeId, state);
+        },
+        onRunFinish: async (state) => {
+            await base?.observer.onRunFinish?.(state);
+        },
+    };
+    return {
+        observer,
+        flush: async () => {
+            try {
+                const committed = readCommittedEvents(options.store, options.attemptId);
+                await writeTypedEventStoreJsonl(options.shadowStoreJsonlPath, committed);
+            }
+            catch (error) {
+                reportError("flush", error);
+            }
+            await base?.flush();
+        },
+    };
+}
+function compareDimension(factValues, authorityValues) {
+    const facts = canonicalStringSet(factValues);
+    const authority = canonicalStringSet(authorityValues);
+    const matched = facts.filter((item) => authority.includes(item));
+    const factsOnly = facts.filter((item) => !authority.includes(item));
+    const authorityOnly = authority.filter((item) => !facts.includes(item));
+    return { facts, authority, matched, factsOnly, authorityOnly };
+}
+function factFieldStrings(facts, kinds, fields) {
+    const out = [];
+    for (const fact of facts) {
+        if (!kinds.includes(fact.kind))
+            continue;
+        for (const field of fields) {
+            const value = fact[field];
+            if (typeof value === "string")
+                out.push(value);
+            else if (Array.isArray(value))
+                out.push(...asStringArray(value));
+        }
+    }
+    return out;
+}
+export function compareShadowFactsToAuthority(input) {
+    const contractFacts = parseContractFacts(input.contractText);
+    const scoutFacts = parseTargetSurfaceFacts(input.scoutText);
+    const planFacts = parsePlanLedgerFacts(input.planText);
+    const requirementCoverage = compareDimension(factFieldStrings(input.facts, ["requirement"], ["id"]), factFieldStrings(contractFacts, ["requirement"], ["id"]));
+    const targetPaths = compareDimension([
+        ...factFieldStrings(input.facts, ["target-surface"], ["implementationPaths", "testPaths", "files", "routes"]),
+    ], [
+        ...factFieldStrings(scoutFacts, ["target-surface"], ["implementationPaths", "testPaths"]),
+        ...factFieldStrings(planFacts, ["target-surface"], ["files", "routes"]),
+    ]);
+    const componentDecisions = compareDimension(factFieldStrings(input.facts, ["component-choice", "state-flow", "data-flow", "mock-api"], ["components", "stylingStrategy", "states", "interactions", "endpoints", "strategy"]), factFieldStrings(planFacts, ["component-choice", "state-flow", "data-flow", "mock-api"], ["components", "stylingStrategy", "states", "interactions", "endpoints", "strategy"]));
+    const blockers = compareDimension(factFieldStrings(input.facts, ["constraint", "open-question", "design-deviation"], ["text", "conflicts"]), [
+        ...factFieldStrings(contractFacts, ["constraint", "open-question"], ["text"]),
+        ...factFieldStrings(planFacts, ["design-deviation"], ["conflicts"]),
+        ...factFieldStrings(scoutFacts, ["design-evidence"], ["conflicts"]),
+    ]);
+    return { requirementCoverage, targetPaths, componentDecisions, blockers };
+}
+export function renderShadowDiff(result) {
+    const lines = ["# Shadow Dual Write Diff", ""];
+    const sections = [
+        ["Requirement Coverage", result.requirementCoverage],
+        ["Target Paths", result.targetPaths],
+        ["Component Decisions", result.componentDecisions],
+        ["Blockers", result.blockers],
+    ];
+    for (const [title, dimension] of sections) {
+        lines.push(`## ${title}`);
+        lines.push(`- matched: ${dimension.matched.length}`);
+        lines.push(`- factsOnly: ${dimension.factsOnly.length}`);
+        lines.push(`- authorityOnly: ${dimension.authorityOnly.length}`);
+        for (const item of dimension.matched)
+            lines.push(`  - [=] ${item}`);
+        for (const item of dimension.factsOnly)
+            lines.push(`  - [+] ${item}`);
+        for (const item of dimension.authorityOnly)
+            lines.push(`  - [-] ${item}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}