@tea-agent/loop-agent 0.44.0-next.6 → 0.44.0-next.8

package/dist/executors/dag-pi/tools/plan-decision-tools.js

@@ -0,0 +1,519 @@
+/** DAG Pi plan decision 工具工厂：decision 通道 record_* 工具与 finalize 编译，禁止反向依赖执行器入口。 */
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+/** Translate derived-patch validation findings into decision-channel
+ * vocabulary. Each zod issue path names a COMPILED patch array, but the model
+ * authored record_* facts — so quote the offending entry's identity and name
+ * the tool that owns it (r14: "uiComponentChoices.0.specReference.section:
+ * Required" is unactionable when the model has never heard of specReference). */
+export function translateDecisionPatchFindings(message, decision) {
+    const body = message.replace(/^invalid-output:\s*/, "");
+    return body
+        .split(/;\s*/)
+        .map(issue => {
+        const choice = issue.match(/uiComponentChoices\.(\d+)\.(.+)/);
+        if (choice) {
+            const row = decision.reuseDecisions[Number(choice[1])];
+            const base = row
+                ? `record_reuse_decision purpose "${row.purpose}" (component ${row.symbol}, decision ${row.decision}): ${issue}`
+                : `record_reuse_decision row ${choice[1]}: ${issue}`;
+            const field = choice[2];
+            return field?.startsWith("specReference")
+                ? `${base} — pass specSection (the AC id / task-source section it implements) on that entry, or use decision "reuse-existing"`
+                : base;
+        }
+        const focus = issue.match(/verificationTargets\.(\d+)\.(.+)/);
+        if (focus) {
+            const row = decision.verificationFocus[Number(focus[1])];
+            if (!row)
+                return `record_verification_focus row ${focus[1]}: ${issue}`;
+            return `record_verification_focus ${row.id}: ${issue} — behavior targets derive uiStates from record_state_ownership rows whose owner equals behaviorGroupId "${row.behaviorGroupId}"; record one for this group if missing`;
+        }
+        const state = issue.match(/uiStates\.(\d+)\.(.+)/);
+        if (state) {
+            const row = decision.stateOwnership[Number(state[1])];
+            return row
+                ? `record_state_ownership "${row.state}" (owner ${row.owner}): ${issue}`
+                : `record_state_ownership row ${state[1]}: ${issue}`;
+        }
+        const interaction = issue.match(/interactions\.(\d+)\.(.+)/);
+        if (interaction) {
+            const row = decision.dataFlows[Number(interaction[1])];
+            return row
+                ? `record_data_flow "${row.interaction}": ${issue}`
+                : `record_data_flow row ${interaction[1]}: ${issue}`;
+        }
+        const requirement = issue.match(/requirements\.(\d+)\.(.+)/);
+        if (requirement) {
+            return `record_module_placement row ${requirement[1]}: ${issue}`;
+        }
+        return issue;
+    })
+        .join("; ");
+}
+export async function createFrontendPlanDecisionTools(input) {
+    const [{ Type }, { defineTool }, { assembleDecisionContractFromFacts, assembleExperimentPlanContract, buildFrontendPlanRelationshipPatch }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+        import("../../../workflows/dag/frontend-plan-decision-contract.js"),
+    ]);
+    const { readCommittedEvents } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../../../workflows/dag/frontend-typed-event-transaction.js");
+    const { createDurableFrontendTools } = await import("../../../workflows/dag/frontend-durable-tools.js");
+    let store = input.store;
+    const { attemptId, authority } = input;
+    const optionalStringArray = Type.Optional(Type.Array(Type.String({ minLength: 1 })));
+    const optionalString = Type.Optional(Type.String({ minLength: 1 }));
+    // In-session pre-validation of the derived relationship patch. The
+    // post-session bridge runs the identical analysis; running it first inside
+    // finalize_decision turns findings into a bounded in-session correction
+    // (fix facts, finalize again) instead of an attempt burn. Skipped when the
+    // caller does not supply the runtime skeleton/sourceBinding.
+    let requiredDeliverablesCache;
+    const prevalidateDerivedPatch = async () => {
+        if (!input.skeleton || !input.sourceBinding)
+            return { ok: true, canonicalSha256: "", canonical: {} };
+        const committed = readCommittedEvents(store, attemptId);
+        const decision = assembleDecisionContractFromFacts(committed.map(record => record.fact));
+        requiredDeliverablesCache ??= (async () => {
+            const map = new Map();
+            try {
+                const { readTypedEventStoreFromJsonl } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+                const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+                for (const record of [...contractRecords].reverse()) {
+                    const fact = record.fact;
+                    if (!fact || fact.origin !== "contract" || fact.kind !== "required-deliverables")
+                        continue;
+                    for (const item of Array.isArray(fact.items) ? fact.items : []) {
+                        if (!item || typeof item !== "object" || Array.isArray(item))
+                            continue;
+                        const requirementId = item.requirementId;
+                        const file = item.path;
+                        if (typeof requirementId !== "string" || typeof file !== "string")
+                            continue;
+                        const paths = map.get(requirementId) ?? [];
+                        paths.push(file);
+                        map.set(requirementId, paths);
+                    }
+                    break;
+                }
+            }
+            catch {
+                // Missing/unreadable contract ledger → no deliverable obligations.
+            }
+            return map;
+        })();
+        const concreteWriteSet = [
+            ...new Set([
+                ...decision.modulePlacements.flatMap(item => item.paths),
+                ...decision.verificationFocus.map(item => item.file),
+            ]),
+        ];
+        const { applyFrontendContractMergePatch, analyzeFrontendPlanPatchCandidate, FrontendContractFailure, PlanPolicyPrecheckFailure, serializeDeterministicJson, } = await import("../../../workflows/dag/frontend-implementation-contract.js");
+        try {
+            const patch = buildFrontendPlanRelationshipPatch({
+                decision,
+                authority,
+                concreteWriteSet,
+                requiredDeliverables: await requiredDeliverablesCache,
+            });
+            const merged = applyFrontendContractMergePatch(input.skeleton, patch);
+            const analysis = await analyzeFrontendPlanPatchCandidate({
+                runDir: input.runDir,
+                rawContractText: serializeDeterministicJson(merged),
+                sourceBinding: input.sourceBinding,
+            });
+            return {
+                ok: true,
+                canonicalSha256: createHash("sha256")
+                    .update(serializeDeterministicJson(analysis.canonical))
+                    .digest("hex"),
+                canonical: analysis.canonical,
+            };
+        }
+        catch (error) {
+            if (error instanceof PlanPolicyPrecheckFailure) {
+                // Template the fix: every uncovered interaction/state maps to a
+                // fill-in record_reuse_decision row (the decision channel's
+                // component-choice tool).
+                const suggestions = error.findings
+                    .filter(finding => finding.code === "ui-design-coverage-missing" && finding.path)
+                    .map(finding => ({
+                    tool: "record_reuse_decision",
+                    args: {
+                        entry: {
+                            symbol: "<name the existing or new component>",
+                            decision: "reuse-existing",
+                            evidence: ["<existing repo file that proves this reuse>"],
+                            purpose: finding.path,
+                        },
+                    },
+                }));
+                const suggestionBlock = suggestions.length > 0
+                    ? ` Suggested record_* calls (copy, fill component, submit): ${JSON.stringify(suggestions)}`
+                    : "";
+                return {
+                    ok: false,
+                    error: `finalize_decision pre-validation failed (fix the listed plan facts, then call finalize_decision again): ${error.message}${suggestionBlock}`,
+                };
+            }
+            // FrontendContractFailure messages carry zod issue paths and are
+            // translated into record_* vocabulary; the bridge compiler throws
+            // decision-state-unbindable / decision-styling-strategy-conflict
+            // diagnostics that are already model-fixable as written.
+            const message = error instanceof Error ? error.message : String(error);
+            const translated = error instanceof FrontendContractFailure
+                ? translateDecisionPatchFindings(message, decision)
+                : message;
+            return {
+                ok: false,
+                error: `finalize_decision pre-validation failed (fix the listed facts with the named record_* tools — resubmit a corrected row with the same identity and replace:true to replace it — then call finalize_decision again): ${translated}`,
+            };
+        }
+    };
+    const planToolReceipt = (details) => ({
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+    });
+    async function adoptDecisionFact(kind, requestId, fact) {
+        try {
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return { ok: true, kind, eventId: committed.eventId, revision: committed.revision, error: "" };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const record = (name, label, description, entrySchema, gate) => defineTool({
+        name,
+        label,
+        description,
+        promptSnippet: `Record ${label}.`,
+        parameters: Type.Object({ entry: entrySchema }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const entry = params?.entry;
+            const kind = name.replace("record_", "").replace(/_/g, "-");
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+                return planToolReceipt({ ok: false, kind, error: `${name} requires a non-empty entry object` });
+            }
+            if (gate) {
+                const rejected = await gate(entry);
+                if (rejected)
+                    return rejected;
+            }
+            const result = await adoptDecisionFact(kind, `${attemptId}:${name}:${randomUUID()}`, { kind, origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
+    const recordModulePlacementTool = record("record_module_placement", "module placement", "Record one module placement: which behavior-group/module id maps to which concrete files. Example: {\"entry\": {\"id\": \"page\", \"paths\": [\"src/page.tsx\"]}}", Type.Object({ id: Type.String({ minLength: 1 }), paths: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) }, { additionalProperties: false }));
+    const recordReuseDecisionTool = record("record_reuse_decision", "reuse decision", "Record one component decision: which component serves which UI state/interaction (purpose). decision \"reuse-existing\" = an existing repo component (evidence[0] = the repo file that proves it); \"specified\" = the frontend spec mandates it; \"new\" = the task source mandates a bounded addition — specified/new require specSection naming the spec/task-source declaration they implement (e.g. an AC id). Set stylingStrategy once (on the first call) when the task mandates a style contract. Resubmit the same purpose with replace:true to correct a row. Example: {\"entry\": {\"symbol\": \"Spinner\", \"decision\": \"reuse-existing\", \"evidence\": [\"src/ui/Spinner.tsx\"], \"purpose\": \"loading\"}} or {\"entry\": {\"symbol\": \"SmokeCounter\", \"decision\": \"new\", \"evidence\": [\"需求.md\"], \"purpose\": \"increment\", \"specSection\": \"AC-FE-002\", \"stylingStrategy\": \"compact, stable, animation-free single card\"}}", Type.Object({
+        symbol: Type.String({ minLength: 1 }),
+        decision: Type.Union([Type.Literal("specified"), Type.Literal("reuse-existing"), Type.Literal("new")]),
+        evidence: Type.Array(Type.String()),
+        specSection: Type.Optional(Type.String({ minLength: 1 })),
+        purpose: Type.String({ minLength: 1 }),
+        covers: optionalStringArray,
+        rationale: optionalString,
+        stylingStrategy: optionalString,
+    }, { additionalProperties: false }), async (entry) => {
+        // specified/new compile into a canonical specReference whose .section
+        // the contract schema mandates; without the section the row can only
+        // fail at finalize, so demand it here where the model can still act.
+        if (entry.decision === "specified") {
+            const evidenceList = Array.isArray(entry.evidence) ? entry.evidence : [];
+            const evidencePath = typeof evidenceList[0] === "string" ? evidenceList[0] : "";
+            const candidates = input.componentSpecCandidatePaths ?? [];
+            if (candidates.length === 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "reuse-decision",
+                    error: `record_reuse_decision specified-requires-spec-candidates: decision "specified" means a declared component spec mandates this choice, but this task declares no component spec candidates — use decision "new" (task-source-mandated addition, evidence[0] = the task-source file) or "reuse-existing"`,
+                });
+            }
+            if (evidencePath && !candidates.includes(evidencePath)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "reuse-decision",
+                    error: `record_reuse_decision specified-spec-reference-outside-candidates: evidence[0] "${evidencePath}" is not a declared component spec candidate; declared candidates: [${candidates.join(", ")}]`,
+                });
+            }
+        }
+        if ((entry.decision === "specified" || entry.decision === "new") &&
+            !(typeof entry.specSection === "string" && entry.specSection.trim())) {
+            return planToolReceipt({
+                ok: false,
+                kind: "reuse-decision",
+                error: `record_reuse_decision spec-section-required: decision "${entry.decision}" must name the spec/task-source declaration it implements via specSection (e.g. an AC id); use decision "reuse-existing" for existing repo conventions. Example: {"entry": {"symbol": "SmokeCounter", "decision": "new", "evidence": ["src/components/SmokeCounter.tsx"], "purpose": "render the counter card", "specSection": "AC-FE-001"}}`,
+            });
+        }
+        return undefined;
+    });
+    const recordStateOwnershipTool = record("record_state_ownership", "state ownership", "Record one UI state and its owner, applicability and expected behavior. owner must equal the behaviorGroupId of the record_verification_focus entries it supports; every behavior group referenced by a verification focus needs at least one state row or finalize fails. Resubmit the same state name with replace:true to correct a row. Example: {\"entry\": {\"state\": \"loading\", \"owner\": \"page\", \"applicable\": true, \"expectedBehavior\": \"render loading\"}}", Type.Object({
+        state: Type.String({ minLength: 1 }),
+        owner: Type.String({ minLength: 1 }),
+        applicable: Type.Boolean(),
+        expectedBehavior: optionalString,
+        notApplicableReason: optionalString,
+    }, { additionalProperties: false }));
+    const frozenInteractionIds = authority.interactionIds ?? [];
+    const recordDataFlowTool = record("record_data_flow", "data flow", "Record one interaction data flow: source behavior group, trigger and expected behavior. One row per interaction name; resubmit the same interaction name to replace it. When a frozen interaction id vocabulary is declared, the interaction name MUST be one of the declared ids — wrong-named records are rejected at submission and stale ones are retracted via retract_data_flow. Example: {\"entry\": {\"interaction\": \"load\", \"source\": \"page\", \"trigger\": \"submit query\", \"expectedBehavior\": \"show loading then results\"}}", Type.Object({
+        interaction: Type.String({ minLength: 1 }),
+        source: Type.String({ minLength: 1 }),
+        trigger: Type.String({ minLength: 1 }),
+        expectedBehavior: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }), frozenInteractionIds.length > 0
+        ? async (entry) => {
+            const name = typeof entry.interaction === "string" ? entry.interaction : "";
+            if (name && !frozenInteractionIds.includes(name)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "data-flow",
+                    code: "INTERACTION_ID_NOT_DECLARED",
+                    error: `interaction "${name}" is not in the frozen vocabulary; allowed: [${frozenInteractionIds.join(", ")}]. Submit the declared id. To remove an already-recorded wrong interaction, call retract_data_flow with {"interaction": "${name}"}.`,
+                });
+            }
+            return undefined;
+        }
+        : undefined);
+    const retractDataFlowTool = defineTool({
+        name: "retract_data_flow",
+        label: "retract data flow",
+        description: "Retract a previously recorded interaction data flow (e.g. one recorded under a wrong interaction id). The retracted record and every fact keyed to that interaction name stop participating in the compiled plan. Declared vocabulary ids cannot be retracted. Example: {\"interaction\": \"increment-counter\", \"reason\": \"recorded under a wrong id\"}",
+        promptSnippet: "Retract one interaction data flow by interaction name.",
+        parameters: Type.Object({
+            interaction: Type.String({ minLength: 1 }),
+            reason: Type.Optional(Type.String({ minLength: 1 })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const interaction = typeof params?.interaction === "string" ? params.interaction : "";
+            if (!interaction) {
+                return planToolReceipt({ ok: false, kind: "data-flow", error: "retract_data_flow requires a non-empty interaction" });
+            }
+            if (frozenInteractionIds.includes(interaction)) {
+                return planToolReceipt({ ok: false, kind: "data-flow", error: `interaction "${interaction}" is a declared vocabulary id and cannot be retracted` });
+            }
+            const result = await adoptDecisionFact("data-flow", `${attemptId}:retract_data_flow:${randomUUID()}`, { kind: "data-flow", origin: "plan", entry: { interaction, retracted: true, ...(typeof params?.reason === "string" ? { reason: params.reason } : {}) } });
+            return planToolReceipt(result);
+        },
+    });
+    const recordApiMockBoundaryTool = record("record_api_mock_boundary", "API/Mock boundary", "Record one API boundary and its mode (real/mock/not-needed) with evidence. The boundary is the stable identity: resubmit the same boundary with replace:true to change its mode (e.g. mock→real); the old decision is replaced, not appended. Real/mock endpoints require fixture (the test fixture path) and consumer (the implementation file that calls the API) — design policy rejects endpoints without them. Example: {\"entry\": {\"boundary\": \"GET /items\", \"mode\": \"mock\", \"evidence\": \"fixture only\", \"fixture\": \"test/fixtures/items.ts\", \"consumer\": \"src/page.tsx\"}}", Type.Object({
+        boundary: Type.String({ minLength: 1 }),
+        mode: Type.Union([Type.Literal("real"), Type.Literal("mock"), Type.Literal("not-needed")]),
+        evidence: Type.String({ minLength: 1 }),
+        fixture: optionalString,
+        consumer: optionalString,
+    }, { additionalProperties: false }), async (entry) => {
+        // Design policy hard-requires fixture + consumer on every derived
+        // endpoint (non-not-needed strategies); demand them here where the
+        // model can still act instead of failing the compile post-session.
+        if ((entry.mode === "real" || entry.mode === "mock") &&
+            (!(typeof entry.fixture === "string" && entry.fixture.trim()) ||
+                !(typeof entry.consumer === "string" && entry.consumer.trim()))) {
+            return planToolReceipt({
+                ok: false,
+                kind: "api-mock-boundary",
+                error: `record_api_mock_boundary fixture-and-consumer-required: ${entry.mode} boundary "${entry.boundary}" needs fixture (the test fixture path) and consumer (the implementation file that calls the API). Example: {"entry": {"boundary": "${entry.boundary}", "mode": "${entry.mode}", "evidence": "<why>", "fixture": "test/fixtures/items.ts", "consumer": "src/page.tsx"}}`,
+            });
+        }
+        return undefined;
+    });
+    const recordVerificationFocusTool = record("record_verification_focus", "verification focus", "Record one behavior-group verification focus: which test file/command proves which behavior group at what evidence level. Every behaviorGroupId must have at least one record_state_ownership row whose owner equals it — declare one UI state per behavior group before finalizing. Example: {\"entry\": {\"id\": \"VT-1\", \"behaviorGroupId\": \"page\", \"file\": \"test/page.test.tsx\", \"commandId\": \"test\", \"evidenceLevel\": \"mounted\"}}", Type.Object({
+        id: Type.String({ minLength: 1 }),
+        behaviorGroupId: Type.String({ minLength: 1 }),
+        file: Type.String({ minLength: 1 }),
+        commandId: Type.String({ minLength: 1 }),
+        evidenceLevel: Type.Union([Type.Literal("unit"), Type.Literal("mounted"), Type.Literal("real-integration")]),
+        boundary: optionalString,
+    }, { additionalProperties: false }), async (entry) => {
+        // Mirror the relationship record_plan_verification_target boundary so
+        // protocol errors surface in-node (bounded correction) instead of
+        // burning attempts on an immutable committed fact that finalize rejects.
+        // Duplicate/identity enforcement lives in the durable wrapper (FACT_IDENTITY_CONFLICT
+        // unless replace:true) and the compile collapses same-id records to the
+        // latest replacement, so no duplicate gate is needed here.
+        const verificationCommandId = typeof entry.commandId === "string" ? entry.commandId.trim() : "";
+        if (!verificationCommandId) {
+            return planToolReceipt({
+                ok: false,
+                kind: "verification-focus",
+                error: `record_verification_focus entry.commandId is required (received ${JSON.stringify(entry.commandId ?? null)}); pick one id from the frozen command directory in your prompt`,
+            });
+        }
+        const { deriveFrontendVerifyCommandDirectoryFromRun, isFrontendTestFilePath } = await import("../../../workflows/dag/frontend-implementation-contract.js");
+        const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
+        if (verifyDirectory.length > 0) {
+            const directoryEntry = verifyDirectory.find((candidate) => candidate.commandId === verificationCommandId);
+            if (!directoryEntry) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "verification-focus",
+                    error: `record_verification_focus verification-target-unknown-command: unknown commandId "${verificationCommandId}"; available frozen commands: [${verifyDirectory.map((candidate) => `${candidate.commandId} (${candidate.mode}: ${candidate.label})`).join(", ")}]`,
+                });
+            }
+            if (directoryEntry.mode === "behavior" &&
+                typeof entry.file === "string" &&
+                !isFrontendTestFilePath(entry.file)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "verification-focus",
+                    error: `record_verification_focus verification-target-phase-mismatch: behavior command "${directoryEntry.label}" (${directoryEntry.commandId}) must bind a test file (__tests__/, tests?/, e2e/, cypress/, *.test.*, *.spec.*, *.cy.*); received file "${entry.file}"`,
+                });
+            }
+        }
+        // A behavior verification target derives its contract uiStates solely
+        // from the committed state-ownership rows whose owner equals its
+        // behaviorGroupId, and the relationship patch rejects a behavior
+        // target with empty uiStates whenever the plan declares any state or
+        // interaction. That rejection currently surfaces only in the
+        // post-session bridge and burns the whole attempt, so enforce the
+        // pairing here as a bounded in-session correction. A ledger with no
+        // ownership and no data-flow facts stays exempt (pure-logic plan),
+        // mirroring the contract-level exemption.
+        const committedLedger = readCommittedEvents(store, attemptId);
+        const ownershipRows = committedLedger.filter((event) => event.fact.kind === "state-ownership");
+        const hasInteractionFacts = committedLedger.some((event) => event.fact.kind === "data-flow");
+        if ((ownershipRows.length > 0 || hasInteractionFacts) &&
+            !ownershipRows.some((event) => event.fact.entry?.owner ===
+                entry.behaviorGroupId)) {
+            return planToolReceipt({
+                ok: false,
+                kind: "verification-focus",
+                error: `record_verification_focus undeclared-behavior-group-state: behavior group "${entry.behaviorGroupId}" (verification target ${entry.id}) has no record_state_ownership row; finalize derives each behavior target's UI states from ownership rows whose owner equals the behaviorGroupId, so record at least one for this group: {"state": "<name>", "owner": "${entry.behaviorGroupId}", "applicable": true, "expectedBehavior": "<what the state does>"}`,
+            });
+        }
+        return undefined;
+    });
+    const recordDependencyTool = record("record_dependency", "dependency", "Record one dependency name. Example: {\"entry\": {\"name\": \"none\"}}", Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false }));
+    const finalizeDecisionTool = defineTool({
+        name: "finalize_decision",
+        label: "finalize_decision",
+        description: "Compile the committed decision facts into a decision contract, pre-validate the derived canonical contract, and commit the terminal. Fails closed on any safety finding or validation finding; correct the reported record_* facts and call finalize_decision again.",
+        promptSnippet: "Compile and finalize the committed decision facts.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute(_toolCallId) {
+            const committed = readCommittedEvents(store, attemptId);
+            const decision = assembleDecisionContractFromFacts(committed.map(record => record.fact));
+            const expectedWriteSet = [
+                ...decision.modulePlacements.flatMap(item => item.paths),
+                ...decision.verificationFocus.map(item => item.file),
+            ];
+            const derived = assembleExperimentPlanContract({
+                decision,
+                authority,
+                concreteWriteSet: expectedWriteSet,
+            });
+            if (derived.findings.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "finalize_decision",
+                    code: "DECISION_SAFETY_FINDINGS",
+                    error: `decision safety projection failed: ${derived.findings.join("; ")}`,
+                });
+            }
+            const prevalidation = await prevalidateDerivedPatch();
+            if (!prevalidation.ok) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "finalize_decision",
+                    code: "DECISION_PREVALIDATION_FAILED",
+                    error: prevalidation.error,
+                });
+            }
+            // Recovery-mode guard: a repair child that finalizes a plan identical
+            // to its parent's has not performed the repair the findings demand —
+            // the identical plan is exactly what admission rejected. Both hashes
+            // use the same deterministic serializer over the canonical contract,
+            // so only a real semantic change passes.
+            // Recovery-mode guard: a repair child must demonstrably close the
+            // parent findings before the run re-enters design review.
+            if (input.parentDecisionSnapshot) {
+                const { readParentCanonical, parentCanonicalContentSha256 } = await import("../../../workflows/dag/frontend-implementation-contract.js");
+                const { extractRepairAssertions, evaluateRepairClosure, decisionIdentitySha256 } = await import("../../../workflows/dag/frontend-plan-decision-contract.js");
+                const parentRunDir = path.join(input.runDir, "..", input.parentDecisionSnapshot.parentRunId);
+                const parentCanonical = await readParentCanonical(parentRunDir);
+                // 1. identical-plan guard. Decisions, not prose: a rationale-only
+                // rewrite is not a repair (smoke r27 cleared a raw byte-hash guard
+                // by editing two rationale strings and changing nothing else). The
+                // byte hash stays as the fallback when the parent canonical cannot
+                // be read.
+                const parentSha = await parentCanonicalContentSha256(parentRunDir);
+                const parentDecisions = parentCanonical
+                    ? decisionIdentitySha256(parentCanonical)
+                    : undefined;
+                const childDecisions = decisionIdentitySha256(prevalidation.canonical);
+                if (parentDecisions
+                    ? parentDecisions === childDecisions
+                    : parentSha !== undefined && parentSha === prevalidation.canonicalSha256) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "finalize_decision",
+                        code: "DECISION_REPAIR_NO_CHANGE",
+                        error: "recovery finalize blocked: every structured decision row is identical to the parent run's (rationale-only edits do not count as a repair), but the review findings require changes. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.",
+                    });
+                }
+                // 2. per-finding closure: every deterministic assertion extracted
+                // from the parent findings must hold on the child canonical.
+                const findings = input.parentDecisionSnapshot.designFindings ?? [];
+                if (parentCanonical && findings.length > 0) {
+                    const assertions = extractRepairAssertions(findings, parentCanonical);
+                    const closure = evaluateRepairClosure(assertions, prevalidation.canonical, parentCanonical);
+                    if (!closure.closed) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "finalize_decision",
+                            code: "DECISION_REPAIR_NOT_CLOSED",
+                            error: `recovery finalize blocked: ${closure.unmet.length} finding(s) are still not closed — ${closure.unmet.join("; ")}. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.`,
+                        });
+                    }
+                }
+            }
+            const result = await adoptDecisionFact("finalize_decision", `${attemptId}:finalize_decision:${randomUUID()}`, { kind: "finalize_decision", origin: "plan", findings: [] });
+            return planToolReceipt(result);
+        },
+    });
+    const durable = await createDurableFrontendTools({
+        file: path.join(input.runDir, input.nodeId, "plan-decision-facts.jsonl"),
+        attemptId,
+        store: input.store,
+        setWorkingStore: next => { store = next; },
+        binding: { authority },
+        tools: [
+            recordModulePlacementTool,
+            recordReuseDecisionTool,
+            recordStateOwnershipTool,
+            recordDataFlowTool,
+            retractDataFlowTool,
+            recordApiMockBoundaryTool,
+            recordVerificationFocusTool,
+            recordDependencyTool,
+            finalizeDecisionTool,
+        ],
+    });
+    const durableFinalizeDecisionTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "finalize_decision");
+    if (!durableFinalizeDecisionTool)
+        throw new Error("frontend plan decision durable finalize tool unavailable");
+    return {
+        customTools: durable.customTools,
+        flush: durable.flush,
+        committedFacts: () => readCommittedEvents(store, attemptId),
+        finalizeDecision: () => durableFinalizeDecisionTool.execute(`${attemptId}:auto-finalize-decision`, {}, undefined, undefined, {}),
+    };
+}