@tea-agent/loop-agent 0.42.0-next.9 → 0.42.1

package/dist/worker/observe/static/views/task.js

@@ -1,3 +1,5 @@
+import { inspectRouteStates } from "../state.js";
+import { mergeTaskHistoryPage } from "../task-history.js";
 /** Observe UI view module (R5). */
 import {
 	UI_TEXT,
@@ -16,7 +18,7 @@ import {
 	DAG_EFFECTIVE_STATUS_LABELS,
 	STATUS_LABELS,
 } from "../constants.js";
-import { clearNode, el, metaGrid, buildTable } from "../dom.js";
+import { clearNode, el, metaGrid, buildTable, reconcileKeyed } from "../dom.js";
 import {
 	badge,
 	badgeClass,
@@ -45,6 +47,7 @@ import {
 import {
 	fetchJson,
 	fetchJsonResult,
+	summarizeFetchError,
 	artifactUrl,
 	parseArtifactPreviewResponse,
 } from "../api.js";
@@ -66,7 +69,7 @@ import {
 	renderViewState,
 	mountViewState,
 } from "../state.js";
-import { uiState } from "../state.js";
+import { uiState, taskHistoryStates, workspaceScope } from "../state.js";
 import { sortPoolTasks } from "../format-pool.js";
 import {
 	dagMetaVisibility,
@@ -75,7 +78,7 @@ import {
 	findDagForRun,
 } from "../dag-model.js";
 import { layoutDag } from "../dag-layout.js";
-import { showView, setBreadcrumb, updateHeaderRefresh, mountRelationBar } from "../shell-chrome.js";
+import { showView, setBreadcrumb, updateHeaderRefresh, mountRelationBar, bindManualViewRefresh } from "../shell-chrome.js";
 import { artifactLink } from "../kpi.js";
 import { findBatchRunIdForTask, taskRunHistoryRow } from "../run-processing.js";
 
@@ -91,7 +94,7 @@ export async function renderTaskDetail(featureId, taskId) {
 	showView("task");
 	setBreadcrumb([
 		{ label: UI_TEXT.dashboard, href: "#/" },
-		{ label: "资源池", href: "/#/inspect/pool" },
+		{ label: "资源池", href: inspectRouteStates.get("return-list") ?? "/#/inspect/pool" },
 		{ label: displayLabel },
 	]);
 
@@ -103,13 +106,29 @@ export async function renderTaskDetail(featureId, taskId) {
 	const ledgerEl = document.getElementById("task-ledger");
 	if (!metaEl || !linksEl || !evidenceEl || !runsEl) return false;
 	if (titleEl) titleEl.textContent = displayLabel;
-	mountViewState(metaEl, "loading", "加载 Task…");
+	const identity = `${workspaceScope() ?? ""}:${featureId ?? ""}:${taskId}`;
+	const requestGeneration = uiState.pollingGeneration;
+	if (metaEl.dataset.taskIdentity !== identity) {
+		metaEl.dataset.taskIdentity = identity;
+		mountViewState(metaEl, "loading", "加载 Task…");
+		clearNode(runsEl);
+		for (const element of [linksEl, evidenceEl, ledgerEl]) if (element) clearNode(element);
+	}
+	if (!taskHistoryStates.has(identity)) taskHistoryStates.set(identity, { runs: [], nextBefore: null, loadedOlder: false, loadingOlder: false });
+	const historyState = taskHistoryStates.get(identity);
 
 	const [taskResult, historyResult, snapshot] = await Promise.all([
 		fetchJsonResult(taskApi),
 		fetchJsonResult(`${taskApi}/runs?limit=20`),
 		fetchJson("/api/snapshot"),
 	]);
+	if (requestGeneration !== uiState.pollingGeneration || metaEl.dataset.taskIdentity !== identity) return false;
+	if (!taskResult.ok && ![404, 409].includes(taskResult.status)) {
+		let error = metaEl.querySelector(".task-refresh-error");
+		if (!error) { error = el("p", "task-refresh-error node-input-error"); metaEl.appendChild(error); }
+		error.textContent = `更新失败，保留上次内容。${summarizeFetchError(taskResult)}`;
+		return true;
+	}
 	const task = taskResult.ok ? taskResult.body : null;
 	const history = historyResult.ok ? historyResult.body : null;
 	if (snapshot) {
@@ -120,7 +139,6 @@ export async function renderTaskDetail(featureId, taskId) {
 	clearNode(metaEl);
 	clearNode(linksEl);
 	clearNode(evidenceEl);
-	clearNode(runsEl);
 
 	if (!task) {
 		if (taskResult.status === 409) {
@@ -234,27 +252,9 @@ export async function renderTaskDetail(featureId, taskId) {
 		evidenceEl.appendChild(evidenceLinks);
 	}
 
-	runsEl.appendChild(el("h3", "section-heading", "运行历史"));
-	const runs = history?.runs ?? [];
-	if (runs.length === 0) {
-		mountViewState(runsEl, "empty", "暂无 ledger 运行记录。");
-	} else {
-		const rows = runs.map(taskRunHistoryRow);
-		runsEl.appendChild(
-			buildTable(
-				["worker run", "状态", "时间", "batch", "retryOf", "失败分类"],
-				rows,
-			),
-		);
-		if (history?.nextBefore) {
-			const more = el("button", "link-button", "加载更早的运行");
-			more.type = "button";
-			more.addEventListener("click", () => {
-				void loadOlderTaskRuns(featureId, taskId, history.nextBefore, runsEl);
-			});
-			runsEl.appendChild(more);
-		}
-	}
+	if (history) mergeTaskHistoryPage(historyState, history);
+	else historyState.error = summarizeFetchError(historyResult);
+	renderTaskHistory(runsEl, historyState, featureId, taskId, identity);
 
 	const active = ["running", "pending", "blocked", "stale"].includes(
 		(task.status ?? "").toLowerCase(),
@@ -262,6 +262,8 @@ export async function renderTaskDetail(featureId, taskId) {
 	if (ledgerEl) {
 		void renderTaskLedger(ledgerEl, taskId);
 	}
+	updateHeaderRefresh(snapshot?.generatedAt ?? uiState.lastSnapshot?.generatedAt, { mode: active ? "auto" : "ended" });
+	bindManualViewRefresh("task", () => renderTaskDetail(featureId, taskId));
 	return active;
 }
 
@@ -315,42 +317,59 @@ async function renderTaskLedger(ledgerEl, taskId) {
 	ledgerEl.appendChild(pre);
 }
 
-export async function loadOlderTaskRuns(featureId, taskId, before, runsEl) {
-	if (runsEl === undefined) {
-		runsEl = before;
-		before = taskId;
-		taskId = featureId;
-		featureId = undefined;
+function renderTaskHistory(runsEl, state, featureId, taskId, identity) {
+	if (runsEl.dataset.historyIdentity !== identity) { clearNode(runsEl); runsEl.dataset.historyIdentity = identity; }
+	let table = runsEl.querySelector("table");
+	if (!table) {
+		runsEl.appendChild(el("h3", "section-heading", "运行历史"));
+		table = buildTable(["worker run", "状态", "时间", "batch", "retryOf", "失败分类"], []);
+		runsEl.appendChild(table);
+		const status = el("p", "muted task-history-status");
+		status.setAttribute("role", "status");
+		runsEl.appendChild(status);
+		const more = el("button", "link-button", "加载更早的运行");
+		more.type = "button";
+		more.addEventListener("click", () => { void loadOlderTaskRuns(featureId, taskId, state.nextBefore, runsEl); });
+		runsEl.appendChild(more);
 	}
-	const taskApi = featureId
-		? `/api/features/${encodeURIComponent(featureId)}/tasks/${encodeURIComponent(taskId)}`
-		: `/api/tasks/${encodeURIComponent(taskId)}`;
-	const page = await fetchJson(
-		`${taskApi}/runs?limit=20&before=${encodeURIComponent(before)}`,
-	);
-	if (!page?.runs?.length) return;
-	const table = runsEl.querySelector("table");
-	if (!table) return;
-	const tbody = table.querySelector("tbody") || table;
-	for (const run of page.runs) {
-		const tr = document.createElement("tr");
-		for (const cell of taskRunHistoryRow(run).cells) {
-			const td = document.createElement("td");
-			if (cell instanceof Node) td.appendChild(cell);
-			else td.textContent = cell;
-			tr.appendChild(td);
-		}
-		tbody.appendChild(tr);
-	}
-	const btn = runsEl.querySelector("button.link-button");
-	if (btn) {
-		if (page.nextBefore) {
-			btn.onclick = () => {
-				void loadOlderTaskRuns(featureId, taskId, page.nextBefore, runsEl);
-			};
-		} else {
-			btn.remove();
-		}
+	reconcileKeyed(table.querySelector("tbody"), state.runs, {
+		getKey: (run) => run.workerRunId,
+		create: () => el("tr"),
+		update: (row, run) => {
+			const signature = JSON.stringify(run);
+			if (row.dataset.signature === signature) return;
+			clearNode(row);
+			for (const cell of taskRunHistoryRow(run).cells) {
+				const td = el("td");
+				if (cell instanceof Node) td.appendChild(cell); else td.textContent = cell ?? "—";
+				row.appendChild(td);
+			}
+			row.dataset.signature = signature;
+		},
+	});
+	const status = runsEl.querySelector(".task-history-status");
+	status.textContent = state.error ? `历史加载失败：${state.error}` : state.runs.length ? `已加载 ${state.runs.length} 次运行` : "暂无 ledger 运行记录。";
+	const more = runsEl.querySelector("button.link-button");
+	more.hidden = !state.nextBefore && !state.error;
+	more.disabled = state.loadingOlder;
+	more.textContent = state.loadingOlder ? "正在加载…" : state.error ? "重试加载" : "加载更早的运行";
+}
+
+export async function loadOlderTaskRuns(featureId, taskId, before, runsEl) {
+	const identity = `${workspaceScope() ?? ""}:${featureId ?? ""}:${taskId}`;
+	const state = taskHistoryStates.get(identity);
+	if (!state || state.loadingOlder) return;
+	state.loadingOlder = true;
+	renderTaskHistory(runsEl, state, featureId, taskId, identity);
+	const taskApi = featureId ? `/api/features/${encodeURIComponent(featureId)}/tasks/${encodeURIComponent(taskId)}` : `/api/tasks/${encodeURIComponent(taskId)}`;
+	try {
+		const result = await fetchJsonResult(`${taskApi}/runs?limit=20${state.nextBefore ? `&before=${encodeURIComponent(state.nextBefore)}` : ""}`);
+		if (taskHistoryStates.get(identity) !== state) return;
+		if (result.ok && result.body) mergeTaskHistoryPage(state, result.body, Boolean(state.nextBefore));
+		else state.error = summarizeFetchError(result);
+	} finally {
+		state.loadingOlder = false;
+		if (runsEl.dataset.historyIdentity === identity && taskHistoryStates.get(identity) === state) renderTaskHistory(runsEl, state, featureId, taskId, identity);
 	}
 }
 

package/dist/workflows/dag/backend-test-plan-protocol.js

@@ -101,6 +101,110 @@ export function lookupRequiredVariantSlotsForMarkdownPath(inventory, markdownPat
         .replace(/\.md$/i, "");
     return inventory.modules.find((item) => item.stem === stem)?.requiredVariantSlots ?? [];
 }
+const MODULE_INDEX_HEADER = [
+    "Module Stem",
+    "Business Resource",
+    "Owned Operations",
+    "Owned Rule Keys",
+    "Case IDs",
+    "Split Reason",
+    "Markdown Path",
+    "Pytest Path",
+];
+function markdownTableCells(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
+        return undefined;
+    return trimmed
+        .slice(1, -1)
+        .split("|")
+        .map((cell) => cell.trim().replace(/^`|`$/g, ""));
+}
+function isMarkdownSeparatorRow(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+/** Validate the minimum complete run-owned Markdown protocol before N2 succeeds. */
+export function assessBackendTestPlanProtocol(markdown) {
+    const canonical = canonicalizeBackendTestPlanProtocolHeadings(markdown).markdown;
+    const lines = canonical.split("\n");
+    const issues = [];
+    if (lines.some((line) => /^(?:```|~~~)/.test(line.trim()))) {
+        issues.push({
+            code: "fenced-plan-output",
+            detail: "return the final Markdown plan directly, without a code fence",
+        });
+    }
+    const headingIndexes = new Map();
+    for (const heading of [
+        "Coverage Scope",
+        "Coverage Matrix",
+        "Scenario Partitions",
+        "Module Index",
+    ]) {
+        headingIndexes.set(heading, lines.flatMap((line, index) => line.trim() === `## ${heading}` ? [index] : []));
+    }
+    const requireUnique = (heading, missingCode, duplicateCode) => {
+        const count = headingIndexes.get(heading)?.length ?? 0;
+        if (count === 0) {
+            issues.push({
+                code: missingCode,
+                detail: `require exactly one exact ## ${heading} section`,
+            });
+        }
+        else if (count > 1) {
+            issues.push({
+                code: duplicateCode,
+                detail: `found ${count}; require exactly one exact ## ${heading} section`,
+            });
+        }
+    };
+    // Module Index is first so retry diagnostics lead with the shard authority.
+    requireUnique("Module Index", "missing-module-index", "duplicate-module-index");
+    requireUnique("Coverage Scope", "missing-coverage-scope", "duplicate-coverage-scope");
+    requireUnique("Coverage Matrix", "missing-coverage-matrix", "duplicate-coverage-matrix");
+    const scenarioCount = headingIndexes.get("Scenario Partitions")?.length ?? 0;
+    if (scenarioCount > 1) {
+        issues.push({
+            code: "duplicate-scenario-partitions",
+            detail: `found ${scenarioCount}; require at most one exact ## Scenario Partitions section`,
+        });
+    }
+    const moduleIndexes = headingIndexes.get("Module Index") ?? [];
+    if (moduleIndexes.length === 1) {
+        const start = moduleIndexes[0] + 1;
+        const nextHeading = lines
+            .slice(start)
+            .findIndex((line) => /^##\s+\S/.test(line.trim()));
+        const end = nextHeading < 0 ? lines.length : start + nextHeading;
+        const rows = lines
+            .slice(start, end)
+            .map(markdownTableCells)
+            .filter((cells) => cells !== undefined);
+        const headerIndex = rows.findIndex((cells) => cells.length === MODULE_INDEX_HEADER.length &&
+            MODULE_INDEX_HEADER.every((name, index) => cells[index] === name));
+        if (headerIndex < 0) {
+            issues.push({
+                code: "invalid-module-index-header",
+                detail: `require exact Module Index header: ${MODULE_INDEX_HEADER.join(" | ")}`,
+            });
+        }
+        else {
+            const dataRows = rows
+                .slice(headerIndex + 1)
+                .filter((cells) => !isMarkdownSeparatorRow(cells));
+            if (!dataRows.some((cells) => cells.length === MODULE_INDEX_HEADER.length &&
+                Boolean(cells[0]?.trim()) &&
+                Boolean(cells[6]?.trim()) &&
+                Boolean(cells[7]?.trim()))) {
+                issues.push({
+                    code: "empty-module-index",
+                    detail: "Module Index must contain at least one complete 8-cell module row",
+                });
+            }
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
 export function isCanonicalPlanHeadingLine(line) {
     return CANONICAL_HEADING_LINE.test(line.trim());
 }

package/dist/workflows/dag/budget-enforcement.js

@@ -1,6 +1,56 @@
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
-import { checkBudgetPreNode, createBudgetLedger, formatBudgetReportMarkdown, isHardBudgetBreached, recordNodeBudgetSample, skipPendingNodesForBudgetBreach, } from "../../application/evaluation/budget.js";
+import { checkBudgetPreNode, createBudgetLedger, formatBudgetReportMarkdown, isHardBudgetBreached, recordNodeBudgetSample, reserveProviderBudget, skipPendingNodesForBudgetBreach, } from "../../application/evaluation/budget.js";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+/** A continuation already contains its ancestors' consumption. Never sum both. */
+export function validateCumulativeBudgetSuccessor(parent, child) {
+    const lineage = child.continuation?.budgetLineage ?? child.frontendRecoveryState?.budgetLineage;
+    const previous = parent.budgetLedger;
+    const next = child.budgetLedger;
+    if (!previous || !next || !lineage || (child.continuation?.parentRunId ?? child.frontendRecoveryState?.parentRunId) !== parent.runId || lineage.parentLedgerSha256 !== sha256OfCanonicalJson(previous) || sha256OfCanonicalJson(lineage.inheritedConsumed) !== sha256OfCanonicalJson(previous.consumed) || sha256OfCanonicalJson(parent.budget ?? null) !== sha256OfCanonicalJson(child.budget ?? null))
+        throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: unbound cumulative continuation");
+    for (const key of ["executorCalls", "providerRequests", "wallTimeMs", "repairPasses", "peakContextChars"])
+        if ((next.consumed[key] ?? 0) < (previous.consumed[key] ?? 0))
+            throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: consumption decreased");
+    return next;
+}
+const requestQueues = new WeakMap();
+/** One shared, attempt-fenced, durable admission queue for every request in a run. */
+export async function reserveDagProviderRequest(input) {
+    const ledger = input.state.budgetLedger;
+    if (!ledger || ledger.limits.maxProviderRequests === undefined)
+        throw Error("FRONTEND_PROVIDER_BUDGET_INVALID: frozen request budget unavailable");
+    const previous = requestQueues.get(ledger) ?? Promise.resolve();
+    const current = previous.catch(() => { }).then(async () => {
+        const active = () => input.state.status === "running" && input.state.nodes[input.nodeId]?.status === "RUNNING" && input.state.nodes[input.nodeId]?.currentAttempt === input.attempt;
+        if (!active())
+            throw Error("FRONTEND_PROVIDER_BUDGET_STALE: request belongs to an inactive attempt");
+        if (isHardBudgetBreached(ledger))
+            throw Error("FRONTEND_PROVIDER_BUDGET_EXHAUSTED: run budget already breached");
+        const breach = reserveProviderBudget(ledger, input.nodeId);
+        if (breach)
+            applyHardBudgetBreach(input.state, breach);
+        try {
+            await input.persist();
+        }
+        catch (error) {
+            ledger.status = "breached";
+            throw Error(`FRONTEND_PROVIDER_BUDGET_PERSIST_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (breach)
+            throw Error("FRONTEND_PROVIDER_BUDGET_EXHAUSTED: request quota reached");
+        if (!active())
+            throw Error("FRONTEND_PROVIDER_BUDGET_STALE: attempt stopped while reserving request");
+    });
+    requestQueues.set(ledger, current);
+    try {
+        await current;
+    }
+    finally {
+        if (requestQueues.get(ledger) === current)
+            requestQueues.delete(ledger);
+    }
+}
 export function initRunBudgetLedger(state, budget) {
     if (!budget)
         return;
@@ -8,7 +58,7 @@ export function initRunBudgetLedger(state, budget) {
     state.budgetLedger = createBudgetLedger(budget);
 }
 function wallTimeMs(state, now = Date.now()) {
-    const lineage = state.continuation?.budgetLineage;
+    const lineage = state.continuation?.budgetLineage ?? state.frontendRecoveryState?.budgetLineage;
     if (lineage) {
         return (lineage.inheritedConsumed.wallTimeMs +
             Math.max(0, now - new Date(lineage.inheritedAt).getTime()));
@@ -16,7 +66,7 @@ function wallTimeMs(state, now = Date.now()) {
     return Math.max(0, now - new Date(state.startedAt).getTime());
 }
 function repairPasses(state) {
-    const lineage = state.continuation?.budgetLineage;
+    const lineage = state.continuation?.budgetLineage ?? state.frontendRecoveryState?.budgetLineage;
     if (lineage) {
         return (lineage.inheritedConsumed.repairPasses +
             Math.max(0, (state.convergence?.currentPass ?? 1) - 1));

package/dist/workflows/dag/dag-retry-schema.js

@@ -32,7 +32,10 @@ export const DEFAULT_DAG_RETRY_CATEGORIES = [
     "rate-limit",
     "unavailable",
     "empty-output",
+    "output-limit",
 ];
+/** Provider stopReason=length: output/context capacity ended the turn early. */
+export const OUTPUT_LIMIT_RETRY_CATEGORY = "output-limit";
 export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
 export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 /** Recoverable model artifact/schema formatting failure on read-only structured nodes. */

package/dist/workflows/dag/frontend-capacity.js

@@ -0,0 +1,9 @@
+/** Shared Contract/Plan bound. Permissions and directory globs are not files. */
+export const FRONTEND_MAX_IMPLEMENTATION_FILES = 15;
+export function frontendConcreteDeliveryFiles(files) {
+    if (!Array.isArray(files))
+        return [];
+    return [...new Set(files.filter((file) => typeof file === "string")
+            .map(file => file.trim().replace(/\\/g, "/").replace(/^(\.\/)+/, ""))
+            .filter(file => file.length > 0 && !/[*?{}]/.test(file) && !file.endsWith("/")))];
+}

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

@@ -0,0 +1,130 @@
+import { z } from "zod";
+/** Shared projections of committed frontend facts. Callers filter commit phase. */
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Join requirement-owned identity with separately committed evidence by id.
+ * Later evidence declarations replace only the lanes they explicitly name. */
+export function resolveFrontendContractRequirements(facts) {
+    const contractFacts = facts.map(object).filter((fact) => fact?.origin === "contract");
+    const evidenceById = new Map();
+    for (const fact of contractFacts) {
+        if (fact.kind !== "evidence-expectation" ||
+            typeof fact.requirementId !== "string")
+            continue;
+        evidenceById.set(fact.requirementId, {
+            ...evidenceById.get(fact.requirementId),
+            ...object(fact.evidence),
+        });
+    }
+    return contractFacts.flatMap((fact) => fact.kind === "requirement" && typeof fact.id === "string"
+        ? [{
+                ...fact,
+                id: fact.id,
+                evidence: { ...object(fact.evidence), ...evidenceById.get(fact.id) },
+            }]
+        : []);
+}
+function names(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string" && item.trim().length > 0)
+        : [];
+}
+const evidenceStatus = z.enum(["required", "optional", "not-applicable"]);
+export const frontendEvidenceExpectationSchema = z.object({
+    requirementId: z.string().min(1),
+    evidence: z.object({
+        static: evidenceStatus.optional(),
+        behavior: evidenceStatus.optional(),
+        mock: evidenceStatus.optional(),
+        "real-integration": evidenceStatus.optional(),
+    }).strict().refine((evidence) => Object.keys(evidence).length > 0, "declare at least one evidence lane"),
+}).strict();
+const concretePath = z.string().min(1).refine((value) => value === value.trim() &&
+    !/^[A-Za-z]:/.test(value) &&
+    !/[\\*?\[\]{}\0]/.test(value) &&
+    value.split("/").every((part) => part !== "" && part !== "." && part !== ".."), "must be a concrete relative POSIX file path without traversal");
+export const frontendRequiredDeliverablesSchema = z.object({
+    items: z.array(z.object({
+        path: concretePath,
+        requirementId: z.string().min(1),
+        sourceFragmentId: z.string().min(1),
+    }).strict()),
+}).strict();
+/** Validate structure and provenance; the Contract model owns the distinction
+ * between delivery obligations, permissions, prohibitions and references. */
+export function validateFrontendRequiredDeliverables(value, requirements) {
+    const declaration = frontendRequiredDeliverablesSchema.parse(value);
+    for (const item of declaration.items) {
+        const requirement = requirements.get(item.requirementId);
+        if (!requirement?.sourceFragmentIds.includes(item.sourceFragmentId)) {
+            throw new Error(`required deliverable ${item.path} has an unknown requirement/fragment binding`);
+        }
+        const text = requirement.sourceFragments?.get(item.sourceFragmentId);
+        const escaped = item.path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        // A sentence-ending period is punctuation; a dot followed by filename
+        // characters is still part of the token (app.ts must not match app.ts.map).
+        const exactPath = new RegExp(`(^|[^\\p{L}\\p{N}_./-])${escaped}(?=$|[^\\p{L}\\p{N}_./-]|\\.(?=$|[^\\p{L}\\p{N}_./-]))`, "u");
+        if (!text || !exactPath.test(text)) {
+            throw new Error(`required deliverable ${item.path} is not an exact path in frozen source fragment ${item.sourceFragmentId}`);
+        }
+    }
+    return declaration;
+}
+/** Read the latest explicit inventory. Never infer obligations from prose. */
+export function extractRequiredDeliverablePaths(facts) {
+    const declaration = facts.map(object).filter((fact) => fact?.origin === "contract" && fact.kind === "required-deliverables").at(-1);
+    if (!declaration)
+        return [];
+    const { items } = frontendRequiredDeliverablesSchema.parse({ items: declaration.items });
+    return [...new Set(items.map((item) => item.path))].sort();
+}
+/** Apply state-flow replacement/removal semantics exactly as the plan compiler does. */
+export function collectCanonicalStateFlowNames(committedFacts, includeRegistry = false) {
+    const uiStateNames = new Set();
+    const interactionNames = new Set();
+    for (const value of committedFacts) {
+        const record = object(value);
+        if (!record || (record.phase !== undefined && record.phase !== "committed"))
+            continue;
+        const fact = object(record.fact) ?? record;
+        if (fact.origin !== "plan")
+            continue;
+        if (includeRegistry && fact.kind === "state-registry") {
+            uiStateNames.clear();
+            interactionNames.clear();
+            for (const name of names(fact.uiStateNames))
+                uiStateNames.add(name);
+            for (const name of names(fact.interactionNames))
+                interactionNames.add(name);
+        }
+        if (fact.kind !== "state-flow")
+            continue;
+        for (const name of names(fact.removeUiStateNames)) {
+            uiStateNames.delete(name);
+        }
+        for (const name of names(fact.removeInteractionNames)) {
+            interactionNames.delete(name);
+        }
+        for (const state of Array.isArray(fact.uiStates) ? fact.uiStates : []) {
+            if (!state || typeof state !== "object" || Array.isArray(state))
+                continue;
+            const name = state.name;
+            if (typeof name === "string" && name.trim())
+                uiStateNames.add(name);
+        }
+        for (const interaction of Array.isArray(fact.interactions)
+            ? fact.interactions
+            : []) {
+            if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) {
+                continue;
+            }
+            const name = interaction.name;
+            if (typeof name === "string" && name.trim())
+                interactionNames.add(name);
+        }
+    }
+    return { uiStateNames, interactionNames };
+}