@chllming/wave-orchestration 0.6.3 → 0.7.0

package/scripts/wave-orchestrator/artifact-schemas.mjs

@@ -1,20 +1,30 @@
 import { readJsonOrNull, toIsoTimestamp, writeJsonAtomic } from "./shared.mjs";
+import {
+  normalizeWaveControlReportMode,
+  normalizeWaveControlRunKind,
+} from "./wave-control-schema.mjs";
 
 export const MANIFEST_SCHEMA_VERSION = 1;
 export const GLOBAL_DASHBOARD_SCHEMA_VERSION = 1;
 export const WAVE_DASHBOARD_SCHEMA_VERSION = 1;
 export const RELAUNCH_PLAN_SCHEMA_VERSION = 1;
+export const RETRY_OVERRIDE_SCHEMA_VERSION = 1;
 export const ASSIGNMENT_SNAPSHOT_SCHEMA_VERSION = 1;
 export const DEPENDENCY_SNAPSHOT_SCHEMA_VERSION = 1;
+export const PROOF_REGISTRY_SCHEMA_VERSION = 1;
 export const RUN_STATE_SCHEMA_VERSION = 2;
+export const WAVE_CONTROL_DELIVERY_STATE_SCHEMA_VERSION = 1;
 
 export const MANIFEST_KIND = "wave-manifest";
 export const GLOBAL_DASHBOARD_KIND = "global-dashboard";
 export const WAVE_DASHBOARD_KIND = "wave-dashboard";
 export const RELAUNCH_PLAN_KIND = "wave-relaunch-plan";
+export const RETRY_OVERRIDE_KIND = "wave-retry-override";
 export const ASSIGNMENT_SNAPSHOT_KIND = "wave-assignment-snapshot";
 export const DEPENDENCY_SNAPSHOT_KIND = "wave-dependency-snapshot";
+export const PROOF_REGISTRY_KIND = "wave-proof-registry";
 export const RUN_STATE_KIND = "wave-run-state";
+export const WAVE_CONTROL_DELIVERY_STATE_KIND = "wave-control-delivery-state";
 
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -25,6 +35,11 @@ function normalizeInteger(value, fallback = null) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function normalizeNonNegativeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
 function normalizeText(value, fallback = null) {
   const normalized = String(value ?? "").trim();
   return normalized || fallback;
@@ -34,6 +49,19 @@ function cloneJson(value) {
   return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
 }
 
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      values
+        .map((value) => normalizeText(value, null))
+        .filter(Boolean),
+    ),
+  );
+}
+
 export function normalizeManifest(payload) {
   const source = isPlainObject(payload) ? payload : {};
   return {
@@ -94,6 +122,42 @@ export function writeRelaunchPlan(filePath, payload, defaults = {}) {
   return normalized;
 }
 
+export function normalizeRetryOverride(payload, defaults = {}) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: RETRY_OVERRIDE_SCHEMA_VERSION,
+    kind: RETRY_OVERRIDE_KIND,
+    lane: normalizeText(source.lane, normalizeText(defaults.lane, null)),
+    wave: normalizeInteger(source.wave, normalizeInteger(defaults.wave, null)),
+    selectedAgentIds: normalizeStringArray(source.selectedAgentIds),
+    reuseAttemptIds: normalizeStringArray(source.reuseAttemptIds),
+    reuseProofBundleIds: normalizeStringArray(source.reuseProofBundleIds),
+    reuseDerivedSummaries: source.reuseDerivedSummaries !== false,
+    invalidateComponentIds: normalizeStringArray(source.invalidateComponentIds),
+    clearReusableAgentIds: normalizeStringArray(source.clearReusableAgentIds),
+    preserveReusableAgentIds: normalizeStringArray(source.preserveReusableAgentIds),
+    resumePhase: normalizeText(source.resumePhase, null),
+    requestedBy: normalizeText(source.requestedBy, normalizeText(defaults.requestedBy, null)),
+    reason: normalizeText(source.reason, null),
+    applyOnce: source.applyOnce !== false,
+    createdAt: normalizeText(source.createdAt, toIsoTimestamp()),
+  };
+}
+
+export function readRetryOverride(filePath, defaults = {}) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    return null;
+  }
+  return normalizeRetryOverride(payload, defaults);
+}
+
+export function writeRetryOverride(filePath, payload, defaults = {}) {
+  const normalized = normalizeRetryOverride(payload, defaults);
+  writeJsonAtomic(filePath, normalized);
+  return normalized;
+}
+
 export function normalizeAssignmentSnapshot(payload, defaults = {}) {
   if (Array.isArray(payload)) {
     return {
@@ -168,6 +232,174 @@ export function writeDependencySnapshot(filePath, payload, defaults = {}) {
   return normalized;
 }
 
+function normalizeProofArtifactEntry(entry) {
+  const source = isPlainObject(entry) ? entry : {};
+  return {
+    path: normalizeText(source.path, null),
+    kind: normalizeText(source.kind, null),
+    requiredFor: normalizeStringArray(source.requiredFor),
+    exists: source.exists === true,
+    sha256: normalizeText(source.sha256, null),
+  };
+}
+
+function normalizeProofComponentEntry(entry) {
+  const source = isPlainObject(entry) ? entry : {};
+  return {
+    componentId: normalizeText(source.componentId, null),
+    level: normalizeText(source.level, null),
+    state: normalizeText(source.state, null),
+    detail: normalizeText(source.detail, null),
+  };
+}
+
+function normalizeProofSummaryEntry(entry) {
+  const source = isPlainObject(entry) ? entry : {};
+  const state = normalizeText(source.state, null);
+  const completion = normalizeText(source.completion, null);
+  const durability = normalizeText(source.durability, null);
+  const proof = normalizeText(source.proof, null);
+  if (!state && !completion && !durability && !proof) {
+    return null;
+  }
+  return {
+    state,
+    completion,
+    durability,
+    proof,
+    detail: normalizeText(source.detail, null),
+  };
+}
+
+function normalizeDocDeltaEntry(entry) {
+  const source = isPlainObject(entry) ? entry : {};
+  const state = normalizeText(source.state, null);
+  if (!state) {
+    return null;
+  }
+  return {
+    state,
+    detail: normalizeText(source.detail, null),
+  };
+}
+
+function normalizeProofRegistryEntry(entry) {
+  const source = isPlainObject(entry) ? entry : {};
+  return {
+    id: normalizeText(source.id, null),
+    agentId: normalizeText(source.agentId, null),
+    state: normalizeText(source.state, null),
+    authoritative: source.authoritative === true,
+    recordedAt: normalizeText(source.recordedAt, toIsoTimestamp()),
+    recordedBy: normalizeText(source.recordedBy, null),
+    detail: normalizeText(source.detail, null),
+    summary: normalizeText(source.summary, null),
+    satisfyOwnedComponents: source.satisfyOwnedComponents === true,
+    proof: normalizeProofSummaryEntry(source.proof),
+    docDelta: normalizeDocDeltaEntry(source.docDelta),
+    components: (Array.isArray(source.components) ? source.components : [])
+      .map((item) => normalizeProofComponentEntry(item))
+      .filter((item) => item.componentId),
+    artifacts: (Array.isArray(source.artifacts) ? source.artifacts : [])
+      .map((item) => normalizeProofArtifactEntry(item))
+      .filter((item) => item.path),
+    scope: normalizeText(source.scope, null),
+    attestation: isPlainObject(source.attestation) ? cloneJson(source.attestation) : null,
+    satisfies: normalizeStringArray(source.satisfies),
+    supersedes: normalizeText(source.supersedes, null),
+    supersededBy: normalizeText(source.supersededBy, null),
+  };
+}
+
+export function normalizeProofRegistry(payload, defaults = {}) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: PROOF_REGISTRY_SCHEMA_VERSION,
+    kind: PROOF_REGISTRY_KIND,
+    lane: normalizeText(source.lane, normalizeText(defaults.lane, null)),
+    wave: normalizeInteger(source.wave, normalizeInteger(defaults.wave, null)),
+    updatedAt: normalizeText(source.updatedAt, toIsoTimestamp()),
+    entries: (Array.isArray(source.entries) ? source.entries : [])
+      .map((entry) => normalizeProofRegistryEntry(entry))
+      .filter((entry) => entry.id && entry.agentId),
+  };
+}
+
+export function readProofRegistry(filePath, defaults = {}) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    return null;
+  }
+  return normalizeProofRegistry(payload, defaults);
+}
+
+export function writeProofRegistry(filePath, payload, defaults = {}) {
+  const normalized = normalizeProofRegistry(payload, defaults);
+  writeJsonAtomic(filePath, normalized);
+  return normalized;
+}
+
+export function normalizeWaveControlDeliveryState(payload, defaults = {}) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: WAVE_CONTROL_DELIVERY_STATE_SCHEMA_VERSION,
+    kind: WAVE_CONTROL_DELIVERY_STATE_KIND,
+    workspaceId: normalizeText(source.workspaceId, normalizeText(defaults.workspaceId, null)),
+    lane: normalizeText(source.lane, normalizeText(defaults.lane, null)),
+    runId: normalizeText(source.runId, normalizeText(defaults.runId, null)),
+    runKind: normalizeWaveControlRunKind(
+      source.runKind,
+      "waveControlDeliveryState.runKind",
+      normalizeText(defaults.runKind, "unknown"),
+    ),
+    reportMode: normalizeWaveControlReportMode(
+      source.reportMode,
+      "waveControlDeliveryState.reportMode",
+      normalizeText(defaults.reportMode, "metadata-plus-selected"),
+    ),
+    endpoint: normalizeText(source.endpoint, normalizeText(defaults.endpoint, null)),
+    queuePath: normalizeText(source.queuePath, normalizeText(defaults.queuePath, null)),
+    eventsPath: normalizeText(source.eventsPath, normalizeText(defaults.eventsPath, null)),
+    pendingCount: normalizeNonNegativeInteger(
+      source.pendingCount,
+      normalizeNonNegativeInteger(defaults.pendingCount, 0),
+    ),
+    sentCount: normalizeNonNegativeInteger(
+      source.sentCount,
+      normalizeNonNegativeInteger(defaults.sentCount, 0),
+    ),
+    failedCount: normalizeNonNegativeInteger(
+      source.failedCount,
+      normalizeNonNegativeInteger(defaults.failedCount, 0),
+    ),
+    lastEnqueuedAt: normalizeText(source.lastEnqueuedAt, normalizeText(defaults.lastEnqueuedAt, null)),
+    lastFlushAt: normalizeText(source.lastFlushAt, normalizeText(defaults.lastFlushAt, null)),
+    lastSuccessAt: normalizeText(source.lastSuccessAt, normalizeText(defaults.lastSuccessAt, null)),
+    lastError:
+      source.lastError === undefined
+        ? defaults.lastError ?? null
+        : isPlainObject(source.lastError)
+          ? source.lastError
+          : normalizeText(source.lastError, null),
+    recentEventIds: normalizeStringArray(source.recentEventIds ?? defaults.recentEventIds),
+    updatedAt: normalizeText(source.updatedAt, normalizeText(defaults.updatedAt, toIsoTimestamp())),
+  };
+}
+
+export function readWaveControlDeliveryState(filePath, defaults = {}) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    return null;
+  }
+  return normalizeWaveControlDeliveryState(payload, defaults);
+}
+
+export function writeWaveControlDeliveryState(filePath, payload, defaults = {}) {
+  const normalized = normalizeWaveControlDeliveryState(payload, defaults);
+  writeJsonAtomic(filePath, normalized);
+  return normalized;
+}
+
 export function cloneArtifactPayload(value) {
   return cloneJson(value);
 }

package/scripts/wave-orchestrator/autonomous.mjs

@@ -45,6 +45,7 @@ Options:
                                 Max backoff delay for 429 retries (default: ${DEFAULT_AGENT_RATE_LIMIT_MAX_DELAY_SECONDS})
   --agent-launch-stagger-ms <n> Delay between agent launches (default: ${DEFAULT_AGENT_LAUNCH_STAGGER_MS})
   --orchestrator-id <id>        Orchestrator ID for coordination board
+  --resident-orchestrator       Launch a resident orchestrator session for each live wave
   --executor <mode>             Default executor passed to launcher: ${SUPPORTED_EXECUTOR_MODES.join(" | ")} (default: lane config)
   --codex-sandbox <mode>        Default Codex sandbox mode passed to launcher (default: ${DEFAULT_CODEX_SANDBOX_MODE})
   --dashboard                   Enable dashboards (default: disabled)
@@ -64,6 +65,7 @@ export function parseArgs(argv) {
     agentRateLimitMaxDelaySeconds: DEFAULT_AGENT_RATE_LIMIT_MAX_DELAY_SECONDS,
     agentLaunchStaggerMs: DEFAULT_AGENT_LAUNCH_STAGGER_MS,
     orchestratorId: null,
+    residentOrchestrator: false,
     executorMode: DEFAULT_EXECUTOR_MODE,
     codexSandboxMode: DEFAULT_CODEX_SANDBOX_MODE,
     noDashboard: true,
@@ -103,6 +105,8 @@ export function parseArgs(argv) {
       options.agentLaunchStaggerMs = parseNonNegativeInt(argv[++i], "--agent-launch-stagger-ms");
     } else if (arg === "--orchestrator-id") {
       options.orchestratorId = String(argv[++i] || "").trim();
+    } else if (arg === "--resident-orchestrator") {
+      options.residentOrchestrator = true;
     } else if (arg === "--executor") {
       options.executorMode = normalizeExecutorMode(argv[++i], "--executor");
       executorProvided = true;
@@ -228,6 +232,9 @@ function launchSingleWave(params) {
   if (params.keepTerminals) {
     args.push("--keep-terminals");
   }
+  if (params.residentOrchestrator) {
+    args.push("--resident-orchestrator");
+  }
   return runCommand(args, { [WAVE_SUPPRESS_UPDATE_NOTICE_ENV]: "1" });
 }
 

package/scripts/wave-orchestrator/benchmark-cases.mjs

@@ -0,0 +1,374 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  materializeCoordinationState,
+  normalizeCoordinationRecord,
+} from "./coordination-store.mjs";
+import { loadBenchmarkCatalog } from "./evals.mjs";
+import { REPO_ROOT, readJsonOrNull } from "./shared.mjs";
+
+const DEFAULT_BENCHMARK_CASES_DIR = "docs/evals/cases";
+const DEFAULT_EXTERNAL_BENCHMARKS_PATH = "docs/evals/external-benchmarks.json";
+const SUPPORTED_CASE_KINDS = new Set(["projection"]);
+const SUPPORTED_CASE_ARMS = new Set([
+  "single-agent",
+  "multi-agent-minimal",
+  "full-wave",
+  "full-wave-plus-improvement",
+]);
+
+function cleanText(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizeRepoRelativePath(value, label) {
+  const normalized = cleanText(value)
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "");
+  if (!normalized) {
+    throw new Error(`${label} is required`);
+  }
+  if (normalized.startsWith("/") || normalized.startsWith("../") || normalized.includes("/../")) {
+    throw new Error(`${label} must stay within the repository`);
+  }
+  return normalized;
+}
+
+function normalizeId(value, label) {
+  const normalized = cleanText(value).toLowerCase();
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) {
+    throw new Error(`${label} must match /^[a-z0-9][a-z0-9._-]*$/`);
+  }
+  return normalized;
+}
+
+function normalizeStringArray(value, label) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return value.map((entry, index) => cleanText(entry)).map((entry, index) => {
+    if (!entry) {
+      throw new Error(`${label}[${index}] must be a non-empty string`);
+    }
+    return entry;
+  });
+}
+
+function normalizeIdArray(value, label, { allowEmpty = true } = {}) {
+  const ids = normalizeStringArray(value, label).map((entry, index) =>
+    normalizeId(entry, `${label}[${index}]`),
+  );
+  if (!allowEmpty && ids.length === 0) {
+    throw new Error(`${label} must not be empty`);
+  }
+  return Array.from(new Set(ids));
+}
+
+function normalizeAgent(rawAgent, index) {
+  if (!rawAgent || typeof rawAgent !== "object" || Array.isArray(rawAgent)) {
+    throw new Error(`fixture.agents[${index}] must be an object`);
+  }
+  const agentId = normalizeId(rawAgent.agentId, `fixture.agents[${index}].agentId`);
+  return {
+    agentId,
+    title: cleanText(rawAgent.title) || agentId,
+    ownedPaths: normalizeStringArray(rawAgent.ownedPaths, `fixture.agents[${index}].ownedPaths`),
+    capabilities: normalizeIdArray(
+      rawAgent.capabilities,
+      `fixture.agents[${index}].capabilities`,
+    ),
+  };
+}
+
+function normalizeAssignments(value, label) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${label}[${index}] must be an object`);
+    }
+    return {
+      requestId: normalizeId(entry.requestId, `${label}[${index}].requestId`),
+      assignedAgentId: normalizeId(entry.assignedAgentId, `${label}[${index}].assignedAgentId`),
+    };
+  });
+}
+
+function normalizeTargetedInboxes(value, label) {
+  if (value == null) {
+    return {};
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([agentId, facts]) => [
+      normalizeId(agentId, `${label}.${agentId}`),
+      normalizeStringArray(facts, `${label}.${agentId}`),
+    ]),
+  );
+}
+
+function normalizeExpectations(rawExpectations = {}) {
+  if (!rawExpectations || typeof rawExpectations !== "object" || Array.isArray(rawExpectations)) {
+    throw new Error("expectations must be an object");
+  }
+  return {
+    globalFacts: normalizeStringArray(rawExpectations.globalFacts, "expectations.globalFacts"),
+    summaryFacts: normalizeStringArray(rawExpectations.summaryFacts, "expectations.summaryFacts"),
+    targetedInboxes: normalizeTargetedInboxes(
+      rawExpectations.targetedInboxes,
+      "expectations.targetedInboxes",
+    ),
+    requiredAssignments: normalizeAssignments(
+      rawExpectations.requiredAssignments,
+      "expectations.requiredAssignments",
+    ),
+    clarificationRequestIds: normalizeIdArray(
+      rawExpectations.clarificationRequestIds,
+      "expectations.clarificationRequestIds",
+    ),
+    minimumDistinctAssignedAgents:
+      rawExpectations.minimumDistinctAssignedAgents == null
+        ? null
+        : Number.parseInt(String(rawExpectations.minimumDistinctAssignedAgents), 10),
+    requireBlockingGuard:
+      rawExpectations.requireBlockingGuard === undefined
+        ? false
+        : Boolean(rawExpectations.requireBlockingGuard),
+  };
+}
+
+function normalizeThresholds(rawThresholds = {}) {
+  if (!rawThresholds || typeof rawThresholds !== "object" || Array.isArray(rawThresholds)) {
+    throw new Error("scoring.thresholds must be an object");
+  }
+  const normalized = {};
+  for (const [key, value] of Object.entries(rawThresholds)) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      throw new Error(`scoring.thresholds.${key} must be numeric`);
+    }
+    normalized[key] = parsed;
+  }
+  return normalized;
+}
+
+function normalizeScoring(rawScoring = {}) {
+  if (!rawScoring || typeof rawScoring !== "object" || Array.isArray(rawScoring)) {
+    throw new Error("scoring must be an object");
+  }
+  const kind = normalizeId(rawScoring.kind, "scoring.kind");
+  return {
+    kind,
+    primaryMetric: normalizeId(rawScoring.primaryMetric, "scoring.primaryMetric"),
+    thresholds: normalizeThresholds(rawScoring.thresholds || {}),
+    practicalWinThreshold:
+      rawScoring.practicalWinThreshold == null
+        ? 5
+        : Number.parseFloat(String(rawScoring.practicalWinThreshold)),
+  };
+}
+
+function normalizeCapabilityRouting(value) {
+  if (value == null) {
+    return { preferredAgents: {} };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("fixture.capabilityRouting must be an object");
+  }
+  const preferredAgents =
+    value.preferredAgents && typeof value.preferredAgents === "object" && !Array.isArray(value.preferredAgents)
+      ? value.preferredAgents
+      : {};
+  return {
+    preferredAgents: Object.fromEntries(
+      Object.entries(preferredAgents).map(([capability, agents]) => [
+        normalizeId(capability, `fixture.capabilityRouting.preferredAgents.${capability}`),
+        normalizeIdArray(
+          agents,
+          `fixture.capabilityRouting.preferredAgents.${capability}`,
+        ),
+      ]),
+    ),
+  };
+}
+
+function normalizeBenchmarkCase(rawCase, filePath, catalog) {
+  if (!rawCase || typeof rawCase !== "object" || Array.isArray(rawCase)) {
+    throw new Error(`Benchmark case must be an object: ${filePath}`);
+  }
+  const id = normalizeId(rawCase.id, `${filePath}: id`);
+  const familyId = normalizeId(rawCase.familyId, `${filePath}: familyId`);
+  const benchmarkId = normalizeId(rawCase.benchmarkId, `${filePath}: benchmarkId`);
+  const family = catalog.families[familyId];
+  if (!family) {
+    throw new Error(`${filePath}: unknown benchmark family "${familyId}"`);
+  }
+  const benchmark = family.benchmarks[benchmarkId];
+  if (!benchmark) {
+    throw new Error(`${filePath}: unknown benchmark "${benchmarkId}" for family "${familyId}"`);
+  }
+  const catalogLocalCases = Array.from(
+    new Set([...(family.localCases || []), ...(benchmark.localCases || [])]),
+  );
+  if (catalogLocalCases.length > 0 && !catalogLocalCases.includes(id)) {
+    throw new Error(
+      `${filePath}: case "${id}" is not registered in ${catalog.path} for ${familyId}/${benchmarkId}`,
+    );
+  }
+  const kind = normalizeId(rawCase.kind || "projection", `${filePath}: kind`);
+  if (!SUPPORTED_CASE_KINDS.has(kind)) {
+    throw new Error(`${filePath}: unsupported case kind "${kind}"`);
+  }
+  const fixture = rawCase.fixture;
+  if (!fixture || typeof fixture !== "object" || Array.isArray(fixture)) {
+    throw new Error(`${filePath}: fixture must be an object`);
+  }
+  const agents = Array.isArray(fixture.agents)
+    ? fixture.agents.map((agent, index) => normalizeAgent(agent, index))
+    : [];
+  if (agents.length === 0) {
+    throw new Error(`${filePath}: fixture.agents must define at least one agent`);
+  }
+  const primaryAgentId = normalizeId(
+    fixture.primaryAgentId || agents[0].agentId,
+    `${filePath}: fixture.primaryAgentId`,
+  );
+  if (!agents.some((agent) => agent.agentId === primaryAgentId)) {
+    throw new Error(`${filePath}: fixture.primaryAgentId must match one of fixture.agents`);
+  }
+  const supportedArms = normalizeIdArray(
+    rawCase.supportedArms || ["single-agent", "multi-agent-minimal", "full-wave"],
+    `${filePath}: supportedArms`,
+    { allowEmpty: false },
+  );
+  for (const arm of supportedArms) {
+    if (!SUPPORTED_CASE_ARMS.has(arm)) {
+      throw new Error(`${filePath}: unsupported benchmark arm "${arm}"`);
+    }
+  }
+  const records = Array.isArray(fixture.records)
+    ? fixture.records.map((record, index) =>
+        normalizeCoordinationRecord(record, {
+          lane: cleanText(fixture.lane) || "main",
+          wave:
+            fixture.waveNumber == null ? 0 : Number.parseInt(String(fixture.waveNumber), 10),
+          source: "benchmark-case",
+        }),
+      )
+    : [];
+  if (records.length === 0) {
+    throw new Error(`${filePath}: fixture.records must define at least one coordination record`);
+  }
+  return {
+    id,
+    version: Number.parseInt(String(rawCase.version ?? "1"), 10) || 1,
+    path: path.relative(REPO_ROOT, filePath).replaceAll(path.sep, "/"),
+    title: cleanText(rawCase.title) || id,
+    summary: cleanText(rawCase.summary) || null,
+    tags: normalizeIdArray(rawCase.tags, `${filePath}: tags`),
+    kind,
+    familyId,
+    benchmarkId,
+    familyTitle: family.title,
+    benchmarkTitle: benchmark.title,
+    supportedArms,
+    scoring: normalizeScoring(rawCase.scoring),
+    expectations: normalizeExpectations(rawCase.expectations),
+    fixture: {
+      lane: cleanText(fixture.lane) || "main",
+      waveNumber:
+        fixture.waveNumber == null ? 0 : Number.parseInt(String(fixture.waveNumber), 10),
+      primaryAgentId,
+      capabilityRouting: normalizeCapabilityRouting(fixture.capabilityRouting),
+      agents,
+      records,
+      state: materializeCoordinationState(records),
+    },
+  };
+}
+
+function readJsonFile(filePath) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    throw new Error(`Invalid JSON file: ${path.relative(REPO_ROOT, filePath)}`);
+  }
+  return payload;
+}
+
+export function loadBenchmarkCases(options = {}) {
+  const casesDir = path.resolve(
+    REPO_ROOT,
+    normalizeRepoRelativePath(options.casesDir || DEFAULT_BENCHMARK_CASES_DIR, "casesDir"),
+  );
+  if (!fs.existsSync(casesDir)) {
+    throw new Error(`Benchmark cases directory does not exist: ${path.relative(REPO_ROOT, casesDir)}`);
+  }
+  const catalog = loadBenchmarkCatalog(options);
+  const files = fs
+    .readdirSync(casesDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => path.join(casesDir, entry.name))
+    .toSorted();
+  const seen = new Set();
+  const cases = files.map((filePath) => {
+    const benchmarkCase = normalizeBenchmarkCase(readJsonFile(filePath), filePath, catalog);
+    if (seen.has(benchmarkCase.id)) {
+      throw new Error(`Duplicate benchmark case id "${benchmarkCase.id}"`);
+    }
+    seen.add(benchmarkCase.id);
+    return benchmarkCase;
+  });
+  return {
+    casesDir: path.relative(REPO_ROOT, casesDir).replaceAll(path.sep, "/"),
+    absoluteCasesDir: casesDir,
+    catalog,
+    cases,
+    byId: new Map(cases.map((benchmarkCase) => [benchmarkCase.id, benchmarkCase])),
+  };
+}
+
+export function loadExternalBenchmarkAdapters(options = {}) {
+  const registryPath = path.resolve(
+    REPO_ROOT,
+    normalizeRepoRelativePath(
+      options.externalBenchmarksPath || DEFAULT_EXTERNAL_BENCHMARKS_PATH,
+      "externalBenchmarksPath",
+    ),
+  );
+  const payload = readJsonFile(registryPath);
+  const adapters = Array.isArray(payload.adapters) ? payload.adapters : [];
+  return {
+    path: path.relative(REPO_ROOT, registryPath).replaceAll(path.sep, "/"),
+    version: Number.parseInt(String(payload.version ?? "1"), 10) || 1,
+    adapters: adapters.map((adapter, index) => {
+      if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) {
+        throw new Error(`adapters[${index}] in ${registryPath} must be an object`);
+      }
+      return {
+        id: normalizeId(adapter.id, `adapters[${index}].id`),
+        title: cleanText(adapter.title) || normalizeId(adapter.id, `adapters[${index}].id`),
+        mode: cleanText(adapter.mode) || "adapted",
+        sourceBenchmark: cleanText(adapter.sourceBenchmark) || null,
+        split: cleanText(adapter.split) || null,
+        pilotManifestPath: cleanText(adapter.pilotManifestPath) || null,
+        officialDocsUrl: cleanText(adapter.officialDocsUrl) || null,
+        officialCodeUrl: cleanText(adapter.officialCodeUrl) || null,
+        summary: cleanText(adapter.summary) || null,
+        commandTemplate: cleanText(adapter.commandTemplate) || null,
+        metrics: normalizeStringArray(adapter.metrics, `adapters[${index}].metrics`),
+        notes: normalizeStringArray(adapter.notes, `adapters[${index}].notes`),
+      };
+    }),
+  };
+}