@tea-agent/loop-agent 0.43.0-next.9 → 0.44.0-next.1

package/dist/workflows/dag/frontend-committed-facts.js

@@ -0,0 +1,461 @@
+import { readTypedEventStoreFromJsonl, } from "./frontend-typed-event-store.js";
+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();
+}
+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",
+];
+/**
+ * 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 override 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 targetRequirements = new Map();
+    for (const fact of facts.filter((item) => item.kind === "plan-verification-target")) {
+        const entry = isRecord(fact.entry) ? fact.entry : undefined;
+        const targetId = asString(entry?.id);
+        if (!targetId)
+            continue;
+        for (const requirementId of asStringArray(entry?.requirementIds)) {
+            const targets = targetRequirements.get(requirementId) ?? [];
+            if (!targets.includes(targetId))
+                targets.push(targetId);
+            targetRequirements.set(requirementId, targets);
+        }
+    }
+    const requirements = facts
+        .filter((fact) => fact.kind === "plan-requirement")
+        .map((fact) => fact.entry)
+        .filter(isRecord)
+        .map((entry) => {
+        const requirementId = asString(entry.id);
+        const derivedTargets = requirementId ? targetRequirements.get(requirementId) : undefined;
+        if (derivedTargets && derivedTargets.length > 0) {
+            return { ...entry, verificationTargetIds: [...derivedTargets].sort() };
+        }
+        return entry;
+    })
+        .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
+        // duplicate edge records 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;
+}
+/** 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)),
+        proposedPaths: canonicalStringSet(asStringArray(fact.proposedPaths)),
+        testPaths: canonicalStringSet(asStringArray(fact.testPaths)),
+    };
+    const namedPaths = canonicalStringSet([
+        ...(surface.entrypoint ? [surface.entrypoint] : []),
+        ...surface.implementationPaths,
+        ...surface.proposedPaths,
+        ...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 && evidence?.proposed !== 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 allPathsAreProposed = surface.proposedPaths.length > 0 &&
+            namedPaths.every((candidate) => surface.proposedPaths.includes(candidate) || freshPaths.has(candidate));
+        if (allPathsAreProposed)
+            return { ok: true, surface };
+        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.proposedPaths,
+        ...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 };
+}

package/dist/workflows/dag/frontend-durable-tools.js

@@ -28,6 +28,9 @@ async function exclusive(key, work) {
 }
 const hash = (value) => sha256OfCanonicalJson(JSON.parse(JSON.stringify(value, (_key, v) => v instanceof Map ? [...v.entries()].sort(([a], [b]) => String(a).localeCompare(String(b))) : v)));
 const ledgerError = (code, message) => Object.assign(new Error(message), { code });
+/** Singleton finalize tools: their committed fact is a run terminal and their
+ * params are an acknowledgement, not domain data (see replay rule below). */
+const FINALIZE_TERMINAL_TOOLS = new Set(["finalize_contract", "finalize_plan", "finalize_decision"]);
 const failure = (code, error) => ({ content: [{ type: "text", text: JSON.stringify({ ok: false, code, error }) }], details: { ok: false, code, error } });
 /** A failed rename must never fall back to copying over a live ledger. */
 async function persist(file, records) {
@@ -98,8 +101,8 @@ export async function createDurableFrontendTools(input) {
             try {
                 await restore();
                 const paramsSha256 = hash(params);
-                const singleton = new Set(["record_route_selection", "record_state_registry", "record_mock_api", "record_data_flow", "record_dependency", "record_design_deviation", "record_required_deliverables", "record_target_surface", "finalize_contract", "finalize_plan"]);
-                const naturalId = params?.id ?? params?.scopeId ?? params?.entry?.id ?? params?.requirementId ?? params?.choice?.purpose ?? (tool.name === "record_openspec_selection" ? params?.path : undefined) ?? (params?.endpoint ? `${params.endpoint.method}:${params.endpoint.path}` : undefined) ?? (singleton.has(tool.name) ? "singleton" : undefined);
+                const singleton = new Set(["record_route_selection", "record_state_registry", "record_mock_api", "record_data_flow", "record_dependency", "record_design_deviation", "record_required_deliverables", "record_target_surface", "finalize_contract", "finalize_plan", "finalize_decision"]);
+                const naturalId = params?.id ?? params?.scopeId ?? params?.entry?.id ?? params?.requirementId ?? params?.choice?.purpose ?? params?.entry?.purpose ?? params?.entry?.state ?? params?.entry?.interaction ?? params?.entry?.boundary ?? (tool.name === "record_openspec_selection" ? params?.path : undefined) ?? (params?.endpoint ? `${params.endpoint.method}:${params.endpoint.path}` : undefined) ?? (singleton.has(tool.name) ? "singleton" : undefined);
                 const identity = `${tool.name}:${typeof naturalId === "string" ? naturalId : "incremental"}`;
                 const submissions = input.store.records.flatMap(r => r.submission?.receipt ? [r.submission] : []);
                 const previousCall = submissions.find(s => s.callId === callId);
@@ -108,9 +111,18 @@ export async function createDurableFrontendTools(input) {
                 const previousFact = submissions.filter(s => s.identity === identity).at(-1);
                 if (tool.name !== "record_plan_group_coverage" && previousFact?.paramsSha256 === paramsSha256)
                     return replay(previousFact.receipt);
+                // A committed finalize terminal carries no domain payload in its params
+                // (r15: the model acknowledged with {replace:false}, the executor's
+                // auto-finalize sends {}) — both are acknowledgements of the same durable
+                // terminal, so any later finalize call replays the receipt instead of
+                // demanding a params match no caller can reproduce. Other singletons
+                // (state registry, data flows, ...) carry domain payloads and keep the
+                // replace:true correction path.
+                if (FINALIZE_TERMINAL_TOOLS.has(tool.name) && previousFact?.receipt)
+                    return replay(previousFact.receipt);
                 if (previousFact && naturalId !== undefined && params?.replace !== true && !["record_evidence_expectation", "record_required_deliverables", "record_data_flow"].includes(tool.name))
                     return failure("FACT_IDENTITY_CONFLICT", `${identity}: changing a saved fact requires explicit replacement (replace:true)`);
-                if (input.store.records.some(r => ["contract-finalized", "finalize_plan", "approve_review", "request_review_changes", "approve_design", "request_design_changes"].includes(String(r.fact.kind))))
+                if (input.store.records.some(r => ["contract-finalized", "finalize_plan", "finalize_decision", "approve_review", "request_review_changes", "approve_design", "request_design_changes"].includes(String(r.fact.kind))))
                     return failure("TERMINAL_CONFLICT", "A successful terminal is already durable; only identical acknowledged submissions may be replayed");
                 const draft = structuredClone(input.store);
                 input.setWorkingStore(draft);