@iislee/opencodex 2.11.0 → 2.31.0

package/src/lab/automation/planner.ts

@@ -0,0 +1,371 @@
+import type { EvidenceLayer } from "../constants";
+import { subjectIdForSubject, scenarioManifestDigest } from "../digest";
+import { discoverScenarios, expandScenario, loadCaseAuthority } from "../conformance/manifest";
+import { CL01_SUITES, CL03_LIVE_SUITES } from "../conformance/types";
+import { resolveProtocolExecutionContext } from "../conformance/executor";
+import { buildProtocolSubjectV1 } from "../subject/protocol-subject";
+import { discoverLiveScenarios, expandLiveScenario, loadLiveCaseAuthority } from "../live/manifest";
+import { isLiveCaseApplicableToRoute } from "../live/executor";
+import { buildAutomationLiveRouteContext } from "./route-context";
+import { liveSuiteManifestDigestForCase } from "../live/suite-manifest";
+import { suiteManifestDigestForCase } from "../conformance/suite-manifest";
+import { isScenarioApplicable } from "../projection/verification";
+import { queryLatestLabObservation } from "../query/latest-observation";
+import { LabProjectionUnavailableError } from "../query/errors";
+import type { OcxConfig } from "../../types";
+import { resolvePolicyCompatibilitySubjects } from "../../routing/compatibility/subject";
+import type {
+  LabAutomationLayer,
+  LabAutomationPlanReason,
+  LabAutomationPolicyV1,
+  LabAutomationRoutesV1,
+  LabAutomationRunRecordV1,
+  LabAutomationStateV1,
+  PlannedLabRunV1,
+} from "./types";
+import { LabAutomationError } from "./types";
+import {
+  buildLabAutomationRunKey,
+  liveExecutionContractDigest,
+  protocolExecutionContractDigest,
+} from "./run-key";
+import { cooldownActive, cooldownCapacityExhausted } from "./cooldown";
+import { isLiveRequestBudgetExhausted, isRunBudgetExhausted } from "./budgets";
+import { LAB_AUTOMATION_HARD_MAX } from "./constants";
+
+export interface PlannerInput {
+  policy: LabAutomationPolicyV1;
+  routes: LabAutomationRoutesV1;
+  state: LabAutomationStateV1;
+  now: number;
+  config?: OcxConfig;
+  configDir?: string;
+}
+
+interface EvidenceIdentity {
+  layer: EvidenceLayer;
+  subjectId: string;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  scenarioId: string;
+  scenarioVersion: string;
+  scenarioManifestDigest: string;
+}
+
+function freshnessReason(
+  latestCompletedAt: number | undefined,
+  maxAgeMs: number | null,
+  refreshBeforeStaleMs: number,
+  now: number,
+): LabAutomationPlanReason {
+  if (latestCompletedAt === undefined) return "missing";
+  if (maxAgeMs === null) return "fresh";
+  const deadline = latestCompletedAt + maxAgeMs;
+  const refreshAt = deadline - refreshBeforeStaleMs;
+  if (now >= deadline) return "refresh_due";
+  if (now >= refreshAt) return "refresh_due";
+  return "fresh";
+}
+
+function activeRunForKey(state: LabAutomationStateV1, runKey: string): LabAutomationRunRecordV1 | undefined {
+  return state.runs.find((row) => row.runKey === runKey && (row.state === "queued" || row.state === "running"));
+}
+
+function cancellationBackoffActive(
+  state: LabAutomationStateV1,
+  runKey: string,
+  failureCooldownMs: number,
+  now: number,
+): boolean {
+  const backoffMs = Math.max(failureCooldownMs, LAB_AUTOMATION_HARD_MAX.schedulerTickMs);
+  return state.runs.some((row) =>
+    row.runKey === runKey
+    && row.trigger === "scheduled"
+    && row.state === "cancelled"
+    && row.terminalCode === "cancelled"
+    && typeof row.completedAt === "number"
+    && row.completedAt + backoffMs > now
+  );
+}
+
+function latestMatchingObservationCompletedAt(
+  identity: EvidenceIdentity,
+  configDir?: string,
+): number | undefined {
+  try {
+    return queryLatestLabObservation(identity, configDir);
+  } catch (error) {
+    if (error instanceof LabProjectionUnavailableError) return undefined;
+    throw error;
+  }
+}
+
+function planProtocolScenarios(input: PlannerInput): PlannedLabRunV1[] {
+  if (!input.policy.enabled || !input.policy.layers.protocolConformance) return [];
+  const authority = loadCaseAuthority();
+  const scenarios = discoverScenarios(authority, CL01_SUITES);
+  const planned: PlannedLabRunV1[] = [];
+  for (const caseRecord of scenarios) {
+    if (!isScenarioApplicable(caseRecord.id, "fixture", "protocol_conformance")) continue;
+    let subject;
+    try {
+      const ctx = resolveProtocolExecutionContext(caseRecord);
+      subject = buildProtocolSubjectV1(ctx);
+    } catch {
+      continue;
+    }
+    const subjectId = subjectIdForSubject(subject);
+    const expanded = expandScenario(caseRecord, authority);
+    const scenarioDigest = scenarioManifestDigest(expanded);
+    const suiteDigest = suiteManifestDigestForCase(caseRecord, authority);
+    const suiteVersion = authority.manifestDefaults.suiteVersion;
+    const scenarioVersion = authority.manifestDefaults.version;
+    const runKey = buildLabAutomationRunKey({
+      evidenceLayer: "protocol_conformance",
+      subjectId,
+      suiteId: caseRecord.suite,
+      suiteVersion,
+      suiteManifestDigest: suiteDigest,
+      scenarioId: caseRecord.id,
+      scenarioVersion,
+      scenarioManifestDigest: scenarioDigest,
+      executionContractDigest: protocolExecutionContractDigest(),
+    });
+    if (activeRunForKey(input.state, runKey)) continue;
+    if (cancellationBackoffActive(input.state, runKey, input.policy.failureCooldownMs, input.now)) continue;
+    if (cooldownActive(input.state, runKey, input.now)) continue;
+    const latestCompletedAt = latestMatchingObservationCompletedAt({
+      layer: "protocol_conformance",
+      subjectId,
+      suiteId: caseRecord.suite,
+      suiteVersion,
+      suiteManifestDigest: suiteDigest,
+      scenarioId: caseRecord.id,
+      scenarioVersion,
+      scenarioManifestDigest: scenarioDigest,
+    }, input.configDir);
+    // CL-00 freezes one freshness default into both suite and scenario manifests; there is no
+    // independent case-level override in the current authority schema.
+    const maxAge = authority.manifestDefaults.freshness.maxAgeMs;
+    const freshness = freshnessReason(latestCompletedAt, maxAge, input.policy.refreshBeforeStaleMs, input.now);
+    if (freshness === "fresh") continue;
+    planned.push({
+      runKey,
+      evidenceLayer: "protocol_conformance",
+      suiteId: caseRecord.suite,
+      suiteVersion,
+      suiteManifestDigest: suiteDigest,
+      scenarioId: caseRecord.id,
+      scenarioVersion,
+      scenarioManifestDigest: scenarioDigest,
+      subjectId,
+      reason: freshness,
+      priority: freshness === "missing" ? 0 : 1,
+      eligibleAt: input.now,
+    });
+  }
+  return planned;
+}
+
+function planLiveScenarios(input: PlannerInput): PlannedLabRunV1[] {
+  if (!input.policy.enabled || !input.policy.layers.liveRouteCompatibility) return [];
+  if (!input.config) return [];
+  if (isLiveRequestBudgetExhausted(input.policy, input.state, input.now)) return [];
+  const authority = loadLiveCaseAuthority();
+  const scenarios = discoverLiveScenarios(authority, CL03_LIVE_SUITES);
+  const planned: PlannedLabRunV1[] = [];
+  for (const routeRef of input.routes.routes) {
+    const routed = input.config.providers?.[routeRef.providerName];
+    if (!routed) continue;
+    const resolved = resolvePolicyCompatibilitySubjects(
+      input.config,
+      routeRef.providerName,
+      routeRef.modelId,
+      routed,
+      input.configDir,
+    );
+    if (!resolved.route) continue;
+    const routeContext = buildAutomationLiveRouteContext(
+      resolved.route,
+      routed.allowPrivateNetwork === true,
+    );
+    for (const caseRecord of scenarios) {
+      if (!isLiveCaseApplicableToRoute(caseRecord, routeContext)) continue;
+      const expanded = expandLiveScenario(caseRecord, authority);
+      const scenarioDigest = scenarioManifestDigest(expanded);
+      const suiteDigest = liveSuiteManifestDigestForCase(caseRecord, authority);
+      const suiteVersion = authority.manifestDefaults.suiteVersion;
+      const scenarioVersion = authority.manifestDefaults.version;
+      const subjectId = resolved.route.subjectId;
+      const runKey = buildLabAutomationRunKey({
+        evidenceLayer: "live_route_compatibility",
+        subjectId,
+        suiteId: caseRecord.suite,
+        suiteVersion,
+        suiteManifestDigest: suiteDigest,
+        scenarioId: caseRecord.id,
+        scenarioVersion,
+        scenarioManifestDigest: scenarioDigest,
+        executionContractDigest: liveExecutionContractDigest(),
+      });
+      if (activeRunForKey(input.state, runKey)) continue;
+      if (cancellationBackoffActive(input.state, runKey, input.policy.failureCooldownMs, input.now)) continue;
+      if (cooldownActive(input.state, runKey, input.now)) continue;
+      const latestCompletedAt = latestMatchingObservationCompletedAt({
+        layer: "live_route_compatibility",
+        subjectId,
+        suiteId: caseRecord.suite,
+        suiteVersion,
+        suiteManifestDigest: suiteDigest,
+        scenarioId: caseRecord.id,
+        scenarioVersion,
+        scenarioManifestDigest: scenarioDigest,
+      }, input.configDir);
+      const maxAge = authority.manifestDefaults.freshness.maxAgeMs;
+      const freshness = freshnessReason(latestCompletedAt, maxAge, input.policy.refreshBeforeStaleMs, input.now);
+      if (freshness === "fresh") continue;
+      planned.push({
+        runKey,
+        evidenceLayer: "live_route_compatibility",
+        suiteId: caseRecord.suite,
+        suiteVersion,
+        suiteManifestDigest: suiteDigest,
+        scenarioId: caseRecord.id,
+        scenarioVersion,
+        scenarioManifestDigest: scenarioDigest,
+        subjectId,
+        reason: freshness,
+        priority: freshness === "missing" ? 0 : 1,
+        eligibleAt: input.now,
+        providerName: routeRef.providerName,
+        modelId: routeRef.modelId,
+      });
+    }
+  }
+  return planned;
+}
+
+/** Deterministic planner — no execution side effects. */
+export function planLabAutomationRuns(input: PlannerInput): PlannedLabRunV1[] {
+  if (!input.policy.enabled) return [];
+  if (isRunBudgetExhausted(input.policy, input.state, input.now)) return [];
+  // Cooldown persistence is bounded. If every slot contains an active backoff, fail closed rather
+  // than enqueueing work whose retry suppression could not be recorded.
+  if (cooldownCapacityExhausted(input.state, input.now)) return [];
+  const protocol = planProtocolScenarios(input);
+  const live = planLiveScenarios(input);
+  const merged = [...protocol, ...live];
+  merged.sort((a, b) => {
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    if (a.eligibleAt !== b.eligibleAt) return a.eligibleAt - b.eligibleAt;
+    return a.runKey < b.runKey ? -1 : a.runKey > b.runKey ? 1 : 0;
+  });
+  const cap = LAB_AUTOMATION_HARD_MAX.maxQueuedRuns;
+  return merged.slice(0, cap);
+}
+
+export interface ManualLabRunInput {
+  evidenceLayer: LabAutomationLayer;
+  scenarioId: string;
+  providerName?: string;
+  modelId?: string;
+  config?: OcxConfig;
+  configDir?: string;
+}
+
+/** Build a single manual run plan — independent of automation enablement. */
+export function planManualLabRun(input: ManualLabRunInput): PlannedLabRunV1 {
+  const now = Date.now();
+  if (input.evidenceLayer === "task_effectiveness") {
+    throw new LabAutomationError("manual task_effectiveness uses CL-07 tooling", "task_background_disabled");
+  }
+  if (input.evidenceLayer === "protocol_conformance") {
+    const authority = loadCaseAuthority();
+    const caseRecord = authority.cases.find((row) => row.id === input.scenarioId);
+    if (!caseRecord) throw new LabAutomationError("unknown protocol scenario", "scenario_inapplicable");
+    const ctx = resolveProtocolExecutionContext(caseRecord);
+    const subject = buildProtocolSubjectV1(ctx);
+    const subjectId = subjectIdForSubject(subject);
+    const expanded = expandScenario(caseRecord, authority);
+    const scenarioDigest = scenarioManifestDigest(expanded);
+    const suiteDigest = suiteManifestDigestForCase(caseRecord, authority);
+    return {
+      runKey: buildLabAutomationRunKey({
+        evidenceLayer: "protocol_conformance",
+        subjectId,
+        suiteId: caseRecord.suite,
+        suiteVersion: authority.manifestDefaults.suiteVersion,
+        suiteManifestDigest: suiteDigest,
+        scenarioId: caseRecord.id,
+        scenarioVersion: authority.manifestDefaults.version,
+        scenarioManifestDigest: scenarioDigest,
+        executionContractDigest: protocolExecutionContractDigest(),
+      }),
+      evidenceLayer: "protocol_conformance",
+      suiteId: caseRecord.suite,
+      suiteVersion: authority.manifestDefaults.suiteVersion,
+      suiteManifestDigest: suiteDigest,
+      scenarioId: caseRecord.id,
+      scenarioVersion: authority.manifestDefaults.version,
+      scenarioManifestDigest: scenarioDigest,
+      subjectId,
+      reason: "missing",
+      priority: 0,
+      eligibleAt: now,
+    };
+  }
+  if (!input.config || !input.providerName || !input.modelId) {
+    throw new LabAutomationError("live manual run requires providerName and modelId", "route_ineligible");
+  }
+  const routed = input.config.providers?.[input.providerName];
+  if (!routed) throw new LabAutomationError("unknown provider route", "route_ineligible");
+  const resolved = resolvePolicyCompatibilitySubjects(
+    input.config,
+    input.providerName,
+    input.modelId,
+    routed,
+    input.configDir,
+  );
+  if (!resolved.route) throw new LabAutomationError("route ineligible for compatibility subject", "route_ineligible");
+  const authority = loadLiveCaseAuthority();
+  const caseRecord = authority.cases.find((row) => row.id === input.scenarioId);
+  if (!caseRecord) throw new LabAutomationError("unknown live scenario", "scenario_inapplicable");
+  const routeContext = buildAutomationLiveRouteContext(
+    resolved.route,
+    routed.allowPrivateNetwork === true,
+  );
+  if (!isLiveCaseApplicableToRoute(caseRecord, routeContext)) {
+    throw new LabAutomationError("scenario inapplicable to route", "scenario_inapplicable");
+  }
+  const expanded = expandLiveScenario(caseRecord, authority);
+  const scenarioDigest = scenarioManifestDigest(expanded);
+  const suiteDigest = liveSuiteManifestDigestForCase(caseRecord, authority);
+  const subjectId = resolved.route.subjectId;
+  return {
+    runKey: buildLabAutomationRunKey({
+      evidenceLayer: "live_route_compatibility",
+      subjectId,
+      suiteId: caseRecord.suite,
+      suiteVersion: authority.manifestDefaults.suiteVersion,
+      suiteManifestDigest: suiteDigest,
+      scenarioId: caseRecord.id,
+      scenarioVersion: authority.manifestDefaults.version,
+      scenarioManifestDigest: scenarioDigest,
+      executionContractDigest: liveExecutionContractDigest(),
+    }),
+    evidenceLayer: "live_route_compatibility",
+    suiteId: caseRecord.suite,
+    suiteVersion: authority.manifestDefaults.suiteVersion,
+    suiteManifestDigest: suiteDigest,
+    scenarioId: caseRecord.id,
+    scenarioVersion: authority.manifestDefaults.version,
+    scenarioManifestDigest: scenarioDigest,
+    subjectId,
+    reason: "missing",
+    priority: 0,
+    eligibleAt: now,
+    providerName: input.providerName,
+    modelId: input.modelId,
+  };
+}

package/src/lab/automation/policy.ts

@@ -0,0 +1,136 @@
+import {
+  LAB_AUTOMATION_DEFAULT_POLICY,
+  LAB_AUTOMATION_HARD_MAX,
+  LAB_AUTOMATION_POLICY_SCHEMA_VERSION,
+} from "./constants";
+import type { LabAutomationPolicyV1 } from "./types";
+import { LabAutomationError } from "./types";
+
+const POLICY_KEYS = new Set([
+  "schemaVersion",
+  "enabled",
+  "layers",
+  "refreshBeforeStaleMs",
+  "maxConcurrentRuns",
+  "maxConcurrentLiveRuns",
+  "maxConcurrentRunsPerRoute",
+  "maxRunsPerHour",
+  "maxLiveRequestsPerHour",
+  "failureCooldownMs",
+  "blockedCooldownMs",
+  "taskEffectivenessBackgroundEnabled",
+]);
+const LAYER_KEYS = new Set([
+  "protocolConformance",
+  "liveRouteCompatibility",
+  "taskEffectiveness",
+]);
+
+function assertClosedKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, field: string): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new LabAutomationError(`unknown ${field} field ${key}`, "invalid_policy");
+    }
+  }
+}
+
+function assertBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new LabAutomationError(`invalid policy field ${field}`, "invalid_policy");
+  return value;
+}
+
+function assertNonNegativeInt(value: unknown, field: string, max: number): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new LabAutomationError(`invalid policy field ${field}`, "invalid_policy");
+  }
+  if (value > max) {
+    throw new LabAutomationError(`policy field ${field} exceeds hard maximum`, "invalid_policy");
+  }
+  return value;
+}
+
+function assertPositiveInt(value: unknown, field: string, max: number): number {
+  const parsed = assertNonNegativeInt(value, field, max);
+  if (parsed === 0) {
+    throw new LabAutomationError(`policy field ${field} must be at least 1`, "invalid_policy");
+  }
+  return parsed;
+}
+
+/** Validate and normalize automation policy with a closed schema and hard upper bounds. */
+export function normalizeLabAutomationPolicyV1(raw: unknown): LabAutomationPolicyV1 {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new LabAutomationError("policy must be an object", "invalid_policy");
+  }
+  const obj = raw as Record<string, unknown>;
+  assertClosedKeys(obj, POLICY_KEYS, "policy");
+  if (obj.schemaVersion !== LAB_AUTOMATION_POLICY_SCHEMA_VERSION) {
+    throw new LabAutomationError("unsupported policy schemaVersion", "invalid_policy");
+  }
+  const layersRaw = obj.layers;
+  if (!layersRaw || typeof layersRaw !== "object" || Array.isArray(layersRaw)) {
+    throw new LabAutomationError("invalid policy layers", "invalid_policy");
+  }
+  const layersObj = layersRaw as Record<string, unknown>;
+  assertClosedKeys(layersObj, LAYER_KEYS, "layers");
+  const taskBackground = assertBoolean(obj.taskEffectivenessBackgroundEnabled, "taskEffectivenessBackgroundEnabled");
+  const layers = {
+    protocolConformance: assertBoolean(layersObj.protocolConformance, "layers.protocolConformance"),
+    liveRouteCompatibility: assertBoolean(layersObj.liveRouteCompatibility, "layers.liveRouteCompatibility"),
+    taskEffectiveness: assertBoolean(layersObj.taskEffectiveness, "layers.taskEffectiveness"),
+  };
+  if (taskBackground && !layers.taskEffectiveness) {
+    throw new LabAutomationError("task background requires task_effectiveness layer", "invalid_policy");
+  }
+  return Object.freeze({
+    schemaVersion: LAB_AUTOMATION_POLICY_SCHEMA_VERSION,
+    enabled: assertBoolean(obj.enabled, "enabled"),
+    layers: Object.freeze(layers),
+    refreshBeforeStaleMs: assertNonNegativeInt(
+      obj.refreshBeforeStaleMs,
+      "refreshBeforeStaleMs",
+      LAB_AUTOMATION_HARD_MAX.refreshBeforeStaleMs,
+    ),
+    maxConcurrentRuns: assertPositiveInt(
+      obj.maxConcurrentRuns,
+      "maxConcurrentRuns",
+      LAB_AUTOMATION_HARD_MAX.maxConcurrentRuns,
+    ),
+    maxConcurrentLiveRuns: assertPositiveInt(
+      obj.maxConcurrentLiveRuns,
+      "maxConcurrentLiveRuns",
+      LAB_AUTOMATION_HARD_MAX.maxConcurrentLiveRuns,
+    ),
+    maxConcurrentRunsPerRoute: assertPositiveInt(
+      obj.maxConcurrentRunsPerRoute,
+      "maxConcurrentRunsPerRoute",
+      LAB_AUTOMATION_HARD_MAX.maxConcurrentRunsPerRoute,
+    ),
+    maxRunsPerHour: assertNonNegativeInt(
+      obj.maxRunsPerHour,
+      "maxRunsPerHour",
+      LAB_AUTOMATION_HARD_MAX.maxRunsPerHour,
+    ),
+    maxLiveRequestsPerHour: assertNonNegativeInt(
+      obj.maxLiveRequestsPerHour,
+      "maxLiveRequestsPerHour",
+      LAB_AUTOMATION_HARD_MAX.maxLiveRequestsPerHour,
+    ),
+    failureCooldownMs: assertNonNegativeInt(
+      obj.failureCooldownMs,
+      "failureCooldownMs",
+      LAB_AUTOMATION_HARD_MAX.failureCooldownMs,
+    ),
+    blockedCooldownMs: assertNonNegativeInt(
+      obj.blockedCooldownMs,
+      "blockedCooldownMs",
+      LAB_AUTOMATION_HARD_MAX.blockedCooldownMs,
+    ),
+    taskEffectivenessBackgroundEnabled: taskBackground,
+  });
+}
+
+/** Default-off automation policy for new installations. */
+export function defaultLabAutomationPolicyV1(): LabAutomationPolicyV1 {
+  return normalizeLabAutomationPolicyV1({ ...LAB_AUTOMATION_DEFAULT_POLICY });
+}

package/src/lab/automation/queue.ts

@@ -0,0 +1,191 @@
+import { randomUUID } from "node:crypto";
+import {
+  LabAutomationError,
+  type LabAutomationPolicyV1,
+  type LabAutomationRunRecordV1,
+  type LabAutomationRunState,
+  type LabAutomationStateV1,
+  type PlannedLabRunV1,
+} from "./types";
+import { LAB_AUTOMATION_HARD_MAX } from "./constants";
+
+const TERMINAL_STATES = new Set<LabAutomationRunState>([
+  "completed",
+  "blocked",
+  "failed",
+  "cancelled",
+  "abandoned",
+]);
+
+function isTerminal(run: LabAutomationRunRecordV1): boolean {
+  return TERMINAL_STATES.has(run.state);
+}
+
+function isRollingBudgetEvidence(run: LabAutomationRunRecordV1, now: number): boolean {
+  if (typeof run.startedAt !== "number") return false;
+  const cutoff = now - LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+  return run.startedAt > cutoff && run.startedAt <= now;
+}
+
+/** Evict only disposable terminal history; rolling budget records remain authority. */
+function evictOldestTerminal(runs: LabAutomationRunRecordV1[], now: number): boolean {
+  let oldestIndex = -1;
+  let oldestTime = Number.POSITIVE_INFINITY;
+  for (let index = 0; index < runs.length; index += 1) {
+    const run = runs[index]!;
+    if (!isTerminal(run) || isRollingBudgetEvidence(run, now)) continue;
+    const terminalAt = run.completedAt ?? run.updatedAt;
+    if (terminalAt < oldestTime) {
+      oldestTime = terminalAt;
+      oldestIndex = index;
+    }
+  }
+  if (oldestIndex < 0) return false;
+  runs.splice(oldestIndex, 1);
+  return true;
+}
+
+export function countRunsByState(state: LabAutomationStateV1, runState: LabAutomationRunState): number {
+  return state.runs.filter((row) => row.state === runState).length;
+}
+
+export function countRunningLive(state: LabAutomationStateV1): number {
+  return state.runs.filter((row) => row.state === "running" && row.evidenceLayer === "live_route_compatibility").length;
+}
+
+export function countRunningForRoute(state: LabAutomationStateV1, subjectId: string): number {
+  return state.runs.filter((row) => row.state === "running" && row.subjectId === subjectId).length;
+}
+
+export function findRunById(state: LabAutomationStateV1, runId: string): LabAutomationRunRecordV1 | undefined {
+  return state.runs.find((row) => row.runId === runId);
+}
+
+export function enqueuePlannedRuns(
+  state: LabAutomationStateV1,
+  planned: PlannedLabRunV1[],
+  trigger: LabAutomationRunRecordV1["trigger"],
+  now: number,
+): LabAutomationStateV1 {
+  const existingActiveKeys = new Set(
+    state.runs
+      .filter((row) => row.state === "queued" || row.state === "running")
+      .map((row) => row.runKey),
+  );
+  const runs = [...state.runs];
+  let queuedCount = runs.filter((row) => row.state === "queued").length;
+  for (const plan of planned) {
+    if (existingActiveKeys.has(plan.runKey)) continue;
+    if (queuedCount >= LAB_AUTOMATION_HARD_MAX.maxQueuedRuns) break;
+    while (runs.length >= LAB_AUTOMATION_HARD_MAX.maxPersistedRuns) {
+      if (!evictOldestTerminal(runs, now)) return { ...state, runs };
+    }
+    runs.push({
+      runId: randomUUID(),
+      runKey: plan.runKey,
+      state: "queued",
+      evidenceLayer: plan.evidenceLayer,
+      suiteId: plan.suiteId,
+      suiteVersion: plan.suiteVersion,
+      suiteManifestDigest: plan.suiteManifestDigest,
+      scenarioId: plan.scenarioId,
+      scenarioVersion: plan.scenarioVersion,
+      scenarioManifestDigest: plan.scenarioManifestDigest,
+      subjectId: plan.subjectId,
+      reason: plan.reason,
+      priority: plan.priority,
+      eligibleAt: plan.eligibleAt,
+      trigger,
+      createdAt: now,
+      updatedAt: now,
+      ...(plan.providerName ? { providerName: plan.providerName } : {}),
+      ...(plan.modelId ? { modelId: plan.modelId } : {}),
+    });
+    queuedCount += 1;
+    existingActiveKeys.add(plan.runKey);
+  }
+  return { ...state, runs };
+}
+
+export function transitionRun(
+  state: LabAutomationStateV1,
+  runId: string,
+  next: LabAutomationRunState,
+  now: number,
+  terminalCode?: string,
+): LabAutomationStateV1 {
+  const runs = state.runs.map((row) => {
+    if (row.runId !== runId) return row;
+    return {
+      ...row,
+      state: next,
+      updatedAt: now,
+      ...(next === "running" ? { startedAt: now } : {}),
+      ...(next === "completed" || next === "blocked" || next === "failed" || next === "cancelled" || next === "abandoned"
+        ? { completedAt: now, ...(terminalCode ? { terminalCode } : {}) }
+        : {}),
+    };
+  });
+  return { ...state, runs };
+}
+
+export function cancelQueuedRun(state: LabAutomationStateV1, runId: string, now: number): LabAutomationStateV1 {
+  const run = findRunById(state, runId);
+  if (!run || run.state !== "queued") return state;
+  return transitionRun(state, runId, "cancelled", now, "cancelled");
+}
+
+export function selectDispatchableRuns(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now: number,
+  predicate: (run: LabAutomationRunRecordV1) => boolean = () => true,
+): LabAutomationRunRecordV1[] {
+  const running = countRunsByState(state, "running");
+  if (running >= policy.maxConcurrentRuns) return [];
+  const slots = policy.maxConcurrentRuns - running;
+  const queued = state.runs
+    .filter((row) => row.state === "queued" && row.eligibleAt <= now && predicate(row))
+    .sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      if (a.eligibleAt !== b.eligibleAt) return a.eligibleAt - b.eligibleAt;
+      return a.runId < b.runId ? -1 : 1;
+    });
+  const selected: LabAutomationRunRecordV1[] = [];
+  const selectedPerRoute = new Map<string, number>();
+  let liveRunning = countRunningLive(state);
+  for (const row of queued) {
+    if (selected.length >= slots) break;
+    const runningForRoute = countRunningForRoute(state, row.subjectId);
+    const selectedForRoute = selectedPerRoute.get(row.subjectId) ?? 0;
+    if (runningForRoute + selectedForRoute >= policy.maxConcurrentRunsPerRoute) continue;
+    if (row.evidenceLayer === "live_route_compatibility") {
+      if (liveRunning >= policy.maxConcurrentLiveRuns) continue;
+    }
+    selected.push(row);
+    selectedPerRoute.set(row.subjectId, selectedForRoute + 1);
+    if (row.evidenceLayer === "live_route_compatibility") liveRunning += 1;
+  }
+  return selected;
+}
+
+export function trimTerminalRuns(state: LabAutomationStateV1, now: number): LabAutomationStateV1 {
+  const keepMs = LAB_AUTOMATION_HARD_MAX.terminalRunRetentionMs;
+  const runs = state.runs.filter((row) => {
+    if (!isTerminal(row)) return true;
+    // The retention window exceeds the rolling budget window. Keep budget evidence explicit
+    // so a future retention reduction cannot over-grant the hourly run budgets.
+    if (isRollingBudgetEvidence(row, now)) return true;
+    const completedAt = row.completedAt ?? row.updatedAt;
+    return now - completedAt < keepMs;
+  });
+  while (runs.length > LAB_AUTOMATION_HARD_MAX.maxPersistedRuns) {
+    if (!evictOldestTerminal(runs, now)) {
+      throw new LabAutomationError(
+        "persisted run ceiling exceeded by non-disposable run records",
+        "invalid_state",
+      );
+    }
+  }
+  return { ...state, runs };
+}