{startupHealth ? (
-
+
+
) : (
diff --git a/gui/src/pages/dashboard-overview-sections.tsx b/gui/src/pages/dashboard-overview-sections.tsx
index f62403a88..61ac28f8b 100644
--- a/gui/src/pages/dashboard-overview-sections.tsx
+++ b/gui/src/pages/dashboard-overview-sections.tsx
@@ -1,11 +1,10 @@
import { useEffect, useRef, useState } from "react";
import { IconAlert, IconCheck, IconInfo, IconRefresh, IconX } from "../icons";
import { Trans } from "../i18n/provider";
-import { visionReasoningLabel } from "../i18n/vision-reasoning-labels";
import { Select } from "../ui";
import { formatNamespacedModelId } from "../provider-icons";
import { navigateHash } from "../hash-routing";
-import { clampVisionReasoningToLadder, EFFORT_CAP_LEVELS, requireJson, shadowCallModelOptions, sidecarBackendForModel, updateJobLabel, visionReasoningLadder, visionReasoningOptionsFor, visionReasoningPatch } from "./dashboard-shared";
+import { clampVisionReasoningToLadder, EFFORT_CAP_LEVELS, requireJson, shadowCallModelOptions, sidecarBackendForModel, updateJobLabel, visionReasoningLadder, visionReasoningOptionsFor, visionReasoningPatch, visionSidecarBackendForModel } from "./dashboard-shared";
import { shadowSourceModelBadge } from "./shadow-call-source";
import type { useDashboardData } from "./use-dashboard-data";
@@ -239,8 +238,8 @@ export function DashboardMaintenancePanel({ d }: { d: Dash }) {
export function DashboardSidecarPanels({ d }: { d: Dash }) {
const {
- locale, t, settings, settingsSaving, toggleCodexAutoStart,
- sidecar, sidecarSaving, sidecarModels, models, saveSidecar,
+ t, settings, settingsSaving, toggleCodexAutoStart,
+ sidecar, sidecarSaving, sidecarModels, visionModels, models, saveSidecar,
shadowCall, shadowCallSaving, shadowCallHelpTriggerRef, shadowCallHelpOpen, setShadowCallHelpOpen, saveShadowCall,
} = d;
const visionModel = sidecar?.vision.model ?? "gpt-5.4-mini";
@@ -270,9 +269,14 @@ export function DashboardSidecarPanels({ d }: { d: Dash }) {
-
-
+ {/* Both sidecar cards wear the DashboardInjectionPanel shell: the PANEL is
+ the flex row, copy left, controls right. */}
+
+
{t("dash.webSearchSidecar")}
+
{t("dash.webSearchSidecarHint")}
+
+
-
{t("dash.webSearchSidecarHint")}
-
-
+
+
{t("dash.visionSidecar")}
-
-
+
{t("dash.visionSidecarHint")}
+
+
+
-
{t("dash.visionSidecarHint")}
diff --git a/gui/src/pages/dashboard-shared.ts b/gui/src/pages/dashboard-shared.ts
index db08250e7..fe906724b 100644
--- a/gui/src/pages/dashboard-shared.ts
+++ b/gui/src/pages/dashboard-shared.ts
@@ -57,7 +57,15 @@ export interface SettingsData {
export type SidecarBackend = "openai" | "anthropic";
export type VisionReasoning = "low" | "medium" | "high" | "xhigh" | "max";
export interface SidecarSetting { backend?: SidecarBackend; model: string; reasoning?: VisionReasoning }
-export interface SidecarData { webSearch: SidecarSetting; vision: SidecarSetting }
+export interface VisionModelOption { value: string; label: string; backend: SidecarBackend; baseline?: boolean }
+export interface SidecarData {
+ webSearch: SidecarSetting;
+ vision: SidecarSetting;
+ /** Server-computed eligible describers. Optional: an older server omits it and
+ * the client falls back to the legacy provider-name list rather than showing
+ * an empty picker. */
+ visionModels?: VisionModelOption[];
+}
export interface SidecarPatch {
webSearch?: { backend?: SidecarBackend | null; model?: string };
vision?: { backend?: SidecarBackend | null; model?: string; reasoning?: VisionReasoning };
@@ -204,6 +212,36 @@ export function sidecarModelOptions(models: ModelInfo[]) {
return out;
}
+/**
+ * Server list when present, else the legacy openai+anthropic list.
+ *
+ * `undefined` and `[]` mean different things and must not be collapsed. A server that
+ * predates this field sends no key at all, and falling back to the provider-name list is
+ * the documented degrade path for it. A current server that sends `[]` has computed that
+ * nothing is eligible, and repopulating the picker from `/api/models` would put back
+ * exactly the text-only rows this feature exists to remove.
+ *
+ * `currentBackend` is the backend already persisted for `current`. It travels with the
+ * grandfathered entry because the legacy fallback path has no server backend to read and
+ * would otherwise infer one from `/api/models`, where anything not literally provided by
+ * "anthropic" reads as OpenAI — silently rewriting a working Anthropic describer on the
+ * next save. What is already stored is better evidence than a guess.
+ */
+export function visionModelOptions(
+ serverOptions: VisionModelOption[] | undefined,
+ models: ModelInfo[],
+ current: string | undefined,
+ currentBackend?: SidecarBackend,
+): Array<{ value: string; label: string; backend?: SidecarBackend }> {
+ const options = serverOptions
+ ? serverOptions.map(option => ({ value: option.value, label: option.label, backend: option.backend }))
+ : sidecarModelOptions(models);
+ if (current && !options.some(option => option.value === current)) {
+ options.unshift({ value: current, label: current, ...(currentBackend ? { backend: currentBackend } : {}) });
+ }
+ return options;
+}
+
/** Options for shadow-call replacement models use the proxy's canonical routing id. */
export function shadowCallModelOptions(models: ModelInfo[], current: string | undefined) {
const out = [{ value: "", label: "—" }, ...models.map(model => ({ value: model.namespaced, label: model.namespaced }))];
@@ -215,6 +253,15 @@ export function sidecarBackendForModel(models: ModelInfo[], modelId: string): Si
return models.find(model => model.id === modelId)?.provider === "anthropic" ? "anthropic" : "openai";
}
+/** Server eligibility is authoritative; catalog inference only supports legacy picker entries. */
+export function visionSidecarBackendForModel(
+ models: ModelInfo[],
+ options: Array<{ value: string; backend?: SidecarBackend }>,
+ modelId: string,
+): SidecarBackend {
+ return options.find(option => option.value === modelId)?.backend ?? sidecarBackendForModel(models, modelId);
+}
+
let lastInputWasKeyboard = false;
if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
window.addEventListener("keydown", () => { lastInputWasKeyboard = true; }, { capture: true, passive: true });
diff --git a/gui/src/pages/models-provider-hints.tsx b/gui/src/pages/models-provider-hints.tsx
index 366d25ac2..428066435 100644
--- a/gui/src/pages/models-provider-hints.tsx
+++ b/gui/src/pages/models-provider-hints.tsx
@@ -1,5 +1,6 @@
import { IconInfo } from "../icons";
import { useT } from "../i18n/shared";
+import { navigateHash } from "../hash-routing";
import type { ProviderDiscoverySummary } from "../models-groups";
import { discoveryFailureLabel } from "./models-shared";
@@ -22,7 +23,9 @@ export function EmptyProviderHint({
{failed
? `${discoveryFailureLabel(t, failed)} `
: `${t(liveModels ? "models.emptyDiscovery" : "models.emptyDiscoveryDisabled")} `}
-
{t("models.openProviderSettings")}
+
);
diff --git a/gui/src/pages/use-dashboard-data.ts b/gui/src/pages/use-dashboard-data.ts
index 0264781fa..9c540e769 100644
--- a/gui/src/pages/use-dashboard-data.ts
+++ b/gui/src/pages/use-dashboard-data.ts
@@ -46,6 +46,7 @@ import {
readDashboardSectionFromHash,
requireJson,
sidecarModelOptions,
+ visionModelOptions,
useModalDialog,
} from "./dashboard-shared";
@@ -460,6 +461,10 @@ export function useDashboardData(apiBase: string) {
}
return opts;
}, [models, sidecar]);
+ const visionModels = useMemo(
+ () => visionModelOptions(sidecar?.visionModels, models, sidecar?.vision?.model, sidecar?.vision?.backend),
+ [sidecar?.visionModels, models, sidecar?.vision],
+ );
const saveSidecar = async (patch: SidecarPatch) => {
if (!sidecar || sidecarSaving) return;
@@ -467,6 +472,7 @@ export function useDashboardData(apiBase: string) {
const next = {
webSearch: mergeSidecarSetting(sidecar.webSearch, patch.webSearch),
vision: mergeSidecarSetting(sidecar.vision, patch.vision),
+ ...(sidecar.visionModels ? { visionModels: sidecar.visionModels } : {}),
};
setSidecarSaving(true);
setSidecar(next);
@@ -477,11 +483,19 @@ export function useDashboardData(apiBase: string) {
body: JSON.stringify(patch),
});
const data = await requireJson
(res, "save failed");
- setSidecar({ webSearch: data.webSearch, vision: data.vision });
+ setSidecar({
+ webSearch: data.webSearch,
+ vision: data.vision,
+ ...(data.visionModels ? { visionModels: data.visionModels } : {}),
+ });
const prev = readSessionListCache(controlsCacheKey(apiBase)) ?? {};
writeSessionListCache(controlsCacheKey(apiBase), {
...prev,
- sidecar: { webSearch: data.webSearch, vision: data.vision },
+ sidecar: {
+ webSearch: data.webSearch,
+ vision: data.vision,
+ ...(data.visionModels ? { visionModels: data.visionModels } : {}),
+ },
});
} catch {
setSidecar(previous);
@@ -745,7 +759,7 @@ export function useDashboardData(apiBase: string) {
updateCheck, updateError, updateJob, reconnecting, error,
effortCapHelpTriggerRef, updateTriggerRef, maHelpTriggerRef, shadowCallHelpTriggerRef,
effortCapHelpDialogRef, updateDialogRef, maHelpDialogRef, shadowCallHelpDialogRef,
- filteredGroups, sidecarModels,
+ filteredGroups, sidecarModels, visionModels,
saveSidecar, saveShadowCall, switchMaMode, toggleCodexAutoStart, runSync, clearSyncFeedback,
fetchUpdateCheck, closeUpdateDialog, openUpdateDialog, changeUpdateChannel, runUpdate,
};
diff --git a/gui/src/styles-dashboard-workspace.css b/gui/src/styles-dashboard-workspace.css
index a7a990d32..87e3e41c9 100644
--- a/gui/src/styles-dashboard-workspace.css
+++ b/gui/src/styles-dashboard-workspace.css
@@ -76,55 +76,90 @@
display: grid;
grid-template-columns: repeat(auto-fit, minmax(min(100%, 21rem), 1fr));
gap: var(--space-4);
- align-items: start;
+ /* Stretch, not start: the two sidecar cards are a matched pair, and a hint that
+ wraps to a different line count in one of them should not leave the other
+ visibly short. */
+ align-items: stretch;
}
-/* Title + select on one row; hint gets the full card width underneath so
- it stays a stable 2-line block (no clamp / no cutoff when the select grows). */
-.dash-sidecar-card {
- display: flex;
- flex-direction: column;
- gap: 6px;
- min-width: 0;
+/* The effort control holds one short wire value (low…max); it must not inherit
+ the model select's reserved width. Matched by POSITION, not `:last-child`:
+ the web-search card has a single select that is simultaneously first and last,
+ and `:last-child` would shrink its model picker too. `:nth-child(2)` only ever
+ matches a real second control. */
+.dash-sidecar-row-card .dash-delegation-controls .custom-select:nth-child(2) {
+ min-width: 6.5rem;
+ max-width: 9rem;
}
-.dash-sidecar-card__row {
- display: flex;
- align-items: center;
- justify-content: space-between;
- flex-wrap: wrap;
- gap: 12px;
+.dash-sidecar-copy {
min-width: 0;
+ flex: 1 1 auto;
}
-.dash-sidecar-card__row .font-semibold {
- min-width: 0;
+/* The hint must wrap inside its own column, never run under the controls. The
+ copy block is the flex item that yields, so it needs a real basis: without
+ one, `flex-basis: auto` lets its max-content width win the negotiation and the
+ text overlaps the control group in longer locales (ko/ru/ja). */
+.dash-sidecar-row-card .dash-sidecar-copy {
+ flex: 1 1 0;
+ overflow-wrap: anywhere;
+}
+
+/* The copy block yields; the control group holds its intrinsic width. Letting the
+ controls shrink (`0 1 auto`) does NOT wrap them — `.custom-select` keeps its own
+ min-width, so the children simply overflow their shrunken container and slide
+ left under the hint text. Hold the group at content width and make the copy the
+ only thing that gives way; the narrow-viewport case is handled by stacking the
+ whole card below. */
+.dash-sidecar-row-card .dash-delegation-controls {
+ flex: 0 0 auto;
+ flex-wrap: nowrap;
}
-.dash-sidecar-card__row .custom-select {
- /* Reserve baseline space to prevent row reflow, but keep the trigger
- compact instead of forcing a permanently wide fixed width. */
- flex: 0 1 auto;
- width: auto;
- min-width: clamp(10rem, 24vw, 11.5rem);
- max-width: min(100%, 14rem);
+/* The model select carries the long value: give it a floor wide enough to read a
+ real model id, and ellipsize inside rather than growing without bound. */
+.dash-sidecar-row-card .dash-delegation-controls .custom-select:first-child {
+ min-width: 10.5rem;
+ max-width: 14rem;
}
-.dash-sidecar-card__row .select-trigger {
+.dash-sidecar-row-card .dash-delegation-controls .select-trigger {
width: 100%;
max-width: 100%;
justify-content: space-between;
}
-.dash-sidecar-card__row .select-trigger > span {
+.dash-sidecar-row-card .dash-delegation-controls .select-trigger > span {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
min-width: 0;
}
-.dash-sidecar-card .setting-hint {
- margin-top: 0;
+/* Both sidecar panels are delegation-style ROWS. This class carries only the
+ grid-cell min-width; the row layout itself comes from .dash-delegation-summary. */
+.dash-sidecar-row-card {
+ min-width: 0;
+}
+
+/* Below the width where a row can hold copy + two selects, stack instead of
+ overflowing. Measured: the row is clean down to ~320px viewport; under that the
+ controls would push past the panel edge. */
+@media (max-width: 22rem) {
+ .dash-sidecar-row-card {
+ flex-direction: column;
+ align-items: stretch;
+ }
+
+ .dash-sidecar-row-card .dash-delegation-controls {
+ justify-content: flex-start;
+ /* Stacking gives the group the full card width, but the two selects still floor at
+ 10.5rem + 6.5rem, which is wider than the viewport this query targets. Once the
+ controls own their own line, wrapping is free — the reason to hold `nowrap` in the
+ row layout (children sliding under the hint) no longer applies. */
+ flex-wrap: wrap;
+ }
}
/* Available models: search + per-provider accordion with model chips */
diff --git a/gui/src/styles.css b/gui/src/styles.css
index e67105459..0710f7c1e 100644
--- a/gui/src/styles.css
+++ b/gui/src/styles.css
@@ -804,6 +804,8 @@ a.btn, a.btn:hover { text-decoration: none; }
.stat .value.mono { font-family: var(--font-code); font-size: var(--text-subtitle); }
.startup-health-bar {
+ box-sizing: border-box;
+ width: 100%;
min-height: var(--control-lg);
margin: calc(-1 * var(--space-3)) 0 var(--space-6);
padding: 0 var(--space-3);
@@ -813,10 +815,14 @@ a.btn, a.btn:hover { text-decoration: none; }
min-width: 0;
color: var(--muted);
background: var(--hover);
+ border: none;
border-block: 1px solid var(--border-soft);
text-decoration: none;
+ font: inherit;
font-size: var(--text-control);
line-height: var(--leading-ui);
+ text-align: start;
+ cursor: pointer;
transition: background var(--motion-fast), color var(--motion-fast);
}
.startup-health-bar:hover { background: var(--raised); color: var(--text); }
diff --git a/gui/tests/codex-auth-provider-enable.test.tsx b/gui/tests/codex-auth-provider-enable.test.tsx
index bf482c0b6..216b21edf 100644
--- a/gui/tests/codex-auth-provider-enable.test.tsx
+++ b/gui/tests/codex-auth-provider-enable.test.tsx
@@ -59,7 +59,8 @@ test("noncanonical disabled OpenAI rows do not offer built-in recovery", () => {
);
expect(html).toContain("The built-in OpenAI provider is not configured.");
- expect(html).toContain('href="#providers"');
+ expect(html).toContain('class="link-btn"');
+ expect(html).toContain("Open Providers");
expect(html).not.toContain("Enable OpenAI");
expect(html).not.toContain("Your OpenAI accounts are still available");
});
diff --git a/gui/tests/models-empty-provider.test.tsx b/gui/tests/models-empty-provider.test.tsx
index bee7f6ef7..442e96bf1 100644
--- a/gui/tests/models-empty-provider.test.tsx
+++ b/gui/tests/models-empty-provider.test.tsx
@@ -534,7 +534,7 @@ async function withCursorDiscoveryServer(
test("empty live-discovery provider renders endpoint guidance and a settings link", () => {
const html = renderHint(true, { status: "ok" });
expect(html).toContain("No models were discovered");
- expect(html).toContain('href="#providers"');
+ expect(html).toContain('class="link-btn"');
expect(html).toContain("Open provider settings");
expect(html).not.toContain("Discovery failed");
});
@@ -545,7 +545,7 @@ test("failed HTTP discovery renders an amber status badge and reason", () => {
expect(html).toContain("HTTP 401");
expect(html).toContain('class="badge badge-amber"');
expect(html).toContain('role="status"');
- expect(html).toContain('href="#providers"');
+ expect(html).toContain('class="link-btn"');
});
test("failed discovery renders each server-owned reason without provider detail", () => {
@@ -584,7 +584,7 @@ test("HTTP 401 discovery exposes HTTP status and badge", async () => {
const html = renderHint(true, discovery);
expect(html).toContain("Discovery failed");
expect(html).toContain("HTTP 401");
- expect(html).toContain('href="#providers"');
+ expect(html).toContain('class="link-btn"');
});
test("destination-blocked discovery exposes blocked status and badge", async () => {
@@ -614,7 +614,7 @@ test("destination-blocked discovery exposes blocked status and badge", async ()
const html = renderHint(true, discovery);
expect(html).toContain("Discovery failed");
expect(html).toContain("blocked by the destination policy");
- expect(html).toContain('href="#providers"');
+ expect(html).toContain('class="link-btn"');
});
test("invalid JSON or malformed model data exposes invalid-response status and badge", async () => {
diff --git a/gui/tests/startup-usage-loading-race.test.tsx b/gui/tests/startup-usage-loading-race.test.tsx
index f465af128..bf90d2487 100644
--- a/gui/tests/startup-usage-loading-race.test.tsx
+++ b/gui/tests/startup-usage-loading-race.test.tsx
@@ -133,15 +133,17 @@ test("an aborted Startup fetch must not clear loading while its replacement is i
await settle();
expect(container.textContent).toContain("Checking startup protection");
- const refresh = container.querySelector("button.btn");
- expect(refresh?.disabled).toBe(true);
+ const refresh = Array.from(container.querySelectorAll("button.btn"))
+ .find(button => (button.textContent ?? "").includes("Refresh"));
+ expect(refresh).toBeTruthy();
+ expect(refresh!.disabled).toBe(true);
await act(async () => {
gates[1]!.resolve(FRESH);
await Promise.resolve();
});
await waitFor(() => !(container.textContent ?? "").includes("Checking startup protection"));
- expect(refresh?.disabled).toBe(false);
+ expect(refresh!.disabled).toBe(false);
await act(async () => { root.unmount(); });
container.remove();
diff --git a/gui/tests/vision-model-options.test.ts b/gui/tests/vision-model-options.test.ts
new file mode 100644
index 000000000..f7cface9c
--- /dev/null
+++ b/gui/tests/vision-model-options.test.ts
@@ -0,0 +1,97 @@
+import { expect, test } from "bun:test";
+import {
+ sidecarBackendForModel,
+ visionModelOptions,
+ visionSidecarBackendForModel,
+ type ModelInfo,
+ type VisionModelOption,
+} from "../src/pages/dashboard-shared";
+
+const models: ModelInfo[] = [
+ { id: "gpt-5.6-luna", provider: "openai", namespaced: "gpt-5.6-luna" },
+ { id: "o3-mini", provider: "openai", namespaced: "o3-mini" },
+ { id: "claude-haiku-4-5", provider: "anthropic", namespaced: "anthropic/claude-haiku-4-5" },
+ { id: "grok-4.5", provider: "xai", namespaced: "xai/grok-4.5" },
+];
+
+const serverOptions: VisionModelOption[] = [
+ { value: "gpt-5.6-luna", label: "gpt-5.6-luna", backend: "openai", baseline: true },
+ { value: "claude-haiku-4-5", label: "claude-haiku-4-5", backend: "anthropic", baseline: true },
+];
+
+test("the server list wins over the legacy provider-name list", () => {
+ const options = visionModelOptions(serverOptions, models, "gpt-5.6-luna");
+ expect(options.map(option => option.value)).toEqual(["gpt-5.6-luna", "claude-haiku-4-5"]);
+ // o3-mini is an openai row, so the legacy list would have offered it.
+ expect(options.some(option => option.value === "o3-mini")).toBe(false);
+});
+
+test("an absent server list falls back instead of emptying the picker", () => {
+ // A server that predates this field must not leave the user with no options at
+ // all; the legacy openai+anthropic list is the documented degrade path.
+ const options = visionModelOptions(undefined, models, undefined);
+ expect(options.map(option => option.value)).toEqual(["gpt-5.6-luna", "o3-mini", "claude-haiku-4-5"]);
+});
+
+test("an empty server list is authoritative and does not resurrect text-only rows", () => {
+ // A current server that computed no eligible describer is not a legacy server. Falling
+ // back here would re-offer o3-mini, the exact row the filter exists to remove.
+ const options = visionModelOptions([], models, undefined);
+ expect(options).toEqual([]);
+});
+
+test("the configured model stays selectable, exactly once", () => {
+ // Grandfathering a model the server no longer lists keeps the picker honest
+ // about what is actually configured.
+ const unlisted = visionModelOptions(serverOptions, models, "custom-vision");
+ expect(unlisted[0]?.value).toBe("custom-vision");
+ expect(unlisted.filter(option => option.value === "custom-vision")).toHaveLength(1);
+
+ const alreadyListed = visionModelOptions(serverOptions, models, "claude-haiku-4-5");
+ expect(alreadyListed.filter(option => option.value === "claude-haiku-4-5")).toHaveLength(1);
+ expect(alreadyListed.map(option => option.value)).toEqual(["gpt-5.6-luna", "claude-haiku-4-5"]);
+});
+
+test("the returned array is fresh, so unshift cannot mutate shared state", () => {
+ const first = visionModelOptions(serverOptions, models, "custom-vision");
+ const second = visionModelOptions(serverOptions, models, "another-custom");
+ expect(first.some(option => option.value === "another-custom")).toBe(false);
+ expect(second.some(option => option.value === "custom-vision")).toBe(false);
+ expect(serverOptions).toHaveLength(2);
+});
+
+test("a server-supplied vision backend wins when the catalog cannot identify its provider", () => {
+ const model = "claude-haiku-4-5";
+ const options = visionModelOptions([
+ // A configured Anthropic adapter need not be named "anthropic", and this
+ // model can be absent from the independently refreshed /api/models catalog.
+ { value: model, label: model, backend: "anthropic" },
+ ], [], undefined);
+
+ // This documents the old save-path result: catalog inference alone defaults
+ // to OpenAI when there is no matching model row.
+ expect(sidecarBackendForModel([], model)).toBe("openai");
+ expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
+});
+
+test("an older server with no option list cannot rewrite the persisted anthropic backend", () => {
+ const model = "claude-grandfathered";
+ // The compatibility path: a server that predates visionModels sends nothing, and the
+ // configured model is absent from the catalog. Without the persisted backend travelling
+ // with the grandfathered entry, the next save would silently downgrade it to openai.
+ const options = visionModelOptions(undefined, [], model, "anthropic");
+
+ expect(options[0]).toMatchObject({ value: model, backend: "anthropic" });
+ expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
+ expect(sidecarBackendForModel([], model)).toBe("openai");
+});
+
+test("an authoritative empty list still keeps the configured model and its backend", () => {
+ const model = "claude-grandfathered";
+ const options = visionModelOptions([], [], model, "anthropic");
+
+ // Nothing is eligible, but the user's own configured model stays visible and keeps the
+ // backend it was saved with, so opening the picker cannot silently rewrite it.
+ expect(options.map(option => option.value)).toEqual([model]);
+ expect(visionSidecarBackendForModel([], options, model)).toBe("anthropic");
+});
diff --git a/src/adapters/command-code.ts b/src/adapters/command-code.ts
index ce20edf33..8f504fde1 100644
--- a/src/adapters/command-code.ts
+++ b/src/adapters/command-code.ts
@@ -21,6 +21,10 @@ const COMMAND_CODE_MODEL_ALIASES: Readonly> = {
"glm-5.2": "zai-org/GLM-5.2",
};
+function canonicalCommandCodeModelId(modelId: string): string {
+ return Object.hasOwn(COMMAND_CODE_MODEL_ALIASES, modelId) ? COMMAND_CODE_MODEL_ALIASES[modelId]! : modelId;
+}
+
/** Flatten tool-result content for the text-only wire output, keeping an `[image]` marker per image part in content order. */
function toolResultText(content: string | OcxContentPart[]): string {
if (typeof content === "string") return content;
@@ -318,7 +322,7 @@ function supportedCommandCodeEffort(provider: OcxProviderConfig, modelId: string
// Compatibility ids (deepseek-v4-flash / glm-5.2) must resolve to their canonical
// Command Code id before the effort lookup, or legacy requests silently lose the
// reasoning effort because the official table is keyed by the canonical ids.
- const canonicalId = COMMAND_CODE_MODEL_ALIASES[modelId] ?? modelId;
+ const canonicalId = canonicalCommandCodeModelId(modelId);
const supported = commandCodeReasoningEfforts(canonicalId) ?? configuredReasoningEfforts(provider, canonicalId);
if (!supported) return undefined;
// Command Code's official profiles describe xhigh and ultra as the CLI labels that map to
@@ -347,7 +351,7 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
config: await commandCodeConfig(cwd), memory: "", taste: null, skills: null,
permissionMode: "standard", mode: "agent",
params: {
- model: COMMAND_CODE_MODEL_ALIASES[parsed.modelId] ?? parsed.modelId,
+ model: canonicalCommandCodeModelId(parsed.modelId),
messages: wireMessages(parsed.context.messages),
tools: wireTools(tools),
system,
diff --git a/src/adapters/google.ts b/src/adapters/google.ts
index 91f8bc099..15e418a62 100644
--- a/src/adapters/google.ts
+++ b/src/adapters/google.ts
@@ -54,8 +54,8 @@ function resolveVertexApiKey(optKey?: string): string | undefined {
/** Prefer Codex's stable opaque thread key; retain the existing deterministic fallback for clients
* that omit it. The replay store hashes this value and never retains the raw session identifier. */
function vertexReplaySessionId(parsed: OcxParsedRequest): string {
- const promptCacheKey = parsed.options.promptCacheKey?.trim();
- return promptCacheKey || antigravitySessionId(parsed);
+ const threadId = parsed._clientThreadId?.trim();
+ return threadId || antigravitySessionId(parsed);
}
/**
@@ -577,15 +577,32 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
pendingUsage = usageFromGemini(usageMeta);
sawTerminalSignal = true;
}
- const candidates = root.candidates as { content?: { parts?: unknown[] }; finishReason?: string }[] | undefined;
- if (!candidates?.length) return "continue";
+ const rawCandidates = root.candidates;
+ if (rawCandidates === undefined) return "continue";
+ if (!Array.isArray(rawCandidates)) {
+ yield { type: "error", message: "google response contained invalid candidates" };
+ return "terminate";
+ }
+ if (rawCandidates.length === 0) return "continue";
+ const rawCandidate = rawCandidates[0];
+ if (rawCandidate === null || typeof rawCandidate !== "object" || Array.isArray(rawCandidate)) {
+ // Unlike a root `data: null` keepalive, this is a claimed response candidate. Treat it
+ // as terminal protocol corruption so the turn cannot complete after silently losing
+ // a candidate or tool call (#1325).
+ yield { type: "error", message: "google response contained invalid candidates" };
+ return "terminate";
+ }
+ const candidate = rawCandidate as {
+ content?: { parts?: unknown[] };
+ finishReason?: string;
+ };
- if (typeof candidates[0].finishReason === "string" && candidates[0].finishReason) {
- lastFinishReason = candidates[0].finishReason;
+ if (typeof candidate.finishReason === "string" && candidate.finishReason) {
+ lastFinishReason = candidate.finishReason;
sawTerminalSignal = true;
}
- const parts = candidates[0].content?.parts as { text?: string; functionCall?: { name: string; args: unknown } }[] | undefined;
+ const parts = candidate.content?.parts as { text?: string; functionCall?: { name: string; args: unknown } }[] | undefined;
// Record Gemini thought signatures for the next stateless tool-result turn. Vertex and
// Antigravity use separate model namespaces so opaque provider state cannot cross routes.
const replayModel = provider.googleMode === "cloud-code-assist" ? antigravityModel : vertexReplayModel;
diff --git a/src/adapters/openai-chat.ts b/src/adapters/openai-chat.ts
index 45f21b7bc..807f81514 100644
--- a/src/adapters/openai-chat.ts
+++ b/src/adapters/openai-chat.ts
@@ -48,14 +48,12 @@ function extractErrorDetail(parsed: unknown): string | undefined {
if (typeof parsed === "string") return parsed.trim() || undefined;
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
const obj = parsed as Record;
- // OpenAI shape: { error: { message } } or { error: "..." }
const err = obj.error;
if (typeof err === "string" && err.trim()) return err.trim();
if (err !== null && typeof err === "object" && !Array.isArray(err)) {
const msg = (err as Record).message;
if (typeof msg === "string" && msg.trim()) return msg.trim();
}
- // FastAPI/pydantic shape (NVIDIA NIM): { detail: "..." } or { detail: [{ msg, loc }, ...] }
const det = obj.detail;
if (typeof det === "string" && det.trim()) return det.trim();
if (Array.isArray(det)) {
@@ -66,15 +64,11 @@ function extractErrorDetail(parsed: unknown): string | undefined {
.filter(m => m.length > 0);
if (msgs.length > 0) return msgs.join("; ");
}
- // Generic fallbacks: { message } / RFC7807 { title }
if (typeof obj.message === "string" && obj.message.trim()) return obj.message.trim();
if (typeof obj.title === "string" && obj.title.trim()) return obj.title.trim();
return undefined;
}
-// ClinePass live responses observed 2026-08-02 wrap non-stream Chat Completions in
-// `{ success, error, data }`; its public Chat Completions docs do not currently describe that
-// envelope. Keep ordinary OpenAI-shaped responses on the direct path.
function unwrapChatCompletionPayload(json: Record): Record {
if ((json.error !== undefined && json.error !== null) || Array.isArray(json.choices)) return json;
const data = json.data;
@@ -169,6 +163,18 @@ function invalidChoicesEvent(usage?: OcxUsage): Extract {
+ return {
+ type: "error",
+ message: "upstream response contained invalid tool calls",
+ ...(usage !== undefined ? { usage } : {}),
+ };
+}
+
+function isRecord(value: unknown): value is Record {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
function developerSystemText(message: OcxMessage): string | undefined {
if (message.role !== "developer") return undefined;
if (typeof message.content === "string") return message.content;
@@ -176,18 +182,34 @@ function developerSystemText(message: OcxMessage): string | undefined {
return message.content.map(part => (part as OcxTextContent).text).join("");
}
+function isNativeOpenAIChatTarget(provider: OcxProviderConfig): boolean {
+ try {
+ return new URL(provider.baseUrl).hostname === "api.openai.com";
+ } catch {
+ return false;
+ }
+}
+
/**
* Chat-completions image_url parts for images carried inside a tool result (issue #888). role:"tool"
* content is text-only on every chat provider, so these ride in a follow-up user message instead of
* being flattened to the "[image]" marker the model can't actually see. Data URLs and remote https
* URLs are both valid in image_url.url, unlike Gemini inline_data which needs base64.
*/
+function toolResultTextForWire(content: string | OcxContentPart[]): string {
+ if (typeof content === "string") return content;
+ const text = content.filter((p) => p.type === "text").map((p) => (p as OcxTextContent).text).join("");
+ if (text) {
+ const untransportableImages = content.filter((p) => p.type === "image" && !p.imageUrl).length;
+ return `${text}${"[image]".repeat(untransportableImages)}`;
+ }
+ return contentPartsToText(content);
+}
+
function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[] {
if (typeof content === "string") return [];
const parts: unknown[] = [];
for (const p of content) {
- // Skip parts without a usable URL (the tool-output parser accepts the empty file_id shape):
- // a {"url":""} part would fail the whole request where the "[image]" marker degrades safely.
if (p.type !== "image" || !p.imageUrl) continue;
parts.push({ type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } });
}
@@ -197,17 +219,8 @@ function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[]
function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
const out: unknown[] = [];
const { context, options } = parsed;
- // Mirror the bridge's replay-cache scope (issue #950): provider call ids are
- // not globally unique, so reasoning must not cross conversation boundaries.
const replayCacheScope = parsed._clientThreadId ?? "global";
- // 260718 dangling tool_calls hardening (devlog/_plan/260718_dangling_toolcall_hardening):
- // strict chat providers (Kimi/Moonshot) 400 when an assistant tool_call is not answered
- // immediately by role:"tool" messages. Repair order: (1) reattach a real result to its
- // original call (barrier messages are DEFERRED until the open tool round closes),
- // (2) synthesize an explicit unavailable-result only when no real result exists,
- // (3) manufacture an orphan assistant call only when no call occurrence matches at all.
- // Occurrences are kept as an ordered list (never a Map) so duplicated ids survive.
interface PendingToolCall { id: string; name: string }
let pendingToolCalls: PendingToolCall[] = [];
let deferredBarrierMessages: unknown[] = [];
@@ -230,10 +243,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
deferredBarrierMessages = [];
};
- // Tool-result images collected during the open round land in ONE user vision message once the
- // round closes — never inside it, where strict providers (Kimi/Moonshot) 400 on interleaved
- // user messages. Released before deferred barriers so the images stay adjacent to the results
- // they came from (mirrors google.ts sibling inline_data parts and the Kiro carrier images).
const flushToolResultImages = (): void => {
if (pendingToolResultImageParts.length === 0) return;
out.push({
@@ -246,9 +255,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
pendingToolResultImageParts = [];
};
- // Close an unresolved tool round with explicit unavailable-result messages. The wording
- // must not claim interruption, success, failure, or user intent: execution status is
- // UNKNOWN, and for user-input tools this must not read as an answer.
const flushPendingToolCalls = (): void => {
if (pendingToolCalls.length === 0) return;
for (const call of pendingToolCalls) {
@@ -263,28 +269,21 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
releaseDeferredBarriers();
};
+ const nativeOpenAI = isNativeOpenAIChatTarget(provider);
const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
: undefined;
- // Chat templates used by LM Studio, llama.cpp, and other strict OpenAI-compatible
- // backends require every system instruction to precede conversation history. Codex can
- // append developer reminders after user turns, so fold text-only developer messages into
- // the single leading system message instead of emitting role:"system" in place. Developer
- // messages with images cannot be represented as system content and remain user-compatible
- // vision messages at their original position below.
- const developerSystemParts = context.messages
- .map(developerSystemText)
- .filter((part): part is string => part !== undefined && part.length > 0);
+ const developerSystemParts = nativeOpenAI
+ ? []
+ : context.messages
+ .map(developerSystemText)
+ .filter((part): part is string => part !== undefined && part.length > 0);
const systemParts = [
...(context.systemPrompt ?? []),
...developerSystemParts,
...(toolCatalogNudge ? [toolCatalogNudge] : []),
];
if (systemParts.length > 0) {
- // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
- // base_instructions is ignored at request time). Neutralize that one identity line
- // so routed, non-OpenAI models don't misreport themselves as GPT-5 / OpenAI — without
- // leaking the proxy identity into the payload.
const wireModelId = provider.modelSuffixBracketStrip
? stripBracketedModelSuffix(parsed.modelId)
: parsed.modelId;
@@ -298,24 +297,23 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
case "developer": {
const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
const hasImages = parts?.some(p => p.type === "image") ?? false;
- if (msg.role === "developer" && !hasImages) break;
let chatMsg: Record;
- if (typeof msg.content === "string") {
+ if (msg.role === "developer" && !hasImages) {
+ if (!nativeOpenAI) break;
+ const text = typeof msg.content === "string"
+ ? msg.content
+ : parts!.map(p => (p as OcxTextContent).text).join("");
+ chatMsg = { role: "developer", content: text };
+ } else if (typeof msg.content === "string") {
chatMsg = { role: "user", content: msg.content };
+ } else if (!hasImages) {
+ chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
} else {
- if (!hasImages) {
- chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
- } else {
- // Vision: chat-completions content-parts array. Images are only valid on the user role,
- // and the data URL goes straight into image_url.url (never the token-exploding text path).
- const chatParts = parts!.map(p => p.type === "image"
- ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
- : { type: "text", text: (p as OcxTextContent).text });
- chatMsg = { role: "user", content: chatParts };
- }
+ const chatParts = parts!.map(p => p.type === "image"
+ ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
+ : { type: "text", text: (p as OcxTextContent).text });
+ chatMsg = { role: "user", content: chatParts };
}
- // A barrier must not split an open tool round: defer it until the round closes
- // (real result arrives) or the round is synthesized shut.
if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
else out.push(chatMsg);
break;
@@ -326,15 +324,8 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
const thinkingParts = aMsg.content.filter(p => p.type === "thinking") as OcxThinkingContent[];
const toolCalls = aMsg.content.filter(p => p.type === "toolCall") as OcxToolCall[];
const chatMsg: Record = { role: "assistant" };
- if (textParts.length > 0) {
- chatMsg.content = textParts.map(p => p.text).join("");
- }
+ if (textParts.length > 0) chatMsg.content = textParts.map(p => p.text).join("");
let reasoningContent = thinkingParts.map(p => p.thinking).join("");
- // History transformations (compaction, lost assistant turn, resumed
- // threads) can strip the reasoning item while the tool round survives.
- // Re-attach the reasoning the bridge recorded for these call ids so
- // preserveReasoningContentModels providers (DeepSeek thinking mode)
- // never receive a bare tool-call continuation (issue #950).
if (
reasoningContent.length === 0
&& toolCalls.length > 0
@@ -347,16 +338,24 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
// recorded under every call id — join unique texts only.
if (cached.length > 0) {
reasoningContent = [...new Set(cached)].join("\n");
+ } else if (modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)) {
+ // Fallback (extends #950, closes #1193): the replay cache is
+ // bounded (64 entries / 256 KiB / 1 h TTL) and always misses on
+ // long sessions, and some tool rounds carry no recorded reasoning
+ // at all. DeepSeek thinking mode rejects ANY tool_call assistant
+ // message missing reasoning_content with HTTP 400, so inject a
+ // minimal placeholder rather than emit a bare continuation the
+ // upstream will reject. Scoped to requiresReasoningPlaceholderModels
+ // (defaulting to the preserve list): preserve-listed providers with
+ // toggleable thinking (MiniMax low effort) opt out with `[]` so
+ // non-thinking histories are never given a fabricated placeholder.
+ reasoningContent = " ";
}
}
if (reasoningContent.length > 0 && modelInList(provider.preserveReasoningContentModels, parsed.modelId)) {
chatMsg.reasoning_content = reasoningContent;
}
- // Skip empty assistant messages: chat APIs like DeepSeek reject an assistant message
- // with neither content, tool calls, nor a provider-supported reasoning_content field.
if (chatMsg.content === undefined && toolCalls.length === 0 && chatMsg.reasoning_content === undefined) break;
- // A new assistant starts while a previous round is still open: close the previous
- // round synthetically first so its tool_calls are never left dangling.
flushPendingToolCalls();
const wireToolCalls = toolCalls.map(tc => {
let id = tc.id;
@@ -370,8 +369,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
type: "function",
function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) },
}));
- // "" instead of null: strict validators (xAI: "Each message must have at least one
- // content element", langchain#34140) reject content-less assistant history entries.
if (!chatMsg.content) chatMsg.content = emptyAssistantContent(provider);
}
if (chatMsg.reasoning_content !== undefined && chatMsg.content === undefined && chatMsg.tool_calls === undefined) {
@@ -385,12 +382,10 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
let toolCallId = msg.toolCallId;
const matchIdx = toolCallId ? pendingToolCalls.findIndex(c => c.id === toolCallId) : -1;
if (matchIdx >= 0 && toolCallId) {
- // Real result reattached to its original call. Barriers were deferred, so the
- // tool message lands immediately inside the open round.
out.push({
role: "tool",
tool_call_id: toolCallId,
- content: contentPartsToText(msg.content),
+ content: toolResultTextForWire(msg.content),
});
pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
pendingToolCalls.splice(matchIdx, 1);
@@ -400,23 +395,31 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
}
} else {
if (!toolCallId) toolCallId = `call_orphan_${out.length}`;
- // No matching call in the open round. Close any unresolved round first so the
- // synthesized orphan pair never splits it, then keep the historical repair:
- // WS turns can arrive with only tool outputs; chat-completions providers reject a bare
- // role:"tool" message unless an assistant tool_call with the same id immediately precedes it.
flushPendingToolCalls();
const name = safeToolName(msg.toolName);
- // The orphan repair synthesizes an assistant tool call for a result
- // whose assistant turn was lost; carry the recorded reasoning so the
- // replayed round stays valid for thinking-mode providers (#950).
const cachedReasoning =
toolCallId && modelInList(provider.preserveReasoningContentModels, parsed.modelId)
? peekReasoningForCall(toolCallId, replayCacheScope)
: undefined;
+ // Same fallback as the main-assistant path: never emit a bare orphan
+ // tool_call continuation on a thinking-mode provider — inject a
+ // placeholder when the replay cache missed (the bounded cache can
+ // always miss on long sessions), or DeepSeek thinking mode 400s.
+ // Gate on the preserve list too: reasoning_content is only ever
+ // serialized for preserve-listed models, so a requires-only custom
+ // entry must not fabricate it on this path (P2 on #1205).
+ // `||` (not `??`): the cache never stores empty strings, but treat a
+ // falsy hit as a miss so the placeholder still fires.
+ const orphanReasoning =
+ cachedReasoning
+ || (modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+ && modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)
+ ? " "
+ : undefined);
out.push({
role: "assistant",
content: emptyAssistantContent(provider),
- ...(cachedReasoning ? { reasoning_content: cachedReasoning } : {}),
+ ...(orphanReasoning ? { reasoning_content: orphanReasoning } : {}),
tool_calls: [{
id: toolCallId,
type: "function",
@@ -427,7 +430,7 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
out.push({
role: "tool",
tool_call_id: toolCallId,
- content: contentPartsToText(msg.content),
+ content: toolResultTextForWire(msg.content),
});
pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
flushToolResultImages();
@@ -437,8 +440,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
}
}
- // Trailing dangle: a turn interrupted after the assistant requested tools leaves the
- // round open; close it synthetically (then release any deferred barriers in order).
flushPendingToolCalls();
releaseDeferredBarriers();
return out;
@@ -544,11 +545,6 @@ function isXaiSchemaTarget(provider: OcxProviderConfig): boolean {
}
}
-// Volcengine Ark regional endpoints. Ark validates an assistant message's text field as a
-// REQUIRED parameter and treats "" as absent, so a tool-call-only assistant in history 400s with
-// `MissingParameter: input.content.text` (#796). Every other OpenAI-compatible provider accepts
-// "", and xAI actively requires it ("Each message must have at least one content element"), so
-// the two contracts are in direct conflict and this cannot be a global change.
const VOLCENGINE_ARK_HOSTNAMES = new Set([
"ark.cn-beijing.volces.com",
"ark.ap-southeast.volces.com",
@@ -562,35 +558,10 @@ function isVolcengineArkTarget(provider: OcxProviderConfig): boolean {
}
}
-/**
- * Placeholder content for an assistant history entry carrying only tool calls or reasoning.
- *
- * UNVERIFIED HYPOTHESIS for Ark. The reported error names `input.content.text`, a nested path,
- * which suggests Ark wants the structured content form `[{type:"text",text:""}]` rather than a
- * bare string — no string value, `""` or `" "`, exposes a `content.text` path at all. But Ark's
- * published examples only show array content for MULTIMODAL USER input, never for an assistant
- * history entry, so this shape is inferred from the error message and not confirmed by the docs
- * or by a live request. The empty inner text at least adds no tokens either way.
- *
- * Confirm against a real Ark endpoint before relying on this; #796 records what is still missing.
- *
- * Every other provider keeps the bare `""`, which xAI's validator specifically requires ("Each
- * message must have at least one content element"), so this cannot be applied globally.
- */
function emptyAssistantContent(provider: OcxProviderConfig): string | { type: "text"; text: string }[] {
return isVolcengineArkTarget(provider) ? [{ type: "text", text: "" }] : "";
}
-/**
- * Providers like Kimi and DeepSeek reject function parameter schemas whose root
- * `type` is missing or `null` — JSON Schema requires `"object"` at the root of
- * function parameters. Add `type: "object"` at the root while preserving
- * `oneOf`, `$defs`, and every other schema key.
- *
- * This mirrors `normalizeFunctionToolSchema` in openai-responses.ts, which
- * applies the same root-only normalization unconditionally on the responses
- * path. Nested schema content is intentionally left untouched.
- */
function ensureRootObjectType(parameters: unknown): Record {
if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
return { type: "object", properties: {} };
@@ -649,13 +620,13 @@ function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig
if (parameters === undefined) return [];
return [{
- type: "function",
- function: {
- name: namespacedToolName(t.namespace, t.name),
- description: t.description,
- parameters,
- ...(t.strict !== undefined ? { strict: t.strict } : {}),
- },
+ type: "function",
+ function: {
+ name: namespacedToolName(t.namespace, t.name),
+ ...(t.description ? { description: t.description } : {}),
+ parameters,
+ ...(t.strict !== undefined ? { strict: t.strict } : {}),
+ },
}];
});
return formatted.length > 0 ? formatted : undefined;
@@ -678,9 +649,18 @@ function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxPro
});
}
-function toolChoiceToChatFormat(tc: OcxParsedRequest["options"]["toolChoice"], tools: OcxParsedRequest["context"]["tools"]): unknown {
+function toolChoiceToChatFormat(
+ tc: OcxParsedRequest["options"]["toolChoice"],
+ tools: OcxParsedRequest["context"]["tools"],
+ provider: OcxProviderConfig,
+): unknown {
if (!tc) return undefined;
- if (isAllowedToolChoice(tc)) return tc.mode === "required" ? "required" : "auto";
+ if (isAllowedToolChoice(tc)) {
+ if (tc.mode === "required" && tc.allowedTools.length === 1 && isNativeOpenAIChatTarget(provider)) {
+ return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.allowedTools[0]) } };
+ }
+ return tc.mode === "required" ? "required" : "auto";
+ }
if (tc === "auto" || tc === "none" || tc === "required") return tc;
if ("name" in tc) return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.name) } };
return undefined;
@@ -732,7 +712,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
const messages = messagesToChatFormat(parsed, provider);
const tools = toolsToChatFormatForProvider(parsed, provider);
- const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools);
+ const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools, provider);
const body: Record = {
model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(parsed.modelId) : parsed.modelId,
@@ -759,24 +739,41 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+ const nativeOpenAI = isNativeOpenAIChatTarget(provider);
let reasoningLog: AdapterRequest["reasoningLog"];
- // ClinePass live requests observed 2026-08-02 require this gateway-specific object; the
- // public API docs do not currently specify its request shape.
if (!reasoningDisabled && provider.reasoningWireFormat === "gateway-object" && parsed.options.reasoning === "none") {
- body.reasoning = { enabled: false };
- reasoningLog = {
- effectiveEffort: "none",
- wireField: "reasoning.enabled",
- wireValue: false,
- };
- } else if (reasoningEffort !== undefined) {
- if (provider.reasoningWireFormat === "gateway-object") {
- body.reasoning = { enabled: true, effort: reasoningEffort };
+ if (nativeOpenAI) {
+ body.reasoning_effort = "none";
reasoningLog = {
- effectiveEffort: reasoningEffort,
- wireField: "reasoning.effort",
- wireValue: reasoningEffort,
+ effectiveEffort: "none",
+ wireField: "reasoning_effort",
+ wireValue: "none",
+ };
+ } else {
+ body.reasoning = { enabled: false };
+ reasoningLog = {
+ effectiveEffort: "none",
+ wireField: "reasoning.enabled",
+ wireValue: false,
};
+ }
+ } else if (reasoningEffort !== undefined) {
+ if (provider.reasoningWireFormat === "gateway-object") {
+ if (nativeOpenAI) {
+ body.reasoning_effort = reasoningEffort;
+ reasoningLog = {
+ effectiveEffort: reasoningEffort,
+ wireField: "reasoning_effort",
+ wireValue: reasoningEffort,
+ };
+ } else {
+ body.reasoning = { enabled: true, effort: reasoningEffort };
+ reasoningLog = {
+ effectiveEffort: reasoningEffort,
+ wireField: "reasoning.effort",
+ wireValue: reasoningEffort,
+ };
+ }
} else if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
const budget = thinkingBudgetForEffort(parsed, reasoningEffort, maxTokens);
if (budget !== undefined) {
@@ -788,9 +785,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
};
}
} else if (modelInList(provider.thinkingToggleModels, parsed.modelId)) {
- // Vendor thinking-toggle wire: the mapped value is sent as `thinking: {type}` because
- // these models ignore/reject reasoning_effort. Most use enabled/disabled; MiniMax-M3
- // uses adaptive/disabled.
if (reasoningEffort === "enabled" || reasoningEffort === "disabled" || reasoningEffort === "adaptive") {
body.thinking = { type: reasoningEffort };
reasoningLog = {
@@ -814,17 +808,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
if (parsed.options.frequencyPenalty !== undefined && !modelInList(provider.noPenaltyModels, parsed.modelId)) {
body.frequency_penalty = parsed.options.frequencyPenalty;
}
- // prompt_cache_key is an OpenAI-specific chat extension; strict backends (Groq,
- // Cerebras, etc.) reject unknown fields. Only forward when the provider opts in.
if (provider.promptCacheKey && parsed.options.promptCacheKey !== undefined) {
body.prompt_cache_key = parsed.options.promptCacheKey;
}
- // Responses `text.format` -> chat `response_format`. json_object maps 1:1; json_schema
- // re-nests the flattened Responses fields under `json_schema` — the exact inverse of
- // responseFormatToText in src/chat/inbound.ts. Forwarded unconditionally (like `stop`):
- // response_format is a first-class Chat Completions field, it is only present when the
- // caller explicitly asked for structured output, and a backend that rejects it should
- // fail loud rather than silently return prose the caller will try to JSON.parse.
const textFormat = parsed.options.textFormat;
if (textFormat?.type === "json_object") {
body.response_format = { type: "json_object" };
@@ -841,30 +827,18 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
}
if (tools) {
- // Default-ON for chat-completions providers (user decision 260709): the buffered
- // parser assembles multi-call streams safely, so `parallelToolCalls: false` is the
- // only per-provider opt-out; Codex's request bit can still force false per request.
- // Rationale + provider evidence: devlog/_plan/260709_parallel_tool_calls.
body.parallel_tool_calls = provider.parallelToolCalls === false
? false
: parsed.options.parallelToolCalls !== false;
}
- if (parsed.stream) {
- body.stream_options = { include_usage: true };
- }
+ if (parsed.stream) body.stream_options = { include_usage: true };
const url = `${provider.baseUrl}/chat/completions`;
const headers: Record = { "Content-Type": "application/json" };
- // Precedence preserved from pre-#128 behavior: apiKey Authorization first, then
- // provider.headers may override (user/registry-configured headers win). Registry
- // staticHeaders (e.g. opencode-free x-opencode-client) flow in via derive.ts and
- // never carry Authorization, so keyless providers are unaffected.
if (hasCredential) headers["Authorization"] = `Bearer ${provider.apiKey}`;
if (provider.headers) Object.assign(headers, provider.headers);
const bodyJson = JSON.stringify(body);
- // Never log pathname/query — tenant-scoped hosts (e.g. Cloudflare
- // /accounts//ai/v1) would otherwise leak account identifiers (#452).
if (isDebugEnabled()) {
let host = "upstream";
try { host = new URL(url).host; } catch { /* keep fallback */ }
@@ -899,14 +873,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
const budgetEncoder = new TextEncoder();
let buffer = "";
let bufferBytes = 0;
- // Streamed tool calls are BUFFERED until a terminal signal, then flushed as atomic
- // start/delta/end sequences. The bridge treats text/reasoning deltas as barriers that
- // close an open tool-call item (bridge.ts closeCurrentToolCall on text_delta), so
- // emitting calls incrementally would orphan later argument deltas whenever a provider
- // interleaves content — and parallel tool calls (multiple ids, index-keyed continuation
- // chunks, whole-chunk calls) cannot be represented live without overlapping sequences.
- // Keyed by `index` (OpenAI wire standard), falling back to `id`, falling back to the
- // last-seen call for providers that omit both on continuation chunks.
interface PendingToolCall { key: string; id: string; name: string; args: string; argsBytes: number }
const pendingToolCalls: PendingToolCall[] = [];
let toolCallSeq = 0;
@@ -917,8 +883,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
return calls;
};
const flushToolCalls = function* (): Generator {
- // Do not treat flushed tool calls as user-facing output for the finish-less EOF
- // fallback — incomplete tool args must stay on the truncation path.
for (const call of closeToolCalls()) {
if (!call.id) call.id = `call_${++toolCallSeq}`;
yield { type: "tool_call_start", id: call.id, name: call.name };
@@ -934,25 +898,13 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
return "terminate";
};
let pendingUsage: OcxUsage | undefined;
- // Track terminal signals so a socket EOF without any terminator can fail closed instead of
- // being reported as a clean completion (silent truncation). A graceful close is either an
- // explicit `[DONE]` sentinel OR a chunk carrying a non-null `finish_reason` (some
- // OpenAI-compatible providers omit `[DONE]` but do send finish_reason).
let finishReason: string | undefined;
- // Only answer text enables the finish-less EOF fallback. Reasoning-only streams can be
- // suppressed by hideThinkingSummary and must not complete as empty successful turns.
let sawUserFacingOutput = false;
- // Single per-line handler shared by the streaming loop and the EOF residual-frame flush, so
- // a final frame is parsed identically wherever it lands (no duplicated, drift-prone parsing).
- // Yields adapter events and returns "terminate" for a terminal frame ([DONE] / error) that
- // must end the stream, or "continue" otherwise. Mutates the closure's terminal-signal state.
const handleDataLine = function* (line: string): Generator {
const rawPayload = sseFieldValue(line, "data");
if (rawPayload === null) return "continue";
const payload = rawPayload.trim();
- // A bare `data:` line carries nothing (heartbeat-style keep-alive on some gateways);
- // it is not a malformed frame, just nothing to parse.
if (payload.length === 0) return "continue";
if (payload === "[DONE]") {
yield* flushToolCalls();
@@ -968,42 +920,20 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
yield { type: "error", message: "malformed upstream SSE data frame" };
return "terminate";
}
- // Validate the shape instead of asserting it. `JSON.parse` yields a value, not necessarily
- // an object — `JSON.parse("null")` returns null without throwing, so the catch above never
- // sees it and the `chunk.error` read below crashed the stream mid-flight.
- //
- // Skip rather than terminate: `data: null` is emitted as a benign padding frame BETWEEN
- // content deltas by real OpenAI-compatible routes (issue #1219), so failing here would
- // discard the finish_reason chunk and [DONE] still in flight and turn a healthy response
- // into a failed turn. Skipping cannot mask a genuinely broken stream — a stream carrying
- // only such frames still sets neither finishReason nor sawUserFacingOutput and so trips
- // the EOF truncation guard below. An unparseable frame stays terminal.
- if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
- return "continue";
- }
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "continue";
const chunk = parsed as Record;
- // A 200/OK chat-completions stream may carry an inline provider error envelope
- // instead of a clean [DONE]. Surface it as a terminal error so the bridge emits a
- // classified response.failed (bridge case "error") — never a truncated completion.
if (chunk.error !== undefined && chunk.error !== null) {
const event = upstreamErrorEvent(chunk.error, pendingUsage);
debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
return yield* terminateWithError(event);
}
- if (chunk.usage) {
- // Record usage but keep parsing: some providers send usage and the final content
- // delta in the SAME chunk; a bail here would drop that content. The choices
- // guard below no-ops a usage-only chunk.
- pendingUsage = usageFromOpenAIChat(chunk.usage as Record);
- }
+ if (chunk.usage) pendingUsage = usageFromOpenAIChat(chunk.usage as Record);
const choices = chunk.choices;
if (choices === undefined) return "continue";
- if (!Array.isArray(choices)) {
- return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
- }
+ if (!Array.isArray(choices)) return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
if (choices.length === 0) return "continue";
const rawChoice = choices[0];
if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
@@ -1019,34 +949,39 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
return yield* terminateWithError(event);
}
- // Observe the terminator BEFORE the delta guard: a finish-only chunk (finish_reason set,
- // no delta) is a graceful close and must record finishReason even though we skip it below.
- if (typeof choice.finish_reason === "string" && choice.finish_reason) {
- finishReason = choice.finish_reason;
- }
+ if (typeof choice.finish_reason === "string" && choice.finish_reason) finishReason = choice.finish_reason;
const delta = choice.delta;
if (delta) {
const reasoningText = reasoningTextFrom(delta);
- if (reasoningText !== undefined) {
- yield { type: "reasoning_raw_delta", text: reasoningText };
- }
+ if (reasoningText !== undefined) yield { type: "reasoning_raw_delta", text: reasoningText };
if (typeof delta.content === "string" && delta.content.length > 0) {
sawUserFacingOutput = true;
yield { type: "text_delta", text: delta.content };
}
- const toolCalls = delta.tool_calls as { index?: number; id?: string; function?: { name?: string; arguments?: string } }[] | undefined;
- if (toolCalls) {
- for (const tc of toolCalls) {
+ const rawToolCalls = delta.tool_calls;
+ if (rawToolCalls !== undefined) {
+ // A claimed tool-call payload is not benign padding. Dropping it can leave the
+ // matching result permanently orphaned, so malformed nested shapes fail closed
+ // through the adapter error channel instead of escaping as TypeError (#1325).
+ if (!Array.isArray(rawToolCalls)) {
+ return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
+ }
+ for (const rawToolCall of rawToolCalls) {
+ if (!isRecord(rawToolCall)) {
+ return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
+ }
+ const tc = rawToolCall as {
+ index?: number;
+ id?: string;
+ function?: { name?: string; arguments?: string };
+ };
const key = typeof tc.index === "number"
? `i:${tc.index}`
: tc.id
- ? `id:${tc.id}`
- : pendingToolCalls[pendingToolCalls.length - 1]?.key;
+ ? `id:${tc.id}`
+ : pendingToolCalls[pendingToolCalls.length - 1]?.key;
let call = key !== undefined ? pendingToolCalls.find(c => c.key === key) : undefined;
- // Mixed keying rescue: a call opened under an index key must still absorb an
- // id-only continuation for the same provider id (and vice versa) instead of
- // splitting into two calls that share one call_id downstream.
if (!call && tc.id) call = pendingToolCalls.find(c => c.id === tc.id);
if (!call) {
call = { key: key ?? `seq:${pendingToolCalls.length}`, id: "", name: "", args: "", argsBytes: 0 };
@@ -1074,11 +1009,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
}
}
- // Any non-empty finish_reason ends the generation: flush assembled tool calls as
- // atomic sequences (covers "tool_calls" AND providers that close tool turns with "stop").
- if (typeof choice.finish_reason === "string" && choice.finish_reason) {
- yield* flushToolCalls();
- }
+ if (typeof choice.finish_reason === "string" && choice.finish_reason) yield* flushToolCalls();
return "continue";
};
@@ -1117,21 +1048,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
}
}
- // Some providers send the terminal `data:` frame (carrying the final delta, finish_reason,
- // and/or usage) WITHOUT a trailing newline before closing the socket, so it never crosses
- // the split("\n") boundary and stays in `buffer`. Run it through the SAME handler so its
- // content/tool-calls are emitted and its terminal signal observed — otherwise a genuinely
- // complete stream loses its last frame and may be falsely failed below.
if (buffer.length > 0) {
if ((yield* handleDataLine(buffer)) === "terminate") return;
}
- // Reader EOF. Prefer failing closed before flushing pending tool calls so the bridge
- // never sees a fabricated tool_call_end on a truncated mid-assembly stream.
- //
- // Checked BEFORE flushToolCalls(), because that helper emits tool_call_end and there is no
- // taking it back: a half-assembled argument string would reach the client as a completed
- // call. Tool calls are buffered here (unlike the Anthropic adapter, which forwards
- // fragments live), so this adapter can still decide.
const sawFinish = finishReason !== undefined;
if (!sawFinish && pendingToolCalls.length > 0) {
debugProviderDiagnostic("openai-chat", "stream-truncated", {
@@ -1142,9 +1061,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
yield { type: "error", message: "upstream stream ended mid tool call without a terminal signal — possible truncation" };
return;
}
- // Finish-less EOF is only safe when answer text was emitted. Reasoning-only / usage-only
- // truncations must stay on the error path (hideThinkingSummary can suppress reasoning).
- // Trailing usage alone is not a terminal signal for this adapter (#735 / restore #773).
if (!sawFinish && !sawUserFacingOutput) {
debugProviderDiagnostic("openai-chat", "stream-truncated", {
finishReason: finishReason ?? null,
@@ -1154,7 +1070,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
return;
}
yield* flushToolCalls();
- // Graceful close that omitted [DONE] but delivered finish_reason and/or answer text.
const stopReason = stopReasonFor(finishReason);
yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
} catch (error) {
@@ -1183,60 +1098,64 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
try {
- const payload = unwrapChatCompletionPayload(json);
- const usage = usageFromOpenAIChat(payload.usage as Record | undefined);
- if (json.success === false && payload.error === undefined) {
- return [{
- type: "error",
- message: "upstream reported failure without an error payload",
- ...(usage ? { usage } : {}),
- }];
- }
- if (payload.error !== undefined && payload.error !== null) {
- return [upstreamErrorEvent(payload.error, usage)];
- }
-
- const events: AdapterEvent[] = [];
- const choices = payload.choices as {
- message?: Record;
- finish_reason?: unknown;
- error?: OpenAIChatError;
- }[] | undefined;
- if (!Array.isArray(choices) || choices.length === 0) {
- return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
- }
- const rawChoice = choices[0];
- if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
- return [invalidChoicesEvent(usage)];
- }
- const choice = rawChoice;
- if (choice.finish_reason === "error") return [upstreamErrorEvent(choice.error, usage)];
- if (!choice.message) return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
-
- const msg = choice.message;
- const reasoningText = reasoningTextFrom(msg);
- if (reasoningText !== undefined) {
- events.push({ type: "reasoning_raw_delta", text: reasoningText });
- }
- if (typeof msg.content === "string") {
- events.push({ type: "text_delta", text: msg.content });
- }
- const toolCalls = msg.tool_calls as { id: string; function: { name: string; arguments: string } }[] | undefined;
- if (toolCalls) {
- for (const tc of toolCalls) {
- events.push({ type: "tool_call_start", id: tc.id, name: tc.function.name });
- events.push({ type: "tool_call_delta", arguments: tc.function.arguments });
- events.push({ type: "tool_call_end" });
+ const payload = unwrapChatCompletionPayload(json);
+ const usage = usageFromOpenAIChat(payload.usage as Record | undefined);
+ if (json.success === false && payload.error === undefined) {
+ return [{
+ type: "error",
+ message: "upstream reported failure without an error payload",
+ ...(usage ? { usage } : {}),
+ }];
}
- }
- const stopReason = stopReasonFor(choice.finish_reason);
- events.push({
- type: "done",
- usage,
- ...(stopReason ? { stopReason } : {}),
- });
- retainTranslatedEventBatch(events, budget);
- return events;
+ if (payload.error !== undefined && payload.error !== null) return [upstreamErrorEvent(payload.error, usage)];
+
+ const events: AdapterEvent[] = [];
+ const choices = payload.choices as {
+ message?: Record;
+ finish_reason?: unknown;
+ error?: OpenAIChatError;
+ }[] | undefined;
+ if (!Array.isArray(choices) || choices.length === 0) {
+ return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+ }
+ const rawChoice = choices[0];
+ if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
+ return [invalidChoicesEvent(usage)];
+ }
+ const choice = rawChoice;
+ if (choice.finish_reason === "error") return [upstreamErrorEvent(choice.error, usage)];
+ if (!choice.message) return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+
+ const msg = choice.message;
+ const reasoningText = reasoningTextFrom(msg);
+ if (reasoningText !== undefined) events.push({ type: "reasoning_raw_delta", text: reasoningText });
+ if (typeof msg.content === "string") events.push({ type: "text_delta", text: msg.content });
+ const rawToolCalls = msg.tool_calls;
+ if (rawToolCalls !== undefined) {
+ if (!Array.isArray(rawToolCalls)) return [invalidToolCallsEvent(usage)];
+ for (const rawToolCall of rawToolCalls) {
+ if (!isRecord(rawToolCall) || !isRecord(rawToolCall.function)) {
+ return [invalidToolCallsEvent(usage)];
+ }
+ const id = rawToolCall.id;
+ const name = rawToolCall.function.name;
+ const args = rawToolCall.function.arguments;
+ if (typeof id !== "string" || typeof name !== "string" || typeof args !== "string") {
+ return [invalidToolCallsEvent(usage)];
+ }
+ events.push({ type: "tool_call_start", id, name });
+ events.push({ type: "tool_call_delta", arguments: args });
+ events.push({ type: "tool_call_end" });
+ }
+ }
+ const stopReason = stopReasonFor(choice.finish_reason);
+ events.push({
+ type: "done",
+ usage,
+ ...(stopReason ? { stopReason } : {}),
+ });
+ retainTranslatedEventBatch(events, budget);
+ return events;
} finally {
budget.releaseRetained(responseBytes, { kind: "retained_collectors" });
}
diff --git a/src/adapters/openai-responses.ts b/src/adapters/openai-responses.ts
index 8bb40769a..9e9b46acc 100644
--- a/src/adapters/openai-responses.ts
+++ b/src/adapters/openai-responses.ts
@@ -538,6 +538,65 @@ function repairOrphanedInputItems(body: unknown, dropReasoning: boolean): unknow
return changed ? { ...body, input: repaired } : body;
}
+/**
+ * Make unambiguous Responses tool pairs adjacent for upstream parsers that require it.
+ *
+ * [Decision Log]
+ * - 목적과 의도: Keep Codex hook-injected developer context without letting it make a strict upstream reject the matching tool result.
+ * - 기존 구현 및 제약 조건: The orphan repair verifies only pair presence; globally reordering valid history would change tolerant providers unnecessarily.
+ * - 검토한 주요 대안: Reorder every Responses request, drop the intervening message, or gate a lossless reorder behind provider capability metadata.
+ * - 선택한 방식: Reorder only unique call/result pairs for providers that explicitly require adjacency, preserving every intervening item immediately after the result.
+ * - 다른 대안 대신 이 방식을 선택한 이유: The provider gate limits semantic blast radius, while refusing ambiguous duplicate ids avoids guessing which result belongs to which call.
+ * - 장점, 단점 및 영향: DeepSeek receives the adjacency its parser requires; tolerant providers stay byte/order equivalent. Ambiguous duplicate ids still fail upstream rather than being silently rewritten.
+ */
+function normalizeResponsesToolResultAdjacency(body: unknown): unknown {
+ if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+ const input = body.input;
+ const calls = new Map();
+ const outputs = new Map();
+
+ const appendIndex = (map: Map, key: string, index: number): void => {
+ const existing = map.get(key);
+ if (existing) existing.push(index);
+ else map.set(key, [index]);
+ };
+
+ for (let index = 0; index < input.length; index += 1) {
+ const item = input[index];
+ if (!isPlainObject(item) || typeof item.call_id !== "string" || item.call_id.length === 0) continue;
+ if (item.type === "function_call" || item.type === "local_shell_call") {
+ appendIndex(calls, `function:${item.call_id}`, index);
+ } else if (item.type === "custom_tool_call") {
+ appendIndex(calls, `custom:${item.call_id}`, index);
+ } else if (item.type === "function_call_output") {
+ appendIndex(outputs, `function:${item.call_id}`, index);
+ } else if (item.type === "custom_tool_call_output") {
+ appendIndex(outputs, `custom:${item.call_id}`, index);
+ }
+ }
+
+ const movedOutputIndices = new Set();
+ const outputAfterCall = new Map();
+ for (const [key, callIndices] of calls) {
+ const outputIndices = outputs.get(key);
+ if (callIndices.length !== 1 || outputIndices?.length !== 1) continue;
+ const callIndex = callIndices[0]!;
+ const outputIndex = outputIndices[0]!;
+ if (outputIndex === callIndex + 1) continue;
+ movedOutputIndices.add(outputIndex);
+ outputAfterCall.set(callIndex, input[outputIndex]);
+ }
+ if (movedOutputIndices.size === 0) return body;
+
+ const normalized: unknown[] = [];
+ for (let index = 0; index < input.length; index += 1) {
+ if (movedOutputIndices.has(index)) continue;
+ normalized.push(input[index]);
+ if (outputAfterCall.has(index)) normalized.push(outputAfterCall.get(index));
+ }
+ return { ...body, input: normalized };
+}
+
/**
* Remove `previous_response_id` before forwarding. Two triggers:
* - the proxy expanded the request into a full input replay (the id is now redundant), or
@@ -1158,6 +1217,9 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
if (forward || stateless) {
outBody = repairOrphanedInputItems(outBody, unexpandedMiss);
}
+ if (provider.requiresAdjacentResponsesToolResults === true) {
+ outBody = normalizeResponsesToolResultAdjacency(outBody);
+ }
if (forward) {
outBody = stripUnsupportedForwardParams(outBody);
} else {
diff --git a/src/claude/outbound.ts b/src/claude/outbound.ts
index 494720c49..c8b4d20df 100644
--- a/src/claude/outbound.ts
+++ b/src/claude/outbound.ts
@@ -245,14 +245,13 @@ export function responsesSseToAnthropicSse(
emit("message_start", { type: "message_start", message: messageSnapshot(model) });
emit("ping", { type: "ping" });
};
- // Idle keepalive (devlog 100): real Anthropic streams may interleave pings anywhere;
- // synthesizing one during upstream silence protects remote deployments behind
- // LB/NAT idle timeouts and covers slow first tokens. Cheap and spec-legal.
+ // Once a semantic Anthropic message has started, keepalive pings protect remote
+ // deployments behind LB/NAT idle timeouts. Transport-only Responses prelude frames
+ // must not manufacture a message before a possible initial error.
if (pingIntervalMs > 0) {
pingTimer = setInterval(() => {
- if (terminated) return;
+ if (terminated || !started) return;
try {
- ensureStarted();
emit("ping", { type: "ping" });
} catch { /* controller torn down; the read loop is ending anyway */ }
}, pingIntervalMs);
@@ -328,20 +327,24 @@ export function responsesSseToAnthropicSse(
))));
return;
}
- ensureStarted();
- closeOpenBlock();
const type = upstreamDerived && isTransientUpstreamStatus(status) ? "overloaded_error" : undefined;
+ if (!started) {
+ // An initial upstream failure is an Anthropic error stream, not a partial message.
+ // Do not manufacture message_start/ping before the terminal error.
+ emit("error", anthropicErrorBody(status, message, type, code));
+ return;
+ }
+ closeOpenBlock();
emit("error", anthropicErrorBody(status, message, type, code));
};
const handleFrame = (eventName: string, data: Rec) => {
switch (eventName) {
case "response.created":
- ensureStarted();
+ // Transport prelude only. Start Anthropic framing on semantic output or completion.
break;
case "response.heartbeat":
- ensureStarted();
- emit("ping", { type: "ping" });
+ if (started) emit("ping", { type: "ping" });
break;
case "response.output_text.delta": {
if (typeof data.delta !== "string" || data.delta.length === 0) break;
diff --git a/src/cli/doctor.ts b/src/cli/doctor.ts
index 2e12745b4..64d62ce8a 100644
--- a/src/cli/doctor.ts
+++ b/src/cli/doctor.ts
@@ -23,6 +23,7 @@ import { withNativeMainSharedClaim } from "../codex/native-main-claim";
import { probeNativeProfileRecoveryState, resolveNativeProfileContext } from "../codex/native-profile-store";
import { NativeProfileError } from "../codex/native-profile-types";
import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
+import { scanCodexAgentRolesWithTomlModelFallback } from "../codex/subagent-model-fallback";
import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
import { countPendingOpencodexHistory } from "../codex/history-provider";
import {
@@ -942,6 +943,15 @@ export async function runDoctor(args: string[] = []): Promise {
}
}
+ console.log("\nCodex agent role files");
+ const tomlFallbackRoles = scanCodexAgentRolesWithTomlModelFallback(resolveCodexHomeDirImpl());
+ if (tomlFallbackRoles.length === 0) {
+ console.log(" ok no per-role model_fallback fields in $CODEX_HOME/agents/*.toml");
+ } else {
+ console.log(` [WARN] ${tomlFallbackRoles.length} agent role file${tomlFallbackRoles.length === 1 ? "" : "s"} contain${tomlFallbackRoles.length === 1 ? "s" : ""} \`model_fallback\`: ${tomlFallbackRoles.join(", ")}`);
+ console.log(" Codex >= 0.146 rejects that field as unknown and skips the whole role. Move the chains to opencodex config `subagentModelFallbackByModel` (keyed by primary model) and remove the field from the TOML files.");
+ }
+
const dual = collectWslDualInstall();
if (dual.wsl) {
console.log("\nWSL Codex installs");
diff --git a/src/cli/index.ts b/src/cli/index.ts
index d96b128f9..f86c5eb7e 100755
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -219,6 +219,22 @@ async function chooseListenPort(requestedPort?: number): Promise {
}
}
+async function findProxyOwnerBeforeJournalRecovery(
+ options: { probeConfiguredPort?: boolean } = {},
+): Promise<{ live: LiveProxy | null; pidSnapshot: number | null }> {
+ const pidSnapshot = readPidFileValue();
+ const hasRuntimeOwner = readRuntimePort() !== null;
+ const shouldProbe = pidSnapshot !== null || hasRuntimeOwner || options.probeConfiguredPort === true;
+ const live = shouldProbe ? await findLiveProxy() : null;
+ if (live) return { live, pidSnapshot };
+
+ // The probe established that the snapshotted owner is stale. Compare before
+ // deleting so a concurrent start that rewrote the PID file keeps its state.
+ removePidIfValueIs(pidSnapshot);
+ if (!currentExternalCodexModelProvider()) reconcileJournal();
+ return { live: null, pidSnapshot };
+}
+
async function handleStart(options: { block?: boolean } = {}) {
// Native (WinSW) service mode has no batch wrapper to read the service token file
// into the environment, so the app loads it here before the server binds. The server
@@ -226,15 +242,10 @@ async function handleStart(options: { block?: boolean } = {}) {
const serviceToken = loadServiceTokenFromFile(process.env);
if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
const requestedPort = parsePortOption();
- if (!currentExternalCodexModelProvider()) reconcileJournal();
- const existingPid = readPid();
- if (existingPid) {
- const live = await findLiveProxy();
- if (live) {
- console.error(`⚠️ Proxy already running (PID ${live.pid ?? existingPid}, port ${live.port}). Use 'ocx stop' first.`);
- process.exit(1);
- }
- removePid(existingPid);
+ const owner = await findProxyOwnerBeforeJournalRecovery();
+ if (owner.live) {
+ console.error(`⚠️ Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+ process.exit(1);
}
// Interactive-only update prompt. Must run BEFORE we bind a port / write a
@@ -442,13 +453,13 @@ function detachedStartEnvironment(): NodeJS.ProcessEnv {
}
async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Promise {
- if (!currentExternalCodexModelProvider()) reconcileJournal();
+ const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
const config = loadConfig();
if (!codexAutoStartEnabled(config)) {
console.log("Codex autostart is disabled.");
return false;
}
- const live = await findLiveProxy();
+ const live = owner.live;
if (live) {
if (options.existingIsSuccess === false) {
console.error("Proxy appeared while restart was confirming absence; no start was attempted.");
diff --git a/src/codex/catalog.ts b/src/codex/catalog.ts
index b7abbf581..a76610b93 100644
--- a/src/codex/catalog.ts
+++ b/src/codex/catalog.ts
@@ -5,7 +5,7 @@ export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
export { CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
-export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember } from "./catalog/provider-fetch";
+export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";
export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmissions, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList, buildComboCatalogOmission, comboCatalogOmissionReason, summarizeComboCatalogOmissions } from "./catalog/aggregation";
export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";
diff --git a/src/codex/catalog/provider-fetch.ts b/src/codex/catalog/provider-fetch.ts
index 04553cf92..5314ecace 100644
--- a/src/codex/catalog/provider-fetch.ts
+++ b/src/codex/catalog/provider-fetch.ts
@@ -151,6 +151,13 @@ interface CapturedProviderGather {
readonly policy: CatalogProviderDiscoveryPolicySnapshot;
readonly request: CapturedModelsRequest;
readonly observedAuth?: ModelsAuthResolution;
+ /**
+ * Configured model ids this provider must keep even when live discovery omits
+ * them — combo targets that are also listed in providers.*.models (OCX-111).
+ * Combo-only ids (not in models[]) stay out of the public catalog and are
+ * synthesized for combo derivation instead (#1305).
+ */
+ readonly retainConfiguredModelIds?: ReadonlySet;
}
interface GatherFlightCapture {
@@ -381,6 +388,7 @@ function captureProviderGather(
name: string,
configured: OcxProviderConfig,
authResolver: ModelsAuthResolver,
+ retainConfiguredModelIds?: ReadonlySet,
): CapturedProviderGather {
const enriched = detachedClone(configured);
enrichProviderFromRegistry(name, enriched);
@@ -422,18 +430,47 @@ function captureProviderGather(
policy,
request,
...(observedAuth ? { observedAuth: Object.freeze({ ...observedAuth }) } : {}),
+ ...(retainConfiguredModelIds && retainConfiguredModelIds.size > 0
+ ? { retainConfiguredModelIds }
+ : {}),
});
}
+/** Model ids each provider must retain for combo catalog derivation (OCX-111). */
+export function configuredComboTargetModelsByProvider(
+ config: Pick,
+): Map> {
+ const byProvider = new Map>();
+ for (const id of listComboIds(config)) {
+ const combo = getCombo(config, id);
+ if (!combo) continue;
+ for (const target of combo.targets) {
+ let models = byProvider.get(target.provider);
+ if (!models) {
+ models = new Set();
+ byProvider.set(target.provider, models);
+ }
+ models.add(target.model);
+ }
+ }
+ return byProvider;
+}
+
function captureGatherFlight(
config: OcxConfig,
createAuthResolver: ModelsAuthResolverFactory,
): GatherFlightCapture {
const providerAuthOutcomes: CatalogGatherProviderAuthOutcome[] = [];
const authResolver = createAuthResolver(providerAuthOutcomes);
+ const comboTargetsByProvider = configuredComboTargetModelsByProvider(config);
const providers = Object.entries(config.providers)
.filter(([, provider]) => provider.disabled !== true)
- .map(([name, provider]) => captureProviderGather(name, provider, authResolver));
+ .map(([name, provider]) => captureProviderGather(
+ name,
+ provider,
+ authResolver,
+ comboTargetsByProvider.get(name),
+ ));
const discoveryPolicySnapshots = Object.freeze(providers.map(provider => provider.policy));
return Object.freeze({
discoveryPolicyIdentity: keyedGatherIdentity("catalog-discovery-policy-v1", discoveryPolicySnapshots),
@@ -460,6 +497,9 @@ function captureGatherFlight(
// It is the one member of a provider row that is legitimately a function,
// so it is dropped here rather than allowed to break every encode.
provider: omitProviderTransportExecutor(provider.provider),
+ // Combo retention is capture-time state, not a provider-row field. Two
+ // gathers that share providers but differ in combo targets must not join.
+ retainConfiguredModelIds: [...(provider.retainConfiguredModelIds ?? [])].sort(),
}))),
discoveryPolicySnapshots,
providers: Object.freeze(providers),
@@ -923,7 +963,16 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
item.max_context_length,
);
const maxInputTokens = positiveSafeInteger(limits?.max_input_tokens, item.max_input_tokens);
- const rawReasoningEfforts = capabilityRecord?.reasoning_effort ?? item.reasoning_efforts;
+ // Some OpenAI-compatible catalogs expose the selectable ladder under
+ // `reasoning_parameters.efforts` instead of the older `reasoning_efforts` key.
+ // Treat both as model metadata: otherwise a valid upstream capability disappears
+ // before client exporters (including omp) can advertise it.
+ const reasoningParameters = plainRecord(item.reasoning_parameters)
+ ?? plainRecord(metadata?.reasoning_parameters)
+ ?? plainRecord(capabilityRecord?.reasoning_parameters);
+ const rawReasoningEfforts = capabilityRecord?.reasoning_effort
+ ?? item.reasoning_efforts
+ ?? reasoningParameters?.efforts;
const listedReasoningEfforts = normalizedStringList(rawReasoningEfforts, 8, 24);
const reasoningEfforts = listedReasoningEfforts
? sanitizeCodexReasoningEfforts(listedReasoningEfforts)
@@ -1004,6 +1053,30 @@ async function fetchProviderModelsWithAuth(
provider: name,
...catalogHintsFromProviderConfig(name, prov, id, contextCap),
}));
+ const withConfiguredRetention = (
+ models: CatalogModel[],
+ options?: { retainComboTargets?: boolean; warnDrops?: boolean },
+ ): CatalogModel[] => {
+ const { models: merged, droppedConfiguredIds } = mergeConfiguredModelsIntoLiveCatalog({
+ name,
+ provider: prov,
+ models,
+ configured,
+ retainConfiguredModelIds: captured.retainConfiguredModelIds,
+ contextCap,
+ seedVertexDefault,
+ retainComboTargets: options?.retainComboTargets,
+ });
+ if (
+ options?.warnDrops === true
+ && droppedConfiguredIds.length > 0
+ && name !== OPENAI_API_PROVIDER_ID
+ && !QUIET_AUTHORITATIVE_CATALOG_PROVIDERS.has(name)
+ ) {
+ warnDroppedConfiguredIdsOnce(name, droppedConfiguredIds);
+ }
+ return merged;
+ };
// Static catalogs never need an OAuth refresh or an upstream model request. Clear any
// discovery failure left by an older live configuration even when the account is logged out.
if (prov.liveModels === false) {
@@ -1047,12 +1120,17 @@ async function fetchProviderModelsWithAuth(
// plan (e.g. claude-fable-5) drop out instead of failing ERROR_BAD_MODEL_NAME. Fall back to the seed.
const cachedCursor = getFreshCached(name, ttlMs);
if (cachedCursor) {
- return observed(applyConfigHintsToCachedModels(name, prov, cachedCursor), "authoritative");
+ return observed(
+ withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cachedCursor)),
+ "authoritative",
+ );
}
if (isModelsFetchCoolingDown(name)) {
const cooling = getStaleCached(name);
return observed(
- cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
+ withConfiguredRetention(
+ cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
+ ),
"degraded",
);
}
@@ -1060,10 +1138,14 @@ async function fetchProviderModelsWithAuth(
if (liveResult.ok) {
const available = filterCursorConfiguredModelsByLiveDiscovery(configured, liveResult.models);
const result = available.length > 0 ? available : configured;
- // Count what discovery actually returned, not the configured rows we fall back to.
- if (!setCached(name, result, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+ // Cache the discovery-filtered roster without combo retention so a later
+ // gather can re-apply the current capture's retain set on read.
+ const forCache = withConfiguredRetention(result, { retainComboTargets: false });
+ if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+ return observed(withConfiguredRetention(configured), "degraded");
+ }
markProviderDiscoveryOk(name, liveResult.models.length);
- return observed(result, "authoritative");
+ return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
}
if (isCurrentCacheGeneration()) {
markModelsFetchFailure(name);
@@ -1074,7 +1156,9 @@ async function fetchProviderModelsWithAuth(
}
const staleCursor = getStaleCached(name);
return observed(
- staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor) : configured,
+ withConfiguredRetention(
+ staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor) : configured,
+ ),
"degraded",
);
}
@@ -1090,7 +1174,9 @@ async function fetchProviderModelsWithAuth(
const fresh = getFreshCached(name, ttlMs);
if (fresh) {
return observed(
- withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, fresh, contextCap)),
+ withConfiguredRetention(
+ withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, fresh, contextCap)),
+ ),
"authoritative",
); // dedups Codex's frequent /v1/models polling within the TTL
}
@@ -1099,9 +1185,11 @@ async function fetchProviderModelsWithAuth(
// fetch timeout on every catalog poll — the dashboard polls this path per page load.
const stale = getStaleCached(name);
return observed(
- stale
- ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
- : failedDiscoveryConfigured,
+ withConfiguredRetention(
+ stale
+ ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+ : failedDiscoveryConfigured,
+ ),
"degraded",
);
}
@@ -1114,7 +1202,11 @@ async function fetchProviderModelsWithAuth(
failure: ProviderModelDiscoveryFailure,
): { models: CatalogModel[]; fallback: "stale" | "configured"; shouldLog: boolean } => {
if (!isCurrentCacheGeneration()) {
- return { models: failedDiscoveryConfigured, fallback: "configured", shouldLog: false };
+ return {
+ models: withConfiguredRetention(failedDiscoveryConfigured),
+ fallback: "configured",
+ shouldLog: false,
+ };
}
// Decide logging BEFORE recording the new status, so we can compare against the prior one and
// suppress an identical repeated failure (#395 log flood). The failure stays observable via the
@@ -1124,9 +1216,11 @@ async function fetchProviderModelsWithAuth(
markProviderDiscoveryFailed(name, failure);
const stale = getStaleCached(name);
return {
- models: stale
- ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
- : failedDiscoveryConfigured,
+ models: withConfiguredRetention(
+ stale
+ ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+ : failedDiscoveryConfigured,
+ ),
fallback: stale ? "stale" : "configured",
shouldLog,
};
@@ -1202,9 +1296,12 @@ async function fetchProviderModelsWithAuth(
...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
...(model.inputModalities ? { inputModalities: model.inputModalities } : {}),
}, contextCap));
- if (!setCached(name, live, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+ const forCache = withConfiguredRetention(live, { retainComboTargets: false });
+ if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+ return observed(withConfiguredRetention(configured), "degraded");
+ }
markProviderDiscoveryOk(name, live.length);
- return observed(live, "authoritative");
+ return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
}
const extracted = extractProviderModelItems(bounded.value, discovery);
if (!extracted.ok) {
@@ -1236,37 +1333,24 @@ async function fetchProviderModelsWithAuth(
// Capture the count BEFORE the alias/configured augmentation below pushes extra rows into
// `live`; otherwise configured entries would be reported as discovered ones.
const liveModelCount = live.length;
- const liveIds = new Set(live.map(m => m.id));
- // Dated-release aliases (Anthropic pattern): older models may appear in the live catalog
- // ONLY under their dated id (claude-haiku-4-5-20251001) while the config names the
- // API-valid alias (claude-haiku-4-5). Such aliases are real, callable models — keep them
- // in the authoritative catalog (alias id, hints from the dated live entry) instead of
- // dropping them and warning on every poll.
- const droppedConfiguredIds: string[] = [];
- for (const m of configured) {
- if (liveIds.has(m.id)) continue;
- const dated = live.find(l => isDatedVariantId(l.id, m.id));
- if (dated) {
- // Reapply config hints so alias-keyed overrides (modelContextWindows etc.) win.
- live.push(applyProviderConfigHints(name, prov, { ...dated, id: m.id }, contextCap));
- } else if (seedVertexDefault || shouldRetainConfiguredProviderModel(name, m.id)) {
- live.push(m);
- } else {
- droppedConfiguredIds.push(m.id);
- }
- }
- if (live.length === 0 && name !== OPENAI_API_PROVIDER_ID) {
+ // Dated-release aliases + configured retention (compat allow-list, combo targets,
+ // Vertex default). Cache without combo retention so a later gather re-applies the
+ // current capture's retain set on read (warm-cache OCX-111 / #1308).
+ const forCache = withConfiguredRetention(live, { retainComboTargets: false });
+ const returned = withConfiguredRetention(forCache, { warnDrops: true });
+ const droppedConfiguredIds = configured
+ .map(model => model.id)
+ .filter(id => !returned.some(model => model.id === id));
+ if (returned.length === 0 && name !== OPENAI_API_PROVIDER_ID) {
console.warn(
`[opencodex] Provider model discovery for "${name}" returned an authoritative empty catalog; ${droppedConfiguredIds.length > 0 ? `dropping configured model ids: ${droppedConfiguredIds.join(", ")}` : "no models will be exposed"}.`,
);
- } else if (droppedConfiguredIds.length > 0
- && name !== OPENAI_API_PROVIDER_ID
- && !QUIET_AUTHORITATIVE_CATALOG_PROVIDERS.has(name)) {
- warnDroppedConfiguredIdsOnce(name, droppedConfiguredIds);
}
- if (!setCached(name, live, Date.now(), cacheGeneration)) return observed(configured, "degraded");
+ if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+ return observed(withConfiguredRetention(configured), "degraded");
+ }
markProviderDiscoveryOk(name, liveModelCount);
- return observed(live, "authoritative");
+ return observed(returned, "authoritative");
} catch (error) {
if (error instanceof ProviderOutboundPolicyError) {
const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
@@ -1313,6 +1397,60 @@ export function shouldRetainConfiguredProviderModel(providerName: string, modelI
return false;
}
+/**
+ * Fold dated-release aliases and retain configured rows that must survive an
+ * authoritative live roster (compatibility allow-list, combo targets, Vertex
+ * default). Used on every discovery return — live, fresh cache, stale, and
+ * failure fallback — so a warm cache captured before a combo existed still
+ * surfaces the configured target (OCX-111 / #1308).
+ *
+ * Cache writes should pass `retainComboTargets: false` so combo retention is
+ * re-applied on read against the current capture, not frozen into the TTL entry.
+ */
+export function mergeConfiguredModelsIntoLiveCatalog(opts: {
+ name: string;
+ provider: OcxProviderConfig;
+ models: readonly CatalogModel[];
+ configured: readonly CatalogModel[];
+ retainConfiguredModelIds?: ReadonlySet;
+ contextCap?: number;
+ seedVertexDefault?: boolean;
+ retainComboTargets?: boolean;
+}): { models: CatalogModel[]; droppedConfiguredIds: string[] } {
+ const {
+ name,
+ provider: prov,
+ configured,
+ retainConfiguredModelIds,
+ contextCap,
+ seedVertexDefault,
+ retainComboTargets = true,
+ } = opts;
+ const out = [...opts.models];
+ const present = new Set(out.map(model => model.id));
+ const droppedConfiguredIds: string[] = [];
+ for (const candidate of configured) {
+ if (present.has(candidate.id)) continue;
+ const dated = out.find(live => isDatedVariantId(live.id, candidate.id));
+ if (dated) {
+ out.push(applyProviderConfigHints(name, prov, { ...dated, id: candidate.id }, contextCap));
+ present.add(candidate.id);
+ continue;
+ }
+ if (
+ seedVertexDefault === true
+ || shouldRetainConfiguredProviderModel(name, candidate.id)
+ || (retainComboTargets && retainConfiguredModelIds?.has(candidate.id) === true)
+ ) {
+ out.push(candidate);
+ present.add(candidate.id);
+ continue;
+ }
+ droppedConfiguredIds.push(candidate.id);
+ }
+ return { models: out, droppedConfiguredIds };
+}
+
export function filterCatalogVisibleModels(
models: CatalogModel[],
config: Pick,
diff --git a/src/codex/history-job.ts b/src/codex/history-job.ts
index 2d35498da..64139c28f 100644
--- a/src/codex/history-job.ts
+++ b/src/codex/history-job.ts
@@ -25,7 +25,7 @@ import type {
HistoryWorkerResult,
} from "./history-worker";
import { historyBackupPathFor } from "./history-provider";
-import type { CodexHistoryFailureReason } from "./history-provider";
+import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
import { getCodexHome } from "./paths";
/** Where Codex keeps its resume history, and the manifest that shadows it. */
@@ -69,7 +69,7 @@ export interface CodexHistoryJobRequest {
}
export type CodexHistoryJobOutcome =
- | { readonly kind: "converged"; readonly rows: number; readonly files: number }
+ | { readonly kind: "converged"; readonly rows: number; readonly files: number; readonly proof?: CodexHistoryVerifiedNoopProof }
| { readonly kind: "skipped" }
| { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
| { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
@@ -92,8 +92,9 @@ export function isPlausibleWorkerResultForTests(
message: Record,
requestId: string,
jobId: string,
+ target?: Pick,
): boolean {
- return isPlausibleWorkerResult(message, requestId, jobId);
+ return isPlausibleWorkerResult(message, requestId, jobId, target);
}
/**
@@ -108,13 +109,30 @@ function isPlausibleWorkerResult(
message: Record,
requestId: string,
jobId: string,
+ target?: Pick,
): boolean {
if (message.requestId !== requestId || message.jobId !== jobId) return false;
switch (message.type) {
case "done":
- return (message.outcome === "converged" || message.outcome === "skipped")
+ if (!((message.outcome === "converged" || message.outcome === "skipped")
&& typeof message.rows === "number"
- && typeof message.files === "number";
+ && typeof message.files === "number")) return false;
+ if (message.proof === undefined) return true;
+ if (!target || !message.proof || typeof message.proof !== "object" || Array.isArray(message.proof)) return false;
+ {
+ const proof = message.proof as Record;
+ return target.operation === "migrate-openai"
+ && message.outcome === "converged"
+ && message.rows === 0
+ && message.files === 0
+ && proof.kind === "verified-noop"
+ && proof.pendingRows === 0
+ && proof.backupEntries === 0
+ && proof.canonicalStateDbPath === target.canonicalStateDbPath
+ && proof.stateDbPresent === true
+ && proof.canonicalBackupPath === target.canonicalBackupPath
+ && typeof proof.backupPresent === "boolean";
+ }
case "blocked":
return message.reason === "busy" || message.reason === "database" || message.reason === "unsafe-path"
|| message.reason === "desired_disabled" || message.reason === "desired_enabled";
@@ -227,7 +245,7 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
}
return result.outcome === "skipped"
? { kind: "skipped" }
- : { kind: "converged", rows: result.rows, files: result.files };
+ : { kind: "converged", rows: result.rows, files: result.files, ...(result.proof ? { proof: result.proof } : {}) };
}
/**
@@ -303,7 +321,7 @@ export async function runCodexHistoryJob(
died("history_worker_unknown_message_type");
return;
}
- if (!isPlausibleWorkerResult(message, requestId, jobId)) {
+ if (!isPlausibleWorkerResult(message, requestId, jobId, request)) {
// A recognized type with a missing payload read as `converged` with
// undefined fields once — success for work that may not have happened.
died("history_worker_malformed_payload");
diff --git a/src/codex/history-migration-guardian.ts b/src/codex/history-migration-guardian.ts
index e25ea97bf..68d52f837 100644
--- a/src/codex/history-migration-guardian.ts
+++ b/src/codex/history-migration-guardian.ts
@@ -1,4 +1,4 @@
-import { countPendingOpencodexHistory, migrateHistoryToOpenai } from "./history-provider";
+import { migrateHistoryToOpenai } from "./history-provider";
import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "./history-job";
/**
@@ -23,7 +23,6 @@ export interface HistoryMigrationGuardianHandle {
}
export interface HistoryMigrationGuardianDeps {
- countFn?: typeof countPendingOpencodexHistory;
migrateFn?: () => ReturnType
| Promise>;
log?: Pick;
@@ -43,7 +42,6 @@ function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
}
export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps = {}): HistoryMigrationGuardianHandle {
- const countFn = deps.countFn ?? countPendingOpencodexHistory;
// The default migration goes through the history job, so the guardian's timer
// thread never performs the transition itself. A background repair that races
// an apply or a restore is exactly what H exists to order.
@@ -53,7 +51,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
operation: "migrate-openai",
});
return outcome.kind === "converged"
- ? { rows: outcome.rows, files: outcome.files }
+ ? { rows: outcome.rows, files: outcome.files, verifiedNoop: outcome.proof?.kind === "verified-noop" }
: { rows: 0, files: 0, failed: true as const };
});
const log = deps.log ?? console;
@@ -73,23 +71,18 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
if (stopped) return;
ticks++;
try {
- const count = countFn();
- if (!count.failed && count.pendingRows === 0 && count.backupEntries === 0) {
- stopped = true; // nothing left to migrate — normal steady state, no log noise
- return;
- }
- // Locked probe or pending work: attempt one migration pass.
+ // The worker re-derives state under H on every pass; no pre-lock probe is
+ // allowed to stop or suppress this attempt.
const result = await migrateFn();
if (!result.failed) {
const moved = result.rows + ((result as { ejectedRows?: number }).ejectedRows ?? 0);
if (moved > 0) {
log.log(`🩹 history-migration: ${moved} legacy opencodex thread(s) migrated back to openai.`);
}
- // A "successful" zero-row migration can also mean the DB does not exist YET while a
- // backup manifest still holds restore work (fresh reinstall race). Only stop when a
- // re-count proves nothing is pending; otherwise keep ticking within the budget.
- const after = countFn();
- if (moved > 0 || (!after.failed && after.pendingRows === 0 && after.backupEntries === 0)) {
+ // Zero mutations are authoritative only when the worker verified the
+ // exact DB/manifest state while H was held.
+ const verifiedNoop = (result as { verifiedNoop?: boolean }).verifiedNoop === true;
+ if (moved > 0 || verifiedNoop) {
stopped = true;
return;
}
@@ -99,7 +92,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
}
if (ticks >= maxTicks) {
stopped = true;
- log.log("⚠️ history-migration: Codex history DB stayed locked; legacy threads not yet migrated. Close the Codex app and run 'ocx sync' (or check 'ocx doctor').");
+ log.log("⚠️ history-migration: Could not verify that legacy threads were migrated; the history database may be busy, unavailable, or not yet ready. Run 'ocx sync' (or check 'ocx doctor').");
return;
}
schedule();
diff --git a/src/codex/history-provider.ts b/src/codex/history-provider.ts
index 9a2ced85f..5717e5710 100644
--- a/src/codex/history-provider.ts
+++ b/src/codex/history-provider.ts
@@ -1,5 +1,5 @@
import { createHash } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { zstdDecompressSync } from "node:zlib";
import { Database } from "bun:sqlite";
@@ -200,6 +200,49 @@ interface BackupManifest {
entries: Record;
}
+export interface CodexHistoryVerifiedNoopProof {
+ readonly kind: "verified-noop";
+ readonly pendingRows: 0;
+ readonly backupEntries: 0;
+ readonly canonicalStateDbPath: string;
+ readonly stateDbPresent: true;
+ readonly canonicalBackupPath: string;
+ readonly backupPresent: boolean;
+}
+
+export type CodexHistoryNoopSnapshot =
+ | CodexHistoryVerifiedNoopProof
+ | {
+ readonly kind: "work-pending";
+ readonly pendingRows: number;
+ readonly backupEntries: number;
+ readonly canonicalStateDbPath: string;
+ readonly stateDbPresent: boolean;
+ readonly canonicalBackupPath: string;
+ readonly backupPresent: boolean;
+ }
+ | {
+ readonly kind: "unknown";
+ readonly pendingRows: null;
+ readonly backupEntries: null;
+ readonly canonicalStateDbPath: string;
+ readonly stateDbPresent: boolean;
+ readonly canonicalBackupPath: string;
+ readonly backupPresent: boolean;
+ readonly reason: "backup-path" | "database-absent" | "manifest-read" | "manifest-schema" | "manifest-foreign" | "database-query" | "snapshot-race";
+ };
+
+type StrictBackupInspection =
+ | { readonly kind: "known"; readonly present: boolean; readonly entries: number; readonly fingerprint: string }
+ | { readonly kind: "unknown"; readonly present: boolean; readonly reason: "manifest-read" | "manifest-schema" | "manifest-foreign" };
+
+let afterNoopPendingCountForTests: (() => void) | undefined;
+
+/** Test seam: runs after the pending count and before stability validation. */
+export function setAfterNoopPendingCountForTests(hook: (() => void) | undefined): void {
+ afterNoopPendingCountForTests = hook;
+}
+
interface NativeRestoreTarget {
modelProvider: string;
source: string;
@@ -212,6 +255,65 @@ function samePath(a: string, b: string): boolean {
return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
}
+function inspectBackupForNoop(path: string, stateDbPath: string): StrictBackupInspection {
+ if (!existsSync(path)) return { kind: "known", present: false, entries: 0, fingerprint: "absent" };
+ let parsed: unknown;
+ let raw: string;
+ try {
+ raw = readFileSync(path, "utf8");
+ parsed = JSON.parse(raw);
+ } catch {
+ return { kind: "unknown", present: true, reason: "manifest-read" };
+ }
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ return { kind: "unknown", present: true, reason: "manifest-schema" };
+ }
+ const manifest = parsed as Partial;
+ if (manifest.version !== 1 || typeof manifest.stateDbPath !== "string") {
+ return { kind: "unknown", present: true, reason: "manifest-schema" };
+ }
+ if (!samePath(manifest.stateDbPath, stateDbPath)) {
+ return { kind: "unknown", present: true, reason: "manifest-foreign" };
+ }
+ if (!manifest.entries || typeof manifest.entries !== "object" || Array.isArray(manifest.entries)) {
+ return { kind: "unknown", present: true, reason: "manifest-schema" };
+ }
+ for (const [id, value] of Object.entries(manifest.entries)) {
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
+ return { kind: "unknown", present: true, reason: "manifest-schema" };
+ }
+ const entry = value as Partial;
+ if (entry.id !== id
+ || typeof entry.rolloutPath !== "string"
+ || typeof entry.modelProvider !== "string"
+ || typeof entry.source !== "string"
+ || typeof entry.hasUserEvent !== "number") {
+ return { kind: "unknown", present: true, reason: "manifest-schema" };
+ }
+ }
+ return {
+ kind: "known",
+ present: true,
+ entries: Object.keys(manifest.entries).length,
+ fingerprint: createHash("sha256").update(raw).digest("hex"),
+ };
+}
+
+function historyFileIdentity(path: string): string | null {
+ try {
+ const stat = statSync(path);
+ return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+ } catch {
+ return null;
+ }
+}
+
+function readHistoryDataVersion(db: Database): number | null {
+ const row = db.query<{ data_version: number }, []>("PRAGMA data_version").get();
+ const value = row?.data_version;
+ return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+
function readBackup(path: string, stateDbPath?: string): BackupManifest {
if (!existsSync(path)) return { version: 1, stateDbPath, entries: {} };
try {
@@ -756,6 +858,81 @@ export function migrateHistoryToOpenai(
return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
}
+/**
+ * Captures no-op evidence while the caller holds the history serialization
+ * lock H. This function does not acquire H itself. Unknown or foreign backup
+ * state is never collapsed into an empty manifest.
+ */
+export function snapshotCodexHistoryNoop(
+ stateDbPath: string,
+ backupPath: string,
+): CodexHistoryNoopSnapshot {
+ const canonicalStateDbPath = resolve(stateDbPath);
+ const canonicalBackupPath = resolve(backupPath);
+ const stateDbPresent = existsSync(stateDbPath);
+ const backupPresent = existsSync(backupPath);
+ const base = { canonicalStateDbPath, stateDbPresent, canonicalBackupPath, backupPresent };
+ if (!samePath(backupPath, historyBackupPathFor(stateDbPath))) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "backup-path" };
+ }
+ const backup = inspectBackupForNoop(backupPath, stateDbPath);
+ if (backup.kind === "unknown") {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: backup.reason };
+ }
+ if (!stateDbPresent) {
+ return backup.entries > 0
+ ? { kind: "work-pending", pendingRows: 0, backupEntries: backup.entries, ...base }
+ : { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-absent" };
+ }
+ const stateDbIdentity = historyFileIdentity(stateDbPath);
+ if (stateDbIdentity === null) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "snapshot-race" };
+ }
+ let monitor: Database | undefined;
+ try {
+ monitor = new Database(stateDbPath, { readonly: true });
+ monitor.exec("PRAGMA busy_timeout = 100");
+ const dataVersionBefore = readHistoryDataVersion(monitor);
+ if (dataVersionBefore === null) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+ }
+ const pending = countPendingOpencodexHistory(stateDbPath, backupPath);
+ if (pending.failed) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+ }
+ afterNoopPendingCountForTests?.();
+ const backupAfter = inspectBackupForNoop(backupPath, stateDbPath);
+ if (backupAfter.kind === "unknown") {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: backupAfter.reason };
+ }
+ const dataVersionAfter = readHistoryDataVersion(monitor);
+ if (dataVersionAfter === null) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+ }
+ if (dataVersionAfter !== dataVersionBefore
+ || pending.backupEntries !== backup.entries
+ || backupAfter.entries !== backup.entries
+ || backupAfter.present !== backup.present
+ || backupAfter.fingerprint !== backup.fingerprint
+ || historyFileIdentity(stateDbPath) !== stateDbIdentity
+ || existsSync(stateDbPath) !== stateDbPresent
+ || existsSync(backupPath) !== backupPresent) {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "snapshot-race" };
+ }
+ return pending.pendingRows === 0 && backup.entries === 0
+ ? { kind: "verified-noop", pendingRows: 0, backupEntries: 0, ...base, stateDbPresent: true }
+ : { kind: "work-pending", pendingRows: pending.pendingRows, backupEntries: backup.entries, ...base };
+ } catch {
+ return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "database-query" };
+ } finally {
+ try {
+ monitor?.close();
+ } catch {
+ // Read-only monitor cleanup cannot make an uncertain snapshot authoritative.
+ }
+ }
+}
+
export interface PendingHistoryCount {
/** Threads still tagged opencodex that the eject path WOULD move (mirrors its WHERE). */
pendingRows: number;
diff --git a/src/codex/history-transition.ts b/src/codex/history-transition.ts
index 1d96e9382..2ff9c0cc5 100644
--- a/src/codex/history-transition.ts
+++ b/src/codex/history-transition.ts
@@ -33,11 +33,11 @@ function classify(outcome: CodexHistoryJobOutcome, txId: string | null): CodexHi
attempts: 1,
nextRetryAt: null,
txId,
- // Mutation counts, not probe counts. The durable counts come from the
- // final probe, which this path does not run — null rather than a
- // manufactured zero.
- pendingRows: null,
- backupEntries: null,
+ // A zero is durable only when the worker proved the exact DB/manifest
+ // state while H was held. Without proof, keep the counts unknown. Keep
+ // `??`: `||` would discard a verified zero.
+ pendingRows: outcome.proof?.pendingRows ?? null,
+ backupEntries: outcome.proof?.backupEntries ?? null,
};
case "skipped":
// The user opting out is a completed decision, not a failure — converged
diff --git a/src/codex/history-worker.ts b/src/codex/history-worker.ts
index 35bf9e5bf..c0ce2dcf1 100644
--- a/src/codex/history-worker.ts
+++ b/src/codex/history-worker.ts
@@ -31,7 +31,11 @@ import {
writeLegacyOpenaiHistoryRecovery,
type HistoryWriteTarget,
} from "./internal/history-writer";
-import type { CodexHistoryFailureReason } from "./history-provider";
+import {
+ snapshotCodexHistoryNoop,
+ type CodexHistoryFailureReason,
+ type CodexHistoryVerifiedNoopProof,
+} from "./history-provider";
/**
* The durable operation, mirrored into the request for diagnostics only.
@@ -65,7 +69,8 @@ export interface HistoryWorkerRunMessage {
export type HistoryWorkerResult =
| { readonly type: "done"; readonly requestId: string; readonly jobId: string;
readonly outcome: "converged" | "skipped";
- readonly rows: number; readonly files: number }
+ readonly rows: number; readonly files: number;
+ readonly proof?: CodexHistoryVerifiedNoopProof }
| { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
| { readonly type: "error"; readonly requestId: string; readonly jobId: string;
@@ -133,6 +138,10 @@ export function runHistoryUnitUnderLock(
if (operation === "recover-legacy-openai") {
return writeLegacyOpenaiHistoryRecovery(permit, target);
}
+ if (operation === "migrate-openai") {
+ const proof = snapshotCodexHistoryNoop(message.canonicalStateDbPath, message.canonicalBackupPath);
+ if (proof.kind === "verified-noop") return { verifiedNoop: proof } as const;
+ }
// apply-opencodex routes history to opencodex; migrate/restore return it to
// native. The provider is derived from the operation, never from a caller.
const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
@@ -152,6 +161,17 @@ export function runHistoryUnitUnderLock(
reason: message.expectedDesiredEnabled ? "desired_disabled" : "desired_enabled",
};
}
+ if ("verifiedNoop" in result) {
+ return {
+ type: "done",
+ requestId,
+ jobId,
+ outcome: "converged",
+ rows: 0,
+ files: 0,
+ proof: result.verifiedNoop,
+ };
+ }
if (result.failed === true) {
return {
type: "error",
diff --git a/src/codex/native-profile-store.ts b/src/codex/native-profile-store.ts
index 7afba8173..794e8ea00 100644
--- a/src/codex/native-profile-store.ts
+++ b/src/codex/native-profile-store.ts
@@ -383,7 +383,7 @@ function readBounded(path: string, limit: number, testSeam?: BoundedReadTestSeam
testSeam?.beforeOpen?.(path);
const flags = process.platform === "win32"
? fsConstants.O_RDONLY
- : fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW;
+ : fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
fd = openSync(path, flags);
const opened = fstatSync(fd, { bigint: true });
if (!opened.isFile() || opened.size > BigInt(limit)) throw new Error("invalid bounded file");
diff --git a/src/codex/subagent-model-fallback.ts b/src/codex/subagent-model-fallback.ts
index 0e51b423c..da40ebfff 100644
--- a/src/codex/subagent-model-fallback.ts
+++ b/src/codex/subagent-model-fallback.ts
@@ -113,7 +113,12 @@ function fallbackChainKey(model: string, namespaces: unknown): string {
return JSON.stringify(["account", selector, model.slice(slash + 1).toLowerCase()]);
}
-function normalizedChain(primary: string, config: OcxConfig, extra: readonly string[] = []): string[] {
+function normalizedChain(
+ primary: string,
+ config: OcxConfig,
+ extra: readonly string[] = [],
+ trailing: readonly string[] = [],
+): string[] {
const chain: string[] = [];
const seen = new Set();
const push = (model: string | undefined) => {
@@ -127,6 +132,7 @@ function normalizedChain(primary: string, config: OcxConfig, extra: readonly str
push(primary);
for (const model of extra) push(model);
for (const model of config.subagentModelFallback ?? []) push(model);
+ for (const model of trailing) push(model);
return chain;
}
@@ -268,8 +274,9 @@ export function selectAvailableSubagentModel(
now = Date.now(),
nativeFallbackOnly = false,
accountUsabilityOptions?: CodexAccountUsabilityOptions,
+ trailingFallback: readonly string[] = [],
): { model: string; rewritten: boolean; skipped: string[] } {
- const chain = normalizedChain(primary, config, extraFallback);
+ const chain = normalizedChain(primary, config, extraFallback, trailingFallback);
const skipped: string[] = [];
for (const candidate of chain) {
if (nativeFallbackOnly) {
@@ -417,6 +424,37 @@ function subagentQuotaPrimeBlockedByHostCircuit(config: OcxConfig): boolean {
return getUpstreamHostHealth(key)?.cooldownUntil !== undefined;
}
+/**
+ * Per-primary-model fallback chains from opencodex config (#1190).
+ *
+ * Storing `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146
+ * reject the whole role file as an unknown field. The config-keyed map is the
+ * supported home for that metadata; keys match the requested primary model id,
+ * using the same raw/encoded slug tolerance as the TOML role lookup.
+ */
+export function resolveConfiguredModelFallbackForPrimary(
+ primary: string,
+ config: OcxConfig,
+): string[] {
+ const byModel = config.subagentModelFallbackByModel;
+ if (!byModel || typeof byModel !== "object") return [];
+ const entries: string[] = [];
+ const seen = new Set();
+ const push = (model: string) => {
+ const trimmed = model.trim();
+ if (trimmed === "") return;
+ const key = fallbackChainKey(trimmed, config.codexAccountNamespaces);
+ if (seen.has(key)) return;
+ seen.add(key);
+ entries.push(trimmed);
+ };
+ for (const [key, chain] of Object.entries(byModel)) {
+ if (!slugsEquivalent(key, primary)) continue;
+ for (const model of chain) push(model);
+ }
+ return entries;
+}
+
/**
* Best-effort quota refresh before subagent model selection.
* Concurrent callers share one in-flight promise. The success TTL is updated only
@@ -479,21 +517,25 @@ export function applySubagentModelFallback(
accountUsabilityOptions?: CodexAccountUsabilityOptions,
): { from?: string; to?: string; skipped?: string[] } | null {
if (!isThreadSpawnRequest(headers)) return null;
- const roleFallback = resolveAgentModelFallbackForPrimary(
+ const tomlRoleFallback = resolveAgentModelFallbackForPrimary(
parsed.modelId,
getCodexHome(),
config.codexAccountNamespaces,
);
+ // Config-keyed chains are the supported per-role home (#1190); TOML `model_fallback`
+ // stays readable for backwards compatibility with homes written before Codex 0.146.
+ const configuredFallback = resolveConfiguredModelFallbackForPrimary(parsed.modelId, config);
const globalFallback = config.subagentModelFallback ?? [];
- if (globalFallback.length === 0 && roleFallback.length === 0) return null;
+ if (globalFallback.length === 0 && configuredFallback.length === 0 && tomlRoleFallback.length === 0) return null;
const selection = selectAvailableSubagentModel(
parsed.modelId,
config,
- roleFallback,
+ configuredFallback,
accountId,
now,
nativeFallbackOnly,
accountUsabilityOptions,
+ tomlRoleFallback,
);
if (!selection.rewritten) return selection.skipped.length > 0
? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped }
@@ -510,33 +552,192 @@ export function subagentFallbackGuidanceText(config: OcxConfig): string {
return ` Subagent model fallback chain (priority order): ${quoted}. When the primary model is quota-exhausted, opencodex rewrites thread_spawn requests to the next available model automatically.`;
}
-const TOML_STRING_ARRAY = /^(model_fallback)\s*=\s*\[(.*)\]\s*$/s;
+const TOML_MODEL_FALLBACK_KEY = /^\s*(?:model_fallback|"model_fallback"|'model_fallback')\s*=/;
-function parseTomlStringArray(raw: string): string[] {
- const matches = [...raw.matchAll(/"((?:\\.|[^"\\])*)"/g)];
- return matches.map(match => match[1]!.replace(/\\"/g, "\""));
+type TomlModelFallbackField = { present: false; value: null } | { present: true; value: string[] | null };
+
+type TomlScanState = {
+ inMultilineString: '"""' | "'''" | null;
+ arrayDepth: number;
+};
+
+/** Track TOML strings, comments, and array brackets on one line. */
+function scanTomlLine(line: string, state: TomlScanState): void {
+ let i = 0;
+ while (i < line.length) {
+ const ch = line[i]!;
+ if (ch === "#") return;
+ if (ch === '"' || ch === "'") {
+ const delimiter = ch.repeat(3);
+ if (line.startsWith(delimiter, i)) {
+ const end = findTomlMultilineStringEnd(line, i + 3, ch);
+ if (end === -1) {
+ state.inMultilineString = delimiter as '"""' | "'''";
+ return;
+ }
+ i = end + 3;
+ continue;
+ }
+ i++;
+ while (i < line.length) {
+ if (ch === '"' && line[i] === "\\") {
+ i += 2;
+ continue;
+ }
+ if (line[i] === ch) break;
+ i++;
+ }
+ i++;
+ continue;
+ }
+ if (ch === "[") state.arrayDepth++;
+ else if (ch === "]") state.arrayDepth = Math.max(0, state.arrayDepth - 1);
+ i++;
+ }
}
-function parseTomlModelFallback(content: string): string[] | null {
- const match = content.match(/^\s*model_fallback\s*=\s*\[(.*?)\]\s*$/ms);
- if (!match) return null;
- return parseTomlStringArray(match[1] ?? "");
+/** Parse a TOML string starting at `start`; returns the decoded value and end offset. */
+function parseTomlStringAt(text: string, start: number): { value: string; end: number } | null {
+ const quote = text[start]!;
+ const delimiter = quote.repeat(3);
+ if (text.startsWith(delimiter, start)) {
+ const end = findTomlMultilineStringEnd(text, start + 3, quote);
+ if (end === -1) return null;
+ let value = text.slice(start + 3, end).trim();
+ if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+ return { value, end: end + 3 };
+ }
+ let i = start + 1;
+ let value = "";
+ while (i < text.length) {
+ const ch = text[i]!;
+ if (quote === '"' && ch === "\\") {
+ const next = text[i + 1];
+ if (next === '"' || next === "\\") {
+ value += next;
+ i += 2;
+ continue;
+ }
+ }
+ if (ch === quote) return { value, end: i + 1 };
+ value += ch;
+ i++;
+ }
+ return null;
+}
+
+function findTomlMultilineStringEnd(text: string, from: number, quote: string): number {
+ const delimiter = quote.repeat(3);
+ let index = text.indexOf(delimiter, from);
+ while (index !== -1) {
+ if (quote === "'") return index;
+ let backslashes = 0;
+ for (let j = index - 1; j >= 0 && text[j] === "\\"; j--) backslashes += 1;
+ if (backslashes % 2 === 0) return index;
+ index = text.indexOf(delimiter, index + 1);
+ }
+ return -1;
+}
+
+/** After an array close, only horizontal whitespace, an inline comment, or the line end is valid. */
+function isValidTomlArrayTail(text: string, from: number): boolean {
+ let i = from;
+ while (i < text.length && (text[i] === " " || text[i] === "\t")) i += 1;
+ if (i >= text.length || text[i] === "\n" || text[i] === "\r") return true;
+ if (text[i] === "#") {
+ while (i < text.length && text[i] !== "\n") i += 1;
+ return true;
+ }
+ return false;
+}
+
+/** Parse a TOML string-array value; null when the value is not a well-formed array of strings. */
+function parseTomlStringArrayValue(text: string): string[] | null {
+ const values: string[] = [];
+ let i = 0;
+ const skipIgnored = () => {
+ while (i < text.length) {
+ const ch = text[i]!;
+ if (ch === "#") {
+ while (i < text.length && text[i] !== "\n") i += 1;
+ continue;
+ }
+ if (/\s/.test(ch)) {
+ i += 1;
+ continue;
+ }
+ break;
+ }
+ };
+ skipIgnored();
+ if (text[i] !== "[") return null;
+ i += 1;
+ let expectValue = true;
+ for (;;) {
+ skipIgnored();
+ if (i >= text.length) return null;
+ const ch = text[i]!;
+ if (ch === "]") {
+ if (!isValidTomlArrayTail(text, i + 1)) return null;
+ return values;
+ }
+ if (ch === ",") {
+ if (expectValue) return null; // leading or doubled comma
+ expectValue = true;
+ i += 1;
+ continue;
+ }
+ if (ch === '"' || ch === "'") {
+ if (!expectValue) return null; // adjacent strings must be comma-separated
+ const parsed = parseTomlStringAt(text, i);
+ if (!parsed) return null;
+ values.push(parsed.value);
+ i = parsed.end;
+ expectValue = false;
+ continue;
+ }
+ return null;
+ }
+}
+
+/**
+ * TOML-aware, presence-aware parse of the `model_fallback` field. Quoted keys
+ * are recognized, and text inside strings (including multiline strings) is
+ * never treated as a key. `present` is true whenever the key exists, even when
+ * the value is not a readable string array; `value` is null in that case.
+ */
+function parseTomlModelFallbackField(content: string): TomlModelFallbackField {
+ const lines = content.split(/\r?\n/);
+ const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 };
+ for (let i = 0; i < lines.length; i += 1) {
+ const line = lines[i]!;
+ if (state.inMultilineString) {
+ const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!);
+ if (end === -1) continue;
+ state.inMultilineString = null;
+ scanTomlLine(line.slice(end + 3), state);
+ continue;
+ }
+ if (state.arrayDepth === 0) {
+ const key = line.match(TOML_MODEL_FALLBACK_KEY);
+ if (key) {
+ const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`;
+ return { present: true, value: parseTomlStringArrayValue(rest) };
+ }
+ }
+ scanTomlLine(line, state);
+ }
+ return { present: false, value: null };
}
export function readAgentModelFallback(filePath: string): string[] | null {
try {
const content = readFileSync(filePath, "utf8");
- const multiline = parseTomlModelFallback(content);
- if (multiline) return multiline;
- for (const line of content.split(/\r?\n/)) {
- const match = line.match(TOML_STRING_ARRAY);
- if (!match) continue;
- return parseTomlStringArray(match[2] ?? "");
- }
+ const parsed = parseTomlModelFallbackField(content);
+ return parsed.present ? parsed.value : null;
} catch {
return null;
}
- return null;
}
export function readCodexAgentModelFallback(role: string, codexHome = CODEX_HOME): string[] {
@@ -545,6 +746,29 @@ export function readCodexAgentModelFallback(role: string, codexHome = CODEX_HOME
return readAgentModelFallback(file) ?? [];
}
+/**
+ * True when the role TOML carries a `model_fallback` key, even an empty array.
+ * Presence is what matters for the doctor scan: Codex >= 0.146 rejects the
+ * field as unknown and skips the whole role regardless of its value. Uses the
+ * same TOML-aware parse as the fallback-reading path, so quoted keys count and
+ * text inside string literals does not.
+ */
+export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_HOME): boolean {
+ const file = join(codexHome, "agents", `${role}.toml`);
+ if (!existsSync(file)) return false;
+ try {
+ const content = readFileSync(file, "utf8");
+ return parseTomlModelFallbackField(content).present;
+ } catch {
+ return false;
+ }
+}
+
+/** Roles whose TOML still carries `model_fallback`, including empty arrays. */
+export function scanCodexAgentRolesWithTomlModelFallback(codexHome = CODEX_HOME): string[] {
+ return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+}
+
export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] {
const dir = join(codexHome, "agents");
if (!existsSync(dir)) return [];
@@ -557,4 +781,4 @@ export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] {
export function shouldPrimeSubagentQuota(config: OcxConfig, now = Date.now()): boolean {
const last = quotaPrimedAt.get("global") ?? 0;
return now - last >= pollIntervalMs(config);
-}
\ No newline at end of file
+}
diff --git a/src/config.ts b/src/config.ts
index b662959bd..32831fd39 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -613,6 +613,7 @@ const providerConfigSchema = z.object({
apiKeyTransport: z.enum(["x-api-key", "bearer"]).optional(),
responsesPath: z.string().min(1).optional(),
statelessResponses: z.boolean().optional(),
+ requiresAdjacentResponsesToolResults: z.boolean().optional(),
supportsServiceTier: z.boolean().optional(),
preserveResponsesReasoningContent: z.boolean().optional(),
allowPrivateNetwork: z.boolean().optional(),
@@ -1070,6 +1071,12 @@ const configSchema = z.object({
injectionModel: z.string().optional().catch(undefined),
injectionEffort: z.string().optional().catch(undefined),
syncCodexSubagentDefaults: z.boolean().optional().catch(undefined),
+ // Per-primary-model fallback chains. Values must be non-empty string arrays;
+ // malformed entries degrade to undefined rather than rejecting the whole config.
+ subagentModelFallbackByModel: z.record(
+ z.string(),
+ z.array(z.string().trim().min(1)).min(1),
+ ).optional().catch(undefined),
codexShimAutoRestore: z.boolean().optional(),
pausedCodexAccountIds: z.array(z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/)).optional(),
codexAccountNamespaces: codexAccountNamespacesSchema.optional(),
diff --git a/src/lab/artifacts/sanitize.ts b/src/lab/artifacts/sanitize.ts
new file mode 100644
index 000000000..cd9c7e81c
--- /dev/null
+++ b/src/lab/artifacts/sanitize.ts
@@ -0,0 +1,114 @@
+/**
+ * Deny-by-default sanitization before artifact hashing/writing.
+ * Never persists prompts, secrets, paths, account IDs, raw URLs, or provider bodies.
+ */
+import type { ArtifactClass } from "../constants";
+import { MAX_SANITIZED_STRING_FIELD } from "../constants";
+import { jcsStringify } from "../digest";
+import { redactSecretString } from "../../lib/redact";
+
+const FORBIDDEN_KEY = /^(?:authorization|proxy-authorization|cookie|set-cookie|api[-_]?key|x-api-key|token|secret|password|email|prompt|messages|content|body|url|hostname|baseUrl|path|account|alias)$/i;
+const SECRETISH = /sk-[a-z0-9]{10,}|Bearer\s+[A-Za-z0-9._\-]+|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}/i;
+const SECRETISH_GLOBAL = /sk-[a-z0-9]{10,}|Bearer\s+[A-Za-z0-9._\-]+|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}/gi;
+
+export function redactForArtifact(artifactClass: ArtifactClass, payload: unknown): unknown {
+ if (
+ artifactClass === "fixture" ||
+ artifactClass === "scenario_manifest" ||
+ artifactClass === "suite_manifest" ||
+ artifactClass === "claim_source_manifest"
+ ) {
+ // Contract artifacts are already synthetic/canonical. Mutating them would
+ // invalidate content-addressed digests; reject secret-shaped material instead.
+ assertNoSecretMaterial(payload, 0);
+ return payload;
+ }
+ return scrubValue(payload, 0);
+}
+
+const FORBIDDEN_CONTRACT_KEYS = /^(?:authorization|proxy-authorization|cookie|set-cookie|api[-_]?key|x-api-key|token|secret|password|email|prompt|messages|baseUrl|hostname|account|alias)$/i;
+
+function assertNoSecretMaterial(value: unknown, depth: number): void {
+ if (depth > 8) {
+ throw new Error("contract artifact exceeds sanitization inspection depth");
+ }
+ if (typeof value === "string") {
+ if (SECRETISH.test(value)) {
+ throw new Error("contract artifact contains forbidden secret-shaped material");
+ }
+ return;
+ }
+ if (Array.isArray(value)) {
+ for (const item of value) assertNoSecretMaterial(item, depth + 1);
+ return;
+ }
+ if (value && typeof value === "object") {
+ for (const [key, child] of Object.entries(value as object)) {
+ if (FORBIDDEN_CONTRACT_KEYS.test(key)) {
+ throw new Error(`contract artifact forbids key ${key}`);
+ }
+ assertNoSecretMaterial(child, depth + 1);
+ }
+ }
+}
+
+function scrubValue(value: unknown, depth: number): unknown {
+ if (depth > 8) return "[truncated_depth]";
+ if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+ if (typeof value === "string") return scrubString(value);
+ if (value instanceof Uint8Array) {
+ const text = new TextDecoder().decode(value);
+ return new TextEncoder().encode(scrubString(text));
+ }
+ if (Array.isArray(value)) {
+ if (value.length > 256) return value.slice(0, 256).map((v) => scrubValue(v, depth + 1));
+ return value.map((v) => scrubValue(v, depth + 1));
+ }
+ if (typeof value === "object") {
+ const out: Record = {};
+ const keys = Object.keys(value as object).slice(0, 64);
+ for (const key of keys) {
+ if (FORBIDDEN_KEY.test(key)) {
+ out[key] = "[redacted]";
+ continue;
+ }
+ out[key] = scrubValue((value as Record)[key], depth + 1);
+ }
+ return out;
+ }
+ return "[unsupported]";
+}
+
+function scrubString(value: string): string {
+ let s = redactSecretString(value);
+ s = s.replace(SECRETISH_GLOBAL, "[REDACTED]");
+ // Strip absolute filesystem paths (coarse)
+ s = s.replace(/(?:[A-Za-z]:\\|\/(?:home|Users|tmp|var|etc|root|mnt)\/)[^\s"']+/g, "[path]");
+ // Strip URL userinfo / private hosts roughly
+ s = s.replace(/https?:\/\/[^\s"']+/gi, (url) => {
+ try {
+ const u = new URL(url);
+ if (u.username || u.password) return "[redacted-url]";
+ if (/^(localhost|127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[0-1])\.)/i.test(u.hostname)) {
+ return `${u.protocol}//[private-host]${u.pathname}`;
+ }
+ return `${u.protocol}//[host]${u.pathname}`;
+ } catch {
+ return "[redacted-url]";
+ }
+ });
+ const bytes = new TextEncoder().encode(s);
+ if (bytes.byteLength > MAX_SANITIZED_STRING_FIELD) {
+ return new TextDecoder().decode(bytes.slice(0, MAX_SANITIZED_STRING_FIELD));
+ }
+ return s;
+}
+
+/** Stable privacy boundary for diagnostic text that may be persisted. */
+export function sanitizeDiagnostic(value: unknown): string {
+ return scrubString(value instanceof Error ? value.message : String(value));
+}
+
+export function sanitizedJsonBytes(value: unknown): Uint8Array {
+ return new TextEncoder().encode(jcsStringify(scrubValue(value, 0)));
+}
diff --git a/src/lab/artifacts/secure-fs.ts b/src/lab/artifacts/secure-fs.ts
new file mode 100644
index 000000000..421d0669b
--- /dev/null
+++ b/src/lab/artifacts/secure-fs.ts
@@ -0,0 +1,468 @@
+/**
+ * Descriptor/handle-bound, no-follow artifact I/O for the Compatibility Lab store.
+ *
+ * POSIX runtimes use directory-relative `dir` opens. Windows uses the same pinned
+ * directory identity checks as other reviewed OpenCodex bounded readers, because
+ * directory-relative child opens are not durable there.
+ */
+import {
+ closeSync,
+ constants as fsConstants,
+ existsSync,
+ fstatSync,
+ fsyncSync,
+ lstatSync,
+ mkdirSync,
+ openSync,
+ readSync,
+ renameSync,
+ unlinkSync,
+ writeSync,
+ type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import {
+ ARTIFACT_FILENAME_EXT,
+ MAX_BYTES_PER_ARTIFACT,
+} from "../constants";
+import { artifactBytesDigest, isSha256Hex } from "../digest";
+
+export class ArtifactFsError extends Error {
+ readonly code: string;
+ constructor(code: string, message: string) {
+ super(message);
+ this.name = "ArtifactFsError";
+ this.code = code;
+ }
+}
+
+export function harnessFailure(message: string, code = "harness_failure"): never {
+ throw new ArtifactFsError(code, message);
+}
+
+const O_RDONLY = fsConstants.O_RDONLY;
+const O_RDWR = fsConstants.O_RDWR;
+const O_CREAT = fsConstants.O_CREAT;
+const O_EXCL = fsConstants.O_EXCL;
+const O_NOFOLLOW = (fsConstants as { O_NOFOLLOW?: number }).O_NOFOLLOW;
+const O_DIRECTORY = (fsConstants as { O_DIRECTORY?: number }).O_DIRECTORY;
+
+type ArtifactIoMode = "dirfd" | "win32_pinned";
+
+let artifactIoMode: ArtifactIoMode | null = null;
+
+export function assertDigestName(digest: string): string {
+ if (!isSha256Hex(digest)) harnessFailure("artifact digest must be lowercase sha256 hex");
+ if (digest.includes("/") || digest.includes("\\") || digest.includes(":") || digest.includes("..")) {
+ harnessFailure("artifact digest must not contain path separators");
+ }
+ return digest;
+}
+
+export function digestFileName(digest: string): string {
+ return `${assertDigestName(digest)}${ARTIFACT_FILENAME_EXT}`;
+}
+
+function platformSupportsNoFollow(): boolean {
+ return typeof O_NOFOLLOW === "number" && O_NOFOLLOW !== 0;
+}
+
+function openFlags(base: number, noFollow: boolean): number {
+ if (noFollow && platformSupportsNoFollow()) return base | O_NOFOLLOW!;
+ return base;
+}
+
+function assertRegularFileStats(stats: Stats, label: string): void {
+ if (
+ !stats.isFile() ||
+ stats.isSymbolicLink() ||
+ stats.isDirectory() ||
+ stats.isFIFO() ||
+ stats.isSocket() ||
+ stats.isCharacterDevice() ||
+ stats.isBlockDevice()
+ ) {
+ harnessFailure(`${label}: not a regular file`, "artifact_unsafe_target");
+ }
+ if (stats.nlink !== 1) {
+ harnessFailure(`${label}: hard links prohibited (nlink=${stats.nlink})`, "artifact_unsafe_target");
+ }
+}
+
+function assertDirectoryStats(stats: Stats, label: string): void {
+ if (!stats.isDirectory() || stats.isSymbolicLink()) {
+ harnessFailure(`${label}: must be a real directory (no symlink/reparse redirection)`, "artifact_unsafe_target");
+ }
+}
+
+function identityOf(stats: Stats): string {
+ return `${stats.dev}:${stats.ino}`;
+}
+
+function assertRelativeName(name: string): void {
+ if (name.includes("..") || name.includes("/") || name.includes("\\") || name.includes("\0")) {
+ harnessFailure("invalid relative artifact name", "artifact_unsafe_target");
+ }
+}
+
+export interface TrustedArtifactDir {
+ path: string;
+ fd: number;
+ identity: string;
+}
+
+type OpenSyncWithDir = (
+ path: string,
+ flags: number,
+ mode: number,
+ options: { dir: number },
+) => number;
+
+type RenameSyncWithDir = (from: string, to: string, options: { dir: number }) => void;
+type UnlinkSyncWithDir = (path: string, options: { dir: number }) => void;
+
+function detectArtifactIoMode(dir: TrustedArtifactDir): ArtifactIoMode {
+ if (artifactIoMode !== null) return artifactIoMode;
+ if (process.platform === "win32") {
+ artifactIoMode = "win32_pinned";
+ return artifactIoMode;
+ }
+ const probe = `.dirfd-probe-${process.pid}`;
+ const finalName = `${probe}.ok`;
+ try {
+ const openWithDir = openSync as unknown as OpenSyncWithDir;
+ const fd = openWithDir(probe, O_CREAT | O_EXCL | O_RDWR, 0o600, { dir: dir.fd });
+ closeSync(fd);
+ (renameSync as unknown as RenameSyncWithDir)(probe, finalName, { dir: dir.fd });
+ if (!existsSync(join(dir.path, finalName))) {
+ artifactIoMode = "win32_pinned";
+ return artifactIoMode;
+ }
+ (unlinkSync as unknown as UnlinkSyncWithDir)(finalName, { dir: dir.fd });
+ artifactIoMode = "dirfd";
+ } catch {
+ artifactIoMode = "win32_pinned";
+ }
+ return artifactIoMode;
+}
+
+function childPath(dir: TrustedArtifactDir, name: string): string {
+ revalidateDir(dir);
+ assertRelativeName(name);
+ return join(dir.path, name);
+}
+
+function assertOpenedPathMatchesDescriptor(dir: TrustedArtifactDir, name: string, fd: number): void {
+ if (detectArtifactIoMode(dir) !== "win32_pinned") return;
+ const opened = fstatSync(fd);
+ assertRegularFileStats(opened, "artifact fd");
+ const pathEntry = lstatSync(childPath(dir, name));
+ if (
+ !pathEntry.isFile() ||
+ pathEntry.isSymbolicLink() ||
+ pathEntry.dev !== opened.dev ||
+ pathEntry.ino !== opened.ino
+ ) {
+ closeSync(fd);
+ harnessFailure("artifact path identity mismatch after open", "artifact_unsafe_target");
+ }
+}
+
+function openAtDir(dir: TrustedArtifactDir, name: string, flags: number, mode = 0): number {
+ revalidateDir(dir);
+ assertRelativeName(name);
+ const mode_ = detectArtifactIoMode(dir);
+ if (mode_ === "dirfd") {
+ return (openSync as unknown as OpenSyncWithDir)(name, flags, mode, { dir: dir.fd });
+ }
+ const fd = openSync(childPath(dir, name), flags, mode);
+ assertOpenedPathMatchesDescriptor(dir, name, fd);
+ return fd;
+}
+
+function renameAtDir(dir: TrustedArtifactDir, from: string, to: string): void {
+ revalidateDir(dir);
+ assertRelativeName(from);
+ assertRelativeName(to);
+ if (detectArtifactIoMode(dir) === "dirfd") {
+ (renameSync as unknown as RenameSyncWithDir)(from, to, { dir: dir.fd });
+ return;
+ }
+ renameSync(childPath(dir, from), childPath(dir, to));
+}
+
+function unlinkAtDir(dir: TrustedArtifactDir, name: string): void {
+ revalidateDir(dir);
+ assertRelativeName(name);
+ if (detectArtifactIoMode(dir) === "dirfd") {
+ (unlinkSync as unknown as UnlinkSyncWithDir)(name, { dir: dir.fd });
+ return;
+ }
+ unlinkSync(childPath(dir, name));
+}
+
+function revalidateDir(dir: TrustedArtifactDir): void {
+ const stats = fstatSync(dir.fd);
+ assertDirectoryStats(stats, "artifacts dir");
+ if (identityOf(stats) !== dir.identity) {
+ harnessFailure("artifacts directory identity changed", "artifact_unsafe_target");
+ }
+}
+
+export function openTrustedArtifactDir(artifactsDir: string): TrustedArtifactDir {
+ const abs = artifactsDir.replace(/[\\/]+$/, "");
+ if (abs.includes("\0")) harnessFailure("NUL in artifacts path", "artifact_unsafe_target");
+ mkdirSync(abs, { recursive: true, mode: 0o700 });
+
+ let fd: number;
+ if (typeof O_DIRECTORY === "number") {
+ try {
+ fd = openSync(abs, openFlags(O_RDONLY | O_DIRECTORY, true));
+ } catch {
+ harnessFailure("failed to open artifacts directory with O_DIRECTORY", "artifact_unsafe_target");
+ }
+ } else {
+ fd = openSync(abs, O_RDONLY);
+ }
+
+ const stats = fstatSync(fd);
+ assertDirectoryStats(stats, "artifacts dir");
+ const trusted = { path: abs, fd, identity: identityOf(stats) };
+ detectArtifactIoMode(trusted);
+ return trusted;
+}
+
+export function closeTrustedArtifactDir(dir: TrustedArtifactDir): void {
+ try {
+ closeSync(dir.fd);
+ } catch {
+ /* ignore */
+ }
+}
+
+export interface StoredArtifactBytes {
+ digest: string;
+ bytes: Uint8Array;
+ byteCount: number;
+}
+
+export interface ReadArtifactOptions {
+ expectedByteCount?: number;
+ contentDigest?: (bytes: Uint8Array) => string;
+}
+
+function readAllFromFd(fd: number, size: number): Buffer {
+ const buf = Buffer.alloc(size);
+ let offset = 0;
+ while (offset < buf.length) {
+ const n = readSync(fd, buf, offset, buf.length - offset, offset);
+ if (n <= 0) break;
+ offset += n;
+ }
+ if (offset !== size) harnessFailure("short read from artifact descriptor", "artifact_mismatch");
+ return buf;
+}
+
+function isRawMissingError(err: unknown): boolean {
+ return !!err && typeof err === "object" && "code" in err && (err as { code: string }).code === "ENOENT";
+}
+
+function isMissingArtifactError(err: unknown): boolean {
+ return isRawMissingError(err) || (err instanceof ArtifactFsError && err.code === "artifact_missing");
+}
+
+function assertArtifactTargetCreatable(dir: TrustedArtifactDir, name: string): void {
+ revalidateDir(dir);
+ assertRelativeName(name);
+ try {
+ const stats = lstatSync(childPath(dir, name));
+ if (stats.isSymbolicLink()) {
+ harnessFailure("artifact target is a symbolic link", "artifact_unsafe_target");
+ }
+ assertRegularFileStats(stats, "artifact create target");
+ harnessFailure("artifact target exists but is not reusable", "artifact_unsafe_target");
+ } catch (err) {
+ if (isRawMissingError(err)) return;
+ if (err instanceof ArtifactFsError) throw err;
+ harnessFailure(
+ `artifact create target check failed: ${err instanceof Error ? err.message : String(err)}`,
+ "artifact_unsafe_target",
+ );
+ }
+}
+
+function writeAll(fd: number, bytes: Uint8Array): void {
+ let offset = 0;
+ while (offset < bytes.byteLength) {
+ const n = writeSync(fd, bytes, offset, bytes.byteLength - offset);
+ if (n <= 0) harnessFailure("artifact write made no progress", "artifact_mismatch");
+ offset += n;
+ }
+}
+
+function writeTempArtifact(
+ dir: TrustedArtifactDir,
+ tmpName: string,
+ bytes: Uint8Array,
+ digest: string,
+ contentDigest: (b: Uint8Array) => string,
+): void {
+ let fd: number | null = null;
+ try {
+ fd = openAtDir(dir, tmpName, openFlags(O_RDWR | O_CREAT | O_EXCL, true), 0o600);
+ writeAll(fd, bytes);
+ fsyncSync(fd);
+ const stats = fstatSync(fd);
+ assertRegularFileStats(stats, "artifact temp");
+ if (stats.size !== bytes.byteLength) {
+ harnessFailure("size mismatch after write", "artifact_mismatch");
+ }
+ const buf = readAllFromFd(fd, bytes.byteLength);
+ if (contentDigest(buf) !== digest) {
+ harnessFailure("digest mismatch on same descriptor", "artifact_mismatch");
+ }
+ closeSync(fd);
+ fd = null;
+ renameAtDir(dir, tmpName, digestFileName(digest));
+ } catch (err) {
+ if (fd !== null) {
+ try { closeSync(fd); } catch { /* ignore */ }
+ }
+ try {
+ unlinkAtDir(dir, tmpName);
+ } catch {
+ /* ignore cleanup */
+ }
+ if (err instanceof ArtifactFsError) throw err;
+ harnessFailure(`artifact write failed: ${err instanceof Error ? err.message : String(err)}`);
+ }
+}
+
+export function readArtifactBytes(
+ dir: TrustedArtifactDir,
+ digest: string,
+ expectedByteCountOrOpts?: number | ReadArtifactOptions,
+): StoredArtifactBytes {
+ const opts: ReadArtifactOptions =
+ typeof expectedByteCountOrOpts === "number"
+ ? { expectedByteCount: expectedByteCountOrOpts }
+ : expectedByteCountOrOpts ?? {};
+ const contentDigest = opts.contentDigest ?? artifactBytesDigest;
+ revalidateDir(dir);
+ assertDigestName(digest);
+ const name = digestFileName(digest);
+
+ let fd: number | null = null;
+ try {
+ fd = openAtDir(dir, name, openFlags(O_RDONLY, true));
+ const stats = fstatSync(fd);
+ assertRegularFileStats(stats, "artifact fd");
+ if (opts.expectedByteCount !== undefined && stats.size !== opts.expectedByteCount) {
+ harnessFailure("artifact size mismatch on descriptor", "artifact_mismatch");
+ }
+ if (stats.size > MAX_BYTES_PER_ARTIFACT) {
+ harnessFailure("artifact exceeds ceiling", "artifact_mismatch");
+ }
+ const buf = readAllFromFd(fd, stats.size);
+ const got = contentDigest(buf);
+ if (got !== digest) harnessFailure("artifact digest mismatch on descriptor", "artifact_mismatch");
+ return { digest, bytes: new Uint8Array(buf), byteCount: stats.size };
+ } catch (err) {
+ if (isRawMissingError(err)) {
+ harnessFailure(`artifact missing: ${digest}`, "artifact_missing");
+ }
+ if (err instanceof ArtifactFsError) throw err;
+ harnessFailure(`artifact read failed: ${err instanceof Error ? err.message : String(err)}`);
+ } finally {
+ if (fd !== null) closeSync(fd);
+ }
+ harnessFailure("artifact read failed");
+}
+
+export function putArtifactBytes(
+ dir: TrustedArtifactDir,
+ bytes: Uint8Array,
+ expectedDigest?: string,
+): StoredArtifactBytes {
+ revalidateDir(dir);
+ if (bytes.byteLength > MAX_BYTES_PER_ARTIFACT) {
+ harnessFailure(`artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
+ }
+ const digest = artifactBytesDigest(bytes);
+ if (expectedDigest !== undefined) {
+ assertDigestName(expectedDigest);
+ if (digest !== expectedDigest) {
+ harnessFailure("artifact digest mismatch before write", "artifact_mismatch");
+ }
+ }
+
+ try {
+ return readArtifactBytes(dir, digest, bytes.byteLength);
+ } catch (err) {
+ if (!isMissingArtifactError(err)) throw err;
+ }
+
+ assertArtifactTargetCreatable(dir, digestFileName(digest));
+ const tmpName = `.tmp-${digest}-${process.pid}-${Date.now()}.partial`;
+ writeTempArtifact(dir, tmpName, bytes, digest, artifactBytesDigest);
+ return readArtifactBytes(dir, digest, bytes.byteLength);
+}
+
+export function putNamedDigestBytes(
+ dir: TrustedArtifactDir,
+ digest: string,
+ bytes: Uint8Array,
+ contentDigest: (b: Uint8Array) => string,
+): StoredArtifactBytes {
+ revalidateDir(dir);
+ assertDigestName(digest);
+ if (bytes.byteLength > MAX_BYTES_PER_ARTIFACT) {
+ harnessFailure(`artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
+ }
+ if (contentDigest(bytes) !== digest) {
+ harnessFailure("named artifact content digest mismatch before write", "artifact_mismatch");
+ }
+
+ try {
+ return readArtifactBytes(dir, digest, { expectedByteCount: bytes.byteLength, contentDigest });
+ } catch (err) {
+ if (!isMissingArtifactError(err)) throw err;
+ }
+
+ assertArtifactTargetCreatable(dir, digestFileName(digest));
+ const tmpName = `.tmp-${digest}-${process.pid}-${Date.now()}.partial`;
+ writeTempArtifact(dir, tmpName, bytes, digest, contentDigest);
+ return readArtifactBytes(dir, digest, { expectedByteCount: bytes.byteLength, contentDigest });
+}
+
+export function deleteArtifactBytes(dir: TrustedArtifactDir, digest: string): void {
+ revalidateDir(dir);
+ assertDigestName(digest);
+ const name = digestFileName(digest);
+ try {
+ unlinkAtDir(dir, name);
+ } catch (err) {
+ if (isRawMissingError(err)) return;
+ if (err instanceof ArtifactFsError) throw err;
+ harnessFailure(`artifact delete failed: ${err instanceof Error ? err.message : String(err)}`);
+ }
+}
+
+export function artifactExists(dir: TrustedArtifactDir, digest: string): boolean {
+ revalidateDir(dir);
+ assertDigestName(digest);
+ try {
+ const fd = openAtDir(dir, digestFileName(digest), openFlags(O_RDONLY, true));
+ try {
+ const stats = fstatSync(fd);
+ assertRegularFileStats(stats, "artifact exists");
+ return true;
+ } finally {
+ closeSync(fd);
+ }
+ } catch (err) {
+ if (isMissingArtifactError(err)) return false;
+ if (err instanceof ArtifactFsError) throw err;
+ harnessFailure(`artifact exists check failed: ${err instanceof Error ? err.message : String(err)}`);
+ }
+}
diff --git a/src/lab/artifacts/store.ts b/src/lab/artifacts/store.ts
new file mode 100644
index 000000000..83ad5e118
--- /dev/null
+++ b/src/lab/artifacts/store.ts
@@ -0,0 +1,282 @@
+import { MAX_BYTES_PER_ARTIFACT, MAX_AGGREGATE_ARTIFACT_BYTES, MAX_ARTIFACTS_PER_RUN, ARTIFACT_FILENAME_EXT, type ArtifactClass, type ContractArtifactClass } from "../constants";
+import {
+ artifactBytesDigest,
+ claimSourceManifestDigest,
+ fixtureDigest,
+ isSha256Hex,
+ jcsStringify,
+ scenarioManifestDigest,
+ suiteManifestDigest,
+} from "../digest";
+import type { ArtifactRefV1, ClaimSourceManifestV1 } from "../events/types";
+import { artifactClassMediaType, validateClaimSourceManifest } from "../events/validate";
+import {
+ closeTrustedArtifactDir,
+ ArtifactFsError,
+ deleteArtifactBytes,
+ openTrustedArtifactDir,
+ putArtifactBytes,
+ putNamedDigestBytes,
+ readArtifactBytes,
+ type TrustedArtifactDir,
+} from "./secure-fs";
+import { redactForArtifact, sanitizeDiagnostic } from "./sanitize";
+
+export { ArtifactFsError, openTrustedArtifactDir };
+export type { TrustedArtifactDir };
+
+export interface PutArtifactInput {
+ artifactClass: ArtifactClass;
+ /** Pre-redaction payload; sanitizer runs before hash/write. */
+ payload: Uint8Array | string | unknown;
+ mediaType?: string;
+ redactionPolicy?: string;
+ /** For contract artifacts whose digest uses a domain other than artifact-bytes. */
+ expectedDigest?: string;
+}
+
+export interface ArtifactReadOptions {
+ expectedByteCount?: number;
+ artifactClass?: ArtifactClass;
+}
+
+export interface ArtifactStore {
+ dir: TrustedArtifactDir;
+ put(input: PutArtifactInput): ArtifactRefV1;
+ get(digest: string, expectedByteCountOrOpts?: number | ArtifactReadOptions): Uint8Array;
+ getVerified(
+ digest: string,
+ expectedByteCountOrOpts?: number | ArtifactReadOptions,
+ ): { bytes: Uint8Array; digest: string };
+ remove(digest: string): void;
+ close(): void;
+}
+
+function toBytes(payload: Uint8Array | string | unknown): Uint8Array {
+ if (payload instanceof Uint8Array) return payload;
+ if (typeof payload === "string") return new TextEncoder().encode(payload);
+ return new TextEncoder().encode(jcsStringify(payload));
+}
+
+function normalizeReadOptions(value?: number | ArtifactReadOptions): ArtifactReadOptions {
+ return typeof value === "number" ? { expectedByteCount: value } : value ?? {};
+}
+
+function jsonDigest(
+ digest: (value: Record) => string,
+): (bytes: Uint8Array) => string {
+ return (bytes) => digest(JSON.parse(new TextDecoder().decode(bytes)) as Record);
+}
+
+function digestForArtifactClass(artifactClass: ArtifactClass): (bytes: Uint8Array) => string {
+ switch (artifactClass) {
+ case "fixture":
+ return fixtureDigest;
+ case "scenario_manifest":
+ return jsonDigest(scenarioManifestDigest);
+ case "suite_manifest":
+ return jsonDigest(suiteManifestDigest);
+ case "claim_source_manifest":
+ return (bytes) => {
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
+ return claimSourceManifestDigest(validateClaimSourceManifest(parsed).manifest);
+ };
+ default:
+ return artifactBytesDigest;
+ }
+}
+
+export function createArtifactStore(artifactsDir: string): ArtifactStore {
+ const dir = openTrustedArtifactDir(artifactsDir);
+ let aggregateBytes = 0;
+ let putCount = 0;
+
+ const getVerified = (
+ digest: string,
+ expectedByteCountOrOpts?: number | ArtifactReadOptions,
+ ): { bytes: Uint8Array; digest: string } => {
+ const opts = normalizeReadOptions(expectedByteCountOrOpts);
+ const candidates = opts.artifactClass
+ ? [digestForArtifactClass(opts.artifactClass)]
+ : [
+ artifactBytesDigest,
+ fixtureDigest,
+ jsonDigest(scenarioManifestDigest),
+ jsonDigest(suiteManifestDigest),
+ digestForArtifactClass("claim_source_manifest"),
+ ];
+
+ let lastErr: unknown;
+ for (const contentDigest of candidates) {
+ try {
+ const got = readArtifactBytes(dir, digest, {
+ expectedByteCount: opts.expectedByteCount,
+ contentDigest,
+ });
+ return { bytes: got.bytes, digest: got.digest };
+ } catch (err) {
+ lastErr = err;
+ if (
+ err instanceof ArtifactFsError &&
+ err.code !== "artifact_mismatch" &&
+ !err.message.includes("mismatch")
+ ) {
+ throw err;
+ }
+ }
+ }
+ throw lastErr instanceof Error
+ ? lastErr
+ : new ArtifactFsError("artifact_mismatch", "artifact digest verification failed");
+ };
+
+ return {
+ dir,
+ put(input: PutArtifactInput): ArtifactRefV1 {
+ if (putCount >= MAX_ARTIFACTS_PER_RUN) {
+ throw new ArtifactFsError("budget_exhausted", "maximum artifacts per run exceeded");
+ }
+ if (input.payload instanceof Uint8Array && input.payload.byteLength > MAX_BYTES_PER_ARTIFACT) {
+ throw new ArtifactFsError("budget_exhausted", `artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
+ }
+ if (typeof input.payload === "string" && new TextEncoder().encode(input.payload).byteLength > MAX_BYTES_PER_ARTIFACT) {
+ throw new ArtifactFsError("budget_exhausted", `artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
+ }
+ const redacted = redactForArtifact(input.artifactClass, input.payload);
+ const bytes = toBytes(redacted);
+ if (bytes.byteLength > MAX_BYTES_PER_ARTIFACT) {
+ throw new ArtifactFsError("budget_exhausted", `artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
+ }
+ if (aggregateBytes + bytes.byteLength > MAX_AGGREGATE_ARTIFACT_BYTES) {
+ throw new ArtifactFsError("budget_exhausted", "aggregate artifact ceiling exceeded");
+ }
+
+ let stored;
+ if (isContractClass(input.artifactClass)) {
+ const contractClass = input.artifactClass;
+ const computedDigest = computeContractDigest(contractClass, bytes, redacted);
+ if (input.expectedDigest !== undefined && computedDigest !== input.expectedDigest) {
+ throw new ArtifactFsError("artifact_mismatch", "contract artifact digest mismatch");
+ }
+ stored = putNamedDigestBytes(
+ dir,
+ computedDigest,
+ bytes,
+ digestForArtifactClass(contractClass),
+ );
+ } else {
+ stored = putArtifactBytes(dir, bytes, input.expectedDigest);
+ }
+
+ putCount += 1;
+ aggregateBytes += stored.byteCount;
+ return {
+ digest: stored.digest,
+ mediaType: input.mediaType ?? artifactClassMediaType(input.artifactClass),
+ byteCount: stored.byteCount,
+ redactionPolicy: input.redactionPolicy ?? defaultRedactionPolicy(input.artifactClass),
+ relativePath: `${stored.digest}${ARTIFACT_FILENAME_EXT}`,
+ artifactClass: input.artifactClass,
+ };
+ },
+ get(digest: string, expectedByteCountOrOpts?: number | ArtifactReadOptions): Uint8Array {
+ return getVerified(digest, expectedByteCountOrOpts).bytes;
+ },
+ getVerified,
+ remove(digest: string): void {
+ deleteArtifactBytes(dir, digest);
+ },
+ close(): void {
+ closeTrustedArtifactDir(dir);
+ },
+ };
+}
+
+function isContractClass(c: ArtifactClass): c is ContractArtifactClass {
+ return (
+ c === "scenario_manifest" ||
+ c === "suite_manifest" ||
+ c === "fixture" ||
+ c === "claim_source_manifest"
+ );
+}
+
+function computeContractDigest(
+ artifactClass: ContractArtifactClass,
+ bytes: Uint8Array,
+ redacted: unknown,
+): string {
+ switch (artifactClass) {
+ case "fixture":
+ return fixtureDigest(bytes);
+ case "scenario_manifest":
+ return scenarioManifestDigest(
+ typeof redacted === "object" && redacted ? (redacted as Record) : JSON.parse(new TextDecoder().decode(bytes)),
+ );
+ case "suite_manifest":
+ return suiteManifestDigest(
+ typeof redacted === "object" && redacted ? (redacted as Record) : JSON.parse(new TextDecoder().decode(bytes)),
+ );
+ case "claim_source_manifest": {
+ const parsed = typeof redacted === "object" && redacted
+ ? redacted
+ : JSON.parse(new TextDecoder().decode(bytes));
+ return claimSourceManifestDigest(validateClaimSourceManifest(parsed).manifest);
+ }
+ default: {
+ const _never: never = artifactClass;
+ return _never;
+ }
+ }
+}
+
+function defaultRedactionPolicy(artifactClass: ArtifactClass): string {
+ switch (artifactClass) {
+ case "scenario_manifest":
+ case "suite_manifest":
+ case "fixture":
+ case "claim_source_manifest":
+ return "contract_canonical_v1";
+ default:
+ return "sanitized_evidence_v1";
+ }
+}
+
+export function putClaimSourceManifest(
+ store: ArtifactStore,
+ manifest: ClaimSourceManifestV1,
+): ArtifactRefV1 {
+ const { manifest: validated, digest } = validateClaimSourceManifest(manifest);
+ return store.put({
+ artifactClass: "claim_source_manifest",
+ payload: validated,
+ expectedDigest: digest,
+ });
+}
+
+export type LoadClaimSourceManifestResult =
+ | { ok: true; manifest: ClaimSourceManifestV1; corruption?: undefined }
+ | { ok: false; manifest: ClaimSourceManifestV1 | null; corruption: string };
+
+export function loadClaimSourceManifest(
+ store: ArtifactStore,
+ digest: string,
+ expected: { subjectId: string; capability: string },
+): LoadClaimSourceManifestResult {
+ if (!isSha256Hex(digest)) return { ok: false, manifest: null, corruption: "invalid digest" };
+ try {
+ const bytes = store.get(digest, { artifactClass: "claim_source_manifest" });
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
+ const { manifest, digest: recomputed } = validateClaimSourceManifest(parsed);
+ if (recomputed !== digest) return { ok: false, manifest, corruption: "claim-source digest mismatch" };
+ if (manifest.subjectId !== expected.subjectId) return { ok: false, manifest, corruption: "claim-source subjectId mismatch" };
+ if (manifest.capability !== expected.capability) return { ok: false, manifest, corruption: "claim-source capability mismatch" };
+ return { ok: true, manifest };
+ } catch (err) {
+ return {
+ ok: false,
+ manifest: null,
+ corruption: sanitizeDiagnostic(err),
+ };
+ }
+}
diff --git a/src/lab/conformance/assertion.ts b/src/lab/conformance/assertion.ts
new file mode 100644
index 000000000..adc94fd4f
--- /dev/null
+++ b/src/lab/conformance/assertion.ts
@@ -0,0 +1,325 @@
+import { jcsEqual } from "./jcs";
+import { pointerExists, resolveJsonPointer } from "./json-pointer";
+import type { AssertionResult, AssertionSpec, NormalizedObservation } from "./types";
+
+const ID_GRAMMARS: Record = {
+ responses_message: /^msg_[A-Za-z0-9_-]{1,128}$/,
+ responses_reasoning: /^rs_[A-Za-z0-9_-]{1,128}$/,
+ responses_call: /^call_[A-Za-z0-9_-]{1,128}$/,
+ nonempty_128: /^[^\s]{1,128}$/,
+};
+
+export function evaluateAssertion(
+ assertion: AssertionSpec,
+ observation: NormalizedObservation,
+): AssertionResult {
+ const base: AssertionResult = {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: "",
+ };
+
+ try {
+ switch (assertion.operator) {
+ case "http_status_equals":
+ return evaluateEquals(assertion, observation, (obs) => obs.client.response.status);
+ case "json_path_equals":
+ return evaluateJsonPathEquals(assertion, observation);
+ case "json_path_present":
+ return evaluatePresence(assertion, observation, true);
+ case "json_path_absent":
+ return evaluatePresence(assertion, observation, false);
+ case "sse_event_sequence":
+ return evaluateEventSequence(assertion, observation);
+ case "sse_event_count":
+ return evaluateEventCount(assertion, observation);
+ case "terminal_signal_equals":
+ return evaluateEquals(assertion, observation, (obs) => obs.client.response.terminal);
+ case "id_matches":
+ return evaluateIdMatches(assertion, observation);
+ case "id_stable_across_events":
+ return evaluateIdStable(assertion, observation);
+ case "id_correlates":
+ return evaluateIdCorrelates(assertion, observation);
+ case "tool_call_equals":
+ return evaluateJsonPathEquals(assertion, observation);
+ case "tool_result_correlates":
+ return evaluateToolResultCorrelates(assertion, observation);
+ case "normalized_text_equals":
+ return evaluateEquals(assertion, observation, (obs) => obs.client.response.normalizedText);
+ case "verifier_result_equals":
+ return evaluateJsonPathEquals(assertion, observation);
+ default:
+ return {
+ ...base,
+ passed: false,
+ observedSummary: `unknown operator ${assertion.operator}`,
+ reason: "unknown_operator",
+ };
+ }
+ } catch (error) {
+ return {
+ ...base,
+ passed: false,
+ observedSummary: String(error),
+ reason: "evaluation_error",
+ };
+ }
+}
+
+function evaluateEquals(
+ assertion: AssertionSpec,
+ observation: NormalizedObservation,
+ pick: (obs: NormalizedObservation) => unknown,
+): AssertionResult {
+ const observed = pick(observation);
+ const passed = jcsEqual(observed, assertion.expected);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: summarize(observed),
+ reason: passed ? undefined : "value_mismatch",
+ };
+}
+
+function evaluateJsonPathEquals(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const resolved = resolveJsonPointer(observation, assertion.selector);
+ if (!resolved.ok) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: resolved.reason,
+ reason: resolved.reason,
+ };
+ }
+ const passed = jcsEqual(resolved.value, assertion.expected);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: summarize(resolved.value),
+ reason: passed ? undefined : "value_mismatch",
+ };
+}
+
+function evaluatePresence(
+ assertion: AssertionSpec,
+ observation: NormalizedObservation,
+ shouldExist: boolean,
+): AssertionResult {
+ const exists = pointerExists(observation, assertion.selector);
+ const passed = shouldExist ? exists : !exists;
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: exists ? "present" : "absent",
+ reason: passed ? undefined : shouldExist ? "selector_missing" : "selector_present",
+ };
+}
+
+function evaluateEventSequence(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const events = observation.client.response.events.map((e) => e.event);
+ const expected = assertion.expected as string[];
+ const passed = Array.isArray(expected)
+ && events.length === expected.length
+ && events.every((e, i) => e === expected[i]);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: summarize(events),
+ reason: passed ? undefined : "event_sequence_mismatch",
+ };
+}
+
+function evaluateEventCount(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const spec = assertion.expected as { event: string; count: number };
+ const count = observation.client.response.events.filter((e) => e.event === spec.event).length;
+ const passed = count === spec.count;
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: String(count),
+ reason: passed ? undefined : "event_count_mismatch",
+ };
+}
+
+function evaluateIdMatches(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const resolved = resolveJsonPointer(observation, assertion.selector);
+ if (!resolved.ok) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: resolved.reason,
+ reason: resolved.reason,
+ };
+ }
+ const grammar = ID_GRAMMARS[String(assertion.expected)];
+ const value = typeof resolved.value === "string" ? resolved.value : "";
+ const passed = grammar ? grammar.test(value) : false;
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: value,
+ reason: passed ? undefined : "id_grammar_mismatch",
+ };
+}
+
+function evaluateIdStable(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const pointers = assertion.expected;
+ if (!Array.isArray(pointers) || pointers.length < 2 || !pointers.every((p) => typeof p === "string")) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: "expected at least two pointers",
+ reason: "invalid_expected",
+ };
+ }
+ const values: string[] = [];
+ for (const pointer of pointers) {
+ const resolved = resolveJsonPointer(observation, pointer);
+ if (!resolved.ok) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: resolved.reason,
+ reason: resolved.reason,
+ };
+ }
+ if (typeof resolved.value !== "string") {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: "identifier must be a string",
+ reason: "selector_type_mismatch",
+ };
+ }
+ values.push(resolved.value);
+ }
+ const passed = values.every((v) => v === values[0]);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: summarize(values),
+ reason: passed ? undefined : "id_not_stable",
+ };
+}
+
+function correlatedIds(left: unknown, right: unknown): boolean {
+ return typeof left === "string"
+ && typeof right === "string"
+ && left.length > 0
+ && right.length > 0
+ && left === right;
+}
+
+function evaluateIdCorrelates(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const pointers = assertion.expected;
+ if (!Array.isArray(pointers) || pointers.length !== 2 || !pointers.every((p) => typeof p === "string")) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: "expected two pointers",
+ reason: "invalid_expected",
+ };
+ }
+ const left = resolveJsonPointer(observation, pointers[0]);
+ const right = resolveJsonPointer(observation, pointers[1]);
+ if (!left.ok || !right.ok) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: left.ok ? (right as { reason: string }).reason : (left as { reason: string }).reason,
+ reason: "selector_missing",
+ };
+ }
+ const passed = correlatedIds(left.value, right.value);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: `${summarize(left.value)} vs ${summarize(right.value)}`,
+ reason: passed ? undefined : "id_correlation_mismatch",
+ };
+}
+
+function evaluateToolResultCorrelates(assertion: AssertionSpec, observation: NormalizedObservation): AssertionResult {
+ const spec = assertion.expected as { call?: unknown; result?: unknown };
+ if (!spec || typeof spec.call !== "string" || typeof spec.result !== "string") {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: "expected call/result pointers",
+ reason: "invalid_expected",
+ };
+ }
+ const call = resolveJsonPointer(observation, spec.call);
+ const result = resolveJsonPointer(observation, spec.result);
+ if (!call.ok || !result.ok) {
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed: false,
+ observedSummary: call.ok ? (result as { reason: string }).reason : (call as { reason: string }).reason,
+ reason: "selector_missing",
+ };
+ }
+ const passed = correlatedIds(call.value, result.value);
+ return {
+ id: assertion.id,
+ operator: assertion.operator,
+ required: assertion.required,
+ passed,
+ observedSummary: `${summarize(call.value)} -> ${summarize(result.value)}`,
+ reason: passed ? undefined : "tool_result_correlation_mismatch",
+ };
+}
+
+function summarize(value: unknown): string {
+ if (typeof value === "string") return value.length > 120 ? value.slice(0, 120) + "…" : value;
+ try {
+ const text = JSON.stringify(value);
+ return text.length > 200 ? text.slice(0, 200) + "…" : text;
+ } catch {
+ return String(value);
+ }
+}
+
+export function evaluateAssertions(
+ assertions: AssertionSpec[],
+ observation: NormalizedObservation,
+): AssertionResult[] {
+ return assertions.map((a) => evaluateAssertion(a, observation));
+}
diff --git a/src/lab/conformance/digest.ts b/src/lab/conformance/digest.ts
new file mode 100644
index 000000000..d6e5baea9
--- /dev/null
+++ b/src/lab/conformance/digest.ts
@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+import { jcsStringify } from "./jcs";
+
+function domainHash(domain: string, payload: Uint8Array | string): string {
+ const hash = createHash("sha256");
+ hash.update(new TextEncoder().encode(`${domain}\0`));
+ if (typeof payload === "string") hash.update(new TextEncoder().encode(payload));
+ else hash.update(payload);
+ return hash.digest("hex");
+}
+
+export function fixtureDigest(bytes: Uint8Array): string {
+ return domainHash("ocx-lab:fixture:v1", bytes);
+}
+
+export function scenarioManifestDigest(expandedScenario: Record): string {
+ return domainHash("ocx-lab:scenario-manifest:v1", jcsStringify(expandedScenario));
+}
+
+export function suiteManifestDigest(expandedSuite: Record): string {
+ return domainHash("ocx-lab:suite-manifest:v1", jcsStringify(expandedSuite));
+}
diff --git a/src/lab/conformance/executor.ts b/src/lab/conformance/executor.ts
new file mode 100644
index 000000000..68e17b1f5
--- /dev/null
+++ b/src/lab/conformance/executor.ts
@@ -0,0 +1,732 @@
+import { createOpenAIChatAdapter } from "../../adapters/openai-chat";
+import { createResponsesPassthroughAdapter } from "../../adapters/openai-responses";
+import { bridgeToResponsesSSE, buildResponseJSON } from "../../bridge";
+import { anthropicToResponsesTranslation } from "../../claude/inbound";
+import { responsesSseToAnthropicSse } from "../../claude/outbound";
+import { createTranslatorBudget } from "../../lib/translator-budget";
+import { parseRequest } from "../../responses/parser";
+import {
+ clearResponseStateForTests,
+ expandPreviousResponseInput,
+ rememberResponseState,
+} from "../../responses/state";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../types";
+import { evaluateAssertions } from "./assertion";
+import { fixtureProviderConfig, upstreamAdapterForProtocol } from "./fixture-provider";
+import { withHarnessTranslatorBudget } from "./harness-budget";
+import { attachMcpVerifiers, executeMcpSyntheticAction } from "./mcp-stub";
+import {
+ attachVerifiers,
+ emptyObservation,
+ finalizeObservation,
+ filterAnthropicEvents,
+ recordUpstreamRequest,
+} from "./observation";
+import { normalizeSseBytes } from "./sse-normalize";
+import type { CaseRecord, NormalizedObservation, ScenarioRunResult, ProtocolExecutionContextV1 } from "./types";
+
+export function resolveProtocolExecutionContext(caseRecord: CaseRecord): ProtocolExecutionContextV1 {
+ const inbound = caseRecord.requirements.inboundProtocols[0] ?? "openai-responses";
+ const upstream = caseRecord.requirements.upstreamProtocols[0] ?? "openai-chat";
+ let surface = caseRecord.requirements.surfaces[0] ?? "responses-http";
+ if (caseRecord.id === "responses-core.protocol.json-sse-equivalence") {
+ surface = "responses-sse";
+ } else if (caseRecord.requirements.surfaces.length === 1) {
+ surface = caseRecord.requirements.surfaces[0]!;
+ }
+ return { inboundProtocol: inbound, upstreamProtocol: upstream, surface };
+}
+
+async function collectAdapterEvents(gen: AsyncGenerator): Promise {
+ const events: AdapterEvent[] = [];
+ for await (const event of gen) events.push(event);
+ return events;
+}
+
+export function nonstreamObservationJson(
+ parsedEvents: AdapterEvent[],
+ responseJson: Record,
+ model = "fixture-model",
+): Record {
+ return parsedEvents.length > 0
+ ? buildResponseJSON(parsedEvents, model) as Record
+ : responseJson;
+}
+
+async function collectBridgeSse(events: AdapterEvent[], model = "fixture-model"): Promise<{
+ events: ReturnType;
+}> {
+ async function* replay(): AsyncGenerator {
+ for (const event of events) yield event;
+ }
+ const stream = bridgeToResponsesSSE(replay(), model, undefined, new Set(["apply_patch"]));
+ const reader = stream.getReader();
+ const decoder = new TextDecoder();
+ let text = "";
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ text += decoder.decode(value, { stream: true });
+ }
+ text += decoder.decode();
+ } finally {
+ reader.releaseLock();
+ }
+ // bridgeToResponsesSSE appends a client-transport [DONE] padding frame. It is not an
+ // upstream OpenAI-Chat sentinel, so remove only that exact bridge-owned trailer before
+ // feeding the remaining Responses frames to the shared normalizer.
+ const trailer = "data: [DONE]\n\n";
+ const framed = text.endsWith(trailer) ? text.slice(0, -trailer.length) : text;
+ return { events: normalizeSseBytes(new TextEncoder().encode(framed), "openai-responses") };
+}
+
+async function parseUpstreamSse(adapter: ReturnType, body: string): Promise {
+ const budget = createTranslatorBudget();
+ try {
+ const response = new Response(body, { status: 200, headers: { "Content-Type": "text/event-stream" } });
+ return await collectAdapterEvents(adapter.parseStream(response, budget));
+ } finally {
+ budget.dispose();
+ }
+}
+
+function parsedFromContext(vector: Record): OcxParsedRequest {
+ const context = vector.context as Record | undefined;
+ const options = vector.options as Record | undefined;
+ const messages = context?.messages as Array> | undefined;
+ const input = messages
+ ? messages.map((m) => ({ role: m.role, content: m.content }))
+ : vector.input ?? "PING";
+ const body: Record = {
+ model: vector.modelId ?? "fixture-model",
+ input,
+ stream: vector.stream ?? false,
+ ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+ ...(options?.reasoning !== undefined ? { reasoning: { effort: options.reasoning } } : {}),
+ ...(options?.textFormat ? { text: { format: options.textFormat } } : {}),
+ ...(vector.tools ? { tools: normalizeTools(vector.tools as unknown[]) } : {}),
+ ...(vector.tool_choice ? { tool_choice: vector.tool_choice } : {}),
+ ...(vector.text ? { text: vector.text } : {}),
+ };
+ if (context?.systemPrompt) body.instructions = (context.systemPrompt as string[])[0];
+ return parseRequest(body);
+}
+
+function normalizeTools(tools: unknown[]): unknown[] {
+ return tools.map((tool) => {
+ if (!tool || typeof tool !== "object") return tool;
+ const rec = tool as Record;
+ if (!rec.type && rec.name && rec.parameters) return { type: "function", ...rec };
+ return tool;
+ });
+}
+
+function createHarnessAdapter(provider: OcxProviderConfig) {
+ return withHarnessTranslatorBudget(
+ provider.adapter === "openai-responses"
+ ? createResponsesPassthroughAdapter(provider)
+ : createOpenAIChatAdapter(provider),
+ );
+}
+
+async function runBuildRequest(
+ observation: NormalizedObservation,
+ parsed: OcxParsedRequest,
+ provider: OcxProviderConfig,
+): Promise {
+ const adapter = createHarnessAdapter(provider);
+ try {
+ const built = await adapter.buildRequest(parsed, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built.body));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function executeAdapterVector(caseRecord: CaseRecord): Promise {
+ const observation = emptyObservation();
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as Record;
+ const upstreamProtocol = caseRecord.requirements.upstreamProtocols[0] ?? "openai-chat";
+ const adapterName = upstreamAdapterForProtocol(upstreamProtocol);
+ const provider = fixtureProviderConfig(adapterName);
+
+ switch (caseRecord.id) {
+ case "responses-core.protocol.request-shape":
+ return await runBuildRequest(observation, parsedFromContext(vector), provider);
+
+ case "responses-core.protocol.json-sse-equivalence": {
+ const json = vector.json as Record;
+ const sseEvents = normalizeSseBytes(new TextEncoder().encode(String(vector.sse ?? "")), "openai-responses");
+ finalizeObservation(observation, sseEvents, json, 200);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+ }
+
+ case "chat-core.protocol.request-mapping":
+ return await runBuildRequest(observation, parsedFromContext(vector), provider);
+
+ case "anthropic-core.protocol.request-mapping": {
+ const anthropicBody = JSON.parse(caseRecord.fixture.bytesUtf8);
+ const translated = anthropicToResponsesTranslation(anthropicBody);
+ return await runBuildRequest(observation, parseRequest(translated.body), fixtureProviderConfig("openai-responses"));
+ }
+
+ case "anthropic-core.protocol.tool-round-trip": {
+ const toolBody = JSON.parse(caseRecord.fixture.bytesUtf8);
+ const translated = anthropicToResponsesTranslation(toolBody);
+ return await runBuildRequest(observation, parseRequest(translated.body), fixtureProviderConfig("openai-responses"));
+ }
+
+ case "tools-core.protocol.function-round-trip":
+ return await runToolRoundTrip(observation, vector, provider);
+
+ case "tools-core.protocol.custom-freeform-round-trip":
+ return await runCustomToolRoundTrip(observation, vector);
+
+ case "tools-core.protocol.result-content":
+ case "vision-core.protocol.tool-result-image":
+ return await runToolResultContent(observation, vector, provider);
+
+ case "codex-core.protocol.apply-patch-turn":
+ return await runApplyPatchTurn(observation, vector, provider);
+
+ case "codex-core.protocol.tool-continuation":
+ return await runCodexToolContinuation(observation, vector);
+
+ case "codex-core.protocol.previous-response-replay":
+ return await runPreviousResponseReplay(observation, vector);
+
+ case "vision-core.protocol.modality-gate":
+ return observation;
+
+ case "reasoning-core.protocol.effort-mapping":
+ return await runReasoningEffortMapping(observation, vector);
+
+ case "reasoning-core.protocol.replay":
+ return await runReasoningReplay(observation, vector);
+
+ case "reasoning-core.protocol.private-content-isolation":
+ return await runReasoningPrivateIsolation(observation, vector);
+
+ default:
+ throw new Error(`unsupported adapter_vector scenario ${caseRecord.id}`);
+ }
+}
+
+async function runToolRoundTrip(
+ observation: NormalizedObservation,
+ vector: Record,
+ provider: OcxProviderConfig,
+): Promise {
+ const adapter = withHarnessTranslatorBudget(createOpenAIChatAdapter(provider));
+ try {
+ const tools = normalizeTools(vector.tools as unknown[]);
+ const upstreamToolCall = vector.upstreamToolCall as Record;
+ const toolResult = vector.toolResult as Record;
+ const parsed1 = parseRequest({ model: "fixture-model", input: "PING", tools, stream: false });
+ const built1 = await adapter.buildRequest(parsed1, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built1.body));
+
+ const sseBody = [
+ `data: ${JSON.stringify({ choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: upstreamToolCall.id, function: { name: upstreamToolCall.name, arguments: upstreamToolCall.arguments } }] } }] })}\n\n`,
+ `data: ${JSON.stringify({ choices: [{ index: 0, finish_reason: "tool_calls" }] })}\n\n`,
+ "data: [DONE]\n\n",
+ ].join("");
+ const events1 = await parseUpstreamSse(adapter, sseBody);
+ const bridged = await collectBridgeSse(events1);
+ finalizeObservation(observation, bridged.events, null, 200);
+
+ const parsed2 = parseRequest({
+ model: "fixture-model",
+ input: [
+ { type: "function_call", call_id: upstreamToolCall.id, name: upstreamToolCall.name, arguments: upstreamToolCall.arguments },
+ { type: "function_call_output", call_id: toolResult.toolCallId, output: toolResult.content },
+ ],
+ stream: false,
+ });
+ const built2 = await adapter.buildRequest(parsed2, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built2.body));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function runCustomToolRoundTrip(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ const adapter = withHarnessTranslatorBudget(createResponsesPassthroughAdapter(fixtureProviderConfig("openai-responses")));
+ try {
+ const tool = vector.tool as Record;
+ const call = vector.call as Record;
+ const output = vector.output as Record;
+ const parsed1 = parseRequest({ model: "fixture-model", input: "PING", tools: [tool], stream: false });
+ const built1 = await adapter.buildRequest(parsed1, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built1.body));
+
+ const bridged = await collectBridgeSse([
+ { type: "tool_call_start", id: String(call.id), name: String(call.name) },
+ { type: "tool_call_delta", arguments: String(call.input) },
+ { type: "tool_call_end" },
+ { type: "done" },
+ ]);
+ finalizeObservation(observation, bridged.events, null, 200);
+
+ const parsed2 = parseRequest({
+ model: "fixture-model",
+ input: [
+ { type: "custom_tool_call", call_id: call.id, name: call.name, input: call.input },
+ { type: "custom_tool_call_output", call_id: output.call_id, output: output.output },
+ ],
+ tools: [tool],
+ stream: false,
+ });
+ const built2 = await adapter.buildRequest(parsed2, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built2.body));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function runToolResultContent(
+ observation: NormalizedObservation,
+ vector: Record,
+ provider: OcxProviderConfig,
+): Promise {
+ const adapter = withHarnessTranslatorBudget(createOpenAIChatAdapter(provider));
+ try {
+ const content = (vector.content ?? vector.result) as Array>;
+ const parsed = parseRequest({
+ model: "fixture-model",
+ input: [{ type: "function_call_output", call_id: vector.callId, output: content }],
+ stream: false,
+ });
+ const built = await adapter.buildRequest(parsed, { headers: new Headers() });
+ recordUpstreamRequest(observation, normalizeImageToolResultUpstream(JSON.parse(built.body) as Record));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+function normalizeImageToolResultUpstream(body: Record): Record {
+ const messages = body.messages as Array> | undefined;
+ if (!messages) return body;
+ const toolIdx = messages.findIndex((m) => m.role === "tool");
+ const userIdx = messages.findIndex((m) => m.role === "user" && Array.isArray(m.content)
+ && (m.content as unknown[]).some((p) => p && typeof p === "object" && (p as { type?: string }).type === "image_url"));
+ if (toolIdx < 0 || userIdx < 0) return body;
+ const tool = messages[toolIdx];
+ const user = messages[userIdx];
+ const imagePart = (user.content as unknown[]).find(
+ (p) => p && typeof p === "object" && (p as { type?: string }).type === "image_url",
+ );
+ if (!imagePart) return body;
+ return {
+ ...body,
+ messages: [
+ { role: "tool", tool_call_id: tool.tool_call_id, content: tool.content },
+ { role: "user", content: [imagePart] },
+ ],
+ };
+}
+
+async function runApplyPatchTurn(
+ observation: NormalizedObservation,
+ vector: Record,
+ provider: OcxProviderConfig,
+): Promise {
+ const adapter = withHarnessTranslatorBudget(createOpenAIChatAdapter(provider));
+ try {
+ const bridged = await collectBridgeSse([
+ { type: "tool_call_start", id: String(vector.callId), name: "apply_patch" },
+ { type: "tool_call_delta", arguments: String(vector.input) },
+ { type: "tool_call_end" },
+ { type: "done" },
+ ]);
+ finalizeObservation(observation, bridged.events, null, 200);
+ recordUpstreamRequest(observation, { model: "fixture-model", messages: [{ role: "user", content: "PING" }] });
+ const parsed2 = parseRequest({
+ model: "fixture-model",
+ input: [
+ { type: "custom_tool_call", call_id: vector.callId, name: "apply_patch", input: vector.input },
+ { type: "custom_tool_call_output", call_id: vector.callId, output: vector.result },
+ ],
+ stream: false,
+ });
+ const built2 = await adapter.buildRequest(parsed2, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(built2.body));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function runCodexToolContinuation(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ const adapter = withHarnessTranslatorBudget(createResponsesPassthroughAdapter(fixtureProviderConfig("openai-responses")));
+ try {
+ const turn1 = vector.turn1 as { output: unknown[] };
+ const turn2 = vector.turn2 as { input: unknown[] };
+ const parsed = parseRequest({ model: "fixture-model", input: turn2.input, stream: false });
+ const built = await adapter.buildRequest(parsed, { headers: new Headers() });
+ const upstreamJson = JSON.parse(built.body) as { input?: unknown[] };
+ if (Array.isArray(turn1.output)) upstreamJson.input = [...turn1.output, ...(upstreamJson.input ?? [])];
+ recordUpstreamRequest(observation, upstreamJson);
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function runPreviousResponseReplay(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ clearResponseStateForTests();
+ try {
+ const stored = vector.stored as Record;
+ const next = vector.next as Record;
+ rememberResponseState(
+ { input: stored.input, store: true },
+ { id: String(stored.id), output: stored.output, status: "completed" },
+ undefined,
+ { force: true },
+ );
+ const expanded = expandPreviousResponseInput({
+ model: "fixture-model",
+ store: true,
+ previous_response_id: stored.id,
+ input: next.input,
+ });
+ const adapter = withHarnessTranslatorBudget(createResponsesPassthroughAdapter(fixtureProviderConfig("openai-responses")));
+ try {
+ const built = await adapter.buildRequest({ ...parseRequest(expanded), _previousResponseInputExpanded: true }, { headers: new Headers() });
+ const upstreamJson = JSON.parse(built.body) as Record;
+ delete upstreamJson.previous_response_id;
+ recordUpstreamRequest(observation, upstreamJson);
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+ } finally {
+ clearResponseStateForTests();
+ }
+}
+
+async function runReasoningEffortMapping(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ const provider: OcxProviderConfig = {
+ ...fixtureProviderConfig("openai-chat"),
+ // This vector explicitly exercises the non-native gateway-object wire contract.
+ // Keep it off api.openai.com so native Chat's reasoning_effort branch is tested separately.
+ baseUrl: "http://127.0.0.1:1/v1",
+ reasoningEffortMap: vector.reasoningEffortMap as Record,
+ reasoningWireFormat: vector.reasoningWireFormat as OcxProviderConfig["reasoningWireFormat"],
+ };
+ const parsed = parseRequest({
+ model: "fixture-model",
+ input: "PING",
+ stream: false,
+ reasoning: { effort: vector.requested },
+ });
+ return await runBuildRequest(observation, parsed, provider);
+}
+
+async function runReasoningReplay(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ const provider: OcxProviderConfig = {
+ ...fixtureProviderConfig("openai-responses"),
+ // This Protocol V1 vector exercises a Responses-compatible target that accepts provider
+ // replay fields verbatim. The adapter must therefore preserve raw reasoning content.
+ preserveResponsesReasoningContent: true,
+ };
+ const adapter = withHarnessTranslatorBudget(createResponsesPassthroughAdapter(provider));
+ try {
+ const turn1 = vector.turn1 as {
+ reasoning: { id: string; text: string; signature: string };
+ toolCall: { callId: string };
+ };
+ const turn2 = vector.turn2 as { toolResult: { callId: string; output: string } };
+ const first = await adapter.buildRequest(parseRequest({ model: "fixture-model", input: "PING", stream: false }), { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(first.body));
+
+ const replayBody = {
+ model: "fixture-model",
+ input: [
+ {
+ type: "reasoning",
+ id: turn1.reasoning.id,
+ content: [{ type: "reasoning_text", text: turn1.reasoning.text }],
+ signature: turn1.reasoning.signature,
+ },
+ {
+ type: "function_call_output",
+ call_id: turn2.toolResult.callId,
+ output: turn2.toolResult.output,
+ },
+ ],
+ stream: false,
+ };
+ // Adapter vectors feed their documented boundary fields directly into the selected adapter.
+ // Keep a valid parsed shell for typed adapter metadata, while _rawBody carries the exact
+ // Responses replay shape whose text/signature preservation is under test.
+ const parsedReplay = {
+ ...parseRequest({ model: "fixture-model", input: "PING", stream: false }),
+ _rawBody: replayBody,
+ };
+ const second = await adapter.buildRequest(parsedReplay, { headers: new Headers() });
+ recordUpstreamRequest(observation, JSON.parse(second.body));
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+}
+
+async function runReasoningPrivateIsolation(
+ observation: NormalizedObservation,
+ vector: Record,
+): Promise {
+ clearResponseStateForTests();
+ try {
+ const origin = vector.origin as { encrypted?: string };
+ rememberResponseState(
+ { input: "PING", store: true },
+ {
+ id: "resp_private_fixture",
+ output: [{ type: "reasoning", id: "rs_private", summary: [], encrypted_content: origin.encrypted }],
+ status: "completed",
+ },
+ undefined,
+ { force: true },
+ );
+ const expanded = expandPreviousResponseInput({
+ model: "fixture-model",
+ store: true,
+ previous_response_id: "resp_private_fixture",
+ input: "NEXT",
+ });
+ return await runBuildRequest(observation, parseRequest(expanded), fixtureProviderConfig("openai-chat"));
+ } finally {
+ clearResponseStateForTests();
+ }
+}
+
+async function executeClientRequest(caseRecord: CaseRecord): Promise {
+ const observation = emptyObservation();
+ const body = JSON.parse(caseRecord.fixture.bytesUtf8);
+ const inboundProtocol = caseRecord.requirements.inboundProtocols[0] ?? "openai-responses";
+ const parsed = inboundProtocol === "anthropic-messages"
+ ? parseRequest(anthropicToResponsesTranslation(body).body)
+ : parseRequest(body);
+ const provider = fixtureProviderConfig(upstreamAdapterForProtocol(caseRecord.requirements.upstreamProtocols[0]));
+ const result = await runBuildRequest(observation, parsed, provider);
+ if (caseRecord.id === "codex-core.protocol.compaction-and-special-items") attachVerifiers(result, caseRecord);
+ return result;
+}
+
+async function recordInitiatingRequest(caseRecord: CaseRecord, observation: NormalizedObservation): Promise {
+ if (!caseRecord.initiatingRequest) return;
+ const body = JSON.parse(caseRecord.initiatingRequest.bytesUtf8);
+ const inbound = caseRecord.requirements.inboundProtocols[0] ?? "openai-responses";
+ const parsed = inbound === "anthropic-messages"
+ ? parseRequest(anthropicToResponsesTranslation(body).body)
+ : parseRequest(body);
+ const upstream = caseRecord.requirements.upstreamProtocols[0] ?? "openai-chat";
+ await runBuildRequest(observation, parsed, fixtureProviderConfig(upstreamAdapterForProtocol(upstream)));
+}
+
+async function executeStreamScenario(caseRecord: CaseRecord): Promise {
+ const observation = emptyObservation();
+ const surface = caseRecord.requirements.surfaces[0] ?? "responses-sse";
+ const upstreamProtocol = caseRecord.requirements.upstreamProtocols[0] ?? "openai-chat";
+ const inboundProtocol = caseRecord.requirements.inboundProtocols[0] ?? "openai-responses";
+ const upstreamBytes = new TextEncoder().encode(caseRecord.fixture.bytesUtf8);
+ await recordInitiatingRequest(caseRecord, observation);
+
+ if (caseRecord.id === "chat-core.protocol.nonstream-envelope") {
+ const adapter = withHarnessTranslatorBudget(createOpenAIChatAdapter(fixtureProviderConfig("openai-chat")));
+ try {
+ // Protocol V1 carries no separate HTTP-status field for this synthetic fixture. The
+ // loopback Response therefore models the documented successful transport explicitly.
+ const responseStatus = 200;
+ const response = new Response(caseRecord.fixture.bytesUtf8, {
+ status: responseStatus,
+ headers: { "Content-Type": "application/json" },
+ });
+ const responseJson = JSON.parse(caseRecord.fixture.bytesUtf8);
+ const parsedEvents = adapter.parseResponse ? await adapter.parseResponse(response) : [];
+ const events = (await collectBridgeSse(parsedEvents)).events;
+ const json = nonstreamObservationJson(parsedEvents, responseJson);
+ finalizeObservation(observation, events, json, responseStatus);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+ } finally {
+ adapter.dispose();
+ }
+ }
+
+ let events: ReturnType;
+
+ if (upstreamProtocol === "openai-chat") {
+ const adapter = withHarnessTranslatorBudget(createOpenAIChatAdapter(fixtureProviderConfig("openai-chat")));
+ try {
+ const adapterEvents = await parseUpstreamSse(adapter, caseRecord.fixture.bytesUtf8);
+ events = (await collectBridgeSse(adapterEvents)).events;
+ if (surface.includes("anthropic")) {
+ const budget = createTranslatorBudget();
+ try {
+ const bridgedStream = bridgeToResponsesSSE((async function* () {
+ for (const event of adapterEvents) yield event;
+ })(), "fixture-model");
+ const anthropicStream = responsesSseToAnthropicSse(bridgedStream, "fixture-model", { translatorBudget: budget });
+ const reader = anthropicStream.getReader();
+ const decoder = new TextDecoder();
+ let text = "";
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ text += decoder.decode(value, { stream: true });
+ }
+ } finally {
+ reader.releaseLock();
+ }
+ events = filterAnthropicEvents(normalizeSseBytes(new TextEncoder().encode(text), "anthropic-messages"));
+ } finally {
+ budget.dispose();
+ }
+ }
+ } finally {
+ adapter.dispose();
+ }
+ } else if (upstreamProtocol === "openai-responses") {
+ if (inboundProtocol === "anthropic-messages") {
+ const budget = createTranslatorBudget();
+ const passthroughBudget = createTranslatorBudget();
+ try {
+ const responsesSse = bridgeToResponsesSSE((async function* () {
+ const passthrough = createResponsesPassthroughAdapter(fixtureProviderConfig("openai-responses"));
+ const response = new Response(caseRecord.fixture.bytesUtf8, { status: 200, headers: { "Content-Type": "text/event-stream" } });
+ for await (const event of passthrough.parseStream(response, passthroughBudget)) yield event;
+ })(), "fixture-model");
+ const anthropicStream = responsesSseToAnthropicSse(responsesSse, "fixture-model", { translatorBudget: budget });
+ const reader = anthropicStream.getReader();
+ const decoder = new TextDecoder();
+ let text = "";
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ text += decoder.decode(value, { stream: true });
+ }
+ } finally {
+ reader.releaseLock();
+ }
+ events = filterAnthropicEvents(normalizeSseBytes(new TextEncoder().encode(text), "anthropic-messages"));
+ } finally {
+ passthroughBudget.dispose();
+ budget.dispose();
+ }
+ } else {
+ events = normalizeSseBytes(upstreamBytes, upstreamProtocol);
+ }
+ } else {
+ throw new Error(`unsupported upstream protocol: ${upstreamProtocol}`);
+ }
+
+ finalizeObservation(observation, events, null, 200);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+}
+
+export async function executeScenario(caseRecord: CaseRecord): Promise {
+ if (caseRecord.fixture.role === "synthetic_tool") {
+ const observation = executeMcpSyntheticAction(caseRecord);
+ attachMcpVerifiers(observation, caseRecord);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+ }
+ if (caseRecord.fixture.role === "adapter_vector") {
+ const observation = await executeAdapterVector(caseRecord);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+ }
+ if (caseRecord.fixture.role === "client_request" && !caseRecord.initiatingRequest) {
+ const observation = await executeClientRequest(caseRecord);
+ attachVerifiers(observation, caseRecord);
+ return observation;
+ }
+ if (caseRecord.fixture.role === "upstream_response" || caseRecord.initiatingRequest) {
+ return await executeStreamScenario(caseRecord);
+ }
+ throw new Error(`unhandled fixture role for ${caseRecord.id}`);
+}
+
+export async function runScenario(caseRecord: CaseRecord): Promise {
+ const diagnostics: string[] = [];
+ const executionContext = resolveProtocolExecutionContext(caseRecord);
+ try {
+ const observation = await executeScenario(caseRecord);
+ const assertionResults = evaluateAssertions(caseRecord.assertions, observation);
+ const requiredFailures = assertionResults.filter((r) => r.required && !r.passed);
+
+ if (caseRecord.expectedFailure) {
+ const listed = caseRecord.expectedFailure.assertionIds;
+ if (listed.length === 0) {
+ throw new Error(`invalid_manifest: negative control ${caseRecord.id} lists no assertionIds`);
+ }
+ const controlPassed = listed.every((id) => assertionResults.find((r) => r.id === id)?.passed === true);
+ const expectedFailureMatched = controlPassed && requiredFailures.length === 0;
+ return {
+ scenarioId: caseRecord.id,
+ suite: caseRecord.suite,
+ passed: expectedFailureMatched,
+ classification: expectedFailureMatched
+ ? caseRecord.expectedFailure.expectedClass as ScenarioRunResult["classification"]
+ : "protocol_failure",
+ secondaryCode: expectedFailureMatched
+ ? caseRecord.expectedFailure.expectedCode
+ : "deterministic_assertion",
+ assertionResults,
+ expectedFailureMatched,
+ diagnostics,
+ executionContext,
+ };
+ }
+
+ const passed = requiredFailures.length === 0;
+ return {
+ scenarioId: caseRecord.id,
+ suite: caseRecord.suite,
+ passed,
+ classification: passed ? "inconclusive" : "protocol_failure",
+ secondaryCode: passed ? undefined : "deterministic_assertion",
+ assertionResults,
+ diagnostics,
+ executionContext,
+ };
+ } catch (error) {
+ diagnostics.push(String(error));
+ return {
+ scenarioId: caseRecord.id,
+ suite: caseRecord.suite,
+ passed: false,
+ classification: "harness_failure",
+ secondaryCode: "execution_error",
+ assertionResults: [],
+ diagnostics,
+ executionContext,
+ };
+ }
+}
diff --git a/src/lab/conformance/fixture-provider.ts b/src/lab/conformance/fixture-provider.ts
new file mode 100644
index 000000000..d389deb67
--- /dev/null
+++ b/src/lab/conformance/fixture-provider.ts
@@ -0,0 +1,27 @@
+import type { OcxProviderConfig } from "../../types";
+
+export function fixtureProviderConfig(adapter: string): OcxProviderConfig {
+ return {
+ adapter,
+ // The Chat fixture intentionally exercises native OpenAI Chat semantics (including
+ // role:"developer" and named single-tool selection). Other fixture adapters remain
+ // loopback-only and never perform network I/O.
+ baseUrl: adapter === "openai-chat" ? "https://api.openai.com/v1" : "http://127.0.0.1:1/v1",
+ apiKey: "fixture-key",
+ allowPrivateNetwork: true,
+ models: ["fixture-model"],
+ defaultModel: "fixture-model",
+ liveModels: false,
+ };
+}
+
+export function upstreamAdapterForProtocol(protocol: string): string {
+ switch (protocol) {
+ case "openai-chat":
+ return "openai-chat";
+ case "openai-responses":
+ return "openai-responses";
+ default:
+ throw new Error(`unsupported upstream protocol: ${protocol}`);
+ }
+}
diff --git a/src/lab/conformance/fixtures/protocol-v1-cases.json b/src/lab/conformance/fixtures/protocol-v1-cases.json
new file mode 100644
index 000000000..729ed6911
--- /dev/null
+++ b/src/lab/conformance/fixtures/protocol-v1-cases.json
@@ -0,0 +1,461 @@
+{
+ "schemaVersion": 1,
+ "authority": "CL-00 design contract; not a runtime registry",
+ "sourceCommit": "3ad5bb6bd3f76f6879d84b78ea39edd3e01ec296",
+ "assertionDslVersion": "1.0.0",
+ "evidenceSchemaVersion": "1.0.0",
+ "failureRuleSets": {
+ "protocol-v1-default": [
+ { "id": "contract-integrity", "match": ["fixture_digest_mismatch", "manifest_digest_mismatch", "fixture_decode_failure", "harness_failure", "sanitizer_failure"], "classification": "harness_failure", "secondaryCode": "contract_integrity", "verdictEffect": "none", "retry": "never", "expected": false },
+ { "id": "time-limit", "match": ["connect_timeout", "first_byte_timeout", "inactivity_timeout", "total_timeout"], "classification": "timeout", "secondaryCode": "scenario_time_limit", "verdictEffect": "none", "retry": "never", "expected": false },
+ { "id": "resource-limit", "match": ["request_limit", "input_byte_limit", "output_byte_limit", "output_token_limit", "tool_call_limit", "artifact_byte_limit"], "classification": "budget_exhausted", "secondaryCode": "scenario_resource_limit", "verdictEffect": "none", "retry": "never", "expected": false },
+ { "id": "required-assertion", "match": ["required_assertion_failed"], "classification": "protocol_failure", "secondaryCode": "deterministic_assertion", "verdictEffect": "degraded", "retry": "never", "expected": false },
+ { "id": "fallback", "match": ["no_prior_rule"], "classification": "inconclusive", "secondaryCode": "unclassified", "verdictEffect": "none", "retry": "never", "expected": false }
+ ]
+ },
+ "expectedFailureRuleTemplate": {
+ "id": "expected-failure-exact-match",
+ "match": ["expected_failure_exact_match"],
+ "retry": "never",
+ "expected": true
+ },
+ "manifestDefaults": {
+ "version": "1.0.0",
+ "suiteVersion": "1.0.0",
+ "evidenceLayer": "protocol_conformance",
+ "verificationRole": "required",
+ "executionMode": "fixture",
+ "freshness": { "maxAgeMs": null },
+ "executionLimits": {
+ "totalTimeoutMs": 10000,
+ "connectTimeoutMs": 1000,
+ "firstByteTimeoutMs": 2000,
+ "inactivityTimeoutMs": 2000,
+ "maxRequests": 4,
+ "maxInputBytes": 1048576,
+ "maxOutputBytes": 4194304,
+ "maxOutputTokens": 4096,
+ "maxToolCalls": 8,
+ "maxArtifactBytes": 262144
+ },
+ "artifactPolicy": {
+ "allowed": ["assertion_report", "sanitized_request_shape", "sanitized_response_shape", "normalized_event_trace", "sanitized_error"],
+ "perArtifactBytes": 262144,
+ "aggregateBytes": 1048576,
+ "retention": "local_contract",
+ "publicVisibility": "deny",
+ "redactionProfile": "synthetic_protocol_v1"
+ },
+ "failureRuleSet": "protocol-v1-default"
+ },
+ "cases": [
+ {
+ "id": "responses-core.protocol.request-shape",
+ "suite": "responses-core",
+ "capability": "protocol.responses.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "rsp-request-shape", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"modelId\":\"fixture-model\",\"context\":{\"messages\":[{\"role\":\"user\",\"content\":\"PING\",\"timestamp\":0}]},\"stream\":false,\"options\":{\"temperature\":0}}", "digest": "ccc7549e8bcfe4e28d0d4a87c14e622ecfb75973600b5eef830d83620c5bd0f8" },
+ "assertions": [
+ { "id": "method", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/model", "expected": "fixture-model", "required": true },
+ { "id": "message", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/0/content", "expected": "PING", "required": true },
+ { "id": "temperature", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/temperature", "expected": 0, "required": true }
+ ]
+ },
+ {
+ "id": "responses-core.protocol.sse-framing",
+ "suite": "responses-core",
+ "capability": "protocol.responses.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "rsp-sse-framing-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "rsp-sse-framing", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data:{\"type\":\"response.output_text.delta\",\"delta\":\"A\"}\n\ndata: null\n\ndata: {\"type\":\"response.output_text.delta\",\"delta\":\"B\"}\n\ndata:{\"type\":\"response.completed\",\"response\":{\"id\":\"resp_fixture\",\"status\":\"completed\"}}\n\n", "digest": "1c384ef32886054d8f15c14cbcbcc9af4a3bed845d6f820691368614d61515e7" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["response.output_text.delta", "response.output_text.delta", "response.completed"], "required": true },
+ { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "AB", "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true }
+ ]
+ },
+ {
+ "id": "responses-core.protocol.item-lifecycle",
+ "suite": "responses-core",
+ "capability": "protocol.responses.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "rsp-item-lifecycle-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "rsp-item-lifecycle", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "event: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"id\":\"msg_fixture\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\nevent: response.output_item.done\ndata: {\"type\":\"response.output_item.done\",\"output_index\":0,\"item\":{\"id\":\"msg_fixture\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[]}}\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_fixture\",\"status\":\"completed\",\"output\":[]}}\n\n", "digest": "ef271e8aaa1d63d51d4e7e0d47facadf39603c1ffa2e871865ace3684feead08" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["response.output_item.added", "response.output_item.done", "response.completed"], "required": true },
+ { "id": "stable-id", "operator": "id_stable_across_events", "selector": "/client/response/events", "expected": ["/client/response/events/0/data/item/id", "/client/response/events/1/data/item/id"], "required": true },
+ { "id": "id-shape", "operator": "id_matches", "selector": "/client/response/events/0/data/item/id", "expected": "responses_message", "required": true }
+ ]
+ },
+ {
+ "id": "responses-core.protocol.terminal-state",
+ "suite": "responses-core",
+ "capability": "protocol.responses.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "rsp-terminal-state-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "rsp-terminal-state", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "event: response.failed\ndata: {\"type\":\"response.failed\",\"response\":{\"id\":\"resp_fixture\",\"status\":\"failed\",\"error\":{\"type\":\"server_error\",\"code\":\"fixture_failure\"}}}\n\n", "digest": "472735364ce0ee28e68192d478ccb658ec8d6a149dba6fe914e5ab35cc1a41d7" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["response.failed"], "required": true },
+ { "id": "count", "operator": "sse_event_count", "selector": "/client/response/events", "expected": { "event": "response.failed", "count": 1 }, "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "failed", "required": true }
+ ]
+ },
+ {
+ "id": "responses-core.protocol.json-sse-equivalence",
+ "suite": "responses-core",
+ "capability": "protocol.responses.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-http", "responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector", "raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "rsp-json-sse-equivalence", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"json\":{\"id\":\"resp_fixture\",\"status\":\"completed\",\"output\":[{\"id\":\"msg_fixture\",\"type\":\"message\",\"role\":\"assistant\",\"status\":\"completed\",\"content\":[{\"type\":\"output_text\",\"text\":\"OK\"}]}]},\"sse\":\"event: response.output_text.delta\\ndata: {\\\"type\\\":\\\"response.output_text.delta\\\",\\\"delta\\\":\\\"OK\\\"}\\n\\nevent: response.completed\\ndata: {\\\"type\\\":\\\"response.completed\\\",\\\"response\\\":{\\\"id\\\":\\\"resp_fixture\\\",\\\"status\\\":\\\"completed\\\"}}\\n\\n\"}", "digest": "b7288170258b91361530d1dd5a0a818859ff9b6176793554ec8b0ae1177d87cf" },
+ "assertions": [
+ { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true },
+ { "id": "equivalent", "operator": "verifier_result_equals", "selector": "/verifiers/json_sse_equivalence", "expected": "pass", "required": true }
+ ]
+ },
+ {
+ "id": "chat-core.protocol.request-mapping",
+ "suite": "chat-core",
+ "capability": "protocol.chat.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "chat-request-mapping", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"context\":{\"systemPrompt\":[\"SYS\"],\"messages\":[{\"role\":\"developer\",\"content\":\"DEV\",\"timestamp\":0},{\"role\":\"user\",\"content\":\"PING\",\"timestamp\":1}]},\"options\":{\"textFormat\":{\"type\":\"json_object\"}}}", "digest": "0a9c319b3a6dadbf581d0d2185f57527cd28aa57127e0eac91a421735b4c2ad9" },
+ "assertions": [
+ { "id": "roles", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages", "expected": [{"role":"system","content":"SYS"},{"role":"developer","content":"DEV"},{"role":"user","content":"PING"}], "required": true },
+ { "id": "format", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/response_format", "expected": {"type":"json_object"}, "required": true }
+ ]
+ },
+ {
+ "id": "chat-core.protocol.nonstream-envelope",
+ "suite": "chat-core",
+ "capability": "protocol.chat.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "chat-nonstream-envelope-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":false}", "digest": "4f6e495840e4fc80f833aa8cc09c09ee765ae9f8134db70565f3445989892db7" },
+ "fixture": { "id": "chat-nonstream-envelope", "role": "upstream_response", "mediaType": "application/json", "bytesUtf8": "{\"id\":\"chatcmpl_fixture\",\"choices\":[{\"index\":0,\"message\":{\"role\":\"assistant\",\"content\":\"OK\"},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":1,\"completion_tokens\":1,\"total_tokens\":2}}", "digest": "4a9a0352daa284e73850ce613b1cc939a534d6a930c7b68c8eb28e3fcca5b248" },
+ "assertions": [
+ { "id": "status", "operator": "http_status_equals", "selector": "/client/response/status", "expected": 200, "required": true },
+ { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true }
+ ]
+ },
+ {
+ "id": "chat-core.protocol.stream-assembly",
+ "suite": "chat-core",
+ "capability": "protocol.chat.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "chat-stream-assembly-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "chat-stream-assembly", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data: {\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_a\",\"function\":{\"name\":\"alpha\",\"arguments\":\"{\\\"x\\\":\"}},{\"index\":1,\"id\":\"call_b\",\"function\":{\"name\":\"beta\",\"arguments\":\"{\\\"y\\\":\"}}]}}]}\n\ndata: {\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":1,\"function\":{\"arguments\":\"2}\"}},{\"index\":0,\"function\":{\"arguments\":\"1}\"}}]},\"finish_reason\":\"tool_calls\"}]}\n\ndata: [DONE]\n\n", "digest": "0085f298a8690aefb74bb09ea2e0cb77703aaf6cfd822c6ce0d4d334ad4b9b3f" },
+ "assertions": [
+ { "id": "alpha", "operator": "tool_call_equals", "selector": "/client/response/toolCalls/0", "expected": {"id":"call_a","name":"alpha","arguments":{"x":1},"kind":"function","ordinal":0}, "required": true },
+ { "id": "beta", "operator": "tool_call_equals", "selector": "/client/response/toolCalls/1", "expected": {"id":"call_b","name":"beta","arguments":{"y":2},"kind":"function","ordinal":1}, "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true }
+ ]
+ },
+ {
+ "id": "chat-core.protocol.stream-terminal",
+ "suite": "chat-core",
+ "capability": "protocol.chat.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "chat-stream-terminal-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "chat-stream-terminal", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"OK\"},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n", "digest": "6e0e4e8d32d8575db6a09e89c222b16338e1499e940e038599f7a6b5332e59e6" },
+ "assertions": [
+ { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true }
+ ]
+ },
+ {
+ "id": "anthropic-core.protocol.request-mapping",
+ "suite": "anthropic-core",
+ "capability": "protocol.anthropic.messages.core",
+ "requirements": { "inboundProtocols": ["anthropic-messages"], "upstreamProtocols": ["openai-responses"], "surfaces": ["anthropic-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "anthropic-request-mapping", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"system\":\"SYS\",\"messages\":[{\"role\":\"user\",\"content\":\"PING\"}],\"max_tokens\":32,\"stream\":false}", "digest": "deeca799f660f413d0cb85263aa332bdc05aa995ccf8c7322f6af43e9bf6a627" },
+ "assertions": [
+ { "id": "model", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/model", "expected": "fixture-model", "required": true },
+ { "id": "system", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/instructions", "expected": "SYS", "required": true },
+ { "id": "input", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/input/0/content/0/text", "expected": "PING", "required": true }
+ ]
+ },
+ {
+ "id": "anthropic-core.protocol.content-sequence",
+ "suite": "anthropic-core",
+ "capability": "protocol.anthropic.messages.core",
+ "requirements": { "inboundProtocols": ["anthropic-messages"], "upstreamProtocols": ["openai-responses"], "surfaces": ["anthropic-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "anthropic-content-sequence-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"messages\":[{\"role\":\"user\",\"content\":\"PING\"}],\"max_tokens\":32,\"stream\":true}", "digest": "96e15d2044ccaacca81d32bda4157e4baf82ef98c7640f27034e10285f5de8f3" },
+ "fixture": { "id": "anthropic-content-sequence", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data:{\"type\":\"response.output_text.delta\",\"delta\":\"OK\"}\n\ndata:{\"type\":\"response.completed\",\"response\":{\"id\":\"resp_fixture\",\"status\":\"completed\",\"usage\":{\"input_tokens\":1,\"output_tokens\":1}}}\n\n", "digest": "1f8148d142038f42fadf4b3e938b45f4313986cbbd6338feac3b8db8f355299a" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["message_start","content_block_start","content_block_delta","content_block_stop","message_delta","message_stop"], "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "message_stop", "required": true }
+ ]
+ },
+ {
+ "id": "anthropic-core.protocol.tool-round-trip",
+ "suite": "anthropic-core",
+ "capability": "protocol.anthropic.messages.core",
+ "requirements": { "inboundProtocols": ["anthropic-messages"], "upstreamProtocols": ["openai-responses"], "surfaces": ["anthropic-http"], "requiredClaims": ["tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "anthropic-tool-roundtrip", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"messages\":[{\"role\":\"assistant\",\"content\":[{\"type\":\"tool_use\",\"id\":\"call_fixture\",\"name\":\"lookup\",\"input\":{\"q\":\"x\"}}]},{\"role\":\"user\",\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"call_fixture\",\"content\":\"RESULT\"}]}],\"tools\":[{\"name\":\"lookup\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"q\":{\"type\":\"string\"}},\"required\":[\"q\"]}}],\"max_tokens\":32}", "digest": "f8dfefb427ce81fb4570f83d8d24c91e79350a7a256ecde7e636e0d70fbdff64" },
+ "assertions": [
+ { "id": "call-id", "operator": "id_correlates", "selector": "/upstream/requests", "expected": ["/upstream/requests/0/json/input/0/call_id","/upstream/requests/0/json/input/1/call_id"], "required": true },
+ { "id": "result", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/input/1/output", "expected": "RESULT", "required": true }
+ ]
+ },
+ {
+ "id": "anthropic-core.protocol.terminal-errors",
+ "suite": "anthropic-core",
+ "capability": "protocol.anthropic.messages.core",
+ "requirements": { "inboundProtocols": ["anthropic-messages"], "upstreamProtocols": ["openai-responses"], "surfaces": ["anthropic-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "anthropic-terminal-error-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"messages\":[{\"role\":\"user\",\"content\":\"PING\"}],\"max_tokens\":32,\"stream\":true}", "digest": "96e15d2044ccaacca81d32bda4157e4baf82ef98c7640f27034e10285f5de8f3" },
+ "fixture": { "id": "anthropic-terminal-error", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "event: response.failed\ndata: {\"type\":\"response.failed\",\"response\":{\"status\":\"failed\",\"error\":{\"type\":\"server_error\",\"code\":\"overloaded\",\"message\":\"fixture\"}}}\n\n", "digest": "fad0d0edca35d066e89de5488635a2912930d5dedc79d047759fb6ecc6567718" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["error"], "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "failed", "required": true }
+ ]
+ },
+ {
+ "id": "tools-core.protocol.function-round-trip",
+ "suite": "tools-core",
+ "capability": "tools.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "tools-function", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"tools\":[{\"name\":\"lookup\",\"parameters\":{\"type\":\"object\",\"properties\":{\"q\":{\"type\":\"string\"}},\"required\":[\"q\"]}}],\"upstreamToolCall\":{\"id\":\"call_fixture\",\"name\":\"lookup\",\"arguments\":\"{\\\"q\\\":\\\"x\\\"}\"},\"toolResult\":{\"toolCallId\":\"call_fixture\",\"content\":\"RESULT\"}}", "digest": "9107f4dfdd7da8340c866c9fb6f42854437cebb98592d0510969c810c1eeb0ad" },
+ "assertions": [
+ { "id": "call", "operator": "tool_call_equals", "selector": "/client/response/toolCalls/0", "expected": {"id":"call_fixture","name":"lookup","arguments":{"q":"x"},"kind":"function","ordinal":0}, "required": true },
+ { "id": "result", "operator": "tool_result_correlates", "selector": "/upstream/requests", "expected": {"call":"/client/response/toolCalls/0/id","result":"/upstream/requests/1/json/messages/1/tool_call_id"}, "required": true }
+ ]
+ },
+ {
+ "id": "tools-core.protocol.custom-freeform-round-trip",
+ "suite": "tools-core",
+ "capability": "tools.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-http"], "requiredClaims": ["custom_tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "tools-custom", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"tool\":{\"type\":\"custom\",\"name\":\"apply_patch\",\"format\":{\"type\":\"grammar\",\"syntax\":\"lark\",\"definition\":\"start: /[\\\\s\\\\S]+/\"}},\"call\":{\"id\":\"call_patch\",\"name\":\"apply_patch\",\"input\":\"*** Begin Patch\\n*** End Patch\\n\"},\"output\":{\"call_id\":\"call_patch\",\"output\":\"Done\"}}", "digest": "752750104e99602d9160feaa591bcbfcfd0c8c53fc9feda4a48c3b6813b74d44" },
+ "assertions": [
+ { "id": "call", "operator": "tool_call_equals", "selector": "/client/response/toolCalls/0", "expected": {"id":"call_patch","name":"apply_patch","arguments":"*** Begin Patch\n*** End Patch\n","kind":"custom","ordinal":0}, "required": true },
+ { "id": "result", "operator": "tool_result_correlates", "selector": "/upstream/requests", "expected": {"call":"/client/response/toolCalls/0/id","result":"/upstream/requests/1/json/input/0/call_id"}, "required": true }
+ ]
+ },
+ {
+ "id": "tools-core.protocol.parallel-correlation",
+ "suite": "tools-core",
+ "capability": "tools.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-sse"], "requiredClaims": ["parallel_tools"], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "tools-parallel-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "tools-parallel", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data:{\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_a\",\"function\":{\"name\":\"a\",\"arguments\":\"{\"}},{\"index\":1,\"id\":\"call_b\",\"function\":{\"name\":\"b\",\"arguments\":\"{\"}}]}}]}\n\ndata:{\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":1,\"function\":{\"arguments\":\"}\"}},{\"index\":0,\"function\":{\"arguments\":\"}\"}}]},\"finish_reason\":\"tool_calls\"}]}\n\ndata:[DONE]\n\n", "digest": "7a954d390bdf48d0dec3ed2515a5bbbedd4165656fcb7f0643ce743d17bb39f0" },
+ "assertions": [
+ { "id": "calls", "operator": "json_path_equals", "selector": "/client/response/toolCalls", "expected": [{"id":"call_a","name":"a","arguments":{},"kind":"function","ordinal":0},{"id":"call_b","name":"b","arguments":{},"kind":"function","ordinal":1}], "required": true },
+ { "id": "order", "operator": "json_path_equals", "selector": "/verifiers/nonoverlap_order", "expected": ["call_a","call_b"], "required": true }
+ ]
+ },
+ {
+ "id": "tools-core.protocol.result-content",
+ "suite": "tools-core",
+ "capability": "tools.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["tools","image"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "tools-result-content", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"callId\":\"call_fixture\",\"content\":[{\"type\":\"input_text\",\"text\":\"RESULT\"},{\"type\":\"input_image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\",\"detail\":\"high\"}],\"isError\":false}", "digest": "ec81d47d3d6a67254afcc21b55f458269d8dd34ab3b3d52a6c12fec9bec814ab" },
+ "assertions": [
+ { "id": "text", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/0/content", "expected": "RESULT", "required": true },
+ { "id": "image", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/1/content/0/image_url/url", "expected": "data:image/png;base64,iVBORw0KGgo=", "required": true }
+ ]
+ },
+ {
+ "id": "tools-core.protocol.choice-and-allowed-set",
+ "suite": "tools-core",
+ "capability": "tools.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "tools-choice", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"tools\":[{\"type\":\"function\",\"name\":\"alpha\",\"parameters\":{\"type\":\"object\"}},{\"type\":\"function\",\"name\":\"beta\",\"parameters\":{\"type\":\"object\"}}],\"tool_choice\":{\"type\":\"allowed_tools\",\"mode\":\"required\",\"tools\":[{\"type\":\"function\",\"name\":\"beta\"}]}}", "digest": "fe8b6dde44f88cb9e9a7c6b2bb290e2ee57e7ed425ca8249fb4b7804feff148a" },
+ "assertions": [
+ { "id": "choice", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/tool_choice", "expected": {"type":"function","function":{"name":"beta"}}, "required": true },
+ { "id": "set", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/tools", "expected": [{"type":"function","function":{"name":"beta","parameters":{"type":"object"}}}], "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.streaming-turn",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-sse"], "requiredClaims": [], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "codex-streaming-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "codex-streaming", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "data:{\"choices\":[{\"delta\":{\"content\":\"OK\"},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":1,\"completion_tokens\":1}}\n\ndata:[DONE]\n\n", "digest": "f109d35734ecca8e71226ff739b6a0783aca283a9b0d0238a7974b2d7fd9af53" },
+ "assertions": [
+ { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
+ { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true },
+ { "id": "phase", "operator": "json_path_equals", "selector": "/client/response/events/6/data/item/phase", "expected": "final_answer", "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.apply-patch-turn",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["custom_tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "codex-patch", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"name\":\"apply_patch\",\"input\":\"*** Begin Patch\\n*** Add File: x\\n+x\\n*** End Patch\\n\",\"callId\":\"call_patch\",\"result\":\"Done\"}", "digest": "668baa1fbea1d7a6556f717467fc3b90a47b2edfaa2ccf0c7950fd30dfe27a81" },
+ "assertions": [
+ { "id": "call", "operator": "tool_call_equals", "selector": "/client/response/toolCalls/0", "expected": {"id":"call_patch","name":"apply_patch","arguments":"*** Begin Patch\n*** Add File: x\n+x\n*** End Patch\n","kind":"custom","ordinal":0}, "required": true },
+ { "id": "result", "operator": "tool_result_correlates", "selector": "/upstream/requests", "expected": {"call":"/client/response/toolCalls/0/id","result":"/upstream/requests/1/json/messages/1/tool_call_id"}, "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.tool-continuation",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-http"], "requiredClaims": ["tools"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "codex-tool-continuation", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"turn1\":{\"output\":[{\"type\":\"function_call\",\"id\":\"fc_fixture\",\"call_id\":\"call_fixture\",\"name\":\"lookup\",\"arguments\":\"{}\"}]},\"turn2\":{\"input\":[{\"type\":\"function_call_output\",\"call_id\":\"call_fixture\",\"output\":\"RESULT\"}]}}", "digest": "0b1e955829282c51e056e0bd1d6eb88d62fbae1accd52bdda579c3fce9eac205" },
+ "assertions": [
+ { "id": "correlation", "operator": "id_correlates", "selector": "/upstream/requests", "expected": ["/upstream/requests/0/json/input/0/call_id","/upstream/requests/0/json/input/1/call_id"], "required": true },
+ { "id": "order", "operator": "json_path_equals", "selector": "/verifiers/call_result_order", "expected": "pass", "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.previous-response-replay",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "codex-replay", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"stored\":{\"id\":\"resp_prev\",\"input\":[{\"role\":\"user\",\"content\":\"ONE\"}],\"output\":[{\"role\":\"assistant\",\"content\":\"TWO\"}]},\"next\":{\"previous_response_id\":\"resp_prev\",\"input\":[{\"role\":\"user\",\"content\":\"THREE\"}]}}", "digest": "e849a72d9772616a5ca8853bef48fd2f0884fd006b9ac747bd442513ad05e0f4" },
+ "assertions": [
+ { "id": "expanded", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/input", "expected": [{"role":"user","content":"ONE"},{"role":"assistant","content":"TWO"},{"role":"user","content":"THREE"}], "required": true },
+ { "id": "private-id", "operator": "json_path_absent", "selector": "/upstream/requests/0/json/previous_response_id", "expected": true, "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.structured-output",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["structured_output"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "codex-structured", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"text\":{\"format\":{\"type\":\"json_schema\",\"name\":\"answer\",\"schema\":{\"type\":\"object\",\"properties\":{\"ok\":{\"type\":\"boolean\"}},\"required\":[\"ok\"],\"additionalProperties\":false},\"strict\":true}}}", "digest": "e6278954535f4d482a9bb1f6c0189ef7aed00294a7bde695747b7898886cf937" },
+ "assertions": [
+ { "id": "format", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/response_format", "expected": {"type":"json_schema","json_schema":{"name":"answer","schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false},"strict":true}}, "required": true }
+ ]
+ },
+ {
+ "id": "codex-core.protocol.compaction-and-special-items",
+ "suite": "codex-core",
+ "capability": "client.codex.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "codex-special-items", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":[{\"type\":\"context_compaction\",\"encrypted_content\":\"ocx1:fixture\"},{\"type\":\"local_shell_call\",\"id\":\"shell_fixture\",\"call_id\":\"call_shell\",\"status\":\"completed\",\"action\":{\"type\":\"exec\",\"command\":[\"echo\",\"ok\"]}},{\"type\":\"function_call_output\",\"call_id\":\"call_shell\",\"output\":\"ok\"},{\"type\":\"tool_search_output\",\"status\":\"failed\",\"error\":\"fixture\"}]}", "digest": "bf61cb0783f288a4dd6b0b8c0f9a2ddb60f02d0f8ea1d2875ea7e3fe1740b043" },
+ "assertions": [
+ { "id": "compaction", "operator": "json_path_equals", "selector": "/verifiers/compaction_replayed", "expected": true, "required": true },
+ { "id": "shell", "operator": "json_path_equals", "selector": "/verifiers/local_shell_correlated", "expected": true, "required": true },
+ { "id": "search", "operator": "json_path_equals", "selector": "/verifiers/tool_search_error", "expected": "fixture", "required": true }
+ ]
+ },
+ {
+ "id": "vision-core.protocol.input-image",
+ "suite": "vision-core",
+ "capability": "modalities.image.input",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["image"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "vision-input", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"READ\"},{\"type\":\"input_image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\",\"detail\":\"high\"}]}]}", "digest": "a26ba5209858c3658d698c1dcb6c92845b2e6aae6bab70a7b9ad1cba1d8aa6a5" },
+ "assertions": [
+ { "id": "text", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/0/content/0/text", "expected": "READ", "required": true },
+ { "id": "image", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/0/content/1/image_url", "expected": {"url":"data:image/png;base64,iVBORw0KGgo=","detail":"high"}, "required": true }
+ ]
+ },
+ {
+ "id": "vision-core.protocol.tool-result-image",
+ "suite": "vision-core",
+ "capability": "modalities.image.input",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["tools","image"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "vision-tool-result", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"callId\":\"call_fixture\",\"result\":[{\"type\":\"input_text\",\"text\":\"RESULT\"},{\"type\":\"input_image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\"}]}", "digest": "02c724259bb3c98002842cafad6d890d3dab7db287f1803fd9ce97ec79630a6d" },
+ "assertions": [
+ { "id": "tool-text", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/0", "expected": {"role":"tool","tool_call_id":"call_fixture","content":"RESULT"}, "required": true },
+ { "id": "image-carrier", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/messages/1/content/0/image_url/url", "expected": "data:image/png;base64,iVBORw0KGgo=", "required": true }
+ ]
+ },
+ {
+ "id": "vision-core.protocol.modality-gate",
+ "suite": "vision-core",
+ "capability": "modalities.image.input",
+ "verificationRole": "negative_control",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": [], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "vision-gate", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"model\":\"text-only\",\"modelInputModalities\":[\"text\"],\"visionSidecar\":{\"enabled\":false},\"requestHasImage\":true}", "digest": "d5b438fb3fad873b0a1bb1b6c91539862e4f3aa8690a963eb6121c5a3229818a" },
+ "assertions": [
+ { "id": "path", "operator": "json_path_equals", "selector": "/verifiers/modality_path", "expected": "unsupported", "required": true },
+ { "id": "no-drop", "operator": "json_path_equals", "selector": "/verifiers/silent_image_drop", "expected": false, "required": true }
+ ],
+ "expectedFailure": { "controlKind": "conformance_negative_control", "expectedClass": "capability_failure", "expectedCode": "image_input_unsupported", "assertionIds": ["path", "no-drop"], "onMatch": "pass", "onMismatch": "fail" }
+ },
+ {
+ "id": "reasoning-core.protocol.effort-mapping",
+ "suite": "reasoning-core",
+ "capability": "reasoning.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["reasoning"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "reasoning-effort", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"requested\":\"high\",\"reasoningEffortMap\":{\"high\":\"adaptive\"},\"reasoningWireFormat\":\"gateway-object\"}", "digest": "d9d5cce104809764d5edbc833088a0a9bb3b4d678a4f135353cc5fecf62e8b57" },
+ "assertions": [
+ { "id": "wire", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/reasoning", "expected": {"enabled":true,"effort":"adaptive"}, "required": true },
+ { "id": "legacy-absent", "operator": "json_path_absent", "selector": "/upstream/requests/0/json/reasoning_effort", "expected": true, "required": true }
+ ]
+ },
+ {
+ "id": "reasoning-core.protocol.summary-stream",
+ "suite": "reasoning-core",
+ "capability": "reasoning.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-sse"], "requiredClaims": ["reasoning"], "requiredHarnessFeatures": ["raw_sse_capture"], "platforms": [], "routePreconditions": [] },
+ "initiatingRequest": { "id": "reasoning-summary-request", "role": "client_request", "mediaType": "application/json", "bytesUtf8": "{\"model\":\"fixture-model\",\"input\":\"PING\",\"stream\":true}", "digest": "c2c39a78b939e6c5182d3206f86aa86d6fd706959de9c37072db759aa510a1f6" },
+ "fixture": { "id": "reasoning-summary", "role": "upstream_response", "mediaType": "text/event-stream", "bytesUtf8": "event: response.reasoning_summary_part.added\ndata: {\"type\":\"response.reasoning_summary_part.added\",\"item_id\":\"rs_fixture\",\"summary_index\":0,\"part\":{\"type\":\"summary_text\",\"text\":\"\"}}\n\nevent: response.reasoning_summary_text.delta\ndata: {\"type\":\"response.reasoning_summary_text.delta\",\"item_id\":\"rs_fixture\",\"summary_index\":0,\"delta\":\"WHY\"}\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"response\":{\"status\":\"completed\"}}\n\n", "digest": "d9c4fa73b67f7a92d9ec55af7ff12b16ddc9870059e5e530ee04006b171367e7" },
+ "assertions": [
+ { "id": "events", "operator": "sse_event_sequence", "selector": "/client/response/events", "expected": ["response.reasoning_summary_part.added","response.reasoning_summary_text.delta","response.completed"], "required": true },
+ { "id": "id", "operator": "id_matches", "selector": "/client/response/events/0/data/item_id", "expected": "responses_reasoning", "required": true }
+ ]
+ },
+ {
+ "id": "reasoning-core.protocol.replay",
+ "suite": "reasoning-core",
+ "capability": "reasoning.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-responses"], "surfaces": ["responses-http"], "requiredClaims": ["reasoning"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "reasoning-replay", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"turn1\":{\"reasoning\":{\"id\":\"rs_fixture\",\"text\":\"PLAN\",\"signature\":\"sig_fixture\"},\"toolCall\":{\"callId\":\"call_fixture\"}},\"turn2\":{\"toolResult\":{\"callId\":\"call_fixture\",\"output\":\"RESULT\"}}}", "digest": "6e137e06f52c32e9f7d394b92343a8b849103328e958ab7c9b2825a799ea60c3" },
+ "assertions": [
+ { "id": "text", "operator": "json_path_equals", "selector": "/upstream/requests/1/json/input/0/content/0/text", "expected": "PLAN", "required": true },
+ { "id": "signature", "operator": "json_path_equals", "selector": "/upstream/requests/1/json/input/0/signature", "expected": "sig_fixture", "required": true }
+ ]
+ },
+ {
+ "id": "reasoning-core.protocol.private-content-isolation",
+ "suite": "reasoning-core",
+ "capability": "reasoning.round_trip",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["openai-chat"], "surfaces": ["responses-http"], "requiredClaims": ["reasoning"], "requiredHarnessFeatures": ["adapter_vector"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "reasoning-private", "role": "adapter_vector", "mediaType": "application/vnd.opencodex.adapter-vector+json", "bytesUtf8": "{\"origin\":{\"provider\":\"alpha\",\"encrypted\":\"opaque_fixture\"},\"destination\":{\"provider\":\"beta\",\"adapter\":\"openai-chat\"}}", "digest": "3519bd299fe2cd5b8069e0cd1c3b65b61d5ce9588c66e54b49d42af5ccf0c81e" },
+ "assertions": [
+ { "id": "upstream-absent", "operator": "json_path_absent", "selector": "/upstream/requests/0/json/encrypted_content", "expected": true, "required": true },
+ { "id": "client-absent", "operator": "json_path_absent", "selector": "/client/response/json/hidden_reasoning", "expected": true, "required": true }
+ ]
+ },
+ {
+ "id": "mcp-core.protocol.namespace-mapping",
+ "suite": "mcp-core",
+ "capability": "tools.mcp.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["cursor-protobuf"], "surfaces": ["responses-http"], "requiredClaims": ["mcp"], "requiredHarnessFeatures": ["adapter_vector","in_memory_mcp_stub","mcp_namespace_round_trip_v1"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "mcp-namespace", "role": "synthetic_tool", "mediaType": "application/vnd.opencodex.mcp-stub+json", "bytesUtf8": "{\"namespace\":\"mcp__fixture\",\"name\":\"lookup\",\"description\":\"fixture\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"q\":{\"type\":\"string\"}}}}", "digest": "91a53f8c580d461d0f5e0d7209e5d4b95249bdfa8bd3fd4f298e18bdeadb0693" },
+ "assertions": [
+ { "id": "wire-name", "operator": "json_path_equals", "selector": "/upstream/requests/0/json/tools/0/name", "expected": "mcp__fixture__lookup", "required": true },
+ { "id": "reverse", "operator": "json_path_equals", "selector": "/client/response/mcpCalls/0", "expected": {"namespace":"mcp__fixture","name":"lookup"}, "required": true }
+ ]
+ },
+ {
+ "id": "mcp-core.protocol.schema-and-bounds",
+ "suite": "mcp-core",
+ "capability": "tools.mcp.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["cursor-protobuf"], "surfaces": ["responses-http"], "requiredClaims": ["mcp"], "requiredHarnessFeatures": ["adapter_vector","in_memory_mcp_stub","mcp_schema_bounds_v1"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "mcp-bounds", "role": "synthetic_tool", "mediaType": "application/vnd.opencodex.mcp-stub+json", "bytesUtf8": "{\"limitBytes\":64,\"exactSchema\":\"{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"x\\\":{\\\"type\\\":\\\"string\\\"}},\\\"a\\\":\\\"xxx\\\"}\",\"overSchema\":\"{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"x\\\":{\\\"type\\\":\\\"string\\\"}},\\\"a\\\":\\\"xxxx\\\"}\"}", "digest": "34ff4414dc8e196d460390557f4fd74c32418ea00710167baff2a0dc1f3b643c" },
+ "assertions": [
+ { "id": "exact", "operator": "verifier_result_equals", "selector": "/verifiers/exact_bound", "expected": "pass", "required": true },
+ { "id": "over", "operator": "verifier_result_equals", "selector": "/verifiers/one_over_rejected", "expected": "pass", "required": true },
+ { "id": "atomic", "operator": "json_path_equals", "selector": "/verifiers/partial_commit", "expected": false, "required": true }
+ ]
+ },
+ {
+ "id": "mcp-core.protocol.call-result",
+ "suite": "mcp-core",
+ "capability": "tools.mcp.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["cursor-protobuf"], "surfaces": ["responses-http"], "requiredClaims": ["mcp"], "requiredHarnessFeatures": ["adapter_vector","in_memory_mcp_stub","mcp_call_result_v1"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "mcp-call", "role": "synthetic_tool", "mediaType": "application/vnd.opencodex.mcp-stub+json", "bytesUtf8": "{\"namespace\":\"mcp__fixture\",\"name\":\"lookup\",\"arguments\":{\"q\":\"x\"},\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"RESULT\"}],\"isError\":false}}", "digest": "986ef5017fbdb46eb18b30daaffe72aecc93868b7d89b11c3e244dc084f46496" },
+ "assertions": [
+ { "id": "call", "operator": "json_path_equals", "selector": "/verifiers/stub_received", "expected": {"namespace":"mcp__fixture","name":"lookup","arguments":{"q":"x"}}, "required": true },
+ { "id": "result", "operator": "json_path_equals", "selector": "/client/response/json", "expected": {"content":[{"type":"text","text":"RESULT"}],"isError":false}, "required": true }
+ ]
+ },
+ {
+ "id": "mcp-core.protocol.resource-round-trip",
+ "suite": "mcp-core",
+ "capability": "tools.mcp.core",
+ "requirements": { "inboundProtocols": ["openai-responses"], "upstreamProtocols": ["cursor-protobuf"], "surfaces": ["responses-http"], "requiredClaims": ["mcp"], "requiredHarnessFeatures": ["adapter_vector","in_memory_mcp_stub","mcp_resource_round_trip_v1"], "platforms": [], "routePreconditions": [] },
+ "fixture": { "id": "mcp-resource", "role": "synthetic_tool", "mediaType": "application/vnd.opencodex.mcp-stub+json", "bytesUtf8": "{\"resources\":[{\"uri\":\"fixture://one\",\"name\":\"one\"}],\"read\":{\"uri\":\"fixture://one\",\"contents\":[{\"uri\":\"fixture://one\",\"text\":\"RESOURCE\"}]}}", "digest": "a3f6317374ce92da0155dd14bbf0d5822e8687cbe8ef7968221f23acf8b16aa5" },
+ "assertions": [
+ { "id": "list", "operator": "json_path_equals", "selector": "/client/response/json/resources", "expected": [{"uri":"fixture://one","name":"one"}], "required": true },
+ { "id": "read", "operator": "json_path_equals", "selector": "/client/response/json/contents", "expected": [{"uri":"fixture://one","text":"RESOURCE"}], "required": true }
+ ]
+ }
+ ]
+}
diff --git a/src/lab/conformance/harness-budget.ts b/src/lab/conformance/harness-budget.ts
new file mode 100644
index 000000000..a161f5ec2
--- /dev/null
+++ b/src/lab/conformance/harness-budget.ts
@@ -0,0 +1,47 @@
+import type { IncomingMeta, ProviderAdapter } from "../../adapters/base";
+import { createTranslatorBudget, type TranslatorBudget } from "../../lib/translator-budget";
+
+type TestAdapter = Omit & {
+ buildRequest(
+ parsed: Parameters[0],
+ incoming?: Partial,
+ ): ReturnType;
+ parseStream(response: Response, budget?: TranslatorBudget): ReturnType;
+ parseResponse?: (
+ response: Response,
+ budget?: TranslatorBudget,
+ ) => ReturnType>;
+ dispose(): void;
+};
+
+/** Inject one bounded translator budget for a harness adapter scope. Call dispose() in finally. */
+export function withHarnessTranslatorBudget(adapter: T): TestAdapter {
+ const budget = createTranslatorBudget();
+ const buildRequest = adapter.buildRequest.bind(adapter);
+ const parseStream = adapter.parseStream.bind(adapter);
+ const parseResponse = adapter.parseResponse?.bind(adapter);
+ let disposed = false;
+ return {
+ ...adapter,
+ buildRequest(parsed: Parameters[0], incoming?: Partial) {
+ return buildRequest(parsed, {
+ ...incoming,
+ headers: incoming?.headers ?? new Headers(),
+ translatorBudget: incoming?.translatorBudget ?? budget,
+ });
+ },
+ parseStream(response: Response, explicitBudget?: TranslatorBudget) {
+ return parseStream(response, explicitBudget ?? budget);
+ },
+ ...(parseResponse ? {
+ parseResponse(response: Response, explicitBudget?: TranslatorBudget) {
+ return parseResponse(response, explicitBudget ?? budget);
+ },
+ } : {}),
+ dispose() {
+ if (disposed) return;
+ disposed = true;
+ budget.dispose();
+ },
+ } as unknown as TestAdapter;
+}
diff --git a/src/lab/conformance/index.ts b/src/lab/conformance/index.ts
new file mode 100644
index 000000000..154292fb3
--- /dev/null
+++ b/src/lab/conformance/index.ts
@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./manifest";
+export * from "./runner";
+export * from "./executor";
+export * from "./negative-controls";
diff --git a/src/lab/conformance/jcs.ts b/src/lab/conformance/jcs.ts
new file mode 100644
index 000000000..6bbcb923c
--- /dev/null
+++ b/src/lab/conformance/jcs.ts
@@ -0,0 +1,24 @@
+/** RFC 8785 JSON Canonicalization Scheme (JCS) for deterministic equality. */
+
+export function jcsStringify(value: unknown): string {
+ if (value === undefined) throw new TypeError("jcsStringify: undefined is not representable in JCS");
+ if (value === null || typeof value === "boolean") return JSON.stringify(value);
+ if (typeof value === "number") {
+ if (!Number.isFinite(value)) throw new TypeError("jcsStringify: non-finite numbers are not representable in JCS");
+ return JSON.stringify(value);
+ }
+ if (typeof value === "string") return JSON.stringify(value);
+ if (Array.isArray(value)) {
+ return `[${value.map(jcsStringify).join(",")}]`;
+ }
+ if (typeof value === "object") {
+ const obj = value as Record;
+ const keys = Object.keys(obj).sort();
+ return `{${keys.map((k) => `${JSON.stringify(k)}:${jcsStringify(obj[k])}`).join(",")}}`;
+ }
+ throw new TypeError(`jcsStringify: unsupported value type ${typeof value}`);
+}
+
+export function jcsEqual(a: unknown, b: unknown): boolean {
+ return jcsStringify(a) === jcsStringify(b);
+}
diff --git a/src/lab/conformance/json-pointer.ts b/src/lab/conformance/json-pointer.ts
new file mode 100644
index 000000000..1676d0abf
--- /dev/null
+++ b/src/lab/conformance/json-pointer.ts
@@ -0,0 +1,39 @@
+/** RFC 6901 JSON Pointer resolution for assertion selectors. */
+
+export type PointerResult =
+ | { ok: true; value: unknown }
+ | { ok: false; reason: "selector_missing" | "selector_type_mismatch" };
+
+function decodeToken(token: string): string {
+ return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+export function resolveJsonPointer(root: unknown, pointer: string): PointerResult {
+ if (!pointer.startsWith("/")) return { ok: false, reason: "selector_missing" };
+ if (pointer === "/") return { ok: true, value: root };
+ const tokens = pointer.slice(1).split("/").map(decodeToken);
+ let current: unknown = root;
+ for (const token of tokens) {
+ if (token === "-") return { ok: false, reason: "selector_missing" };
+ if (Array.isArray(current)) {
+ if (!/^(0|[1-9][0-9]*)$/.test(token)) return { ok: false, reason: "selector_missing" };
+ const index = Number(token);
+ if (index >= current.length) return { ok: false, reason: "selector_missing" };
+ current = current[index];
+ continue;
+ }
+ if (current === null || typeof current !== "object") {
+ return { ok: false, reason: "selector_missing" };
+ }
+ const obj = current as Record;
+ if (!Object.prototype.hasOwnProperty.call(obj, token)) {
+ return { ok: false, reason: "selector_missing" };
+ }
+ current = obj[token];
+ }
+ return { ok: true, value: current };
+}
+
+export function pointerExists(root: unknown, pointer: string): boolean {
+ return resolveJsonPointer(root, pointer).ok;
+}
diff --git a/src/lab/conformance/manifest.ts b/src/lab/conformance/manifest.ts
new file mode 100644
index 000000000..df8001239
--- /dev/null
+++ b/src/lab/conformance/manifest.ts
@@ -0,0 +1,180 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { fixtureDigest } from "./digest";
+import { MCP_ACTION_TOKENS } from "./mcp-stub";
+import type {
+ CaseAuthority,
+ CaseRecord,
+ FailureClassification,
+ FailureRule,
+} from "./types";
+import { CL01_SUITES, SYNTHETIC_MARKER } from "./types";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+// Provenance is the normative CL-00 authority name, not the runtime copy's basename.
+const AUTHORITY_FILE = "022_protocol_v1_cases.json";
+
+export function loadCaseAuthority(): CaseAuthority {
+ const path = join(MODULE_DIR, "fixtures", "protocol-v1-cases.json");
+ const raw = JSON.parse(readFileSync(path, "utf8")) as CaseAuthority;
+ validateAuthority(raw);
+ return raw;
+}
+
+export function discoverScenarios(
+ authority: CaseAuthority,
+ suites: readonly string[] = CL01_SUITES,
+): CaseRecord[] {
+ return authority.cases.filter((c) => suites.includes(c.suite));
+}
+
+export function expandScenario(caseRecord: CaseRecord, authority: CaseAuthority): Record {
+ 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,
+ assertions: caseRecord.assertions,
+ ...(caseRecord.expectedFailure ? { expectedFailure: caseRecord.expectedFailure } : {}),
+ failureRules: expandFailureRules(caseRecord, authority),
+ artifactPolicy: defaults.artifactPolicy,
+ freshness: defaults.freshness,
+ };
+}
+
+function fixtureRef(fixture: CaseRecord["fixture"], authority: CaseAuthority): Record {
+ 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 expandFailureRules(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((r) => r.id === "required-assertion");
+ if (idx >= 0) base.splice(idx, 0, controlRule);
+ else base.push(controlRule);
+ return base;
+}
+
+export function validateFixtureDigests(caseRecord: CaseRecord): string[] {
+ const errors: string[] = [];
+ const check = (fixture: CaseRecord["fixture"], label: string) => {
+ const bytes = new TextEncoder().encode(fixture.bytesUtf8);
+ const digest = fixtureDigest(bytes);
+ if (digest !== fixture.digest) {
+ errors.push(`${label} digest mismatch: expected ${fixture.digest}, got ${digest}`);
+ }
+ };
+ check(caseRecord.fixture, caseRecord.fixture.id);
+ if (caseRecord.initiatingRequest) check(caseRecord.initiatingRequest, caseRecord.initiatingRequest.id);
+ return errors;
+}
+
+export function validateExpandedFixtureRef(
+ ref: Record,
+ authority: CaseAuthority,
+ fixtureBytes: string,
+): string[] {
+ const errors: string[] = [];
+ const bytes = new TextEncoder().encode(fixtureBytes);
+ if (ref.syntheticMarker !== SYNTHETIC_MARKER) {
+ errors.push(`invalid syntheticMarker: ${String(ref.syntheticMarker)}`);
+ }
+ const provenance = ref.provenance as Record | undefined;
+ if (!provenance || provenance.kind !== "lab_authored") {
+ errors.push("invalid provenance kind");
+ } else if (provenance.authority !== AUTHORITY_FILE) {
+ errors.push(`invalid provenance authority: ${String(provenance.authority)}`);
+ } else if (provenance.sourceCommit !== authority.sourceCommit) {
+ errors.push(`invalid provenance sourceCommit: ${String(provenance.sourceCommit)}`);
+ }
+ if (ref.digest !== fixtureDigest(bytes)) {
+ errors.push("fixture digest mismatch in expanded ref");
+ }
+ if (ref.byteLength !== bytes.byteLength) {
+ errors.push("fixture byteLength mismatch in expanded ref");
+ }
+ return errors;
+}
+
+function validateMcpHarnessFeatures(caseRecord: CaseRecord): string[] {
+ if (caseRecord.suite !== "mcp-core") return [];
+ const tokens = caseRecord.requirements.requiredHarnessFeatures.filter(
+ (f) => MCP_ACTION_TOKENS.includes(f as typeof MCP_ACTION_TOKENS[number]),
+ );
+ if (tokens.length !== 1) {
+ return [`${caseRecord.id}: invalid_manifest MCP action token count ${tokens.length}`];
+ }
+ if (caseRecord.fixture.role !== "synthetic_tool") {
+ return [`${caseRecord.id}: MCP cases require synthetic_tool fixture role`];
+ }
+ return [];
+}
+
+function validateAuthority(authority: CaseAuthority): void {
+ if (authority.schemaVersion !== 1) throw new Error("unsupported schemaVersion");
+ if (!authority.sourceCommit || typeof authority.sourceCommit !== "string") {
+ throw new Error("missing sourceCommit");
+ }
+ if (!Array.isArray(authority.cases) || authority.cases.length === 0) throw new Error("no cases");
+ for (const caseRecord of authority.cases) {
+ const errors = [
+ ...validateFixtureDigests(caseRecord),
+ ...validateMcpHarnessFeatures(caseRecord),
+ ];
+ const expanded = expandScenario(caseRecord, authority);
+ const fixtures = expanded.fixtures as Array>;
+ for (let i = 0; i < fixtures.length; i++) {
+ const fixtureSource = i === 0 && caseRecord.initiatingRequest
+ ? caseRecord.initiatingRequest.bytesUtf8
+ : caseRecord.fixture.bytesUtf8;
+ errors.push(...validateExpandedFixtureRef(fixtures[i], authority, fixtureSource));
+ }
+ if (errors.length > 0) throw new Error(errors.join("; "));
+ if (caseRecord.fixture.role === "upstream_response" && !caseRecord.initiatingRequest) {
+ throw new Error(`${caseRecord.id}: upstream_response without initiatingRequest`);
+ }
+ }
+}
diff --git a/src/lab/conformance/mcp-stub.ts b/src/lab/conformance/mcp-stub.ts
new file mode 100644
index 000000000..ee50b3599
--- /dev/null
+++ b/src/lab/conformance/mcp-stub.ts
@@ -0,0 +1,179 @@
+import type { CaseRecord, NormalizedObservation } from "./types";
+import { emptyObservation, projectMcpCalls, setClientResponse } from "./observation";
+
+export const MCP_ACTION_TOKENS = [
+ "mcp_namespace_round_trip_v1",
+ "mcp_schema_bounds_v1",
+ "mcp_call_result_v1",
+ "mcp_resource_round_trip_v1",
+] as const;
+
+export type McpActionToken = typeof MCP_ACTION_TOKENS[number];
+
+export function mcpActionToken(caseRecord: CaseRecord): McpActionToken | null {
+ const features = caseRecord.requirements.requiredHarnessFeatures;
+ const tokens = features.filter((f) => MCP_ACTION_TOKENS.includes(f as McpActionToken));
+ if (tokens.length !== 1) return null;
+ return tokens[0] as McpActionToken;
+}
+
+export function executeMcpSyntheticAction(caseRecord: CaseRecord): NormalizedObservation {
+ const token = mcpActionToken(caseRecord);
+ if (!token) throw new Error(`invalid_manifest: missing or ambiguous MCP action token for ${caseRecord.id}`);
+ const decoded = JSON.parse(caseRecord.fixture.bytesUtf8) as Record;
+ switch (token) {
+ case "mcp_namespace_round_trip_v1":
+ return runNamespaceRoundTrip(decoded);
+ case "mcp_schema_bounds_v1":
+ return runSchemaBounds(decoded);
+ case "mcp_call_result_v1":
+ return runCallResult(decoded);
+ case "mcp_resource_round_trip_v1":
+ return runResourceRoundTrip(decoded);
+ }
+}
+
+function nonEmptyString(value: unknown): value is string {
+ return typeof value === "string" && value.length > 0;
+}
+
+function runNamespaceRoundTrip(decoded: Record): NormalizedObservation {
+ if (!nonEmptyString(decoded.namespace) || !nonEmptyString(decoded.name)) {
+ throw new Error("invalid_manifest: MCP namespace/name must be non-empty strings");
+ }
+ const namespace = decoded.namespace;
+ const name = decoded.name;
+ const wireName = `${namespace}__${name}`;
+ const observation = emptyObservation();
+ observation.upstream.requests.push({
+ status: 0,
+ headers: {},
+ json: {
+ model: "fixture-model",
+ tools: [{
+ name: wireName,
+ description: decoded.description,
+ inputSchema: decoded.inputSchema,
+ }],
+ },
+ rawBytes: 0,
+ });
+ const toolCalls = [{
+ id: "call_fixture",
+ name: wireName,
+ arguments: {},
+ kind: "function" as const,
+ ordinal: 0,
+ }];
+ setClientResponse(observation, {
+ toolCalls,
+ mcpCalls: projectMcpCalls(toolCalls),
+ status: 200,
+ });
+ return observation;
+}
+
+function utf8ByteLength(value: string): number {
+ return new TextEncoder().encode(value).byteLength;
+}
+
+function parsesJson(value: string): boolean {
+ try {
+ JSON.parse(value);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function runSchemaBounds(decoded: Record): NormalizedObservation {
+ const observation = emptyObservation();
+ const limitBytes = decoded.limitBytes;
+ const exactSchema = decoded.exactSchema;
+ const overSchema = decoded.overSchema;
+ if (!Number.isInteger(limitBytes) || (limitBytes as number) <= 0
+ || typeof exactSchema !== "string" || typeof overSchema !== "string") {
+ observation.verifiers = {
+ exact_bound: "fail",
+ one_over_rejected: "fail",
+ partial_commit: false,
+ };
+ return observation;
+ }
+
+ const limit = limitBytes as number;
+ const exactValid = utf8ByteLength(exactSchema) === limit && parsesJson(exactSchema);
+ // The inert stub models two isolated catalogue transactions. The over-bound transaction
+ // is rejected before commit; its validity matters so this tests the byte ceiling rather
+ // than malformed JSON.
+ const overRejected = utf8ByteLength(overSchema) === limit + 1 && parsesJson(overSchema);
+ observation.verifiers = {
+ exact_bound: exactValid ? "pass" : "fail",
+ one_over_rejected: overRejected ? "pass" : "fail",
+ partial_commit: false,
+ };
+ return observation;
+}
+
+function runCallResult(decoded: Record): NormalizedObservation {
+ if (!nonEmptyString(decoded.namespace) || !nonEmptyString(decoded.name)) {
+ throw new Error("invalid_manifest: MCP namespace/name must be non-empty strings");
+ }
+ const namespace = decoded.namespace;
+ const name = decoded.name;
+ const argumentsValue = decoded.arguments ?? {};
+ const result = decoded.result;
+ const wireName = `${namespace}__${name}`;
+ const observation = emptyObservation();
+ const toolCalls = [{
+ id: "call_fixture",
+ name: wireName,
+ arguments: argumentsValue,
+ kind: "function" as const,
+ ordinal: 0,
+ }];
+ setClientResponse(observation, {
+ toolCalls,
+ mcpCalls: projectMcpCalls(toolCalls),
+ json: result,
+ status: 200,
+ });
+ observation.verifiers = {
+ stub_received: { namespace, name, arguments: argumentsValue },
+ };
+ return observation;
+}
+
+function runResourceRoundTrip(decoded: Record): NormalizedObservation {
+ if (!Array.isArray(decoded.resources) || !decoded.read || typeof decoded.read !== "object") {
+ throw new Error("invalid_manifest: invalid MCP resource fixture");
+ }
+ const read = decoded.read as { uri?: unknown; contents?: unknown[] };
+ if (!nonEmptyString(read.uri) || !Array.isArray(read.contents)) {
+ throw new Error("invalid_manifest: invalid MCP resource read fixture");
+ }
+ const matching = decoded.resources.filter((resource) =>
+ resource && typeof resource === "object" && (resource as { uri?: unknown }).uri === read.uri
+ );
+ if (matching.length !== 1) throw new Error("invalid_manifest: MCP resource URI must resolve exactly once");
+ const observation = emptyObservation();
+ setClientResponse(observation, {
+ json: {
+ resources: decoded.resources,
+ contents: read.contents,
+ },
+ status: 200,
+ });
+ return observation;
+}
+
+export function attachMcpVerifiers(observation: NormalizedObservation, caseRecord: CaseRecord): void {
+ if (caseRecord.id === "mcp-core.protocol.namespace-mapping") {
+ const toolCalls = observation.client.response.toolCalls;
+ if (toolCalls.length === 1) {
+ observation.client.response.mcpCalls = projectMcpCalls(toolCalls);
+ }
+ }
+ // runCallResult records the literal one-invocation receipt. Do not reconstruct it here:
+ // assertions must inspect the action result that actually ran.
+}
diff --git a/src/lab/conformance/negative-controls.ts b/src/lab/conformance/negative-controls.ts
new file mode 100644
index 000000000..66ab70f4e
--- /dev/null
+++ b/src/lab/conformance/negative-controls.ts
@@ -0,0 +1,160 @@
+import type { CaseRecord } from "./types";
+
+/** Deliberately broken variants proving the harness rejects known defects. */
+export const NEGATIVE_CONTROL_FIXTURES: Array<{
+ id: string;
+ defect: string;
+ mutate: (caseRecord: CaseRecord) => CaseRecord;
+}> = [
+ {
+ id: "negative.malformed-sse",
+ defect: "malformed SSE JSON",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.malformed-sse",
+ assertions: [
+ { id: "events", operator: "sse_event_sequence", selector: "/client/response/events", expected: ["response.completed"], required: true },
+ { id: "terminal", operator: "terminal_signal_equals", selector: "/client/response/terminal", expected: "completed", required: true },
+ ],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: "data: {not-json}\n\ndata: {\"type\":\"response.completed\",\"response\":{\"status\":\"completed\"}}\n\n",
+ },
+ }),
+ },
+ {
+ id: "negative.missing-terminal",
+ defect: "missing terminal event",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.missing-terminal",
+ assertions: [{ id: "terminal", operator: "terminal_signal_equals", selector: "/client/response/terminal", expected: "completed", required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: "data: {\"type\":\"response.output_text.delta\",\"delta\":\"A\"}\n\n",
+ },
+ }),
+ },
+ {
+ id: "negative.corrupted-tool-id",
+ defect: "corrupted tool IDs",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.corrupted-tool-id",
+ assertions: [{ id: "alpha", operator: "tool_call_equals", selector: "/client/response/toolCalls/0", expected: { id: "call_a", name: "alpha", arguments: { x: 1 }, kind: "function", ordinal: 0 }, required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: "data:{\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"WRONG\",\"function\":{\"name\":\"alpha\",\"arguments\":\"{\\\"x\\\":1}\"}}]}}]}\n\ndata:{\"choices\":[{\"finish_reason\":\"tool_calls\"}]}\n\ndata:[DONE]\n\n",
+ },
+ }),
+ },
+ {
+ id: "negative.tool-result-order",
+ defect: "invalid tool-result ordering",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.tool-result-order",
+ assertions: [{ id: "result", operator: "tool_result_correlates", selector: "/upstream/requests", expected: { call: "/client/response/toolCalls/0/id", result: "/upstream/requests/1/json/messages/1/tool_call_id" }, required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: JSON.stringify({
+ tools: [{ name: "lookup", parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] } }],
+ upstreamToolCall: { id: "call_fixture", name: "lookup", arguments: "{\"q\":\"x\"}" },
+ toolResult: { toolCallId: "wrong_id", content: "RESULT" },
+ }),
+ },
+ }),
+ },
+ {
+ id: "negative.truncated-tool-args",
+ defect: "truncated tool arguments",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.truncated-tool-args",
+ assertions: [{ id: "alpha", operator: "tool_call_equals", selector: "/client/response/toolCalls/0", expected: { id: "call_a", name: "alpha", arguments: { x: 1 }, kind: "function", ordinal: 0 }, required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: `data: ${JSON.stringify({ choices: [{ delta: { tool_calls: [{ index: 0, id: "call_a", function: { name: "alpha", arguments: "{\"x\":" } }] } }] })}\n\ndata: ${JSON.stringify({ choices: [{ finish_reason: "tool_calls" }] })}\n\ndata: [DONE]\n\n`,
+ },
+ }),
+ },
+ {
+ id: "negative.parallel-tool-fragments",
+ defect: "duplicate parallel-tool fragments",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.parallel-tool-fragments",
+ assertions: [{ id: "order", operator: "json_path_equals", selector: "/verifiers/nonoverlap_order", expected: ["call_a", "call_b"], required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: "data:{\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_a\",\"function\":{\"name\":\"a\",\"arguments\":\"{}\"}},{\"index\":0,\"id\":\"call_a\",\"function\":{\"name\":\"a\",\"arguments\":\"{}\"}}]}}]}\n\ndata:{\"choices\":[{\"finish_reason\":\"tool_calls\"}]}\n\ndata:[DONE]\n\n",
+ },
+ }),
+ },
+ {
+ id: "negative.custom-tool-failure",
+ defect: "custom/freeform tool translation failure",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.custom-tool-failure",
+ assertions: [{ id: "call", operator: "tool_call_equals", selector: "/client/response/toolCalls/0", expected: { id: "call_patch", name: "apply_patch", arguments: "*** Begin Patch\n*** End Patch\n", kind: "custom", ordinal: 0 }, required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: JSON.stringify({
+ tool: { type: "custom", name: "apply_patch", format: { type: "grammar", syntax: "lark", definition: "start: /[\\s\\S]+/" } },
+ call: { id: "call_patch", name: "apply_patch", input: "WRONG PATCH" },
+ output: { call_id: "call_patch", output: "Done" },
+ }),
+ },
+ }),
+ },
+ {
+ id: "negative.continuation-semantics",
+ defect: "invalid continuation semantics",
+ mutate: (c) => ({
+ ...c,
+ id: "negative.continuation-semantics",
+ assertions: [{ id: "order", operator: "json_path_equals", selector: "/verifiers/call_result_order", expected: "pass", required: true }],
+ fixture: {
+ ...c.fixture,
+ bytesUtf8: JSON.stringify({
+ turn1: { output: [{ type: "function_call", id: "fc_fixture", call_id: "call_fixture", name: "lookup", arguments: "{}" }] },
+ turn2: { input: [{ type: "function_call_output", call_id: "wrong_call", output: "RESULT" }] },
+ }),
+ },
+ }),
+ },
+];
+
+export function baseCaseForNegativeControl(controlId: string, cases: CaseRecord[]): CaseRecord | undefined {
+ switch (controlId) {
+ case "negative.malformed-sse":
+ case "negative.missing-terminal":
+ return cases.find((c) => c.id === "responses-core.protocol.sse-framing");
+ case "negative.corrupted-tool-id":
+ case "negative.truncated-tool-args":
+ return cases.find((c) => c.id === "chat-core.protocol.stream-assembly");
+ case "negative.tool-result-order":
+ return cases.find((c) => c.id === "tools-core.protocol.function-round-trip");
+ case "negative.parallel-tool-fragments":
+ return cases.find((c) => c.id === "tools-core.protocol.parallel-correlation");
+ case "negative.custom-tool-failure":
+ return cases.find((c) => c.id === "tools-core.protocol.custom-freeform-round-trip");
+ case "negative.continuation-semantics":
+ return cases.find((c) => c.id === "codex-core.protocol.tool-continuation");
+ default:
+ return undefined;
+ }
+}
+
+export function buildNegativeControls(cases: CaseRecord[]): CaseRecord[] {
+ const built: CaseRecord[] = [];
+ for (const control of NEGATIVE_CONTROL_FIXTURES) {
+ const base = baseCaseForNegativeControl(control.id, cases);
+ if (!base) continue;
+ const cloned = structuredClone(base);
+ delete cloned.expectedFailure;
+ built.push(control.mutate(cloned));
+ }
+ return built;
+}
diff --git a/src/lab/conformance/observation.ts b/src/lab/conformance/observation.ts
new file mode 100644
index 000000000..0f1cca02d
--- /dev/null
+++ b/src/lab/conformance/observation.ts
@@ -0,0 +1,355 @@
+import type {
+ CaseRecord,
+ NormalizedEvent,
+ NormalizedObservation,
+ ToolCallProjection,
+} from "./types";
+import { normalizeSseBytes } from "./sse-normalize";
+
+export function emptyObservation(): NormalizedObservation {
+ return {
+ client: {
+ request: { status: 0, headers: {}, json: null, rawBytes: 0 },
+ response: {
+ status: 0,
+ headers: {},
+ json: null,
+ events: [],
+ toolCalls: [],
+ mcpCalls: [],
+ terminal: null,
+ normalizedText: "",
+ },
+ },
+ upstream: { requests: [], responses: [] },
+ process: { exitCode: null },
+ verifiers: {},
+ };
+}
+
+export function recordUpstreamRequest(
+ observation: NormalizedObservation,
+ json: unknown,
+ status = 0,
+): void {
+ const body = JSON.stringify(json ?? null);
+ observation.upstream.requests.push({
+ status,
+ headers: {},
+ json,
+ rawBytes: new TextEncoder().encode(body).byteLength,
+ });
+}
+
+export function setClientResponse(
+ observation: NormalizedObservation,
+ patch: Partial,
+): void {
+ observation.client.response = { ...observation.client.response, ...patch };
+}
+
+function parseToolArguments(raw: unknown, kind: "function" | "custom"): unknown {
+ if (kind === "custom") return typeof raw === "string" ? raw : "";
+ if (typeof raw === "string") {
+ try { return JSON.parse(raw); } catch { return null; }
+ }
+ return raw;
+}
+
+interface ToolCallProjectionResult {
+ calls: ToolCallProjection[];
+ sawCallItems: boolean;
+ duplicateIds: boolean;
+}
+
+function projectToolCallsDetailed(output: unknown[]): ToolCallProjectionResult {
+ const calls: ToolCallProjection[] = [];
+ let ordinal = 0;
+ let sawCallItems = false;
+ for (const item of output) {
+ if (!item || typeof item !== "object") continue;
+ const rec = item as Record;
+ if (rec.type === "function_call") {
+ sawCallItems = true;
+ const id = rec.call_id ?? rec.id;
+ const name = rec.name;
+ if (typeof id !== "string" || id.length === 0 || typeof name !== "string" || name.length === 0) continue;
+ const args = parseToolArguments(rec.arguments, "function");
+ if (args === null) continue;
+ calls.push({ id, name, arguments: args, kind: "function", ordinal: ordinal++ });
+ } else if (rec.type === "custom_tool_call") {
+ sawCallItems = true;
+ const id = rec.call_id ?? rec.id;
+ const name = rec.name;
+ if (typeof id !== "string" || id.length === 0 || typeof name !== "string" || name.length === 0) continue;
+ calls.push({
+ id,
+ name,
+ arguments: parseToolArguments(rec.input, "custom"),
+ kind: "custom",
+ ordinal: ordinal++,
+ });
+ }
+ }
+ const ids = calls.map((call) => call.id);
+ const duplicateIds = new Set(ids).size !== ids.length;
+ return { calls: duplicateIds ? [] : calls, sawCallItems, duplicateIds };
+}
+
+/** Build toolCalls projection from Responses output items or SSE events (manifest §5). */
+export function projectToolCallsFromOutput(output: unknown[]): ToolCallProjection[] {
+ return projectToolCallsDetailed(output).calls;
+}
+
+function projectToolCallsFromEventsDetailed(events: NormalizedEvent[]): ToolCallProjectionResult {
+ const output: unknown[] = [];
+ for (const ev of events) {
+ if (ev.event === "response.output_item.done" && ev.data && typeof ev.data === "object") {
+ const data = ev.data as Record;
+ const item = data.item;
+ if (item && typeof item === "object") output.push(item);
+ }
+ }
+ return projectToolCallsDetailed(output);
+}
+
+export function projectToolCallsFromEvents(events: NormalizedEvent[]): ToolCallProjection[] {
+ return projectToolCallsFromEventsDetailed(events).calls;
+}
+
+export function projectMcpCalls(toolCalls: ToolCallProjection[]): Array<{ namespace: string; name: string }> {
+ const out: Array<{ namespace: string; name: string }> = [];
+ for (const call of toolCalls) {
+ if (!call.name.startsWith("mcp__")) continue;
+ const idx = call.name.lastIndexOf("__");
+ if (idx <= 0 || idx >= call.name.length - 2) continue;
+ const namespace = call.name.slice(0, idx);
+ const name = call.name.slice(idx + 2);
+ if (!namespace || !name) continue;
+ if (new TextEncoder().encode(namespace).byteLength > 64 || new TextEncoder().encode(name).byteLength > 64) continue;
+ out.push({ namespace, name });
+ }
+ return out;
+}
+
+export function filterAnthropicEvents(events: ReturnType): ReturnType {
+ return events.filter((e) => e.event !== "ping");
+}
+
+function deriveTerminal(events: NormalizedEvent[]): string | null {
+ if (events.some((e) => e.event === "error")) return "failed";
+ if (events.some((e) => e.event === "response.failed")) return "failed";
+ if (events.some((e) => e.event === "response.completed")) return "completed";
+ if (events.some((e) => e.event === "message_stop")) return "message_stop";
+ if (events.some((e) => e.event === "response.incomplete")) return "incomplete";
+ return null;
+}
+
+function extractOutputText(json: Record): string {
+ let text = "";
+ const output = json.output;
+ if (!Array.isArray(output)) return text;
+ for (const item of output) {
+ if (!item || typeof item !== "object") continue;
+ const content = (item as { content?: unknown[] }).content;
+ if (!Array.isArray(content)) continue;
+ for (const part of content) {
+ if (part && typeof part === "object" && (part as { type?: string }).type === "output_text") {
+ text += String((part as { text?: string }).text ?? "");
+ }
+ }
+ }
+ return text;
+}
+
+export function deriveNormalizedText(events: NormalizedEvent[], json: unknown): string {
+ if (json && typeof json === "object" && !Array.isArray(json)) {
+ const text = extractOutputText(json as Record);
+ if (text) return text;
+ }
+ let text = "";
+ for (const ev of events) {
+ if (ev.event === "response.output_text.delta" && ev.data && typeof ev.data === "object") {
+ text += String((ev.data as { delta?: string }).delta ?? "");
+ }
+ if (ev.event === "content_block_delta" && ev.data && typeof ev.data === "object") {
+ const delta = (ev.data as { delta?: { text?: string } }).delta;
+ if (delta && typeof delta.text === "string") text += delta.text;
+ }
+ }
+ return text;
+}
+
+export function finalizeObservation(
+ observation: NormalizedObservation,
+ events: NormalizedEvent[],
+ json: unknown = null,
+ status = 200,
+): void {
+ const eventProjection = projectToolCallsFromEventsDetailed(events);
+ const jsonProjection = projectToolCallsDetailed(
+ json && typeof json === "object" && !Array.isArray(json)
+ ? ((json as { output?: unknown[] }).output ?? [])
+ : [],
+ );
+ const selectedProjection = eventProjection.sawCallItems ? eventProjection : jsonProjection;
+ const resolvedToolCalls = selectedProjection.calls;
+ const terminal = deriveTerminal(events);
+ setClientResponse(observation, {
+ events,
+ toolCalls: resolvedToolCalls,
+ mcpCalls: projectMcpCalls(resolvedToolCalls),
+ terminal,
+ normalizedText: deriveNormalizedText(events, json),
+ json,
+ status,
+ });
+ observation.verifiers.duplicate_tool_call_ids = selectedProjection.duplicateIds;
+}
+
+export function attachVerifiers(observation: NormalizedObservation, caseRecord: CaseRecord): void {
+ observation.verifiers = { ...observation.verifiers, ...buildVerifiers(observation, caseRecord) };
+}
+
+function buildVerifiers(observation: NormalizedObservation, caseRecord: CaseRecord): Record {
+ const verifiers: Record = {};
+ const toolCalls = observation.client.response.toolCalls;
+
+ verifiers.nonoverlap_order = (() => {
+ const ids: string[] = [];
+ for (let i = 0; i < toolCalls.length; i++) {
+ const call = toolCalls[i];
+ if (!call.id || call.arguments === null) return [];
+ if (call.ordinal !== i) return [];
+ ids.push(call.id);
+ }
+ const unique = new Set(ids);
+ return unique.size === ids.length ? ids : [];
+ })();
+
+ verifiers.call_result_order = evaluateCallResultOrder(observation);
+
+ if (caseRecord.id === "codex-core.protocol.compaction-and-special-items") {
+ verifiers.compaction_replayed = evaluateCompactionReplayed(caseRecord);
+ verifiers.local_shell_correlated = evaluateLocalShellCorrelated(caseRecord);
+ verifiers.tool_search_error = evaluateToolSearchError(caseRecord);
+ }
+
+ if (caseRecord.id === "responses-core.protocol.json-sse-equivalence") {
+ verifiers.json_sse_equivalence = evaluateJsonSseEquivalence(caseRecord);
+ }
+
+ if (caseRecord.id === "vision-core.protocol.modality-gate") {
+ verifiers.modality_path = evaluateModalityPath(caseRecord);
+ verifiers.silent_image_drop = evaluateSilentImageDrop(caseRecord);
+ }
+
+ return verifiers;
+}
+
+function evaluateCallResultOrder(observation: NormalizedObservation): string {
+ const request = observation.upstream.requests[0]?.json as { input?: unknown[] } | undefined;
+ const input = request?.input;
+ if (!Array.isArray(input)) return "fail";
+ const pendingCallIds = new Set();
+ let callCount = 0;
+ let resultCount = 0;
+ for (const item of input) {
+ if (!item || typeof item !== "object") continue;
+ const record = item as { type?: string; call_id?: unknown };
+ if (record.type === "function_call") {
+ if (typeof record.call_id !== "string" || record.call_id.length === 0) return "fail";
+ if (pendingCallIds.has(record.call_id)) return "fail";
+ pendingCallIds.add(record.call_id);
+ callCount++;
+ continue;
+ }
+ if (record.type === "function_call_output") {
+ if (typeof record.call_id !== "string" || record.call_id.length === 0) return "fail";
+ if (!pendingCallIds.delete(record.call_id)) return "fail";
+ resultCount++;
+ }
+ }
+ return callCount > 0 && resultCount === callCount && pendingCallIds.size === 0 ? "pass" : "fail";
+}
+
+function evaluateCompactionReplayed(caseRecord: CaseRecord): boolean {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as { input?: unknown[] };
+ const input = vector.input;
+ if (!Array.isArray(input)) return false;
+ const compaction = input.find((i) => i && typeof i === "object" && (i as { type?: string }).type === "context_compaction");
+ if (!compaction) return false;
+ return typeof (compaction as { encrypted_content?: string }).encrypted_content === "string";
+}
+
+function evaluateLocalShellCorrelated(caseRecord: CaseRecord): boolean {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as { input?: unknown[] };
+ const input = vector.input;
+ if (!Array.isArray(input)) return false;
+ let shellId: string | undefined;
+ for (const item of input) {
+ if (!item || typeof item !== "object") continue;
+ const type = (item as { type?: string }).type;
+ if (type === "local_shell_call") {
+ shellId = String((item as { call_id?: string }).call_id ?? "");
+ continue;
+ }
+ if (type === "function_call_output" && shellId) {
+ return String((item as { call_id?: string }).call_id ?? "") === shellId;
+ }
+ }
+ return false;
+}
+
+function evaluateToolSearchError(caseRecord: CaseRecord): string | null {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as { input?: unknown[] };
+ const input = vector.input;
+ if (!Array.isArray(input)) return null;
+ const failed = input.filter((i) => i && typeof i === "object" && (i as { type?: string }).type === "tool_search_output"
+ && (i as { status?: string }).status === "failed");
+ if (failed.length !== 1) return null;
+ return String((failed[0] as { error?: string }).error ?? "");
+}
+
+function evaluateModalityPath(caseRecord: CaseRecord): string {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as Record;
+ const requestHasImage = Boolean(vector.requestHasImage);
+ const modalities = vector.modelInputModalities as string[] | undefined;
+ const sidecar = vector.visionSidecar as { enabled?: boolean } | undefined;
+ if (requestHasImage && Array.isArray(modalities) && modalities.includes("image")) return "native";
+ if (sidecar?.enabled) return "sidecar";
+ return "unsupported";
+}
+
+function evaluateSilentImageDrop(caseRecord: CaseRecord): boolean {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as Record;
+ if (!Boolean(vector.requestHasImage)) return false;
+ // Protocol V1's closed modality-gate vector treats the explicit `unsupported` path as a
+ // typed rejection, not as an omitted image. Native/sidecar paths likewise preserve it.
+ return !["native", "sidecar", "unsupported"].includes(evaluateModalityPath(caseRecord));
+}
+
+function evaluateJsonSseEquivalence(caseRecord: CaseRecord): string {
+ const vector = JSON.parse(caseRecord.fixture.bytesUtf8) as { json?: Record; sse?: string };
+ const json = vector.json;
+ const sse = vector.sse ?? "";
+ if (!json) return "fail";
+ const jsonProjection = {
+ text: extractOutputText(json),
+ terminal: String(json.status ?? ""),
+ };
+ const events = normalizeSseBytes(new TextEncoder().encode(sse), "openai-responses");
+ let sseText = "";
+ let sseTerminal = "";
+ for (const ev of events) {
+ if (ev.event === "response.output_text.delta" && ev.data && typeof ev.data === "object") {
+ sseText += String((ev.data as { delta?: string }).delta ?? "");
+ }
+ if (ev.event === "response.completed" && ev.data && typeof ev.data === "object") {
+ const response = (ev.data as { response?: { status?: string } }).response;
+ sseTerminal = String(response?.status ?? "");
+ }
+ }
+ const sseProjection = { text: sseText, terminal: sseTerminal };
+ return JSON.stringify(jsonProjection) === JSON.stringify(sseProjection) ? "pass" : "fail";
+}
diff --git a/src/lab/conformance/runner.ts b/src/lab/conformance/runner.ts
new file mode 100644
index 000000000..864f88726
--- /dev/null
+++ b/src/lab/conformance/runner.ts
@@ -0,0 +1,57 @@
+import { discoverScenarios, loadCaseAuthority } from "./manifest";
+import { runScenario } from "./executor";
+import { buildNegativeControls } from "./negative-controls";
+import type { ScenarioRunResult } from "./types";
+import { CL01_SUITES } from "./types";
+
+export interface ConformanceRunSummary {
+ /** Number of scenarios executed. */
+ total: number;
+ /** Number of scenarios that met their expected outcome. */
+ passed: number;
+ /** Number of scenarios that did not meet their expected outcome. */
+ failed: number;
+ results: ScenarioRunResult[];
+}
+
+export interface NegativeControlRunSummary extends ConformanceRunSummary {
+ /** Number of deliberately defective controls correctly rejected by the harness. */
+ rejected: number;
+}
+
+export async function runConformanceSuite(
+ suites: readonly string[] = CL01_SUITES,
+): Promise {
+ const authority = loadCaseAuthority();
+ const scenarios = discoverScenarios(authority, suites);
+ if (scenarios.length === 0) throw new Error("harness_failure: no CL-01 scenarios discovered");
+ const results: ScenarioRunResult[] = [];
+ for (const scenario of scenarios) {
+ results.push(await runScenario(scenario));
+ }
+ const passed = results.filter((r) => r.passed).length;
+ return { total: results.length, passed, failed: results.length - passed, results };
+}
+
+export async function runNegativeControls(): Promise {
+ const authority = loadCaseAuthority();
+ const scenarios = buildNegativeControls(discoverScenarios(authority));
+ if (scenarios.length === 0) throw new Error("harness_failure: no negative controls discovered");
+ const results: ScenarioRunResult[] = [];
+ for (const scenario of scenarios) {
+ results.push(await runScenario(scenario));
+ }
+ const rejected = results.filter((r) => !r.passed).length;
+ return {
+ total: results.length,
+ passed: rejected,
+ rejected,
+ failed: results.length - rejected,
+ results,
+ };
+}
+
+export function listScenarioIds(suites: readonly string[] = CL01_SUITES): string[] {
+ const authority = loadCaseAuthority();
+ return discoverScenarios(authority, suites).map((s) => s.id);
+}
diff --git a/src/lab/conformance/sse-normalize.ts b/src/lab/conformance/sse-normalize.ts
new file mode 100644
index 000000000..0d3a9525e
--- /dev/null
+++ b/src/lab/conformance/sse-normalize.ts
@@ -0,0 +1,59 @@
+import { sseFieldValue } from "../../lib/sse-decoder";
+import type { NormalizedEvent } from "./types";
+
+/** CL-00 §5 SSE normalization for assertion observations. */
+export function normalizeSseBytes(bytes: Uint8Array, sourceProtocol: string): NormalizedEvent[] {
+ let text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+ if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+ text = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+ const events: NormalizedEvent[] = [];
+ let ordinal = 0;
+ const frames = text.split("\n\n");
+ for (const rawFrame of frames) {
+ if (!rawFrame.trim()) continue;
+ const lines = rawFrame.split("\n");
+ const dataLines: string[] = [];
+ let eventName: string | undefined;
+ for (const line of lines) {
+ if (line.startsWith(":")) continue;
+ const eventValue = sseFieldValue(line, "event");
+ if (eventValue !== null) {
+ eventName = eventValue;
+ continue;
+ }
+ const dataValue = sseFieldValue(line, "data");
+ if (dataValue !== null) dataLines.push(dataValue);
+ }
+ if (dataLines.length === 0) continue;
+ const joined = dataLines.join("\n");
+ if (sourceProtocol === "openai-chat" && joined === "[DONE]") {
+ events.push({ event: "[DONE]", data: "[DONE]", ordinal: ordinal++ });
+ continue;
+ }
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(joined);
+ } catch {
+ events.push({ event: eventName ?? "malformed", data: joined, ordinal: ordinal++ });
+ continue;
+ }
+ // Protocol V1 treats null, scalar, and array data values as padding.
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+ const inferred = eventName ?? (typeof (parsed as { type?: unknown }).type === "string"
+ ? (parsed as { type: string }).type
+ : "message");
+ events.push({ event: inferred, data: parsed, ordinal: ordinal++ });
+ }
+ return events;
+}
+
+export function eventsFromBridgeFrames(
+ frames: Array<{ event?: string; data: Record }>,
+): NormalizedEvent[] {
+ return frames.map((frame, ordinal) => ({
+ event: frame.event ?? (typeof frame.data.type === "string" ? frame.data.type : "message"),
+ data: frame.data,
+ ordinal,
+ }));
+}
diff --git a/src/lab/conformance/suite-manifest.ts b/src/lab/conformance/suite-manifest.ts
new file mode 100644
index 000000000..412a77c84
--- /dev/null
+++ b/src/lab/conformance/suite-manifest.ts
@@ -0,0 +1,78 @@
+import { scenarioManifestDigest, suiteManifestDigest } from "../digest";
+import type { CaseAuthority, CaseRecord, VerificationRole } from "./types";
+import { expandScenario } from "./manifest";
+
+export interface SuiteScenarioRefV1 {
+ id: string;
+ version: string;
+ role: VerificationRole;
+ manifestDigest: string;
+}
+
+export interface SuiteManifestV1 {
+ schemaVersion: 1;
+ id: string;
+ version: string;
+ evidenceLayer: string;
+ capability: string;
+ assertionDslVersion: string;
+ evidenceSchemaVersion: string;
+ freshness: { maxAgeMs: number | null };
+ contradictionRule: string;
+ scenarios: SuiteScenarioRefV1[];
+ verificationRule: string;
+}
+
+/** Expand the canonical suite manifest for one suite ID from CL-01 authority. */
+export function expandSuiteManifest(
+ suiteId: string,
+ authority: CaseAuthority,
+): SuiteManifestV1 {
+ const cases = authority.cases.filter((c) => c.suite === suiteId);
+ if (cases.length === 0) {
+ throw new Error(`unknown suite ${suiteId}`);
+ }
+ const defaults = authority.manifestDefaults;
+ const capability = cases[0]!.capability;
+ if (cases.some((caseRecord) => caseRecord.capability !== capability)) {
+ throw new Error(`suite ${suiteId} declares mixed capabilities`);
+ }
+ const scenarios: SuiteScenarioRefV1[] = cases
+ .map((caseRecord) => suiteScenarioRef(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,
+ assertionDslVersion: authority.assertionDslVersion,
+ evidenceSchemaVersion: authority.evidenceSchemaVersion,
+ freshness: defaults.freshness ?? { maxAgeMs: null },
+ contradictionRule: "newest-required-observation-v1",
+ scenarios,
+ verificationRule: "all-applicable-required-pass-v1",
+ };
+}
+
+function suiteScenarioRef(caseRecord: CaseRecord, authority: CaseAuthority): SuiteScenarioRefV1 {
+ const expanded = expandScenario(caseRecord, authority);
+ return {
+ id: caseRecord.id,
+ version: String(authority.manifestDefaults.version),
+ role: caseRecord.verificationRole ?? authority.manifestDefaults.verificationRole,
+ manifestDigest: scenarioManifestDigest(expanded),
+ };
+}
+
+export function suiteManifestObjectForCase(
+ caseRecord: CaseRecord,
+ authority: CaseAuthority,
+): Record {
+ return expandSuiteManifest(caseRecord.suite, authority) as unknown as Record;
+}
+
+export function suiteManifestDigestForCase(caseRecord: CaseRecord, authority: CaseAuthority): string {
+ return suiteManifestDigest(expandSuiteManifest(caseRecord.suite, authority) as unknown as Record);
+}
diff --git a/src/lab/conformance/types.ts b/src/lab/conformance/types.ts
new file mode 100644
index 000000000..d0d7f830c
--- /dev/null
+++ b/src/lab/conformance/types.ts
@@ -0,0 +1,172 @@
+/** CL-01 deterministic protocol conformance harness types (CL-00 contract). */
+
+export const SYNTHETIC_MARKER = "ocx-lab-synthetic-v1";
+
+export type EvidenceLayer = "protocol_conformance" | "live_route_compatibility" | "task_effectiveness";
+
+export type VerificationRole = "required" | "supplemental" | "negative_control";
+
+export type FailureClassification =
+ | "harness_failure"
+ | "timeout"
+ | "budget_exhausted"
+ | "protocol_failure"
+ | "capability_failure"
+ | "behavioral_failure"
+ | "inconclusive";
+
+export interface FixtureRecord {
+ id: string;
+ role: "client_request" | "upstream_response" | "adapter_vector" | "synthetic_tool";
+ mediaType: string;
+ bytesUtf8: string;
+ digest: string;
+}
+
+export interface AssertionSpec {
+ id: string;
+ operator: string;
+ selector: string;
+ expected: unknown;
+ required: boolean;
+}
+
+export interface ExpectedFailureSpec {
+ controlKind: "conformance_negative_control" | "capability_absence_control";
+ expectedClass: string;
+ expectedCode: string;
+ assertionIds: string[];
+ onMatch: "pass" | "unsupported";
+ onMismatch: "fail" | "inconclusive";
+}
+
+export interface CaseRecord {
+ id: string;
+ suite: string;
+ capability: string;
+ verificationRole?: VerificationRole;
+ requirements: {
+ inboundProtocols: string[];
+ upstreamProtocols: string[];
+ surfaces: string[];
+ requiredClaims: string[];
+ requiredHarnessFeatures: string[];
+ platforms: string[];
+ routePreconditions: string[];
+ };
+ fixture: FixtureRecord;
+ initiatingRequest?: FixtureRecord;
+ assertions: AssertionSpec[];
+ expectedFailure?: ExpectedFailureSpec;
+}
+
+export interface FailureRule {
+ id: string;
+ match: string[];
+ classification: FailureClassification;
+ secondaryCode?: string;
+ verdictEffect: "none" | "degraded" | "unsupported";
+ retry: "never" | "bounded" | "after_precondition_change";
+ expected: boolean;
+}
+
+export interface CaseAuthority {
+ schemaVersion: number;
+ sourceCommit: string;
+ assertionDslVersion: string;
+ evidenceSchemaVersion: string;
+ failureRuleSets: Record;
+ expectedFailureRuleTemplate: Pick;
+ manifestDefaults: {
+ version: string;
+ suiteVersion: string;
+ evidenceLayer: EvidenceLayer;
+ verificationRole: VerificationRole;
+ executionMode: string;
+ freshness: { maxAgeMs: number | null };
+ executionLimits: Record;
+ artifactPolicy: Record;
+ failureRuleSet: string;
+ };
+ cases: CaseRecord[];
+}
+
+export interface NormalizedEvent {
+ event: string;
+ data: unknown;
+ ordinal: number;
+}
+
+export interface ToolCallProjection {
+ id: string;
+ name: string;
+ arguments: unknown;
+ kind: "function" | "custom";
+ ordinal: number;
+}
+
+export interface McpCallProjection {
+ namespace: string;
+ name: string;
+}
+
+export interface NormalizedObservation {
+ client: {
+ request: { status: number; headers: Record; json: unknown; rawBytes: number };
+ response: {
+ status: number;
+ headers: Record;
+ json: unknown;
+ events: NormalizedEvent[];
+ toolCalls: ToolCallProjection[];
+ mcpCalls: McpCallProjection[];
+ terminal: string | null;
+ normalizedText: string;
+ };
+ };
+ upstream: {
+ requests: Array<{ status: number; headers: Record; json: unknown; rawBytes: number }>;
+ responses: unknown[];
+ };
+ process: { exitCode: number | null };
+ verifiers: Record;
+}
+
+export interface AssertionResult {
+ id: string;
+ operator: string;
+ required: boolean;
+ passed: boolean;
+ observedSummary: string;
+ reason?: string;
+}
+
+export interface ProtocolExecutionContextV1 {
+ inboundProtocol: string;
+ upstreamProtocol: string;
+ surface: string;
+}
+
+export interface ScenarioRunResult {
+ scenarioId: string;
+ suite: string;
+ passed: boolean;
+ classification: FailureClassification;
+ secondaryCode?: string;
+ assertionResults: AssertionResult[];
+ expectedFailureMatched?: boolean;
+ diagnostics: string[];
+ executionContext: ProtocolExecutionContextV1;
+}
+
+/** All eight protocol-conformance suites frozen by CL-00 Protocol V1. */
+export const CL01_SUITES = [
+ "responses-core",
+ "chat-core",
+ "anthropic-core",
+ "tools-core",
+ "codex-core",
+ "vision-core",
+ "reasoning-core",
+ "mcp-core",
+] as const;
diff --git a/src/lab/constants.ts b/src/lab/constants.ts
new file mode 100644
index 000000000..881ca9ea4
--- /dev/null
+++ b/src/lab/constants.ts
@@ -0,0 +1,126 @@
+/** CL-02 projection / ledger constants frozen from CL-00 contracts. */
+
+export const LAB_EVENT_SCHEMA_VERSION = 1;
+export const LAB_PROJECTION_SPEC_VERSION = "cl-02.v1";
+export const LAB_PRODUCER = "opencodex-lab";
+export const LAB_PRODUCER_VERSION = "2.10.2";
+
+export const MAX_INVALIDATION_TARGETS = 1024;
+export const MAX_BYTES_PER_ARTIFACT = 256 * 1024;
+export const MAX_AGGREGATE_ARTIFACT_BYTES = 1024 * 1024;
+export const MAX_ARTIFACTS_PER_RUN = 16;
+export const MAX_SERIALIZED_EVENT_BYTES = 64 * 1024;
+export const MAX_SANITIZED_STRING_FIELD = 4 * 1024;
+export const MAX_EVENT_NESTING_DEPTH = 8;
+export const MAX_OBJECT_KEYS_PER_EVENT = 64;
+export const MAX_ARRAY_ELEMENTS_PER_EVENT = 256;
+
+export const OBSERVATION_LIMIT_NAMES = [
+ "totalTimeoutMs",
+ "connectTimeoutMs",
+ "firstByteTimeoutMs",
+ "inactivityTimeoutMs",
+ "maxRequests",
+ "maxInputBytes",
+ "maxOutputBytes",
+ "maxOutputTokens",
+ "maxToolCalls",
+ "maxArtifactBytes",
+] as const;
+
+export type ObservationLimitName = (typeof OBSERVATION_LIMIT_NAMES)[number];
+
+export const EVENT_KINDS = [
+ "observation",
+ "claim_snapshot",
+ "invalidation",
+ "purge_tombstone",
+] as const;
+
+export type LabEventKind = (typeof EVENT_KINDS)[number];
+
+export const EVIDENCE_LAYERS = [
+ "protocol_conformance",
+ "live_route_compatibility",
+ "task_effectiveness",
+] as const;
+
+export type EvidenceLayer = (typeof EVIDENCE_LAYERS)[number];
+
+export const VERDICTS = [
+ "UNKNOWN",
+ "CLAIMED",
+ "PROBED",
+ "VERIFIED",
+ "DEGRADED",
+ "BLOCKED",
+ "UNSUPPORTED",
+] as const;
+
+export type CompatibilityVerdict = (typeof VERDICTS)[number];
+
+export const INVALIDATION_REASONS = [
+ "harness_defect",
+ "fixture_defect",
+ "redaction_defect",
+ "integrity_defect",
+ "contract_artifact_missing",
+ "manual_correction",
+] as const;
+
+export type InvalidationReason = (typeof INVALIDATION_REASONS)[number];
+
+export const PURGE_ACTIONS = [
+ "ledger",
+ "sqlite",
+ "artifact",
+ "scratch",
+ "export",
+] as const;
+
+export type PurgeAction = (typeof PURGE_ACTIONS)[number];
+
+export const CLAIM_SOURCE_KINDS = [
+ "provider_config",
+ "provider_registry",
+ "cached_catalog",
+ "native_metadata",
+ "adapter_inference",
+] as const;
+
+export type ClaimSourceKind = (typeof CLAIM_SOURCE_KINDS)[number];
+
+export const ARTIFACT_CLASSES = [
+ "scenario_manifest",
+ "suite_manifest",
+ "fixture",
+ "claim_source_manifest",
+ "assertion_report",
+ "request_shape",
+ "response_shape",
+ "event_trace",
+ "error_taxonomy",
+ "verifier_summary",
+] as const;
+
+export type ArtifactClass = (typeof ARTIFACT_CLASSES)[number];
+
+export const CONTRACT_ARTIFACT_CLASSES = [
+ "scenario_manifest",
+ "suite_manifest",
+ "fixture",
+ "claim_source_manifest",
+] as const;
+
+export type ContractArtifactClass = (typeof CONTRACT_ARTIFACT_CLASSES)[number];
+
+export const EXECUTION_MODES = ["fixture", "live", "fabric"] as const;
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+
+export const OUTCOMES = ["pass", "fail", "blocked", "inconclusive"] as const;
+export type ObservationOutcome = (typeof OUTCOMES)[number];
+
+export const CLAIM_POLARITIES = ["supported", "not_supported", "withdrawn"] as const;
+export type ClaimPolarity = (typeof CLAIM_POLARITIES)[number];
+
+export const ARTIFACT_FILENAME_EXT = ".bin";
diff --git a/src/lab/digest.ts b/src/lab/digest.ts
new file mode 100644
index 000000000..c54b3b443
--- /dev/null
+++ b/src/lab/digest.ts
@@ -0,0 +1,64 @@
+import { createHash, createHmac } from "node:crypto";
+import { jcsStringify } from "./conformance/jcs";
+import {
+ fixtureDigest,
+ scenarioManifestDigest,
+ suiteManifestDigest,
+} from "./conformance/digest";
+
+export { fixtureDigest, scenarioManifestDigest, suiteManifestDigest, jcsStringify };
+export { jcsEqual } from "./conformance/jcs";
+
+/** Domain-separated SHA-256: UTF-8(domain) || NUL || payload. */
+export function domainHash(domain: string, payload: Uint8Array | string): string {
+ const hash = createHash("sha256");
+ hash.update(new TextEncoder().encode(`${domain}\0`));
+ if (typeof payload === "string") hash.update(new TextEncoder().encode(payload));
+ else hash.update(payload);
+ return hash.digest("hex");
+}
+
+export const LAB_DOMAIN = {
+ event: "ocx-lab:event:v1",
+ subject: "ocx-lab:subject:v1",
+ claimSourceManifest: "ocx-lab:claim-source-manifest:v1",
+ scenarioManifest: "ocx-lab:scenario-manifest:v1",
+ suiteManifest: "ocx-lab:suite-manifest:v1",
+ fixture: "ocx-lab:fixture:v1",
+ localFingerprint: "ocx-lab:local-fingerprint:v1",
+ artifactBytes: "ocx-lab:artifact-bytes:v1",
+} as const;
+
+export function eventIdForPayload(eventWithoutId: unknown): string {
+ return domainHash(LAB_DOMAIN.event, jcsStringify(eventWithoutId));
+}
+
+export function subjectIdForSubject(subject: unknown): string {
+ return domainHash(LAB_DOMAIN.subject, jcsStringify(subject));
+}
+
+export function claimSourceManifestDigest(manifest: unknown): string {
+ return domainHash(LAB_DOMAIN.claimSourceManifest, jcsStringify(manifest));
+}
+
+/** Content digest for already-redacted artifact bytes (not contract fixture domain). */
+export function artifactBytesDigest(bytes: Uint8Array): string {
+ return domainHash(LAB_DOMAIN.artifactBytes, bytes);
+}
+
+export function localFingerprint(
+ fieldName: string,
+ value: unknown,
+ salt: Uint8Array | string,
+): string {
+ const key = typeof salt === "string" ? new TextEncoder().encode(salt) : salt;
+ const preimage = `${LAB_DOMAIN.localFingerprint}\0${fieldName}\0`;
+ return createHmac("sha256", key)
+ .update(new TextEncoder().encode(preimage))
+ .update(new TextEncoder().encode(jcsStringify(value)))
+ .digest("hex");
+}
+
+export function isSha256Hex(value: string): boolean {
+ return /^[0-9a-f]{64}$/.test(value);
+}
diff --git a/src/lab/events/errors.ts b/src/lab/events/errors.ts
new file mode 100644
index 000000000..17009183a
--- /dev/null
+++ b/src/lab/events/errors.ts
@@ -0,0 +1,9 @@
+export class LabValidationError extends Error {
+ readonly code: string;
+
+ constructor(code: string, message: string) {
+ super(message);
+ this.name = "LabValidationError";
+ this.code = code;
+ }
+}
diff --git a/src/lab/events/limits.ts b/src/lab/events/limits.ts
new file mode 100644
index 000000000..d6cba306f
--- /dev/null
+++ b/src/lab/events/limits.ts
@@ -0,0 +1,114 @@
+import {
+ MAX_ARRAY_ELEMENTS_PER_EVENT,
+ MAX_EVENT_NESTING_DEPTH,
+ MAX_OBJECT_KEYS_PER_EVENT,
+ MAX_SANITIZED_STRING_FIELD,
+} from "../constants";
+import { LabValidationError } from "./errors";
+
+const FORBIDDEN_KEY_RE =
+ /(?:^|_)(?:secret|token|apikey|api_key|password|credential|authorization|cookie|bearer|prompt|repository|filepath|file_path|baseurl|base_url|hostname|rawrequest|raw_request)(?:$|_)/i;
+
+const FORBIDDEN_EXACT_KEYS = new Set([
+ "authorization",
+ "apiKey",
+ "api_key",
+ "password",
+ "secret",
+ "token",
+ "cookie",
+ "cookies",
+ "headers",
+ "prompt",
+ "path",
+ "filepath",
+ "filePath",
+ "repository",
+ "repo",
+ "baseUrl",
+ "url",
+ "rawRequest",
+ "rawBytes",
+]);
+
+function fieldPath(base: string, key: string | number): string {
+ return base ? `${base}.${String(key)}` : String(key);
+}
+
+function assertAllowedValueType(value: unknown, path: string): void {
+ if (value === null) return;
+ const t = typeof value;
+ if (t === "string" || t === "boolean") return;
+ if (t === "number") {
+ if (!Number.isFinite(value as number)) {
+ throw new LabValidationError("non_finite", `${path} must be finite number`);
+ }
+ return;
+ }
+ if (Array.isArray(value) || (t === "object" && value !== null)) return;
+ throw new LabValidationError("unsupported_type", `${path} has unsupported type`);
+}
+
+function assertKeyAllowed(key: string, path: string): void {
+ if (FORBIDDEN_EXACT_KEYS.has(key) || FORBIDDEN_KEY_RE.test(key)) {
+ throw new LabValidationError("forbidden_field", `${path} forbidden`);
+ }
+ if (key.includes("\0")) {
+ throw new LabValidationError("nul_forbidden", `${path} contains NUL`);
+ }
+}
+
+/** Recursive deterministic CL-00 structural/privacy ceilings before JSONL admission. */
+export function enforceEventStructureLimits(
+ value: unknown,
+ path = "",
+ depth = 0,
+): void {
+ assertAllowedValueType(value, path || "event");
+ if (value === null) return;
+
+ if (typeof value === "string") {
+ const bytes = new TextEncoder().encode(value).byteLength;
+ if (bytes > MAX_SANITIZED_STRING_FIELD) {
+ throw new LabValidationError("field_too_large", `${path} exceeds ${MAX_SANITIZED_STRING_FIELD} bytes`);
+ }
+ if (/sk-[a-z0-9]{10,}/i.test(value) || /Bearer\s+\S+/i.test(value)) {
+ throw new LabValidationError("secret_pattern", `${path} contains secret-shaped data`);
+ }
+ if (
+ /^[A-Za-z]:\\/.test(value) ||
+ /(?:^|[\s"'([])\/(?:home|Users|tmp|var|etc|root|mnt)\//.test(value) ||
+ value.includes("\\Users\\")
+ ) {
+ throw new LabValidationError("raw_path", `${path} contains raw filesystem path`);
+ }
+ return;
+ }
+
+ if (typeof value === "number" || typeof value === "boolean") return;
+
+ if (Array.isArray(value)) {
+ if (depth >= MAX_EVENT_NESTING_DEPTH) {
+ throw new LabValidationError("nesting_depth", `${path} exceeds nesting depth ${MAX_EVENT_NESTING_DEPTH}`);
+ }
+ if (value.length > MAX_ARRAY_ELEMENTS_PER_EVENT) {
+ throw new LabValidationError("array_too_large", `${path} exceeds ${MAX_ARRAY_ELEMENTS_PER_EVENT} elements`);
+ }
+ for (let i = 0; i < value.length; i++) {
+ enforceEventStructureLimits(value[i], fieldPath(path, i), depth + 1);
+ }
+ return;
+ }
+
+ if (depth >= MAX_EVENT_NESTING_DEPTH) {
+ throw new LabValidationError("nesting_depth", `${path} exceeds nesting depth ${MAX_EVENT_NESTING_DEPTH}`);
+ }
+ const keys = Object.keys(value as Record);
+ if (keys.length > MAX_OBJECT_KEYS_PER_EVENT) {
+ throw new LabValidationError("too_many_keys", `${path} exceeds ${MAX_OBJECT_KEYS_PER_EVENT} keys`);
+ }
+ for (const key of keys) {
+ assertKeyAllowed(key, fieldPath(path, key));
+ enforceEventStructureLimits((value as Record)[key], fieldPath(path, key), depth + 1);
+ }
+}
diff --git a/src/lab/events/types.ts b/src/lab/events/types.ts
new file mode 100644
index 000000000..69ed120db
--- /dev/null
+++ b/src/lab/events/types.ts
@@ -0,0 +1,228 @@
+import type {
+ ArtifactClass,
+ ClaimPolarity,
+ ClaimSourceKind,
+ EvidenceLayer,
+ ExecutionMode,
+ InvalidationReason,
+ LabEventKind,
+ ObservationOutcome,
+ PurgeAction,
+} from "../constants";
+
+export interface LabProducer {
+ name: string;
+ version: string;
+}
+
+export interface ProtocolSubjectV1 {
+ subjectSchemaVersion: 1;
+ subjectKind: "protocol";
+ opencodexCompatibilityVersion: string;
+ effectiveAdapter: string;
+ inboundProtocol: string;
+ upstreamProtocol: string;
+ surface: string;
+ behaviorFingerprint: string;
+}
+
+export interface RouteDependencyV1 {
+ role: string;
+ providerId: string;
+ providerInstanceFingerprint: string;
+ clientModelId: string;
+ upstreamModelId: string;
+ effectiveAdapter: string;
+ upstreamProtocol: string;
+ endpointFingerprint: string;
+ behaviorFingerprint: string;
+}
+
+export interface RouteSubjectV1 {
+ subjectSchemaVersion: 1;
+ subjectKind: "route";
+ providerId: string;
+ providerInstanceFingerprint: string;
+ clientModelId: string;
+ upstreamModelId: string;
+ effectiveAdapter: string;
+ inboundProtocol: string;
+ upstreamProtocol: string;
+ surface: string;
+ opencodexCompatibilityVersion: string;
+ behaviorFingerprint: string;
+ endpointFingerprint: string;
+ dependencies: RouteDependencyV1[];
+}
+
+export interface TaskSubjectV1 {
+ subjectSchemaVersion: 1;
+ subjectKind: "task";
+ routeSubject: RouteSubjectV1;
+ taskClassId: string;
+ taskClassVersion: string;
+ taskFixtureDigest: string;
+ verifierManifestDigest: string;
+ fabricCompatibilityVersion: string;
+ sandboxProfileDigest: string;
+}
+
+export type EvidenceSubjectV1 = ProtocolSubjectV1 | RouteSubjectV1 | TaskSubjectV1;
+
+export interface ArtifactRefV1 {
+ digest: string;
+ mediaType: string;
+ byteCount: number;
+ redactionPolicy: string;
+ /** Digest-derived relative name only (e.g. `.bin`). */
+ relativePath: string;
+ artifactClass: ArtifactClass;
+}
+
+export interface AssertionRecordV1 {
+ id: string;
+ operator: string;
+ required: boolean;
+ passed: boolean;
+ expectedSummary: string;
+ observedSummary: string;
+ reason?: string;
+}
+
+export interface FailureRecordV1 {
+ class: string;
+ code: string;
+ retryable: boolean;
+ attribution: "opencodex" | "route" | "environment" | "harness";
+}
+
+export interface LabEventBase {
+ schemaVersion: number;
+ eventId: string;
+ eventKind: LabEventKind;
+ recordedAt: number;
+ producer: string;
+ producerVersion: string;
+}
+
+export interface ObservationEvent extends LabEventBase {
+ eventKind: "observation";
+ evidenceLayer: EvidenceLayer;
+ scenarioId: string;
+ scenarioVersion: string;
+ scenarioManifestDigest: string;
+ suiteId: string;
+ suiteVersion: string;
+ suiteManifestDigest: string;
+ fixtureDigests: string[];
+ subject: EvidenceSubjectV1;
+ subjectId: string;
+ startedAt: number;
+ completedAt: number;
+ executionMode: ExecutionMode;
+ attempt: number;
+ limits: Record;
+ outcome: ObservationOutcome;
+ assertions: AssertionRecordV1[];
+ failure?: FailureRecordV1;
+ expectedFailure?: Record;
+ environment: Record;
+ artifactRefs: ArtifactRefV1[];
+ sourceRefs?: string[];
+}
+
+export interface ClaimSnapshotEvent extends LabEventBase {
+ eventKind: "claim_snapshot";
+ evidenceLayer: "live_route_compatibility";
+ subject: RouteSubjectV1;
+ subjectId: string;
+ capability: string;
+ polarity: ClaimPolarity;
+ sourceManifestDigest: string;
+ sourceEventIds: string[];
+ supersedes: string[];
+ effectiveAt: number;
+}
+
+export interface InvalidationEvent extends LabEventBase {
+ eventKind: "invalidation";
+ targetEventIds: string[];
+ reason: InvalidationReason;
+}
+
+export interface PurgeTombstoneEvent extends LabEventBase {
+ eventKind: "purge_tombstone";
+ targetEventIds: string[];
+ targetArtifactDigests: string[];
+ reason: "sensitive_evidence";
+ purgeActions: PurgeAction[];
+}
+
+export type LabEvent =
+ | ObservationEvent
+ | ClaimSnapshotEvent
+ | InvalidationEvent
+ | PurgeTombstoneEvent;
+
+export type ClaimCapabilityFactsV1 = {
+ contextWindow?: number;
+ inputModalities?: string[];
+ reasoningEfforts?: string[];
+ catalogCapabilityNames?: string[];
+ serviceTier?: string[];
+ toolCapable?: boolean;
+ parallelToolCalls?: boolean;
+ endpointLocality?: "local" | "private" | "unknown";
+ canonicalOpenAiForward?: boolean;
+};
+
+export interface ClaimSourceV1 {
+ kind: ClaimSourceKind;
+ revision: string | null;
+ facts: ClaimCapabilityFactsV1;
+}
+
+export interface RouteCapabilityEvidenceV1 {
+ contextWindow?: number;
+ tools?: boolean | "unknown";
+ image?: boolean | "unknown";
+ structuredOutput?: boolean | "unknown";
+ reasoningEfforts?: string[];
+ serviceTier?: string | "unknown";
+ localOnly?: boolean | "unknown";
+ remoteAllowed?: boolean | "unknown";
+ encryptedCodexTasks?: boolean | "unknown";
+}
+
+export interface ClaimSourceManifestV1 {
+ schemaVersion: 1;
+ subjectId: string;
+ providerId: string;
+ clientModelId: string;
+ capability: string;
+ sources: ClaimSourceV1[];
+ resolvedEvidence: RouteCapabilityEvidenceV1;
+}
+
+export interface LedgerCorruption {
+ kind:
+ | "malformed_line"
+ | "partial_line"
+ | "duplicate_event"
+ | "invalid_event"
+ | "invalid_reference"
+ | "missing_artifact"
+ | "artifact_mismatch"
+ | "claim_corruption"
+ | "empty_ledger";
+ lineNumber?: number;
+ eventId?: string;
+ detail: string;
+}
+
+export interface ReplayResult {
+ events: LabEvent[];
+ corruptions: LedgerCorruption[];
+ validLineCount: number;
+ totalLineCount: number;
+}
diff --git a/src/lab/events/validate.ts b/src/lab/events/validate.ts
new file mode 100644
index 000000000..d101e28b0
--- /dev/null
+++ b/src/lab/events/validate.ts
@@ -0,0 +1,772 @@
+import { enforceEventStructureLimits } from "./limits";
+import { LabValidationError } from "./errors";
+export { LabValidationError } from "./errors";
+import {
+ ARTIFACT_CLASSES,
+ ARTIFACT_FILENAME_EXT,
+ CLAIM_POLARITIES,
+ CLAIM_SOURCE_KINDS,
+ EVIDENCE_LAYERS,
+ EVENT_KINDS,
+ EXECUTION_MODES,
+ INVALIDATION_REASONS,
+ LAB_EVENT_SCHEMA_VERSION,
+ MAX_INVALIDATION_TARGETS,
+ MAX_SANITIZED_STRING_FIELD,
+ MAX_SERIALIZED_EVENT_BYTES,
+ OBSERVATION_LIMIT_NAMES,
+ OUTCOMES,
+ PURGE_ACTIONS,
+ type ArtifactClass,
+ type ClaimSourceKind,
+ type EvidenceLayer,
+ type LabEventKind,
+} from "../constants";
+import {
+ claimSourceManifestDigest,
+ eventIdForPayload,
+ isSha256Hex,
+ jcsStringify,
+ subjectIdForSubject,
+} from "../digest";
+import type {
+ ArtifactRefV1,
+ ClaimCapabilityFactsV1,
+ ClaimSnapshotEvent,
+ ClaimSourceManifestV1,
+ ClaimSourceV1,
+ EvidenceSubjectV1,
+ InvalidationEvent,
+ LabEvent,
+ ObservationEvent,
+ ProtocolSubjectV1,
+ PurgeTombstoneEvent,
+ RouteCapabilityEvidenceV1,
+ RouteSubjectV1,
+ TaskSubjectV1,
+} from "./types";
+
+function isPlainObject(value: unknown): value is Record {
+ return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertString(value: unknown, field: string, max = MAX_SANITIZED_STRING_FIELD): string {
+ if (typeof value !== "string") throw new LabValidationError("invalid_type", `${field} must be string`);
+ const bytes = new TextEncoder().encode(value).byteLength;
+ if (bytes > max) throw new LabValidationError("field_too_large", `${field} exceeds ${max} bytes`);
+ if (value.includes("\0")) throw new LabValidationError("nul_forbidden", `${field} contains NUL`);
+ return value;
+}
+
+function assertIntMs(value: unknown, field: string): number {
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+ throw new LabValidationError("invalid_timestamp", `${field} must be UTC epoch milliseconds`);
+ }
+ return value;
+}
+
+function assertClosed(value: unknown, field: string, allowed: readonly T[]): T {
+ if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+ throw new LabValidationError("closed_set", `${field} must be one of ${allowed.join("|")}`);
+ }
+ return value as T;
+}
+
+function utf8LexLess(a: string, b: string): boolean {
+ const ae = new TextEncoder().encode(a);
+ const be = new TextEncoder().encode(b);
+ const n = Math.min(ae.length, be.length);
+ for (let i = 0; i < n; i++) {
+ if (ae[i]! < be[i]!) return true;
+ if (ae[i]! > be[i]!) return false;
+ }
+ return ae.length < be.length;
+}
+
+/** Sorted unique lowercase SHA-256 hex IDs; rejects duplicates / unsorted / uppercase. */
+export function validateSortedUniqueHexIds(
+ ids: unknown,
+ field: string,
+ opts: { nonEmpty?: boolean; max?: number } = {},
+): string[] {
+ if (!Array.isArray(ids)) throw new LabValidationError("invalid_type", `${field} must be array`);
+ if (opts.nonEmpty && ids.length === 0) {
+ throw new LabValidationError("empty_targets", `${field} must be non-empty`);
+ }
+ if (opts.max !== undefined && ids.length > opts.max) {
+ throw new LabValidationError("too_many_targets", `${field} exceeds ${opts.max}`);
+ }
+ const out: string[] = [];
+ for (let i = 0; i < ids.length; i++) {
+ const id = ids[i];
+ if (typeof id !== "string" || !isSha256Hex(id)) {
+ throw new LabValidationError("invalid_id", `${field}[${i}] must be lowercase sha256 hex`);
+ }
+ if (i > 0) {
+ const prev = out[i - 1]!;
+ if (id === prev) throw new LabValidationError("duplicate_id", `${field} contains duplicates`);
+ if (!utf8LexLess(prev, id)) {
+ throw new LabValidationError("unsorted_ids", `${field} must be UTF-8 lexicographically sorted`);
+ }
+ }
+ out.push(id);
+ }
+ return out;
+}
+
+function validateArtifactRef(raw: unknown, index: number): ArtifactRefV1 {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_artifact_ref", `artifactRefs[${index}]`);
+ const digest = assertString(raw.digest, `artifactRefs[${index}].digest`);
+ if (!isSha256Hex(digest)) throw new LabValidationError("invalid_digest", `artifactRefs[${index}].digest`);
+ const mediaType = assertString(raw.mediaType, `artifactRefs[${index}].mediaType`, 256);
+ if (typeof raw.byteCount !== "number" || !Number.isInteger(raw.byteCount) || raw.byteCount < 0) {
+ throw new LabValidationError("invalid_byte_count", `artifactRefs[${index}].byteCount`);
+ }
+ const redactionPolicy = assertString(raw.redactionPolicy, `artifactRefs[${index}].redactionPolicy`, 256);
+ const relativePath = assertString(raw.relativePath, `artifactRefs[${index}].relativePath`, 128);
+ if (relativePath !== `${digest}${ARTIFACT_FILENAME_EXT}`) {
+ throw new LabValidationError("invalid_relative_path", `artifactRefs[${index}].relativePath must be digest-derived`);
+ }
+ if (relativePath.includes("/") || relativePath.includes("\\") || relativePath.includes("..")) {
+ throw new LabValidationError("path_traversal", `artifactRefs[${index}].relativePath`);
+ }
+ const artifactClass = assertClosed(raw.artifactClass, `artifactRefs[${index}].artifactClass`, ARTIFACT_CLASSES);
+ return { digest, mediaType, byteCount: raw.byteCount, redactionPolicy, relativePath, artifactClass };
+}
+
+function validateProtocolSubject(raw: Record): ProtocolSubjectV1 {
+ if (raw.subjectSchemaVersion !== 1 || raw.subjectKind !== "protocol") {
+ throw new LabValidationError("invalid_subject", "protocol subject schema/kind mismatch");
+ }
+ return {
+ subjectSchemaVersion: 1,
+ subjectKind: "protocol",
+ opencodexCompatibilityVersion: assertString(raw.opencodexCompatibilityVersion, "opencodexCompatibilityVersion"),
+ effectiveAdapter: assertString(raw.effectiveAdapter, "effectiveAdapter"),
+ inboundProtocol: assertString(raw.inboundProtocol, "inboundProtocol"),
+ upstreamProtocol: assertString(raw.upstreamProtocol, "upstreamProtocol"),
+ surface: assertString(raw.surface, "surface"),
+ behaviorFingerprint: assertString(raw.behaviorFingerprint, "behaviorFingerprint"),
+ };
+}
+
+function validateRouteSubject(raw: Record): RouteSubjectV1 {
+ if (raw.subjectSchemaVersion !== 1 || raw.subjectKind !== "route") {
+ throw new LabValidationError("invalid_subject", "route subject schema/kind mismatch");
+ }
+ if (!Array.isArray(raw.dependencies)) {
+ throw new LabValidationError("invalid_subject", "dependencies must be array");
+ }
+ const dependencies = raw.dependencies.map((dep, i) => {
+ if (!isPlainObject(dep)) throw new LabValidationError("invalid_dependency", `dependencies[${i}]`);
+ return {
+ role: assertString(dep.role, `dependencies[${i}].role`),
+ providerId: assertString(dep.providerId, `dependencies[${i}].providerId`),
+ providerInstanceFingerprint: assertString(dep.providerInstanceFingerprint, `dependencies[${i}].providerInstanceFingerprint`),
+ clientModelId: assertString(dep.clientModelId, `dependencies[${i}].clientModelId`),
+ upstreamModelId: assertString(dep.upstreamModelId, `dependencies[${i}].upstreamModelId`),
+ effectiveAdapter: assertString(dep.effectiveAdapter, `dependencies[${i}].effectiveAdapter`),
+ upstreamProtocol: assertString(dep.upstreamProtocol, `dependencies[${i}].upstreamProtocol`),
+ endpointFingerprint: assertString(dep.endpointFingerprint, `dependencies[${i}].endpointFingerprint`),
+ behaviorFingerprint: assertString(dep.behaviorFingerprint, `dependencies[${i}].behaviorFingerprint`),
+ };
+ });
+ return {
+ subjectSchemaVersion: 1,
+ subjectKind: "route",
+ providerId: assertString(raw.providerId, "providerId"),
+ providerInstanceFingerprint: assertString(raw.providerInstanceFingerprint, "providerInstanceFingerprint"),
+ clientModelId: assertString(raw.clientModelId, "clientModelId"),
+ upstreamModelId: assertString(raw.upstreamModelId, "upstreamModelId"),
+ effectiveAdapter: assertString(raw.effectiveAdapter, "effectiveAdapter"),
+ inboundProtocol: assertString(raw.inboundProtocol, "inboundProtocol"),
+ upstreamProtocol: assertString(raw.upstreamProtocol, "upstreamProtocol"),
+ surface: assertString(raw.surface, "surface"),
+ opencodexCompatibilityVersion: assertString(raw.opencodexCompatibilityVersion, "opencodexCompatibilityVersion"),
+ behaviorFingerprint: assertString(raw.behaviorFingerprint, "behaviorFingerprint"),
+ endpointFingerprint: assertString(raw.endpointFingerprint, "endpointFingerprint"),
+ dependencies,
+ };
+}
+
+function validateTaskSubject(raw: Record): TaskSubjectV1 {
+ if (raw.subjectSchemaVersion !== 1 || raw.subjectKind !== "task") {
+ throw new LabValidationError("invalid_subject", "task subject schema/kind mismatch");
+ }
+ if (!isPlainObject(raw.routeSubject)) {
+ throw new LabValidationError("invalid_subject", "task.routeSubject required");
+ }
+ return {
+ subjectSchemaVersion: 1,
+ subjectKind: "task",
+ routeSubject: validateRouteSubject(raw.routeSubject),
+ taskClassId: assertString(raw.taskClassId, "taskClassId"),
+ taskClassVersion: assertString(raw.taskClassVersion, "taskClassVersion"),
+ taskFixtureDigest: assertString(raw.taskFixtureDigest, "taskFixtureDigest"),
+ verifierManifestDigest: assertString(raw.verifierManifestDigest, "verifierManifestDigest"),
+ fabricCompatibilityVersion: assertString(raw.fabricCompatibilityVersion, "fabricCompatibilityVersion"),
+ sandboxProfileDigest: assertString(raw.sandboxProfileDigest, "sandboxProfileDigest"),
+ };
+}
+
+export function validateSubject(raw: unknown, layer: EvidenceLayer): EvidenceSubjectV1 {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_subject", "subject must be object");
+ const kind = raw.subjectKind;
+ if (layer === "protocol_conformance") {
+ if (kind !== "protocol") throw new LabValidationError("layer_subject_mismatch", "protocol layer requires protocol subject");
+ return validateProtocolSubject(raw);
+ }
+ if (layer === "live_route_compatibility") {
+ if (kind !== "route") throw new LabValidationError("layer_subject_mismatch", "live layer requires route subject");
+ return validateRouteSubject(raw);
+ }
+ if (layer === "task_effectiveness") {
+ if (kind !== "task") throw new LabValidationError("layer_subject_mismatch", "task layer requires task subject");
+ return validateTaskSubject(raw);
+ }
+ const _exhaustive: never = layer;
+ throw new LabValidationError("unknown_layer", String(_exhaustive));
+}
+
+function stripEventId(event: Record): Record {
+ const { eventId: _omit, ...rest } = event;
+ return rest;
+}
+
+function enforceEventId(event: LabEvent): void {
+ const recomputed = eventIdForPayload(stripEventId(event as unknown as Record));
+ if (event.eventId !== recomputed) {
+ throw new LabValidationError("event_id_mismatch", `eventId mismatch: got ${event.eventId}, expected ${recomputed}`);
+ }
+}
+
+function enforceSerializedSize(event: LabEvent): void {
+ const bytes = new TextEncoder().encode(jcsStringify(event)).byteLength;
+ if (bytes > MAX_SERIALIZED_EVENT_BYTES) {
+ throw new LabValidationError("event_too_large", `serialized event exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes`);
+ }
+}
+
+function validateAssertionRecord(raw: unknown, index: number): ObservationEvent["assertions"][number] {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_assertions", `assertions[${index}]`);
+ const allowed = new Set(["id", "operator", "required", "passed", "expectedSummary", "observedSummary", "reason"]);
+ for (const key of Object.keys(raw)) {
+ if (!allowed.has(key)) {
+ throw new LabValidationError("unknown_assertion_key", `assertions[${index}].${key}`);
+ }
+ }
+ const record = {
+ id: assertString(raw.id, `assertions[${index}].id`),
+ operator: assertString(raw.operator, `assertions[${index}].operator`),
+ required: raw.required === true || raw.required === false
+ ? raw.required
+ : (() => { throw new LabValidationError("invalid_assertions", `assertions[${index}].required`); })(),
+ passed: raw.passed === true || raw.passed === false
+ ? raw.passed
+ : (() => { throw new LabValidationError("invalid_assertions", `assertions[${index}].passed`); })(),
+ expectedSummary: assertString(raw.expectedSummary, `assertions[${index}].expectedSummary`),
+ observedSummary: assertString(raw.observedSummary, `assertions[${index}].observedSummary`),
+ ...(raw.reason !== undefined ? { reason: assertString(raw.reason, `assertions[${index}].reason`) } : {}),
+ };
+ return record;
+}
+
+function validateObservationLimits(raw: unknown): Record {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_limits", "limits");
+ const out: Record = {};
+ for (const key of Object.keys(raw)) {
+ if (!(OBSERVATION_LIMIT_NAMES as readonly string[]).includes(key)) {
+ throw new LabValidationError("unknown_limit", `limits.${key}`);
+ }
+ const value = raw[key];
+ if (value === null) {
+ out[key] = null;
+ continue;
+ }
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+ throw new LabValidationError("invalid_limits", `limits.${key}`);
+ }
+ out[key] = value;
+ }
+ return out;
+}
+
+function validateObservationEnvironment(raw: unknown): Record {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_environment", "environment");
+ const topKeys = Object.keys(raw);
+ if (topKeys.length !== 1 || topKeys[0] !== "runtime") {
+ throw new LabValidationError("invalid_environment", "environment must contain only runtime");
+ }
+ const runtime = raw.runtime;
+ if (!isPlainObject(runtime)) throw new LabValidationError("invalid_environment", "environment.runtime");
+ const runtimeKeys = Object.keys(runtime);
+ const allowedRuntime = new Set(["platform", "arch", "bunVersion"]);
+ for (const key of runtimeKeys) {
+ if (!allowedRuntime.has(key)) {
+ throw new LabValidationError("unknown_environment_key", `environment.runtime.${key}`);
+ }
+ }
+ const out: Record = {
+ runtime: {
+ platform: assertString(runtime.platform, "environment.runtime.platform"),
+ arch: assertString(runtime.arch, "environment.runtime.arch"),
+ ...(runtime.bunVersion !== undefined
+ ? { bunVersion: assertString(runtime.bunVersion, "environment.runtime.bunVersion") }
+ : {}),
+ },
+ };
+ return out;
+}
+
+function validateExpectedFailure(raw: unknown): Record {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_expected_failure", "expectedFailure");
+ const allowed = new Set([
+ "controlKind",
+ "expectedClass",
+ "expectedCode",
+ "assertionIds",
+ "onMatch",
+ "onMismatch",
+ ]);
+ for (const key of Object.keys(raw)) {
+ if (!allowed.has(key)) {
+ throw new LabValidationError("unknown_expected_failure_key", `expectedFailure.${key}`);
+ }
+ }
+ if (!Array.isArray(raw.assertionIds) || !raw.assertionIds.every((id) => typeof id === "string")) {
+ throw new LabValidationError("invalid_expected_failure", "expectedFailure.assertionIds");
+ }
+ return {
+ controlKind: assertClosed(raw.controlKind, "expectedFailure.controlKind", [
+ "conformance_negative_control",
+ "capability_absence_control",
+ ] as const),
+ expectedClass: assertString(raw.expectedClass, "expectedFailure.expectedClass"),
+ expectedCode: assertString(raw.expectedCode, "expectedFailure.expectedCode"),
+ assertionIds: raw.assertionIds as string[],
+ onMatch: assertClosed(raw.onMatch, "expectedFailure.onMatch", ["pass", "unsupported"] as const),
+ onMismatch: assertClosed(raw.onMismatch, "expectedFailure.onMismatch", ["fail", "inconclusive"] as const),
+ };
+}
+
+function validateSourceRefs(raw: unknown): string[] {
+ if (!Array.isArray(raw)) throw new LabValidationError("invalid_source_refs", "sourceRefs");
+ return raw.map((r, i) => assertString(r, `sourceRefs[${i}]`));
+}
+
+function validateObservation(raw: Record): ObservationEvent {
+ const evidenceLayer = assertClosed(raw.evidenceLayer, "evidenceLayer", EVIDENCE_LAYERS);
+ const subject = validateSubject(raw.subject, evidenceLayer);
+ const subjectId = assertString(raw.subjectId, "subjectId");
+ if (subjectId !== subjectIdForSubject(subject)) {
+ throw new LabValidationError("subject_id_mismatch", "subjectId does not match subject");
+ }
+ if (!Array.isArray(raw.fixtureDigests) || raw.fixtureDigests.length === 0) {
+ throw new LabValidationError("missing_fixture_digests", "fixtureDigests required");
+ }
+ const fixtureDigests = raw.fixtureDigests.map((d, i) => {
+ const digest = assertString(d, `fixtureDigests[${i}]`);
+ if (!isSha256Hex(digest)) throw new LabValidationError("invalid_digest", `fixtureDigests[${i}]`);
+ return digest;
+ });
+ const scenarioManifestDigest = assertString(raw.scenarioManifestDigest, "scenarioManifestDigest");
+ const suiteManifestDigest = assertString(raw.suiteManifestDigest, "suiteManifestDigest");
+ if (!isSha256Hex(scenarioManifestDigest) || !isSha256Hex(suiteManifestDigest)) {
+ throw new LabValidationError("invalid_digest", "scenario/suite manifest digest");
+ }
+ if (!Array.isArray(raw.assertions)) throw new LabValidationError("invalid_assertions", "assertions");
+ if (!Array.isArray(raw.artifactRefs)) throw new LabValidationError("invalid_artifact_refs", "artifactRefs");
+ const event: ObservationEvent = {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventId: assertString(raw.eventId, "eventId"),
+ eventKind: "observation",
+ recordedAt: assertIntMs(raw.recordedAt, "recordedAt"),
+ producer: assertString(raw.producer, "producer"),
+ producerVersion: assertString(raw.producerVersion, "producerVersion"),
+ evidenceLayer,
+ scenarioId: assertString(raw.scenarioId, "scenarioId"),
+ scenarioVersion: assertString(raw.scenarioVersion, "scenarioVersion"),
+ scenarioManifestDigest,
+ suiteId: assertString(raw.suiteId, "suiteId"),
+ suiteVersion: assertString(raw.suiteVersion, "suiteVersion"),
+ suiteManifestDigest,
+ fixtureDigests,
+ subject,
+ subjectId,
+ startedAt: assertIntMs(raw.startedAt, "startedAt"),
+ completedAt: assertIntMs(raw.completedAt, "completedAt"),
+ executionMode: assertClosed(raw.executionMode, "executionMode", EXECUTION_MODES),
+ attempt: typeof raw.attempt === "number" && Number.isInteger(raw.attempt) && raw.attempt >= 1
+ ? raw.attempt
+ : (() => { throw new LabValidationError("invalid_attempt", "attempt"); })(),
+ limits: validateObservationLimits(raw.limits),
+ outcome: assertClosed(raw.outcome, "outcome", OUTCOMES),
+ assertions: raw.assertions.map(validateAssertionRecord),
+ environment: validateObservationEnvironment(raw.environment),
+ artifactRefs: raw.artifactRefs.map(validateArtifactRef),
+ };
+ if (raw.failure !== undefined) {
+ if (!isPlainObject(raw.failure)) throw new LabValidationError("invalid_failure", "failure");
+ event.failure = {
+ class: assertString(raw.failure.class, "failure.class"),
+ code: assertString(raw.failure.code, "failure.code"),
+ retryable: raw.failure.retryable === true,
+ attribution: assertClosed(raw.failure.attribution, "failure.attribution", [
+ "opencodex",
+ "route",
+ "environment",
+ "harness",
+ ] as const),
+ };
+ }
+ if (raw.expectedFailure !== undefined) {
+ event.expectedFailure = validateExpectedFailure(raw.expectedFailure);
+ }
+ if (raw.sourceRefs !== undefined) {
+ event.sourceRefs = validateSourceRefs(raw.sourceRefs);
+ }
+ if (event.completedAt < event.startedAt) {
+ throw new LabValidationError("invalid_time_range", "completedAt < startedAt");
+ }
+ return event;
+}
+
+function validateClaimSnapshot(raw: Record): ClaimSnapshotEvent {
+ if (raw.evidenceLayer !== "live_route_compatibility") {
+ throw new LabValidationError("invalid_claim_layer", "claims exist only for live_route_compatibility");
+ }
+ const subject = validateSubject(raw.subject, "live_route_compatibility") as RouteSubjectV1;
+ const subjectId = assertString(raw.subjectId, "subjectId");
+ if (subjectId !== subjectIdForSubject(subject)) {
+ throw new LabValidationError("subject_id_mismatch", "subjectId does not match subject");
+ }
+ const sourceManifestDigest = assertString(raw.sourceManifestDigest, "sourceManifestDigest");
+ if (!isSha256Hex(sourceManifestDigest)) {
+ throw new LabValidationError("invalid_digest", "sourceManifestDigest");
+ }
+ return {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventId: assertString(raw.eventId, "eventId"),
+ eventKind: "claim_snapshot",
+ recordedAt: assertIntMs(raw.recordedAt, "recordedAt"),
+ producer: assertString(raw.producer, "producer"),
+ producerVersion: assertString(raw.producerVersion, "producerVersion"),
+ evidenceLayer: "live_route_compatibility",
+ subject,
+ subjectId,
+ capability: assertString(raw.capability, "capability"),
+ polarity: assertClosed(raw.polarity, "polarity", CLAIM_POLARITIES),
+ sourceManifestDigest,
+ sourceEventIds: validateSortedUniqueHexIds(raw.sourceEventIds, "sourceEventIds", {
+ nonEmpty: false,
+ max: MAX_INVALIDATION_TARGETS,
+ }),
+ supersedes: validateSortedUniqueHexIds(raw.supersedes, "supersedes", {
+ nonEmpty: false,
+ max: MAX_INVALIDATION_TARGETS,
+ }),
+ effectiveAt: assertIntMs(raw.effectiveAt, "effectiveAt"),
+ };
+}
+
+function validateInvalidation(raw: Record): InvalidationEvent {
+ return {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventId: assertString(raw.eventId, "eventId"),
+ eventKind: "invalidation",
+ recordedAt: assertIntMs(raw.recordedAt, "recordedAt"),
+ producer: assertString(raw.producer, "producer"),
+ producerVersion: assertString(raw.producerVersion, "producerVersion"),
+ targetEventIds: validateSortedUniqueHexIds(raw.targetEventIds, "targetEventIds", {
+ nonEmpty: true,
+ max: MAX_INVALIDATION_TARGETS,
+ }),
+ reason: assertClosed(raw.reason, "reason", INVALIDATION_REASONS),
+ };
+}
+
+function validatePurge(raw: Record): PurgeTombstoneEvent {
+ const targetEventIds = validateSortedUniqueHexIds(raw.targetEventIds ?? [], "targetEventIds", {
+ nonEmpty: false,
+ max: MAX_INVALIDATION_TARGETS,
+ });
+ const targetArtifactDigests = validateSortedUniqueHexIds(
+ raw.targetArtifactDigests ?? [],
+ "targetArtifactDigests",
+ { nonEmpty: false, max: MAX_INVALIDATION_TARGETS },
+ );
+ if (targetEventIds.length === 0 && targetArtifactDigests.length === 0) {
+ throw new LabValidationError("empty_purge_targets", "at least one purge target required");
+ }
+ if (raw.reason !== "sensitive_evidence") {
+ throw new LabValidationError("invalid_purge_reason", "reason must be sensitive_evidence");
+ }
+ if (!Array.isArray(raw.purgeActions) || raw.purgeActions.length === 0) {
+ throw new LabValidationError("empty_purge_actions", "purgeActions required");
+ }
+ const purgeActions = raw.purgeActions.map((a, i) =>
+ assertClosed(a, `purgeActions[${i}]`, PURGE_ACTIONS),
+ );
+ for (let i = 0; i < purgeActions.length; i++) {
+ for (let j = i + 1; j < purgeActions.length; j++) {
+ if (purgeActions[i] === purgeActions[j]) {
+ throw new LabValidationError("duplicate_purge_action", "purgeActions must be unique");
+ }
+ }
+ }
+ const sortedActions = [...purgeActions].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+ for (let i = 0; i < purgeActions.length; i++) {
+ if (purgeActions[i] !== sortedActions[i]) {
+ throw new LabValidationError("unsorted_purge_actions", "purgeActions must be sorted");
+ }
+ }
+ return {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventId: assertString(raw.eventId, "eventId"),
+ eventKind: "purge_tombstone",
+ recordedAt: assertIntMs(raw.recordedAt, "recordedAt"),
+ producer: assertString(raw.producer, "producer"),
+ producerVersion: assertString(raw.producerVersion, "producerVersion"),
+ targetEventIds,
+ targetArtifactDigests,
+ reason: "sensitive_evidence",
+ purgeActions,
+ };
+}
+
+/** Structural validation of a parsed JSON object into a LabEvent (fail-closed). */
+export function validateLabEvent(raw: unknown): LabEvent {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_event", "event must be object");
+ if (raw.schemaVersion !== LAB_EVENT_SCHEMA_VERSION) {
+ throw new LabValidationError("schema_version", "unsupported schemaVersion");
+ }
+ const kind = assertClosed(raw.eventKind, "eventKind", EVENT_KINDS) as LabEventKind;
+ let event: LabEvent;
+ switch (kind) {
+ case "observation":
+ event = validateObservation(raw);
+ break;
+ case "claim_snapshot":
+ event = validateClaimSnapshot(raw);
+ break;
+ case "invalidation":
+ event = validateInvalidation(raw);
+ break;
+ case "purge_tombstone":
+ event = validatePurge(raw);
+ break;
+ default: {
+ const _never: never = kind;
+ throw new LabValidationError("unknown_kind", String(_never));
+ }
+ }
+ enforceEventId(event);
+ enforceEventStructureLimits(event);
+ enforceSerializedSize(event);
+ return event;
+}
+
+const FORBIDDEN_FACT_KEYS = new Set([
+ "baseUrl",
+ "hostname",
+ "url",
+ "headers",
+ "authorization",
+ "apiKey",
+ "credential",
+ "account",
+ "email",
+ "path",
+ "prompt",
+ "repository",
+]);
+
+const ALLOWED_FACT_KEYS = new Set([
+ "contextWindow",
+ "inputModalities",
+ "reasoningEfforts",
+ "catalogCapabilityNames",
+ "serviceTier",
+ "toolCapable",
+ "parallelToolCalls",
+ "endpointLocality",
+ "canonicalOpenAiForward",
+]);
+
+function validateFacts(raw: unknown, label: string): ClaimCapabilityFactsV1 {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_facts", label);
+ for (const key of Object.keys(raw)) {
+ if (FORBIDDEN_FACT_KEYS.has(key) || /url|host|header|secret|token|cookie|email|path/i.test(key)) {
+ throw new LabValidationError("forbidden_fact", `${label}.${key} forbidden`);
+ }
+ if (!ALLOWED_FACT_KEYS.has(key)) {
+ throw new LabValidationError("unknown_fact", `${label}.${key} unknown`);
+ }
+ }
+ const facts: ClaimCapabilityFactsV1 = {};
+ if (raw.contextWindow !== undefined) {
+ if (typeof raw.contextWindow !== "number" || !Number.isInteger(raw.contextWindow) || raw.contextWindow < 0) {
+ throw new LabValidationError("invalid_facts", "contextWindow");
+ }
+ facts.contextWindow = raw.contextWindow;
+ }
+ if (raw.inputModalities !== undefined) {
+ if (!Array.isArray(raw.inputModalities) || !raw.inputModalities.every((x) => typeof x === "string")) {
+ throw new LabValidationError("invalid_facts", "inputModalities");
+ }
+ facts.inputModalities = raw.inputModalities as string[];
+ }
+ if (raw.reasoningEfforts !== undefined) {
+ if (!Array.isArray(raw.reasoningEfforts) || !raw.reasoningEfforts.every((x) => typeof x === "string")) {
+ throw new LabValidationError("invalid_facts", "reasoningEfforts");
+ }
+ facts.reasoningEfforts = raw.reasoningEfforts as string[];
+ }
+ if (raw.catalogCapabilityNames !== undefined) {
+ if (!Array.isArray(raw.catalogCapabilityNames) || !raw.catalogCapabilityNames.every((x) => typeof x === "string")) {
+ throw new LabValidationError("invalid_facts", "catalogCapabilityNames");
+ }
+ facts.catalogCapabilityNames = raw.catalogCapabilityNames as string[];
+ }
+ if (raw.serviceTier !== undefined) {
+ if (!Array.isArray(raw.serviceTier) || !raw.serviceTier.every((x) => typeof x === "string")) {
+ throw new LabValidationError("invalid_facts", "serviceTier");
+ }
+ facts.serviceTier = raw.serviceTier as string[];
+ }
+ if (raw.toolCapable !== undefined) {
+ if (typeof raw.toolCapable !== "boolean") throw new LabValidationError("invalid_facts", "toolCapable");
+ facts.toolCapable = raw.toolCapable;
+ }
+ if (raw.parallelToolCalls !== undefined) {
+ if (typeof raw.parallelToolCalls !== "boolean") throw new LabValidationError("invalid_facts", "parallelToolCalls");
+ facts.parallelToolCalls = raw.parallelToolCalls;
+ }
+ if (raw.endpointLocality !== undefined) {
+ facts.endpointLocality = assertClosed(raw.endpointLocality, "endpointLocality", [
+ "local",
+ "private",
+ "unknown",
+ ] as const);
+ }
+ if (raw.canonicalOpenAiForward !== undefined) {
+ if (typeof raw.canonicalOpenAiForward !== "boolean") {
+ throw new LabValidationError("invalid_facts", "canonicalOpenAiForward");
+ }
+ facts.canonicalOpenAiForward = raw.canonicalOpenAiForward;
+ }
+ return facts;
+}
+
+function validateResolvedEvidence(raw: unknown): RouteCapabilityEvidenceV1 {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_resolved", "resolvedEvidence");
+ const out: RouteCapabilityEvidenceV1 = {};
+ const copyBoolOrUnknown = (key: keyof RouteCapabilityEvidenceV1) => {
+ const v = raw[key as string];
+ if (v === undefined) return;
+ if (v !== true && v !== false && v !== "unknown") {
+ throw new LabValidationError("invalid_resolved", String(key));
+ }
+ (out as Record)[key] = v;
+ };
+ if (raw.contextWindow !== undefined) {
+ if (typeof raw.contextWindow !== "number" || !Number.isInteger(raw.contextWindow)) {
+ throw new LabValidationError("invalid_resolved", "contextWindow");
+ }
+ out.contextWindow = raw.contextWindow;
+ }
+ copyBoolOrUnknown("tools");
+ copyBoolOrUnknown("image");
+ copyBoolOrUnknown("structuredOutput");
+ copyBoolOrUnknown("localOnly");
+ copyBoolOrUnknown("remoteAllowed");
+ copyBoolOrUnknown("encryptedCodexTasks");
+ if (raw.reasoningEfforts !== undefined) {
+ if (!Array.isArray(raw.reasoningEfforts) || !raw.reasoningEfforts.every((x) => typeof x === "string")) {
+ throw new LabValidationError("invalid_resolved", "reasoningEfforts");
+ }
+ out.reasoningEfforts = raw.reasoningEfforts as string[];
+ }
+ if (raw.serviceTier !== undefined) {
+ if (typeof raw.serviceTier !== "string") throw new LabValidationError("invalid_resolved", "serviceTier");
+ out.serviceTier = raw.serviceTier;
+ }
+ return out;
+}
+
+/** Validate ClaimSourceManifestV1 and return canonical object + digest. */
+export function validateClaimSourceManifest(raw: unknown): {
+ manifest: ClaimSourceManifestV1;
+ digest: string;
+} {
+ if (!isPlainObject(raw)) throw new LabValidationError("invalid_claim_source", "manifest must be object");
+ if (raw.schemaVersion !== 1) throw new LabValidationError("schema_version", "ClaimSourceManifest schemaVersion");
+ if (!Array.isArray(raw.sources)) throw new LabValidationError("invalid_sources", "sources");
+ const seen = new Set();
+ const sources: ClaimSourceV1[] = [];
+ for (let i = 0; i < raw.sources.length; i++) {
+ const src = raw.sources[i];
+ if (!isPlainObject(src)) throw new LabValidationError("invalid_source", `sources[${i}]`);
+ const kind = assertClosed(src.kind, `sources[${i}].kind`, CLAIM_SOURCE_KINDS);
+ if (seen.has(kind)) throw new LabValidationError("duplicate_source_kind", kind);
+ seen.add(kind);
+ if (src.revision !== null && typeof src.revision !== "string") {
+ throw new LabValidationError("invalid_revision", `sources[${i}].revision`);
+ }
+ sources.push({
+ kind,
+ revision: src.revision as string | null,
+ facts: validateFacts(src.facts, `sources[${i}].facts`),
+ });
+ }
+ // Closed kind order
+ for (let i = 1; i < sources.length; i++) {
+ const prevIdx = CLAIM_SOURCE_KINDS.indexOf(sources[i - 1]!.kind);
+ const curIdx = CLAIM_SOURCE_KINDS.indexOf(sources[i]!.kind);
+ if (curIdx <= prevIdx) {
+ throw new LabValidationError("source_order", "sources must follow closed kind order");
+ }
+ }
+ const manifest: ClaimSourceManifestV1 = {
+ schemaVersion: 1,
+ subjectId: assertString(raw.subjectId, "subjectId"),
+ providerId: assertString(raw.providerId, "providerId"),
+ clientModelId: assertString(raw.clientModelId, "clientModelId"),
+ capability: assertString(raw.capability, "capability"),
+ sources,
+ resolvedEvidence: validateResolvedEvidence(raw.resolvedEvidence),
+ };
+ if (!isSha256Hex(manifest.subjectId)) {
+ throw new LabValidationError("invalid_subject_id", "subjectId must be sha256 hex");
+ }
+ return { manifest, digest: claimSourceManifestDigest(manifest) };
+}
+
+export function assignEventId & { eventId?: string }>(
+ eventWithoutId: T,
+): T & { eventId: string } {
+ const { eventId: _ignored, ...rest } = eventWithoutId as T & { eventId?: string };
+ const eventId = eventIdForPayload(rest);
+ return { ...rest, eventId } as T & { eventId: string };
+}
+
+export function artifactClassMediaType(artifactClass: ArtifactClass): string {
+ switch (artifactClass) {
+ case "scenario_manifest":
+ case "suite_manifest":
+ case "claim_source_manifest":
+ case "assertion_report":
+ case "request_shape":
+ case "response_shape":
+ case "event_trace":
+ case "error_taxonomy":
+ case "verifier_summary":
+ return "application/json";
+ case "fixture":
+ return "application/octet-stream";
+ default: {
+ const _never: never = artifactClass;
+ return _never;
+ }
+ }
+}
diff --git a/src/lab/index.ts b/src/lab/index.ts
new file mode 100644
index 000000000..2515f8481
--- /dev/null
+++ b/src/lab/index.ts
@@ -0,0 +1,19 @@
+export * from "./constants";
+export * from "./digest";
+export * from "./paths";
+export * from "./events/types";
+export * from "./events/validate";
+export * from "./artifacts/secure-fs";
+export * from "./artifacts/store";
+export * from "./artifacts/sanitize";
+export * from "./ledger/store";
+export * from "./ledger/invalidation";
+export * from "./ledger/purge";
+export * from "./projection/schema";
+export * from "./projection/verdicts";
+export * from "./projection/rebuild";
+export * from "./events/limits";
+export * from "./conformance/suite-manifest";
+export * from "./ledger/artifact-refs";
+export * from "./projection/verification";
+export * from "./observe/from-conformance";
diff --git a/src/lab/ledger/artifact-refs.ts b/src/lab/ledger/artifact-refs.ts
new file mode 100644
index 000000000..0832f535e
--- /dev/null
+++ b/src/lab/ledger/artifact-refs.ts
@@ -0,0 +1,127 @@
+import type { ClaimSnapshotEvent, LabEvent, ObservationEvent } from "../events/types";
+import type { InvalidationIndex } from "./invalidation";
+
+/** Collect artifacts that the frozen CL-00 retention rules still require. */
+export function collectReferencedArtifactDigests(
+ events: LabEvent[],
+ index: InvalidationIndex,
+ opts: { excludeEventIds?: Set } = {},
+): Set {
+ const refs = new Set();
+ const exclude = opts.excludeEventIds ?? new Set();
+
+ for (const event of events) {
+ if (exclude.has(event.eventId)) continue;
+ if (index.purgedEventIds.has(event.eventId)) continue;
+
+ if (event.eventKind === "observation") {
+ // CL-00 releases observation artifacts after invalidation or purge.
+ if (index.invalidatedBy.has(event.eventId)) continue;
+ addObservationArtifacts(event, refs);
+ continue;
+ }
+ if (event.eventKind === "claim_snapshot") {
+ // CL-00 retains claim source manifests while any non-purged claim references them.
+ refs.add(event.sourceManifestDigest);
+ }
+ }
+ return refs;
+}
+
+function addObservationArtifacts(obs: ObservationEvent, refs: Set): void {
+ refs.add(obs.scenarioManifestDigest);
+ refs.add(obs.suiteManifestDigest);
+ for (const digest of obs.fixtureDigests) refs.add(digest);
+ for (const ref of obs.artifactRefs) refs.add(ref.digest);
+}
+
+export function eventReferencesArtifactDigest(event: LabEvent, digest: string): boolean {
+ if (event.eventKind === "observation") {
+ if (event.scenarioManifestDigest === digest) return true;
+ if (event.suiteManifestDigest === digest) return true;
+ if (event.fixtureDigests.includes(digest)) return true;
+ return event.artifactRefs.some((ref) => ref.digest === digest);
+ }
+ if (event.eventKind === "claim_snapshot") {
+ return event.sourceManifestDigest === digest;
+ }
+ return false;
+}
+
+/**
+ * Expand purge targets so explicitly sensitive artifact digests cannot survive
+ * while any retained ledger evidence line still references them.
+ */
+export function expandSensitiveArtifactEventTargets(
+ events: LabEvent[],
+ index: InvalidationIndex,
+ targetEventIds: Set,
+ explicitArtifactDigests: Set,
+): Set {
+ const expanded = new Set(targetEventIds);
+ if (explicitArtifactDigests.size === 0) return expanded;
+
+ for (const event of events) {
+ if (expanded.has(event.eventId)) continue;
+ if (index.purgedEventIds.has(event.eventId)) continue;
+ for (const digest of explicitArtifactDigests) {
+ if (eventReferencesArtifactDigest(event, digest)) {
+ expanded.add(event.eventId);
+ break;
+ }
+ }
+ }
+ return expanded;
+}
+
+/** Artifacts still required by surviving evidence after excluding purge targets. */
+export function artifactsStillRequired(
+ events: LabEvent[],
+ index: InvalidationIndex,
+ excludeEventIds: Set,
+): Set {
+ return collectReferencedArtifactDigests(events, index, { excludeEventIds });
+}
+
+export interface ArtifactDeletionPlan {
+ deletable: string[];
+ /** Explicitly sensitive digests that remain pinned by surviving evidence. */
+ retainedExplicit: string[];
+}
+
+/** Plan physical artifact deletion for a purge without silently retaining explicit targets. */
+export function artifactDeletionPlan(
+ events: LabEvent[],
+ index: InvalidationIndex,
+ targetEventIds: Set,
+ explicitArtifactDigests: string[],
+): ArtifactDeletionPlan {
+ const stillRequired = artifactsStillRequired(events, index, targetEventIds);
+ const candidates = new Set(explicitArtifactDigests);
+
+ for (const event of events) {
+ if (!targetEventIds.has(event.eventId)) continue;
+ if (event.eventKind === "observation") {
+ const scratch = new Set();
+ addObservationArtifacts(event, scratch);
+ for (const digest of scratch) candidates.add(digest);
+ } else if (event.eventKind === "claim_snapshot") {
+ candidates.add(event.sourceManifestDigest);
+ }
+ }
+
+ return {
+ deletable: [...candidates].filter((digest) => !stillRequired.has(digest)).sort(),
+ retainedExplicit: explicitArtifactDigests.filter((digest) => stillRequired.has(digest)).sort(),
+ };
+}
+
+export function observationArtifactDigests(obs: ObservationEvent): string[] {
+ const out = new Set();
+ addObservationArtifacts(obs, out);
+ return [...out].sort();
+}
+
+export function claimArtifactDigests(claim: ClaimSnapshotEvent): string[] {
+ return [claim.sourceManifestDigest];
+}
diff --git a/src/lab/ledger/invalidation.ts b/src/lab/ledger/invalidation.ts
new file mode 100644
index 000000000..5c62b8dca
--- /dev/null
+++ b/src/lab/ledger/invalidation.ts
@@ -0,0 +1,136 @@
+import type {
+ ClaimSnapshotEvent,
+ InvalidationEvent,
+ LabEvent,
+ LedgerCorruption,
+ ObservationEvent,
+ PurgeTombstoneEvent,
+} from "../events/types";
+import { LabValidationError } from "../events/validate";
+
+export interface InvalidationIndex {
+ /** eventId -> invalidation eventIds that targeted it */
+ invalidatedBy: Map;
+ purgedEventIds: Set;
+ purgedArtifactDigests: Set;
+ corruptions: LedgerCorruption[];
+}
+
+type EventPosition = { kind: LabEvent["eventKind"]; index: number };
+
+/**
+ * Apply purge tombstones before ordinary invalidations.
+ * Invalidation target lists are atomic: any bad target rejects the whole event.
+ */
+export function buildInvalidationIndex(events: LabEvent[]): InvalidationIndex {
+ const purgedEventIds = new Set();
+ const purgedArtifactDigests = new Set();
+ const invalidatedBy = new Map();
+ const corruptions: LedgerCorruption[] = [];
+
+ const validEvidenceIds = new Map();
+ const allEventIds = new Map();
+
+ // First pass: record event positions and evidence positions; apply purges as encountered.
+ for (let i = 0; i < events.length; i++) {
+ const event = events[i]!;
+ allEventIds.set(event.eventId, { kind: event.eventKind, index: i });
+ if (event.eventKind === "observation" || event.eventKind === "claim_snapshot") {
+ validEvidenceIds.set(event.eventId, { kind: event.eventKind, index: i });
+ continue;
+ }
+ if (event.eventKind === "purge_tombstone") {
+ applyPurge(event, purgedEventIds, purgedArtifactDigests);
+ }
+ }
+
+ // Second pass: validate and apply invalidations against earlier evidence.
+ for (let i = 0; i < events.length; i++) {
+ const event = events[i]!;
+ if (event.eventKind !== "invalidation") continue;
+ try {
+ validateInvalidationTargets(event, i, validEvidenceIds, allEventIds);
+ for (const target of event.targetEventIds) {
+ const list = invalidatedBy.get(target) ?? [];
+ list.push(event.eventId);
+ invalidatedBy.set(target, list);
+ }
+ } catch (err) {
+ corruptions.push({
+ kind: "invalid_reference",
+ eventId: event.eventId,
+ detail: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ return { invalidatedBy, purgedEventIds, purgedArtifactDigests, corruptions };
+}
+
+function applyPurge(
+ event: PurgeTombstoneEvent,
+ purgedEventIds: Set,
+ purgedArtifactDigests: Set,
+): void {
+ for (const id of event.targetEventIds) purgedEventIds.add(id);
+ for (const digest of event.targetArtifactDigests) purgedArtifactDigests.add(digest);
+}
+
+function validateInvalidationTargets(
+ event: InvalidationEvent,
+ index: number,
+ validEvidenceIds: Map,
+ allEventIds: Map,
+): void {
+ for (const target of event.targetEventIds) {
+ if (target === event.eventId) {
+ throw new LabValidationError("self_target", "invalidation cannot target itself");
+ }
+ const meta = validEvidenceIds.get(target);
+ if (!meta) {
+ const other = allEventIds.get(target);
+ if (
+ other &&
+ other.index < index &&
+ (other.kind === "invalidation" || other.kind === "purge_tombstone")
+ ) {
+ throw new LabValidationError("bad_target_kind", `cannot invalidate ${other.kind}`);
+ }
+ throw new LabValidationError("unknown_target", `unknown target ${target}`);
+ }
+ if (meta.index >= index) {
+ throw new LabValidationError("future_target", `target ${target} is not earlier`);
+ }
+ // Purged targets may no longer have a ledger line. A previously valid evidence
+ // ID remains addressable because validEvidenceIds records its original position.
+ }
+}
+
+export function isEventExcluded(
+ eventId: string,
+ index: InvalidationIndex,
+): boolean {
+ if (index.purgedEventIds.has(eventId)) return true;
+ if (index.invalidatedBy.has(eventId)) return true;
+ return false;
+}
+
+export function usableObservations(
+ events: LabEvent[],
+ index: InvalidationIndex,
+): ObservationEvent[] {
+ return events.filter(
+ (e): e is ObservationEvent =>
+ e.eventKind === "observation" && !isEventExcluded(e.eventId, index),
+ );
+}
+
+export function usableClaims(
+ events: LabEvent[],
+ index: InvalidationIndex,
+): ClaimSnapshotEvent[] {
+ return events.filter(
+ (e): e is ClaimSnapshotEvent =>
+ e.eventKind === "claim_snapshot" && !isEventExcluded(e.eventId, index),
+ );
+}
diff --git a/src/lab/ledger/purge.ts b/src/lab/ledger/purge.ts
new file mode 100644
index 000000000..700221b0e
--- /dev/null
+++ b/src/lab/ledger/purge.ts
@@ -0,0 +1,226 @@
+import {
+ closeTrustedArtifactDir,
+ deleteArtifactBytes,
+ openTrustedArtifactDir,
+ type TrustedArtifactDir,
+} from "../artifacts/secure-fs";
+import { ArtifactFsError } from "../artifacts/secure-fs";
+import {
+ LAB_EVENT_SCHEMA_VERSION,
+ LAB_PRODUCER,
+ LAB_PRODUCER_VERSION,
+ PURGE_ACTIONS,
+} from "../constants";
+import type { LabEvent, PurgeTombstoneEvent } from "../events/types";
+import { assignEventId, validateLabEvent } from "../events/validate";
+import {
+ artifactDeletionPlan,
+ expandSensitiveArtifactEventTargets,
+} from "./artifact-refs";
+import { buildInvalidationIndex } from "./invalidation";
+import { appendLabEvent, replayLabLedger } from "./store";
+import { ensureLabDirs } from "../paths";
+import { rebuildLabProjection } from "../projection/rebuild";
+import { jcsStringify } from "../digest";
+import {
+ closeSync,
+ existsSync,
+ fsyncSync,
+ openSync,
+ readdirSync,
+ renameSync,
+ rmSync,
+ unlinkSync,
+ writeSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export class PurgeError extends Error {
+ readonly code: string;
+ readonly completedActions: string[];
+ constructor(code: string, message: string, completedActions: string[] = []) {
+ super(message);
+ this.name = "PurgeError";
+ this.code = code;
+ this.completedActions = [...completedActions];
+ }
+}
+
+export interface SensitivePurgeRequest {
+ configDir?: string;
+ targetEventIds?: string[];
+ targetArtifactDigests?: string[];
+ purgeActions?: Array<(typeof PURGE_ACTIONS)[number]>;
+ recordedAt?: number;
+ producerVersion?: string;
+}
+
+function writeAll(fd: number, bytes: Uint8Array): void {
+ let offset = 0;
+ while (offset < bytes.byteLength) {
+ const n = writeSync(fd, bytes, offset, bytes.byteLength - offset);
+ if (n <= 0) throw new PurgeError("short_write", "ledger rewrite short write");
+ offset += n;
+ }
+}
+
+function atomicRewriteLedger(ledgerPath: string, events: LabEvent[]): void {
+ const body = events.map((e) => jcsStringify(e)).join("\n") + (events.length ? "\n" : "");
+ const bytes = new TextEncoder().encode(body);
+ const parent = dirname(ledgerPath);
+ const tmpPath = join(parent, `.purge-${process.pid}-${Date.now()}.jsonl.tmp`);
+ try {
+ const fd = openSync(tmpPath, "wx", 0o600);
+ try {
+ writeAll(fd, bytes);
+ fsyncSync(fd);
+ } finally {
+ closeSync(fd);
+ }
+ renameSync(tmpPath, ledgerPath);
+ if (process.platform !== "win32") {
+ const dirFd = openSync(parent, "r");
+ try {
+ fsyncSync(dirFd);
+ } finally {
+ closeSync(dirFd);
+ }
+ }
+ } catch (err) {
+ try {
+ unlinkSync(tmpPath);
+ } catch {
+ // Preserve the original failure. The temp file may already have been renamed.
+ }
+ throw err;
+ }
+}
+
+function deleteArtifactsFailClosed(dir: TrustedArtifactDir, digests: string[]): void {
+ const errors: string[] = [];
+ for (const digest of digests) {
+ try {
+ deleteArtifactBytes(dir, digest);
+ } catch (err) {
+ if (err instanceof ArtifactFsError && err.code === "artifact_missing") continue;
+ errors.push(err instanceof Error ? err.message : String(err));
+ }
+ }
+ if (errors.length > 0) {
+ throw new PurgeError("artifact_delete_failed", errors.join("; "));
+ }
+}
+
+function purgeBoundedDirectory(dirPath: string): void {
+ if (!existsSync(dirPath)) return;
+ const entries = readdirSync(dirPath, { withFileTypes: true });
+ for (const entry of entries) {
+ const full = join(dirPath, entry.name);
+ try {
+ rmSync(full, { recursive: entry.isDirectory(), force: true });
+ } catch (err) {
+ throw new PurgeError(
+ "scratch_export_delete_failed",
+ err instanceof Error ? err.message : String(err),
+ );
+ }
+ }
+}
+
+/**
+ * Exceptional sensitive-evidence purge:
+ * physically remove targeted JSONL lines and artifacts, append purge_tombstone,
+ * rebuild SQLite. Fails closed when required sensitive bytes cannot be removed.
+ */
+export function purgeSensitiveEvidence(req: SensitivePurgeRequest): PurgeTombstoneEvent {
+ const paths = ensureLabDirs(req.configDir);
+ const targetEventIds = [...(req.targetEventIds ?? [])].sort();
+ const targetArtifactDigests = [...(req.targetArtifactDigests ?? [])].sort();
+ const purgeActions = [...(req.purgeActions ?? ["ledger", "sqlite", "artifact", "scratch"])].sort();
+ const explicitSensitive = new Set(targetArtifactDigests);
+
+ const replay = replayLabLedger(paths.ledgerPath);
+ const index = buildInvalidationIndex(replay.events);
+ const removeIds = expandSensitiveArtifactEventTargets(
+ replay.events,
+ index,
+ new Set(targetEventIds),
+ explicitSensitive,
+ );
+
+ const tombstonePayload = {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventKind: "purge_tombstone" as const,
+ recordedAt: req.recordedAt ?? Date.now(),
+ producer: LAB_PRODUCER,
+ producerVersion: req.producerVersion ?? LAB_PRODUCER_VERSION,
+ targetEventIds: [...removeIds].sort(),
+ targetArtifactDigests,
+ reason: "sensitive_evidence" as const,
+ purgeActions,
+ };
+ const tombstone = validateLabEvent(assignEventId(tombstonePayload)) as PurgeTombstoneEvent;
+
+ const deletionPlan = purgeActions.includes("artifact")
+ ? artifactDeletionPlan(replay.events, index, removeIds, targetArtifactDigests)
+ : { deletable: [], retainedExplicit: [] };
+
+ if (deletionPlan.retainedExplicit.length > 0) {
+ throw new PurgeError(
+ "sensitive_bytes_retained",
+ `explicit sensitive artifacts remain required: ${deletionPlan.retainedExplicit.join(",")}`,
+ );
+ }
+
+ let dir: TrustedArtifactDir | null = null;
+ const completed: string[] = [];
+ try {
+ if (purgeActions.includes("scratch")) {
+ purgeBoundedDirectory(paths.scratchDir);
+ completed.push("scratch");
+ }
+ if (purgeActions.includes("export")) {
+ purgeBoundedDirectory(paths.exportDir);
+ completed.push("export");
+ }
+
+ if (purgeActions.includes("artifact")) {
+ if (deletionPlan.deletable.length > 0) {
+ dir = openTrustedArtifactDir(paths.artifactsDir);
+ deleteArtifactsFailClosed(dir, deletionPlan.deletable);
+ }
+ completed.push("artifact");
+ }
+
+ if (purgeActions.includes("ledger")) {
+ const kept: LabEvent[] = [];
+ for (const event of replay.events) {
+ if (removeIds.has(event.eventId)) continue;
+ kept.push(event);
+ }
+ kept.push(tombstone);
+ atomicRewriteLedger(paths.ledgerPath, kept);
+ } else {
+ appendLabEvent(paths.ledgerPath, tombstone);
+ }
+ completed.push("ledger");
+
+ if (purgeActions.includes("sqlite")) {
+ rebuildLabProjection(req.configDir);
+ completed.push("sqlite");
+ }
+
+ return tombstone;
+ } catch (err) {
+ if (err instanceof PurgeError) {
+ throw new PurgeError(err.code, err.message, [...completed, ...err.completedActions]);
+ }
+ throw new PurgeError(
+ "purge_failed",
+ err instanceof Error ? err.message : String(err),
+ completed,
+ );
+ } finally {
+ if (dir) closeTrustedArtifactDir(dir);
+ }
+}
diff --git a/src/lab/ledger/store.ts b/src/lab/ledger/store.ts
new file mode 100644
index 000000000..ade8c3e3d
--- /dev/null
+++ b/src/lab/ledger/store.ts
@@ -0,0 +1,278 @@
+import {
+ closeSync,
+ existsSync,
+ fsyncSync,
+ mkdirSync,
+ openSync,
+ readSync,
+ statSync,
+ writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { jcsStringify } from "../digest";
+import { MAX_SERIALIZED_EVENT_BYTES } from "../constants";
+import type { LabEvent, LedgerCorruption, ReplayResult } from "../events/types";
+import { LabValidationError, validateLabEvent } from "../events/validate";
+import { ensureLabDirs, labLedgerPath } from "../paths";
+
+export interface LedgerStore {
+ path: string;
+ append(event: LabEvent): void;
+ replay(): ReplayResult;
+}
+
+/** Durable append of one validated event as a single JSONL line + fsync. */
+export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
+ const validated = validateLabEvent(event);
+ mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+ const line = `${jcsStringify(validated)}\n`;
+ const bytes = new TextEncoder().encode(line);
+ const fd = openSync(ledgerPath, "a", 0o600);
+ try {
+ let written = 0;
+ while (written < bytes.byteLength) {
+ const n = writeSync(fd, bytes, written, bytes.byteLength - written);
+ if (n <= 0) {
+ throw new LabValidationError("short_write", "ledger append made no progress");
+ }
+ written += n;
+ }
+ fsyncSync(fd);
+ } finally {
+ closeSync(fd);
+ }
+}
+
+function processLine(
+ line: string,
+ lineNumber: number,
+ lineHasTrailingNewline: boolean,
+ events: LabEvent[],
+ seenIds: Set,
+ corruptions: LedgerCorruption[],
+): void {
+ if (!lineHasTrailingNewline) {
+ corruptions.push({
+ kind: "partial_line",
+ lineNumber,
+ detail: "partial final JSONL line (missing trailing newline)",
+ });
+ return;
+ }
+ if (line.trim() === "") {
+ corruptions.push({ kind: "malformed_line", lineNumber, detail: "empty line" });
+ return;
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(line);
+ } catch {
+ corruptions.push({ kind: "malformed_line", lineNumber, detail: "JSON parse failed" });
+ return;
+ }
+
+ let event: LabEvent;
+ try {
+ event = validateLabEvent(parsed);
+ } catch (err) {
+ corruptions.push({
+ kind: "invalid_event",
+ lineNumber,
+ detail: err instanceof Error ? err.message : String(err),
+ });
+ return;
+ }
+
+ if (seenIds.has(event.eventId)) {
+ corruptions.push({
+ kind: "duplicate_event",
+ lineNumber,
+ eventId: event.eventId,
+ detail: "duplicate eventId",
+ });
+ return;
+ }
+ seenIds.add(event.eventId);
+ events.push(event);
+}
+
+function splitIncompleteUtf8Tail(buf: Buffer): { processable: Buffer; remainder: Buffer } {
+ if (buf.length === 0) return { processable: buf, remainder: Buffer.alloc(0) };
+ for (let back = 1; back <= 4 && back <= buf.length; back++) {
+ const byte = buf[buf.length - back]!;
+ if ((byte & 0xc0) === 0x80) continue;
+ const needed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+ const seqStart = buf.length - back;
+ const available = buf.length - seqStart;
+ if (available < needed) {
+ return { processable: buf.subarray(0, seqStart), remainder: buf.subarray(seqStart) };
+ }
+ break;
+ }
+ return { processable: buf, remainder: Buffer.alloc(0) };
+}
+
+function processBufferedLines(
+ buf: Buffer,
+ state: {
+ lineNumber: number;
+ totalLineCount: number;
+ skippingOversizedLine: boolean;
+ events: LabEvent[];
+ seenIds: Set;
+ corruptions: LedgerCorruption[];
+ },
+): { carry: Buffer; skippingOversizedLine: boolean } {
+ let start = 0;
+ let skipping = state.skippingOversizedLine;
+
+ while (start < buf.length) {
+ const newlineIdx = buf.indexOf(0x0a, start);
+ if (newlineIdx < 0) {
+ const tail = buf.subarray(start);
+ if (skipping) {
+ return { carry: Buffer.alloc(0), skippingOversizedLine: true };
+ }
+ if (tail.length > MAX_SERIALIZED_EVENT_BYTES) {
+ state.lineNumber += 1;
+ state.totalLineCount += 1;
+ state.corruptions.push({
+ kind: "malformed_line",
+ lineNumber: state.lineNumber,
+ detail: `line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes without newline`,
+ });
+ return { carry: tail, skippingOversizedLine: true };
+ }
+ return { carry: tail, skippingOversizedLine: false };
+ }
+
+ const lineBytes = buf.subarray(start, newlineIdx);
+ start = newlineIdx + 1;
+
+ if (skipping) {
+ skipping = false;
+ continue;
+ }
+
+ state.lineNumber += 1;
+ state.totalLineCount += 1;
+ processLine(lineBytes.toString("utf8"), state.lineNumber, true, state.events, state.seenIds, state.corruptions);
+ }
+
+ return { carry: Buffer.alloc(0), skippingOversizedLine: skipping };
+}
+
+/**
+ * Replay the JSONL ledger using chunked reads (no whole-file string buffer).
+ * Malformed or partial lines contribute no evidence and are reported as corruption.
+ */
+export function replayLabLedger(ledgerPath: string): ReplayResult {
+ const corruptions: LedgerCorruption[] = [];
+ const events: LabEvent[] = [];
+ if (!existsSync(ledgerPath)) {
+ return { events, corruptions, validLineCount: 0, totalLineCount: 0 };
+ }
+ const size = statSync(ledgerPath).size;
+ if (size === 0) {
+ return {
+ events,
+ corruptions: [{ kind: "empty_ledger", detail: "ledger file is empty" }],
+ validLineCount: 0,
+ totalLineCount: 0,
+ };
+ }
+
+ const fd = openSync(ledgerPath, "r");
+ const chunkSize = 64 * 1024;
+ const chunk = Buffer.alloc(chunkSize);
+ let carry: Buffer = Buffer.alloc(0);
+ let lineNumber = 0;
+ let totalLineCount = 0;
+ const seenIds = new Set();
+ let offset = 0;
+ let skippingOversizedLine = false;
+
+ const state = {
+ lineNumber,
+ totalLineCount,
+ skippingOversizedLine,
+ events,
+ seenIds,
+ corruptions,
+ };
+
+ try {
+ while (offset < size) {
+ const toRead = Math.min(chunkSize, size - offset);
+ const n = readSync(fd, chunk, 0, toRead, offset);
+ if (n <= 0) break;
+ offset += n;
+
+ const combined = carry.length > 0
+ ? Buffer.concat([carry, chunk.subarray(0, n)])
+ : chunk.subarray(0, n);
+ const { processable, remainder } = splitIncompleteUtf8Tail(combined);
+ carry = remainder;
+
+ const result = processBufferedLines(processable, state);
+ carry = result.carry.length > 0
+ ? Buffer.from(Buffer.concat([carry, result.carry]))
+ : carry;
+ skippingOversizedLine = result.skippingOversizedLine;
+ state.skippingOversizedLine = skippingOversizedLine;
+ lineNumber = state.lineNumber;
+ totalLineCount = state.totalLineCount;
+ }
+
+ if (carry.length > 0) {
+ if (skippingOversizedLine) {
+ lineNumber += 1;
+ totalLineCount += 1;
+ corruptions.push({
+ kind: "malformed_line",
+ lineNumber,
+ detail: `oversized line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes`,
+ });
+ } else if (carry.length > MAX_SERIALIZED_EVENT_BYTES) {
+ lineNumber += 1;
+ totalLineCount += 1;
+ corruptions.push({
+ kind: "malformed_line",
+ lineNumber,
+ detail: `partial line exceeds ${MAX_SERIALIZED_EVENT_BYTES} bytes`,
+ });
+ } else {
+ lineNumber += 1;
+ totalLineCount += 1;
+ processLine(carry.toString("utf8"), lineNumber, false, events, seenIds, corruptions);
+ }
+ }
+ } finally {
+ closeSync(fd);
+ }
+
+ return {
+ events,
+ corruptions,
+ validLineCount: events.length,
+ totalLineCount,
+ };
+}
+
+export function openLedgerStore(configDir?: string): LedgerStore {
+ const paths = ensureLabDirs(configDir);
+ return {
+ path: paths.ledgerPath,
+ append(event: LabEvent) {
+ appendLabEvent(paths.ledgerPath, event);
+ },
+ replay() {
+ return replayLabLedger(paths.ledgerPath);
+ },
+ };
+}
+
+export function defaultLedgerPath(configDir?: string): string {
+ return labLedgerPath(configDir);
+}
diff --git a/src/lab/observe/from-conformance.ts b/src/lab/observe/from-conformance.ts
new file mode 100644
index 000000000..5a165439c
--- /dev/null
+++ b/src/lab/observe/from-conformance.ts
@@ -0,0 +1,343 @@
+/**
+ * Persistence seam: transform CL-01 conformance results into valid observation events.
+ * Deterministic harness execution stays separate from ledger persistence.
+ */
+import { createHash } from "node:crypto";
+import { createArtifactStore, type ArtifactStore } from "../artifacts/store";
+import {
+ LAB_EVENT_SCHEMA_VERSION,
+ LAB_PRODUCER,
+ LAB_PRODUCER_VERSION,
+ type ObservationOutcome,
+} from "../constants";
+import {
+ jcsStringify,
+ scenarioManifestDigest,
+ subjectIdForSubject,
+ suiteManifestDigest,
+} from "../digest";
+import type { ObservationEvent, ProtocolSubjectV1 } from "../events/types";
+import { assignEventId } from "../events/validate";
+import { appendLabEvent } from "../ledger/store";
+import { ensureLabDirs } from "../paths";
+import type {
+ CaseAuthority,
+ CaseRecord,
+ ProtocolExecutionContextV1,
+ ScenarioRunResult,
+} from "../conformance/types";
+import { expandScenario } from "../conformance/manifest";
+import { suiteManifestObjectForCase } from "../conformance/suite-manifest";
+import { fixtureDigest } from "../conformance/digest";
+import { resolveProtocolExecutionContext } from "../conformance/executor";
+
+const COMPAT_VERSION = "protocol-v1";
+
+type TimedScenarioRunResult = ScenarioRunResult & {
+ startedAt?: number;
+ completedAt?: number;
+};
+
+export interface PersistConformanceOptions {
+ configDir?: string;
+ recordedAt?: number;
+ /** Actual execution timestamps from the CL-01 runner; never fabricated. */
+ startedAt?: number;
+ completedAt?: number;
+ producerVersion?: string;
+ artifactStore?: ArtifactStore;
+}
+
+export interface PersistedConformanceObservation {
+ event: ObservationEvent;
+ ledgerPath: string;
+}
+
+function validateExecutionContext(
+ caseRecord: CaseRecord,
+ ctx: ProtocolExecutionContextV1,
+): ProtocolExecutionContextV1 {
+ const checks: Array<[string, string[], string]> = [
+ ["inboundProtocols", caseRecord.requirements.inboundProtocols, ctx.inboundProtocol],
+ ["upstreamProtocols", caseRecord.requirements.upstreamProtocols, ctx.upstreamProtocol],
+ ["surfaces", caseRecord.requirements.surfaces, ctx.surface],
+ ];
+ for (const [name, declared, actual] of checks) {
+ if (declared.length === 0) throw new Error(`case ${caseRecord.id} has empty ${name}`);
+ if (!declared.includes(actual)) {
+ throw new Error(`case ${caseRecord.id} execution context violates ${name}`);
+ }
+ }
+ return ctx;
+}
+
+function behaviorFingerprintForCase(
+ caseRecord: CaseRecord,
+ executionContext?: ProtocolExecutionContextV1,
+): string {
+ const ctx = validateExecutionContext(
+ caseRecord,
+ executionContext ?? resolveProtocolExecutionContext(caseRecord),
+ );
+ const adapter = upstreamAdapter(ctx.upstreamProtocol);
+ const values = {
+ schemaVersion: 1,
+ resolverVersion: 1,
+ values: {
+ "wire.adapter": {
+ source: "lab_forced",
+ value: adapter,
+ },
+ "wire.upstreamProtocol": {
+ source: "lab_forced",
+ value: ctx.upstreamProtocol,
+ },
+ "runtime.arch": {
+ source: "lab_forced",
+ value: process.arch,
+ },
+ "runtime.bunVersion": {
+ source: "lab_forced",
+ value: process.versions.bun ?? Bun.version,
+ },
+ "runtime.platform": {
+ source: "lab_forced",
+ value: process.platform,
+ },
+ },
+ };
+ return createHash("sha256").update(jcsStringify(values)).digest("hex");
+}
+
+function protocolSubject(caseRecord: CaseRecord, result: ScenarioRunResult): ProtocolSubjectV1 {
+ const ctx = validateExecutionContext(
+ caseRecord,
+ result.executionContext ?? resolveProtocolExecutionContext(caseRecord),
+ );
+ return {
+ subjectSchemaVersion: 1,
+ subjectKind: "protocol",
+ opencodexCompatibilityVersion: COMPAT_VERSION,
+ effectiveAdapter: upstreamAdapter(ctx.upstreamProtocol),
+ inboundProtocol: ctx.inboundProtocol,
+ upstreamProtocol: ctx.upstreamProtocol,
+ surface: ctx.surface,
+ behaviorFingerprint: behaviorFingerprintForCase(caseRecord, ctx),
+ };
+}
+
+function upstreamAdapter(protocol: string): string {
+ switch (protocol) {
+ case "openai-responses":
+ return "openai-responses";
+ case "anthropic-messages":
+ return "anthropic";
+ case "openai-chat":
+ return "openai-chat";
+ default:
+ throw new Error(`unsupported protocol identity: ${protocol}`);
+ }
+}
+
+function outcomeFromResult(result: ScenarioRunResult): ObservationOutcome {
+ if (result.passed) return "pass";
+ switch (result.classification) {
+ case "timeout":
+ case "budget_exhausted":
+ return "blocked";
+ case "inconclusive":
+ case "harness_failure":
+ return "inconclusive";
+ case "protocol_failure":
+ case "capability_failure":
+ case "behavioral_failure":
+ return "fail";
+ default: {
+ const _never: never = result.classification;
+ return _never;
+ }
+ }
+}
+
+function requireExecutionTimes(
+ result: ScenarioRunResult,
+ opts: PersistConformanceOptions,
+): { startedAt: number; completedAt: number } {
+ const timed = result as TimedScenarioRunResult;
+ const startedAt = opts.startedAt ?? timed.startedAt;
+ const completedAt = opts.completedAt ?? timed.completedAt;
+ if (!Number.isInteger(startedAt) || !Number.isInteger(completedAt)) {
+ throw new Error("real startedAt/completedAt are required for persisted conformance evidence");
+ }
+ if (startedAt! < 0 || completedAt! < startedAt!) {
+ throw new Error("invalid persisted conformance execution timestamps");
+ }
+ return { startedAt: startedAt!, completedAt: completedAt! };
+}
+
+/**
+ * Build a valid protocol_conformance observation from one CL-01 scenario result.
+ * Does not append; use persistConformanceResult for ledger write.
+ */
+export function observationFromConformanceResult(
+ result: ScenarioRunResult,
+ caseRecord: CaseRecord,
+ authority: CaseAuthority,
+ opts: PersistConformanceOptions = {},
+): { event: ObservationEvent; artifacts: ReturnType[] } {
+ const paths = ensureLabDirs(opts.configDir);
+ const ownsStore = !opts.artifactStore;
+ const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
+ try {
+ const { startedAt, completedAt } = requireExecutionTimes(result, opts);
+ const recordedAt = opts.recordedAt ?? completedAt;
+
+ const expandedScenario = expandScenario(caseRecord, authority);
+ const scenarioDigest = scenarioManifestDigest(expandedScenario);
+ const suiteExpanded = suiteManifestObjectForCase(caseRecord, authority);
+ const suiteDigest = suiteManifestDigest(suiteExpanded);
+
+ const fixtureDigests: string[] = [];
+ const artifacts: ReturnType[] = [];
+
+ const putFixture = (fixture: CaseRecord["fixture"]) => {
+ const bytes = new TextEncoder().encode(fixture.bytesUtf8);
+ const digest = fixtureDigest(bytes);
+ fixtureDigests.push(digest);
+ artifacts.push(
+ store.put({
+ artifactClass: "fixture",
+ payload: bytes,
+ expectedDigest: digest,
+ mediaType: fixture.mediaType,
+ }),
+ );
+ };
+ putFixture(caseRecord.fixture);
+ if (caseRecord.initiatingRequest) putFixture(caseRecord.initiatingRequest);
+
+ artifacts.push(
+ store.put({
+ artifactClass: "scenario_manifest",
+ payload: expandedScenario,
+ expectedDigest: scenarioDigest,
+ }),
+ );
+ artifacts.push(
+ store.put({
+ artifactClass: "suite_manifest",
+ payload: suiteExpanded,
+ expectedDigest: suiteDigest,
+ }),
+ );
+
+ const assertionReport = store.put({
+ artifactClass: "assertion_report",
+ payload: {
+ scenarioId: result.scenarioId,
+ passed: result.passed,
+ classification: result.classification,
+ assertions: result.assertionResults.map((a) => ({
+ id: a.id,
+ operator: a.operator,
+ required: a.required,
+ passed: a.passed,
+ observedSummary: a.observedSummary,
+ reason: a.reason,
+ })),
+ },
+ });
+ artifacts.push(assertionReport);
+
+ const subject = protocolSubject(caseRecord, result);
+ const subjectId = subjectIdForSubject(subject);
+ const outcome = outcomeFromResult(result);
+ const authorityLimits = authority.manifestDefaults.executionLimits;
+
+ const eventWithoutId = {
+ schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+ eventKind: "observation" as const,
+ recordedAt,
+ producer: LAB_PRODUCER,
+ producerVersion: opts.producerVersion ?? LAB_PRODUCER_VERSION,
+ evidenceLayer: "protocol_conformance" as const,
+ scenarioId: caseRecord.id,
+ scenarioVersion: String(authority.manifestDefaults.version),
+ scenarioManifestDigest: scenarioDigest,
+ suiteId: caseRecord.suite,
+ suiteVersion: String(authority.manifestDefaults.suiteVersion),
+ suiteManifestDigest: suiteDigest,
+ fixtureDigests,
+ subject,
+ subjectId,
+ startedAt,
+ completedAt,
+ executionMode: "fixture" as const,
+ attempt: 1,
+ limits: { ...authorityLimits },
+ outcome,
+ assertions: result.assertionResults.map((a) => ({
+ id: a.id,
+ operator: a.operator,
+ required: a.required,
+ passed: a.passed,
+ expectedSummary: "see_assertion_report",
+ observedSummary: a.observedSummary.slice(0, 512),
+ ...(a.reason ? { reason: a.reason } : {}),
+ })),
+ ...(caseRecord.expectedFailure
+ ? { expectedFailure: { ...caseRecord.expectedFailure } }
+ : {}),
+ environment: {
+ runtime: {
+ platform: process.platform,
+ arch: process.arch,
+ bunVersion: process.versions.bun ?? Bun.version,
+ },
+ },
+ artifactRefs: artifacts,
+ ...(result.passed
+ ? {}
+ : {
+ failure: {
+ class: result.classification,
+ code: result.secondaryCode ?? result.classification,
+ retryable: false,
+ attribution:
+ result.classification === "harness_failure"
+ ? ("harness" as const)
+ : ("opencodex" as const),
+ },
+ }),
+ };
+
+ const event = assignEventId(eventWithoutId) as ObservationEvent;
+ return { event, artifacts };
+ } finally {
+ if (ownsStore) store.close();
+ }
+}
+
+/** Transform → validate → append one CL-01 result into the canonical JSONL ledger. */
+export function persistConformanceResult(
+ result: ScenarioRunResult,
+ caseRecord: CaseRecord,
+ authority: CaseAuthority,
+ opts: PersistConformanceOptions = {},
+): PersistedConformanceObservation {
+ const paths = ensureLabDirs(opts.configDir);
+ const ownsStore = !opts.artifactStore;
+ const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
+ try {
+ const { event } = observationFromConformanceResult(result, caseRecord, authority, {
+ ...opts,
+ artifactStore: store,
+ });
+ appendLabEvent(paths.ledgerPath, event);
+ return { event, ledgerPath: paths.ledgerPath };
+ } finally {
+ if (ownsStore) store.close();
+ }
+}
+
+export { behaviorFingerprintForCase };
diff --git a/src/lab/paths.ts b/src/lab/paths.ts
new file mode 100644
index 000000000..d54e11f4d
--- /dev/null
+++ b/src/lab/paths.ts
@@ -0,0 +1,60 @@
+import { chmodSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+
+function ensureRestrictedDir(dir: string): void {
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ if (process.platform === "win32") return;
+ const mode = statSync(dir).mode & 0o777;
+ if (mode !== 0o700) chmodSync(dir, 0o700);
+}
+
+/** Canonical Compatibility Lab state root under the OpenCodex config dir. */
+export function labRoot(configDir = getConfigDir()): string {
+ return join(configDir, "lab");
+}
+
+export function labLedgerPath(configDir = getConfigDir()): string {
+ return join(labRoot(configDir), "compatibility.jsonl");
+}
+
+export function labSqlitePath(configDir = getConfigDir()): string {
+ return join(labRoot(configDir), "compatibility.sqlite");
+}
+
+export function labArtifactsDir(configDir = getConfigDir()): string {
+ return join(labRoot(configDir), "artifacts");
+}
+
+export function labScratchDir(configDir = getConfigDir()): string {
+ return join(labRoot(configDir), "scratch");
+}
+
+export function labExportDir(configDir = getConfigDir()): string {
+ return join(labRoot(configDir), "export");
+}
+
+/** Ensure lab directories exist with restrictive permissions where the platform allows. */
+export function ensureLabDirs(configDir = getConfigDir()): {
+ root: string;
+ ledgerPath: string;
+ sqlitePath: string;
+ artifactsDir: string;
+ scratchDir: string;
+ exportDir: string;
+} {
+ const root = labRoot(configDir);
+ const artifactsDir = labArtifactsDir(configDir);
+ const scratchDir = labScratchDir(configDir);
+ const exportDir = labExportDir(configDir);
+ ensureRestrictedDir(root);
+ ensureRestrictedDir(artifactsDir);
+ return {
+ root,
+ ledgerPath: labLedgerPath(configDir),
+ sqlitePath: labSqlitePath(configDir),
+ artifactsDir,
+ scratchDir,
+ exportDir,
+ };
+}
diff --git a/src/lab/projection/rebuild.ts b/src/lab/projection/rebuild.ts
new file mode 100644
index 000000000..bea548167
--- /dev/null
+++ b/src/lab/projection/rebuild.ts
@@ -0,0 +1,477 @@
+import { Database } from "bun:sqlite";
+import { existsSync, unlinkSync } from "node:fs";
+import { createArtifactStore, loadClaimSourceManifest } from "../artifacts/store";
+import { ArtifactFsError } from "../artifacts/secure-fs";
+import { sanitizeDiagnostic } from "../artifacts/sanitize";
+import { LAB_PROJECTION_SPEC_VERSION } from "../constants";
+import { expandScenario, loadCaseAuthority } from "../conformance/manifest";
+import { scenarioManifestDigest, jcsStringify } from "../digest";
+import {
+ parseSuiteManifestFromArtifact,
+ type ScenarioRequirements,
+} from "./verification";
+import type { ClaimSnapshotEvent, LabEvent, LedgerCorruption } from "../events/types";
+import { buildInvalidationIndex, isEventExcluded } from "../ledger/invalidation";
+import { replayLabLedger } from "../ledger/store";
+import { ensureLabDirs } from "../paths";
+import { LAB_SQLITE_DDL, LAB_SQLITE_SCHEMA_VERSION } from "./schema";
+import {
+ claimKeyString,
+ excludeEventIds,
+ projectVerdicts,
+ projectionKeyString,
+ resolveClaimStates,
+} from "./verdicts";
+
+export interface RebuildResult {
+ events: number;
+ verdicts: number;
+ corruptions: LedgerCorruption[];
+ sqlitePath: string;
+}
+
+function wipeSqlite(path: string): void {
+ for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+ let removed = false;
+ for (let attempt = 0; attempt < 8; attempt++) {
+ try {
+ if (existsSync(candidate)) unlinkSync(candidate);
+ removed = true;
+ break;
+ } catch (err) {
+ const code = err && typeof err === "object" && "code" in err
+ ? String((err as { code: unknown }).code)
+ : "";
+ if (code !== "EBUSY" && code !== "EPERM") throw err;
+ if (attempt < 7) Bun.sleepSync(20 * (attempt + 1));
+ }
+ }
+ if (!removed) {
+ throw new Error(`failed to remove stale projection file after retries: ${candidate}`);
+ }
+ }
+}
+
+function resetProjectionSchema(db: Database): void {
+ db.exec(`
+ DROP TABLE IF EXISTS verdicts;
+ DROP TABLE IF EXISTS corruption;
+ DROP TABLE IF EXISTS artifacts;
+ DROP TABLE IF EXISTS purges;
+ DROP TABLE IF EXISTS invalidations;
+ DROP TABLE IF EXISTS claims;
+ DROP TABLE IF EXISTS observations;
+ DROP TABLE IF EXISTS subjects;
+ DROP TABLE IF EXISTS events;
+ DROP TABLE IF EXISTS schema_meta;
+ `);
+ db.exec(LAB_SQLITE_DDL);
+}
+
+interface ArtifactValidationResult {
+ unusableObservationIds: Set;
+ unusableClaimEventIds: Set
\nCaption text'), false);
assert.equal(isMediaOnly("Some real description."), false);
assert.equal(stripMediaTokens('