@bitkyc08/opencodex 2.19.0 → 2.21.0

package/src/lab/ledger/purge.ts

@@ -18,10 +18,11 @@ import {
   expandSensitiveArtifactEventTargets,
 } from "./artifact-refs";
 import { buildInvalidationIndex } from "./invalidation";
-import { appendLabEvent, replayLabLedger } from "./store";
+import { withLedgerMutation } from "./store";
 import { ensureLabDirs } from "../paths";
 import { rebuildLabProjection } from "../projection/rebuild";
 import { jcsStringify } from "../digest";
+import { purgeLocalPublicEvidenceCopies } from "../public/purge";
 import {
   closeSync,
   existsSync,
@@ -34,7 +35,7 @@ import {
   writeSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-
+ 
 export class PurgeError extends Error {
   readonly code: string;
   readonly completedActions: string[];
@@ -45,7 +46,7 @@ export class PurgeError extends Error {
     this.completedActions = [...completedActions];
   }
 }
-
+ 
 export interface SensitivePurgeRequest {
   configDir?: string;
   targetEventIds?: string[];
@@ -54,7 +55,7 @@ export interface SensitivePurgeRequest {
   recordedAt?: number;
   producerVersion?: string;
 }
-
+ 
 function writeAll(fd: number, bytes: Uint8Array): void {
   let offset = 0;
   while (offset < bytes.byteLength) {
@@ -63,7 +64,7 @@ function writeAll(fd: number, bytes: Uint8Array): void {
     offset += n;
   }
 }
-
+ 
 function atomicRewriteLedger(ledgerPath: string, events: LabEvent[]): void {
   const body = events.map((e) => jcsStringify(e)).join("\n") + (events.length ? "\n" : "");
   const bytes = new TextEncoder().encode(body);
@@ -90,7 +91,7 @@ function atomicRewriteLedger(ledgerPath: string, events: LabEvent[]): void {
     }
     throw err;
   }
-
+ 
   if (process.platform !== "win32") {
     try {
       const dirFd = openSync(parent, "r");
@@ -100,8 +101,6 @@ function atomicRewriteLedger(ledgerPath: string, events: LabEvent[]): void {
         closeSync(dirFd);
       }
     } catch (err) {
-      // The rename is already committed and visible. Report durability failure
-      // without pretending the ledger action can be rolled back.
       throw new PurgeError(
         "ledger_durability_failed",
         `ledger rewrite committed but directory fsync failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -110,7 +109,7 @@ function atomicRewriteLedger(ledgerPath: string, events: LabEvent[]): void {
     }
   }
 }
-
+ 
 function deleteArtifactsFailClosed(dir: TrustedArtifactDir, digests: string[]): void {
   const errors: string[] = [];
   for (const digest of digests) {
@@ -125,7 +124,7 @@ function deleteArtifactsFailClosed(dir: TrustedArtifactDir, digests: string[]):
     throw new PurgeError("artifact_delete_failed", errors.join("; "));
   }
 }
-
+ 
 function purgeBoundedDirectory(dirPath: string): void {
   if (!existsSync(dirPath)) return;
   const entries = readdirSync(dirPath, { withFileTypes: true });
@@ -141,7 +140,41 @@ function purgeBoundedDirectory(dirPath: string): void {
     }
   }
 }
-
+ 
+function normalizePurgeError(err: unknown, completed: readonly string[]): PurgeError {
+  if (err instanceof PurgeError) {
+    return new PurgeError(
+      err.code,
+      err.message,
+      [...new Set([...completed, ...err.completedActions])],
+    );
+  }
+  return new PurgeError(
+    "purge_failed",
+    err instanceof Error ? err.message : String(err),
+    [...completed],
+  );
+}
+ 
+function buildPurgeTombstone(
+  req: SensitivePurgeRequest,
+  removeIds: ReadonlySet<string>,
+  targetArtifactDigests: string[],
+  purgeActions: Array<(typeof PURGE_ACTIONS)[number]>,
+): PurgeTombstoneEvent {
+  return validateLabEvent(assignEventId({
+    schemaVersion: LAB_EVENT_SCHEMA_VERSION,
+    eventKind: "purge_tombstone" as const,
+    recordedAt: req.recordedAt ?? Date.now(),
+    producer: LAB_PRODUCER,
+    producerVersion: req.producerVersion ?? LAB_PRODUCER_VERSION,
+    targetEventIds: [...removeIds].sort(),
+    targetArtifactDigests,
+    reason: "sensitive_evidence" as const,
+    purgeActions,
+  })) as PurgeTombstoneEvent;
+}
+ 
 /**
  * Exceptional sensitive-evidence purge:
  * physically remove targeted JSONL lines and artifacts, append purge_tombstone,
@@ -153,89 +186,125 @@ export function purgeSensitiveEvidence(req: SensitivePurgeRequest): PurgeTombsto
   const targetArtifactDigests = [...(req.targetArtifactDigests ?? [])].sort();
   const purgeActions = [...(req.purgeActions ?? PURGE_ACTIONS)].sort();
   const explicitSensitive = new Set(targetArtifactDigests);
-
-  const replay = replayLabLedger(paths.ledgerPath);
-  const index = buildInvalidationIndex(replay.events);
-  const removeIds = expandSensitiveArtifactEventTargets(
-    replay.events,
-    index,
-    new Set(targetEventIds),
-    explicitSensitive,
-  );
-
-  const tombstonePayload = {
-    schemaVersion: LAB_EVENT_SCHEMA_VERSION,
-    eventKind: "purge_tombstone" as const,
-    recordedAt: req.recordedAt ?? Date.now(),
-    producer: LAB_PRODUCER,
-    producerVersion: req.producerVersion ?? LAB_PRODUCER_VERSION,
-    targetEventIds: [...removeIds].sort(),
-    targetArtifactDigests,
-    reason: "sensitive_evidence" as const,
-    purgeActions,
-  };
-  const tombstone = validateLabEvent(assignEventId(tombstonePayload)) as PurgeTombstoneEvent;
-
-  const deletionPlan = purgeActions.includes("artifact")
-    ? artifactDeletionPlan(replay.events, index, removeIds, targetArtifactDigests)
-    : { deletable: [], retainedExplicit: [] };
-
-  if (deletionPlan.retainedExplicit.length > 0) {
-    throw new PurgeError(
-      "sensitive_bytes_retained",
-      `explicit sensitive artifacts remain required: ${deletionPlan.retainedExplicit.join(",")}`,
-    );
-  }
-
-  let dir: TrustedArtifactDir | null = null;
   const completed: string[] = [];
+  // Cell object: the mutation callback assigns through the property, which keeps
+  // the post-mutation read at the declared type (a closure-captured let would
+  // narrow to null and break the combined-error report below).
+  const deferredExport: { error: PurgeError | null } = { error: null };
+  let operationError: PurgeError | null = null;
+  let tombstone: PurgeTombstoneEvent | null = null;
+ 
   try {
-    if (purgeActions.includes("scratch")) {
-      purgeBoundedDirectory(paths.scratchDir);
-      completed.push("scratch");
-    }
-    if (purgeActions.includes("export")) {
-      purgeBoundedDirectory(paths.exportDir);
-      completed.push("export");
-    }
-
-    if (purgeActions.includes("artifact")) {
-      if (deletionPlan.deletable.length > 0) {
-        dir = openTrustedArtifactDir(paths.artifactsDir);
-        deleteArtifactsFailClosed(dir, deletionPlan.deletable);
+    tombstone = withLedgerMutation(paths.ledgerPath, (ledger) => {
+      // Replay and plan under the same lock as every append. Otherwise an event
+      // appended after this snapshot can be lost by the atomic rename or can
+      // start referencing an artifact after the deletion plan was calculated.
+      const replay = ledger.replay();
+      const index = buildInvalidationIndex(replay.events);
+      const removeIds = expandSensitiveArtifactEventTargets(
+        replay.events,
+        index,
+        new Set(targetEventIds),
+        explicitSensitive,
+      );
+ 
+      const deletionPlan = purgeActions.includes("artifact")
+        ? artifactDeletionPlan(replay.events, index, removeIds, targetArtifactDigests)
+        : { deletable: [], retainedExplicit: [] };
+ 
+      if (deletionPlan.retainedExplicit.length > 0) {
+        throw new PurgeError(
+          "sensitive_bytes_retained",
+          `explicit sensitive artifacts remain required: ${deletionPlan.retainedExplicit.join(",")}`,
+        );
       }
-      completed.push("artifact");
-    }
-
-    if (purgeActions.includes("ledger")) {
-      const kept: LabEvent[] = [];
-      for (const event of replay.events) {
-        if (removeIds.has(event.eventId)) continue;
-        kept.push(event);
+ 
+      if (purgeActions.includes("scratch")) {
+        purgeBoundedDirectory(paths.scratchDir);
+        completed.push("scratch");
       }
-      kept.push(tombstone);
-      atomicRewriteLedger(paths.ledgerPath, kept);
-    } else {
-      appendLabEvent(paths.ledgerPath, tombstone);
-    }
-    completed.push("ledger");
-
+      if (purgeActions.includes("export")) {
+        try {
+          purgeLocalPublicEvidenceCopies(req.configDir);
+          completed.push("export");
+        } catch (err) {
+          // Export deletion is independent from artifact/ledger/sqlite deletion. Keep
+          // deleting every other requested sensitive copy, then report this failure.
+          deferredExport.error = normalizePurgeError(err, completed);
+        }
+      }
+ 
+      let dir: TrustedArtifactDir | null = null;
+      try {
+        if (purgeActions.includes("artifact")) {
+          if (deletionPlan.deletable.length > 0) {
+            dir = openTrustedArtifactDir(paths.artifactsDir);
+            deleteArtifactsFailClosed(dir, deletionPlan.deletable);
+          }
+          completed.push("artifact");
+        }
+ 
+        // Never persist a tombstone claiming that export completed when the export
+        // purge failed. Other independent actions remain recordable and continue.
+        const tombstoneActions = deferredExport.error
+          ? purgeActions.filter((action) => action !== "export")
+          : purgeActions;
+        const hasTombstoneTarget = removeIds.size > 0
+          || targetArtifactDigests.length > 0
+          || tombstoneActions.includes("scratch")
+          || tombstoneActions.includes("export");
+ 
+        if (tombstoneActions.length > 0 && (hasTombstoneTarget || !deferredExport.error)) {
+          const mutationTombstone = buildPurgeTombstone(req, removeIds, targetArtifactDigests, tombstoneActions);
+          if (purgeActions.includes("ledger")) {
+            const kept: LabEvent[] = [];
+            for (const event of replay.events) {
+              if (removeIds.has(event.eventId)) continue;
+              kept.push(event);
+            }
+            kept.push(mutationTombstone);
+            atomicRewriteLedger(paths.ledgerPath, kept);
+            completed.push("ledger");
+          } else {
+            ledger.append(mutationTombstone);
+          }
+          return mutationTombstone;
+        }
+        return null;
+      } finally {
+        if (dir) closeTrustedArtifactDir(dir);
+      }
+    });
+ 
+    // SQLite is disposable and rebuildLabProjection replays the canonical
+    // ledger again, so it does not need to extend the mutation lock duration.
     if (purgeActions.includes("sqlite")) {
       rebuildLabProjection(req.configDir);
       completed.push("sqlite");
     }
-
-    return tombstone;
   } catch (err) {
-    if (err instanceof PurgeError) {
-      throw new PurgeError(err.code, err.message, [...completed, ...err.completedActions]);
-    }
+    operationError = normalizePurgeError(err, completed);
+  }
+ 
+  const deferredExportError = deferredExport.error;
+  if (operationError && deferredExportError) {
     throw new PurgeError(
       "purge_failed",
-      err instanceof Error ? err.message : String(err),
-      completed,
+      `export purge failed: ${deferredExportError.message}; subsequent purge failure (${operationError.code}): ${operationError.message}`,
+      [...new Set([...completed, ...deferredExportError.completedActions, ...operationError.completedActions])],
     );
-  } finally {
-    if (dir) closeTrustedArtifactDir(dir);
   }
+  if (operationError) throw operationError;
+  if (deferredExportError) {
+    throw new PurgeError(
+      deferredExportError.code,
+      deferredExportError.message,
+      [...new Set([...completed, ...deferredExportError.completedActions])],
+    );
+  }
+  if (!tombstone) {
+    throw new PurgeError("purge_failed", "purge completed without a durable tombstone", completed);
+  }
+  return tombstone;
 }
+ 

package/src/lab/ledger/store.ts

@@ -25,6 +25,12 @@ export interface LedgerStore {
   replay(): ReplayResult;
 }
 
+export interface LedgerMutationContext {
+  replay(): ReplayResult;
+  append(event: LabEvent): void;
+  appendIfAbsent(event: LabEvent): boolean;
+}
+
 const LEDGER_LOCK_STALE_MS = 60_000;
 const LEDGER_LOCK_WAIT_MS = 5_000;
 
@@ -36,10 +42,7 @@ interface LedgerLockMeta {
 
 /** Block synchronously for the given duration (ledger lock retry only). */
 function sleepSyncMs(ms: number): void {
-  const end = Date.now() + ms;
-  while (Date.now() < end) {
-    /* spin */
-  }
+  Bun.sleepSync(ms);
 }
 
 /** Read pid, createdAt, and token metadata from a ledger lock file, if well-formed. */
@@ -83,8 +86,94 @@ function isLedgerLockStale(lockPath: string): boolean {
       return false;
     }
   }
-  if (isLockHolderAlive(meta.pid)) return false;
-  return Date.now() - meta.createdAt > LEDGER_LOCK_STALE_MS;
+  return !isLockHolderAlive(meta.pid);
+}
+
+/** Write lock ownership metadata to a newly created exclusive lock file. */
+function writeLedgerLockMeta(fd: number, token: string): void {
+  const metadataBytes = Buffer.from(JSON.stringify({
+    pid: process.pid,
+    createdAt: Date.now(),
+    token,
+  }), "utf8");
+  let written = 0;
+  while (written < metadataBytes.byteLength) {
+    const n = writeSync(fd, metadataBytes, written, metadataBytes.byteLength - written);
+    if (n <= 0) {
+      throw new LabValidationError("short_write", "ledger lock metadata write incomplete");
+    }
+    written += n;
+  }
+}
+
+/** Discard a lock whose exclusive creator failed before publishing ownership metadata. */
+function discardUninitialisedLedgerLock(lockPath: string, lockFd: number): void {
+  try {
+    closeSync(lockFd);
+  } catch {
+    /* ignore */
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Release a lock file only when the token still matches the path owner. */
+function releaseLedgerLock(lockPath: string, lockFd: number, token: string): void {
+  try {
+    closeSync(lockFd);
+  } catch {
+    /* ignore */
+  }
+  try {
+    const meta = readLedgerLockMeta(lockPath);
+    if (meta?.token === token) unlinkSync(lockPath);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Recover one stale lock while holding a separate recovery mutex.
+ *
+ * The recovery mutex prevents two waiters from both observing the same stale
+ * owner and then unlinking each other's replacement lock. If a process dies
+ * while holding the recovery mutex, acquisition fails closed instead of
+ * guessing ownership of that mutex.
+ */
+function recoverStaleLedgerLock(lockPath: string): boolean {
+  const recoveryPath = `${lockPath}.recovery`;
+  const token = randomBytes(16).toString("hex");
+  let recoveryFd: number;
+  try {
+    recoveryFd = openSync(
+      recoveryPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      0o600,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw error;
+  }
+
+  try {
+    writeLedgerLockMeta(recoveryFd, token);
+  } catch (error) {
+    discardUninitialisedLedgerLock(recoveryPath, recoveryFd);
+    throw error;
+  }
+
+  try {
+    // Re-check after taking the recovery mutex. Another waiter may already
+    // have recovered the old lock and installed a live replacement.
+    if (!existsSync(lockPath) || !isLedgerLockStale(lockPath)) return false;
+    unlinkSync(lockPath);
+    return true;
+  } finally {
+    releaseLedgerLock(recoveryPath, recoveryFd, token);
+  }
 }
 
 /** Create a ledger lock file exclusively, recovering stale locks when needed. */
@@ -97,30 +186,19 @@ function tryAcquireLedgerLock(lockPath: string, deadline: number): { fd: number;
     } catch (error) {
       if (existsSync(lockPath) && isLedgerLockStale(lockPath)) {
         try {
-          unlinkSync(lockPath);
-        } catch (unlinkError) {
-          if (Date.now() >= deadline) throw unlinkError;
-          sleepSyncMs(10);
+          if (recoverStaleLedgerLock(lockPath)) continue;
+        } catch (recoveryError) {
+          if (Date.now() >= deadline) throw recoveryError;
         }
-        continue;
       }
       if (Date.now() >= deadline) throw error;
       sleepSyncMs(10);
       continue;
     }
     try {
-      const metadataBytes = Buffer.from(JSON.stringify({ pid: process.pid, createdAt: Date.now(), token }), "utf8");
-      const written = writeSync(fd, metadataBytes);
-      if (written !== metadataBytes.byteLength) {
-        throw new LabValidationError("short_write", "ledger lock metadata write incomplete");
-      }
+      writeLedgerLockMeta(fd, token);
     } catch (error) {
-      closeSync(fd);
-      try {
-        unlinkSync(lockPath);
-      } catch {
-        /* best-effort */
-      }
+      discardUninitialisedLedgerLock(lockPath, fd);
       throw error;
     }
     return { fd, token };
@@ -128,21 +206,6 @@ function tryAcquireLedgerLock(lockPath: string, deadline: number): { fd: number;
   throw new Error("ledger lock acquisition timed out");
 }
 
-/** Release a ledger lock only when the token still matches the lock file. */
-function releaseLedgerLock(lockPath: string, lockFd: number, token: string): void {
-  try {
-    closeSync(lockFd);
-  } catch {
-    /* ignore */
-  }
-  try {
-    const meta = readLedgerLockMeta(lockPath);
-    if (meta?.token === token) unlinkSync(lockPath);
-  } catch {
-    /* best-effort */
-  }
-}
-
 /** Run a ledger mutation while holding the compatibility ledger lock file. */
 function withLedgerLock<T>(ledgerPath: string, fn: () => T): T {
   const lockPath = `${ledgerPath}.lock`;
@@ -156,11 +219,10 @@ function withLedgerLock<T>(ledgerPath: string, fn: () => T): T {
   }
 }
 
-/** Durable append of one validated event as a single JSONL line + fsync. */
-export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
-  const validated = validateLabEvent(event);
+/** Durable append of one already-validated event as a single JSONL line + fsync. */
+function appendValidatedLabEvent(ledgerPath: string, event: LabEvent): void {
   mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
-  const line = `${jcsStringify(validated)}\n`;
+  const line = `${jcsStringify(event)}\n`;
   const bytes = new TextEncoder().encode(line);
   const fd = openSync(ledgerPath, "a", 0o600);
   try {
@@ -178,26 +240,78 @@ export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
   }
 }
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" && value !== null) || typeof value === "function"
+  ) && typeof (value as { then?: unknown }).then === "function";
+}
+
 /**
- * Append only when eventId is absent. Uses an exclusive lock file plus a
- * process-local event-id index refreshed under the lock.
+ * Serialize a ledger read-modify-write transaction with all ordinary appends.
+ * The callback is intentionally synchronous. Mutation methods become invalid
+ * as soon as the callback returns, so an accidental async continuation cannot
+ * write after the lock has been released.
  */
-export function appendLabEventIfAbsent(ledgerPath: string, event: LabEvent): boolean {
-  const validated = validateLabEvent(event);
+export function withLedgerMutation<T>(
+  ledgerPath: string,
+  fn: (mutation: LedgerMutationContext) => T,
+): T {
   return withLedgerLock(ledgerPath, () => {
-    // Refresh from disk under the lock so concurrent writers are visible.
-    const fresh = new Set<string>();
-    if (existsSync(ledgerPath)) {
-      for (const row of replayLabLedger(ledgerPath).events) {
-        fresh.add(row.eventId);
+    let active = true;
+    const requireActive = () => {
+      if (!active) {
+        throw new LabValidationError(
+          "inactive_ledger_mutation",
+          "ledger mutation context used after its lock was released",
+        );
       }
+    };
+    const replay = () => {
+      requireActive();
+      return replayLabLedger(ledgerPath);
+    };
+    const append = (event: LabEvent) => {
+      requireActive();
+      appendValidatedLabEvent(ledgerPath, validateLabEvent(event));
+    };
+    const appendIfAbsent = (event: LabEvent): boolean => {
+      requireActive();
+      const validated = validateLabEvent(event);
+      if (replay().events.some((row) => row.eventId === validated.eventId)) return false;
+      appendValidatedLabEvent(ledgerPath, validated);
+      return true;
+    };
+
+    try {
+      const result = fn({ replay, append, appendIfAbsent });
+      if (isThenable(result)) {
+        throw new LabValidationError(
+          "async_ledger_mutation",
+          "ledger mutation callback must be synchronous",
+        );
+      }
+      return result;
+    } finally {
+      active = false;
     }
-    if (fresh.has(validated.eventId)) return false;
-    appendLabEvent(ledgerPath, validated);
-    return true;
   });
 }
 
+/** Durable append of one validated event as a single JSONL line + fsync. */
+export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
+  withLedgerMutation(ledgerPath, (mutation) => {
+    mutation.append(event);
+  });
+}
+
+/**
+ * Append only when eventId is absent. Uses the same mutation lock as every
+ * other ledger writer so the presence check and append are one transaction.
+ */
+export function appendLabEventIfAbsent(ledgerPath: string, event: LabEvent): boolean {
+  return withLedgerMutation(ledgerPath, (mutation) => mutation.appendIfAbsent(event));
+}
+
 function processLine(
   line: string,
   lineNumber: number,
@@ -415,4 +529,4 @@ export function openLedgerStore(configDir?: string): LedgerStore {
 
 export function defaultLedgerPath(configDir?: string): string {
   return labLedgerPath(configDir);
-}
+}

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

@@ -17,7 +17,7 @@ import {
 } from "../digest";
 import type { ObservationEvent } from "../events/types";
 import { assignEventId } from "../events/validate";
-import { appendLabEvent } from "../ledger/store";
+import { withLedgerMutation } from "../ledger/store";
 import { ensureLabDirs } from "../paths";
 import type {
   CaseAuthority,
@@ -285,12 +285,14 @@ export function persistConformanceResult(
   const ownsStore = !opts.artifactStore;
   const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
   try {
-    const { event } = observationFromConformanceResult(result, caseRecord, authority, {
-      ...opts,
-      artifactStore: store,
+    return withLedgerMutation(paths.ledgerPath, (ledger) => {
+      const { event } = observationFromConformanceResult(result, caseRecord, authority, {
+        ...opts,
+        artifactStore: store,
+      });
+      ledger.append(event);
+      return { event, ledgerPath: paths.ledgerPath };
     });
-    appendLabEvent(paths.ledgerPath, event);
-    return { event, ledgerPath: paths.ledgerPath };
   } finally {
     if (ownsStore) store.close();
   }

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

@@ -5,7 +5,7 @@ import { LAB_EVENT_SCHEMA_VERSION, LAB_PRODUCER, LAB_PRODUCER_VERSION, OBSERVATI
 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 { withLedgerMutation } from "../ledger/store";
 import { ensureLabDirs } from "../paths";
 import type { CaseAuthority, CaseRecord } from "../conformance/types";
 import { trustedLiveResultRetryable } from "../live/executor";
@@ -106,6 +106,12 @@ export function observationFromLiveResult(result: LiveScenarioRunResult, caseRec
 
 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 }; }
+  try {
+    return withLedgerMutation(paths.ledgerPath, (ledger) => {
+      const { event } = observationFromLiveResult(result, caseRecord, authority, { ...opts, artifactStore: store });
+      ledger.append(event);
+      return { event, ledgerPath: paths.ledgerPath };
+    });
+  }
   finally { if (ownsStore) store.close(); }
 }