opencode-swarm 7.136.1 → 7.136.2

package/dist/cli/index-z1tm47nj.js

@@ -0,0 +1,783 @@
+// @bun
+import {
+  canonicalJson,
+  computeRunIntegrityHash,
+  computeTaskInputContentHash,
+  computeTaskLineageInputHash,
+  computeTaskSetContentHash,
+  resolveContainedExistingPath
+} from "./index-y8552snf.js";
+import {
+  atomicWriteFile
+} from "./index-ey29aap6.js";
+import {
+  withEvidenceLock
+} from "./index-09b9zncg.js";
+import {
+  exports_external,
+  init_zod
+} from "./index-bpmtbmy9.js";
+
+// src/evaluation/contracts.ts
+init_zod();
+var IdentifierSchema = exports_external.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+var Sha256Schema = exports_external.string().regex(/^[a-f0-9]{64}$/);
+var IsoDateSchema = exports_external.iso.datetime({ offset: true });
+var RelativePathSchema = exports_external.string().min(1).max(1024).refine((value) => !value.includes("\x00"), "path contains a NUL byte").refine((value) => !/^(?:[A-Za-z]:[\\/]|[\\/]{1,2})/.test(value), {
+  message: "path must be project-relative"
+}).refine((value) => !value.replace(/\\/g, "/").split("/").some((segment) => segment === ".."), "path must not traverse outside its root");
+var EvaluationSplitSchema = exports_external.enum(["train", "validation", "test"]);
+var CostRecordSchema = exports_external.object({
+  source: exports_external.enum(["reported", "estimated", "unavailable"]),
+  usd: exports_external.number().finite().nonnegative().optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.source === "unavailable" && value.usd !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["usd"],
+      message: "unavailable costs cannot declare a USD value"
+    });
+  }
+  if (value.source !== "unavailable" && value.usd === undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["usd"],
+      message: "reported and estimated costs require a USD value"
+    });
+  }
+});
+var HumanReviewReceiptSchema = exports_external.object({
+  reviewer: exports_external.string().min(1).max(200),
+  reviewedAt: IsoDateSchema,
+  instruction: exports_external.literal(true),
+  fixture: exports_external.literal(true),
+  scorer: exports_external.literal(true),
+  secretsPrivacy: exports_external.literal(true),
+  license: exports_external.literal(true),
+  split: exports_external.literal(true)
+}).strict();
+var EvaluationTaskV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  id: IdentifierSchema,
+  derivedFromTaskId: IdentifierSchema.optional(),
+  source: exports_external.enum(["curated", "trace-proposal"]),
+  split: EvaluationSplitSchema,
+  category: IdentifierSchema,
+  protected: exports_external.boolean().default(false),
+  instructionPath: RelativePathSchema,
+  environment: exports_external.discriminatedUnion("kind", [
+    exports_external.object({ kind: exports_external.literal("fixture"), path: RelativePathSchema }).strict(),
+    exports_external.object({ kind: exports_external.literal("container"), path: RelativePathSchema }).strict()
+  ]),
+  scorer: exports_external.object({
+    kind: exports_external.enum(["builtin", "project"]),
+    argv: exports_external.array(exports_external.string().min(1).max(4096)).min(1).max(64),
+    timeoutMs: exports_external.number().int().min(100).max(600000),
+    scoreRange: exports_external.tuple([exports_external.number().finite(), exports_external.number().finite()]).refine(([minimum, maximum]) => maximum > minimum, {
+      message: "score range maximum must be greater than minimum"
+    })
+  }).strict(),
+  provenance: exports_external.object({
+    origin: exports_external.string().min(1).max(2048),
+    license: exports_external.string().min(1).max(200),
+    collectedAt: IsoDateSchema.optional(),
+    review: HumanReviewReceiptSchema.optional()
+  }).strict(),
+  contentHash: Sha256Schema
+}).strict().superRefine((task, ctx) => {
+  if (task.derivedFromTaskId === task.id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["derivedFromTaskId"],
+      message: "a derived task must reference a different parent task"
+    });
+  }
+  if (task.source === "trace-proposal" && !task.provenance.review) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["provenance", "review"],
+      message: "trace-derived tasks require an explicit human review receipt"
+    });
+  }
+  if (task.scorer.kind === "project" && !RelativePathSchema.safeParse(task.scorer.argv[0]).success) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["scorer", "argv", 0],
+      message: "project scorer executable must be project-relative"
+    });
+  }
+});
+var EvaluationCandidateV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  id: IdentifierSchema,
+  kind: exports_external.enum(["baseline", "skill", "harness"]),
+  payloadPath: RelativePathSchema,
+  model: exports_external.string().min(1).max(300),
+  agent: exports_external.string().min(1).max(160).optional(),
+  contentHash: Sha256Schema
+}).strict();
+var EvaluationOutcomeSchema = exports_external.enum([
+  "scored",
+  "infrastructure_failure",
+  "timeout",
+  "cancelled",
+  "malformed",
+  "unsupported",
+  "integrity_failure"
+]);
+var EvaluationResultV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  taskId: IdentifierSchema,
+  category: IdentifierSchema,
+  protected: exports_external.boolean().default(false),
+  repetition: exports_external.number().int().nonnegative(),
+  candidateId: IdentifierSchema,
+  seed: exports_external.string().min(1).max(500),
+  outcome: EvaluationOutcomeSchema,
+  score: exports_external.number().finite().optional(),
+  scoreRange: exports_external.tuple([exports_external.number().finite(), exports_external.number().finite()]),
+  cost: CostRecordSchema,
+  durationMs: exports_external.number().int().nonnegative(),
+  retries: exports_external.number().int().nonnegative().default(0),
+  failureCode: exports_external.string().min(1).max(160).optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+}).strict().superRefine((result, ctx) => {
+  const [minimum, maximum] = result.scoreRange;
+  if (maximum <= minimum) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["scoreRange"],
+      message: "score range maximum must be greater than minimum"
+    });
+  }
+  if (result.outcome === "scored") {
+    if (result.score === undefined || result.score < minimum || result.score > maximum) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["score"],
+        message: "scored outcomes require an in-range score"
+      });
+    }
+  } else if (result.score !== undefined) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["score"],
+      message: "non-score outcomes must not be imputed with a score"
+    });
+  }
+});
+var EvaluationBudgetsV1Schema = exports_external.object({
+  maxTasks: exports_external.number().int().positive(),
+  maxRepetitions: exports_external.number().int().positive(),
+  maxConcurrency: exports_external.number().int().positive(),
+  maxTaskTimeMs: exports_external.number().int().positive(),
+  maxRetries: exports_external.number().int().nonnegative(),
+  maxOutputBytes: exports_external.number().int().positive(),
+  maxSpendUsd: exports_external.number().finite().nonnegative().optional()
+}).strict();
+var EnvironmentFingerprintV1Schema = exports_external.object({
+  platform: exports_external.string().min(1),
+  arch: exports_external.string().min(1),
+  runtime: exports_external.string().min(1),
+  baseSha: exports_external.string().regex(/^[a-f0-9]{40,64}$/),
+  activeTreeHash: Sha256Schema,
+  taskSetHash: Sha256Schema
+}).strict();
+var EvaluationRunV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  runId: IdentifierSchema,
+  createdAt: IsoDateSchema,
+  status: exports_external.enum(["complete", "inconclusive", "cancelled"]),
+  baseline: EvaluationCandidateV1Schema,
+  candidate: EvaluationCandidateV1Schema,
+  taskSet: exports_external.object({
+    id: IdentifierSchema,
+    contentHash: Sha256Schema,
+    taskIds: exports_external.array(IdentifierSchema).min(1)
+  }).strict(),
+  split: EvaluationSplitSchema,
+  seed: exports_external.string().min(1).max(500),
+  models: exports_external.array(exports_external.string().min(1).max(300)).min(1),
+  environment: EnvironmentFingerprintV1Schema,
+  budgets: EvaluationBudgetsV1Schema,
+  results: exports_external.array(EvaluationResultV1Schema),
+  cost: CostRecordSchema,
+  integrityHash: Sha256Schema
+}).strict().superRefine((run, ctx) => {
+  if (run.environment.taskSetHash !== run.taskSet.contentHash) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["environment", "taskSetHash"],
+      message: "environment and task-set hashes must agree"
+    });
+  }
+  const allowed = new Set([run.baseline.id, run.candidate.id]);
+  if (allowed.size !== 2) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["candidate", "id"],
+      message: "baseline and candidate ids must differ"
+    });
+  }
+  if (run.results.some((result) => !allowed.has(result.candidateId))) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["results"],
+      message: "results may only reference the declared baseline and candidate"
+    });
+  }
+  const taskIds = new Set(run.taskSet.taskIds);
+  if (run.results.some((result) => !taskIds.has(result.taskId))) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["results"],
+      message: "results may only reference tasks in the frozen task set"
+    });
+  }
+  const resultKeys = run.results.map((result) => `${result.candidateId}\x00${result.taskId}\x00${result.repetition}`);
+  if (new Set(resultKeys).size !== resultKeys.length) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["results"],
+      message: "run contains duplicate candidate/task/repetition results"
+    });
+  }
+  if (run.results.some((result) => result.repetition >= run.budgets.maxRepetitions)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["results"],
+      message: "result repetition exceeds the declared run budget"
+    });
+  }
+});
+var PromotionPolicyV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  minValidPairs: exports_external.number().int().positive().default(6),
+  minCoverage: exports_external.number().min(0).max(1).default(0.8),
+  deadband: exports_external.number().min(0).max(1).default(0),
+  confidence: exports_external.literal(0.95).default(0.95),
+  bootstrapResamples: exports_external.literal(1e4).default(1e4),
+  requireAvailableCosts: exports_external.boolean().default(true),
+  protectedCategoryTolerances: exports_external.record(exports_external.string(), exports_external.number().min(0).max(1)).default({})
+}).strict();
+var PromotionComparisonSchema = exports_external.object({
+  baselineRunId: IdentifierSchema,
+  baselineCandidateId: IdentifierSchema,
+  baselineMean: exports_external.number().min(0).max(1),
+  candidateMean: exports_external.number().min(0).max(1),
+  pairedDelta: exports_external.number().min(-1).max(1),
+  confidenceInterval: exports_external.tuple([
+    exports_external.number().min(-1).max(1),
+    exports_external.number().min(-1).max(1)
+  ]),
+  validPairs: exports_external.number().int().nonnegative(),
+  missingPairs: exports_external.number().int().nonnegative(),
+  coverage: exports_external.number().min(0).max(1)
+}).strict();
+var PromotionDecisionV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  decisionId: IdentifierSchema,
+  runId: IdentifierSchema,
+  decidedAt: IsoDateSchema,
+  status: exports_external.enum(["accept", "reject", "inconclusive"]),
+  reasons: exports_external.array(exports_external.string().min(1).max(300)),
+  baseline: PromotionComparisonSchema,
+  historicalBest: PromotionComparisonSchema,
+  deadband: exports_external.number().min(0).max(1),
+  bootstrap: exports_external.object({
+    resamples: exports_external.literal(1e4),
+    confidence: exports_external.literal(0.95),
+    seedHash: Sha256Schema
+  }).strict(),
+  categories: exports_external.array(exports_external.object({
+    category: IdentifierSchema,
+    protected: exports_external.boolean(),
+    tolerance: exports_external.number().min(0).max(1),
+    baselineMean: exports_external.number().min(0).max(1),
+    candidateMean: exports_external.number().min(0).max(1),
+    pairedDelta: exports_external.number().min(-1).max(1),
+    regression: exports_external.boolean()
+  }).strict()),
+  lineage: exports_external.object({
+    baselineRunId: IdentifierSchema,
+    historicalBestRunId: IdentifierSchema,
+    taskSetHash: Sha256Schema,
+    baselineHash: Sha256Schema,
+    candidateHash: Sha256Schema,
+    historicalBestHash: Sha256Schema
+  }).strict(),
+  policyHash: Sha256Schema,
+  unavailableQualityMetrics: exports_external.array(exports_external.enum(["complexity_delta", "public_api_delta"])).default(["complexity_delta", "public_api_delta"])
+}).strict();
+var GateNameSchema = exports_external.enum([
+  "reviewer",
+  "test-engineer",
+  "sast",
+  "mutation",
+  "quality"
+]);
+var GateAuditManifestV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  id: IdentifierSchema,
+  createdAt: IsoDateSchema,
+  taskIds: exports_external.array(IdentifierSchema).min(1),
+  gates: exports_external.array(GateNameSchema).min(1),
+  models: exports_external.array(exports_external.string().min(1).max(300)).min(1),
+  preferredSwarm: IdentifierSchema.optional(),
+  repetitions: exports_external.number().int().positive().max(100),
+  seed: exports_external.string().min(1).max(500),
+  maxConcurrency: exports_external.number().int().positive().max(64),
+  maxRetries: exports_external.number().int().nonnegative().max(20),
+  maxTimeMs: exports_external.number().int().positive(),
+  maxCostUsd: exports_external.number().finite().nonnegative().optional(),
+  contentHash: Sha256Schema
+}).strict();
+var GateAuditCellV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  taskId: IdentifierSchema,
+  candidateId: IdentifierSchema.optional(),
+  defectType: IdentifierSchema,
+  gate: GateNameSchema,
+  model: exports_external.string().min(1).max(300),
+  repetition: exports_external.number().int().nonnegative(),
+  outcome: exports_external.enum([
+    "caught",
+    "missed",
+    "false_rejection",
+    "unsupported",
+    "infrastructure_failure"
+  ]),
+  retries: exports_external.number().int().nonnegative(),
+  cost: CostRecordSchema,
+  durationMs: exports_external.number().int().nonnegative(),
+  failureClassification: exports_external.enum([
+    "clean",
+    "pre_existing_failure",
+    "new_regression",
+    "flaky_failure",
+    "infrastructure_failure",
+    "unknown_failure"
+  ]).optional(),
+  failureCode: exports_external.string().min(1).max(160).optional()
+}).strict();
+var GateAuditResultV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  runId: IdentifierSchema,
+  manifestHash: Sha256Schema,
+  createdAt: IsoDateSchema,
+  status: exports_external.enum(["complete", "inconclusive", "cancelled"]),
+  cells: exports_external.array(GateAuditCellV1Schema),
+  cost: CostRecordSchema,
+  qualityMetricAvailability: exports_external.object({
+    complexity_delta: exports_external.literal("unavailable"),
+    public_api_delta: exports_external.literal("unavailable")
+  }).strict()
+}).strict();
+var TestConsumptionClaimV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  runId: IdentifierSchema,
+  taskSetHash: Sha256Schema,
+  baselineHash: Sha256Schema,
+  candidateHash: Sha256Schema,
+  claimedAt: IsoDateSchema
+}).strict();
+var TaskSetSnapshotV1Schema = exports_external.object({
+  v: exports_external.literal(1),
+  id: IdentifierSchema,
+  split: EvaluationSplitSchema,
+  tasks: exports_external.array(EvaluationTaskV1Schema).min(1),
+  contentHash: Sha256Schema,
+  createdAt: IsoDateSchema
+}).strict();
+
+// src/evaluation/store.ts
+import { mkdir as mkdir2, readdir, readFile as readFile2 } from "fs/promises";
+import * as path2 from "path";
+
+// src/evidence/immutable-store.ts
+import { mkdir, readFile } from "fs/promises";
+import * as path from "path";
+async function readOptionalFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+}
+async function writeImmutableArtifact(options) {
+  await mkdir(path.dirname(options.filePath), { recursive: true });
+  return withEvidenceLock(options.directory, options.relativeLockPath, options.agent, options.taskId, async () => {
+    const desired = options.serialize(options.value);
+    const existing = await readOptionalFile(options.filePath);
+    if (existing !== undefined) {
+      let parsed;
+      try {
+        parsed = options.parse(JSON.parse(existing));
+      } catch (error) {
+        throw options.conflictError({
+          kind: "corrupt",
+          filePath: options.filePath,
+          cause: error
+        });
+      }
+      if (options.serialize(parsed) === desired || options.isEquivalent?.(parsed, options.value)) {
+        return parsed;
+      }
+      throw options.conflictError({
+        kind: "divergent",
+        filePath: options.filePath
+      });
+    }
+    await atomicWriteFile(options.filePath, desired);
+    return options.value;
+  });
+}
+
+// src/evaluation/store.ts
+var AGENT = "evaluation-store";
+var TEST_LEDGER_RELATIVE = path2.join("evolution", "test-consumption.jsonl");
+var TASK_SPLIT_REGISTRY_RELATIVE = path2.join("evolution", "tasks", "split-registry.json");
+
+class EvaluationConflictError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EvaluationConflictError";
+  }
+}
+
+class TestAlreadyConsumedError extends Error {
+  priorClaim;
+  constructor(priorClaim) {
+    super(`held-out test task set ${priorClaim.taskSetHash} was already consumed by run ${priorClaim.runId}`);
+    this.name = "TestAlreadyConsumedError";
+    this.priorClaim = priorClaim;
+  }
+}
+function swarmPath(directory, ...segments) {
+  return path2.join(directory, ".swarm", ...segments);
+}
+function serialized(value) {
+  return `${canonicalJson(value)}
+`;
+}
+function parseTaskSplitRegistry(content) {
+  if (content === undefined)
+    return { v: 1, entries: [] };
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch (error) {
+    throw new EvaluationConflictError(`task split registry is corrupt: ${String(error)}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new EvaluationConflictError("task split registry is corrupt");
+  }
+  const record = value;
+  if (record.v !== 1 || !Array.isArray(record.entries)) {
+    throw new EvaluationConflictError("task split registry is corrupt");
+  }
+  const entries = record.entries.map((candidate) => {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+      throw new EvaluationConflictError("task split registry is corrupt");
+    }
+    const entry = candidate;
+    if (typeof entry.lineageHash !== "string" || !["train", "validation", "test"].includes(String(entry.split)) || !Array.isArray(entry.taskIds) || !entry.taskIds.every((id) => typeof id === "string") || !Array.isArray(entry.inputHashes) || !entry.inputHashes.every((hash) => typeof hash === "string")) {
+      throw new EvaluationConflictError("task split registry is corrupt");
+    }
+    return {
+      lineageHash: entry.lineageHash,
+      split: entry.split,
+      taskIds: [...new Set(entry.taskIds)].sort(),
+      inputHashes: [...new Set(entry.inputHashes)].sort()
+    };
+  });
+  return { v: 1, entries };
+}
+function evaluationConflictError(conflict) {
+  return conflict.kind === "corrupt" ? new EvaluationConflictError(`existing evaluation artifact is corrupt: ${conflict.filePath}: ${String(conflict.cause)}`) : new EvaluationConflictError(`immutable evaluation artifact conflicts with existing content: ${conflict.filePath}`);
+}
+function writeImmutable(options) {
+  return writeImmutableArtifact({
+    ...options,
+    agent: AGENT,
+    serialize: serialized,
+    conflictError: evaluationConflictError
+  });
+}
+function validateTaskInputs(directory, task) {
+  resolveContainedExistingPath(directory, task.instructionPath);
+  const environmentRoot = resolveContainedExistingPath(directory, task.environment.path);
+  if (task.scorer.kind === "project") {
+    const executable = task.scorer.argv[0];
+    if (!executable)
+      throw new Error("project scorer requires an executable");
+    const scorerPath = resolveContainedExistingPath(directory, executable);
+    const relative2 = path2.relative(environmentRoot, scorerPath);
+    if (!relative2 || relative2 === ".." || relative2.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative2)) {
+      throw new Error("project scorer executable must be inside the admitted task environment");
+    }
+  }
+}
+async function admitEvaluationTask(directory, input, inputRoot = directory) {
+  const task = EvaluationTaskV1Schema.parse(input);
+  if (await computeTaskInputContentHash(inputRoot, task) !== task.contentHash) {
+    throw new Error(`task ${task.id} content hash does not match its canonical inputs`);
+  }
+  validateTaskInputs(inputRoot, task);
+  const lineageInputHash = await computeTaskLineageInputHash(inputRoot, task);
+  const relative2 = path2.join("evolution", "tasks", task.split, `${task.id}.json`);
+  const admissionLock = TASK_SPLIT_REGISTRY_RELATIVE;
+  const filePath = swarmPath(directory, relative2);
+  await mkdir2(path2.dirname(filePath), { recursive: true });
+  return withEvidenceLock(directory, admissionLock, AGENT, task.id, async () => {
+    const registryPath = swarmPath(directory, TASK_SPLIT_REGISTRY_RELATIVE);
+    const registry = parseTaskSplitRegistry(await readOptionalFile(registryPath));
+    const existingTaskEntry = registry.entries.find((entry) => entry.taskIds.includes(task.id));
+    if (existingTaskEntry && existingTaskEntry.split !== task.split) {
+      throw new EvaluationConflictError(`task ${task.id} is already admitted to a different split`);
+    }
+    const parentEntry = task.derivedFromTaskId ? registry.entries.find((entry) => entry.taskIds.includes(task.derivedFromTaskId)) : undefined;
+    if (task.derivedFromTaskId && !parentEntry) {
+      throw new EvaluationConflictError(`derived task ${task.id} references an unadmitted parent ${task.derivedFromTaskId}`);
+    }
+    const lineageEntry = parentEntry ?? registry.entries.find((entry) => entry.lineageHash === lineageInputHash || entry.inputHashes.includes(lineageInputHash));
+    if (lineageEntry && lineageEntry.split !== task.split) {
+      throw new EvaluationConflictError(`task ${task.id} lineage is already admitted to ${lineageEntry.split}; derived and aliased tasks must inherit that split`);
+    }
+    for (const split of ["train", "validation", "test"]) {
+      if (split === task.split)
+        continue;
+      if (await readOptionalFile(swarmPath(directory, "evolution", "tasks", split, `${task.id}.json`))) {
+        throw new EvaluationConflictError(`task ${task.id} is already admitted to a different split`);
+      }
+    }
+    const desired = serialized(task);
+    const existing = await readOptionalFile(filePath);
+    if (existing !== undefined) {
+      const parsed = EvaluationTaskV1Schema.parse(JSON.parse(existing));
+      if (serialized(parsed) === desired) {
+        if (lineageEntry) {
+          lineageEntry.taskIds = [
+            ...new Set([...lineageEntry.taskIds, task.id])
+          ].sort();
+          lineageEntry.inputHashes = [
+            ...new Set([...lineageEntry.inputHashes, lineageInputHash])
+          ].sort();
+        } else {
+          registry.entries.push({
+            lineageHash: lineageInputHash,
+            split: task.split,
+            taskIds: [task.id],
+            inputHashes: [lineageInputHash]
+          });
+        }
+        registry.entries.sort((left, right) => left.lineageHash.localeCompare(right.lineageHash));
+        await atomicWriteFile(registryPath, serialized(registry));
+        return parsed;
+      }
+      if (task.split !== "train") {
+        throw new EvaluationConflictError(`${task.split} task ${task.id} is immutable after admission`);
+      }
+    }
+    await atomicWriteFile(filePath, desired);
+    if (lineageEntry) {
+      lineageEntry.taskIds = [
+        ...new Set([...lineageEntry.taskIds, task.id])
+      ].sort();
+      lineageEntry.inputHashes = [
+        ...new Set([...lineageEntry.inputHashes, lineageInputHash])
+      ].sort();
+    } else {
+      registry.entries.push({
+        lineageHash: lineageInputHash,
+        split: task.split,
+        taskIds: [task.id],
+        inputHashes: [lineageInputHash]
+      });
+    }
+    registry.entries.sort((left, right) => left.lineageHash.localeCompare(right.lineageHash));
+    await atomicWriteFile(registryPath, serialized(registry));
+    return task;
+  });
+}
+async function saveTaskSetSnapshot(directory, input, inputRoot = directory) {
+  const snapshot = TaskSetSnapshotV1Schema.parse(input);
+  const ids = snapshot.tasks.map((task) => task.id);
+  if (new Set(ids).size !== ids.length)
+    throw new Error("task-set contains duplicate task ids");
+  if (snapshot.tasks.some((task) => task.split !== snapshot.split)) {
+    throw new Error("task-set tasks must all belong to the declared split");
+  }
+  for (const task of snapshot.tasks) {
+    if (await computeTaskInputContentHash(inputRoot, task) !== task.contentHash) {
+      throw new Error(`task ${task.id} content hash is invalid`);
+    }
+  }
+  if (computeTaskSetContentHash(snapshot) !== snapshot.contentHash) {
+    throw new Error("task-set content hash does not match its canonical inputs");
+  }
+  const relative2 = path2.join("evolution", "task-sets", `${snapshot.contentHash}.json`);
+  return writeImmutable({
+    directory,
+    relativeLockPath: relative2,
+    filePath: swarmPath(directory, relative2),
+    taskId: snapshot.id,
+    value: snapshot,
+    parse: (value) => TaskSetSnapshotV1Schema.parse(value),
+    isEquivalent: (existing, desired) => existing.contentHash === desired.contentHash
+  });
+}
+async function saveEvaluationRun(directory, input) {
+  const run = EvaluationRunV1Schema.parse(input);
+  if (computeRunIntegrityHash(run) !== run.integrityHash) {
+    throw new Error(`run ${run.runId} integrity hash is invalid`);
+  }
+  const relative2 = path2.join("evolution", "runs", `${run.runId}.json`);
+  return writeImmutable({
+    directory,
+    relativeLockPath: relative2,
+    filePath: swarmPath(directory, relative2),
+    taskId: run.runId,
+    value: run,
+    parse: (value) => EvaluationRunV1Schema.parse(value)
+  });
+}
+async function readEvaluationRun(directory, runId) {
+  const content = await readOptionalFile(swarmPath(directory, "evolution", "runs", `${runId}.json`));
+  return content === undefined ? undefined : EvaluationRunV1Schema.parse(JSON.parse(content));
+}
+async function savePromotionDecision(directory, input) {
+  const decision = PromotionDecisionV1Schema.parse(input);
+  const relative2 = path2.join("evolution", "decisions", `${decision.decisionId}.json`);
+  return writeImmutable({
+    directory,
+    relativeLockPath: relative2,
+    filePath: swarmPath(directory, relative2),
+    taskId: decision.runId,
+    value: decision,
+    parse: (value) => PromotionDecisionV1Schema.parse(value),
+    isEquivalent: (existing, desired) => {
+      const { decidedAt: _existingTimestamp, ...existingCore } = existing;
+      const { decidedAt: _desiredTimestamp, ...desiredCore } = desired;
+      return canonicalJson(existingCore) === canonicalJson(desiredCore);
+    }
+  });
+}
+async function saveGateAuditResult(directory, input) {
+  const result = GateAuditResultV1Schema.parse(input);
+  const relative2 = path2.join("evidence", "gate-audit", result.runId, "results.json");
+  return writeImmutable({
+    directory,
+    relativeLockPath: relative2,
+    filePath: swarmPath(directory, relative2),
+    taskId: result.runId,
+    value: result,
+    parse: (value) => GateAuditResultV1Schema.parse(value)
+  });
+}
+async function saveGateAuditManifest(directory, input) {
+  const manifest = GateAuditManifestV1Schema.parse(input);
+  const relative2 = path2.join("evolution", "gate-audit-manifests", `${manifest.id}.json`);
+  return writeImmutable({
+    directory,
+    relativeLockPath: relative2,
+    filePath: swarmPath(directory, relative2),
+    taskId: manifest.id,
+    value: manifest,
+    parse: (value) => GateAuditManifestV1Schema.parse(value)
+  });
+}
+async function readGateAuditManifest(directory, runId) {
+  const content = await readOptionalFile(swarmPath(directory, "evolution", "gate-audit-manifests", `${runId}.json`));
+  return content === undefined ? undefined : GateAuditManifestV1Schema.parse(JSON.parse(content));
+}
+async function readGateAuditResult(directory, runId) {
+  const content = await readOptionalFile(swarmPath(directory, "evidence", "gate-audit", runId, "results.json"));
+  return content === undefined ? undefined : GateAuditResultV1Schema.parse(JSON.parse(content));
+}
+async function listGateAuditResults(directory) {
+  const root = swarmPath(directory, "evidence", "gate-audit");
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { results: [], corruptRunIds: [] };
+    }
+    throw error;
+  }
+  const results = [];
+  const corruptRunIds = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/.test(entry.name)) {
+      continue;
+    }
+    try {
+      const parsed = GateAuditResultV1Schema.parse(JSON.parse(await readFile2(path2.join(root, entry.name, "results.json"), "utf8")));
+      if (parsed.runId !== entry.name)
+        throw new Error("run id/path mismatch");
+      results.push(parsed);
+    } catch {
+      corruptRunIds.push(entry.name);
+    }
+  }
+  return { results, corruptRunIds };
+}
+function parseTestLedger(content) {
+  return content.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line, index) => {
+    try {
+      return TestConsumptionClaimV1Schema.parse(JSON.parse(line));
+    } catch (error) {
+      throw new EvaluationConflictError(`test-consumption ledger is corrupt at line ${index + 1}: ${String(error)}`);
+    }
+  });
+}
+async function claimHeldOutTest(directory, input) {
+  const claim = TestConsumptionClaimV1Schema.parse(input);
+  const filePath = swarmPath(directory, TEST_LEDGER_RELATIVE);
+  await mkdir2(path2.dirname(filePath), { recursive: true });
+  return withEvidenceLock(directory, TEST_LEDGER_RELATIVE, AGENT, claim.runId, async () => {
+    const content = await readOptionalFile(filePath) ?? "";
+    const claims = parseTestLedger(content);
+    const identicalRun = claims.find((entry) => entry.runId === claim.runId);
+    if (identicalRun) {
+      if (identicalRun.taskSetHash === claim.taskSetHash && identicalRun.baselineHash === claim.baselineHash && identicalRun.candidateHash === claim.candidateHash) {
+        return identicalRun;
+      }
+      throw new EvaluationConflictError(`run ${claim.runId} conflicts with its prior held-out test claim`);
+    }
+    const prior = claims.find((entry) => entry.taskSetHash === claim.taskSetHash);
+    if (prior)
+      throw new TestAlreadyConsumedError(prior);
+    await atomicWriteFile(filePath, `${content.replace(/\s*$/, "")}${content.trim() ? `
+` : ""}${serialized(claim)}`);
+    return claim;
+  });
+}
+async function getProtectedEvaluationRunIds(directory) {
+  const protectedIds = new Set;
+  const ledger = await readOptionalFile(swarmPath(directory, TEST_LEDGER_RELATIVE));
+  for (const claim of parseTestLedger(ledger ?? ""))
+    protectedIds.add(claim.runId);
+  const decisionsDirectory = swarmPath(directory, "evolution", "decisions");
+  let files = [];
+  try {
+    files = await readdir(decisionsDirectory);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  for (const filename of files.filter((value) => value.endsWith(".json")).sort()) {
+    const decision = PromotionDecisionV1Schema.parse(JSON.parse(await readFile2(path2.join(decisionsDirectory, filename), "utf8")));
+    protectedIds.add(decision.runId);
+    protectedIds.add(decision.lineage.baselineRunId);
+    if (decision.lineage.historicalBestRunId !== "unavailable") {
+      protectedIds.add(decision.lineage.historicalBestRunId);
+    }
+  }
+  return protectedIds;
+}
+
+export { IdentifierSchema, CostRecordSchema, EvaluationTaskV1Schema, EvaluationCandidateV1Schema, EvaluationRunV1Schema, PromotionPolicyV1Schema, PromotionDecisionV1Schema, GateNameSchema, GateAuditManifestV1Schema, GateAuditResultV1Schema, admitEvaluationTask, saveTaskSetSnapshot, saveEvaluationRun, readEvaluationRun, savePromotionDecision, saveGateAuditResult, saveGateAuditManifest, readGateAuditManifest, readGateAuditResult, listGateAuditResults, claimHeldOutTest, getProtectedEvaluationRunIds };