@iislee/opencodex 2.11.0 → 2.31.0

package/src/lab/artifacts/store.ts

@@ -0,0 +1,310 @@
+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 parseContractJson(bytes: Uint8Array): unknown {
+  return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+}
+
+function jsonDigest(
+  digest: (value: Record<string, unknown>) => string,
+): (bytes: Uint8Array) => string {
+  return (bytes) => {
+    try {
+      return digest(parseContractJson(bytes) as Record<string, unknown>);
+    } catch (err) {
+      if (err instanceof ArtifactFsError) throw err;
+      throw new ArtifactFsError("artifact_mismatch", "artifact content is not valid contract JSON");
+    }
+  };
+}
+
+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) => {
+        try {
+          const parsed = parseContractJson(bytes);
+          return claimSourceManifestDigest(validateClaimSourceManifest(parsed).manifest);
+        } catch (err) {
+          if (err instanceof ArtifactFsError) throw err;
+          throw new ArtifactFsError("artifact_mismatch", "claim-source artifact failed validation");
+        }
+      };
+    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;
+        let computedDigest: string;
+        try {
+          computedDigest = computeContractDigest(contractClass, bytes, redacted);
+        } catch (err) {
+          if (err instanceof ArtifactFsError) throw err;
+          throw new ArtifactFsError(
+            "artifact_mismatch",
+            err instanceof Error ? err.message : "contract artifact failed validation",
+          );
+        }
+        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<string, unknown>) : parseContractJson(bytes) as Record<string, unknown>,
+      );
+    case "suite_manifest":
+      return suiteManifestDigest(
+        typeof redacted === "object" && redacted ? (redacted as Record<string, unknown>) : parseContractJson(bytes) as Record<string, unknown>,
+      );
+    case "claim_source_manifest": {
+      const parsed = typeof redacted === "object" && redacted
+        ? redacted
+        : parseContractJson(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:
+      // v2 marks the sanitizer that also redacts network and account
+      // identifiers. The field records which algorithm produced the bytes, so
+      // it moves whenever those semantics change.
+      return "sanitized_evidence_v2";
+  }
+}
+
+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 = parseContractJson(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),
+    };
+  }
+}

package/src/lab/automation/budgets.ts

@@ -0,0 +1,78 @@
+import { LAB_AUTOMATION_HARD_MAX } from "./constants";
+import type { LabAutomationPolicyV1, LabAutomationStateV1 } from "./types";
+
+export function rollBudgetWindow(state: LabAutomationStateV1, now: number): LabAutomationStateV1 {
+  if (now - state.budgetWindowStartedAt < LAB_AUTOMATION_HARD_MAX.budgetWindowMs) return state;
+  return {
+    ...state,
+    budgetWindowStartedAt: now,
+    runsThisHour: 0,
+    liveRequestsThisHour: 0,
+  };
+}
+
+function rollingStartedRuns(state: LabAutomationStateV1, now: number): number {
+  const cutoff = now - LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+  return state.runs.filter((run) => typeof run.startedAt === "number" && run.startedAt > cutoff && run.startedAt <= now).length;
+}
+
+function rollingStartedLiveRuns(state: LabAutomationStateV1, now: number): number {
+  const cutoff = now - LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+  return state.runs.filter((run) =>
+    run.evidenceLayer === "live_route_compatibility"
+    && typeof run.startedAt === "number"
+    && run.startedAt > cutoff
+    && run.startedAt <= now
+  ).length;
+}
+
+function legacyCounterActive(state: LabAutomationStateV1, now: number): boolean {
+  return now - state.budgetWindowStartedAt < LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+}
+
+export function runBudgetRemaining(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): number {
+  const rolling = rollingStartedRuns(state, now);
+  const legacy = legacyCounterActive(state, now) ? state.runsThisHour : 0;
+  return Math.max(0, policy.maxRunsPerHour - Math.max(rolling, legacy));
+}
+
+export function liveRequestBudgetRemaining(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): number {
+  const rolling = rollingStartedLiveRuns(state, now);
+  const legacy = legacyCounterActive(state, now) ? state.liveRequestsThisHour : 0;
+  return Math.max(0, policy.maxLiveRequestsPerHour - Math.max(rolling, legacy));
+}
+
+export function isRunBudgetExhausted(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): boolean {
+  return runBudgetRemaining(policy, state, now) <= 0;
+}
+
+export function isLiveRequestBudgetExhausted(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): boolean {
+  return liveRequestBudgetRemaining(policy, state, now) <= 0;
+}
+
+/** Legacy persisted counters remain for schema compatibility; startedAt records are rolling authority. */
+export function recordRunBudgetUse(state: LabAutomationStateV1, liveRequest: boolean): LabAutomationStateV1 {
+  return {
+    ...state,
+    runsThisHour: Math.min(LAB_AUTOMATION_HARD_MAX.maxRunsPerHour, state.runsThisHour + 1),
+    liveRequestsThisHour: liveRequest
+      ? Math.min(LAB_AUTOMATION_HARD_MAX.maxLiveRequestsPerHour, state.liveRequestsThisHour + 1)
+      : state.liveRequestsThisHour,
+  };
+}

package/src/lab/automation/config-persistence.ts

@@ -0,0 +1,256 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  linkSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { renameAtomicFile } from "../../lib/windows-atomic-replace";
+import {
+  ensureLabDirs,
+  labAutomationPolicyPath,
+} from "../paths";
+import { normalizeLabAutomationPolicyV1 } from "./policy";
+import {
+  loadLabAutomationPolicy,
+  loadLabAutomationRoutes,
+  normalizeLabAutomationRoutesV1,
+} from "./persistence";
+import type { LabAutomationPolicyV1, LabAutomationRoutesV1 } from "./types";
+import { LabAutomationError } from "./types";
+
+const CONFIG_SCHEMA_VERSION = 1 as const;
+const CONFIG_KEYS = new Set(["schemaVersion", "policy", "routes"]);
+const CONFIG_LOCK_WAIT_MS = 5_000;
+const LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+
+interface ConfigLockMeta {
+  pid: number;
+  token: string;
+}
+
+export interface LabAutomationConfigV1 {
+  schemaVersion: typeof CONFIG_SCHEMA_VERSION;
+  policy: LabAutomationPolicyV1;
+  routes: LabAutomationRoutesV1;
+}
+
+type ConfigCommitFault = "before_publish" | null;
+let configCommitFaultForTests: ConfigCommitFault = null;
+
+function configPath(configDir?: string): string {
+  return join(dirname(labAutomationPolicyPath(configDir)), "automation-config.json");
+}
+
+function configLockPath(configDir?: string): string {
+  return `${configPath(configDir)}.lock`;
+}
+
+function sleepLockRetry(): void {
+  Atomics.wait(LOCK_SLEEP, 0, 0, 10);
+}
+
+function readLockMeta(lockPath: string): ConfigLockMeta | null {
+  try {
+    const parsed = JSON.parse(readFileSync(lockPath, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const row = parsed as Record<string, unknown>;
+    if (!Number.isSafeInteger(row.pid) || (row.pid as number) <= 0) return null;
+    if (typeof row.token !== "string" || row.token.length < 16 || row.token.length > 128) return null;
+    return { pid: row.pid as number, token: row.token };
+  } catch {
+    return null;
+  }
+}
+
+function pidDefinitelyDead(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error
+      ? String((error as { code?: unknown }).code)
+      : undefined;
+    return code === "ESRCH";
+  }
+}
+
+function cleanupFile(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Absent or already cleaned.
+  }
+}
+
+function releaseLock(lockPath: string, token: string): void {
+  try {
+    if (readLockMeta(lockPath)?.token === token) unlinkSync(lockPath);
+  } catch {
+    // Already released or replaced.
+  }
+}
+
+function reclaimDeadLock(lockPath: string): boolean {
+  const observed = readLockMeta(lockPath);
+  if (!observed || !pidDefinitelyDead(observed.pid)) return false;
+  const current = readLockMeta(lockPath);
+  if (!current || current.pid !== observed.pid || current.token !== observed.token) return false;
+  try {
+    unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireConfigLock(configDir?: string): () => void {
+  ensureLabDirs(configDir);
+  const lockPath = configLockPath(configDir);
+  const deadline = Date.now() + CONFIG_LOCK_WAIT_MS;
+  while (true) {
+    const token = randomUUID();
+    const privatePath = `${lockPath}.${process.pid}.${token}.tmp`;
+    let publicationAttempted = false;
+    try {
+      const fd = openSync(privatePath, "wx", 0o600);
+      try {
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, token }), { encoding: "utf8" });
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      publicationAttempted = true;
+      linkSync(privatePath, lockPath);
+      cleanupFile(privatePath);
+      return () => releaseLock(lockPath, token);
+    } catch (error) {
+      cleanupFile(privatePath);
+      const code = error && typeof error === "object" && "code" in error
+        ? String((error as { code?: unknown }).code)
+        : undefined;
+      if (code === "EEXIST" && !publicationAttempted) continue;
+      if (code !== "EEXIST") {
+        throw new LabAutomationError("automation config lock failed", "state_lock_failed");
+      }
+      if (reclaimDeadLock(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        throw new LabAutomationError("automation config is busy", "state_lock_busy");
+      }
+      sleepLockRetry();
+    }
+  }
+}
+
+function withConfigLock<T>(configDir: string | undefined, action: () => T): T {
+  const release = acquireConfigLock(configDir);
+  try {
+    return action();
+  } finally {
+    release();
+  }
+}
+
+function normalizeConfig(raw: unknown): LabAutomationConfigV1 {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new LabAutomationError("automation config must be an object", "invalid_state");
+  }
+  const row = raw as Record<string, unknown>;
+  for (const key of Object.keys(row)) {
+    if (!CONFIG_KEYS.has(key)) {
+      throw new LabAutomationError(`unknown automation config field ${key}`, "invalid_state");
+    }
+  }
+  if (row.schemaVersion !== CONFIG_SCHEMA_VERSION) {
+    throw new LabAutomationError("unsupported automation config schemaVersion", "invalid_state");
+  }
+  return Object.freeze({
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    policy: normalizeLabAutomationPolicyV1(row.policy),
+    routes: normalizeLabAutomationRoutesV1(row.routes),
+  });
+}
+
+function loadConfigUnlocked(configDir?: string): LabAutomationConfigV1 {
+  ensureLabDirs(configDir);
+  const path = configPath(configDir);
+  if (!existsSync(path)) {
+    return Object.freeze({
+      schemaVersion: CONFIG_SCHEMA_VERSION,
+      policy: loadLabAutomationPolicy(configDir),
+      routes: loadLabAutomationRoutes(configDir),
+    });
+  }
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(path, "utf8")) as unknown);
+  } catch (error) {
+    if (error instanceof LabAutomationError) throw error;
+    throw new LabAutomationError("invalid automation config JSON", "invalid_state");
+  }
+}
+
+function writeConfigUnlocked(
+  policy: LabAutomationPolicyV1,
+  routes: LabAutomationRoutesV1,
+  configDir?: string,
+): LabAutomationConfigV1 {
+  ensureLabDirs(configDir);
+  const normalized = Object.freeze({
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    policy: normalizeLabAutomationPolicyV1(policy),
+    routes: normalizeLabAutomationRoutesV1(routes),
+  });
+  const path = configPath(configDir);
+  const tmp = join(dirname(path), `.automation-config.${process.pid}.${randomUUID()}.tmp`);
+  let fd: number | null = null;
+  try {
+    fd = openSync(tmp, "wx", 0o600);
+    writeFileSync(fd, JSON.stringify(normalized), { encoding: "utf8" });
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    if (configCommitFaultForTests === "before_publish") {
+      throw new LabAutomationError("synthetic automation config commit failure", "invalid_state");
+    }
+    renameAtomicFile(tmp, path, undefined, "lab-automation");
+    return normalized;
+  } finally {
+    if (fd !== null) closeSync(fd);
+    cleanupFile(tmp);
+  }
+}
+
+/** Load one coherent policy/routes generation. */
+export function loadLabAutomationConfig(configDir?: string): LabAutomationConfigV1 {
+  return withConfigLock(configDir, () => loadConfigUnlocked(configDir));
+}
+
+/** Atomically publish one coherent policy/routes generation. */
+export function saveLabAutomationConfig(
+  policy: LabAutomationPolicyV1,
+  routes: LabAutomationRoutesV1,
+  configDir?: string,
+): LabAutomationConfigV1 {
+  return withConfigLock(configDir, () => writeConfigUnlocked(policy, routes, configDir));
+}
+
+/** Update only policy while preserving routes from the same committed generation. */
+export function saveLabAutomationPolicyConfig(
+  policy: LabAutomationPolicyV1,
+  configDir?: string,
+): LabAutomationConfigV1 {
+  return withConfigLock(configDir, () => {
+    const current = loadConfigUnlocked(configDir);
+    return writeConfigUnlocked(policy, current.routes, configDir);
+  });
+}
+
+/** Test-only fault injection before the atomic rename publication point. */
+export function setLabAutomationConfigCommitFaultForTests(fault: ConfigCommitFault): void {
+  configCommitFaultForTests = fault;
+}

package/src/lab/automation/constants.ts

@@ -0,0 +1,39 @@
+/** CL-08 automation hard ceilings — callers cannot raise policy above these values. */
+
+export const LAB_AUTOMATION_POLICY_SCHEMA_VERSION = 1 as const;
+
+export const LAB_AUTOMATION_HARD_MAX = Object.freeze({
+  refreshBeforeStaleMs: 30 * 24 * 60 * 60 * 1000,
+  maxConcurrentRuns: 4,
+  maxConcurrentLiveRuns: 2,
+  maxConcurrentRunsPerRoute: 2,
+  maxRunsPerHour: 60,
+  maxLiveRequestsPerHour: 30,
+  failureCooldownMs: 24 * 60 * 60 * 1000,
+  blockedCooldownMs: 7 * 24 * 60 * 60 * 1000,
+  terminalRunRetentionMs: 7 * 24 * 60 * 60 * 1000,
+  maxQueuedRuns: 256,
+  maxPersistedRuns: 512,
+  maxAutomationRoutes: 64,
+  budgetWindowMs: 60 * 60 * 1000,
+  schedulerTickMs: 60 * 1000,
+});
+
+export const LAB_AUTOMATION_DEFAULT_POLICY = Object.freeze({
+  schemaVersion: LAB_AUTOMATION_POLICY_SCHEMA_VERSION,
+  enabled: false,
+  layers: Object.freeze({
+    protocolConformance: false,
+    liveRouteCompatibility: false,
+    taskEffectiveness: false,
+  }),
+  refreshBeforeStaleMs: 24 * 60 * 60 * 1000,
+  maxConcurrentRuns: 2,
+  maxConcurrentLiveRuns: 1,
+  maxConcurrentRunsPerRoute: 1,
+  maxRunsPerHour: 12,
+  maxLiveRequestsPerHour: 6,
+  failureCooldownMs: 5 * 60 * 1000,
+  blockedCooldownMs: 60 * 60 * 1000,
+  taskEffectivenessBackgroundEnabled: false,
+});