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

package/dist/application/evaluation/budget.js

@@ -208,3 +208,24 @@ export function formatBudgetReportMarkdown(ledger) {
     }
     return `${lines.join("\n")}\n`;
 }
+export const frontendObservedSessionIdentitySchema = z.object({
+    sourceExecutionId: z.string().uuid().optional(),
+    sessionId: z.string().min(1), phase: z.string().min(1), executionKind: z.enum(["model", "runtime"]), dispatchReason: z.enum(["initial", "correction"]),
+    scopeIds: z.array(z.string()), taskId: z.string().nullable(), runId: z.string().nullable(), nodeId: z.string().nullable(), attempt: z.number().int().nullable(),
+    sourceDigest: z.string().nullable(), contractDigest: z.string().nullable(),
+}).strict();
+/** Durable task request authority and the source-bound snapshot carried by a DAG. */
+export const sourceProviderBudgetSchema = z.object({
+    schemaVersion: z.literal(1), taskId: z.string().min(1), budgetId: z.string().uuid(),
+    maxProviderRequests: z.number().int().positive(), reservedRequests: z.number().int().nonnegative(),
+    requestSessions: z.record(z.object({ identity: frontendObservedSessionIdentitySchema, reservedRequests: z.number().int().positive() }).strict()).optional(),
+}).strict().refine(value => value.reservedRequests <= value.maxProviderRequests && Object.entries(value.requestSessions ?? {}).every(([key, session]) => key === `${session.identity.runId ?? "task"}:${session.identity.sessionId}` && session.identity.executionKind === "model" && session.identity.taskId === value.taskId) && Object.values(value.requestSessions ?? {}).reduce((sum, session) => sum + session.reservedRequests, 0) <= value.reservedRequests);
+export const sourceProviderBudgetBindingSchema = z.object({
+    ledger: sourceProviderBudgetSchema,
+    contract: z.object({ revision: z.number().int().nonnegative(), canonicalHash: z.string().regex(/^[a-f0-9]{64}$/) }).strict().optional(),
+    sourceBindingSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    evidence: z.object({ executions: z.array(z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/), content: z.string() }).strict()).optional(), receipts: z.array(z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/), content: z.string() }).strict()), diagnostics: z.array(z.string()) }).strict().optional(),
+}).strict();
+export function sourceBudgetContractIdentity(binding) {
+    return binding ? { revision: binding.revision, canonicalHash: binding.canonicalHash } : undefined;
+}

package/dist/application/evaluation/corpus-hash.js

@@ -9,24 +9,19 @@ function normalizeTask(task) {
         featureId: task.featureId ?? null,
     };
 }
-/**
- * Canonical payload for corpusHash.
- * Excludes corpusId, createdAt, description, corpusHash, and free-text notes.
- */
+/** Excludes display metadata, but binds every frontend input and oracle ref. */
 export function buildCanonicalCorpusPayload(manifest) {
-    const tasks = manifest.tasks
-        .map((task) => normalizeTask(task))
-        .sort((a, b) => (a.taskRef < b.taskRef ? -1 : a.taskRef > b.taskRef ? 1 : 0));
-    return {
-        schemaVersion: 1,
-        tasks,
-    };
+    const files = (refs) => refs.map(ref => ({ path: ref.path, sha256: ref.sha256 })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const tasks = (manifest.schemaVersion === 2
+        ? manifest.tasks.map(task => ({ ...normalizeTask(task), category: task.category,
+            requirements: files(task.requirements), initialFiles: files(task.initialFiles), oracleFiles: files(task.oracleFiles) }))
+        : manifest.tasks.map(normalizeTask))
+        .sort((a, b) => a.taskRef < b.taskRef ? -1 : a.taskRef > b.taskRef ? 1 : 0);
+    return { schemaVersion: manifest.schemaVersion,
+        ...(manifest.schemaVersion === 2 ? { purpose: manifest.purpose } : {}), tasks };
 }
 export function computeCorpusHash(manifest) {
-    const payload = buildCanonicalCorpusPayload(manifest);
-    const digest = createHash("sha256")
-        .update(stableStringify(payload))
-        .digest("hex");
+    const digest = createHash("sha256").update(stableStringify(buildCanonicalCorpusPayload(manifest))).digest("hex");
     return formatContentSha(digest);
 }
 export function assertCorpusHashMatches(manifest) {

package/dist/application/evaluation/corpus.js

@@ -1,7 +1,8 @@
-import { loadCorpusManifestFromPath, listCorpusIds, materializeCorpusManifest, readCorpusManifest, registerCorpusManifest, summarizeCorpus, } from "../../infrastructure/evaluation/corpus-store.js";
+import { loadCorpusManifestFromPath, assertCorpusArtifacts, listCorpusIds, materializeCorpusManifest, readCorpusManifest, registerCorpusManifest, summarizeCorpus, } from "../../infrastructure/evaluation/corpus-store.js";
 export async function validateCorpus(input) {
     const raw = await loadCorpusManifestFromPath(input.repoRoot, input.manifestPath);
     const manifest = await materializeCorpusManifest(raw);
+    await assertCorpusArtifacts(input.repoRoot, manifest);
     return { manifest, summary: summarizeCorpus(manifest) };
 }
 export async function registerCorpus(input) {

package/dist/application/evaluation/frontend-browser-acceptance.js

@@ -0,0 +1,77 @@
+import { realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { z } from "zod";
+import { readFileBoundarySafe } from "../../shared/path-safety.js";
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const refSchema = z.object({ path: z.string().min(1), sha256: digest }).strict();
+const files = ["index.html", "src/app.js", "test/counter.test.js", "acceptance-prd.md"];
+const requiredChecks = ["initial", "idle", "limit", "reset", "loading", "empty", "real-integration"];
+const additionalChecks = ["noPageErrors", "preservesQuery", "loadedState", "disabledWhileLoading", "replacesOldItems", "errorState", "errorClearsOldItems"];
+const checksSchema = (keys) => z.object(Object.fromEntries(keys.map(key => [key, z.boolean()]))).strict();
+/** Adapter only for the frozen counter corpus and independent browser script. */
+export async function readFrontendBrowserAcceptance(input) {
+    const observed = [];
+    const read = async (root, name, expected) => {
+        const target = path.resolve(root, name);
+        const bytes = await readFileBoundarySafe({ boundaryRoot: root, targetPath: target, label: "frontend browser acceptance" });
+        if (expected && sha(bytes) !== expected)
+            throw Error(`browser evidence hash mismatch: ${name}`);
+        observed.push({ root, target, bytes });
+        return bytes;
+    };
+    const readRef = (value) => { const ref = refSchema.parse(value); return read(input.repoRoot, ref.path, ref.sha256); };
+    const contract = z.object({ schemaVersion: z.literal(1), kind: z.literal("counter-browser-acceptance-v1"), checker: refSchema, oracle: refSchema }).strict().parse(JSON.parse((await readRef(input.contract)).toString("utf8")));
+    await readRef(contract.checker);
+    await readRef(contract.oracle);
+    const raw = JSON.parse((await readRef(input.report)).toString("utf8"));
+    const header = z.object({ schemaVersion: z.literal(1), evidenceKind: z.literal("actual-task-artifact-browser"), runId: z.string().min(1), runStatus: z.enum(["finished", "failed", "partial_failed"]), stateSha256: digest, checkpointSha256: digest, checkerSha256: digest, frozenOracleSha256: digest,
+        sourceHashes: z.object(Object.fromEntries(files.map(file => [file, digest]))).strict(), pass: z.boolean() }).passthrough().parse(raw);
+    if (header.checkerSha256 !== contract.checker.sha256 || header.frozenOracleSha256 !== contract.oracle.sha256)
+        throw Error("browser checker not registered");
+    const state = JSON.parse((await read(input.runDir, "state.json", header.stateSha256)).toString("utf8"));
+    if (typeof state.cwd !== "string" || await realpath(state.cwd) !== await realpath(input.repoRoot))
+        throw Error("browser workspace mismatch");
+    if (state.runId !== header.runId || state.status !== header.runStatus || !state.finishedAt)
+        throw Error("browser run identity mismatch");
+    const checkpoint = z.object({ gitHeadSha: z.string().regex(/^[a-f0-9]{40,64}$/), changedPaths: z.array(z.object({ path: z.string(), contentSha256: digest.optional() }).passthrough()) }).passthrough().parse(JSON.parse((await read(input.runDir, ".runtime/workspace-checkpoint-terminal.json", header.checkpointSha256)).toString("utf8")));
+    for (const name of files) {
+        const changed = checkpoint.changedPaths.filter(row => row.path === name);
+        if (changed.length > 1)
+            throw Error("ambiguous browser checkpoint path");
+        const expected = changed.length ? changed[0].contentSha256 : sha(execFileSync("git", ["show", `${checkpoint.gitHeadSha}:${name}`], { cwd: input.repoRoot }));
+        if (header.sourceHashes[name] !== expected)
+            throw Error(`browser artifact not bound to terminal checkpoint: ${name}`);
+    }
+    let passed;
+    const diagnostics = ["counter-browser-only-product-gates-pending"];
+    if (typeof raw.error === "string") {
+        if (raw.result !== undefined || raw.additional !== undefined)
+            throw Error("browser execution error conflicts with completed checks");
+        if (header.pass)
+            throw Error("browser error cannot pass");
+        passed = null;
+        diagnostics.push("browser-execution-error");
+    }
+    else {
+        const result = z.object({ checks: checksSchema(requiredChecks), failedChecks: z.array(z.string()) }).passthrough().parse(raw.result);
+        const additional = checksSchema(additionalChecks).parse(raw.additional);
+        const errors = z.array(z.string()).parse(raw.errors);
+        const failed = Object.entries(result.checks).filter(([, value]) => !value).map(([key]) => key).sort();
+        if (JSON.stringify(failed) !== JSON.stringify([...result.failedChecks].sort()))
+            throw Error("browser failed-check list mismatch");
+        passed = failed.length === 0 && Object.values(additional).every(Boolean) && errors.length === 0;
+        if (header.pass !== passed)
+            throw Error("browser summary contradicts checks");
+        if (passed && state.status !== "finished")
+            throw Error("failed run cannot become successful browser delivery");
+    }
+    for (const entry of observed) {
+        const latest = await readFileBoundarySafe({ boundaryRoot: entry.root, targetPath: entry.target, label: "browser evidence recheck" });
+        if (!latest.equals(entry.bytes))
+            throw Error("browser evidence changed during collection");
+    }
+    return { passed, diagnostics, runId: header.runId, reportSha256: input.report.sha256, contractSha256: input.contract.sha256 };
+}

package/dist/application/evaluation/frontend-corpus-browser-acceptance.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { readFileBoundarySafe } from "../../shared/path-safety.js";
+import { dagEvaluationBindingSchema } from "../../workflows/dag/types.js";
+import { verifyControllerIdentityForResume } from "../../workflows/dag/controller-identity.js";
+import { assertFrontendPairExecution } from "./frontend-pair-registration.js";
+import { corpusManifestSchema } from "./types.js";
+import { assertCorpusHashMatches } from "./corpus-hash.js";
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const ref = z.object({ path: z.string().min(1), sha256: digest }).strict();
+const contractSchema = z.object({ schemaVersion: z.literal(1), kind: z.literal("frontend-corpus-browser-acceptance-v1"), corpus: ref, checker: ref, oracle: ref, coverage: ref }).strict();
+const observationSchema = z.object({
+    schemaVersion: z.literal(1), evidenceKind: z.literal("unbound-corpus-browser-observation"), runId: z.null(), caseId: z.string(),
+    browser: z.string().nullable(), pass: z.boolean(), checks: z.record(z.boolean()), failedChecks: z.array(z.string()),
+    pageErrors: z.array(z.string()), resourceErrors: z.array(z.string()), servedFiles: z.record(digest), checkerSha256: digest,
+    infrastructureError: z.string().optional(),
+}).passthrough();
+const reportSchema = z.object({
+    schemaVersion: z.literal(1), evidenceKind: z.literal("actual-corpus-task-browser"), caseId: z.string(), runId: z.string().min(1),
+    runStatus: z.enum(["finished", "failed", "partial_failed"]), taskRef: z.string(), cellId: z.string(), artifactHashes: z.record(digest),
+    stateSha256: digest, runSha256: digest, checkpointSha256: digest, registration: ref, contractSha256: digest, corpusSha256: digest,
+    checkerSha256: digest, oracleSha256: digest, coverageSha256: digest, pass: z.boolean(), allChecksPresent: z.boolean(), observation: observationSchema,
+}).strict();
+const webAsset = (name) => name === "index.html" || ["src/", "data/", "public/", "assets/"].some(prefix => name.startsWith(prefix));
+function safeName(name) {
+    if (!name || name.includes("\\") || name.includes(":") || name.includes("\0") || name.startsWith("/") || name.split("/").some(part => !part || part === "." || part === ".."))
+        throw Error("invalid corpus browser artifact path");
+    return name;
+}
+/** Validates browser facts for a registered run. Success here does not prove
+ * source fidelity, writer boundaries, Node-test quality, or model execution. */
+export async function readFrontendCorpusBrowserAcceptance(input) {
+    const observed = [];
+    const read = async (root, name, expected) => {
+        const bytes = await readFileBoundarySafe({ boundaryRoot: root, targetPath: path.resolve(root, name), label: "corpus browser evidence" });
+        if (expected !== undefined && sha(bytes) !== expected)
+            throw Error(`corpus browser evidence hash mismatch: ${name}`);
+        observed.push({ root, name, bytes });
+        return bytes;
+    };
+    const readRef = (value) => { const parsed = ref.parse(value); return read(input.repoRoot, parsed.path, parsed.sha256); };
+    const report = reportSchema.parse(JSON.parse((await readRef(input.report)).toString("utf8")));
+    const contract = contractSchema.parse(JSON.parse((await readRef(input.contract)).toString("utf8")));
+    if (report.contractSha256 !== input.contract.sha256 || report.corpusSha256 !== contract.corpus.sha256 ||
+        report.checkerSha256 !== contract.checker.sha256 || report.oracleSha256 !== contract.oracle.sha256 ||
+        report.coverageSha256 !== contract.coverage.sha256 || report.observation.checkerSha256 !== contract.oracle.sha256)
+        throw Error("corpus browser checker identity mismatch");
+    await readRef(contract.checker);
+    await readRef(contract.oracle);
+    const corpus = corpusManifestSchema.parse(JSON.parse((await readRef(contract.corpus)).toString("utf8")));
+    if (corpus.schemaVersion !== 2)
+        throw Error("corpus browser requires frontend corpus");
+    assertCorpusHashMatches(corpus);
+    for (const task of corpus.tasks)
+        for (const value of [...task.requirements, ...task.initialFiles, ...task.oracleFiles])
+            await readRef(value);
+    const coverage = z.object({ schemaVersion: z.literal(1), cases: z.record(z.record(z.array(z.string().min(1)).min(1))) }).passthrough()
+        .parse(JSON.parse((await readRef(contract.coverage)).toString("utf8")));
+    const state = JSON.parse((await read(input.runDir, "state.json", report.stateSha256)).toString("utf8"));
+    const spec = JSON.parse((await read(input.runDir, "run.json", report.runSha256)).toString("utf8"));
+    if (state.evidenceKind?.includes("selftest"))
+        throw Error("selftest cannot be corpus run evidence");
+    if (typeof state.cwd !== "string" || await realpath(state.cwd) !== await realpath(input.repoRoot))
+        throw Error("corpus browser workspace mismatch");
+    if (state.runId !== report.runId || state.status !== report.runStatus || !Number.isFinite(Date.parse(state.startedAt)) ||
+        !state.finishedAt || !Number.isFinite(Date.parse(state.finishedAt)) || Date.parse(state.finishedAt) < Date.parse(state.startedAt))
+        throw Error("corpus browser terminal identity mismatch");
+    const binding = dagEvaluationBindingSchema.parse(state.evaluation);
+    if (!binding.frontendPair || JSON.stringify(binding) !== JSON.stringify(spec.evaluation) || binding.taskRef !== report.taskRef ||
+        binding.frontendPair.cellId !== report.cellId || binding.frontendPair.registration.path !== report.registration.path ||
+        binding.frontendPair.registration.sha256 !== report.registration.sha256)
+        throw Error("corpus browser frozen evaluation mismatch");
+    const controller = JSON.parse((await read(input.runDir, "controller-identity.json")).toString("utf8"));
+    if (state.controllerIdentityRef?.path !== "controller-identity.json" || controller.status !== "pinned" || !controller.identity)
+        throw Error("corpus browser controller not pinned");
+    const pinned = await verifyControllerIdentityForResume({ runDir: input.runDir, state, currentIdentity: controller.identity });
+    const registration = await assertFrontendPairExecution({ repoRoot: input.repoRoot, binding, controllerFingerprint: pinned.identity.packageFingerprint.value, startedAt: state.startedAt });
+    if (registration.shared.acceptance !== input.contract.sha256)
+        throw Error("corpus browser acceptance contract not registered");
+    await readRef(report.registration);
+    const tasks = corpus.tasks.filter(task => task.taskRef === binding.taskRef);
+    if (tasks.length !== 1)
+        throw Error("corpus browser task missing");
+    const task = tasks[0];
+    if (task.category !== report.caseId || task.category !== report.observation.caseId || task.split !== binding.split || !task.seeds.includes(binding.seed))
+        throw Error("corpus browser case mismatch");
+    for (const key of ["checker", "oracle", "coverage"])
+        if (!task.oracleFiles.some(value => value.path === contract[key].path && value.sha256 === contract[key].sha256))
+            throw Error("corpus browser checker not owned by task");
+    const caseCoverage = coverage.cases[task.category];
+    if (!caseCoverage || !Object.keys(caseCoverage).length)
+        throw Error("corpus browser coverage missing");
+    const required = new Set([...Object.values(caseCoverage).flat(), "no-page-errors", "bound-resources"]);
+    const observation = report.observation;
+    if (Object.keys(observation.checks).some(name => !required.has(name) && name !== "interaction-completed"))
+        throw Error("unknown corpus browser check");
+    if (observation.checks["interaction-completed"] === true)
+        throw Error("invalid corpus interaction diagnostic");
+    // The producer records infrastructure errors before case interactions. It
+    // cannot relabel completed business checks as an environment-only failure.
+    if (observation.infrastructureError !== undefined && Object.keys(observation.checks).some(name => name !== "bound-resources"))
+        throw Error("corpus browser infrastructure phase contradicts checks");
+    const allPresent = [...required].every(name => Object.hasOwn(observation.checks, name));
+    if (allPresent !== report.allChecksPresent)
+        throw Error("corpus browser check coverage mismatch");
+    const failed = Object.entries(observation.checks).filter(([, passed]) => !passed).map(([name]) => name).sort();
+    if (JSON.stringify(failed) !== JSON.stringify([...observation.failedChecks].sort()))
+        throw Error("corpus browser failed-check list mismatch");
+    for (const [name, errors] of [["no-page-errors", observation.pageErrors], ["bound-resources", observation.resourceErrors]])
+        if (Object.hasOwn(observation.checks, name) && observation.checks[name] !== (errors.length === 0))
+            throw Error("corpus browser error flags mismatch");
+    const observedPass = observation.infrastructureError === undefined && Object.keys(observation.checks).length > 0 && failed.length === 0;
+    if (observation.pass !== observedPass || report.pass !== (state.status === "finished" && observedPass && allPresent))
+        throw Error("corpus browser summary contradicts checks");
+    const checkpoint = z.object({ schemaVersion: z.literal(1), gitHeadSha: z.string().regex(/^[a-f0-9]{40,64}$/),
+        changedPaths: z.array(z.object({ path: z.string(), state: z.string(), contentSha256: digest.optional(), mode: z.string().optional() }).passthrough()) }).passthrough()
+        .parse(JSON.parse((await read(input.runDir, ".runtime/workspace-checkpoint-terminal.json", report.checkpointSha256)).toString("utf8")));
+    const changes = new Map();
+    for (const row of checkpoint.changedPaths) {
+        safeName(row.path);
+        if (changes.has(row.path))
+            throw Error("duplicate corpus checkpoint path");
+        changes.set(row.path, row);
+    }
+    const entries = new Map();
+    const tree = execFileSync("git", ["ls-tree", "-rz", "--full-tree", checkpoint.gitHeadSha], { cwd: input.repoRoot, maxBuffer: 16 * 1024 * 1024 }).toString("utf8");
+    for (const item of tree.split("\0").filter(Boolean)) {
+        const tab = item.indexOf("\t"), name = item.slice(tab + 1), [mode, type] = item.slice(0, tab).split(" ");
+        if (webAsset(name))
+            entries.set(safeName(name), { mode, type: type });
+    }
+    for (const [name, row] of changes)
+        if (webAsset(name)) {
+            if (row.state === "deleted")
+                entries.delete(name);
+            else
+                entries.set(name, { mode: row.mode, type: "blob" });
+        }
+    if (!entries.has("index.html") || !entries.has("src/app.js") || JSON.stringify([...entries.keys()].sort()) !== JSON.stringify(Object.keys(report.artifactHashes).sort()))
+        throw Error("corpus browser terminal resource set mismatch");
+    for (const [name, entry] of entries) {
+        if (entry.type !== "blob" || entry.mode && !["100644", "100755"].includes(entry.mode))
+            throw Error("unsupported corpus browser resource mode");
+        const changed = changes.get(name);
+        if (changed && !changed.contentSha256)
+            throw Error("corpus browser checkpoint digest missing");
+        const expected = changed ? changed.contentSha256 : sha(execFileSync("git", ["show", `${checkpoint.gitHeadSha}:${name}`], { cwd: input.repoRoot, maxBuffer: 16 * 1024 * 1024 }));
+        if (report.artifactHashes[name] !== expected)
+            throw Error("corpus browser terminal resource hash mismatch");
+    }
+    for (const [name, value] of Object.entries(observation.servedFiles))
+        if (!entries.has(safeName(name)) || report.artifactHashes[name] !== value)
+            throw Error("corpus browser served unbound resource");
+    if (report.pass && (!observation.servedFiles["index.html"] || !observation.servedFiles["src/app.js"]))
+        throw Error("corpus browser entry request missing");
+    for (const snapshot of observed) {
+        const latest = await readFileBoundarySafe({ boundaryRoot: snapshot.root, targetPath: path.resolve(snapshot.root, snapshot.name), label: "corpus browser recheck" });
+        if (!latest.equals(snapshot.bytes))
+            throw Error("corpus browser evidence changed during collection");
+    }
+    const diagnostics = ["corpus-browser-only-product-gates-pending"];
+    let browserPassed = failed.length || observation.pageErrors.length || observation.resourceErrors.length ? false : allPresent ? true : null;
+    if (observation.infrastructureError !== undefined) {
+        browserPassed = observation.resourceErrors.length ? false : null;
+        diagnostics.push("corpus-browser-infrastructure-error");
+    }
+    else if (!allPresent)
+        diagnostics.push("corpus-browser-checks-incomplete");
+    return { browserPassed, diagnostics, runId: report.runId, caseId: report.caseId, taskRef: report.taskRef, cellId: report.cellId,
+        corpusHash: corpus.corpusHash, reportSha256: input.report.sha256, contractSha256: input.contract.sha256, artifactHashes: report.artifactHashes };
+}

package/dist/application/evaluation/frontend-gateway-evidence.js

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+import { readFileBoundarySafe } from '../../shared/path-safety.js';
+import { campaignPlanSchema } from './types.js';
+import { computeCampaignPlanHash } from './campaign-hash.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const count = z.number().int().nonnegative().safe();
+const ref = z.object({ path: z.string().min(1), sha256: digest }).strict();
+const bindingSchema = z.object({ campaignId: z.string().min(1), cellId: z.string().min(1), taskRef: z.string().min(1), planHash: z.string().regex(/^sha256:[a-f0-9]{64}$/) }).strict();
+const contractSchema = z.object({ schemaVersion: z.literal(3), evidenceBinding: bindingSchema, upstreamKind: z.enum(['meter', 'provider']), model: z.string().min(1), upstream: z.string().url(), maxTokens: count.positive(), maxRequests: count.positive(), maxWallMs: count.positive(), requestTokenCeiling: count.positive(), payloadByteLimit: count.positive().optional(), maxOutputTokens: count.positive().optional() }).strict();
+const stateSchema = z.object({ schemaVersion: z.literal(1), id: z.string().uuid(), contract: digest, startedAt: count.nullable(), requests: count, tokens: count, inflight: z.null(), stopped: z.string().nullable(), actualModels: z.array(z.string()) }).strict();
+const rowSchema = z.object({ schemaVersion: z.literal(3), evidenceKind: z.literal('gateway-fetch-attempt'), meterId: z.string().uuid(), contract: digest, evidenceBinding: bindingSchema, upstreamKind: z.enum(['meter', 'provider']), requestId: z.string().uuid(), parentRequestId: z.string().uuid().nullable(), request: count.positive(), startedAt: count, finishedAt: count, httpStatus: z.number().int().min(100).max(599).nullable(), totalTokens: count.nullable(), responseUsage: z.record(count), actualModels: z.array(z.string()), error: z.string().nullable(), stopped: z.string().nullable(), wireRequest: z.object({ model: z.string().min(1), payloadSha256: digest, bytes: count, stream: z.boolean(), parameterCoverage: z.literal('selected-explicit-parameters'), explicitParameters: z.record(z.unknown()) }).strict() }).strict();
+/** A single meter's frozen observations, not a task-wide request count or a
+ * billing result. The caller must bind expected identity and artifact hashes
+ * to its preregistered protocol, then validate topology and run coverage. */
+export async function readFrontendGatewayEvidence(input) {
+    const expected = bindingSchema.parse(input.expectedBinding);
+    const snapshots = [];
+    const read = async (raw) => {
+        const value = ref.parse(raw), target = path.resolve(input.repoRoot, value.path);
+        const bytes = await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: target, label: 'gateway evidence' });
+        if (createHash('sha256').update(bytes).digest('hex') !== value.sha256)
+            throw Error('gateway evidence hash mismatch');
+        snapshots.push({ target, bytes });
+        return bytes.toString('utf8');
+    };
+    const contract = contractSchema.parse(JSON.parse(await read(input.contract)));
+    const state = stateSchema.parse(JSON.parse(await read(input.state)));
+    const text = await read(input.requests);
+    const rows = text.trim() ? text.trim().split('\n').map(line => rowSchema.parse(JSON.parse(line))) : [];
+    const sameBinding = (value) => JSON.stringify(value) === JSON.stringify(expected);
+    if (!sameBinding(contract.evidenceBinding) || state.contract !== input.contract.sha256)
+        throw Error('gateway contract identity mismatch');
+    if (state.requests !== rows.length || state.requests > contract.maxRequests)
+        throw Error('gateway request ledger mismatch');
+    if (state.startedAt !== (rows[0]?.startedAt ?? null))
+        throw Error('gateway start time mismatch');
+    const seen = new Set(), models = new Set();
+    let accountedTokens = 0, knownTokens = 0, unknownUsageAttempts = 0, previousFinished = 0;
+    for (const [index, row] of rows.entries()) {
+        if (row.meterId !== state.id || row.contract !== state.contract || !sameBinding(row.evidenceBinding) || row.upstreamKind !== contract.upstreamKind || row.wireRequest.model !== contract.model)
+            throw Error('gateway row identity mismatch');
+        if (row.request !== index + 1 || seen.has(row.requestId))
+            throw Error('gateway duplicate or missing request');
+        if (row.finishedAt < row.startedAt || row.startedAt < previousFinished)
+            throw Error('gateway request timing mismatch');
+        if (row.totalTokens !== null && row.responseUsage.total_tokens !== row.totalTokens || row.totalTokens === null && row.responseUsage.total_tokens !== undefined)
+            throw Error('gateway reported usage mismatch');
+        seen.add(row.requestId);
+        previousFinished = row.finishedAt;
+        for (const model of row.actualModels)
+            models.add(model);
+        if (row.totalTokens === null)
+            unknownUsageAttempts++;
+        else
+            knownTokens += row.totalTokens;
+        accountedTokens += row.totalTokens ?? contract.requestTokenCeiling;
+    }
+    if (!Number.isSafeInteger(accountedTokens) || state.tokens !== accountedTokens)
+        throw Error('gateway token ledger mismatch');
+    if (unknownUsageAttempts && !state.stopped)
+        throw Error('gateway unknown usage without stop');
+    if (JSON.stringify([...models].sort()) !== JSON.stringify([...new Set(state.actualModels)].sort()))
+        throw Error('gateway response model ledger mismatch');
+    for (const snapshot of snapshots) {
+        const latest = await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: snapshot.target, label: 'gateway evidence recheck' });
+        if (!latest.equals(snapshot.bytes))
+            throw Error('gateway evidence changed during collection');
+    }
+    return { evidenceKind: 'single-meter-observations', meterId: state.id, upstreamKind: contract.upstreamKind, upstream: contract.upstream, binding: expected,
+        observedFetchAttempts: rows.length, accountedTokens, reportedTokens: unknownUsageAttempts ? null : knownTokens, unknownUsageAttempts,
+        stopped: state.stopped, rows };
+}
+const topologySchema = z.object({ schemaVersion: z.literal(2), kind: z.literal('frontend-gateway-topology'), campaignId: z.string().min(1), registeredAt: z.string().datetime(), meters: z.array(z.object({ meterId: z.string().uuid(), role: z.enum(['cell', 'shared']), endpoint: z.string().url(), contract: ref, binding: bindingSchema, upstreamMeterId: z.string().uuid().nullable() }).strict()).min(1) }).strict();
+/** Plan precedes gateway topology, which precedes pair registration. Gateway
+ * contracts reference planHash, never the registration that contains them. */
+export async function assertFrontendGatewayTopology(input) {
+    const plan = campaignPlanSchema.parse(input.plan);
+    if (computeCampaignPlanHash(plan.campaignId, plan.cells) !== plan.planHash)
+        throw Error('gateway plan hash mismatch');
+    const snapshots = [];
+    const read = async (raw) => {
+        const value = ref.parse(raw), target = path.resolve(input.repoRoot, value.path);
+        const bytes = await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: target, label: 'registered gateway topology' });
+        if (createHash('sha256').update(bytes).digest('hex') !== value.sha256)
+            throw Error('gateway topology hash mismatch');
+        snapshots.push({ target, bytes });
+        return JSON.parse(bytes.toString('utf8'));
+    };
+    const topology = topologySchema.parse(await read(input.topology));
+    const registeredAt = Date.parse(z.string().datetime().parse(input.registrationCreatedAt));
+    if (topology.campaignId !== plan.campaignId || Date.parse(topology.registeredAt) < Date.parse(plan.createdAt) || Date.parse(topology.registeredAt) > registeredAt)
+        throw Error('gateway topology registration order mismatch');
+    const meters = new Map(topology.meters.map(m => [m.meterId, m])), endpoints = new Set(topology.meters.map(m => m.endpoint));
+    if (meters.size !== topology.meters.length || endpoints.size !== meters.size)
+        throw Error('gateway topology duplicates');
+    const cells = plan.cells.filter(cell => cell.executionRole === 'candidate_run'), matched = new Set();
+    for (const meter of meters.values()) {
+        if (meter.binding.campaignId !== plan.campaignId || meter.binding.planHash !== plan.planHash || new URL(meter.endpoint).origin !== meter.endpoint)
+            throw Error('gateway topology plan binding mismatch');
+        const contract = contractSchema.parse(await read(meter.contract));
+        if (JSON.stringify(contract.evidenceBinding) !== JSON.stringify(meter.binding))
+            throw Error('gateway contract binding mismatch');
+        const upstream = new URL(contract.upstream);
+        if (meter.upstreamMeterId !== null) {
+            if (contract.upstreamKind !== 'meter' || upstream.origin !== meters.get(meter.upstreamMeterId)?.endpoint || !['/chat/completions', '/v1/chat/completions'].includes(upstream.pathname) || upstream.search || upstream.hash || upstream.username || upstream.password)
+                throw Error('gateway upstream mismatch');
+        }
+        else if (contract.upstreamKind !== 'provider' || endpoints.has(upstream.origin))
+            throw Error('gateway provider edge mislabeled');
+        const seen = new Set();
+        let next = meter.meterId;
+        while (next !== null) {
+            if (seen.has(next) || !meters.has(next))
+                throw Error('gateway topology cyclic or incomplete');
+            seen.add(next);
+            next = meters.get(next).upstreamMeterId;
+        }
+        if (meter.role === 'cell') {
+            const candidates = cells.filter(cell => cell.cellId === meter.binding.cellId && cell.taskRef === meter.binding.taskRef);
+            if (candidates.length !== 1 || matched.has(meter.binding.cellId))
+                throw Error('gateway topology cell mismatch');
+            matched.add(meter.binding.cellId);
+        }
+    }
+    if (matched.size !== cells.length)
+        throw Error('gateway topology does not cover planned cells');
+    for (const snapshot of snapshots)
+        if (!(await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: snapshot.target, label: 'gateway admission recheck' })).equals(snapshot.bytes))
+            throw Error('gateway admission evidence changed');
+    return { topologySha256: input.topology.sha256, cellIds: [...matched] };
+}
+/** Verify the supplied snapshot graph. This does not establish that a runtime
+ * used only these gateways, nor that the snapshots cover its whole lifetime. */
+export async function readFrontendGatewayGraph(input) {
+    const topologyRef = ref.parse(input.topology), protocol = z.string().regex(/^sha256:[a-f0-9]{64}$/).parse(input.expectedPlanHash);
+    const target = path.resolve(input.repoRoot, topologyRef.path);
+    const bytes = await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: target, label: 'gateway topology' });
+    if (createHash('sha256').update(bytes).digest('hex') !== topologyRef.sha256)
+        throw Error('gateway topology hash mismatch');
+    const topology = topologySchema.parse(JSON.parse(bytes.toString('utf8')));
+    const declared = new Map(topology.meters.map(m => [m.meterId, m]));
+    const supplied = new Map(input.evidence.map(m => [m.meterId, m]));
+    if (declared.size !== topology.meters.length || supplied.size !== input.evidence.length || declared.size !== supplied.size || [...supplied.keys()].some(id => !declared.has(id)))
+        throw Error('gateway topology meter set mismatch');
+    const endpoints = new Set();
+    for (const meter of declared.values()) {
+        if (new URL(meter.endpoint).origin !== meter.endpoint || endpoints.has(meter.endpoint))
+            throw Error('gateway endpoint invalid or duplicated');
+        endpoints.add(meter.endpoint);
+        if (meter.binding.campaignId !== topology.campaignId || meter.binding.planHash !== protocol)
+            throw Error('gateway topology protocol mismatch');
+        const seen = new Set();
+        let next = meter.meterId;
+        while (next !== null) {
+            if (seen.has(next))
+                throw Error('gateway topology cycle');
+            seen.add(next);
+            const item = declared.get(next);
+            if (!item)
+                throw Error('gateway topology upstream missing');
+            next = item.upstreamMeterId;
+        }
+    }
+    const snapshots = [];
+    for (const meter of declared.values()) {
+        const evidence = supplied.get(meter.meterId);
+        const snapshot = await readFrontendGatewayEvidence({ repoRoot: input.repoRoot, expectedBinding: meter.binding, contract: meter.contract, state: evidence.state, requests: evidence.requests });
+        if (snapshot.meterId !== meter.meterId)
+            throw Error('gateway topology meter identity mismatch');
+        const upstream = new URL(snapshot.upstream);
+        if (meter.upstreamMeterId !== null) {
+            if (snapshot.upstreamKind !== 'meter' || upstream.origin !== declared.get(meter.upstreamMeterId).endpoint || !['/chat/completions', '/v1/chat/completions'].includes(upstream.pathname) || upstream.search || upstream.hash || upstream.username || upstream.password)
+                throw Error('gateway topology upstream endpoint mismatch');
+        }
+        else if (snapshot.upstreamKind !== 'provider' || endpoints.has(upstream.origin))
+            throw Error('gateway provider edge mislabeled');
+        if (snapshot.rows.some(row => Date.parse(topology.registeredAt) >= row.startedAt))
+            throw Error('gateway topology registered after dispatch');
+        snapshots.push(snapshot);
+    }
+    const rows = new Map();
+    for (const row of snapshots.flatMap(s => s.rows)) {
+        if (rows.has(row.requestId))
+            throw Error('gateway request ID reused across meters');
+        rows.set(row.requestId, row);
+    }
+    const children = new Map();
+    for (const row of rows.values()) {
+        if (row.parentRequestId === null) {
+            if (declared.get(row.meterId).role !== 'cell')
+                throw Error('shared gateway request lacks originating cell');
+            continue;
+        }
+        const parent = rows.get(row.parentRequestId);
+        if (!parent || declared.get(parent.meterId).upstreamMeterId !== row.meterId || children.has(parent.requestId))
+            throw Error('gateway parent edge missing or ambiguous');
+        if (parent.wireRequest.payloadSha256 !== row.wireRequest.payloadSha256 || parent.wireRequest.bytes !== row.wireRequest.bytes || parent.wireRequest.model !== row.wireRequest.model || row.startedAt < parent.startedAt || row.finishedAt > parent.finishedAt)
+            throw Error('gateway forwarded request mismatch');
+        children.set(parent.requestId, row);
+    }
+    const diagnostics = [];
+    for (const row of rows.values())
+        if (row.upstreamKind === 'meter' && !children.has(row.requestId)) {
+            if (row.httpStatus !== null && row.httpStatus >= 200 && row.httpStatus < 300)
+                throw Error('successful gateway hop missing');
+            diagnostics.push(`unresolved-meter-hop:${row.requestId}`);
+        }
+    const providerAttempts = [...rows.values()].filter(row => row.upstreamKind === 'provider').map(row => {
+        let origin = row;
+        while (origin.parentRequestId !== null)
+            origin = rows.get(origin.parentRequestId);
+        return { ...row, originCellId: origin.evidenceBinding.cellId, originTaskRef: origin.evidenceBinding.taskRef };
+    });
+    // Re-read against the same hashes after graph validation, so independent
+    // meter snapshots cannot silently change while other meters are collected.
+    for (const meter of declared.values()) {
+        const evidence = supplied.get(meter.meterId);
+        await readFrontendGatewayEvidence({ repoRoot: input.repoRoot, expectedBinding: meter.binding, contract: meter.contract, state: evidence.state, requests: evidence.requests });
+    }
+    if (!(await readFileBoundarySafe({ boundaryRoot: input.repoRoot, targetPath: target, label: 'gateway topology recheck' })).equals(bytes))
+        throw Error('gateway topology changed during collection');
+    return { evidenceKind: 'observed-gateway-request-graph', topologySha256: topologyRef.sha256, observedProviderAttempts: providerAttempts.length,
+        reportedProviderTokens: diagnostics.length || providerAttempts.some(row => row.totalTokens === null) ? null : providerAttempts.reduce((sum, row) => sum + row.totalTokens, 0), providerAttempts, diagnostics };
+}