@abelxiaoxing/cadence 1.8.3 → 2.0.0

package/src/apply-transaction.ts

@@ -1,1437 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import {
-  chmodSync,
-  closeSync,
-  constants,
-  fsyncSync,
-  linkSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  openSync,
-  readFileSync,
-  realpathSync,
-  renameSync,
-  rmdirSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { DatabaseSync } from "node:sqlite";
-import type { ArtifactStore } from "./artifact-store.ts";
-import { compareCanonicalStrings } from "./canonical.ts";
-import { isValidRelativePath } from "./contracts.ts";
-import { syncDirectory } from "./directory-sync.ts";
-import { isExecutionRetained } from "./execution-retention.ts";
-import { removePathSync } from "./remove-path.ts";
-import { observeSafePath } from "./safe-path.ts";
-import { configureSqlite, ensureSqliteSchema } from "./sqlite-schema.ts";
-import { APPLY_SCHEMA } from "./storage-schema.ts";
-import type {
-  WorkspaceEntry,
-  WorkspaceRevision,
-  WorkspaceStore,
-} from "./workspace-store.ts";
-
-const IDENTIFIER = /^[a-z0-9](?:[a-z0-9._:-]{0,126}[a-z0-9])?$/iu;
-const SHA256 = /^[a-f0-9]{64}$/u;
-
-type TransactionState =
-  | "prepared"
-  | "applying"
-  | "recovering"
-  | "paused"
-  | "discarded"
-  | "completed";
-type PendingIntent = "cancel" | "discard";
-type StepState = "pending" | "applying" | "applied" | "rolled-back";
-
-interface TransactionStep {
-  path: string;
-  before: WorkspaceEntry;
-  after: WorkspaceEntry;
-  state: StepState;
-}
-
-interface TransactionEvent {
-  sequence: number;
-  kind: string;
-  path?: string;
-}
-
-interface TransactionJournal {
-  transactionId: string;
-  consumerRoot: string;
-  baselineRevisionId: string;
-  finalRevisionId: string;
-  verificationId: string;
-  boundPaths: string[];
-  state: TransactionState;
-  code?: string;
-  pendingIntent?: PendingIntent;
-  rollbackRetained: boolean;
-  externalPaths: string[];
-  retainedHashes: string[];
-  releasedHashes: string[];
-  createdDirectories: string[];
-  steps: TransactionStep[];
-  events: TransactionEvent[];
-}
-
-interface JournalRow {
-  journal_json: string;
-  journal_hash: string;
-}
-
-export interface CumulativeVerificationExecutionInput {
-  root: string;
-  revisionId: string;
-  verificationId: string;
-  signal?: AbortSignal;
-}
-
-export type CumulativeVerificationExecutionResult =
-  | {
-      ok: true;
-      exitCode: 0;
-      classification: string;
-    }
-  | {
-      ok: false;
-      kind:
-        | "artifact"
-        | "environment"
-        | "verification"
-        | "verification-adapter"
-        | "approval-boundary"
-        | "cancelled";
-      code: string;
-    };
-
-export interface VerifyCumulativeRevisionInput {
-  workspaceStore: WorkspaceStore;
-  revisionId: string;
-  verificationId: string;
-  execute: (
-    input: CumulativeVerificationExecutionInput,
-  ) =>
-    | CumulativeVerificationExecutionResult
-    | Promise<CumulativeVerificationExecutionResult>;
-  signal?: AbortSignal;
-}
-
-interface CumulativeVerificationFact {
-  readonly revisionId: string;
-  readonly verificationId: string;
-}
-
-const verificationFacts = new WeakMap<
-  object,
-  CumulativeVerificationFact & { workspaceStore: WorkspaceStore }
->();
-
-export type CumulativeVerificationResult =
-  | { ok: true; fact: object; revisionId: string; verificationId: string }
-  | {
-      ok: false;
-      kind:
-        | "artifact"
-        | "environment"
-        | "verification"
-        | "verification-adapter"
-        | "approval-boundary"
-        | "cancelled";
-      code: string;
-      verificationId: string;
-    };
-
-export interface ApplyTransactionHooks {
-  beforeFileMutation?: (input: {
-    transactionId: string;
-    path: string;
-    index: number;
-  }) => void | Promise<void>;
-  afterFileMutationBeforeSave?: (input: {
-    transactionId: string;
-    path: string;
-    index: number;
-  }) => void | Promise<void>;
-  afterFileMutation?: (input: {
-    transactionId: string;
-    path: string;
-    index: number;
-  }) => void | Promise<void>;
-  /** Production executors settle their process scope before cancellation returns. */
-  awaitPostApplySettlement?: boolean;
-  postApply?: (input: {
-    transactionId: string;
-    root: string;
-    signal: AbortSignal;
-  }) =>
-    | { ok: true }
-    | { ok: false; code: string }
-    | Promise<{ ok: true } | { ok: false; code: string }>;
-}
-
-export interface ApplyTransactionOptions {
-  root: string;
-  artifacts: ArtifactStore;
-  workspaces: WorkspaceStore;
-  hooks?: ApplyTransactionHooks;
-  databasePath?: string;
-}
-
-export interface PrepareApplyInput {
-  transactionId: string;
-  consumerRoot: string;
-  baselineRevisionId: string;
-  finalRevisionId: string;
-  boundPaths: string[];
-  verificationFact: unknown;
-}
-
-export type ApplyTransactionOutcome =
-  | {
-      ok: true;
-      transactionId: string;
-      state: "prepared" | "completed";
-      replayed?: true;
-    }
-  | {
-      ok: false;
-      transactionId: string;
-      state: "paused" | "discarded";
-      code: string;
-      replayed?: true;
-    };
-
-function hashBytes(bytes: Uint8Array): string {
-  return createHash("sha256").update(bytes).digest("hex");
-}
-
-function journalHash(journal: TransactionJournal): string {
-  return createHash("sha256")
-    .update("cadence-apply-transaction\0")
-    .update(JSON.stringify(journal))
-    .digest("hex");
-}
-
-function requireIdentifier(value: string): void {
-  if (!IDENTIFIER.test(value)) throw new Error("transaction-id-invalid");
-}
-
-function requireRelative(relative: string): void {
-  if (!isValidRelativePath(relative) || relative === ".") {
-    throw new Error("transaction-path-invalid");
-  }
-}
-
-function ensurePrivateDirectory(directory: string): void {
-  if (!path.isAbsolute(directory)) throw new Error("transaction-root-invalid");
-  let cursor = path.resolve(directory);
-  const missing: string[] = [];
-  for (;;) {
-    const stat = lstatSync(cursor, { throwIfNoEntry: false });
-    if (stat) {
-      if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw new Error("transaction-root-invalid");
-      }
-      break;
-    }
-    missing.push(cursor);
-    const parent = path.dirname(cursor);
-    if (parent === cursor) throw new Error("transaction-root-invalid");
-    cursor = parent;
-  }
-  for (const target of missing.reverse()) {
-    mkdirSync(target, { mode: 0o700 });
-    chmodSync(target, 0o700);
-  }
-  chmodSync(directory, 0o700);
-}
-
-function entryEqual(left: WorkspaceEntry, right: WorkspaceEntry): boolean {
-  if (left.kind !== right.kind) return false;
-  return (
-    left.kind === "absent" ||
-    (right.kind === "file" &&
-      left.hash === right.hash &&
-      left.bytes === right.bytes &&
-      left.mode === right.mode)
-  );
-}
-
-function normalizedEntry(entry: WorkspaceEntry | undefined): WorkspaceEntry {
-  return entry ? structuredClone(entry) : { kind: "absent" };
-}
-
-function isContainedBy(parent: string, candidate: string): boolean {
-  const relative = path.relative(parent, candidate);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-function canonicalConsumerRoot(input: string): string {
-  const absolute = path.resolve(input);
-  const stat = lstatSync(absolute, { throwIfNoEntry: false });
-  if (!stat?.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error("consumer-root-invalid");
-  }
-  return realpathSync.native(absolute);
-}
-
-function currentEntry(
-  root: string,
-  relative: string,
-): WorkspaceEntry | "unsafe" {
-  const observation = observeSafePath(root, relative);
-  if (observation.kind === "absent") return { kind: "absent" };
-  if (observation.kind !== "file") return "unsafe";
-  const absolute = path.join(root, ...relative.split("/"));
-  const bytes = readFileSync(absolute);
-  const stat = lstatSync(absolute);
-  return {
-    kind: "file",
-    hash: hashBytes(bytes),
-    bytes: bytes.byteLength,
-    mode: stat.mode & 0o777,
-  };
-}
-
-function mainMatches(
-  root: string,
-  relative: string,
-  expected: WorkspaceEntry,
-): boolean {
-  const current = currentEntry(root, relative);
-  return current !== "unsafe" && entryEqual(current, expected);
-}
-
-function fileEntryAt(target: string): WorkspaceEntry | "unsafe" | "absent" {
-  const stat = lstatSync(target, { throwIfNoEntry: false });
-  if (!stat) return "absent";
-  if (!stat.isFile() || stat.isSymbolicLink()) return "unsafe";
-  const bytes = readFileSync(target);
-  const confirmed = lstatSync(target, { throwIfNoEntry: false });
-  if (
-    !confirmed?.isFile() ||
-    confirmed.isSymbolicLink() ||
-    confirmed.dev !== stat.dev ||
-    confirmed.ino !== stat.ino
-  ) {
-    return "unsafe";
-  }
-  return {
-    kind: "file",
-    hash: hashBytes(bytes),
-    bytes: bytes.byteLength,
-    mode: confirmed.mode & 0o777,
-  };
-}
-
-function restoreClaim(claim: string, target: string): boolean {
-  try {
-    linkSync(claim, target);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
-    throw error;
-  }
-  unlinkSync(claim);
-  syncDirectory(path.dirname(target));
-  return true;
-}
-
-async function raceWithAbort<T>(
-  execution: Promise<T>,
-  signal: AbortSignal,
-): Promise<T> {
-  let removeAbort = () => {};
-  const aborted = new Promise<never>((_resolve, reject) => {
-    const onAbort = () =>
-      reject(
-        signal.reason instanceof Error
-          ? signal.reason
-          : new Error("operation-cancelled"),
-      );
-    removeAbort = () => signal.removeEventListener("abort", onAbort);
-    if (signal.aborted) onAbort();
-    else signal.addEventListener("abort", onAbort, { once: true });
-  });
-  try {
-    return await Promise.race([execution, aborted]);
-  } finally {
-    removeAbort();
-  }
-}
-
-function safeTargetPath(root: string, relative: string): string {
-  requireRelative(relative);
-  const segments = relative.split("/");
-  let parent = root;
-  for (const segment of segments.slice(0, -1)) {
-    parent = path.join(parent, segment);
-    const stat = lstatSync(parent, { throwIfNoEntry: false });
-    if (!stat) break;
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      throw new Error("transaction-target-unsafe");
-    }
-  }
-  return path.join(root, ...segments);
-}
-
-function writeExclusiveFile(
-  target: string,
-  bytes: Uint8Array,
-  mode: number,
-): boolean {
-  const directory = path.dirname(target);
-  const temporary = path.join(
-    directory,
-    `.${path.basename(target)}.${process.pid}.${randomUUID()}.apply-tmp`,
-  );
-  const descriptor = openSync(
-    temporary,
-    constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
-    0o600,
-  );
-  try {
-    writeFileSync(descriptor, bytes);
-    fsyncSync(descriptor);
-  } finally {
-    closeSync(descriptor);
-  }
-  try {
-    chmodSync(temporary, mode);
-    try {
-      linkSync(temporary, target);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
-      throw error;
-    }
-    unlinkSync(temporary);
-    syncDirectory(directory);
-    return true;
-  } catch (error) {
-    removePathSync(temporary, { force: true });
-    throw error;
-  } finally {
-    removePathSync(temporary, { force: true });
-  }
-}
-
-function event(
-  journal: TransactionJournal,
-  kind: string,
-  relative?: string,
-): void {
-  journal.events.push({
-    sequence: journal.events.length + 1,
-    kind,
-    ...(relative ? { path: relative } : {}),
-  });
-}
-
-function requireRevisionId(value: string): void {
-  if (!SHA256.test(value)) throw new Error("workspace-revision-id-invalid");
-}
-
-function validateJournal(value: unknown): TransactionJournal {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("transaction-journal-invalid");
-  }
-  const journal = value as TransactionJournal;
-  if (
-    !IDENTIFIER.test(journal.transactionId) ||
-    !path.isAbsolute(journal.consumerRoot) ||
-    !SHA256.test(journal.baselineRevisionId) ||
-    !SHA256.test(journal.finalRevisionId) ||
-    !IDENTIFIER.test(journal.verificationId) ||
-    !Array.isArray(journal.boundPaths) ||
-    ![
-      "prepared",
-      "applying",
-      "recovering",
-      "paused",
-      "discarded",
-      "completed",
-    ].includes(journal.state) ||
-    typeof journal.rollbackRetained !== "boolean" ||
-    !Array.isArray(journal.externalPaths) ||
-    !Array.isArray(journal.retainedHashes) ||
-    !Array.isArray(journal.releasedHashes) ||
-    !Array.isArray(journal.createdDirectories) ||
-    !Array.isArray(journal.steps) ||
-    !Array.isArray(journal.events)
-  ) {
-    throw new Error("transaction-journal-invalid");
-  }
-  if (
-    new Set(journal.createdDirectories).size !==
-      journal.createdDirectories.length ||
-    journal.createdDirectories.some((relative) => {
-      try {
-        requireRelative(relative);
-        return false;
-      } catch {
-        return true;
-      }
-    })
-  ) {
-    throw new Error("transaction-journal-invalid");
-  }
-  if (
-    journal.boundPaths.length === 0 ||
-    new Set(journal.boundPaths).size !== journal.boundPaths.length ||
-    journal.boundPaths.some((relative) => {
-      try {
-        requireRelative(relative);
-        return false;
-      } catch {
-        return true;
-      }
-    })
-  ) {
-    throw new Error("transaction-journal-invalid");
-  }
-  for (const step of journal.steps) {
-    requireRelative(step.path);
-    if (
-      !["pending", "applying", "applied", "rolled-back"].includes(step.state)
-    ) {
-      throw new Error("transaction-journal-invalid");
-    }
-  }
-  if (
-    journal.steps.length !== journal.boundPaths.length ||
-    journal.steps.some((step, index) => step.path !== journal.boundPaths[index])
-  ) {
-    throw new Error("transaction-journal-invalid");
-  }
-  return journal;
-}
-
-function isAncestor(
-  workspaces: WorkspaceStore,
-  ancestorId: string,
-  revision: WorkspaceRevision,
-): boolean {
-  let cursor: WorkspaceRevision | null = revision;
-  const visited = new Set<string>();
-  while (cursor) {
-    if (cursor.revisionId === ancestorId) return true;
-    if (visited.has(cursor.revisionId)) {
-      throw new Error("workspace-revision-cycle");
-    }
-    visited.add(cursor.revisionId);
-    cursor = cursor.parentRevisionId
-      ? workspaces.getRevision(cursor.parentRevisionId)
-      : null;
-  }
-  return false;
-}
-
-/** Materialize and execute verification without exposing a caller-forgeable fact. */
-export async function verifyCumulativeRevision(
-  input: VerifyCumulativeRevisionInput,
-): Promise<CumulativeVerificationResult> {
-  requireRevisionId(input.revisionId);
-  requireIdentifier(input.verificationId);
-  const revision = input.workspaceStore.getRevision(input.revisionId);
-  const temporary = mkdtempSync(
-    path.join(tmpdir(), "cadence-cumulative-verification-"),
-  );
-  chmodSync(temporary, 0o700);
-  try {
-    await input.workspaceStore.materializeAsync(
-      revision.revisionId,
-      temporary,
-      input.signal,
-    );
-    if (input.signal?.aborted) {
-      return {
-        ok: false,
-        kind: "cancelled",
-        code: "cancelled",
-        verificationId: input.verificationId,
-      };
-    }
-    const result = await input.execute({
-      root: temporary,
-      revisionId: revision.revisionId,
-      verificationId: input.verificationId,
-      signal: input.signal,
-    });
-    if (!result.ok) {
-      return {
-        ok: false,
-        kind: result.kind,
-        code: result.code,
-        verificationId: input.verificationId,
-      };
-    }
-    if (result.exitCode !== 0 || result.classification.length === 0) {
-      throw new Error("verification-outcome-invalid");
-    }
-    const fact = Object.freeze({
-      revisionId: revision.revisionId,
-      verificationId: input.verificationId,
-    });
-    verificationFacts.set(fact, {
-      ...fact,
-      workspaceStore: input.workspaceStore,
-    });
-    return {
-      ok: true,
-      fact,
-      revisionId: revision.revisionId,
-      verificationId: input.verificationId,
-    };
-  } finally {
-    if (!isExecutionRetained(temporary))
-      removePathSync(temporary, { recursive: true, force: true });
-  }
-}
-
-/** Journaled, restart-safe final delivery from one immutable revision. */
-export class ApplyTransaction {
-  readonly root: string;
-  readonly #artifacts: ArtifactStore;
-  readonly #workspaces: WorkspaceStore;
-  readonly #hooks: ApplyTransactionHooks;
-  readonly #database: DatabaseSync;
-  readonly #active = new Map<
-    string,
-    {
-      controller: AbortController;
-      promise: Promise<ApplyTransactionOutcome>;
-    }
-  >();
-  #closed = false;
-
-  constructor(options: ApplyTransactionOptions) {
-    if (!options || typeof options !== "object") {
-      throw new Error("transaction-options-invalid");
-    }
-    this.root = path.resolve(options.root);
-    ensurePrivateDirectory(this.root);
-    this.#artifacts = options.artifacts;
-    this.#workspaces = options.workspaces;
-    this.#hooks = options.hooks ?? {};
-    const databasePath = path.resolve(
-      options.databasePath ?? path.join(this.root, "apply.sqlite3"),
-    );
-    if (!isContainedBy(this.root, databasePath)) {
-      throw new Error("transaction-database-path-invalid");
-    }
-    const existing = lstatSync(databasePath, { throwIfNoEntry: false });
-    if (existing && (!existing.isFile() || existing.isSymbolicLink())) {
-      throw new Error("transaction-database-path-invalid");
-    }
-    this.#database = new DatabaseSync(databasePath);
-    configureSqlite(this.#database);
-    ensureSqliteSchema(this.#database, APPLY_SCHEMA);
-    chmodSync(databasePath, 0o600);
-  }
-
-  #save(journal: TransactionJournal): void {
-    if (this.#closed) throw new Error("transaction-store-closed");
-    const json = JSON.stringify(journal);
-    const digest = journalHash(journal);
-    this.#database
-      .prepare(
-        `INSERT INTO apply_transaction_journal (
-           transaction_id, journal_json, journal_hash
-         ) VALUES (?, ?, ?)
-         ON CONFLICT(transaction_id) DO UPDATE SET
-           journal_json = excluded.journal_json,
-           journal_hash = excluded.journal_hash`,
-      )
-      .run(journal.transactionId, json, digest);
-  }
-
-  #load(transactionId: string): TransactionJournal {
-    if (this.#closed) throw new Error("transaction-store-closed");
-    requireIdentifier(transactionId);
-    const row = this.#database
-      .prepare(
-        `SELECT journal_json, journal_hash
-         FROM apply_transaction_journal WHERE transaction_id = ?`,
-      )
-      .get(transactionId) as JournalRow | undefined;
-    if (!row) throw new Error("transaction-unavailable");
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(row.journal_json);
-    } catch {
-      throw new Error("transaction-journal-invalid");
-    }
-    const journal = validateJournal(parsed);
-    if (journalHash(journal) !== row.journal_hash) {
-      throw new Error("transaction-journal-integrity-invalid");
-    }
-    return structuredClone(journal);
-  }
-
-  #project(journal: TransactionJournal, replayed = false) {
-    return {
-      transactionId: journal.transactionId,
-      state: journal.state,
-      ...(journal.code ? { code: journal.code } : {}),
-      ...(journal.pendingIntent
-        ? { pendingIntent: journal.pendingIntent }
-        : {}),
-      rollbackRetained: journal.rollbackRetained,
-      externalPaths: [...journal.externalPaths],
-      steps: journal.steps.map((step) => ({
-        path: step.path,
-        state: step.state,
-      })),
-      events: journal.events
-        .filter((entry) => entry.kind === "intent-prepared")
-        .map((entry) => ({ ...entry })),
-      ...(replayed ? { replayed: true as const } : {}),
-    };
-  }
-
-  #outcome(
-    journal: TransactionJournal,
-    replayed = false,
-  ): ApplyTransactionOutcome {
-    if (journal.state === "completed" || journal.state === "prepared") {
-      return {
-        ok: true,
-        transactionId: journal.transactionId,
-        state: journal.state,
-        ...(replayed ? { replayed: true as const } : {}),
-      };
-    }
-    if (journal.state !== "paused" && journal.state !== "discarded") {
-      throw new Error("transaction-outcome-nonterminal");
-    }
-    return {
-      ok: false,
-      transactionId: journal.transactionId,
-      state: journal.state,
-      code: journal.code ?? "recovery-required",
-      ...(replayed ? { replayed: true as const } : {}),
-    };
-  }
-
-  #settledOutcome(
-    journal: TransactionJournal,
-  ): ApplyTransactionOutcome | undefined {
-    return journal.state === "completed" ||
-      journal.state === "paused" ||
-      journal.state === "discarded"
-      ? this.#outcome(journal)
-      : undefined;
-  }
-
-  async prepare(input: PrepareApplyInput): Promise<ApplyTransactionOutcome> {
-    requireIdentifier(input.transactionId);
-    requireRevisionId(input.baselineRevisionId);
-    requireRevisionId(input.finalRevisionId);
-    if (!Array.isArray(input.boundPaths) || input.boundPaths.length === 0) {
-      throw new Error("transaction-bound-paths-invalid");
-    }
-    const boundPaths = [...new Set(input.boundPaths)].sort();
-    if (boundPaths.length !== input.boundPaths.length) {
-      throw new Error("transaction-bound-paths-invalid");
-    }
-    for (const relative of boundPaths) requireRelative(relative);
-    const fact =
-      input.verificationFact && typeof input.verificationFact === "object"
-        ? verificationFacts.get(input.verificationFact)
-        : undefined;
-    if (
-      !fact ||
-      fact.workspaceStore !== this.#workspaces ||
-      fact.revisionId !== input.finalRevisionId
-    ) {
-      throw new Error("verification-fact-invalid");
-    }
-    const consumerRoot = canonicalConsumerRoot(input.consumerRoot);
-    if (isContainedBy(consumerRoot, this.root)) {
-      throw new Error("transaction-root-inside-consumer");
-    }
-    const existing = this.#database
-      .prepare(
-        "SELECT journal_json, journal_hash FROM apply_transaction_journal WHERE transaction_id = ?",
-      )
-      .get(input.transactionId) as JournalRow | undefined;
-    if (existing) {
-      const journal = this.#load(input.transactionId);
-      if (
-        journal.consumerRoot !== consumerRoot ||
-        journal.baselineRevisionId !== input.baselineRevisionId ||
-        journal.finalRevisionId !== input.finalRevisionId ||
-        journal.verificationId !== fact.verificationId ||
-        JSON.stringify(journal.boundPaths) !== JSON.stringify(boundPaths)
-      ) {
-        throw new Error("transaction-id-conflict");
-      }
-      return this.#outcome(journal, true);
-    }
-
-    const baseline = this.#workspaces.getRevision(input.baselineRevisionId);
-    const finalRevision = this.#workspaces.getRevision(input.finalRevisionId);
-    if (!isAncestor(this.#workspaces, baseline.revisionId, finalRevision)) {
-      throw new Error("workspace-revision-base-invalid");
-    }
-    for (const relative of boundPaths) {
-      const expected = normalizedEntry(baseline.entries[relative]);
-      if (!mainMatches(consumerRoot, relative, expected)) {
-        return {
-          ok: false,
-          transactionId: input.transactionId,
-          state: "paused",
-          code: "main-workspace-stale",
-        };
-      }
-    }
-    const steps = boundPaths.map((relative) => ({
-      path: relative,
-      before: normalizedEntry(baseline.entries[relative]),
-      after: normalizedEntry(finalRevision.entries[relative]),
-      state: "pending" as const,
-    }));
-    const retainedHashes = [
-      ...new Set(
-        steps.flatMap((step) =>
-          [step.before, step.after]
-            .filter(
-              (entry): entry is Extract<WorkspaceEntry, { kind: "file" }> =>
-                entry.kind === "file",
-            )
-            .map((entry) => entry.hash),
-        ),
-      ),
-    ].sort();
-    for (const hash of retainedHashes) this.#artifacts.retain(hash);
-    const journal: TransactionJournal = {
-      transactionId: input.transactionId,
-      consumerRoot,
-      baselineRevisionId: baseline.revisionId,
-      finalRevisionId: finalRevision.revisionId,
-      verificationId: fact.verificationId,
-      boundPaths,
-      state: "prepared",
-      rollbackRetained: true,
-      externalPaths: [],
-      retainedHashes,
-      releasedHashes: [],
-      createdDirectories: [],
-      steps,
-      events: [],
-    };
-    event(journal, "intent-prepared");
-    this.#save(journal);
-    return this.#outcome(journal);
-  }
-
-  #ensureTargetParents(journal: TransactionJournal, relative: string): string {
-    const segments = relative.split("/");
-    let parent = journal.consumerRoot;
-    const relativeSegments: string[] = [];
-    for (const segment of segments.slice(0, -1)) {
-      parent = path.join(parent, segment);
-      relativeSegments.push(segment);
-      const directory = relativeSegments.join("/");
-      const stat = lstatSync(parent, { throwIfNoEntry: false });
-      if (stat) {
-        if (!stat.isDirectory() || stat.isSymbolicLink()) {
-          throw new Error("transaction-target-unsafe");
-        }
-        continue;
-      }
-      if (!journal.createdDirectories.includes(directory)) {
-        journal.createdDirectories.push(directory);
-        event(journal, "directory-create-intent", directory);
-        this.#save(journal);
-      }
-      try {
-        mkdirSync(parent, { mode: 0o755 });
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-        journal.createdDirectories = journal.createdDirectories.filter(
-          (candidate) => candidate !== directory,
-        );
-        this.#save(journal);
-      }
-      const created = lstatSync(parent, { throwIfNoEntry: false });
-      if (!created?.isDirectory() || created.isSymbolicLink()) {
-        throw new Error("transaction-target-unsafe");
-      }
-      syncDirectory(path.dirname(parent));
-      if (journal.createdDirectories.includes(directory)) {
-        event(journal, "directory-created", directory);
-        this.#save(journal);
-      }
-    }
-    return safeTargetPath(journal.consumerRoot, relative);
-  }
-
-  #claimPath(journal: TransactionJournal, step: TransactionStep): string {
-    const target = safeTargetPath(journal.consumerRoot, step.path);
-    return path.join(
-      path.dirname(target),
-      `.${path.basename(target)}.${createHash("sha256")
-        .update(`${journal.transactionId}\0${step.path}`)
-        .digest("hex")
-        .slice(0, 24)}.apply-claim`,
-    );
-  }
-
-  #settleClaim(journal: TransactionJournal, step: TransactionStep): boolean {
-    const target = safeTargetPath(journal.consumerRoot, step.path);
-    const claim = this.#claimPath(journal, step);
-    const claimed = fileEntryAt(claim);
-    if (claimed === "absent") return true;
-    if (claimed === "unsafe") return false;
-    const current = currentEntry(journal.consumerRoot, step.path);
-    if (current !== "unsafe" && current.kind === "absent") {
-      return restoreClaim(claim, target);
-    }
-    if (
-      current !== "unsafe" &&
-      (entryEqual(claimed, step.before) || entryEqual(claimed, step.after))
-    ) {
-      unlinkSync(claim);
-      syncDirectory(path.dirname(target));
-      return true;
-    }
-    return false;
-  }
-
-  #applyEntry(
-    journal: TransactionJournal,
-    step: TransactionStep,
-    expected: WorkspaceEntry,
-    entry: WorkspaceEntry,
-  ): boolean {
-    const target = this.#ensureTargetParents(journal, step.path);
-    const directory = path.dirname(target);
-    const claim = this.#claimPath(journal, step);
-    if (lstatSync(claim, { throwIfNoEntry: false })) {
-      throw new Error("transaction-claim-unsettled");
-    }
-
-    if (expected.kind === "file") {
-      try {
-        renameSync(target, claim);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-        throw error;
-      }
-      syncDirectory(directory);
-      const claimed = fileEntryAt(claim);
-      if (
-        claimed === "unsafe" ||
-        claimed === "absent" ||
-        !entryEqual(claimed, expected)
-      ) {
-        if (!restoreClaim(claim, target)) {
-          throw new Error("transaction-claim-conflict");
-        }
-        return false;
-      }
-    } else if (lstatSync(target, { throwIfNoEntry: false })) {
-      return false;
-    }
-
-    if (entry.kind === "absent") {
-      if (expected.kind === "file") {
-        unlinkSync(claim);
-        syncDirectory(directory);
-      }
-      return true;
-    }
-    const bytes = this.#artifacts.read(entry.hash);
-    if (bytes.byteLength !== entry.bytes) {
-      throw new Error("transaction-artifact-integrity-invalid");
-    }
-    const installed = writeExclusiveFile(target, bytes, entry.mode);
-    if (expected.kind === "file") {
-      unlinkSync(claim);
-      syncDirectory(directory);
-    }
-    return installed;
-  }
-
-  async #release(journal: TransactionJournal): Promise<void> {
-    if (!journal.rollbackRetained) return;
-    for (const hash of journal.retainedHashes) {
-      if (journal.releasedHashes.includes(hash)) continue;
-      this.#artifacts.release(hash);
-      journal.releasedHashes.push(hash);
-      this.#save(journal);
-    }
-    journal.rollbackRetained = false;
-    this.#save(journal);
-  }
-
-  #rollbackCreatedDirectories(
-    journal: TransactionJournal,
-    external: Set<string>,
-  ): void {
-    const deepestFirst = [...journal.createdDirectories].sort(
-      (left, right) =>
-        right.split("/").length - left.split("/").length ||
-        compareCanonicalStrings(right, left),
-    );
-    for (const relative of deepestFirst) {
-      const observation = observeSafePath(journal.consumerRoot, relative);
-      if (observation.kind === "absent") continue;
-      if (observation.kind !== "directory") {
-        external.add(relative);
-        continue;
-      }
-      const target = path.join(journal.consumerRoot, ...relative.split("/"));
-      try {
-        rmdirSync(target);
-      } catch (error) {
-        if (
-          ["ENOTEMPTY", "EEXIST"].includes(
-            (error as NodeJS.ErrnoException).code ?? "",
-          )
-        ) {
-          external.add(relative);
-          continue;
-        }
-        throw error;
-      }
-      syncDirectory(path.dirname(target));
-      event(journal, "directory-rolled-back", relative);
-      this.#save(journal);
-    }
-  }
-
-  async #rollback(
-    journal: TransactionJournal,
-    terminal: {
-      state: "paused" | "discarded";
-      code: string;
-      externalPaths?: string[];
-    },
-  ): Promise<ApplyTransactionOutcome> {
-    journal.state = "recovering";
-    event(journal, "rollback-started");
-    this.#save(journal);
-    const external = new Set(terminal.externalPaths ?? []);
-    for (const step of [...journal.steps].reverse()) {
-      if (!this.#settleClaim(journal, step)) {
-        external.add(step.path);
-        continue;
-      }
-      const current = currentEntry(journal.consumerRoot, step.path);
-      if (step.state === "pending") {
-        if (current !== "unsafe" && entryEqual(current, step.before)) {
-          step.state = "rolled-back";
-          this.#save(journal);
-        } else {
-          external.add(step.path);
-        }
-        continue;
-      }
-      if (current !== "unsafe" && entryEqual(current, step.after)) {
-        if (!entryEqual(step.before, step.after)) {
-          if (!this.#applyEntry(journal, step, step.after, step.before)) {
-            external.add(step.path);
-            continue;
-          }
-        }
-        step.state = "rolled-back";
-        event(journal, "file-rolled-back", step.path);
-        this.#save(journal);
-      } else if (current !== "unsafe" && entryEqual(current, step.before)) {
-        step.state = "rolled-back";
-        this.#save(journal);
-      } else {
-        external.add(step.path);
-      }
-    }
-    this.#rollbackCreatedDirectories(journal, external);
-    journal.externalPaths = [...external].sort();
-    journal.state = terminal.state;
-    journal.code = terminal.code;
-    event(journal, "rollback-settled");
-    this.#save(journal);
-    await this.#release(journal);
-    return this.#outcome(journal);
-  }
-
-  async #driveForward(
-    transactionId: string,
-    signal?: AbortSignal,
-  ): Promise<ApplyTransactionOutcome> {
-    let journal = this.#load(transactionId);
-    if (journal.pendingIntent) {
-      return this.#rollback(journal, {
-        state: journal.pendingIntent === "discard" ? "discarded" : "paused",
-        code:
-          journal.pendingIntent === "discard"
-            ? "run-discarded"
-            : "operation-cancelled",
-      });
-    }
-    journal.state = journal.state === "recovering" ? "recovering" : "applying";
-    event(journal, "apply-started");
-    this.#save(journal);
-
-    for (const [index, originalStep] of journal.steps.entries()) {
-      journal = this.#load(transactionId);
-      let step = journal.steps[index] as TransactionStep;
-      if (journal.pendingIntent || signal?.aborted) {
-        journal.pendingIntent ??= "cancel";
-        journal.state = "recovering";
-        event(journal, "control-pending");
-        this.#save(journal);
-        return this.#rollback(journal, {
-          state: journal.pendingIntent === "discard" ? "discarded" : "paused",
-          code:
-            journal.pendingIntent === "discard"
-              ? "run-discarded"
-              : "operation-cancelled",
-        });
-      }
-      if (!this.#settleClaim(journal, step)) {
-        return this.#rollback(journal, {
-          state: "paused",
-          code: "recovery-required",
-          externalPaths: [step.path],
-        });
-      }
-      const current = currentEntry(journal.consumerRoot, step.path);
-      if (step.state === "applied") {
-        if (current === "unsafe" || !entryEqual(current, step.after)) {
-          return this.#rollback(journal, {
-            state: "paused",
-            code: "recovery-required",
-            externalPaths: [step.path],
-          });
-        }
-        continue;
-      }
-      if (
-        step.state === "applying" &&
-        current !== "unsafe" &&
-        entryEqual(current, step.after)
-      ) {
-        step.state = "applied";
-        event(journal, "file-apply-recovered", step.path);
-        this.#save(journal);
-        continue;
-      }
-      if (current === "unsafe" || !entryEqual(current, step.before)) {
-        return this.#rollback(journal, {
-          state: "paused",
-          code: "recovery-required",
-          externalPaths: [step.path],
-        });
-      }
-
-      if (entryEqual(step.before, step.after)) {
-        step.state = "applied";
-        event(journal, "bound-path-checked", step.path);
-        this.#save(journal);
-        continue;
-      }
-
-      step.state = "applying";
-      event(journal, "file-step-started", step.path);
-      this.#save(journal);
-      await this.#hooks.beforeFileMutation?.({
-        transactionId,
-        path: originalStep.path,
-        index,
-      });
-      journal = this.#load(transactionId);
-      step = journal.steps[index] as TransactionStep;
-      if (journal.pendingIntent || signal?.aborted) {
-        journal.pendingIntent ??= "cancel";
-        this.#save(journal);
-        return this.#rollback(journal, {
-          state: journal.pendingIntent === "discard" ? "discarded" : "paused",
-          code:
-            journal.pendingIntent === "discard"
-              ? "run-discarded"
-              : "operation-cancelled",
-        });
-      }
-      if (!this.#applyEntry(journal, step, step.before, step.after)) {
-        return this.#rollback(journal, {
-          state: "paused",
-          code: "recovery-required",
-          externalPaths: [step.path],
-        });
-      }
-      await this.#hooks.afterFileMutationBeforeSave?.({
-        transactionId,
-        path: originalStep.path,
-        index,
-      });
-      journal = this.#load(transactionId);
-      step = journal.steps[index] as TransactionStep;
-      step.state = "applied";
-      event(journal, "file-applied", step.path);
-      this.#save(journal);
-      try {
-        await this.#hooks.afterFileMutation?.({
-          transactionId,
-          path: originalStep.path,
-          index,
-        });
-      } catch (error) {
-        journal = this.#load(transactionId);
-        const settled = this.#settledOutcome(journal);
-        if (settled) return settled;
-        if (!journal.pendingIntent && !signal?.aborted) throw error;
-      }
-      journal = this.#load(transactionId);
-      const settled = this.#settledOutcome(journal);
-      if (settled) return settled;
-      if (journal.pendingIntent || signal?.aborted) {
-        journal.pendingIntent ??= "cancel";
-        journal.state = "recovering";
-        event(journal, "control-pending");
-        this.#save(journal);
-        return this.#rollback(journal, {
-          state: journal.pendingIntent === "discard" ? "discarded" : "paused",
-          code:
-            journal.pendingIntent === "discard"
-              ? "run-discarded"
-              : "operation-cancelled",
-        });
-      }
-      const appliedStep = journal.steps[index] as TransactionStep;
-      if (
-        !mainMatches(journal.consumerRoot, appliedStep.path, appliedStep.after)
-      ) {
-        return this.#rollback(journal, {
-          state: "paused",
-          code: "recovery-required",
-          externalPaths: [appliedStep.path],
-        });
-      }
-    }
-
-    journal = this.#load(transactionId);
-    const external = journal.steps
-      .filter(
-        (step) => !mainMatches(journal.consumerRoot, step.path, step.after),
-      )
-      .map((step) => step.path);
-    if (external.length > 0) {
-      return this.#rollback(journal, {
-        state: "paused",
-        code: "recovery-required",
-        externalPaths: external,
-      });
-    }
-    let postApply: { ok: true } | { ok: false; code: string } | undefined;
-    try {
-      if (this.#hooks.postApply) {
-        const isolatedRoot = mkdtempSync(
-          path.join(this.root, "post-apply-verification-"),
-        );
-        try {
-          await this.#workspaces.materializeAsync(
-            journal.finalRevisionId,
-            isolatedRoot,
-            signal,
-          );
-          const execution = Promise.resolve(
-            this.#hooks.postApply({
-              transactionId,
-              root: isolatedRoot,
-              signal: signal ?? new AbortController().signal,
-            }),
-          );
-          void execution.catch(() => undefined);
-          postApply =
-            signal && !this.#hooks.awaitPostApplySettlement
-              ? await raceWithAbort(execution, signal)
-              : await execution;
-        } finally {
-          if (!isExecutionRetained(isolatedRoot))
-            removePathSync(isolatedRoot, { recursive: true, force: true });
-        }
-      }
-    } catch (error) {
-      journal = this.#load(transactionId);
-      const settled = this.#settledOutcome(journal);
-      if (settled) return settled;
-      if (!journal.pendingIntent && !signal?.aborted) throw error;
-    }
-    if (isExecutionRetained(this.root)) {
-      journal = this.#load(transactionId);
-      journal.state = "recovering";
-      journal.code = "isolation-termination-unconfirmed";
-      this.#save(journal);
-      return { ok: false, transactionId, state: "paused", code: journal.code };
-    }
-    journal = this.#load(transactionId);
-    const settled = this.#settledOutcome(journal);
-    if (settled) return settled;
-    if (journal.pendingIntent || signal?.aborted) {
-      journal.pendingIntent ??= "cancel";
-      journal.state = "recovering";
-      event(journal, "control-pending");
-      this.#save(journal);
-      return this.#rollback(journal, {
-        state: journal.pendingIntent === "discard" ? "discarded" : "paused",
-        code:
-          journal.pendingIntent === "discard"
-            ? "run-discarded"
-            : "operation-cancelled",
-      });
-    }
-    const postApplyExternal = journal.steps
-      .filter(
-        (step) => !mainMatches(journal.consumerRoot, step.path, step.after),
-      )
-      .map((step) => step.path);
-    if (postApplyExternal.length > 0) {
-      return this.#rollback(journal, {
-        state: "paused",
-        code: "recovery-required",
-        externalPaths: postApplyExternal,
-      });
-    }
-    if (postApply && !postApply.ok) {
-      return this.#rollback(journal, {
-        state: "paused",
-        code: postApply.code,
-      });
-    }
-    journal.state = "completed";
-    delete journal.code;
-    event(journal, "transaction-completed");
-    this.#save(journal);
-    await this.#release(journal);
-    return this.#outcome(journal);
-  }
-
-  async apply(
-    transactionId: string,
-    signal?: AbortSignal,
-  ): Promise<ApplyTransactionOutcome> {
-    const journal = this.#load(transactionId);
-    if (journal.state === "completed") {
-      if (journal.rollbackRetained) await this.#release(journal);
-      return this.#outcome(journal, true);
-    }
-    if (journal.state === "paused" || journal.state === "discarded") {
-      return this.#outcome(journal, true);
-    }
-    try {
-      return await this.#drive(transactionId, signal);
-    } catch (error) {
-      const interrupted = this.#load(transactionId);
-      if (
-        interrupted.state !== "completed" &&
-        interrupted.state !== "paused" &&
-        interrupted.state !== "discarded"
-      ) {
-        interrupted.state = "recovering";
-        event(interrupted, "apply-interrupted");
-        this.#save(interrupted);
-      }
-      throw error;
-    }
-  }
-
-  async recover(transactionId: string): Promise<ApplyTransactionOutcome> {
-    const journal = this.#load(transactionId);
-    if (
-      journal.state === "completed" ||
-      journal.state === "paused" ||
-      journal.state === "discarded"
-    ) {
-      if (journal.rollbackRetained) await this.#release(journal);
-      return this.#outcome(journal, true);
-    }
-    return this.#drive(transactionId);
-  }
-
-  #drive(
-    transactionId: string,
-    parentSignal?: AbortSignal,
-  ): Promise<ApplyTransactionOutcome> {
-    const existing = this.#active.get(transactionId);
-    if (existing) return existing.promise;
-    if (isExecutionRetained(this.root))
-      return Promise.resolve({
-        ok: false,
-        transactionId,
-        state: "paused",
-        code: "isolation-termination-unconfirmed",
-      });
-    const controller = new AbortController();
-    const forwardAbort = () => {
-      if (!controller.signal.aborted) {
-        controller.abort(
-          parentSignal?.reason ?? new Error("operation-cancelled"),
-        );
-      }
-    };
-    if (parentSignal?.aborted) forwardAbort();
-    else parentSignal?.addEventListener("abort", forwardAbort, { once: true });
-    let active!: {
-      controller: AbortController;
-      promise: Promise<ApplyTransactionOutcome>;
-    };
-    const promise = this.#driveForward(
-      transactionId,
-      controller.signal,
-    ).finally(() => {
-      parentSignal?.removeEventListener("abort", forwardAbort);
-      if (this.#active.get(transactionId) === active) {
-        this.#active.delete(transactionId);
-      }
-    });
-    active = { controller, promise };
-    this.#active.set(transactionId, active);
-    return active.promise;
-  }
-
-  requestControl(transactionId: string, intent: PendingIntent) {
-    if (intent !== "cancel" && intent !== "discard") {
-      throw new Error("transaction-control-invalid");
-    }
-    const journal = this.#load(transactionId);
-    if (journal.state === "completed" || journal.state === "discarded") {
-      return this.#project(journal, true);
-    }
-    journal.pendingIntent = intent;
-    journal.state = "recovering";
-    event(journal, "control-pending");
-    this.#save(journal);
-    const active = this.#active.get(transactionId);
-    if (active && !active.controller.signal.aborted) {
-      active.controller.abort(
-        new Error(
-          intent === "discard" ? "run-discarded" : "operation-cancelled",
-        ),
-      );
-    }
-    return this.#project(journal);
-  }
-
-  status(transactionId: string) {
-    return this.#project(this.#load(transactionId));
-  }
-
-  close(): void {
-    if (this.#closed) return;
-    this.#closed = true;
-    this.#database.close();
-  }
-
-  [Symbol.dispose](): void {
-    this.close();
-  }
-}