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

package/dist/workflows/dag/frontend-plan-decision-contract.js

@@ -0,0 +1,803 @@
+import { z } from "zod";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { deterministicSha256 } from "./frontend-implementation-contract.js";
+import { isConcreteWriteSetPath } from "./frontend-writer-admission.js";
+/** Experimental model input/output. Not a canonical writer authority. The
+ * only coverage judgment is behaviorGroupId -> verification focus. Group
+ * membership belongs to the source-bound Contract, not another Plan table. */
+export const frontendPlanDecisionContractSchema = z.object({
+    schemaId: z.literal("frontend-plan-decision-contract-v1"),
+    modulePlacements: z.array(z.object({ id: z.string().min(1), paths: z.array(z.string().min(1)).min(1) }).strict()),
+    reuseDecisions: z.array(z.object({
+        symbol: z.string().min(1),
+        decision: z.enum(["specified", "reuse-existing", "new"]),
+        evidence: z.array(z.string()),
+        // Required at tool level for specified/new (the spec section or task-source
+        // declaration the choice implements); the bridge carries it into the
+        // canonical specReference.section, which the contract schema mandates.
+        specSection: z.string().min(1).optional(),
+        purpose: z.string().min(1), covers: z.array(z.string().min(1)).optional(), rationale: z.string().min(1).optional(),
+        // Optional task-wide style contract carried once on any choice row (the
+        // relationship component-choice channel); the bridge promotes the first
+        // non-empty value to the canonical top-level stylingStrategy.
+        stylingStrategy: z.string().min(1).optional(),
+    }).strict()),
+    stateOwnership: z.array(z.object({
+        state: z.string().min(1), owner: z.string().min(1),
+        applicable: z.boolean(), expectedBehavior: z.string().min(1).optional(), notApplicableReason: z.string().min(1).optional(),
+    }).strict()),
+    dataFlows: z.array(z.object({
+        interaction: z.string().min(1), source: z.string().min(1),
+        trigger: z.string().min(1), expectedBehavior: z.string().min(1),
+    }).strict()),
+    apiMockBoundaries: z.array(z.object({
+        boundary: z.string().min(1),
+        mode: z.enum(["real", "mock", "not-needed"]),
+        evidence: z.string().min(1),
+        // Design policy hard-requires fixture + consumer on every derived endpoint
+        // (non-not-needed strategies); the bridge promotes them verbatim instead of
+        // fabricating paths. Required at tool level for real/mock (gate).
+        fixture: z.string().min(1).optional(),
+        consumer: z.string().min(1).optional(),
+    }).strict()),
+    dependencies: z.array(z.string()),
+    verificationFocus: z.array(z.object({
+        id: z.string().min(1), behaviorGroupId: z.string().min(1),
+        file: z.string().min(1), commandId: z.string().min(1),
+        evidenceLevel: z.enum(["unit", "mounted", "real-integration"]),
+        boundary: z.string().min(1).optional(),
+    }).strict()),
+}).strict();
+const sorted = (values) => [...new Set(values)].sort();
+const concrete = (file) => isConcreteWriteSetPath(file) && !/[\[\]{}():]/.test(file) && !file.split("/").includes(".");
+export function projectFrontendSafetyFacts(input) {
+    const decision = frontendPlanDecisionContractSchema.parse(input.decision);
+    const { authority } = input;
+    const findings = [];
+    if (!/^[a-f0-9]{64}$/.test(authority.sourceBinding.requirementSha256) || authority.sourceBinding.requirementSha256 !== authority.observedRequirementSha256)
+        findings.push("source-binding-stale-or-invalid");
+    const requirementIds = sorted(authority.requirements.map(item => item.id));
+    if (requirementIds.length !== authority.requirements.length || authority.requirements.some(item => !item.id.trim() || !item.expectedOutcome.trim()))
+        findings.push("invalid-requirements");
+    const groups = new Map(authority.behaviorGroups.map(group => [group.id, group]));
+    if (groups.size !== authority.behaviorGroups.length)
+        findings.push("duplicate-behavior-group");
+    const ownedStates = new Set(decision.stateOwnership.map(item => item.state));
+    for (const group of authority.behaviorGroups) {
+        if (!group.requirementIds.length)
+            findings.push(`empty-behavior-group:${group.id}`);
+        for (const id of group.requirementIds)
+            if (!requirementIds.includes(id))
+                findings.push(`unknown-requirement:${id}`);
+        for (const state of group.requiredStates ?? []) {
+            if (!ownedStates.has(state))
+                findings.push(`missing-state:${group.id}:${state}`);
+        }
+    }
+    const mockBoundaries = new Set(decision.apiMockBoundaries.filter(item => item.mode === "mock").map(item => item.boundary));
+    const verificationByRequirement = Object.fromEntries(requirementIds.map(id => [id, []]));
+    const seen = new Set();
+    const levels = { unit: 0, mounted: 1, "real-integration": 2 };
+    const verificationTargets = decision.verificationFocus.map(focus => {
+        if (seen.has(focus.id))
+            findings.push(`duplicate-verification:${focus.id}`);
+        seen.add(focus.id);
+        const group = groups.get(focus.behaviorGroupId);
+        if (!group)
+            findings.push(`unknown-behavior-group:${focus.behaviorGroupId}`);
+        if (!authority.commands.some(command => command.id === focus.commandId))
+            findings.push(`unknown-command:${focus.commandId}`);
+        if (group && levels[focus.evidenceLevel] < levels[group.minimumEvidenceLevel])
+            findings.push(`insufficient-evidence-level:${focus.id}`);
+        if (focus.boundary && focus.evidenceLevel === "real-integration" && mockBoundaries.has(focus.boundary))
+            findings.push(`mock-claimed-as-real:${focus.id}:${focus.boundary}`);
+        const ids = sorted(group?.requirementIds ?? []);
+        for (const id of ids)
+            verificationByRequirement[id]?.push(focus.id);
+        return { id: focus.id, file: focus.file, commandId: focus.commandId, requirementIds: ids };
+    });
+    for (const id of requirementIds)
+        verificationByRequirement[id] = sorted(verificationByRequirement[id]);
+    const deliveryFiles = sorted([...decision.modulePlacements.flatMap(item => item.paths), ...verificationTargets.map(item => item.file)]);
+    for (const file of sorted([...deliveryFiles, ...input.concreteWriteSet])) {
+        if (!concrete(file))
+            findings.push(`write-set-path-not-concrete:${file}`);
+        if (!authority.allowedPaths.some(pattern => pathMatchesPattern(file, pattern)) || authority.forbiddenPaths.some(pattern => pathMatchesPattern(file, pattern)))
+            findings.push(`write-set-outside-authority:${file}`);
+    }
+    // References in reuseDecisions never expand delivery files or authorization.
+    const writeSetGaps = deliveryFiles.filter(file => !input.concreteWriteSet.includes(file));
+    for (const file of input.concreteWriteSet)
+        if (!deliveryFiles.includes(file))
+            findings.push(`unplanned-write:${file}`);
+    const missingVerificationRequirementIds = requirementIds.filter(id => !verificationByRequirement[id].length);
+    return { schemaId: "frontend-safety-projection-v1", authorityDigest: deterministicSha256(authority), requirementIds, deliveryFiles, verificationTargets, verificationByRequirement, missingVerificationRequirementIds, writeSetGaps, findings: sorted(findings) };
+}
+/** Compile the experimental Plan output into a canonical-contract-shaped
+ * requirements + verificationTargets view. The model supplies semantic decisions
+ * only: module placements, reuse, state ownership, data flows, Mock boundaries
+ * and one behavior-group -> verification-focus judgment per group. The runtime
+ * expands group membership (source-bound) and derives the per-AC
+ * implementationTargets and verificationTargetIds that production Policy /
+ * Admission consume. This proves the per-AC file table is derivable and does
+ * not have to be re-entered by the planner. */
+export function assembleExperimentPlanContract(input) {
+    const projection = projectFrontendSafetyFacts(input);
+    const groupByRequirement = new Map();
+    for (const group of input.authority.behaviorGroups) {
+        for (const id of group.requirementIds)
+            groupByRequirement.set(id, group.id);
+    }
+    const placementPathsById = new Map(input.decision.modulePlacements.map(item => [item.id, item.paths]));
+    const unplacedRequirementIds = [];
+    const requirements = input.authority.requirements.map(req => {
+        const groupId = groupByRequirement.get(req.id);
+        const implementationTargets = groupId
+            ? sorted(placementPathsById.get(groupId) ?? [])
+            : [];
+        if (implementationTargets.length === 0)
+            unplacedRequirementIds.push(req.id);
+        return {
+            id: req.id,
+            expectedOutcome: req.expectedOutcome,
+            implementationTargets,
+            deliverableTargets: [],
+            verificationTargetIds: projection.verificationByRequirement[req.id] ?? [],
+        };
+    });
+    const uiStates = input.decision.stateOwnership.map(item => ({
+        name: item.state,
+        applicable: item.applicable,
+        ...(item.expectedBehavior ? { expectedBehavior: item.expectedBehavior } : {}),
+        ...(item.notApplicableReason ? { notApplicableReason: item.notApplicableReason } : {}),
+    }));
+    const focusIdsByGroup = new Map();
+    for (const focus of input.decision.verificationFocus) {
+        const ids = focusIdsByGroup.get(focus.behaviorGroupId) ?? [];
+        ids.push(focus.id);
+        focusIdsByGroup.set(focus.behaviorGroupId, ids);
+    }
+    const interactions = input.decision.dataFlows.map(flow => ({
+        name: flow.interaction,
+        trigger: flow.trigger,
+        expectedBehavior: flow.expectedBehavior,
+        implementationTargets: sorted(placementPathsById.get(flow.source) ?? []),
+        verificationTargetIds: sorted(focusIdsByGroup.get(flow.source) ?? []),
+    }));
+    const uiComponentChoices = input.decision.reuseDecisions.map(item => {
+        const evidencePath = item.evidence[0];
+        return {
+            purpose: item.purpose,
+            component: item.symbol,
+            decision: item.decision,
+            specReference: evidencePath
+                ? { path: evidencePath, ...(item.specSection ? { section: item.specSection } : {}) }
+                : null,
+            rationale: item.rationale ?? "",
+            ...(item.covers ? { covers: item.covers } : {}),
+        };
+    });
+    const boundaries = input.decision.apiMockBoundaries;
+    const mockStrategy = boundaries.some(item => item.mode === "mock")
+        ? "browser-intercept"
+        : boundaries.some(item => item.mode === "real")
+            ? "native"
+            : "not-needed";
+    const mockEndpoints = boundaries.map(item => {
+        const [method = "", ...pathParts] = item.boundary.split(/\s+/);
+        const rawPath = (pathParts.join(" ") || item.boundary).trim();
+        return {
+            method,
+            path: rawPath.startsWith("/") ? rawPath : `/${rawPath}`,
+            ...(item.fixture ? { fixture: item.fixture } : {}),
+            ...(item.consumer ? { consumer: item.consumer } : {}),
+        };
+    });
+    const mockApi = {
+        strategy: mockStrategy,
+        productionDefaultOff: true,
+        activation: "explicit activation boundary",
+        endpoints: mockEndpoints,
+    };
+    const targets = { files: projection.deliveryFiles };
+    const designEvidence = { source: "experiment-decision", paths: [], conflicts: [] };
+    const dependencyPolicy = input.decision.dependencies.length > 0
+        ? input.decision.dependencies.join(", ")
+        : "零新增";
+    const verificationTargets = projection.verificationTargets.map(target => ({
+        ...target,
+        mode: "behavior",
+        commandLabel: target.commandId,
+        uiStates: [],
+    }));
+    return {
+        requirements,
+        verificationTargets,
+        uiStates,
+        interactions,
+        uiComponentChoices,
+        mockApi,
+        targets,
+        designEvidence,
+        dependencyPolicy,
+        deliveryFiles: projection.deliveryFiles,
+        missingVerificationRequirementIds: projection.missingVerificationRequirementIds,
+        unplacedRequirementIds: sorted(unplacedRequirementIds),
+        writeSetGaps: projection.writeSetGaps,
+        findings: sorted([
+            ...projection.findings,
+            ...unplacedRequirementIds.map(id => `unplaced-requirement:${id}`),
+        ]),
+    };
+}
+/** Fact kinds emitted by the experimental decision Plan tools. Each tool's
+ * entry mirrors the corresponding decision-schema array element exactly. */
+export const FRONTEND_DECISION_FACT_KINDS = [
+    "module-placement",
+    "reuse-decision",
+    "state-ownership",
+    "data-flow",
+    "api-mock-boundary",
+    "verification-focus",
+    "dependency",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Case/separator-insensitive identity used by `checkUxNameCollisions`. The
+ * decision ledger is append-only across retry attempts (a correction re-records
+ * a state/flow with `replace` only for id-keyed kinds), so the same concept
+ * legitimately appears under "increment counter", "increment-counter", … .
+ * Grouping by this identity and letting the LAST committed row win collapses
+ * retry churn onto the model's final correction instead of failing the derived
+ * canonical with ux-name-collision. */
+function planNameKey(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+const HTTP_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+]);
+const NO_DEPENDENCY_TOKENS = new Set(["none", "无", "无新增", "不新增"]);
+/**
+ * Compile the relationship-shaped plan patch from a *finalized* decision
+ * contract (the same one `finalizeDecision` derived the safety projection
+ * from). This is the decision → relationship bridge: after a successful
+ * decision finalize the executor publishes the patch here as a
+ * `target-surface` + `finalize_plan` ledger pair so the plan node's R1
+ * self-check and every downstream shell see the canonical compile authority
+ * they already consume on the relationship path.
+ *
+ * The pure function is intentionally free of the UI-name → requirement heuristics
+ * that plague relationship-model output: every row is bound from the decision's
+ * own group structure, so nothing is invented here.
+ */
+export function buildFrontendPlanRelationshipPatch(input) {
+    const { decision, authority } = input;
+    const groupByRequirement = new Map();
+    for (const group of authority.behaviorGroups) {
+        for (const id of group.requirementIds)
+            groupByRequirement.set(id, group.id);
+    }
+    const groupById = new Map(authority.behaviorGroups.map(group => [group.id, group]));
+    const placementPathsById = new Map(decision.modulePlacements.map(item => [item.id, item.paths]));
+    const vtIdsByGroup = new Map();
+    for (const focus of decision.verificationFocus) {
+        const ids = vtIdsByGroup.get(focus.behaviorGroupId) ?? [];
+        if (!ids.includes(focus.id))
+            ids.push(focus.id);
+        vtIdsByGroup.set(focus.behaviorGroupId, ids);
+    }
+    const requiredByRequirement = new Map();
+    for (const [requirementId, paths] of input.requiredDeliverables ?? []) {
+        const set = requiredByRequirement.get(requirementId) ?? new Set();
+        for (const file of paths)
+            if (file.trim())
+                set.add(file.trim());
+        requiredByRequirement.set(requirementId, set);
+    }
+    // ---- Raw state rows (dedupe by case/separator-insensitive name, last row
+    // wins). Canonical applicability/attribution is decided below after the
+    // component choices' group coverage is known.
+    const stateByKey = new Map();
+    const stateKeyOrder = [];
+    for (const entry of decision.stateOwnership) {
+        const key = planNameKey(entry.state);
+        if (!key)
+            continue;
+        if (!stateByKey.has(key))
+            stateKeyOrder.push(key);
+        stateByKey.set(key, entry);
+    }
+    // ---- interactions: derived from data flows; dedupe by name identity, last
+    // committed flow wins (the model's final correction vocabulary), and bind
+    // implementationTargets / verificationTargetIds from the flow source group.
+    const flowByKey = new Map();
+    const flowKeyOrder = [];
+    for (const flow of decision.dataFlows) {
+        const key = planNameKey(flow.interaction);
+        if (!key)
+            continue;
+        if (!flowByKey.has(key))
+            flowKeyOrder.push(key);
+        flowByKey.set(key, flow);
+    }
+    const interactions = [];
+    const interactionNamesByGroup = new Map();
+    for (const key of flowKeyOrder) {
+        const flow = flowByKey.get(key);
+        const groupId = flow.source;
+        interactions.push({
+            name: flow.interaction,
+            trigger: flow.trigger,
+            expectedBehavior: flow.expectedBehavior,
+            implementationTargets: sorted(placementPathsById.get(groupId) ?? []),
+            verificationTargetIds: sorted(vtIdsByGroup.get(groupId) ?? []),
+        });
+        const names = interactionNamesByGroup.get(groupId) ?? [];
+        names.push(flow.interaction);
+        interactionNamesByGroup.set(groupId, names);
+    }
+    // ---- Which behavior groups do the component decisions actually cover?
+    // A reuse row covers a group when one of its `covers` entries names the
+    // group directly or one of its requirement ids, or when the row's `purpose`
+    // is exactly an applicable state / interaction name owned by the group
+    // (single-purpose rows like "loading"). Union across every reuse row: a
+    // state row below may only stay applicable when its owner group is designed
+    // by at least one choice — a finalized decision set that declares an
+    // applicable state with no design choice is internally inconsistent, and the
+    // derived canonical cannot invent a component for it.
+    const rawStateByGroup = new Map();
+    for (const key of stateKeyOrder) {
+        const entry = stateByKey.get(key);
+        const names = rawStateByGroup.get(entry.owner) ?? [];
+        if (!names.includes(entry.state))
+            names.push(entry.state);
+        rawStateByGroup.set(entry.owner, names);
+    }
+    const designedGroupIds = new Set();
+    for (const entry of decision.reuseDecisions) {
+        for (const cover of entry.covers ?? []) {
+            const groupId = groupByRequirement.get(cover) ??
+                (groupById.has(cover) ? cover : undefined);
+            if (groupId)
+                designedGroupIds.add(groupId);
+        }
+        for (const [groupId, stateNames] of rawStateByGroup) {
+            if (stateNames.includes(entry.purpose))
+                designedGroupIds.add(groupId);
+        }
+        for (const [groupId, interactionNames] of interactionNamesByGroup) {
+            if (interactionNames.includes(entry.purpose))
+                designedGroupIds.add(groupId);
+        }
+    }
+    // ---- uiStates: canonical rows. Dedupe by case/separator-insensitive name
+    // (last row wins), bind applicable states to their owner group's placement +
+    // verification focus + covering component choice. Non-applicable states keep
+    // applicable:false + notApplicableReason. An applicable state the finalized
+    // decisions cannot realize is a contradiction inside the decision set, not a
+    // compile-time judgment call: silently demoting it to not-applicable (or
+    // dropping the row) would rewrite the model's design semantics behind its
+    // back, so the compiler fails with a repairable diagnostic instead — the
+    // finalize repair loop feeds it straight back to the model.
+    const unbindable = (name, groupId, problem) => new Error(`decision-state-unbindable: applicable state "${name}" (owner behavior group "${groupId}") ${problem} — fix the named record_* facts or resubmit the state row (same state, replace:true) with applicable:false plus notApplicableReason`);
+    const applicableStateNamesByGroup = new Map();
+    const declaredStateNamesByGroup = new Map();
+    const uiStates = [];
+    for (const key of stateKeyOrder) {
+        const entry = stateByKey.get(key);
+        const name = entry.state;
+        const groupId = entry.owner;
+        const declared = declaredStateNamesByGroup.get(groupId) ?? [];
+        if (!declared.includes(name))
+            declared.push(name);
+        declaredStateNamesByGroup.set(groupId, declared);
+        const state = {
+            name,
+            applicable: entry.applicable,
+        };
+        if (!entry.applicable) {
+            state.notApplicableReason =
+                entry.notApplicableReason ?? "not applicable by decision";
+            uiStates.push(state);
+            continue;
+        }
+        const implementationTargets = sorted(placementPathsById.get(groupId) ?? []);
+        const verificationTargetIds = sorted(vtIdsByGroup.get(groupId) ?? []);
+        if (implementationTargets.length === 0) {
+            throw unbindable(name, groupId, `has no module placement; record record_module_placement {id: "${groupId}", paths: [...]} or place the state under a placed group`);
+        }
+        if (verificationTargetIds.length === 0) {
+            throw unbindable(name, groupId, `has no verification focus; record record_verification_focus {behaviorGroupId: "${groupId}", ...}`);
+        }
+        if (!designedGroupIds.has(groupId)) {
+            throw unbindable(name, groupId, `is not covered by any component decision; record record_reuse_decision with purpose or covers including "${name}"`);
+        }
+        if (entry.expectedBehavior)
+            state.expectedBehavior = entry.expectedBehavior;
+        state.implementationTargets = implementationTargets;
+        state.verificationTargetIds = verificationTargetIds;
+        const names = applicableStateNamesByGroup.get(groupId) ?? [];
+        if (!names.includes(name))
+            names.push(name);
+        applicableStateNamesByGroup.set(groupId, names);
+        uiStates.push(state);
+    }
+    // ---- verificationTargets: one row per committed focus; requirementIds from
+    // the focus group's membership; uiStates from that group's applicable
+    // state-ownership rows so every behavior target references a declared state
+    // (falling back to the group's declared names when a pure-verification group
+    // owns no applicable state).
+    const verificationTargets = decision.verificationFocus.map(focus => {
+        const group = groupById.get(focus.behaviorGroupId);
+        const requirementIds = sorted(group?.requirementIds ?? []);
+        const uiStateNames = applicableStateNamesByGroup.get(focus.behaviorGroupId) ?? [];
+        const referencedStates = uiStateNames.length > 0
+            ? uiStateNames
+            : declaredStateNamesByGroup.get(focus.behaviorGroupId) ?? [];
+        return {
+            id: focus.id,
+            commandId: focus.commandId,
+            file: focus.file,
+            requirementIds,
+            uiStates: sorted(referencedStates),
+        };
+    });
+    const verificationTargetIds = new Set(verificationTargets.map(target => target.id));
+    // ---- requirements: derived group expansion + contract deliverable
+    // obligations. Every requirement must keep a placement and at least one
+    // verification target (both are guaranteed post-finalize because the
+    // decision safety projection blocks unplaced / unverified requirements).
+    const requirements = authority.requirements.map(requirement => {
+        const groupId = groupByRequirement.get(requirement.id);
+        const placed = sorted(placementPathsById.get(groupId ?? "") ?? []);
+        const deliverable = sorted(requiredByRequirement.get(requirement.id) ?? []);
+        const implementationTargets = sorted([...placed, ...deliverable]);
+        const derivedVerificationTargetIds = sorted([...(vtIdsByGroup.get(groupId ?? "") ?? [])].filter(id => verificationTargetIds.has(id)));
+        return {
+            id: requirement.id,
+            expectedOutcome: requirement.expectedOutcome,
+            implementationTargets,
+            deliverableTargets: deliverable,
+            verificationTargetIds: derivedVerificationTargetIds,
+        };
+    });
+    // ---- uiComponentChoices: reuse/new decisions keep their component identity;
+    // covers are expanded with the applicable state and interaction names of the
+    // behavior groups the choice already covers by requirement id (or group id).
+    // We never invent a component for an uncovered name.
+    const uiComponentChoices = decision.reuseDecisions.map(entry => {
+        const coveredGroupIds = new Set();
+        for (const cover of entry.covers ?? []) {
+            const groupId = groupByRequirement.get(cover) ??
+                (groupById.has(cover) ? cover : undefined);
+            if (groupId)
+                coveredGroupIds.add(groupId);
+        }
+        const expanded = sorted([...coveredGroupIds].flatMap(groupId => [
+            ...(applicableStateNamesByGroup.get(groupId) ?? []),
+            ...(interactionNamesByGroup.get(groupId) ?? []),
+        ]));
+        // Explicit state/interaction names the model listed stay; requirement /
+        // group ids in covers were the expansion source and are replaced by the
+        // derived names (covers is the choice→UX-name map the policy reads).
+        const explicitNames = (entry.covers ?? []).filter(cover => !groupByRequirement.has(cover) && !groupById.has(cover));
+        const choice = {
+            purpose: entry.purpose,
+            component: entry.symbol,
+            decision: entry.decision,
+            rationale: entry.rationale ?? "",
+        };
+        if (entry.decision === "reuse-existing") {
+            if (entry.evidence.length > 0)
+                choice.evidencePath = entry.evidence[0];
+            choice.specReference = null;
+        }
+        else if (entry.evidence.length > 0 && entry.specSection) {
+            // The canonical contract schema mandates specReference.section for
+            // specified/new choices; the tool gate requires specSection up front,
+            // so a row reaching here without one stays specReference-less and the
+            // contract superRefine reports it against the decision channel.
+            choice.specReference = { path: entry.evidence[0], section: entry.specSection };
+        }
+        const covers = sorted([...expanded, ...explicitNames]);
+        if (covers.length > 0)
+            choice.covers = covers;
+        return choice;
+    });
+    // ---- stylingStrategy: task-wide style contract. The relationship channel
+    // sets it once on any component choice; the decision channel mirrors that.
+    // Rows naming different strategies contradict each other, and silently
+    // keeping one would drop the other behind the model's back, so the compiler
+    // reports the conflict for repair instead of picking a winner.
+    const strategyRows = decision.reuseDecisions
+        .filter(entry => typeof entry.stylingStrategy === "string" && entry.stylingStrategy.trim().length > 0)
+        .map(entry => ({ purpose: entry.purpose, strategy: entry.stylingStrategy.trim() }));
+    const strategiesByValue = new Map();
+    for (const row of strategyRows) {
+        const purposes = strategiesByValue.get(row.strategy) ?? [];
+        if (!purposes.includes(row.purpose))
+            purposes.push(row.purpose);
+        strategiesByValue.set(row.strategy, purposes);
+    }
+    if (strategiesByValue.size > 1) {
+        const breakdown = [...strategiesByValue.entries()]
+            .map(([strategy, purposes]) => `${JSON.stringify(strategy)} (on ${purposes.join(", ")})`)
+            .join(" vs ");
+        throw new Error(`decision-styling-strategy-conflict: reuse decisions declare different stylingStrategy values: ${breakdown} — the task-wide style contract must be one statement; resubmit the losing rows (same purpose, replace:true) without stylingStrategy`);
+    }
+    const stylingStrategy = strategyRows[0]?.strategy;
+    // ---- mockApi: never fabricate endpoints from prose boundaries. All
+    // not-needed boundaries → not-needed. A real/mock boundary becomes an
+    // endpoint only when the boundary parses as "<METHOD> /path" with a frozen
+    // method; fixture/consumer are bound to derived implementation paths.
+    // ---- mock boundaries: dedupe by trimmed boundary identity (last row wins)
+    // so a mock→real correction replaces the superseded decision instead of
+    // leaving its stale fixture/mode in play alongside the correction.
+    const boundaryByKey = new Map();
+    const boundaryOrder = [];
+    for (const boundary of decision.apiMockBoundaries) {
+        const key = boundary.boundary.trim();
+        if (!key)
+            continue;
+        if (!boundaryByKey.has(key))
+            boundaryOrder.push(key);
+        boundaryByKey.set(key, boundary);
+    }
+    const boundaries = boundaryOrder.map(key => boundaryByKey.get(key));
+    const allNotNeeded = boundaries.length > 0 && boundaries.every(boundary => boundary.mode === "not-needed");
+    const mockStrategy = allNotNeeded
+        ? "not-needed"
+        : boundaries.some(boundary => boundary.mode === "mock")
+            ? "browser-intercept"
+            : boundaries.some(boundary => boundary.mode === "real")
+                ? "native"
+                : "not-needed";
+    const endpoints = [];
+    if (!allNotNeeded && mockStrategy !== "not-needed") {
+        for (const boundary of boundaries) {
+            if (boundary.mode === "not-needed")
+                continue;
+            const match = /^\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/\S.*?)\s*$/.exec(boundary.boundary);
+            if (!match)
+                continue;
+            const method = match[1];
+            if (!HTTP_METHODS.has(method))
+                continue;
+            const pathValue = match[2].trim();
+            if (!pathValue.startsWith("/"))
+                continue;
+            // Design policy hard-requires fixture + consumer on every endpoint. The
+            // decision channel is their only honest source: fabricating a default
+            // fixture path or the first placement as consumer would point the mock
+            // evidence chain at files the model never planned, so an endpoint whose
+            // decision lacks them fails the compile with a named repair instead.
+            const missing = [!boundary.fixture?.trim() && "fixture", !boundary.consumer?.trim() && "consumer"].filter(Boolean).join(" and ");
+            if (missing) {
+                throw new Error(`decision-mock-endpoint-unbindable: ${boundary.mode} boundary "${boundary.boundary}" has no ${missing}; record record_api_mock_boundary with the same boundary plus fixture (the test fixture path) and consumer (the implementation file that calls it), or mark the boundary not-needed`);
+            }
+            endpoints.push({
+                method,
+                path: pathValue,
+                fixture: boundary.fixture,
+                consumer: boundary.consumer,
+            });
+        }
+    }
+    const mockApi = {
+        strategy: mockStrategy,
+        activation: mockStrategy === "not-needed"
+            ? "n/a; no backend or remote request path"
+            : "explicit activation boundary",
+        endpoints,
+    };
+    // ---- dependencyPolicy: explicit declarative no-new-dependencies default
+    // when the model recorded no real dependency names ("none"/"无" tokens are
+    // not package names).
+    const dependencies = decision.dependencies.filter(name => !NO_DEPENDENCY_TOKENS.has(name.trim().toLowerCase()) && name.trim() !== "");
+    const dependencyPolicy = dependencies.length > 0 ? dependencies.join(", ") : "零新增，不新增 npm 依赖";
+    return {
+        requirements,
+        uiStates,
+        interactions,
+        verificationTargets,
+        uiComponentChoices,
+        mockApi,
+        dependencyPolicy,
+        ...(stylingStrategy ? { stylingStrategy } : {}),
+    };
+}
+const repairAssertionSchema = z.discriminatedUnion("check", [
+    z.object({ check: z.literal("file-absent"), token: z.string().min(1), source: z.string() }).strict(),
+    z.object({ check: z.literal("state-present"), token: z.string().min(1), source: z.string() }).strict(),
+    z.object({ check: z.literal("vt-changed"), token: z.string().min(1), source: z.string(),
+        expectedRequirementIds: z.array(z.string().min(1)).min(1) }).strict(),
+]);
+/** No heuristic fallback: absent structured expectations mean that semantic
+ * closure must be decided by the subsequent design review. Invalid explicit
+ * assertions throw rather than silently disabling a requested check. */
+export function extractRepairAssertions(findings, _parentCanonical) {
+    return findings.flatMap(finding => z.array(repairAssertionSchema).parse(finding.repairAssertions ?? []));
+}
+/**
+ * Fields that annotate a decision but cannot change what the plan decides:
+ * justification prose, the human-readable purpose, the non-applicability
+ * explanation, and the source citation. They are excluded from the recovery
+ * decision identity.
+ *
+ * Smoke r34: the identity guard (rationale-only at the time) blocked a
+ * no-op repair twice, and the child then cleared it by rewriting only
+ * `uiComponentChoices[].specReference` — the citation for a choice whose
+ * ownership mapping had not changed at all. A repair must move a decision the
+ * machine reads (targets, implementation mappings, states, coverage, plan
+ * requirements, verification targets), never just the words around it.
+ */
+const DECISION_FREE_TEXT_KEYS = new Set([
+    "rationale",
+    "purpose",
+    "notApplicableReason",
+    "specReference",
+]);
+export function stripDecisionFreeText(value) {
+    if (Array.isArray(value))
+        return value.map(stripDecisionFreeText);
+    if (value && typeof value === "object") {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source)) {
+            if (DECISION_FREE_TEXT_KEYS.has(key))
+                continue;
+            out[key] = stripDecisionFreeText(source[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Identity of a compiled plan's decisions, ignoring justification prose.
+ *
+ * The recovery identical-plan guard used a raw content hash, so smoke r27
+ * showed a repair child clearing `DECISION_REPAIR_NO_CHANGE` by rewriting two
+ * `rationale` strings while every structured decision row — targets,
+ * implementation mappings, states, verification targets — stayed identical.
+ * The guard compares this projection instead, so "no decision changed" is a
+ * blocked repair regardless of prose edits. Semantics beyond that remain the
+ * design review's judgment.
+ */
+export function decisionIdentitySha256(canonical) {
+    return deterministicSha256(stripDecisionFreeText(canonical));
+}
+/**
+ * Evaluate the repair closure: every assertion must hold on the child
+ * canonical. `unmet` names exactly what the model still has to change, so a
+ * failed closure is a repairable finalize rejection, never a silent pass.
+ */
+export function evaluateRepairClosure(assertions, childCanonical, parentCanonical) {
+    const childFiles = (childCanonical.targets?.files ?? []).map((f) => String(f));
+    const childStates = new Set((childCanonical.uiStates ?? [])
+        .filter((state) => state.applicable !== false)
+        .map((state) => String(state.name ?? "")));
+    const childVtById = new Map((childCanonical.verificationTargets ?? []).map((target) => [
+        String(target.id ?? ""),
+        target,
+    ]));
+    const parentVtById = new Map((parentCanonical.verificationTargets ?? []).map((target) => [
+        String(target.id ?? ""),
+        target,
+    ]));
+    const unmet = [];
+    for (const assertion of assertions) {
+        if (assertion.check === "file-absent") {
+            if (childFiles.some((file) => file === assertion.token)) {
+                unmet.push(`file-absent: "${assertion.token}" is still present in the child canonical (targets.files/implementationTargets)`);
+            }
+        }
+        else if (assertion.check === "state-present") {
+            if (!childStates.has(assertion.token)) {
+                unmet.push(`state-present: applicable UI state "${assertion.token}" is still missing from the child canonical`);
+            }
+        }
+        else if (assertion.check === "vt-changed") {
+            const child = childVtById.get(assertion.token);
+            const parent = parentVtById.get(assertion.token);
+            if (!child || !parent) {
+                unmet.push(`vt-changed: VT "${assertion.token}" is missing from the child canonical`);
+            }
+            else {
+                const expected = JSON.stringify([...new Set(assertion.expectedRequirementIds)].sort());
+                const actualIds = Array.isArray(child.requirementIds) ? child.requirementIds.map(String) : [];
+                const actual = JSON.stringify([...new Set(actualIds)].sort());
+                if (actual !== expected)
+                    unmet.push(`vt-changed: VT "${assertion.token}" does not map to the required requirementIds`);
+            }
+        }
+    }
+    return { closed: unmet.length === 0, unmet };
+}
+/** Last-wins collapse of committed decision entries by their natural
+ * identity (id/purpose/state/interaction/boundary). Shared by the ledger
+ * compile and the recovery snapshot builder so both see exactly the same
+ * surviving rows. Keyless rows are kept: schema validation still rejects
+ * malformed entries instead of silently dropping them. */
+export function collapseDecisionEntriesByKind(kind, collected) {
+    const keyOf = (entry) => {
+        const key = kind === "module-placement" || kind === "verification-focus"
+            ? entry.id
+            : kind === "reuse-decision"
+                ? entry.purpose
+                : kind === "state-ownership"
+                    ? entry.state
+                    : kind === "data-flow"
+                        ? entry.interaction
+                        : kind === "api-mock-boundary"
+                            ? typeof entry.boundary === "string" ? entry.boundary.trim() : undefined
+                            : undefined;
+        return typeof key === "string" && key ? key : undefined;
+    };
+    const byKey = new Map();
+    const keyless = [];
+    // Retracted tombstones remove their own key and every other record keyed to
+    // the same interaction — a wrong-named record cannot survive a rename (r19).
+    const retractedKeys = new Set();
+    for (const entry of collected) {
+        if (entry.retracted === true && typeof entry.interaction === "string") {
+            retractedKeys.add(entry.interaction);
+        }
+    }
+    for (const entry of collected) {
+        if (entry.retracted === true)
+            continue;
+        const key = keyOf(entry);
+        if (kind === "data-flow" && typeof entry.interaction === "string" && retractedKeys.has(entry.interaction))
+            continue;
+        if (key)
+            byKey.set(key, entry);
+        else
+            keyless.push(entry);
+    }
+    return byKey.size > 0 ? [...byKey.values(), ...keyless] : [...collected];
+}
+/** Compile committed decision facts into a FrontendPlanDecisionContract. Each
+ * fact's `entry` is already schema-shaped (the tool validates it); this collects
+ * entries by kind into the decision arrays and re-validates the whole. This is
+ * the compile authority for the experimental decision Plan path and is the
+ * runtime counterpart to the model emitting decision facts instead of the
+ * per-AC relationship table. */
+export function assembleDecisionContractFromFacts(facts) {
+    const committed = facts.filter(fact => fact.origin === undefined || fact.origin === "plan");
+    // Durable resubmission with replace:true appends a *new* ledger record with the
+    // same natural identity instead of physically deleting the superseded one
+    // (mirroring the relationship ledger, where the compiler resolves replaces).
+    // Without a last-wins collapse here, a correction that re-records the same VT
+    // id compiles into duplicate entries and every subsequent finalize fails with
+    // duplicate-verification even though the model did exactly what replace told
+    // it to. Identity is per kind: module placement and verification focus are
+    // keyed by entry.id; the committed array is already in ledger (revision)
+    // order, so the last record with a given key wins.
+    const committedEntries = (kind) => {
+        const collected = committed
+            .filter(fact => fact.kind === kind && isRecord(fact.entry))
+            .map(fact => fact.entry);
+        return collapseDecisionEntriesByKind(kind, collected);
+    };
+    const entries = committedEntries;
+    return frontendPlanDecisionContractSchema.parse({
+        schemaId: "frontend-plan-decision-contract-v1",
+        modulePlacements: entries("module-placement"),
+        reuseDecisions: entries("reuse-decision"),
+        stateOwnership: entries("state-ownership"),
+        dataFlows: entries("data-flow"),
+        apiMockBoundaries: entries("api-mock-boundary"),
+        dependencies: entries("dependency").flatMap(entry => {
+            const names = Array.isArray(entry.names) ? entry.names : [entry.name];
+            return names.filter((name) => typeof name === "string" && name.length > 0);
+        }),
+        verificationFocus: entries("verification-focus"),
+    });
+}