@tea-agent/loop-agent 0.43.0-next.18 → 0.43.0-next.19

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

@@ -1,975 +0,0 @@
-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",
-    "state-registry",
-    "component-choice",
-    "state-flow",
-    "data-flow",
-    "mock-api",
-    "design-deviation",
-    "dependency",
-    "plan-requirement",
-    "plan-verification-target",
-    "plan-evidence-gap",
-    "mock-endpoint",
-];
-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;
-    }
-    // No finalize-published snapshot: the receipt fix loop can end an attempt
-    // before any finalize_plan succeeds while dozens of record_* facts are
-    // already committed. Assemble the patch from those record facts instead of
-    // declaring the ledger missing (r19: "ledger missing" discarded a ledger
-    // with 92 committed facts).
-    return assemblePlanPatchFromCommittedFacts(records);
-}
-/**
- * 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;
-    // Singleton policy facts: the LAST committed fact wins. The model corrects a
-    // rejected plan by re-recording the policy (r18). Requirements / verification
-    // targets / evidence gaps stay additive; component choices accumulate; and
-    // state-flow is merged below by item name so UX-local batches do not erase one
-    // another.
-    const lastByKind = (kind) => {
-        let found;
-        for (const fact of facts) {
-            if (fact.kind === kind)
-                found = fact;
-        }
-        return found;
-    };
-    // Patch snapshots (published by earlier finalize calls) carry no routes;
-    // exclude them so a snapshot cannot shadow the model's route selection.
-    const routeSurface = (() => {
-        let found;
-        for (const fact of facts) {
-            if (fact.kind !== "target-surface" || isRecord(fact.patch))
-                continue;
-            found = fact;
-        }
-        return found;
-    })();
-    const patch = {};
-    const targetSurface = routeSurface;
-    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)
-        : []);
-    // Later corrections supersede earlier submissions per purpose: without
-    // this, a re-recorded choice (fixing a wrong specReference) would appear
-    // twice and the reviewer would still audit the stale entry (r19).
-    const choicesByPurpose = new Map();
-    const dedupedChoices = [];
-    for (const choice of collectedChoices) {
-        const purpose = asString(choice.purpose);
-        if (!purpose) {
-            dedupedChoices.push(choice);
-            continue;
-        }
-        if (choicesByPurpose.has(purpose)) {
-            const at = dedupedChoices.findIndex((existing) => asString(existing.purpose) === purpose);
-            dedupedChoices[at] = choice;
-        }
-        else {
-            choicesByPurpose.set(purpose, choice);
-            dedupedChoices.push(choice);
-        }
-    }
-    const stylingStrategy = componentChoices
-        .map((fact) => asString(fact.stylingStrategy))
-        .find((value) => value.length > 0);
-    if (dedupedChoices.length > 0)
-        patch.uiComponentChoices = dedupedChoices;
-    if (stylingStrategy)
-        patch.stylingStrategy = stylingStrategy;
-    // UX-local batches can emit several state-flow facts. Aggregate by the
-    // stable state/interaction name so a later correction replaces only that
-    // item; last-wins at the whole-fact level silently discarded earlier local
-    // batches when Segment 2 was split (r21).
-    const stateFlows = facts.filter((fact) => fact.kind === "state-flow");
-    const stateByName = new Map();
-    const unnamedStates = [];
-    const interactionByName = new Map();
-    const unnamedInteractions = [];
-    for (const flow of stateFlows) {
-        for (const name of asStringArray(flow.removeUiStateNames))
-            stateByName.delete(name);
-        for (const name of asStringArray(flow.removeInteractionNames))
-            interactionByName.delete(name);
-        for (const state of Array.isArray(flow.uiStates) ? flow.uiStates : []) {
-            if (!isRecord(state))
-                continue;
-            const name = asString(state.name);
-            if (name)
-                stateByName.set(name, state);
-            else
-                unnamedStates.push(state);
-        }
-        for (const interaction of Array.isArray(flow.interactions) ? flow.interactions : []) {
-            if (!isRecord(interaction))
-                continue;
-            const name = asString(interaction.name);
-            if (name)
-                interactionByName.set(name, interaction);
-            else
-                unnamedInteractions.push(interaction);
-        }
-    }
-    if (stateFlows.length > 0) {
-        patch.uiStates = [...stateByName.values(), ...unnamedStates];
-        patch.interactions = [...interactionByName.values(), ...unnamedInteractions];
-    }
-    const mockApi = lastByKind("mock-api");
-    if (!mockApi && facts.some(f => f.kind === "mock-endpoint" && f.removed !== true))
-        throw Error("MOCK_POLICY_MISSING: endpoint has no policy");
-    if (mockApi && isRecord(mockApi.mockApi)) {
-        const endpoints = new Map();
-        for (const endpoint of Array.isArray(mockApi.mockApi.endpoints) ? mockApi.mockApi.endpoints : []) {
-            if (isRecord(endpoint))
-                endpoints.set(`${endpoint.method}:${endpoint.path}`, endpoint);
-        }
-        for (const fact of facts)
-            if (fact.kind === "mock-endpoint" && isRecord(fact.endpoint)) {
-                const key = `${fact.endpoint.method}:${fact.endpoint.path}`;
-                if (fact.removed === true)
-                    endpoints.delete(key);
-                else
-                    endpoints.set(key, fact.endpoint);
-            }
-        if (mockApi.mockApi.strategy === "not-needed" && endpoints.size)
-            throw Error("MOCK_POLICY_CONFLICT: withdraw endpoints before declaring Mock/API not needed");
-        patch.mockApi = { ...mockApi.mockApi, endpoints: [...endpoints.values()] };
-    }
-    const deviation = lastByKind("design-deviation");
-    if (deviation) {
-        const conflicts = canonicalStringSet(asStringArray(deviation.conflicts));
-        if (conflicts.length > 0)
-            patch.designEvidence = { conflicts };
-    }
-    const dependency = lastByKind("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, ...(inherited.text ? { expectedOutcome: inherited.text } : {}), ...(inherited.execution ? { execution: inherited.execution } : {}) };
-        // 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;
-    })
-        .map((entry) => {
-        if (isRecord(entry) && !isRecord(entry.evidenceGap)) {
-            const requirementId = asString(entry.id);
-            const standaloneGap = facts
-                .filter((fact) => fact.kind === "plan-evidence-gap")
-                .map((fact) => fact.entry)
-                .filter(isRecord)
-                .filter((gap) => asString(gap.requirementId) === requirementId)
-                .at(-1);
-            if (standaloneGap && asString(standaloneGap.description)) {
-                return { ...entry, evidenceGap: standaloneGap };
-            }
-        }
-        return entry;
-    })
-        // 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.map((other) => asString(other.id)).lastIndexOf(asString(entry.id)) === index);
-    if (requirements.length > 0)
-        patch.requirements = requirements;
-    const verificationTargetOrder = [];
-    const verificationTargetById = new Map();
-    for (const fact of facts.filter((item) => item.kind === "plan-verification-target")) {
-        const entry = fact.entry;
-        if (!isRecord(entry))
-            continue;
-        const id = asString(entry.id);
-        if (!id)
-            continue;
-        if (!verificationTargetById.has(id))
-            verificationTargetOrder.push(id);
-        verificationTargetById.set(id, entry);
-    }
-    const verificationTargets = verificationTargetOrder
-        .map((id) => verificationTargetById.get(id))
-        .filter((entry) => Boolean(entry))
-        .map((entry) => {
-        // Coverage precedes UX. A later state-flow fact explicitly naming
-        // this VT establishes the reverse binding without another model call.
-        // No path/name heuristics: unbound or ambiguous decisions stay subject
-        // to canonical validation. Recompute from live states after removals.
-        const boundStates = [...stateByName.values()]
-            .filter((state) => state.applicable === true &&
-            asStringArray(state.verificationTargetIds).includes(asString(entry.id)))
-            .map((state) => asString(state.name));
-        if (boundStates.length === 0)
-            return entry;
-        return { ...entry, uiStates: [...new Set([
-                    ...asStringArray(entry.uiStates), ...boundStates,
-                ])].sort() };
-    });
-    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 and leave no unresolved paths. Existing surfaces must
- * include fresh runtime evidence for a named target path. Greenfield
- * surfaces are the one explicit exception: when runtime-injected source
- * declarations prove that every named path was specified by the task source,
- * all paths may be future (not yet on disk). This keeps create-new work
- * possible without allowing Scout to invent an arbitrary path under the
- * writer boundary. An empty test path list remains valid.
- */
-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)
-        : []);
-    const pathEvidence = Array.isArray(fact.pathEvidence)
-        ? fact.pathEvidence.filter(isRecord)
-        : [];
-    const hasSourceDeclarationLedger = Array.isArray(fact.sourceDeclaredPaths);
-    const undeclaredFuturePaths = hasSourceDeclarationLedger
-        ? namedPaths.filter((candidate) => {
-            const evidence = pathEvidence.find((item) => asString(item.path) === candidate);
-            return evidence?.fresh !== true && evidence?.sourceDeclared !== true;
-        })
-        : [];
-    if (undeclaredFuturePaths.length > 0)
-        return {
-            ok: false,
-            reason: `frontend scout target surface has future paths not declared by the task source: ${undeclaredFuturePaths.join(", ")}; test path is not declared by the task source, so do not guess test/ vs tests/ or other target directories`,
-        };
-    if (!namedPaths.some((candidate) => freshPaths.has(candidate))) {
-        const allPathsAreSourceDeclaredFuturePaths = hasSourceDeclarationLedger &&
-            namedPaths.length > 0 &&
-            namedPaths.every((candidate) => {
-                const evidence = pathEvidence.find((item) => asString(item.path) === candidate);
-                return evidence?.fresh !== true && evidence?.sourceDeclared === true;
-            });
-        if (allPathsAreSourceDeclaredFuturePaths)
-            return { ok: true, surface };
-        return {
-            ok: false,
-            reason: "frontend scout target surface lacks fresh runtime evidence for a named target path; greenfield exceptions require runtime-injected source declarations for every future 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");
-}