@tea-agent/loop-agent 0.44.0-next.7 → 0.44.0-next.9

package/dist/executors/dag-pi/plan/ledger-contract.js

@@ -0,0 +1,55 @@
+/** DAG Pi plan ledger 契约与来源继承装载：纯类型与纯函数，禁止反向依赖执行器入口。 */
+import path from "node:path";
+import { frontendExecutionSchema } from "../../../workflows/dag/frontend-execution-groups.js";
+/**
+ * Source fidelity ledger (AC-005/AC-006): load the contract node's committed
+ * requirement facts and build a requirement-id → provenance map. The contract
+ * node declared sourceFragmentIds/sourceRefs from the ledger's
+ * requirement→fragment mapping; the plan inherits them by id so the compiled
+ * canonical contract carries authoritative provenance without the plan
+ * re-deriving (or fabricating) it. Best-effort: missing/unreadable contract
+ * ledger yields an empty map and the plan compiles as before (the design
+ * policy shell will then fail closed on missing provenance).
+ */
+export async function loadContractRequirementInheritance(runDir) {
+    const { readTypedEventStoreFromJsonl } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+    let records;
+    try {
+        records = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+    }
+    catch {
+        return new Map();
+    }
+    const byId = new Map();
+    for (const record of records) {
+        const fact = record.fact;
+        if (!fact || typeof fact !== "object")
+            continue;
+        const recordFact = fact;
+        if (recordFact.origin !== "contract" ||
+            recordFact.kind !== "requirement") {
+            continue;
+        }
+        // Contract requirement facts carry id/sourceFragmentIds/sourceRefs on
+        // the fact itself (origin=contract, kind=requirement, id, text, ...),
+        // not inside an `entry` wrapper.
+        const id = typeof recordFact.id === "string" ? recordFact.id : "";
+        if (!id)
+            continue;
+        const sourceFragmentIds = Array.isArray(recordFact.sourceFragmentIds)
+            ? recordFact.sourceFragmentIds.filter((value) => typeof value === "string")
+            : undefined;
+        const sourceRefs = Array.isArray(recordFact.sourceRefs)
+            ? recordFact.sourceRefs.filter((value) => typeof value === "string")
+            : undefined;
+        if (sourceFragmentIds || sourceRefs) {
+            byId.set(id, {
+                ...(typeof recordFact.text === "string" ? { text: recordFact.text } : {}),
+                ...(recordFact.execution !== undefined ? { execution: frontendExecutionSchema.parse(recordFact.execution) } : {}),
+                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
+                ...(sourceRefs ? { sourceRefs } : {}),
+            });
+        }
+    }
+    return byId;
+}

package/dist/executors/dag-pi/tools/contract-tools.js

@@ -0,0 +1,515 @@
+/** DAG Pi contract 工具工厂：origin=contract 增量契约工具与 vNext 审计装配，禁止反向依赖执行器入口。 */
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createDurableFrontendTools } from "../../../workflows/dag/frontend-durable-tools.js";
+import { writeJsonAtomic } from "../../../infrastructure/harness/atomic-write.js";
+import { mapContractBlockedOwner } from "../../../workflows/dag/frontend-human-decision.js";
+import { collectFrontendExecutionGroups, frontendExecutionSchema } from "../../../workflows/dag/frontend-execution-groups.js";
+import { frontendEvidenceExpectationSchema, validateFrontendRequiredDeliverables, } from "../../../workflows/dag/frontend-contract-facts.js";
+import { isRecordObject } from "../guards.js";
+/** A contract fact is source-mapped when it carries a non-empty `sourceSpan`
+ * (object or string), a non-empty `sourceRefs` array, or a non-empty `source`
+ * string. Anything else is an unmapped source segment (AC-001). */
+function contractFactSourceSpan(fact) {
+    if (isRecordObject(fact.sourceSpan) || typeof fact.sourceSpan === "string") {
+        return fact.sourceSpan;
+    }
+    if (Array.isArray(fact.sourceRefs) && fact.sourceRefs.length > 0) {
+        return fact.sourceRefs;
+    }
+    if (Array.isArray(fact.sourceFragmentIds) &&
+        fact.sourceFragmentIds.some((value) => typeof value === "string" && value.trim().length > 0)) {
+        return fact.sourceFragmentIds;
+    }
+    if (typeof fact.source === "string" && fact.source.trim().length > 0) {
+        return fact.source;
+    }
+    return undefined;
+}
+/**
+ * A+B (AC-001): deterministically assemble the read-only `frontend-task-contract-vNext`
+ * audit artifact from committed contract facts. It never rewrites the original
+ * task source: unmapped requirement/constraint segments are listed explicitly
+ * so Plan/Implement/Review keep binding to the raw source, not the model's
+ * summarized contract. The blocked disposition is projected through the frozen
+ * `mapContractBlockedOwner` mapping (AC-002).
+ */
+export function buildFrontendTaskContractVNext(records) {
+    const facts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter(isRecordObject);
+    const finalized = facts.find((fact) => fact.kind === "contract-finalized");
+    const disposition = typeof finalized?.disposition === "string" ? finalized.disposition : null;
+    const blockingOwner = typeof finalized?.blockingOwner === "string"
+        ? finalized.blockingOwner
+        : null;
+    const projected = mapContractBlockedOwner({
+        disposition: disposition ?? "",
+        blockingOwner: blockingOwner ?? undefined,
+    });
+    const byKind = (kind) => facts.filter((fact) => fact.kind === kind);
+    const requirements = byKind("requirement");
+    const unmappedSourceSegments = requirements
+        .filter((fact) => contractFactSourceSpan(fact) === undefined)
+        .map((fact) => ({
+        kind: "requirement",
+        id: typeof fact.id === "string"
+            ? fact.id
+            : typeof fact.text === "string"
+                ? fact.text
+                : undefined,
+    }))
+        .filter((segment) => segment.id !== undefined);
+    return {
+        schemaVersion: 1,
+        schemaId: "frontend-task-contract-vNext",
+        disposition,
+        blockingOwner,
+        blockedOwner: projected === "not-blocked" ? null : projected,
+        requirements,
+        constraints: byKind("constraint"),
+        evidenceExpectations: byKind("evidence-expectation"),
+        deliverableDeclarations: byKind("required-deliverables").at(-1)?.items ?? [],
+        handoffIntents: byKind("handoff-intent"),
+        openQuestions: byKind("open-question"),
+        splitProposals: byKind("split-proposal"),
+        unmappedSourceSegments,
+    };
+}
+/**
+ * A+B: `frontend-contract-pi` incremental contract tools. The `record_*` tools
+ * commit origin=contract facts and `finalize_contract` commits the terminal
+ * disposition (ready | ready-with-assumptions | blocked + blockingOwner).
+ */
+export async function createFrontendContractTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../../../workflows/dag/frontend-typed-event-transaction.js");
+    let store = input.store;
+    const attemptId = input.attemptId;
+    let activeScope = null;
+    const committedRequirementIds = () => new Set(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "requirement").map(r => String(r.fact.id)));
+    const completedScopeRequirementIds = () => new Set(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "contract-scope-completed").flatMap(r => Array.isArray(r.fact.requirementIds) ? r.fact.requirementIds.filter((id) => typeof id === "string") : []));
+    const receipt = (details) => ({
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+    });
+    async function adoptContractFact(kind, fact) {
+        try {
+            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
+            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 recordKinds = {
+        record_constraint: "constraint",
+        record_handoff_intent: "handoff-intent",
+        record_open_question: "open-question",
+        record_split_proposal: "split-proposal",
+    };
+    const recordTools = Object.entries(recordKinds).map(([name, kind]) => defineTool({
+        name,
+        label: name,
+        description: `Commit an origin=contract ${kind} fact. IMPORTANT: submit incrementally — batch up to 5 record_* calls per message, starting from the FIRST message; never attempt to emit the whole contract in one response (a single large dump will be truncated and rejected). Every message must make progress by committing at least one record_* fact.`,
+        promptSnippet: `Commit 1-5 origin=contract ${kind} facts (up to 5 per message).`,
+        parameters: Type.Object({
+            text: Type.String({ minLength: 1 }),
+            requirementIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+            sourceFragmentIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+            ...(kind === "constraint" ? { category: Type.Optional(Type.Enum({ constraint: "constraint", "non-goal": "non-goal", risk: "risk" })) } : {}),
+            ...(kind === "handoff-intent" ? { taskKind: Type.Literal("frontend-test"), blocking: Type.Optional(Type.Boolean()) } : {}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const data = params;
+            if (!data.text?.trim())
+                return receipt({ ok: false, code: "TOOL_SCHEMA_INVALID", error: `${name}: text must be non-empty` });
+            const knownFragments = new Set([...(input.canonicalRequirements?.values() ?? [])].flatMap(r => r.sourceFragmentIds));
+            if (data.requirementIds?.some(id => !input.canonicalRequirements?.has(id)) || data.sourceFragmentIds?.some(id => !knownFragments.has(id)))
+                return receipt({ ok: false, code: "CONTRACT_REFERENCE_UNKNOWN", error: `${name}: reference is outside the frozen source inventory` });
+            const result = await adoptContractFact(kind, {
+                ...(params ?? {}),
+                kind,
+                origin: "contract",
+            });
+            return receipt(result);
+        },
+    }));
+    // record_requirement is runtime-owned by design: the requirement TEXT and
+    // sourceFragmentIds come from the frozen source-fidelity ledger, never from
+    // model-authored prose. The model only names the canonical id it confirms.
+    // This closes the free-shape hole (additionalProperties:true accepted
+    // `statement` rewrites and JSON-stringified `sourceFragmentIds` arrays,
+    // which then reached the planner as empty text + dead fragment bindings).
+    const recordRequirementTool = defineTool({
+        name: "record_requirement",
+        label: "record_requirement",
+        description: 'Confirm one canonical ledger requirement (origin=contract requirement fact). Pass the canonical id and optional execution:{groupId,kind,summary} only. Reuse a group only when its behavior and all permission/threshold/error conditions agree; retain separate groups for differences. Constraints/exclusions do not require invented UI. The canonical id is listed in the <frontend_contract_input> inventory, e.g. {"id": "AC-001"} — the runtime commits the authoritative text and sourceFragmentIds from the frozen ledger. Never pass text/statement/sourceFragmentIds yourself: free-form rewrites and JSON-stringified fragment arrays are rejected. IMPORTANT: batch up to 5 record_* calls per message, starting from the FIRST message.',
+        promptSnippet: "Confirm 1-5 canonical requirements by id (up to 5 per message).",
+        parameters: Type.Object({ id: Type.String({ description: "Canonical ledger requirement id (e.g. AC-001)" }), execution: Type.Optional(Type.Object({ groupId: Type.String({ minLength: 1 }), kind: Type.Union([Type.Literal("behavior"), Type.Literal("constraint"), Type.Literal("exclusion")]), summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const id = typeof params?.id === "string" ? params.id.trim() : "";
+            if (!id) {
+                return receipt({
+                    ok: false,
+                    kind: "requirement",
+                    error: "record_requirement requires the canonical requirement id",
+                });
+            }
+            if (activeScope && !activeScope.has(id))
+                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: `requirement ${id} is outside the complete input scope of this session` });
+            const canonical = input.canonicalRequirements?.get(id);
+            if (!canonical) {
+                const known = [...(input.canonicalRequirements?.keys() ?? [])];
+                return receipt({
+                    ok: false,
+                    kind: "requirement",
+                    error: `record_requirement id "${id}" is not a canonical ledger requirement; canonical ids are: ${known.join(", ") || "(none)"}`,
+                });
+            }
+            if (params.execution) {
+                try {
+                    collectFrontendExecutionGroups([...readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "requirement" && r.fact.id !== id).map(r => ({ id: String(r.fact.id), execution: r.fact.execution })), { id, execution: params.execution }]);
+                }
+                catch (error) {
+                    return receipt({ ok: false, code: "EXECUTION_GROUP_CONFLICT", error: String(error) });
+                }
+            }
+            const result = await adoptContractFact("requirement", {
+                kind: "requirement",
+                origin: "contract",
+                disposition: "explicit",
+                id,
+                text: canonical.text,
+                sourceFragmentIds: canonical.sourceFragmentIds,
+                ...(params.execution ? { execution: params.execution } : {}),
+            });
+            return receipt(result);
+        },
+    });
+    // Requirement identity/text/source are runtime-owned and seeded before the
+    // model starts. Execution grouping is still a model decision, so expose it
+    // as a small typed update instead of forcing the model to re-submit the same
+    // requirement just to attach execution metadata.
+    const recordRequirementExecutionTool = defineTool({
+        name: "record_requirement_execution",
+        label: "record_requirement_execution",
+        description: "Attach execution ownership to already-confirmed canonical requirements.",
+        promptSnippet: "Record execution group metadata for confirmed requirements.",
+        parameters: Type.Object({
+            requirementIds: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true }),
+            execution: Type.Object({
+                groupId: Type.String({ minLength: 1 }),
+                kind: Type.Union([Type.Literal("behavior"), Type.Literal("constraint"), Type.Literal("exclusion")]),
+                summary: Type.String({ minLength: 1 }),
+            }, { additionalProperties: false }),
+        }, { additionalProperties: false }),
+        async execute(callId, params) {
+            const ids = params.requirementIds;
+            if (activeScope && ids.some((id) => !activeScope?.has(id)))
+                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "execution metadata references a requirement outside the active contract scope" });
+            const canonical = input.canonicalRequirements;
+            const unknown = ids.filter((id) => !canonical?.has(id));
+            if (unknown.length > 0)
+                return receipt({ ok: false, code: "CONTRACT_REFERENCE_UNKNOWN", error: `record_requirement_execution references unknown canonical requirements: ${unknown.join(", ")}` });
+            const execution = frontendExecutionSchema.parse(params.execution);
+            const existing = readCommittedEvents(store, attemptId)
+                .filter((record) => record.fact.kind === "requirement")
+                .map((record) => ({ id: String(record.fact.id), execution: record.fact.execution }))
+                .filter((unit) => !ids.includes(unit.id));
+            try {
+                collectFrontendExecutionGroups([...existing, ...ids.map((id) => ({ id, execution }))]);
+            }
+            catch (error) {
+                return receipt({ ok: false, code: "EXECUTION_GROUP_CONFLICT", error: error instanceof Error ? error.message : String(error) });
+            }
+            let result = { ok: true };
+            for (const id of ids) {
+                const requirement = canonical.get(id);
+                result = await adoptContractFact("requirement", { kind: "requirement", origin: "contract", disposition: "explicit", id, text: requirement.text, sourceFragmentIds: requirement.sourceFragmentIds, execution });
+                if (result.ok !== true)
+                    return receipt(result);
+            }
+            return receipt({ ...result, requestId: callId });
+        },
+    });
+    // Authoritative UI state declarations: the contract node extracts the
+    // PRD/reference UI-state table into structured facts so the planner binds
+    // uiStates to declared ids instead of inventing names (dogfood
+    // dag-1788504923861-0f7b17a9: 10 invented list-visibility variants, 0 of
+    // the 7 PRD states).
+    const recordUiStateTool = defineTool({
+        name: "record_ui_state",
+        label: "record_ui_state",
+        description: 'Declare ONE authoritative UI state extracted from the task source\'s UI-state table (origin=contract ui-state-declaration fact). Call once per declared state, exactly as the source names it: {"id": "<state id from the source table>", "trigger": "<when this state applies>", "observableOutcome": "<what the user can observe>"}. The planner must bind these ids later; do not rename or invent states.',
+        promptSnippet: "Declare 1-5 authoritative UI states (up to 5 per message).",
+        parameters: Type.Object({
+            id: Type.String({ description: "UI state id exactly as the source table declares it" }),
+            trigger: Type.String({ description: "When this state applies" }),
+            observableOutcome: Type.String({ description: "Observable result for the user" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const id = typeof params?.id === "string" ? params.id.trim() : "";
+            const trigger = typeof params?.trigger === "string" ? params.trigger.trim() : "";
+            const observableOutcome = typeof params?.observableOutcome === "string"
+                ? params.observableOutcome.trim()
+                : "";
+            if (!id || !trigger || !observableOutcome) {
+                return receipt({
+                    ok: false,
+                    kind: "ui-state-declaration",
+                    error: "record_ui_state requires non-empty id, trigger, and observableOutcome",
+                });
+            }
+            const result = await adoptContractFact("ui-state-declaration", {
+                kind: "ui-state-declaration",
+                origin: "contract",
+                id,
+                trigger,
+                observableOutcome,
+            });
+            return receipt(result);
+        },
+    });
+    const evidenceStatus = Type.Enum({
+        required: "required", optional: "optional", "not-applicable": "not-applicable",
+    });
+    const recordEvidenceExpectationTool = defineTool({
+        name: "record_evidence_expectation",
+        label: "record_evidence_expectation",
+        description: 'Record evidence requirements as {requirementId:"<canonical id>",evidence:{static:"required|optional|not-applicable",behavior:"required|optional|not-applicable",mock:"required|optional|not-applicable","real-integration":"required|optional|not-applicable"}}. Declare at least one lane; later calls replace only the lanes they name.',
+        parameters: Type.Object({
+            requirementId: Type.String(),
+            evidence: Type.Object({
+                static: Type.Optional(evidenceStatus),
+                behavior: Type.Optional(evidenceStatus),
+                mock: Type.Optional(evidenceStatus),
+                "real-integration": Type.Optional(evidenceStatus),
+            }, { additionalProperties: false }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const fact = frontendEvidenceExpectationSchema.parse(params);
+                if (!input.canonicalRequirements?.has(fact.requirementId)) {
+                    throw new Error(`unknown canonical requirement ${fact.requirementId}`);
+                }
+                return receipt(await adoptContractFact("evidence-expectation", {
+                    kind: "evidence-expectation", origin: "contract", ...fact,
+                }));
+            }
+            catch (error) {
+                return receipt({
+                    ok: false, kind: "evidence-expectation",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+    });
+    const recordRequiredDeliverablesTool = defineTool({
+        name: "record_required_deliverables",
+        label: "record_required_deliverables",
+        description: 'Declare the complete source-required file deliverables as {items:[{path,requirementId,sourceFragmentId}]}. Interpret obligations from the original source, including lists/tables: permissions (allowedPaths/only allowed to modify), prohibitions, examples and read-only references are NOT delivery obligations. Each path must appear exactly in its frozen requirement-bound source fragment. Submit {items:[]} explicitly if no files are mandatory. Each call appends complete source-bound items; replace:true explicitly replaces the inventory. Required before finalize_contract ready.',
+        parameters: Type.Object({ replace: Type.Optional(Type.Boolean()), items: Type.Array(Type.Object({
+                path: Type.String(), requirementId: Type.String(), sourceFragmentId: Type.String(),
+            }, { additionalProperties: false })) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const declaration = validateFrontendRequiredDeliverables({ items: params.items }, input.canonicalRequirements ?? new Map());
+                const previous = params.replace ? [] : readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "required-deliverables").at(-1)?.fact.items;
+                const items = [...new Map([...(Array.isArray(previous) ? previous : []), ...declaration.items].map(item => [JSON.stringify(item), item])).values()];
+                return receipt(await adoptContractFact("required-deliverables", {
+                    kind: "required-deliverables", origin: "contract", items,
+                }));
+            }
+            catch (error) {
+                return receipt({
+                    ok: false, kind: "required-deliverables",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+    });
+    // OpenSpec selection committed as individual typed facts (one path per
+    // call) so a large candidate set never exceeds a single model output
+    // budget: each tool call carries exactly one {path, disposition,
+    // rationale} row and the ledger accumulates them across calls. Only
+    // positive classifications (required | relevant) are legal; unmentioned
+    // candidates default to irrelevant at the prewrite gate.
+    const recordOpenspecSelectionTool = defineTool({
+        name: "record_openspec_selection",
+        label: "record_openspec_selection",
+        description: "Commit one OpenSpec candidate classification (origin=contract openspec-selection fact). Call once per path you actually use or consult: required (must be read and cited) or relevant (informs planning). Never call it for irrelevant candidates — unmentioned candidates default to irrelevant. You may call it many times; one row per call.",
+        promptSnippet: "Commit one OpenSpec candidate classification (required | relevant); one path per call; skip irrelevant candidates.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: "Repo-relative candidate spec path, e.g. openspec/project-specs/ui/ucp-components-md/AdvancedSearch.md",
+            }),
+            disposition: Type.Enum({
+                required: "required",
+                relevant: "relevant",
+            }),
+            rationale: Type.String({}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const path = typeof params?.path === "string" ? params.path : "";
+            const disposition = params?.disposition;
+            const rationale = typeof params?.rationale === "string" ? params.rationale : "";
+            if (!path || !disposition || !rationale.trim()) {
+                return receipt({
+                    ok: false,
+                    kind: "openspec-selection",
+                    error: "record_openspec_selection requires non-empty path, disposition (required|relevant), and rationale",
+                });
+            }
+            const result = await adoptContractFact("openspec-selection", {
+                kind: "openspec-selection",
+                origin: "contract",
+                path,
+                disposition,
+                rationale,
+            });
+            return receipt(result);
+        },
+    });
+    const finalizeContractTool = defineTool({
+        name: "finalize_contract",
+        label: "finalize_contract",
+        description: "Commit the contract-finalized terminal fact with a disposition of ready | ready-with-assumptions | blocked (blocked requires blockingOwner). A successful terminal commit occurs exactly once. If validation fails, correct only the reported facts and retry finalize.",
+        promptSnippet: "Commit the contract-finalized terminal (disposition + optional blockingOwner).",
+        parameters: Type.Object({
+            disposition: Type.Enum({
+                ready: "ready",
+                "ready-with-assumptions": "ready-with-assumptions",
+                blocked: "blocked",
+            }),
+            blockingOwner: Type.Optional(Type.Enum({
+                "blocked-human": "blocked-human",
+                "blocked-external": "blocked-external",
+            })),
+            assumptions: Type.Optional(Type.Array(Type.String({}))),
+            summary: Type.Optional(Type.String({})),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const disposition = params?.disposition;
+            const blockingOwner = params?.blockingOwner;
+            if (disposition === "blocked" && !blockingOwner) {
+                return receipt({
+                    ok: false,
+                    kind: "finalize_contract",
+                    error: "blocked disposition requires blockingOwner (blocked-human | blocked-external)",
+                });
+            }
+            if (disposition !== "blocked" && input.canonicalRequirements?.size &&
+                !readCommittedEvents(store, attemptId).some((record) => record.fact.kind === "required-deliverables")) {
+                return receipt({
+                    ok: false, kind: "finalize_contract",
+                    error: "call record_required_deliverables with the complete source-bound inventory (or items:[] when none) before finalizing",
+                });
+            }
+            const missing = [...(input.canonicalRequirements?.keys() ?? [])].filter(id => !committedRequirementIds().has(id) || (activeScope !== null && !completedScopeRequirementIds().has(id)));
+            if (disposition !== "blocked" && missing.length)
+                return receipt({ ok: false, code: "CONTRACT_REQUIREMENT_COVERAGE_MISSING", error: `Confirm all complete source obligations before finalizing: ${missing.join(", ")}` });
+            const blockedOwner = mapContractBlockedOwner({
+                disposition: disposition ?? "",
+                blockingOwner,
+            });
+            const result = await adoptContractFact("contract-finalized", {
+                kind: "contract-finalized",
+                origin: "contract",
+                disposition,
+                ...(blockingOwner ? { blockingOwner } : {}),
+                ...(blockedOwner !== "not-blocked" ? { blockedOwner } : {}),
+                ...(Array.isArray(params?.assumptions)
+                    ? { assumptions: params.assumptions }
+                    : {}),
+                ...(typeof params?.summary === "string"
+                    ? { summary: params.summary }
+                    : {}),
+            });
+            return receipt(result);
+        },
+    });
+    const completeScopeTool = defineTool({
+        name: "complete_contract_scope", label: "complete_contract_scope",
+        description: "After recording all requirements AND their evidence, constraints, questions and deliverables for this session, mark the scope complete. Confirming an ID alone does not complete its analysis. Do this before finalize_contract.",
+        parameters: Type.Object({ requirementIds: Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }) }, { additionalProperties: false }),
+        async execute(_id, params) {
+            const ids = params.requirementIds;
+            if (activeScope === null || ids.length !== activeScope.size || ids.some(id => !activeScope?.has(id) || !committedRequirementIds().has(id)))
+                return receipt({ ok: false, code: "CONTRACT_SCOPE_INCOMPLETE", error: "Complete exactly the active scope after confirming all its obligations" });
+            return receipt(await adoptContractFact("contract-scope-completed", { kind: "contract-scope-completed", origin: "contract", requirementIds: ids }));
+        },
+    });
+    const durable = await createDurableFrontendTools({
+        file: path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), attemptId, store: input.store,
+        setWorkingStore: next => { store = next; }, binding: { canonicalRequirements: input.canonicalRequirements, sourceDigest: input.sourceDigest },
+        tools: [
+            ...recordTools,
+            recordRequirementTool,
+            recordRequirementExecutionTool,
+            recordEvidenceExpectationTool,
+            recordUiStateTool,
+            recordRequiredDeliverablesTool,
+            recordOpenspecSelectionTool,
+            completeScopeTool,
+            finalizeContractTool,
+        ],
+    });
+    const durableRecordRequirementTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "record_requirement");
+    if (!durableRecordRequirementTool)
+        throw new Error("frontend contract durable requirement tool unavailable");
+    return {
+        customTools: durable.customTools,
+        inputRequirements: () => [...(input.canonicalRequirements ?? [])].map(([id, value]) => ({ id, text: value.text, sourceFragmentIds: [...value.sourceFragmentIds] })),
+        seedCanonicalRequirements: async () => {
+            for (const id of input.canonicalRequirements?.keys() ?? []) {
+                if (committedRequirementIds().has(id))
+                    continue;
+                const receipt = await durableRecordRequirementTool.execute(`${attemptId}:seed-requirement:${id}`, { id }, undefined, undefined, {});
+                if (receipt.details?.ok !== true) {
+                    throw new Error(`runtime requirement seed rejected for ${id}`);
+                }
+            }
+            await durable.flush();
+        },
+        completedScopeRequirementIds,
+        setActiveRequirementScope: ids => { activeScope = ids === null ? null : new Set(ids); },
+        committedRequirementIds,
+        committedFacts: () => readCommittedEvents(input.store, attemptId),
+        flush: async () => {
+            await durable.flush();
+            const committed = readCommittedEvents(input.store, attemptId);
+            await writeJsonAtomic(path.join(input.runDir, input.nodeId, "frontend-task-contract-vNext.json"), buildFrontendTaskContractVNext(committed));
+        },
+    };
+}