@anionex/dsh-turn-rewind 0.1.0

package/src/snapshot.ts

@@ -0,0 +1,229 @@
+import { createHash } from 'node:crypto'
+import type { BigIntStats } from 'node:fs'
+import { lstat, readFile, readlink } from 'node:fs/promises'
+import { ChangeLedgerError } from './errors.js'
+import { discoverRepository, sameRepositoryFence, type RepositorySnapshotSource } from './git.js'
+import { isNodeError, resolveWorkspacePath } from './path-utils.js'
+import type { LedgerStore } from './store.js'
+import type {
+  ResolvedChangeLedgerConfig,
+  SnapshotEntry,
+  WorkspaceChange,
+} from './types.js'
+
+/** One captured tree, optionally persisted into the blob store. */
+export interface CapturedTree {
+  readonly source: RepositorySnapshotSource
+  readonly entries: Readonly<Record<string, SnapshotEntry>>
+  readonly treeHash: string
+  readonly fileCount: number
+  readonly totalBytes: number
+}
+
+/** Capture the current tracked and non-ignored Git working tree. */
+export async function captureTree(options: {
+  readonly cwd: string
+  readonly config: ResolvedChangeLedgerConfig
+  readonly store?: LedgerStore
+  readonly signal?: AbortSignal
+}): Promise<CapturedTree> {
+  throwIfAborted(options.signal)
+  const source = await discoverRepository(options.cwd, options.signal)
+  if (source.paths.length > options.config.maxFiles) {
+    throw new ChangeLedgerError(
+      'TOO_MANY_FILES',
+      `workspace has ${source.paths.length} eligible paths; configured maximum is ${options.config.maxFiles}`,
+    )
+  }
+
+  const entries: Record<string, SnapshotEntry> = Object.create(null) as Record<string, SnapshotEntry>
+  let totalBytes = 0
+  for (const path of source.paths) {
+    throwIfAborted(options.signal)
+    const entry = await captureEntry(source.state.root, path, options.config.maxFileBytes, options.signal)
+    if (entry === undefined) continue
+    if (entry.kind === 'file') {
+      totalBytes += entry.content.length
+      if (totalBytes > options.config.maxSnapshotBytes) {
+        throw new ChangeLedgerError(
+          'SNAPSHOT_TOO_LARGE',
+          `eligible files exceed configured aggregate limit of ${options.config.maxSnapshotBytes} bytes`,
+        )
+      }
+      if (options.store !== undefined) {
+        await options.store.putBlob(source.state.root, entry.snapshot.blob, entry.content)
+      }
+      entries[path] = entry.snapshot
+      continue
+    }
+    entries[path] = entry.snapshot
+  }
+
+  return {
+    source,
+    entries,
+    treeHash: hashTree(entries),
+    fileCount: Object.keys(entries).length,
+    totalBytes,
+  }
+}
+
+/**
+ * Capture the complete tree twice and accept it only when both path/content and
+ * repository fences agree. This prevents a point from silently mixing files
+ * observed at incompatible moments while another process is editing the tree.
+ */
+export async function captureStableTree(options: {
+  readonly cwd: string
+  readonly config: ResolvedChangeLedgerConfig
+  readonly store?: LedgerStore
+  readonly signal?: AbortSignal
+}): Promise<CapturedTree> {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const first = await captureTree({
+      cwd: options.cwd,
+      config: options.config,
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+    const second = await captureTree(options)
+    if (first.treeHash === second.treeHash
+      && sameRepositoryFence(first.source.state, second.source.state)
+      && arraysEqual(first.source.state.stagedPaths, second.source.state.stagedPaths)
+      && arraysEqual(first.source.paths, second.source.paths)) {
+      return second
+    }
+  }
+  throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', 'workspace did not remain stable across repeated full-tree captures')
+}
+
+/** Compute stable path-level differences between two captured trees. */
+export function diffTrees(
+  before: Readonly<Record<string, SnapshotEntry>>,
+  after: Readonly<Record<string, SnapshotEntry>>,
+): WorkspaceChange[] {
+  const paths = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort(comparePaths)
+  const changes: WorkspaceChange[] = []
+  for (const path of paths) {
+    const left = before[path]
+    const right = after[path]
+    if (left === undefined && right !== undefined) {
+      changes.push({ path, kind: 'added', after: right })
+      continue
+    }
+    if (left !== undefined && right === undefined) {
+      changes.push({ path, kind: 'deleted', before: left })
+      continue
+    }
+    if (left === undefined || right === undefined || entriesEqual(left, right)) continue
+    if (left.kind !== right.kind) {
+      changes.push({ path, kind: 'type-changed', before: left, after: right })
+      continue
+    }
+    if (left.kind === 'file' && right.kind === 'file' && left.blob === right.blob && left.mode !== right.mode) {
+      changes.push({ path, kind: 'mode-changed', before: left, after: right })
+      continue
+    }
+    if (left.kind === 'symlink' && right.kind === 'symlink' && left.target === right.target && left.mode !== right.mode) {
+      changes.push({ path, kind: 'mode-changed', before: left, after: right })
+      continue
+    }
+    changes.push({ path, kind: 'modified', before: left, after: right })
+  }
+  return changes
+}
+
+/** Return whether two snapshot entries are byte/type/mode equivalent. */
+export function entriesEqual(left: SnapshotEntry | undefined, right: SnapshotEntry | undefined): boolean {
+  if (left === undefined || right === undefined) return left === right
+  if (left.kind !== right.kind || left.mode !== right.mode) return false
+  if (left.kind === 'file' && right.kind === 'file') {
+    return left.blob === right.blob && left.size === right.size
+  }
+  return left.kind === 'symlink' && right.kind === 'symlink' && left.target === right.target
+}
+
+/** Hash a complete path map into a deterministic tree identity. */
+export function hashTree(entries: Readonly<Record<string, SnapshotEntry>>): string {
+  const hash = createHash('sha256')
+  for (const path of Object.keys(entries).sort(comparePaths)) {
+    const entry = entries[path]
+    if (entry === undefined) continue
+    hash.update(path)
+    hash.update('\0')
+    if (entry.kind === 'file') {
+      hash.update(`file\0${entry.blob}\0${entry.size}\0${entry.mode}\0`)
+    } else {
+      hash.update(`symlink\0${entry.target}\0${entry.mode}\0`)
+    }
+  }
+  return hash.digest('hex')
+}
+
+async function captureEntry(
+  root: string,
+  path: string,
+  maxFileBytes: number,
+  signal?: AbortSignal,
+): Promise<{ readonly kind: 'file'; readonly snapshot: SnapshotEntry & { readonly kind: 'file' }; readonly content: Buffer }
+  | { readonly kind: 'symlink'; readonly snapshot: SnapshotEntry & { readonly kind: 'symlink' } }
+  | undefined> {
+  const target = resolveWorkspacePath(root, path)
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    throwIfAborted(signal)
+    let before
+    try {
+      before = await lstat(target, { bigint: true })
+    } catch (error) {
+      if (isNodeError(error, 'ENOENT')) return undefined
+      throw error
+    }
+    const mode = Number(before.mode & 0o777n)
+    if (before.isSymbolicLink()) {
+      const linkTarget = await readlink(target)
+      const after = await lstat(target, { bigint: true })
+      if (!sameStat(before, after)) continue
+      return { kind: 'symlink', snapshot: { kind: 'symlink', target: linkTarget, mode } }
+    }
+    if (!before.isFile()) {
+      throw new ChangeLedgerError('UNSUPPORTED_FILE_TYPE', `eligible path is not a regular file or symlink: ${JSON.stringify(path)}`)
+    }
+    if (before.size > BigInt(maxFileBytes)) {
+      throw new ChangeLedgerError(
+        'FILE_TOO_LARGE',
+        `${JSON.stringify(path)} is ${before.size.toString()} bytes; configured per-file maximum is ${maxFileBytes}`,
+      )
+    }
+    const content = await readFile(target)
+    throwIfAborted(signal)
+    const after = await lstat(target, { bigint: true })
+    if (!sameStat(before, after) || BigInt(content.length) !== after.size) continue
+    const blob = createHash('sha256').update(content).digest('hex')
+    return {
+      kind: 'file',
+      snapshot: { kind: 'file', blob, size: content.length, mode },
+      content,
+    }
+  }
+  throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `path changed repeatedly while being captured: ${JSON.stringify(path)}`)
+}
+
+function sameStat(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw signal.reason
+}
+
+function comparePaths(left: string, right: string): number {
+  return Buffer.from(left).compare(Buffer.from(right))
+}
+
+function arraysEqual(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}

package/src/store.ts

@@ -0,0 +1,383 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { link, mkdir, open, readFile, readdir, rmdir, stat, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { ChangeLedgerError, errorMessage } from './errors.js'
+import { isNodeError, openExclusive, processExists, readJson, syncDirectory, writeJsonAtomic } from './path-utils.js'
+import type { ResolvedChangeLedgerConfig, RestoreOperation, RestorePointManifest } from './types.js'
+import { parseManifest, parseOperation, validateBlobHash, validateOperationId, validateRestorePointId } from './validate.js'
+
+interface LockRecord {
+  readonly pid: number
+  readonly createdAt: number
+  readonly nonce: string
+}
+
+/** Durable content-addressed storage and per-workspace locking. */
+export class LedgerStore {
+  constructor(readonly config: ResolvedChangeLedgerConfig) {}
+
+  /** Create the state root and reconcile crash-interrupted operations. */
+  async initialize(): Promise<number> {
+    await mkdir(join(this.config.storageDir, 'workspaces'), { recursive: true, mode: 0o700 })
+    let reconciled = 0
+    for (const workspaceKey of await safeDirectoryNames(join(this.config.storageDir, 'workspaces'))) {
+      const workspaceDir = join(this.config.storageDir, 'workspaces', workspaceKey)
+      if (await this.workspaceAppearsActive(workspaceDir)) continue
+      const operationDir = join(workspaceDir, 'operations')
+      for (const filename of await safeJsonNames(operationDir)) {
+        const path = join(operationDir, filename)
+        const operation = parseOperation(await readJson(path))
+        if (filename !== `${operation.id}.json`) {
+          throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} does not match its persisted id ${operation.id}`)
+        }
+        if (this.workspaceDir(operation.workspace) !== workspaceDir) {
+          throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} is stored under the wrong workspace key`)
+        }
+        if (operation.state !== 'running' && operation.state !== 'rollback-running') continue
+        await this.writeOperation({
+          ...operation,
+          state: 'interrupted',
+          error: operation.error ?? 'DSH stopped before the restore operation reached a terminal state',
+        })
+        reconciled += 1
+      }
+    }
+    return reconciled
+  }
+
+  /** Acquire the exclusive lock for one canonical workspace. */
+  async acquire(workspace: string): Promise<() => Promise<void>> {
+    const lockPath = join(this.workspaceDir(workspace), 'lock.json')
+    await mkdir(this.workspaceDir(workspace), { recursive: true, mode: 0o700 })
+    const nonce = randomUUID()
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      let handle
+      try {
+        handle = await openExclusive(lockPath)
+      } catch (error) {
+        if (!isNodeError(error, 'EEXIST')) throw error
+        const reclaimed = await this.reclaimStaleLock(lockPath)
+        if (reclaimed) continue
+        throw new ChangeLedgerError('WORKSPACE_LOCKED', `another change-ledger operation owns ${JSON.stringify(workspace)}`)
+      }
+      const record: LockRecord = { pid: process.pid, createdAt: Date.now(), nonce }
+      try {
+        await handle.writeFile(`${JSON.stringify(record)}\n`, 'utf8')
+        await handle.sync()
+      } finally {
+        await handle.close()
+      }
+      await syncDirectory(this.workspaceDir(workspace))
+      let released = false
+      return async () => {
+        if (released) return
+        released = true
+        try {
+          const current = parseLock(await readJson(lockPath))
+          if (current.nonce !== nonce) return
+          await unlink(lockPath)
+          await syncDirectory(this.workspaceDir(workspace))
+        } catch (error) {
+          if (!isNodeError(error, 'ENOENT') && !isMissingStateRead(error)) throw error
+        }
+      }
+    }
+    throw new ChangeLedgerError('WORKSPACE_LOCKED', `could not acquire change-ledger lock for ${JSON.stringify(workspace)}`)
+  }
+
+  /** Persist a blob if it is not already present, and verify existing content. */
+  async putBlob(workspace: string, hash: string, content: Buffer): Promise<void> {
+    validateBlobHash(hash)
+    const contentHash = createHash('sha256').update(content).digest('hex')
+    if (contentHash !== hash) {
+      throw new ChangeLedgerError('BLOB_HASH_MISMATCH', `refusing to store content whose SHA-256 does not match ${hash}`)
+    }
+    const path = this.blobPath(workspace, hash)
+    const directory = join(this.workspaceDir(workspace), 'blobs', hash.slice(0, 2))
+    await mkdir(directory, { recursive: true, mode: 0o700 })
+    const temporary = join(directory, `.${randomUUID()}.tmp`)
+    try {
+      const handle = await open(temporary, 'wx', 0o600)
+      try {
+        await handle.writeFile(content)
+        await handle.sync()
+      } finally {
+        await handle.close()
+      }
+      try {
+        await link(temporary, path)
+        await syncDirectory(directory)
+        return
+      } catch (error) {
+        if (!isNodeError(error, 'EEXIST')) throw error
+      }
+    } finally {
+      try {
+        await unlink(temporary)
+      } catch (error) {
+        if (!isNodeError(error, 'ENOENT')) throw error
+      }
+    }
+    const existing = await readFile(path)
+    const existingHash = createHash('sha256').update(existing).digest('hex')
+    if (existingHash !== hash || !existing.equals(content)) {
+      throw new ChangeLedgerError('BLOB_COLLISION', `stored blob ${hash} does not match its content hash`)
+    }
+  }
+
+  /** Read and verify one content-addressed blob. */
+  async readBlob(workspace: string, hash: string): Promise<Buffer> {
+    validateBlobHash(hash)
+    const content = await readFile(this.blobPath(workspace, hash))
+    const actual = createHash('sha256').update(content).digest('hex')
+    if (actual !== hash) throw new ChangeLedgerError('BLOB_CORRUPT', `blob ${hash} failed SHA-256 verification`)
+    return content
+  }
+
+  /** Write one restore-point manifest atomically. */
+  async writeManifest(manifest: RestorePointManifest): Promise<void> {
+    parseManifest(manifest)
+    await writeJsonAtomic(this.manifestPath(manifest.workspace, manifest.id), manifest)
+  }
+
+  /** Load and validate one restore-point manifest. */
+  async readManifest(workspace: string, id: string): Promise<RestorePointManifest> {
+    validateRestorePointId(id)
+    let raw: unknown
+    try {
+      raw = await readJson(this.manifestPath(workspace, id))
+    } catch (error) {
+      if (isMissingStateRead(error)) {
+        throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `restore point ${id} does not exist`, { cause: error })
+      }
+      throw error
+    }
+    const manifest = parseManifest(raw)
+    if (manifest.id !== id) {
+      throw new ChangeLedgerError('STATE_CORRUPT', `restore point file ${id}.json contains id ${manifest.id}`)
+    }
+    if (manifest.workspace !== workspace) {
+      throw new ChangeLedgerError('STATE_CORRUPT', `restore point ${id} belongs to a different workspace`)
+    }
+    return manifest
+  }
+
+  /** List all validated restore points for one workspace, newest first. */
+  async listManifests(workspace: string): Promise<RestorePointManifest[]> {
+    const manifests: RestorePointManifest[] = []
+    for (const filename of await safeJsonNames(join(this.workspaceDir(workspace), 'manifests'))) {
+      const manifest = parseManifest(await readJson(join(this.workspaceDir(workspace), 'manifests', filename)))
+      if (filename !== `${manifest.id}.json`) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `manifest ${filename} does not match its persisted id ${manifest.id}`)
+      }
+      if (manifest.workspace !== workspace) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `manifest ${filename} belongs to a different workspace`)
+      }
+      manifests.push(manifest)
+    }
+    return manifests.sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id))
+  }
+
+  /** Delete one restore-point manifest. Blobs remain until garbage collection succeeds. */
+  async deleteManifest(workspace: string, id: string): Promise<void> {
+    validateRestorePointId(id)
+    const directory = join(this.workspaceDir(workspace), 'manifests')
+    try {
+      await unlink(this.manifestPath(workspace, id))
+    } catch (error) {
+      if (isNodeError(error, 'ENOENT')) {
+        throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `restore point ${id} does not exist`)
+      }
+      throw error
+    }
+    await syncDirectory(directory)
+  }
+
+  /** Persist one restore-operation journal. */
+  async writeOperation(operation: RestoreOperation): Promise<void> {
+    parseOperation(operation)
+    await writeJsonAtomic(this.operationPath(operation.workspace, operation.id), operation)
+  }
+
+  /** List validated restore operations for one workspace. */
+  async listOperations(workspace: string): Promise<RestoreOperation[]> {
+    const operations: RestoreOperation[] = []
+    for (const filename of await safeJsonNames(join(this.workspaceDir(workspace), 'operations'))) {
+      const operation = parseOperation(await readJson(join(this.workspaceDir(workspace), 'operations', filename)))
+      if (filename !== `${operation.id}.json`) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} does not match its persisted id ${operation.id}`)
+      }
+      if (operation.workspace !== workspace) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `operation ${filename} belongs to a different workspace`)
+      }
+      operations.push(operation)
+    }
+    return operations.sort((left, right) => right.startedAt - left.startedAt || right.id.localeCompare(left.id))
+  }
+
+  /** Return whether an incomplete operation still references a restore point. */
+  async isReferencedByRecovery(workspace: string, restorePointId: string): Promise<boolean> {
+    return (await this.listOperations(workspace)).some((operation) =>
+      (operation.state === 'interrupted' || operation.state === 'recovery-required')
+      && (operation.restorePointId === restorePointId || operation.rescuePointId === restorePointId))
+  }
+
+  /** Delete blobs not referenced by any remaining manifest. */
+  async collectGarbage(
+    workspace: string,
+    additionalReferenced: Iterable<string> = [],
+  ): Promise<{ deletedBlobs: number; retainedBlobs: number }> {
+    const referenced = new Set<string>(additionalReferenced)
+    for (const hash of referenced) validateBlobHash(hash)
+    for (const manifest of await this.listManifests(workspace)) {
+      for (const entry of Object.values(manifest.entries)) {
+        if (entry.kind === 'file') referenced.add(entry.blob)
+      }
+    }
+    let deletedBlobs = 0
+    let retainedBlobs = 0
+    const blobsRoot = join(this.workspaceDir(workspace), 'blobs')
+    for (const prefix of await safeDirectoryNames(blobsRoot)) {
+      const prefixPath = join(blobsRoot, prefix)
+      for (const filename of await safeFileNames(prefixPath)) {
+        if (filename.startsWith('.') && filename.endsWith('.tmp')) {
+          await unlink(join(prefixPath, filename))
+          deletedBlobs += 1
+          continue
+        }
+        validateBlobHash(filename)
+        if (filename.slice(0, 2) !== prefix) {
+          throw new ChangeLedgerError('STATE_CORRUPT', `blob ${filename} is stored under the wrong prefix directory ${prefix}`)
+        }
+        if (referenced.has(filename)) {
+          retainedBlobs += 1
+          continue
+        }
+        await unlink(join(prefixPath, filename))
+        deletedBlobs += 1
+      }
+      try {
+        await rmdir(prefixPath)
+      } catch (error) {
+        if (!isNodeError(error, 'ENOTEMPTY') && !isNodeError(error, 'EEXIST') && !isNodeError(error, 'ENOENT')) throw error
+      }
+    }
+    return { deletedBlobs, retainedBlobs }
+  }
+
+  private workspaceDir(workspace: string): string {
+    const key = createHash('sha256').update(workspace).digest('hex')
+    return join(this.config.storageDir, 'workspaces', key)
+  }
+
+  private manifestPath(workspace: string, id: string): string {
+    return join(this.workspaceDir(workspace), 'manifests', `${validateRestorePointId(id)}.json`)
+  }
+
+  private operationPath(workspace: string, id: string): string {
+    return join(this.workspaceDir(workspace), 'operations', `${validateOperationId(id)}.json`)
+  }
+
+  private blobPath(workspace: string, hash: string): string {
+    validateBlobHash(hash)
+    return join(this.workspaceDir(workspace), 'blobs', hash.slice(0, 2), hash)
+  }
+
+  private async reclaimStaleLock(lockPath: string): Promise<boolean> {
+    let lock: LockRecord
+    try {
+      lock = parseLock(await readJson(lockPath))
+    } catch (error) {
+      let age = 0
+      try {
+        age = Date.now() - (await stat(lockPath)).mtimeMs
+      } catch (statError) {
+        if (isNodeError(statError, 'ENOENT')) return true
+        throw statError
+      }
+      if (age < this.config.staleLockMs) {
+        throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', `active lock is unreadable: ${errorMessage(error)}`)
+      }
+      await unlink(lockPath)
+      return true
+    }
+    if (processExists(lock.pid)) return false
+    if (Date.now() - lock.createdAt < this.config.staleLockMs) return false
+    try {
+      const current = parseLock(await readJson(lockPath))
+      if (current.nonce !== lock.nonce) return false
+      await unlink(lockPath)
+      return true
+    } catch (error) {
+      if (isNodeError(error, 'ENOENT')) return true
+      throw error
+    }
+  }
+
+  private async workspaceAppearsActive(workspaceDir: string): Promise<boolean> {
+    const lockPath = join(workspaceDir, 'lock.json')
+    try {
+      const lock = parseLock(await readJson(lockPath))
+      if (processExists(lock.pid)) return true
+      return Date.now() - lock.createdAt < this.config.staleLockMs
+    } catch (error) {
+      if (error instanceof ChangeLedgerError && error.code === 'STATE_READ_FAILED' && isMissingCause(error.cause)) return false
+      if (isNodeError(error, 'ENOENT')) return false
+      try {
+        return Date.now() - (await stat(lockPath)).mtimeMs < this.config.staleLockMs
+      } catch (statError) {
+        if (isNodeError(statError, 'ENOENT')) return false
+        throw statError
+      }
+    }
+  }
+}
+
+function parseLock(value: unknown): LockRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock must be an object')
+  }
+  const record = value as Record<string, unknown>
+  if (!Number.isSafeInteger(record.pid) || (record.pid as number) <= 0) {
+    throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock pid is invalid')
+  }
+  if (!Number.isSafeInteger(record.createdAt) || (record.createdAt as number) < 0) {
+    throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock createdAt is invalid')
+  }
+  if (typeof record.nonce !== 'string' || record.nonce === '') {
+    throw new ChangeLedgerError('WORKSPACE_LOCK_CORRUPT', 'workspace lock nonce is invalid')
+  }
+  return { pid: record.pid as number, createdAt: record.createdAt as number, nonce: record.nonce }
+}
+
+async function safeJsonNames(path: string): Promise<string[]> {
+  return (await safeFileNames(path)).filter((name) => name.endsWith('.json')).sort()
+}
+
+async function safeDirectoryNames(path: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true })
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort()
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) return []
+    throw error
+  }
+}
+
+async function safeFileNames(path: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true })
+    return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort()
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) return []
+    throw error
+  }
+}
+
+function isMissingCause(error: unknown): boolean {
+  return error instanceof Error && 'cause' in error && isNodeError(error.cause, 'ENOENT')
+}
+
+function isMissingStateRead(error: unknown): boolean {
+  return error instanceof ChangeLedgerError && error.code === 'STATE_READ_FAILED' && isMissingCause(error)
+}