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

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 };
+}

package/dist/application/evaluation/frontend-pair-registration.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
+import { readFileBoundarySafe } from "../../shared/path-safety.js";
+import { campaignPlanSchema, candidateIdSchema } from "./types.js";
+import { computeCampaignPlanHash } from "./campaign-hash.js";
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const bundleHash = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const ref = z.object({ path: z.string().min(1), sha256: hash }).strict();
+// Keep registration schemas independent of DAG evidence readers: DAG types
+// import this module while the readers themselves depend on DAG lifecycle.
+export const frontendSharedArtifactsSchema = z.object({ source: ref, budget: ref, model: ref, initialTree: ref }).strict();
+const sharedSchema = z.object({ source: hash, model: hash, budget: hash, initialTree: hash, acceptance: hash }).strict();
+const armSchema = z.object({ candidateId: candidateIdSchema, bundleHash, controllerFingerprint: bundleHash, controller: ref, promptTools: ref }).strict();
+const registrationSchema = z.object({
+    schemaVersion: z.literal(1), kind: z.literal("frontend-task-pair-registration"),
+    createdAt: z.string().datetime(), campaignId: z.string().min(1), planHash: bundleHash,
+    baseline: armSchema, candidate: armSchema, shared: sharedSchema, sharedArtifacts: frontendSharedArtifactsSchema.optional(),
+    gatewayTopology: ref.optional(),
+}).strict();
+const observedSchema = sharedSchema.extend({ protocol: hash, controller: hash, promptTools: hash }).strict();
+/** Identity admission only, not acceptance or promotion. `identities` must be
+ * collected by a reader which verifies the run and all referenced artifacts;
+ * this gate binds those identities to predeclared, rehashed candidate bytes. */
+export async function validateFrontendPairRegistration(input) {
+    const registrationRef = ref.parse(input.registration);
+    const read = async () => {
+        const bytes = await readFileBoundarySafe({ boundaryRoot: input.repoRoot,
+            targetPath: path.resolve(input.repoRoot, registrationRef.path), label: "frontend pair registration" });
+        if (createHash("sha256").update(bytes).digest("hex") !== registrationRef.sha256)
+            throw Error("pair registration hash mismatch");
+        return registrationSchema.parse(JSON.parse(bytes.toString("utf8")));
+    };
+    const registration = await read();
+    const plan = campaignPlanSchema.parse(input.plan);
+    if (computeCampaignPlanHash(plan.campaignId, plan.cells) !== plan.planHash)
+        throw Error("pair plan content hash mismatch");
+    if (registration.campaignId !== plan.campaignId || registration.planHash !== plan.planHash)
+        throw Error("pair registration plan mismatch");
+    if (registration.baseline.candidateId === registration.candidate.candidateId)
+        throw Error("distinct registered candidates required");
+    const startedAt = Date.parse(z.string().datetime().parse(input.earliestRunStartedAt));
+    const registeredAt = Date.parse(registration.createdAt), plannedAt = Date.parse(plan.createdAt);
+    if (!Number.isFinite(plannedAt) || plannedAt > registeredAt || registeredAt >= startedAt)
+        throw Error("pair must be planned and registered before execution");
+    const baselineCells = plan.cells.filter(cell => cell.cellId === input.baselineCellId);
+    const candidateCells = plan.cells.filter(cell => cell.cellId === input.candidateCellId);
+    if (baselineCells.length !== 1 || candidateCells.length !== 1)
+        throw Error("pair cells missing or duplicated");
+    const baseline = baselineCells[0], candidate = candidateCells[0];
+    if (baseline.executionRole !== "candidate_run" || candidate.executionRole !== "candidate_run" ||
+        baseline.taskRef !== candidate.taskRef || baseline.seed !== candidate.seed || baseline.split !== candidate.split)
+        throw Error("pair cells do not share task/seed/split");
+    for (const [side, cell] of [["baseline", baseline], ["candidate", candidate]]) {
+        const arm = registration[side];
+        if (cell.candidateId !== arm.candidateId || cell.bundleHash !== arm.bundleHash)
+            throw Error("pair cell candidate mismatch");
+        const record = await readCandidateRecord(input.repoRoot, arm.candidateId);
+        if (record.manifest.bundleHash !== arm.bundleHash)
+            throw Error("registered candidate bundle mismatch");
+        const candidateTime = Date.parse(record.manifest.createdAt);
+        const recordedAt = Date.parse(record.events[0]?.at ?? "");
+        if (!Number.isFinite(candidateTime) || !Number.isFinite(recordedAt) ||
+            candidateTime > registeredAt || recordedAt > registeredAt)
+            throw Error("candidate registered after pair protocol");
+        const identity = observedSchema.parse(input.identities[side]);
+        if (identity.protocol !== registrationRef.sha256)
+            throw Error("observed protocol mismatch");
+        for (const key of ["source", "model", "budget", "initialTree", "acceptance"]) {
+            if (identity[key] !== registration.shared[key])
+                throw Error(`shared pair identity mismatch: ${key}`);
+        }
+        for (const key of ["controller", "promptTools"]) {
+            const declared = arm[key];
+            if (!record.manifest.contentRefs.some(content => content.path === declared.path && content.sha256 === `sha256:${declared.sha256}`))
+                throw Error(`candidate does not own registered ${key} snapshot`);
+            if (identity[key] !== declared.sha256)
+                throw Error(`observed candidate ${key} mismatch`);
+        }
+    }
+    if (registration.gatewayTopology) {
+        const { assertFrontendGatewayTopology } = await import("./frontend-gateway-evidence.js");
+        await assertFrontendGatewayTopology({ repoRoot: input.repoRoot, topology: registration.gatewayTopology, plan, registrationCreatedAt: registration.createdAt });
+    }
+    await read();
+    return { campaignId: plan.campaignId, planHash: plan.planHash, registrationSha256: registrationRef.sha256,
+        baselineCandidateId: baseline.candidateId, candidateId: candidate.candidateId };
+}
+export const frontendPairExecutionBindingSchema = z.object({
+    registration: ref, cellId: z.string().min(1),
+}).strict();
+/** Called by the runner before allocation and on resume. */
+export async function assertFrontendPairExecution(input) {
+    const pair = frontendPairExecutionBindingSchema.parse(input.binding.frontendPair);
+    const bytes = await readFileBoundarySafe({ boundaryRoot: input.repoRoot,
+        targetPath: path.resolve(input.repoRoot, pair.registration.path), label: "frontend execution registration" });
+    if (createHash("sha256").update(bytes).digest("hex") !== pair.registration.sha256)
+        throw Error("execution registration hash mismatch");
+    const protocol = registrationSchema.parse(JSON.parse(bytes.toString("utf8")));
+    const { readCampaignPlan } = await import("../../infrastructure/evaluation/campaign-store.js");
+    const stored = await readCampaignPlan(input.repoRoot, input.binding.campaignId);
+    if (!stored)
+        throw Error("frontend pair campaign plan missing");
+    const plan = campaignPlanSchema.parse(stored);
+    if (protocol.campaignId !== input.binding.campaignId || protocol.planHash !== plan.planHash ||
+        computeCampaignPlanHash(plan.campaignId, plan.cells) !== plan.planHash)
+        throw Error("execution pair plan mismatch");
+    const registeredAt = Date.parse(protocol.createdAt), startedAt = Date.parse(input.startedAt), plannedAt = Date.parse(plan.createdAt);
+    if (![registeredAt, startedAt, plannedAt].every(Number.isFinite) || plannedAt > registeredAt || registeredAt >= startedAt)
+        throw Error("execution pair protocol must predate run");
+    const arms = [protocol.baseline, protocol.candidate].filter(arm => arm.candidateId === input.binding.candidateId);
+    const cells = plan.cells.filter(cell => cell.cellId === pair.cellId);
+    if (arms.length !== 1 || cells.length !== 1)
+        throw Error("execution pair arm or cell missing/ambiguous");
+    const arm = arms[0], cell = cells[0];
+    if (cell.executionRole !== "candidate_run" || cell.candidateId !== arm.candidateId || cell.bundleHash !== arm.bundleHash ||
+        input.binding.bundleHash !== arm.bundleHash || cell.seed !== input.binding.seed || cell.split !== input.binding.split || cell.taskRef !== input.binding.taskRef)
+        throw Error("execution pair cell binding mismatch");
+    if (protocol.baseline.candidateId === protocol.candidate.candidateId)
+        throw Error("execution pair requires distinct arms");
+    for (const member of [protocol.baseline, protocol.candidate]) {
+        const partners = plan.cells.filter(row => row.executionRole === "candidate_run" && row.candidateId === member.candidateId &&
+            row.taskRef === cell.taskRef && row.seed === cell.seed && row.split === cell.split);
+        if (partners.length !== 1 || partners[0].bundleHash !== member.bundleHash)
+            throw Error("execution pair counterpart missing or mismatched");
+    }
+    if (arm.controllerFingerprint !== input.controllerFingerprint)
+        throw Error("execution pair controller fingerprint mismatch");
+    const record = await readCandidateRecord(input.repoRoot, arm.candidateId);
+    const recordedAt = Date.parse(record.events[0]?.at ?? "");
+    if (record.manifest.bundleHash !== arm.bundleHash || !Number.isFinite(recordedAt) || recordedAt > registeredAt)
+        throw Error("execution pair candidate registration mismatch");
+    for (const key of ["controller", "promptTools"]) {
+        if (!record.manifest.contentRefs.some(content => content.path === arm[key].path && content.sha256 === `sha256:${arm[key].sha256}`))
+            throw Error("execution pair snapshot not owned by candidate");
+    }
+    if (protocol.gatewayTopology) {
+        const { assertFrontendGatewayTopology } = await import("./frontend-gateway-evidence.js");
+        await assertFrontendGatewayTopology({ repoRoot: input.repoRoot, topology: protocol.gatewayTopology, plan, registrationCreatedAt: protocol.createdAt });
+    }
+    return { planHash: plan.planHash, shared: protocol.shared, sharedArtifacts: protocol.sharedArtifacts, gatewayTopology: protocol.gatewayTopology };
+}

package/dist/application/evaluation/frontend-paired-summary.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { campaignPlanSchema } from "./types.js";
+const metric = z.number().finite().nonnegative().nullable();
+const observationSchema = z.object({
+    cellId: z.string().min(1),
+    bundleHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    runId: z.string().min(1),
+    firstPassed: z.boolean().nullable(),
+    finalPassed: z.boolean().nullable(),
+    requests: z.number().int().nonnegative().nullable(),
+    tokens: z.number().int().nonnegative().nullable(),
+    wallClockMs: metric,
+}).strict().refine(row => row.firstPassed !== true || row.finalPassed === true, {
+    message: "first success requires final success",
+});
+/** For independent paired trials, Hoeffding bounds the mean of differences
+ * in [-1, 1]: P(|mean - E(mean)| >= e) <= 2 exp(-n e² / 2).
+ * This deliberately stays wide for small samples, including all ties.
+ * Each interval has marginal 95% coverage, not simultaneous coverage across
+ * metrics/cases, and targets this fixed plan rather than unseen task classes. */
+function pairedUncertainty(pairs) {
+    const calculate = (field) => {
+        let observed = 0, totalDifference = 0;
+        for (const pair of pairs) {
+            const before = pair.baseline?.[field], after = pair.candidate?.[field];
+            if (before == null || after == null)
+                continue;
+            observed++;
+            totalDifference += Number(after) - Number(before);
+        }
+        const complete = observed === pairs.length && observed > 0;
+        const difference = complete ? totalDifference / observed : null;
+        const halfWidth = complete ? Math.sqrt(2 * Math.log(40) / observed) : null;
+        return {
+            method: "paired-hoeffding", confidenceLevel: 0.95,
+            assumption: "independent-paired-trials-fixed-plan",
+            planned: pairs.length, observed, difference,
+            interval: difference === null || halfWidth === null ? null : {
+                lower: Math.max(-1, difference - halfWidth), upper: Math.min(1, difference + halfWidth),
+            },
+        };
+    };
+    return { first: calculate("firstPassed"), final: calculate("finalPassed") };
+}
+function distribution(values) {
+    if (!values.length || values.some(value => value === null)) {
+        return { values, total: null, median: null, maximum: null };
+    }
+    const sorted = values.slice().sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return {
+        values,
+        total: sorted.reduce((sum, value) => sum + value, 0),
+        median: sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2,
+        maximum: sorted.at(-1),
+    };
+}
+function summarize(rows) {
+    const success = (field) => {
+        const values = rows.map(row => row?.[field] ?? null);
+        const passed = values.filter(value => value === true).length;
+        const failed = values.filter(value => value === false).length;
+        const unknown = values.length - passed - failed;
+        return { planned: rows.length, passed, failed, unknown, rate: unknown || !rows.length ? null : passed / rows.length };
+    };
+    const first = success("firstPassed"), final = success("finalPassed");
+    const requests = distribution(rows.map(row => row?.requests ?? null));
+    const tokens = distribution(rows.map(row => row?.tokens ?? null));
+    const wallClockMs = distribution(rows.map(row => row?.wallClockMs ?? null));
+    return {
+        first, final, requests, tokens, wallClockMs,
+        // Failed attempts remain in the numerator. Unknown or zero correct
+        // deliveries cannot yield an apparent zero-cost delivery.
+        tokensPerCorrectDelivery: final.unknown || !final.passed || tokens.total === null ? null : tokens.total / final.passed,
+    };
+}
+/** Descriptive statistics only. The caller must verify source artifacts and
+ * preregistered identity/model/budget/oracle bindings before interpreting these
+ * observations. This function never authorizes promotion or returns a pass. */
+export function summarizeFrontendTaskPairs(input) {
+    const plan = campaignPlanSchema.parse(input.plan);
+    if (input.baselineCandidateId === input.candidateId)
+        throw Error("distinct candidates required");
+    const cells = plan.cells.filter(cell => cell.executionRole === "candidate_run" &&
+        [input.baselineCandidateId, input.candidateId].includes(cell.candidateId));
+    const byId = new Map(cells.map(cell => [cell.cellId, cell]));
+    if (byId.size !== cells.length)
+        throw Error("duplicate planned cell");
+    const observations = new Map();
+    const runIds = new Set();
+    for (const raw of input.observations) {
+        const row = observationSchema.parse(raw), cell = byId.get(row.cellId);
+        if (!cell || cell.bundleHash !== row.bundleHash)
+            throw Error("observation does not match planned candidate cell");
+        if (observations.has(row.cellId) || runIds.has(row.runId))
+            throw Error("duplicate cell or run observation");
+        observations.set(row.cellId, row);
+        runIds.add(row.runId);
+    }
+    const groups = new Map();
+    for (const cell of cells) {
+        const key = JSON.stringify([cell.split, cell.taskRef, cell.seed]);
+        const pair = groups.get(key) ?? { taskRef: cell.taskRef, split: cell.split, seed: cell.seed };
+        const side = cell.candidateId === input.baselineCandidateId ? "baselineCellId" : "candidateCellId";
+        if (pair[side])
+            throw Error("duplicate planned candidate/task/seed/split");
+        pair[side] = cell.cellId;
+        groups.set(key, pair);
+    }
+    if (!groups.size || [...groups.values()].some(pair => !pair.baselineCellId || !pair.candidateCellId)) {
+        throw Error("plan must contain both arms for every pair");
+    }
+    const pairs = [...groups.values()].map(pair => ({
+        ...pair,
+        baseline: observations.get(pair.baselineCellId) ?? null,
+        candidate: observations.get(pair.candidateCellId) ?? null,
+    }));
+    const perCase = [...new Set(pairs.map(pair => JSON.stringify([pair.split, pair.taskRef])))].map(key => {
+        const selected = pairs.filter(pair => JSON.stringify([pair.split, pair.taskRef]) === key);
+        const tally = (field) => {
+            const counts = { baselineWins: 0, candidateWins: 0, ties: 0, unknown: 0 };
+            for (const pair of selected) {
+                const before = pair.baseline?.[field], after = pair.candidate?.[field];
+                if (before == null || after == null)
+                    counts.unknown++;
+                else if (before === after)
+                    counts.ties++;
+                else if (after)
+                    counts.candidateWins++;
+                else
+                    counts.baselineWins++;
+            }
+            return counts;
+        };
+        return { taskRef: selected[0].taskRef, split: selected[0].split,
+            first: tally("firstPassed"), final: tally("finalPassed"),
+            pairedUncertainty: pairedUncertainty(selected),
+            baseline: summarize(selected.map(pair => pair.baseline)),
+            candidate: summarize(selected.map(pair => pair.candidate)) };
+    });
+    return {
+        evidenceKind: "descriptive-task-pair-summary", perCase,
+        campaignId: plan.campaignId, planHash: plan.planHash,
+        baselineCandidateId: input.baselineCandidateId, candidateId: input.candidateId,
+        pairs,
+        pairedUncertainty: pairedUncertainty(pairs),
+        baseline: summarize(pairs.map(pair => pair.baseline)),
+        candidate: summarize(pairs.map(pair => pair.candidate)),
+    };
+}