@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/lab/observe/from-live.ts

@@ -0,0 +1,103 @@
+// CL-03 live result -> CL-02 immutable observation persistence.
+import { createArtifactStore, type ArtifactStore } from "../artifacts/store";
+import { sanitizeDiagnostic, truncateUtf8 } from "../artifacts/sanitize";
+import { LAB_EVENT_SCHEMA_VERSION, LAB_PRODUCER, LAB_PRODUCER_VERSION, OBSERVATION_LIMIT_NAMES, type ObservationOutcome } from "../constants";
+import { fixtureDigest, scenarioManifestDigest, subjectIdForSubject, suiteManifestDigest } from "../digest";
+import type { FailureRecordV1, ObservationEvent } from "../events/types";
+import { assignEventId } from "../events/validate";
+import { appendLabEvent } from "../ledger/store";
+import { ensureLabDirs } from "../paths";
+import type { CaseAuthority, CaseRecord } from "../conformance/types";
+import { trustedLiveResultRetryable } from "../live/executor";
+import { expandLiveScenario } from "../live/manifest";
+import { liveSuiteManifestObjectForCase } from "../live/suite-manifest";
+import type { LiveScenarioRunResult } from "../live/types";
+
+export interface PersistLiveOptions { configDir?: string; recordedAt?: number; startedAt?: number; completedAt?: number; producerVersion?: string; artifactStore?: ArtifactStore }
+export interface PersistedLiveObservation { event: ObservationEvent; ledgerPath: string }
+
+function outcomeFromLiveResult(result: LiveScenarioRunResult): ObservationOutcome {
+  if (result.passed) return "pass";
+  switch (result.classification) {
+    case "timeout":
+    case "budget_exhausted":
+    case "authentication_blocked":
+    case "quota_blocked":
+    case "region_blocked":
+    case "network_failure":
+    case "provider_transient":
+      return "blocked";
+    case "protocol_failure":
+    case "capability_failure":
+    case "behavioral_failure":
+      return "fail";
+    case "inconclusive":
+    case "harness_failure":
+      return "inconclusive";
+  }
+}
+
+function failureFromLiveResult(result: LiveScenarioRunResult, retryable: boolean): FailureRecordV1 | undefined {
+  if (result.passed || result.classification === "inconclusive") return undefined;
+  const attribution: FailureRecordV1["attribution"] = result.classification === "harness_failure"
+    ? "harness"
+    : ["authentication_blocked", "quota_blocked", "region_blocked", "network_failure", "provider_transient", "timeout", "budget_exhausted"].includes(result.classification)
+      ? "environment"
+      : "route";
+  return {
+    class: result.classification,
+    code: result.secondaryCode ?? result.classification,
+    retryable,
+    attribution,
+  };
+}
+
+function requireExecutionTimes(result: LiveScenarioRunResult, opts: PersistLiveOptions): { startedAt: number; completedAt: number } {
+  const startedAt = opts.startedAt ?? result.startedAt; const completedAt = opts.completedAt ?? result.completedAt;
+  if (!Number.isInteger(startedAt) || !Number.isInteger(completedAt) || startedAt < 0 || completedAt < startedAt) throw new Error("invalid persisted live execution timestamps");
+  return { startedAt, completedAt };
+}
+
+export function observationFromLiveResult(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority, opts: PersistLiveOptions = {}): { event: ObservationEvent; artifacts: ReturnType<ArtifactStore["put"]>[] } {
+  const retryable = trustedLiveResultRetryable(result, caseRecord, authority);
+  if (!result.routeSubject) throw new Error("live evidence without an exact RouteSubjectV1 is not persistable");
+  const { startedAt, completedAt } = requireExecutionTimes(result, opts);
+  const paths = ensureLabDirs(opts.configDir); const ownsStore = !opts.artifactStore; const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
+  try {
+    const recordedAt = opts.recordedAt ?? completedAt;
+    const expandedScenario = expandLiveScenario(caseRecord, authority); const scenarioDigest = scenarioManifestDigest(expandedScenario);
+    const suiteExpanded = liveSuiteManifestObjectForCase(caseRecord, authority); const suiteDigest = suiteManifestDigest(suiteExpanded);
+    const fixtureDigests: string[] = []; const artifacts: ReturnType<ArtifactStore["put"]>[] = [];
+    const putFixture = (fixture: CaseRecord["fixture"]) => {
+      const bytes = new TextEncoder().encode(fixture.bytesUtf8); const digest = fixtureDigest(bytes); fixtureDigests.push(digest);
+      artifacts.push(store.put({ artifactClass: "fixture", payload: bytes, expectedDigest: digest, mediaType: fixture.mediaType }));
+    };
+    putFixture(caseRecord.fixture); if (caseRecord.initiatingRequest) putFixture(caseRecord.initiatingRequest);
+    artifacts.push(store.put({ artifactClass: "scenario_manifest", payload: expandedScenario, expectedDigest: scenarioDigest }));
+    artifacts.push(store.put({ artifactClass: "suite_manifest", payload: suiteExpanded, expectedDigest: suiteDigest }));
+    artifacts.push(store.put({ artifactClass: "assertion_report", payload: { scenarioId: result.scenarioId, passed: result.passed, classification: result.classification,
+      assertions: result.assertionResults.map((row) => ({ id: row.id, operator: row.operator, required: row.required, passed: row.passed, observedSummary: row.observedSummary, reason: row.reason })) } }));
+    const subject = result.routeSubject; const subjectId = subjectIdForSubject(subject); const authorityLimits = authority.manifestDefaults.executionLimits;
+    const limits: Record<string, number | null> = {}; for (const key of OBSERVATION_LIMIT_NAMES) if (key in authorityLimits) limits[key] = authorityLimits[key] ?? null;
+    const failure = failureFromLiveResult(result, retryable);
+    const eventWithoutId = {
+      schemaVersion: LAB_EVENT_SCHEMA_VERSION, eventKind: "observation" as const, recordedAt, producer: LAB_PRODUCER, producerVersion: opts.producerVersion ?? LAB_PRODUCER_VERSION,
+      evidenceLayer: "live_route_compatibility" as const, scenarioId: caseRecord.id, scenarioVersion: String(authority.manifestDefaults.version), scenarioManifestDigest: scenarioDigest,
+      suiteId: caseRecord.suite, suiteVersion: String(authority.manifestDefaults.suiteVersion), suiteManifestDigest: suiteDigest, fixtureDigests, subject, subjectId,
+      startedAt, completedAt, executionMode: "live" as const, attempt: 1, limits, outcome: outcomeFromLiveResult(result),
+      // Sanitize before truncating: the reverse order can split a redaction
+      // target and persist a fragment of the raw value.
+      assertions: result.assertionResults.map((row) => ({ id: row.id, operator: row.operator, required: row.required, passed: row.passed, expectedSummary: "see_assertion_report", observedSummary: truncateUtf8(sanitizeDiagnostic(row.observedSummary), 512), ...(row.reason ? { reason: row.reason } : {}) })),
+      ...(caseRecord.expectedFailure ? { expectedFailure: { ...caseRecord.expectedFailure } } : {}),
+      environment: { runtime: { platform: process.platform, arch: process.arch, bunVersion: process.versions.bun ?? Bun.version } }, artifactRefs: artifacts,
+      ...(failure ? { failure } : {}),
+    };
+    return { event: assignEventId(eventWithoutId) as ObservationEvent, artifacts };
+  } finally { if (ownsStore) store.close(); }
+}
+
+export function persistLiveResult(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority, opts: PersistLiveOptions = {}): PersistedLiveObservation {
+  const paths = ensureLabDirs(opts.configDir); const ownsStore = !opts.artifactStore; const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
+  try { const { event } = observationFromLiveResult(result, caseRecord, authority, { ...opts, artifactStore: store }); appendLabEvent(paths.ledgerPath, event); return { event, ledgerPath: paths.ledgerPath }; }
+  finally { if (ownsStore) store.close(); }
+}

package/src/lab/paths.ts

@@ -0,0 +1,65 @@
+import { chmodSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+
+function ensureRestrictedDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") return;
+  const mode = statSync(dir).mode & 0o777;
+  if (mode !== 0o700) chmodSync(dir, 0o700);
+}
+
+/** Canonical Compatibility Lab state root under the OpenCodex config dir. */
+export function labRoot(configDir = getConfigDir()): string {
+  return join(configDir, "lab");
+}
+
+export function labLedgerPath(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "compatibility.jsonl");
+}
+
+export function labSqlitePath(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "compatibility.sqlite");
+}
+
+export function labArtifactsDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "artifacts");
+}
+
+export function labScratchDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "scratch");
+}
+
+export function labExportDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "export");
+}
+
+/** Opaque per-installation salt for local fingerprinting (never exported as evidence). */
+export function labInstallationSaltPath(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "installation-salt.bin");
+}
+
+/** Ensure lab directories exist with restrictive permissions where the platform allows. */
+export function ensureLabDirs(configDir = getConfigDir()): {
+  root: string;
+  ledgerPath: string;
+  sqlitePath: string;
+  artifactsDir: string;
+  scratchDir: string;
+  exportDir: string;
+} {
+  const root = labRoot(configDir);
+  const artifactsDir = labArtifactsDir(configDir);
+  const scratchDir = labScratchDir(configDir);
+  const exportDir = labExportDir(configDir);
+  ensureRestrictedDir(root);
+  ensureRestrictedDir(artifactsDir);
+  return {
+    root,
+    ledgerPath: labLedgerPath(configDir),
+    sqlitePath: labSqlitePath(configDir),
+    artifactsDir,
+    scratchDir,
+    exportDir,
+  };
+}

package/src/lab/projection/rebuild.ts

@@ -0,0 +1,477 @@
+import { Database } from "bun:sqlite";
+import { existsSync, unlinkSync } from "node:fs";
+import { createArtifactStore, loadClaimSourceManifest } from "../artifacts/store";
+import { ArtifactFsError } from "../artifacts/secure-fs";
+import { sanitizeDiagnostic } from "../artifacts/sanitize";
+import { LAB_PROJECTION_SPEC_VERSION } from "../constants";
+import { expandScenario, loadCaseAuthority } from "../conformance/manifest";
+import { scenarioManifestDigest, jcsStringify } from "../digest";
+import {
+  parseSuiteManifestFromArtifact,
+  type ScenarioRequirements,
+} from "./verification";
+import type { ClaimSnapshotEvent, LabEvent, LedgerCorruption } from "../events/types";
+import { buildInvalidationIndex, isEventExcluded } from "../ledger/invalidation";
+import { replayLabLedger } from "../ledger/store";
+import { ensureLabDirs } from "../paths";
+import { LAB_SQLITE_DDL, LAB_SQLITE_SCHEMA_VERSION } from "./schema";
+import {
+  claimKeyString,
+  excludeEventIds,
+  projectVerdicts,
+  projectionKeyString,
+  resolveClaimStates,
+} from "./verdicts";
+
+export interface RebuildResult {
+  events: number;
+  verdicts: number;
+  corruptions: LedgerCorruption[];
+  sqlitePath: string;
+}
+
+function wipeSqlite(path: string): void {
+  for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+    let removed = false;
+    for (let attempt = 0; attempt < 8; attempt++) {
+      try {
+        if (existsSync(candidate)) unlinkSync(candidate);
+        removed = true;
+        break;
+      } catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+          ? String((err as { code: unknown }).code)
+          : "";
+        if (code !== "EBUSY" && code !== "EPERM") throw err;
+        if (attempt < 7) Bun.sleepSync(20 * (attempt + 1));
+      }
+    }
+    if (!removed) {
+      throw new Error(`failed to remove stale projection file after retries: ${candidate}`);
+    }
+  }
+}
+
+function resetProjectionSchema(db: Database): void {
+  db.exec(`
+    DROP TABLE IF EXISTS verdicts;
+    DROP TABLE IF EXISTS corruption;
+    DROP TABLE IF EXISTS artifacts;
+    DROP TABLE IF EXISTS purges;
+    DROP TABLE IF EXISTS invalidations;
+    DROP TABLE IF EXISTS claims;
+    DROP TABLE IF EXISTS observations;
+    DROP TABLE IF EXISTS subjects;
+    DROP TABLE IF EXISTS events;
+    DROP TABLE IF EXISTS schema_meta;
+  `);
+  db.exec(LAB_SQLITE_DDL);
+}
+
+interface ArtifactValidationResult {
+  unusableObservationIds: Set<string>;
+  unusableClaimEventIds: Set<string>;
+}
+
+/**
+ * Deterministic rebuild:
+ * delete compatibility.sqlite → replay JSONL → validate artifacts → project.
+ */
+export function rebuildLabProjection(configDir?: string): RebuildResult {
+  const paths = ensureLabDirs(configDir);
+  wipeSqlite(paths.sqlitePath);
+
+  const replay = replayLabLedger(paths.ledgerPath);
+  const corruptions: LedgerCorruption[] = [...replay.corruptions];
+  const index = buildInvalidationIndex(replay.events);
+  corruptions.push(...index.corruptions);
+
+  const artifactStore = createArtifactStore(paths.artifactsDir);
+  const validation = validateRequiredArtifacts(replay.events, index, artifactStore, corruptions);
+
+  const authority = loadCaseAuthority();
+  const scenarioRequirementsByDigest = new Map<string, ScenarioRequirements>();
+  for (const caseRecord of authority.cases) {
+    const expanded = expandScenario(caseRecord, authority);
+    scenarioRequirementsByDigest.set(scenarioManifestDigest(expanded), {
+      inboundProtocols: [...caseRecord.requirements.inboundProtocols],
+      upstreamProtocols: [...caseRecord.requirements.upstreamProtocols],
+      surfaces: [...caseRecord.requirements.surfaces],
+      freshness: { ...authority.manifestDefaults.freshness },
+    });
+  }
+
+  const loadSuiteManifest = (digest: string) => {
+    try {
+      const bytes = artifactStore.get(digest, { artifactClass: "suite_manifest" });
+      const parsed = JSON.parse(new TextDecoder().decode(bytes));
+      return parseSuiteManifestFromArtifact(parsed);
+    } catch {
+      return null;
+    }
+  };
+  const loadScenarioManifest = (digest: string) => {
+    try {
+      const bytes = artifactStore.get(digest, { artifactClass: "scenario_manifest" });
+      return JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  };
+  const loadScenarioRequirements = (digest: string) => scenarioRequirementsByDigest.get(digest) ?? null;
+
+  const db = new Database(paths.sqlitePath);
+  let transactionOpen = false;
+  try {
+    db.exec("PRAGMA journal_mode=DELETE;");
+    db.exec("PRAGMA foreign_keys=OFF;");
+    db.exec("BEGIN IMMEDIATE;");
+    transactionOpen = true;
+    resetProjectionSchema(db);
+
+    db.prepare(
+      "INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)",
+    ).run("schema_version", String(LAB_SQLITE_SCHEMA_VERSION));
+    db.prepare(
+      "INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)",
+    ).run("projection_spec_version", LAB_PROJECTION_SPEC_VERSION);
+    db.prepare(
+      "INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)",
+    ).run("built_at_ms", String(Date.now()));
+
+    const insertCorruption = db.prepare(
+      "INSERT INTO corruption(kind, line_number, event_id, detail) VALUES (?, ?, ?, ?)",
+    );
+    for (const c of corruptions) {
+      insertCorruption.run(c.kind, c.lineNumber ?? null, c.eventId ?? null, c.detail);
+    }
+
+    const insertEvent = db.prepare(
+      `INSERT INTO events(event_id, event_kind, recorded_at, producer, producer_version, payload_json, excluded, exclusion_reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insertSubject = db.prepare(
+      `INSERT OR IGNORE INTO subjects(subject_id, subject_kind, subject_json) VALUES (?, ?, ?)`,
+    );
+    const insertObs = db.prepare(
+      `INSERT INTO observations(
+         event_id, subject_id, evidence_layer, suite_id, suite_version, suite_manifest_digest,
+         scenario_id, scenario_version, scenario_manifest_digest, outcome, completed_at, execution_mode
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insertClaim = db.prepare(
+      `INSERT INTO claims(
+         event_id, subject_id, capability, polarity, source_manifest_digest,
+         effective_at, recorded_at, supersedes_json, current, usable
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insertInv = db.prepare(
+      `INSERT INTO invalidations(event_id, reason, targets_json, recorded_at, applied) VALUES (?, ?, ?, ?, ?)`,
+    );
+    const insertPurge = db.prepare(
+      `INSERT INTO purges(event_id, target_event_ids_json, target_artifact_digests_json, purge_actions_json, recorded_at)
+       VALUES (?, ?, ?, ?, ?)`,
+    );
+    const insertArtifact = db.prepare(
+      `INSERT INTO artifacts(digest, artifact_class, media_type, byte_count, status, last_error)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(digest) DO UPDATE SET
+         artifact_class = COALESCE(excluded.artifact_class, artifacts.artifact_class),
+         media_type = COALESCE(excluded.media_type, artifacts.media_type),
+         byte_count = COALESCE(excluded.byte_count, artifacts.byte_count),
+         status = CASE
+           WHEN artifacts.status = 'purged_unavailable' OR excluded.status = 'purged_unavailable'
+             THEN 'purged_unavailable'
+           WHEN artifacts.status = 'corrupt' OR excluded.status = 'corrupt'
+             THEN 'corrupt'
+           ELSE 'present'
+         END,
+         last_error = COALESCE(excluded.last_error, artifacts.last_error)`,
+    );
+
+    const excluded = excludeEventIds(index);
+    const usableClaimEvents = replay.events.filter(
+      (e): e is ClaimSnapshotEvent =>
+        e.eventKind === "claim_snapshot" && !isEventExcluded(e.eventId, index),
+    );
+    const claimStates = resolveClaimStates(usableClaimEvents, {
+      unusableClaimEventIds: validation.unusableClaimEventIds,
+      purgedEventIds: index.purgedEventIds,
+    });
+
+    for (const event of replay.events) {
+      const isExcluded = excluded.has(event.eventId);
+      let exclusionReason: string | null = null;
+      if (index.purgedEventIds.has(event.eventId)) exclusionReason = "purged";
+      else if (index.invalidatedBy.has(event.eventId)) exclusionReason = "invalidated";
+
+      insertEvent.run(
+        event.eventId,
+        event.eventKind,
+        event.recordedAt,
+        event.producer,
+        event.producerVersion,
+        jcsStringify(event),
+        isExcluded ? 1 : 0,
+        exclusionReason,
+      );
+
+      if (event.eventKind === "observation") {
+        insertSubject.run(event.subjectId, event.subject.subjectKind, jcsStringify(event.subject));
+        const usable = !isExcluded && !validation.unusableObservationIds.has(event.eventId);
+        if (usable) {
+          insertObs.run(
+            event.eventId,
+            event.subjectId,
+            event.evidenceLayer,
+            event.suiteId,
+            event.suiteVersion,
+            event.suiteManifestDigest,
+            event.scenarioId,
+            event.scenarioVersion,
+            event.scenarioManifestDigest,
+            event.outcome,
+            event.completedAt,
+            event.executionMode,
+          );
+        }
+        for (const ref of event.artifactRefs) {
+          const purged = index.purgedArtifactDigests.has(ref.digest);
+          const corrupt = validation.unusableObservationIds.has(event.eventId);
+          insertArtifact.run(
+            ref.digest,
+            ref.artifactClass,
+            ref.mediaType,
+            ref.byteCount,
+            purged ? "purged_unavailable" : corrupt ? "corrupt" : "present",
+            corrupt ? "required artifact unusable" : null,
+          );
+        }
+      } else if (event.eventKind === "claim_snapshot") {
+        insertSubject.run(event.subjectId, event.subject.subjectKind, jcsStringify(event.subject));
+        const key = claimKeyString(event.subjectId, event.capability);
+        const state = claimStates.states.get(key);
+        const current = state?.current?.eventId === event.eventId ? 1 : 0;
+        const claimCorruption = corruptions.find(
+          (c) => c.kind === "claim_corruption" && c.eventId === event.eventId,
+        );
+        const usable = !isExcluded && !state?.corruption &&
+          !validation.unusableClaimEventIds.has(event.eventId) ? 1 : 0;
+
+        if (!isExcluded) {
+          insertArtifact.run(
+            event.sourceManifestDigest,
+            "claim_source_manifest",
+            "application/json",
+            null,
+            claimCorruption ? "corrupt" : "present",
+            claimCorruption?.detail ?? null,
+          );
+        }
+
+        insertClaim.run(
+          event.eventId,
+          event.subjectId,
+          event.capability,
+          event.polarity,
+          event.sourceManifestDigest,
+          event.effectiveAt,
+          event.recordedAt,
+          jcsStringify(event.supersedes),
+          current,
+          usable,
+        );
+      } else if (event.eventKind === "invalidation") {
+        const applied = !corruptions.some((c) => c.eventId === event.eventId && c.kind === "invalid_reference");
+        insertInv.run(
+          event.eventId,
+          event.reason,
+          jcsStringify(event.targetEventIds),
+          event.recordedAt,
+          applied ? 1 : 0,
+        );
+      } else if (event.eventKind === "purge_tombstone") {
+        insertPurge.run(
+          event.eventId,
+          jcsStringify(event.targetEventIds),
+          jcsStringify(event.targetArtifactDigests),
+          jcsStringify(event.purgeActions),
+          event.recordedAt,
+        );
+        for (const digest of event.targetArtifactDigests) {
+          insertArtifact.run(digest, null, null, null, "purged_unavailable", null);
+        }
+      }
+    }
+
+    const { verdicts, corruptions: verdictCorruptions } = projectVerdicts(replay.events, {
+      index,
+      unusableObservationIds: validation.unusableObservationIds,
+      unusableClaimEventIds: validation.unusableClaimEventIds,
+      loadSuiteManifest,
+      loadScenarioManifest,
+      loadScenarioRequirements,
+    });
+    for (const c of verdictCorruptions) {
+      if (!corruptions.some((x) => x.detail === c.detail && x.eventId === c.eventId)) {
+        corruptions.push(c);
+        insertCorruption.run(c.kind, c.lineNumber ?? null, c.eventId ?? null, c.detail);
+      }
+    }
+
+    const insertVerdict = db.prepare(
+      `INSERT INTO verdicts(
+         projection_key, subject_id, evidence_layer, suite_id, suite_version, suite_manifest_digest,
+         projection_spec_version, verdict, as_of, scenario_manifest_digests_json, claim_source_digest,
+         contributing_event_ids_json, contradicting_event_ids_json, notes_json
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    for (const v of verdicts) {
+      insertVerdict.run(
+        projectionKeyString(v.key),
+        v.key.subjectId,
+        v.key.evidenceLayer,
+        v.key.suiteId,
+        v.key.suiteVersion,
+        v.key.suiteManifestDigest,
+        v.key.projectionSpecVersion,
+        v.verdict,
+        v.asOf,
+        jcsStringify(v.scenarioManifestDigests),
+        v.claimSourceDigest ?? null,
+        jcsStringify(v.contributingEventIds),
+        jcsStringify(v.contradictingEventIds),
+        jcsStringify(v.notes),
+      );
+    }
+
+    db.exec("COMMIT;");
+    transactionOpen = false;
+    return {
+      events: replay.events.length,
+      verdicts: verdicts.length,
+      corruptions,
+      sqlitePath: paths.sqlitePath,
+    };
+  } catch (err) {
+    if (transactionOpen) {
+      try {
+        db.exec("ROLLBACK;");
+      } catch {
+        // Preserve the original rebuild failure.
+      }
+    }
+    throw err;
+  } finally {
+    try {
+      db.exec("PRAGMA foreign_keys=ON;");
+    } catch {
+      // Closing the disposable DB is still safe if pragma restoration fails.
+    }
+    db.close();
+    artifactStore.close();
+  }
+}
+
+function validateRequiredArtifacts(
+  events: LabEvent[],
+  index: ReturnType<typeof buildInvalidationIndex>,
+  artifactStore: ReturnType<typeof createArtifactStore>,
+  corruptions: LedgerCorruption[],
+): ArtifactValidationResult {
+  const unusableObservationIds = new Set<string>();
+  const unusableClaimEventIds = new Set<string>();
+
+  for (const event of events) {
+    if (isEventExcluded(event.eventId, index)) continue;
+    if (event.eventKind === "observation") {
+      const required: Array<{ digest: string; artifactClass: "scenario_manifest" | "suite_manifest" | "fixture" }> = [
+        { digest: event.scenarioManifestDigest, artifactClass: "scenario_manifest" },
+        { digest: event.suiteManifestDigest, artifactClass: "suite_manifest" },
+        ...event.fixtureDigests.map((digest) => ({ digest, artifactClass: "fixture" as const })),
+      ];
+      let unusable = false;
+      for (const { digest, artifactClass } of required) {
+        if (index.purgedArtifactDigests.has(digest)) {
+          corruptions.push({
+            kind: "missing_artifact",
+            eventId: event.eventId,
+            detail: `required artifact purged: ${digest}`,
+          });
+          unusable = true;
+          continue;
+        }
+        try {
+          artifactStore.get(digest, { artifactClass });
+        } catch (err) {
+          const detail = sanitizeDiagnostic(err);
+          corruptions.push({
+            kind: err instanceof ArtifactFsError &&
+              (err.code === "artifact_mismatch" || err.message.includes("mismatch"))
+              ? "artifact_mismatch"
+              : "missing_artifact",
+            eventId: event.eventId,
+            detail,
+          });
+          unusable = true;
+        }
+      }
+      if (unusable) unusableObservationIds.add(event.eventId);
+      continue;
+    }
+
+    if (event.eventKind === "claim_snapshot") {
+      if (index.purgedArtifactDigests.has(event.sourceManifestDigest)) {
+        unusableClaimEventIds.add(event.eventId);
+        corruptions.push({
+          kind: "claim_corruption",
+          eventId: event.eventId,
+          detail: `claim source artifact purged: ${event.sourceManifestDigest}`,
+        });
+        continue;
+      }
+      const loaded = loadClaimSourceManifest(artifactStore, event.sourceManifestDigest, {
+        subjectId: event.subjectId,
+        capability: event.capability,
+      });
+      if (!loaded.ok) {
+        unusableClaimEventIds.add(event.eventId);
+        corruptions.push({
+          kind: "claim_corruption",
+          eventId: event.eventId,
+          detail: loaded.corruption,
+        });
+      }
+    }
+  }
+
+  return { unusableObservationIds, unusableClaimEventIds };
+}
+
+/** Snapshot derived verdict rows for rebuild-determinism tests (excludes asOf wall clock). */
+export function readVerdictSnapshot(sqlitePath: string): unknown[] {
+  const db = new Database(sqlitePath, { readonly: true });
+  try {
+    return db
+      .query(
+        `SELECT projection_key, subject_id, evidence_layer, suite_id, suite_version,
+                suite_manifest_digest, projection_spec_version, verdict,
+                scenario_manifest_digests_json, claim_source_digest,
+                contributing_event_ids_json, contradicting_event_ids_json, notes_json
+         FROM verdicts ORDER BY projection_key`,
+      )
+      .all();
+  } finally {
+    db.close();
+  }
+}
+
+export function readCorruptionRows(sqlitePath: string): unknown[] {
+  const db = new Database(sqlitePath, { readonly: true });
+  try {
+    return db.query(`SELECT kind, line_number, event_id, detail FROM corruption ORDER BY id`).all();
+  } finally {
+    db.close();
+  }
+}