@tea-agent/loop-agent 0.43.0-next.1 → 0.43.0-next.10

package/dist/workflows/dag/frontend-input-projection.js

@@ -0,0 +1,76 @@
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+/** An execution packing target, not a claim about any model's context limit. */
+export const FRONTEND_SCOPE_TARGET_BYTES = 24_000;
+export function packFrontendInputUnits(units, options = {}) {
+    const target = options.targetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
+    const maxUnits = options.maxUnits ?? 4;
+    if (!Number.isFinite(target) || target <= 0 || !Number.isInteger(maxUnits) || maxUnits < 1)
+        throw Error("FRONTEND_INPUT_POLICY_INVALID");
+    const batches = [];
+    let batch = [];
+    let bytes = 2;
+    let cost = 0;
+    const ids = new Set();
+    for (const unit of units) {
+        if (!unit.id || ids.has(unit.id))
+            throw Error(`FRONTEND_INPUT_ID_CONFLICT: ${unit.id}`);
+        ids.add(unit.id);
+        const size = Buffer.byteLength(JSON.stringify(unit), "utf8") + 1;
+        if (options.maxUnitBytes !== undefined && size > options.maxUnitBytes)
+            throw Error(`FRONTEND_INPUT_UNIT_TOO_LARGE: ${unit.id} requires ${size} bytes; split the source obligation without dropping conditions`);
+        const unitCost = options.cost?.(unit) ?? 1;
+        if (batch.length && (batch.length >= maxUnits || bytes + size > target || cost + unitCost > (options.maxCost ?? Infinity))) {
+            batches.push(batch);
+            batch = [];
+            bytes = 2;
+            cost = 0;
+        }
+        batch.push(unit);
+        bytes += size;
+        cost += unitCost;
+    }
+    if (batch.length)
+        batches.push(batch);
+    return batches;
+}
+/** Select whole obligations before serialization; never clip identities or text. */
+export function projectFrontendInputScope(payload, scopeIds) {
+    const byId = new Map(payload.requirements.map(r => [r.id, r]));
+    const requirements = [...new Set(scopeIds)].map(id => {
+        const unit = byId.get(id);
+        if (!unit)
+            throw Error(`FRONTEND_INPUT_SCOPE_MISSING: ${id}`);
+        return unit;
+    });
+    const fragments = new Set(requirements.flatMap(r => Array.isArray(r.sourceFragmentIds) ? r.sourceFragmentIds : []));
+    const inScope = (fact) => {
+        const ids = typeof fact.requirementId === "string" ? [fact.requirementId] : Array.isArray(fact.requirementIds) ? fact.requirementIds : [];
+        return !ids.length || ids.some(id => scopeIds.includes(String(id)));
+    };
+    return {
+        ...payload, requirements,
+        ...(Array.isArray(payload.sharedFacts) ? { sharedFacts: payload.sharedFacts.filter(f => f && typeof f === "object" && inScope(f)).map(f => f.kind === "required-deliverables" && Array.isArray(f.items) ? { ...f, items: f.items.filter((item) => inScope(item)) } : f) } : {}),
+        ...(Array.isArray(payload.fragments) ? { fragments: payload.fragments.filter(f => f && typeof f === "object" && fragments.has(f.id)) } : {}),
+        inputManifest: { schemaVersion: 1, semantics: "full", sourceSha256: sha256OfCanonicalJson(payload), scopeIds: requirements.map(r => r.id), excludedIds: payload.requirements.filter(r => !scopeIds.includes(r.id)).map(r => r.id) },
+    };
+}
+export function parseFrontendInputBlock(prompt, phase) {
+    const block = new RegExp(`<frontend_${phase}_input>[\\s\\S]*?<\\/frontend_${phase}_input>`).exec(prompt)?.[0];
+    if (!block)
+        return undefined;
+    for (const line of block.split(/\r?\n/)) {
+        try {
+            const payload = JSON.parse(line);
+            if (Array.isArray(payload.requirements))
+                return { block, payload };
+        }
+        catch { /* wrapper prose is not JSON */ }
+    }
+    throw Error(`FRONTEND_INPUT_INVALID: ${phase} compiled inventory is not parseable`);
+}
+export function projectFrontendContractPrompt(prompt, scopeIds) {
+    const input = parseFrontendInputBlock(prompt, "contract");
+    if (!input)
+        throw Error("FRONTEND_INPUT_MISSING: contract compiled inventory unavailable");
+    return prompt.replace(input.block, ["<frontend_contract_input>", "Complete canonical obligations for this session only. Confirm each id with record_requirement; preserve all independent conditions.", JSON.stringify(projectFrontendInputScope(input.payload, scopeIds)), "</frontend_contract_input>"].join("\n"));
+}

package/dist/workflows/dag/frontend-plan-completeness.js

@@ -0,0 +1,186 @@
+import { collectCanonicalStateFlowNames } from "./frontend-contract-facts.js";
+export function committedFactFromPlanRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.phase !== undefined && record.phase !== "committed")
+        return undefined;
+    const fact = record.fact;
+    return fact && typeof fact === "object" && !Array.isArray(fact)
+        ? fact
+        : typeof record.kind === "string"
+            ? record
+            : undefined;
+}
+export function planFactStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+export function planFactScopeIntersects(fact, requirementIds) {
+    return planFactStringList(fact.scopeRequirementIds).some((id) => requirementIds.has(id));
+}
+/** Compute the authoritative coverage queue from the committed plan ledger. */
+export function collectFrontendPlanMissingFacts(input) {
+    const requirements = new Map();
+    const standaloneEvidenceGaps = new Set();
+    const verificationTargetIds = new Set();
+    const verificationTargetRequirements = new Map();
+    for (const value of input.committedFacts) {
+        const fact = committedFactFromPlanRecord(value);
+        if (!fact || fact.origin !== "plan")
+            continue;
+        if (fact.kind === "plan-requirement" && fact.entry && typeof fact.entry === "object") {
+            const entry = fact.entry;
+            if (typeof entry.id === "string" && entry.id.trim())
+                requirements.set(entry.id, entry);
+        }
+        if (fact.kind === "plan-verification-target" && fact.entry && typeof fact.entry === "object") {
+            const entry = fact.entry;
+            const id = entry.id;
+            if (typeof id === "string" && id.trim()) {
+                verificationTargetIds.add(id);
+                verificationTargetRequirements.set(id, new Set(Array.isArray(entry.requirementIds)
+                    ? entry.requirementIds.filter((value) => typeof value === "string")
+                    : []));
+            }
+        }
+        if (fact.kind === "plan-evidence-gap" && fact.entry && typeof fact.entry === "object") {
+            const entry = fact.entry;
+            const requirementId = entry.requirementId;
+            const description = entry.description;
+            if (typeof requirementId === "string" && requirementId.trim() && typeof description === "string" && description.trim()) {
+                standaloneEvidenceGaps.add(requirementId);
+            }
+        }
+    }
+    const missing = [];
+    for (const id of input.requirementIds) {
+        const entry = requirements.get(id);
+        if (!entry) {
+            missing.push({
+                kind: "plan-requirement",
+                id,
+                requirementIds: [id],
+                reason: `requirement ${id} has no committed plan-requirement fact`,
+            });
+            continue;
+        }
+        const targetIds = Array.isArray(entry.verificationTargetIds)
+            ? entry.verificationTargetIds.filter((value) => typeof value === "string" && value.trim().length > 0)
+            : [];
+        const gap = entry.evidenceGap && typeof entry.evidenceGap === "object"
+            ? entry.evidenceGap
+            : undefined;
+        const hasEvidenceGap = (typeof gap?.description === "string" && gap.description.trim().length > 0) ||
+            standaloneEvidenceGaps.has(id);
+        if (targetIds.length === 0 && !hasEvidenceGap) {
+            missing.push({
+                kind: "plan-verification-target",
+                requirementIds: [id],
+                reason: `requirement ${id} declares neither a verification target nor a non-empty evidenceGap`,
+            });
+            continue;
+        }
+        for (const targetId of targetIds) {
+            if (!verificationTargetIds.has(targetId) ||
+                !verificationTargetRequirements.get(targetId)?.has(id)) {
+                missing.push({
+                    kind: "plan-verification-target",
+                    id: targetId,
+                    requirementIds: [id],
+                    reason: `requirement ${id} references verification target ${targetId}, but that target is not committed`,
+                });
+            }
+        }
+    }
+    return missing;
+}
+/** Completeness checks for phases whose facts are committed incrementally. */
+export function collectFrontendPlanPhaseMissingFacts(input) {
+    const facts = input.committedFacts
+        .map(committedFactFromPlanRecord)
+        .filter((fact) => Boolean(fact && fact.origin === "plan"));
+    if (input.phase === "ux-registry") {
+        return facts.some((fact) => fact.kind === "state-registry")
+            ? []
+            : [
+                {
+                    kind: "state-registry",
+                    requirementIds: [...input.requirementIds],
+                    reason: "global UX vocabulary phase has no committed state-registry fact",
+                },
+            ];
+    }
+    if (input.phase === "ux-local") {
+        // One snapshot per check: no cross-revision cache to invalidate.
+        const required = new Set(input.behaviorRequiredRequirementIds ?? []);
+        const requested = new Set(input.requirementIds.filter(id => required.has(id)));
+        if (!requested.size)
+            return [];
+        const byRequirement = new Map();
+        for (const fact of facts) {
+            for (const id of new Set(planFactStringList(fact.scopeRequirementIds))) {
+                if (!requested.has(id))
+                    continue;
+                const entries = byRequirement.get(id) ?? [];
+                entries.push(fact);
+                byRequirement.set(id, entries);
+            }
+        }
+        const liveStateFlow = collectCanonicalStateFlowNames(facts);
+        const missing = [];
+        for (const id of input.requirementIds) {
+            if (!required.has(id))
+                continue;
+            const scopedFacts = byRequirement.get(id) ?? [];
+            const hasChoice = scopedFacts.some((fact) => fact.kind === "component-choice" &&
+                Array.isArray(fact.uiComponentChoices) &&
+                fact.uiComponentChoices.length > 0);
+            const canonicalStateFlow = collectCanonicalStateFlowNames(scopedFacts);
+            const hasStateFlow = [...canonicalStateFlow.uiStateNames].some(name => liveStateFlow.uiStateNames.has(name)) ||
+                [...canonicalStateFlow.interactionNames].some(name => liveStateFlow.interactionNames.has(name));
+            if (!hasChoice) {
+                missing.push({
+                    kind: "component-choice",
+                    requirementIds: [id],
+                    reason: "behaviour-required UX slice has no committed component-choice fact",
+                });
+            }
+            if (!hasStateFlow) {
+                missing.push({
+                    kind: "state-flow",
+                    requirementIds: [id],
+                    reason: "behaviour-required UX slice has no committed state-flow fact",
+                });
+            }
+        }
+        return missing;
+    }
+    const hasMockApi = facts.some((fact) => fact.kind === "mock-api");
+    const allInteractions = collectCanonicalStateFlowNames(facts).interactionNames;
+    const requested = new Set(input.requirementIds);
+    const liveInteractions = new Set([...collectCanonicalStateFlowNames(facts.filter(f => !planFactStringList(f.scopeRequirementIds).length || planFactScopeIntersects(f, requested))).interactionNames].filter(name => allInteractions.has(name)));
+    const coveredInteractions = new Set(facts
+        .filter((fact) => fact.kind === "data-flow")
+        .flatMap((fact) => planFactStringList(fact.interactions)));
+    const missing = [];
+    if (!hasMockApi) {
+        missing.push({
+            kind: "mock-api",
+            requirementIds: [...input.requirementIds],
+            reason: "global Mock/data phase has no committed mock-api fact",
+        });
+    }
+    for (const interaction of liveInteractions) {
+        if (coveredInteractions.has(interaction))
+            continue;
+        missing.push({
+            kind: "data-flow",
+            id: interaction,
+            requirementIds: [...input.requirementIds],
+            reason: `interaction ${interaction} has no committed data-flow fact`,
+        });
+    }
+    return missing;
+}

package/dist/workflows/dag/frontend-plan-recovery-policy.js

@@ -0,0 +1,18 @@
+/** Precise failures own their recovery. A stale transport length marker must
+ * never turn cancellation, provider rejection or policy failure into progress. */
+export function classifyFrontendPlanRecovery(result) {
+    const category = result.failureCategory ?? "";
+    if (result.timedOut || result.stopReason === "aborted" ||
+        /interrupt|termination-unconfirmed|budget_breach/.test(category) ||
+        ["cancelled", "auth", "missing-api-key", "rate-limit", "quota", "timeout", "tool-policy", "write-guard", "path-violation", "governance-blocked", "human-rejected"].includes(category))
+        return "stop";
+    if (result.ok)
+        return "none";
+    if (category === "output-limit")
+        return "output";
+    if (["context-overflow", "context-budget-exhausted"].includes(category))
+        return "context";
+    if (result.stopReason === "length" && ["", "empty-output", "network", "nonzero-exit", "unknown"].includes(category))
+        return "output";
+    return "none";
+}

package/dist/workflows/dag/frontend-plan-render.js

@@ -1,3 +1,4 @@
+import { collectFrontendExecutionGroups } from "./frontend-execution-groups.js";
 /**
  * Deterministic Markdown renderer for a canonical frontend implementation
  * contract. The prewrite gate materializes this as `contracts/frontend-plan.md`
@@ -17,13 +18,19 @@ function bulletList(items) {
  * prose — the renderer must never present it as requirement content. */
 const IMPLIED_OUTCOME_PREFIX = "implied by contract:";
 function requirementsCoverage(contract) {
-    const lines = contract.requirements.map((requirement) => {
+    const renderRequirement = (requirement, includeOutcome = true) => {
         const targets = requirement.implementationTargets.join(", ");
         const verificationTargets = requirement.verificationTargetIds.join(", ");
-        const authoredOutcome = requirement.expectedOutcome.startsWith(IMPLIED_OUTCOME_PREFIX)
+        const authoredOutcome = !includeOutcome || requirement.expectedOutcome.startsWith(IMPLIED_OUTCOME_PREFIX)
             ? ""
             : ` — ${requirement.expectedOutcome}`;
         return `- ${requirement.id} → ${targets || "(no targets)"} [${verificationTargets || "no VT"}]${authoredOutcome}`;
+    };
+    const lines = collectFrontendExecutionGroups(contract.requirements).flatMap(group => {
+        const members = contract.requirements.filter(r => group.requirementIds.includes(r.id));
+        if (group.kind === "unclassified")
+            return members.map(r => renderRequirement(r));
+        return [`### ${group.id} (${group.kind})`, group.summary, ...members.map(r => renderRequirement(r, false)), "Full independent acceptance conditions remain in contracts/frontend-implementation-contract.json."];
     });
     return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
 }
@@ -72,7 +79,7 @@ function sourceFidelityLedger(contract) {
         `- ledger: ${binding.ledgerPath}`,
         `- ledgerSha256: ${binding.ledgerSha256 ?? "(missing)"}`,
         `- inputDigest: ${binding.inputDigest ?? "(missing)"}`,
-        "- 语义权威：原始 requirement/acceptance 文档与 requirement-ledger.json；本计划只消费派生摘要与 bound ledger 指针，长原文不内联。",
+        "- 语义权威：原始 requirement/acceptance 文档与 requirement-ledger.json；本计划按执行组展示共享方案；独立验收全文保留在 canonical contract，执行输入按完整义务分批。",
     ];
     const boundCount = Object.keys(binding.requirementToFragments ?? {}).length;
     if (boundCount > 0) {

package/dist/workflows/dag/frontend-recovery-controller.js

@@ -96,13 +96,13 @@ export async function runRecoveryOperationController(input) {
             };
         }
         // Total budget fold + hard stop (resource protection, fail-closed).
-        const ledgers = await readLedgers();
-        if (deps.budget) {
-            budgetAggregate = foldOperationBudgets({
-                ledgers,
-                budget: deps.budget,
-                now,
-            });
+        try {
+            const ledgers = await readLedgers();
+            if (deps.budget)
+                budgetAggregate = foldOperationBudgets({ ledgers, budget: deps.budget, now });
+        }
+        catch (error) {
+            return { terminalReason: "needs-attention", attempts: attempt, budgetAggregate, fingerprints, detail: `Recovery budget evidence unavailable: ${error instanceof Error ? error.message : String(error)}` };
         }
         if (budgetAggregate?.status === "breached") {
             return {

package/dist/workflows/dag/frontend-recovery-lineage.js

@@ -87,6 +87,7 @@ export function foldOperationBudgets(input) {
         limits: { ...input.budget.limits },
         consumed: {
             executorCalls: 0,
+            ...(input.budget.limits.maxProviderRequests !== undefined ? { providerRequests: 0 } : {}),
             wallTimeMs: 0,
             tokens: null,
             repairPasses: 0,
@@ -100,6 +101,15 @@ export function foldOperationBudgets(input) {
     let knownTokenSum = 0;
     const missing = new Set();
     for (const ledger of input.ledgers) {
+        if (input.budget.limits.maxProviderRequests !== undefined) {
+            if (ledger.consumed.providerRequests === undefined) {
+                if (input.budget.mode === "hard")
+                    throw Error("FRONTEND_PROVIDER_BUDGET_INVALID: missing operation request consumption");
+                delete aggregate.consumed.providerRequests;
+            }
+            else if (aggregate.consumed.providerRequests !== undefined)
+                aggregate.consumed.providerRequests += ledger.consumed.providerRequests;
+        }
         aggregate.consumed.executorCalls += ledger.consumed.executorCalls;
         aggregate.consumed.wallTimeMs += ledger.consumed.wallTimeMs;
         aggregate.consumed.repairPasses += ledger.consumed.repairPasses;
@@ -119,6 +129,9 @@ export function foldOperationBudgets(input) {
     aggregate.consumed.missingTokenNodeIds = [...missing].sort((a, b) => a.localeCompare(b));
     if (aggregate.mode === "hard") {
         const limits = aggregate.limits;
+        pushAggregateBreach(aggregate, "providerRequests", aggregate.consumed.providerRequests ?? 0, limits.maxProviderRequests, now);
+        if (aggregate.breaches.length)
+            aggregate.status = "breached";
         pushAggregateBreach(aggregate, "executorCalls", aggregate.consumed.executorCalls, limits.maxExecutorCalls, now);
         pushAggregateBreach(aggregate, "wallTimeMs", aggregate.consumed.wallTimeMs, limits.maxWallTimeMs, now);
         pushAggregateBreach(aggregate, "repairPasses", aggregate.consumed.repairPasses, limits.maxRepairPasses, now);

package/dist/workflows/dag/frontend-recovery-run.js

@@ -1,5 +1,6 @@
 import { copyFile, mkdir, readdir, readFile, rm, access } from "node:fs/promises";
 import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { sha256Hex } from "./frontend-implementation-contract.js";
 import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, FRONTEND_RECOVERY_STAGING_PREFIX, computeFrontendRecoveryPlan, computeFrontendRecoveryPlanForSource, } from "./frontend-recovery-plan.js";
@@ -413,6 +414,8 @@ async function materializeChildStaging(input) {
         }
     }
     const childState = {
+        ...(parentState.budget ? { budget: structuredClone(parentState.budget) } : {}),
+        ...(parentState.budgetLedger ? { budgetLedger: structuredClone(parentState.budgetLedger) } : {}),
         version: 1,
         title: parentSpec.title,
         runId: childRunId,
@@ -434,6 +437,7 @@ async function materializeChildStaging(input) {
             }
             : {}),
         frontendRecoveryState: {
+            ...(parentState.budgetLedger ? { budgetLineage: { parentLedgerSha256: sha256OfCanonicalJson(parentState.budgetLedger), inheritedAt: createdAt, inheritedConsumed: structuredClone(parentState.budgetLedger.consumed) } } : {}),
             schemaVersion: 1,
             phase: "child-running",
             requestId,

package/dist/workflows/dag/frontend-review-scopes.js

@@ -0,0 +1,139 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, realpath, lstat } from "node:fs/promises";
+import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { readCommittedEvents } from "./frontend-typed-event-store.js";
+import { stageTypedEventFact, adoptTypedEventFact } from "./frontend-typed-event-transaction.js";
+const invalidScope = (message) => Object.assign(new Error(`FRONTEND_REVIEW_SCOPE_INVALID: ${message}`), { code: "FRONTEND_REVIEW_SCOPE_INVALID" });
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isArtifactReference = (value) => isRecord(value)
+    && typeof value.path === "string" && value.path.length > 0
+    && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256);
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+/** The section index is navigation; reconstruct coverage against the canonical source before using it. */
+export async function loadFrontendReviewScopes(runDir, phase, targetBytes) {
+    const root = await realpath(runDir);
+    const files = new Map();
+    async function read(relative, expected) {
+        const absolute = path.resolve(root, relative);
+        if (!absolute.startsWith(root + path.sep) || (await lstat(absolute)).isSymbolicLink() || !(await realpath(absolute)).startsWith(root + path.sep))
+            throw invalidScope("artifact escaped run");
+        const text = await readFile(absolute, "utf8");
+        const sha256 = hash(text);
+        if (expected && sha256 !== expected)
+            throw Error(`FRONTEND_REVIEW_SCOPE_DRIFT: ${relative}`);
+        files.set(relative, sha256);
+        return { id: relative, text, sha256 };
+    }
+    let indexArtifact;
+    try {
+        indexArtifact = await read("contracts/frontend-implementation-contract.index.json");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const index = JSON.parse(indexArtifact.text);
+    if (!isRecord(index) || !isArtifactReference(index.contract) || !Array.isArray(index.sections))
+        throw invalidScope("malformed contract index");
+    const canonicalArtifact = await read(index.contract.path, index.contract.sha256);
+    const canonical = JSON.parse(canonicalArtifact.text);
+    if (!isRecord(canonical))
+        throw invalidScope("canonical contract must be an object");
+    const covered = new Map();
+    const sections = [];
+    const ids = new Set();
+    for (const entry of index.sections) {
+        if (!isRecord(entry) || !isArtifactReference(entry) || !Array.isArray(entry.slices))
+            throw invalidScope("malformed section index entry");
+        if (ids.has(entry.path))
+            throw invalidScope("duplicate section identity");
+        ids.add(entry.path);
+        const section = await read(entry.path, entry.sha256);
+        const payload = JSON.parse(section.text);
+        if (!isRecord(payload) || !Array.isArray(payload.slices) || !isRecord(payload.data))
+            throw invalidScope(`malformed section: ${entry.path}`);
+        if (payload.contractSha256 !== canonicalArtifact.sha256 || sha256OfCanonicalJson(payload.slices) !== sha256OfCanonicalJson(entry.slices))
+            throw invalidScope("unbound section");
+        for (const slice of payload.slices) {
+            if (!isRecord(slice) || typeof slice.field !== "string" || !Object.hasOwn(canonical, slice.field) || !Object.hasOwn(payload.data, slice.field))
+                throw invalidScope(`missing or invalid field reference in ${entry.path}: ${String(slice?.field)}`);
+            const value = canonical[slice.field];
+            const positions = covered.get(slice.field) ?? new Set();
+            if (Array.isArray(value)) {
+                if (!Number.isInteger(slice.start) || !Number.isInteger(slice.end) || slice.start < 0 || slice.end < slice.start || slice.end > value.length || slice.total !== value.length)
+                    throw invalidScope("invalid array coverage");
+                if ((value.length === 0 && covered.has(slice.field)) || (value.length > 0 && slice.start === slice.end))
+                    throw invalidScope(`empty or duplicate array coverage: ${slice.field}`);
+                for (let i = slice.start; i < slice.end; i++) {
+                    if (positions.has(i))
+                        throw invalidScope("overlapping coverage");
+                    positions.add(i);
+                }
+            }
+            else {
+                if (["start", "end", "total"].some(key => Object.hasOwn(slice, key)))
+                    throw invalidScope(`scalar field has array range: ${slice.field}`);
+                if (positions.size)
+                    throw invalidScope("duplicate field");
+                positions.add(0);
+            }
+            const range = Array.isArray(value) ? value.slice(slice.start, slice.end) : value;
+            if (sha256OfCanonicalJson(range) !== sha256OfCanonicalJson(payload.data[slice.field]))
+                throw invalidScope(`section differs from canonical obligation: ${slice.field}`);
+            covered.set(slice.field, positions);
+        }
+        const sectionFields = new Set(payload.slices.map(slice => slice.field));
+        if (Object.keys(payload.data).some(field => !sectionFields.has(field)))
+            throw invalidScope(`unindexed section data: ${entry.path}`);
+        sections.push(section);
+    }
+    if (Object.keys(canonical).some(field => !covered.has(field) || covered.get(field).size !== (Array.isArray(canonical[field]) ? canonical[field].length : 1)))
+        throw invalidScope("canonical field coverage incomplete");
+    const scopes = Buffer.byteLength(canonicalArtifact.text) <= targetBytes ? [canonicalArtifact] : sections;
+    if (phase === "review") {
+        const context = await read("contracts/frontend-review-context.json");
+        const payload = JSON.parse(context.text);
+        if (payload.contractRef.sha256 !== canonicalArtifact.sha256 || payload.contractRef.indexSha256 !== indexArtifact.sha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review context contract binding");
+        const diff = await read(payload.diff.reviewIndexPath);
+        const diffIndex = JSON.parse(diff.text);
+        await read(payload.diff.patchPath, payload.diff.patchSha256);
+        if (diffIndex.patchSha256 !== payload.diff.patchSha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review diff binding");
+        scopes.push(context);
+        for (const hunk of diffIndex.hunks)
+            scopes.push(await read(hunk.patchPath, hunk.sha256));
+    }
+    return { scopes, digest: sha256OfCanonicalJson([...files]), validate: async () => { for (const [relative, expected] of files)
+            await read(relative, expected); } };
+}
+/** Checkpoints attest explicit model completion of already supplied, hash-bound scopes. */
+export function createFrontendReviewScopeProtocol(input) {
+    const kind = input.phase === "design" ? "design-scope-completed" : "review-scope-completed";
+    let active = new Set();
+    const completedScopeIds = () => new Set(readCommittedEvents(input.getStore(), input.attemptId).filter(r => r.fact.kind === kind).map(r => String(r.fact.id)));
+    const receipt = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
+    return {
+        setActiveScope(ids) { active = new Set(ids); },
+        completedScopeIds,
+        committedFacts: () => readCommittedEvents(input.getStore(), input.attemptId),
+        assertComplete() { const missing = input.inventory?.scopes.filter(s => !completedScopeIds().has(s.id)) ?? []; if (missing.length)
+            throw Object.assign(Error(`FRONTEND_REVIEW_SCOPE_INCOMPLETE: ${missing.map(s => s.id).join(", ")}`), { code: "FRONTEND_REVIEW_SCOPE_INCOMPLETE" }); },
+        customTools: !input.inventory ? [] : [{ name: "complete_review_scope", label: "complete_review_scope", description: "After reviewing the supplied complete scope and saving its findings, checkpoint its exact runtime id. This does not approve the implementation or design.", parameters: { type: "object", properties: { id: { type: "string", minLength: 1 } }, required: ["id"], additionalProperties: false },
+                async execute(callId, params) {
+                    const scope = input.inventory.scopes.find(s => s.id === params.id);
+                    if (!scope || !active.has(params.id))
+                        return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "Only the supplied active review scope may be completed" });
+                    await input.inventory.validate();
+                    const store = input.getStore();
+                    const requestId = `${input.attemptId}:${callId}:${randomUUID()}`;
+                    const fact = { kind, id: scope.id, sha256: scope.sha256 };
+                    const staged = stageTypedEventFact({ store, requestId, attemptId: input.attemptId, fact });
+                    const committed = await adoptTypedEventFact({ store, requestId, attemptId: input.attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
+                    return receipt({ ok: true, kind, revision: committed.revision });
+                },
+            }],
+    };
+}