@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/lab/live/executor.ts

@@ -0,0 +1,311 @@
+import { evaluateAssertions } from "../conformance/assertion";
+import { emptyObservation, finalizeObservation, setClientResponse } from "../conformance/observation";
+import { normalizeSseBytes } from "../conformance/sse-normalize";
+import type { CaseAuthority, CaseRecord, FailureClassification, FailureRule, NormalizedEvent, NormalizedObservation } from "../conformance/types";
+import { domainHash, jcsStringify, scenarioManifestDigest, subjectIdForSubject, suiteManifestDigest } from "../digest";
+import type { RouteSubjectV1 } from "../events/types";
+import { isTrustedLabRouteExecutor } from "../../lib/lab-live-execution-authority";
+import { buildRouteSubjectV1 } from "../subject/route-subject";
+import { createLabDestination, LabDestinationError } from "./destination";
+import { expandLiveScenario, loadLiveCaseAuthority } from "./manifest";
+import { createSandboxResourceState, enforceSandboxLimits, LabSandboxError, prepareLiveSandbox } from "./sandbox";
+import { liveSuiteManifestObjectForCase } from "./suite-manifest";
+import { classifyTransportError, TransportError } from "./transport";
+import type { DnsResolver, LabRouteContext, LabTransport, LiveExecutionAuthority, LiveRunConfig, LiveScenarioRunResult, TrustedLabRouteExecutor } from "./types";
+
+export interface LiveExecutorOptions {
+  /** Host-issued exact-route capability for evidence-eligible production execution. */
+  routeExecutor?: TrustedLabRouteExecutor;
+  /** Test-only byte transport. Results are deliberately not evidence-eligible. */
+  transport?: LabTransport;
+  resolve?: DnsResolver;
+  configDir?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface TrustedLiveResultReceipt {
+  authorityDigest: string;
+  scenarioId: string;
+  suiteId: string;
+  scenarioManifestDigest: string;
+  suiteManifestDigest: string;
+  routeSubjectId: string;
+  resultDigest: string;
+  retryPolicy: FailureRule["retry"] | null;
+}
+
+const TRUSTED_RESULT_RECEIPTS = new WeakMap<object, TrustedLiveResultReceipt>();
+const LIVE_AUTHORITY_DOMAIN = "ocx-lab:live-authority:v1";
+const TRUSTED_LIVE_RESULT_DOMAIN = "ocx-lab:trusted-live-result:v1";
+
+function trustedResultDigest(result: LiveScenarioRunResult): string {
+  const payload = {
+    scenarioId: result.scenarioId,
+    suite: result.suite,
+    startedAt: result.startedAt,
+    completedAt: result.completedAt,
+    passed: result.passed,
+    classification: result.classification,
+    secondaryCode: result.secondaryCode ?? null,
+    assertionResults: result.assertionResults.map((row) => ({
+      id: row.id,
+      operator: row.operator,
+      required: row.required,
+      passed: row.passed,
+      observedSummary: row.observedSummary,
+      reason: row.reason ?? null,
+    })),
+    diagnostics: [...result.diagnostics],
+    routeSubject: result.routeSubject ?? null,
+    transportError: result.transportError ?? null,
+    executionAuthority: result.executionAuthority,
+  };
+  return domainHash(TRUSTED_LIVE_RESULT_DOMAIN, jcsStringify(payload));
+}
+
+function receiptFor(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority, retryPolicy: FailureRule["retry"] | null): TrustedLiveResultReceipt {
+  if (!result.routeSubject) throw new Error("trusted live result has no route subject");
+  return {
+    authorityDigest: domainHash(LIVE_AUTHORITY_DOMAIN, jcsStringify(authority)),
+    scenarioId: caseRecord.id,
+    suiteId: caseRecord.suite,
+    scenarioManifestDigest: scenarioManifestDigest(expandLiveScenario(caseRecord, authority)),
+    suiteManifestDigest: suiteManifestDigest(liveSuiteManifestObjectForCase(caseRecord, authority)),
+    routeSubjectId: subjectIdForSubject(result.routeSubject),
+    resultDigest: trustedResultDigest(result),
+    retryPolicy,
+  };
+}
+
+function sealTrustedLiveResult(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority, retryPolicy: FailureRule["retry"] | null): void {
+  TRUSTED_RESULT_RECEIPTS.set(result, receiptFor(result, caseRecord, authority, retryPolicy));
+}
+
+/** Verify the module-private execution receipt before any live result enters persistence. */
+export function assertTrustedLiveResultReceipt(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority): void {
+  const actual = TRUSTED_RESULT_RECEIPTS.get(result);
+  if (!actual || result.executionAuthority !== "trusted_route") {
+    throw new Error("live result lacks trusted execution receipt");
+  }
+  const expected = receiptFor(result, caseRecord, authority, actual.retryPolicy);
+  for (const key of Object.keys(expected) as Array<keyof TrustedLiveResultReceipt>) {
+    if (actual[key] !== expected[key]) throw new Error("live result trusted execution receipt mismatch");
+  }
+  if (result.scenarioId !== caseRecord.id || result.suite !== caseRecord.suite) {
+    throw new Error("live result scenario identity mismatch");
+  }
+}
+
+/** Return retryability sealed by the executor after validating the trusted receipt. */
+export function trustedLiveResultRetryable(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority): boolean {
+  assertTrustedLiveResultReceipt(result, caseRecord, authority);
+  return TRUSTED_RESULT_RECEIPTS.get(result)?.retryPolicy === "bounded";
+}
+
+function liveLimitsFromAuthority(authorityLimits: Record<string, number>): LiveRunConfig {
+  return {
+    totalTimeoutMs: authorityLimits.totalTimeoutMs ?? 120_000, connectTimeoutMs: authorityLimits.connectTimeoutMs ?? 10_000,
+    firstByteTimeoutMs: authorityLimits.firstByteTimeoutMs ?? 30_000, inactivityTimeoutMs: authorityLimits.inactivityTimeoutMs ?? 30_000,
+    maxRequests: authorityLimits.maxRequests ?? 16, maxInputBytes: authorityLimits.maxInputBytes ?? 8 * 1024 * 1024,
+    maxOutputBytes: authorityLimits.maxOutputBytes ?? 16 * 1024 * 1024, maxOutputTokens: authorityLimits.maxOutputTokens ?? 32_768,
+    maxToolCalls: authorityLimits.maxToolCalls ?? 32, maxMemoryBytes: authorityLimits.maxMemoryBytes ?? 512 * 1024 * 1024,
+    maxChildProcesses: authorityLimits.maxChildProcesses ?? 0, maxArtifacts: authorityLimits.maxArtifacts ?? 16,
+    perArtifactBytes: authorityLimits.perArtifactBytes ?? 256 * 1024, aggregateArtifactBytes: authorityLimits.aggregateArtifactBytes ?? 1024 * 1024,
+  };
+}
+
+export function isLiveCaseApplicableToRoute(caseRecord: CaseRecord, route: LabRouteContext): boolean {
+  const req = caseRecord.requirements;
+  if (!req.inboundProtocols.includes(route.inboundProtocol) || !req.upstreamProtocols.includes(route.upstreamProtocol) || !req.surfaces.includes(route.surface)) return false;
+  if (req.platforms.length > 0 && !req.platforms.includes(process.platform)) return false;
+  if (!req.requiredClaims.every((claim) => (route.requiredClaims ?? []).includes(claim))) return false;
+  if (!req.requiredHarnessFeatures.every((feature) => (route.availableHarnessFeatures ?? []).includes(feature))) return false;
+  return true;
+}
+
+function routePreconditionFailure(route: LabRouteContext, caseRecord: CaseRecord): string | null {
+  for (const precondition of caseRecord.requirements.routePreconditions) {
+    if (precondition === "lab_run_approval" && route.labRunApproval !== true) return "route_precondition_unmet:lab_run_approval";
+    if (precondition === "allow_private_network" && route.allowPrivateNetwork !== true) return "route_precondition_unmet:allow_private_network";
+  }
+  return null;
+}
+
+function classifyWithFailureRules(rules: FailureRule[], signal: string): { classification: FailureClassification; secondaryCode: string; retryPolicy: FailureRule["retry"] | null } {
+  const rule = rules.find((row) => row.match.includes(signal));
+  return rule ? { classification: rule.classification, secondaryCode: rule.secondaryCode ?? signal, retryPolicy: rule.retry }
+    : { classification: "inconclusive", secondaryCode: "unclassified", retryPolicy: null };
+}
+
+function pathForProtocol(protocol: string): string {
+  if (protocol === "openai-chat") return "/chat/completions";
+  if (protocol === "anthropic-messages") return "/messages";
+  return "/responses";
+}
+
+function chatObservation(body: string, status: number): NormalizedObservation {
+  const observation = emptyObservation();
+  const output: unknown[] = [];
+  let text = "";
+  let terminal = false;
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith("data:")) {
+    const toolParts = new Map<number, { id: string; name: string; arguments: string }>();
+    for (const frame of body.split(/\r?\n\r?\n/)) {
+      const line = frame.split(/\r?\n/).find((row) => row.startsWith("data:"));
+      if (!line) continue;
+      const payload = line.slice(5).trim();
+      if (!payload || payload === "[DONE]") { if (payload === "[DONE]") terminal = true; continue; }
+      let json: any;
+      try { json = JSON.parse(payload); } catch { continue; }
+      for (const choice of Array.isArray(json.choices) ? json.choices : []) {
+        if (typeof choice?.delta?.content === "string") text += choice.delta.content;
+        if (choice?.finish_reason != null) terminal = true;
+        for (const call of Array.isArray(choice?.delta?.tool_calls) ? choice.delta.tool_calls : []) {
+          const idx = Number.isInteger(call?.index) ? call.index : toolParts.size;
+          const prior = toolParts.get(idx) ?? { id: "", name: "", arguments: "" };
+          if (typeof call?.id === "string") prior.id = call.id;
+          if (typeof call?.function?.name === "string") prior.name = call.function.name;
+          if (typeof call?.function?.arguments === "string") prior.arguments += call.function.arguments;
+          toolParts.set(idx, prior);
+        }
+      }
+    }
+    for (const row of [...toolParts.entries()].sort((a, b) => a[0] - b[0]).map(([, value]) => value)) {
+      output.push({ type: "function_call", call_id: row.id, name: row.name, arguments: row.arguments });
+    }
+  } else {
+    const json = JSON.parse(body) as any;
+    const choice = Array.isArray(json.choices) ? json.choices[0] : undefined;
+    if (typeof choice?.message?.content === "string") text = choice.message.content;
+    terminal = choice?.finish_reason != null;
+    for (const call of Array.isArray(choice?.message?.tool_calls) ? choice.message.tool_calls : []) {
+      output.push({ type: "function_call", call_id: call.id, name: call.function?.name, arguments: call.function?.arguments });
+    }
+  }
+  if (text) output.unshift({ type: "message", content: [{ type: "output_text", text }] });
+  const json = { status: terminal ? "completed" : "incomplete", output };
+  const events: NormalizedEvent[] = terminal ? [{ event: "response.completed", data: { response: json }, ordinal: 0 }] : [];
+  finalizeObservation(observation, events, json, status);
+  return observation;
+}
+
+function responsesObservation(body: string, status: number): NormalizedObservation {
+  const observation = emptyObservation();
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith("data:") || trimmed.startsWith("event:")) {
+    const events = normalizeSseBytes(new TextEncoder().encode(body), "openai-responses");
+    finalizeObservation(observation, events, null, status);
+    return observation;
+  }
+  const json = JSON.parse(body) as Record<string, unknown>;
+  finalizeObservation(observation, [], json, status);
+  const state = typeof json.status === "string" ? json.status : undefined;
+  if (state === "completed" || state === "failed" || state === "incomplete") {
+    setClientResponse(observation, { terminal: state === "completed" ? "completed" : state });
+  }
+  return observation;
+}
+
+function normalizeTransportObservation(route: LabRouteContext, response: { status: number; body: string }): NormalizedObservation {
+  const observation = route.upstreamProtocol === "openai-chat" ? chatObservation(response.body, response.status) : responsesObservation(response.body, response.status);
+  if (route.surface.startsWith("anthropic-") && observation.client.response.terminal === "completed") {
+    setClientResponse(observation, { terminal: "message_stop" });
+  }
+  return observation;
+}
+
+async function withTotalTimeout<T>(timeoutMs: number, run: (signal: AbortSignal) => Promise<T>): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new TransportError("total_timeout", "live scenario total timeout")), timeoutMs);
+  try {
+    return await Promise.race([
+      run(controller.signal),
+      new Promise<T>((_, reject) => controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true })),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
+export async function runLiveScenario(caseRecord: CaseRecord, routeContext: LabRouteContext, opts: LiveExecutorOptions = {}): Promise<LiveScenarioRunResult> {
+  const diagnostics: string[] = [];
+  const startedAt = Date.now();
+  let routeSubject: RouteSubjectV1 | undefined;
+  let executionAuthority: LiveExecutionAuthority = "none";
+  let authority: CaseAuthority | undefined;
+  let activeCase = caseRecord;
+  let trustedExecutionStarted = false;
+  let failureRules: FailureRule[] = [];
+  const complete = (partial: Omit<LiveScenarioRunResult, "startedAt" | "completedAt" | "executionAuthority">, retryPolicy: FailureRule["retry"] | null = null): LiveScenarioRunResult => {
+    const result: LiveScenarioRunResult = { ...partial, executionAuthority, startedAt, completedAt: Math.max(startedAt, Date.now()) };
+    if (trustedExecutionStarted && authority && result.routeSubject) sealTrustedLiveResult(result, activeCase, authority, retryPolicy);
+    return result;
+  };
+  try {
+    const environment = prepareLiveSandbox(opts.env);
+    authority = loadLiveCaseAuthority();
+    const canonicalCase = authority.cases.find((row) => row.id === caseRecord.id);
+    if (!canonicalCase || jcsStringify(canonicalCase) !== jcsStringify(caseRecord)) {
+      throw new TransportError("harness_failure", "live scenario does not match canonical authority");
+    }
+    activeCase = canonicalCase;
+    if (!isLiveCaseApplicableToRoute(activeCase, routeContext)) {
+      return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed: false, classification: "inconclusive", secondaryCode: "scenario_inapplicable", assertionResults: [], diagnostics, routeSubject });
+    }
+    const preconditionFailure = routePreconditionFailure(routeContext, activeCase);
+    if (preconditionFailure) {
+      return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed: false, classification: "inconclusive", secondaryCode: preconditionFailure, assertionResults: [], diagnostics: [preconditionFailure], routeSubject });
+    }
+    const expanded = expandLiveScenario(activeCase, authority);
+    failureRules = expanded.failureRules as FailureRule[];
+    const limits = liveLimitsFromAuthority(expanded.executionLimits as Record<string, number>);
+    const destination = await createLabDestination({ baseUrl: routeContext.baseUrl, allowPrivateNetwork: routeContext.allowPrivateNetwork, labRunApproval: routeContext.labRunApproval, resolve: opts.resolve, configDir: opts.configDir });
+    routeSubject = buildRouteSubjectV1(routeContext, destination, opts.configDir);
+    const state = createSandboxResourceState();
+    let observation: NormalizedObservation;
+    if (opts.routeExecutor) {
+      if (!isTrustedLabRouteExecutor(opts.routeExecutor)) throw new TransportError("untrusted_route_executor", "untrusted route executor capability");
+      executionAuthority = "trusted_route";
+      trustedExecutionStarted = true;
+      observation = await withTotalTimeout(limits.totalTimeoutMs, (signal) => opts.routeExecutor!.execute({ routeContext, destination, routeSubject: routeSubject!, scenarioId: activeCase.id, initiatingRequest: activeCase.initiatingRequest?.bytesUtf8, limits, signal, environment }));
+    } else if (opts.transport && activeCase.initiatingRequest) {
+      executionAuthority = "test_transport";
+      const body = activeCase.initiatingRequest.bytesUtf8;
+      const inputBytes = new TextEncoder().encode(body).byteLength;
+      enforceSandboxLimits(state, limits, { requests: 1, inputBytes });
+      const response = await withTotalTimeout(limits.totalTimeoutMs, (signal) => opts.transport!.request({ method: "POST", path: pathForProtocol(routeContext.upstreamProtocol), body, signal }));
+      if (response.status === 401 || response.status === 403) throw new TransportError("auth_blocked", `HTTP ${response.status}`);
+      if (response.status === 429) throw new TransportError("quota_blocked", "HTTP 429");
+      if (response.status === 451) throw new TransportError("region_blocked", "HTTP 451");
+      if (response.status >= 500) throw new TransportError("provider_transient", `HTTP ${response.status}`);
+      const outputBytes = new TextEncoder().encode(response.body).byteLength;
+      enforceSandboxLimits(state, limits, { outputBytes, outputTokens: Math.ceil(outputBytes / 4) });
+      observation = normalizeTransportObservation(routeContext, response);
+    } else {
+      throw new TransportError("live_transport_required", activeCase.initiatingRequest ? "live transport or trusted route executor required" : "trusted route executor required");
+    }
+    const assertionResults = evaluateAssertions(activeCase.assertions, observation);
+    const requiredFailures = assertionResults.filter((row) => row.required && !row.passed);
+    if (activeCase.expectedFailure) {
+      const matched = activeCase.expectedFailure.assertionIds.every((id) => assertionResults.find((row) => row.id === id)?.passed === true) && requiredFailures.length === 0;
+      if (matched) {
+        return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed: true, classification: activeCase.expectedFailure.expectedClass, secondaryCode: activeCase.expectedFailure.expectedCode, assertionResults, diagnostics, routeSubject });
+      }
+      const mismatch = classifyWithFailureRules(failureRules, "required_assertion_failed");
+      return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed: false, classification: mismatch.classification, secondaryCode: mismatch.secondaryCode, assertionResults, diagnostics, routeSubject }, mismatch.retryPolicy);
+    }
+    const passed = requiredFailures.length === 0;
+    const classified = passed ? { classification: "inconclusive" as FailureClassification, secondaryCode: "pass", retryPolicy: null } : classifyWithFailureRules(failureRules, "required_assertion_failed");
+    return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed, classification: passed ? "inconclusive" : classified.classification, secondaryCode: passed ? undefined : classified.secondaryCode, assertionResults, diagnostics, routeSubject }, passed ? null : classified.retryPolicy);
+  } catch (error) {
+    const diagnosticCode = error instanceof TransportError || error instanceof LabSandboxError || error instanceof LabDestinationError
+      ? error.code
+      : "execution_error";
+    diagnostics.push(diagnosticCode);
+    let classified = classifyTransportError(error);
+    if (error instanceof LabSandboxError) classified = { classification: error.code === "harness_failure" ? "harness_failure" : "budget_exhausted", secondaryCode: error.code };
+    if (error instanceof LabDestinationError) classified = { classification: error.code === "network_blocked" ? "network_failure" : "harness_failure", secondaryCode: error.code };
+    const failureSignal = error instanceof TransportError || error instanceof LabSandboxError || error instanceof LabDestinationError ? error.code : "harness_failure";
+    const retryPolicy = failureRules.find((rule) => rule.match.includes(failureSignal))?.retry ?? null;
+    return complete({ scenarioId: activeCase.id, suite: activeCase.suite, passed: false, classification: classified.classification, secondaryCode: classified.secondaryCode, assertionResults: [], diagnostics, routeSubject, transportError: error instanceof TransportError ? error.code : undefined }, retryPolicy);
+  }
+}

package/src/lab/live/inert-tools.ts

@@ -0,0 +1,56 @@
+export interface InertToolDefinition {
+  name: string;
+  kind: "function" | "custom";
+  description?: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface InertToolResult {
+  output: string;
+}
+
+const LAB_TOOLS: Record<string, InertToolDefinition & { staticResult: InertToolResult }> = {
+  lookup: {
+    name: "lookup",
+    kind: "function",
+    description: "Lab inert lookup tool",
+    parameters: {
+      type: "object",
+      properties: { q: { type: "string" } },
+      required: ["q"],
+    },
+    staticResult: { output: "RESULT" },
+  },
+  apply_patch: {
+    name: "apply_patch",
+    kind: "custom",
+    description: "Lab inert patch tool",
+    staticResult: { output: "PATCHED" },
+  },
+};
+
+export function listInertToolDefinitions(): InertToolDefinition[] {
+  return Object.values(LAB_TOOLS).map(({ staticResult: _r, ...tool }) => tool);
+}
+
+export function validateInertToolArgs(name: string, args: unknown): void {
+  const tool = LAB_TOOLS[name];
+  if (!tool) throw new Error(`unknown inert tool: ${name}`);
+  if (tool.kind === "function") {
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+      throw new Error("invalid function tool arguments");
+    }
+    const record = args as Record<string, unknown>;
+    if (typeof record.q !== "string") {
+      throw new Error("lookup requires string q");
+    }
+  }
+}
+
+/** Execute an inert lab tool — validate args and return static results only. */
+export function executeInertTool(name: string, args: unknown): InertToolResult {
+  validateInertToolArgs(name, args);
+  const tool = LAB_TOOLS[name];
+  if (!tool) throw new Error(`unknown inert tool: ${name}`);
+  return { ...tool.staticResult };
+}

package/src/lab/live/manifest.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { fixtureDigest } from "../digest";
+import type { CaseAuthority, CaseRecord, FailureClassification, FailureRule } from "../conformance/types";
+import { CL03_LIVE_SUITES, SYNTHETIC_MARKER } from "../conformance/types";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const AUTHORITY_FILE = "024_live_v1_cases.json";
+const RUNTIME_AUTHORITY = join(MODULE_DIR, "..", "conformance", "fixtures", "live-v1-cases.json");
+const REPO_AUTHORITY = join(MODULE_DIR, "..", "..", "..", "devlog", "_plan", "260807_compatibility_lab", AUTHORITY_FILE);
+
+function readAuthority(path: string): CaseAuthority { return JSON.parse(readFileSync(path, "utf8")) as CaseAuthority; }
+
+/** During source-tree execution, fail closed unless the runtime copy is byte-identical to normative 024. */
+export function assertLiveAuthorityMirror(): void {
+  if (!existsSync(REPO_AUTHORITY)) return;
+  const runtimeBytes = readFileSync(RUNTIME_AUTHORITY);
+  const normativeBytes = readFileSync(REPO_AUTHORITY);
+  if (!runtimeBytes.equals(normativeBytes)) throw new Error("harness_failure: live authority runtime copy drift");
+}
+
+export function loadLiveCaseAuthority(): CaseAuthority {
+  assertLiveAuthorityMirror();
+  const raw = readAuthority(RUNTIME_AUTHORITY);
+  validateLiveAuthority(raw);
+  return raw;
+}
+
+export function discoverLiveScenarios(authority: CaseAuthority, suites: readonly string[] = CL03_LIVE_SUITES): CaseRecord[] {
+  return authority.cases.filter((row) => suites.includes(row.suite));
+}
+
+export function expandLiveScenario(caseRecord: CaseRecord, authority: CaseAuthority): Record<string, unknown> {
+  const defaults = authority.manifestDefaults;
+  const fixtures = caseRecord.initiatingRequest ? [fixtureRef(caseRecord.initiatingRequest, authority), fixtureRef(caseRecord.fixture, authority)] : [fixtureRef(caseRecord.fixture, authority)];
+  return {
+    schemaVersion: authority.schemaVersion, id: caseRecord.id, version: defaults.version,
+    suite: { id: caseRecord.suite, version: defaults.suiteVersion, evidenceLayer: defaults.evidenceLayer },
+    evidenceLayer: defaults.evidenceLayer, capability: caseRecord.capability,
+    verificationRole: caseRecord.verificationRole ?? defaults.verificationRole, requirements: caseRecord.requirements,
+    fixtures, executionLimits: defaults.executionLimits, executionMode: defaults.executionMode, assertions: caseRecord.assertions,
+    ...(caseRecord.expectedFailure ? { expectedFailure: caseRecord.expectedFailure } : {}),
+    failureRules: expandLiveFailureRules(caseRecord, authority), artifactPolicy: defaults.artifactPolicy, freshness: defaults.freshness,
+  };
+}
+
+function fixtureRef(fixture: CaseRecord["fixture"], authority: CaseAuthority): Record<string, unknown> {
+  const bytes = new TextEncoder().encode(fixture.bytesUtf8);
+  return { id: fixture.id, role: fixture.role, mediaType: fixture.mediaType, digest: fixture.digest, byteLength: bytes.byteLength,
+    syntheticMarker: SYNTHETIC_MARKER, provenance: { kind: "lab_authored", authority: AUTHORITY_FILE, sourceCommit: authority.sourceCommit } };
+}
+
+function expandLiveFailureRules(caseRecord: CaseRecord, authority: CaseAuthority): FailureRule[] {
+  const setName = authority.manifestDefaults.failureRuleSet;
+  const ruleSet = authority.failureRuleSets[setName];
+  if (!Array.isArray(ruleSet)) throw new Error(`harness_failure: contract_integrity unknown failureRuleSet ${setName}`);
+  const base = [...ruleSet];
+  if (!caseRecord.expectedFailure) return base;
+  const template = authority.expectedFailureRuleTemplate;
+  const controlRule: FailureRule = { id: template.id, match: [...template.match], classification: caseRecord.expectedFailure.expectedClass as FailureClassification,
+    secondaryCode: caseRecord.expectedFailure.expectedCode, verdictEffect: caseRecord.expectedFailure.onMatch === "unsupported" ? "unsupported" : "none",
+    retry: template.retry, expected: template.expected };
+  const idx = base.findIndex((row) => row.id === "required-assertion");
+  if (idx >= 0) base.splice(idx, 0, controlRule); else base.push(controlRule);
+  return base;
+}
+
+function validateLiveAuthority(authority: CaseAuthority): void {
+  if (authority.schemaVersion !== 1 || authority.manifestDefaults.evidenceLayer !== "live_route_compatibility") throw new Error("invalid live authority");
+  if (!authority.sourceCommit || !Array.isArray(authority.cases) || authority.cases.length !== 10) throw new Error("invalid live authority case set");
+  const ids = new Set<string>();
+  for (const caseRecord of authority.cases) {
+    if (ids.has(caseRecord.id)) throw new Error(`duplicate live scenario ${caseRecord.id}`);
+    ids.add(caseRecord.id);
+    if (!caseRecord.id.split(".").includes("live")) throw new Error(`non-live scenario in CL-03 authority: ${caseRecord.id}`);
+    const bytes = new TextEncoder().encode(caseRecord.fixture.bytesUtf8);
+    if (fixtureDigest(bytes) !== caseRecord.fixture.digest) throw new Error(`${caseRecord.id}: fixture digest mismatch`);
+    if (caseRecord.initiatingRequest) {
+      const initBytes = new TextEncoder().encode(caseRecord.initiatingRequest.bytesUtf8);
+      if (fixtureDigest(initBytes) !== caseRecord.initiatingRequest.digest) throw new Error(`${caseRecord.id}: initiatingRequest digest mismatch`);
+    }
+    expandLiveScenario(caseRecord, authority);
+  }
+}

package/src/lab/live/mcp-loopback.ts

@@ -0,0 +1,57 @@
+export interface McpStubTool {
+  namespace: string;
+  name: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface McpStubCall {
+  namespace: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface McpStubResult {
+  content: Array<{ type: "text"; text: string }>;
+}
+
+const tools = new Map<string, McpStubTool>();
+const invocations: McpStubCall[] = [];
+
+function toolKey(namespace: string, name: string): string {
+  return `${namespace}::${name}`;
+}
+
+/** Register a lab-owned MCP stub tool (in-memory only). */
+export function registerMcpStubTool(tool: McpStubTool): void {
+  tools.set(toolKey(tool.namespace, tool.name), { ...tool });
+}
+
+export function clearMcpStub(): void {
+  tools.clear();
+  invocations.length = 0;
+}
+
+export function listMcpStubTools(): McpStubTool[] {
+  return [...tools.values()];
+}
+
+/** Invoke the in-memory MCP stub with fixed pure results. */
+export function invokeMcpStub(
+  namespace: string,
+  name: string,
+  args: Record<string, unknown>,
+  result: McpStubResult,
+): McpStubResult {
+  const key = toolKey(namespace, name);
+  if (!tools.has(key)) throw new Error(`MCP stub tool not registered: ${namespace}/${name}`);
+  invocations.push({ namespace, name, arguments: { ...args } });
+  return result;
+}
+
+export function mcpStubInvocations(): readonly McpStubCall[] {
+  return invocations;
+}
+
+export function wireName(namespace: string, name: string): string {
+  return `mcp__${namespace}__${name}`;
+}

package/src/lab/live/runner.ts

@@ -0,0 +1,19 @@
+import { CL03_LIVE_SUITES } from "../conformance/types";
+import { isLiveCaseApplicableToRoute, runLiveScenario, type LiveExecutorOptions } from "./executor";
+import { discoverLiveScenarios, loadLiveCaseAuthority } from "./manifest";
+import type { LabRouteContext, LiveScenarioRunResult } from "./types";
+
+export interface LiveRunSummary { total: number; passed: number; failed: number; results: LiveScenarioRunResult[] }
+
+export async function runLiveSuite(routeContext: LabRouteContext, suites: readonly string[] = CL03_LIVE_SUITES, opts: LiveExecutorOptions = {}): Promise<LiveRunSummary> {
+  const authority = loadLiveCaseAuthority();
+  const scenarios = discoverLiveScenarios(authority, suites).filter((scenario) => isLiveCaseApplicableToRoute(scenario, routeContext));
+  const results: LiveScenarioRunResult[] = [];
+  for (const scenario of scenarios) results.push(await runLiveScenario(scenario, routeContext, opts));
+  const passed = results.filter((row) => row.passed).length;
+  return { total: results.length, passed, failed: results.length - passed, results };
+}
+
+export function listLiveScenarioIds(suites: readonly string[] = CL03_LIVE_SUITES): string[] {
+  return discoverLiveScenarios(loadLiveCaseAuthority(), suites).map((scenario) => scenario.id);
+}

package/src/lab/live/sandbox.ts

@@ -0,0 +1,61 @@
+import type { LiveRunConfig } from "./types";
+
+const PROXY_ENV_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy"] as const;
+const ALLOWED_ENV = { TZ: "UTC", NO_COLOR: "1" } as const;
+
+export class LabSandboxError extends Error {
+  override readonly name = "LabSandboxError";
+  constructor(message: string, readonly code: string) { super(message); }
+}
+
+export function rejectProxyEnvironment(env: NodeJS.ProcessEnv = process.env): void {
+  for (const name of PROXY_ENV_VARS) {
+    const value = env[name];
+    if (value !== undefined && value !== "") throw new LabSandboxError(`proxy environment variable ${name} is forbidden`, "harness_failure");
+  }
+}
+
+export function labSandboxEnvironment(): Readonly<Record<string, string>> { return Object.freeze({ ...ALLOWED_ENV }); }
+
+export interface SandboxResourceState {
+  requests: number;
+  inputBytes: number;
+  outputBytes: number;
+  outputTokens: number;
+  toolCalls: number;
+  artifacts: number;
+  artifactBytes: number;
+  childProcesses: number;
+}
+
+export function createSandboxResourceState(): SandboxResourceState {
+  return { requests: 0, inputBytes: 0, outputBytes: 0, outputTokens: 0, toolCalls: 0, artifacts: 0, artifactBytes: 0, childProcesses: 0 };
+}
+
+/**
+ * Counter-based ceilings enforce the resources observable in this process. The hard resident-memory
+ * boundary is NOT inferred from the hosting Bun test/server process RSS; a trusted exact-route
+ * executor must attest/enforce that isolated boundary before its result is evidence-eligible.
+ */
+export function enforceSandboxLimits(state: SandboxResourceState, limits: LiveRunConfig, delta: Partial<SandboxResourceState> = {}): void {
+  const next: SandboxResourceState = {
+    requests: state.requests + (delta.requests ?? 0), inputBytes: state.inputBytes + (delta.inputBytes ?? 0),
+    outputBytes: state.outputBytes + (delta.outputBytes ?? 0), outputTokens: state.outputTokens + (delta.outputTokens ?? 0),
+    toolCalls: state.toolCalls + (delta.toolCalls ?? 0), artifacts: state.artifacts + (delta.artifacts ?? 0),
+    artifactBytes: state.artifactBytes + (delta.artifactBytes ?? 0), childProcesses: state.childProcesses + (delta.childProcesses ?? 0),
+  };
+  if (next.childProcesses > limits.maxChildProcesses) throw new LabSandboxError("child process limit exceeded", "child_process_limit");
+  if (next.requests > limits.maxRequests) throw new LabSandboxError("request limit exceeded", "request_limit");
+  if (next.inputBytes > limits.maxInputBytes) throw new LabSandboxError("input byte limit exceeded", "input_byte_limit");
+  if (next.outputBytes > limits.maxOutputBytes) throw new LabSandboxError("output byte limit exceeded", "output_byte_limit");
+  if (next.outputTokens > limits.maxOutputTokens) throw new LabSandboxError("output token limit exceeded", "output_token_limit");
+  if (next.toolCalls > limits.maxToolCalls) throw new LabSandboxError("tool call limit exceeded", "tool_call_limit");
+  if (next.artifacts > limits.maxArtifacts) throw new LabSandboxError("artifact limit exceeded", "artifact_byte_limit");
+  if (next.artifactBytes > limits.aggregateArtifactBytes) throw new LabSandboxError("aggregate artifact limit exceeded", "artifact_byte_limit");
+  Object.assign(state, next);
+}
+
+export function prepareLiveSandbox(env: NodeJS.ProcessEnv = process.env): Readonly<Record<string, string>> {
+  rejectProxyEnvironment(env);
+  return labSandboxEnvironment();
+}

package/src/lab/live/suite-manifest.ts

@@ -0,0 +1,41 @@
+import { scenarioManifestDigest, suiteManifestDigest } from "../digest";
+import type { CaseAuthority, CaseRecord, VerificationRole } from "../conformance/types";
+import { expandLiveScenario } from "./manifest";
+
+export interface LiveSuiteScenarioRefV1 { id: string; version: string; role: VerificationRole; manifestDigest: string }
+export interface LiveSuiteManifestV1 {
+  schemaVersion: 1; id: string; version: string; evidenceLayer: string; capability: string;
+  assertionDslVersion: string; evidenceSchemaVersion: string; freshness: { maxAgeMs: number | null };
+  contradictionRule: string; scenarios: LiveSuiteScenarioRefV1[]; verificationRule: string;
+}
+
+function casesForSuiteManifest(suiteId: string, authority: CaseAuthority): { own: CaseRecord[]; referenced: CaseRecord[] } {
+  const own = authority.cases.filter((row) => row.suite === suiteId);
+  if (own.length === 0) throw new Error(`unknown live suite ${suiteId}`);
+  if (suiteId !== "codex-core") return { own, referenced: own };
+  const prerequisite = authority.cases.find((row) => row.id === "responses-core.live.basic-turn");
+  if (!prerequisite) throw new Error("harness_failure: codex live prerequisite missing");
+  return { own, referenced: [...own, prerequisite] };
+}
+
+export function expandLiveSuiteManifest(suiteId: string, authority: CaseAuthority): LiveSuiteManifestV1 {
+  const { own, referenced } = casesForSuiteManifest(suiteId, authority);
+  const defaults = authority.manifestDefaults;
+  const scenarios = referenced.map((caseRecord) => ({
+    id: caseRecord.id, version: String(defaults.version), role: caseRecord.verificationRole ?? defaults.verificationRole,
+    manifestDigest: scenarioManifestDigest(expandLiveScenario(caseRecord, authority)),
+  })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  return {
+    schemaVersion: 1, id: suiteId, version: String(defaults.suiteVersion), evidenceLayer: defaults.evidenceLayer,
+    capability: own[0]!.capability, assertionDslVersion: authority.assertionDslVersion, evidenceSchemaVersion: authority.evidenceSchemaVersion,
+    freshness: defaults.freshness ?? { maxAgeMs: null }, contradictionRule: "newest-required-observation-v1", scenarios,
+    verificationRule: "all-applicable-required-pass-v1",
+  };
+}
+
+export function liveSuiteManifestObjectForCase(caseRecord: CaseRecord, authority: CaseAuthority): Record<string, unknown> {
+  return expandLiveSuiteManifest(caseRecord.suite, authority) as unknown as Record<string, unknown>;
+}
+export function liveSuiteManifestDigestForCase(caseRecord: CaseRecord, authority: CaseAuthority): string {
+  return suiteManifestDigest(expandLiveSuiteManifest(caseRecord.suite, authority) as unknown as Record<string, unknown>);
+}