amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/tree-materialization.js

@@ -0,0 +1,3766 @@
+'use strict';
+
+/**
+ * Durable physical plan for workspace-tree snapshots.
+ *
+ * The tree database and replica cursor are control records. Before either can
+ * move, every destructive filesystem action is named here with its exact
+ * source identity and a deterministic, same-filesystem staging path. A crash
+ * can therefore resume the one plan instead of guessing from whatever paths
+ * happen to exist after restart.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { shouldEnroll } = require('./tree/inclusion');
+const { isPathAbsentError } = require('./tree/path-state');
+const { openLocalDb } = require('../state/db');
+const nativeFileTransaction = require('./native-file-transaction/client');
+
+const CONTRACT = 'workspace-tree-materialization@1';
+const OPERATION_CONTRACT = 'workspace-tree-operation-materialization@1';
+
+function ensureSchema(database = openLocalDb()) {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS workspace_tree_materializations (
+      resource_id TEXT NOT NULL,
+      snapshot_version INTEGER NOT NULL,
+      snapshot_checksum TEXT NOT NULL,
+      local_path TEXT NOT NULL,
+      plan_json TEXT NOT NULL,
+      materialization_state TEXT NOT NULL DEFAULT 'prepared'
+        CHECK (materialization_state IN ('prepared', 'crossed', 'committed')),
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      PRIMARY KEY(resource_id, snapshot_version)
+    );
+
+    CREATE TABLE IF NOT EXISTS workspace_tree_operation_materializations (
+      resource_id TEXT NOT NULL,
+      mutation_id TEXT NOT NULL,
+      official_version INTEGER NOT NULL,
+      plan_json TEXT NOT NULL,
+      materialization_state TEXT NOT NULL DEFAULT 'prepared'
+        CHECK (materialization_state IN ('prepared', 'crossed', 'committed')),
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      PRIMARY KEY(resource_id, mutation_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS workspace_tree_operation_successors (
+      successor_seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      resource_id TEXT NOT NULL,
+      owner_mutation_id TEXT NOT NULL,
+      successor_mutation_id TEXT NOT NULL,
+      operation_json TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      UNIQUE(resource_id, owner_mutation_id, successor_mutation_id)
+    );
+  `);
+}
+
+function normalize(row) {
+  if (!row) return null;
+  return {
+    resourceId: row.resource_id,
+    snapshotVersion: Number(row.snapshot_version),
+    snapshotChecksum: row.snapshot_checksum,
+    localPath: row.local_path,
+    plan: JSON.parse(row.plan_json),
+    state: row.materialization_state,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function list(database = openLocalDb(), resourceId = null) {
+  ensureSchema(database);
+  const rows = resourceId
+    ? database.prepare(`
+      SELECT * FROM workspace_tree_materializations
+      WHERE resource_id = ?
+      ORDER BY snapshot_version ASC
+    `).all(resourceId)
+    : database.prepare(`
+      SELECT * FROM workspace_tree_materializations
+      ORDER BY created_at ASC, resource_id ASC, snapshot_version ASC
+    `).all();
+  return rows.map(normalize);
+}
+
+function get(resourceId, snapshotVersion, database = openLocalDb()) {
+  ensureSchema(database);
+  return normalize(database.prepare(`
+    SELECT * FROM workspace_tree_materializations
+    WHERE resource_id = ? AND snapshot_version = ?
+  `).get(resourceId, snapshotVersion));
+}
+
+function insert(plan, database = openLocalDb()) {
+  ensureSchema(database);
+  const body = JSON.stringify(plan);
+  database.prepare(`
+    INSERT INTO workspace_tree_materializations (
+      resource_id, snapshot_version, snapshot_checksum, local_path, plan_json
+    ) VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(resource_id, snapshot_version) DO NOTHING
+  `).run(
+    plan.resourceId,
+    plan.snapshotVersion,
+    plan.snapshotChecksum,
+    plan.rootPath,
+    body,
+  );
+  const held = get(plan.resourceId, plan.snapshotVersion, database);
+  if (
+    !held
+    || held.snapshotChecksum !== plan.snapshotChecksum
+    || JSON.stringify(held.plan) !== body
+  ) {
+    throw new Error(
+      `workspace tree snapshot ${plan.resourceId}@${plan.snapshotVersion} changed its physical plan`,
+    );
+  }
+  return held;
+}
+
+function normalizedExcludedPrefixes(values = []) {
+  const normalized = Array.from(new Set(values.map((value) => (
+    String(value || '').split('/').filter(Boolean).join('/')
+  )).filter(Boolean))).sort((left, right) => (
+    left.split('/').length - right.split('/').length
+    || left.localeCompare(right)
+  ));
+  const roots = [];
+  for (const candidate of normalized) {
+    if (roots.some((root) => (
+      candidate === root || candidate.startsWith(`${root}/`)
+    ))) continue;
+    roots.push(candidate);
+  }
+  return roots;
+}
+
+function excludedPathMatcher(values) {
+  const prefixes = normalizedExcludedPrefixes(values);
+  const root = { terminal: false, children: new Map() };
+  for (const prefix of prefixes) {
+    let current = root;
+    for (const segment of prefix.split('/')) {
+      if (!current.children.has(segment)) {
+        current.children.set(segment, { terminal: false, children: new Map() });
+      }
+      current = current.children.get(segment);
+    }
+    current.terminal = true;
+  }
+  return {
+    prefixes,
+    matches(relativePath) {
+      let current = root;
+      for (const segment of relativePath.split('/').filter(Boolean)) {
+        current = current.children.get(segment);
+        if (!current) return false;
+        if (current.terminal) return true;
+      }
+      return current.terminal;
+    },
+  };
+}
+
+function contentDigest(target, stat, options = {}) {
+  const hash = crypto.createHash('sha256');
+  const excluded = excludedPathMatcher(options.excludedPrefixes);
+  const visit = (candidate, relative) => {
+    if (relative && excluded.matches(relative)) return;
+    if (typeof options.onVisit === 'function') options.onVisit(candidate, relative);
+    const held = fs.lstatSync(candidate, { bigint: true });
+    const kind = held.isSymbolicLink()
+      ? 'symlink'
+      : held.isDirectory()
+        ? 'folder'
+        : held.isFile()
+          ? 'file'
+          : 'other';
+    hash.update(`${relative}\0${kind}\0${held.mode}\0${held.size}\0`);
+    if (kind === 'symlink') {
+      hash.update(fs.readlinkSync(candidate));
+      return;
+    }
+    if (kind === 'file') {
+      hash.update(fs.readFileSync(candidate));
+      return;
+    }
+    if (kind !== 'folder') return;
+    for (const name of fs.readdirSync(candidate).sort()) {
+      visit(path.join(candidate, name), relative ? `${relative}/${name}` : name);
+    }
+  };
+  visit(target, '');
+  hash.update(`\0root:${stat.dev}:${stat.ino}`);
+  return hash.digest('hex');
+}
+
+function identity(target, options = {}) {
+  const stat = fs.lstatSync(target, { bigint: true });
+  const excludedPrefixes = normalizedExcludedPrefixes(options.excludedPrefixes);
+  const value = {
+    kind: stat.isSymbolicLink()
+      ? 'symlink'
+      : stat.isDirectory()
+        ? 'folder'
+        : stat.isFile()
+          ? 'file'
+          : 'other',
+    dev: stat.dev.toString(),
+    ino: stat.ino.toString(),
+  };
+  if (options.deep !== false) {
+    value.digest = contentDigest(target, stat, {
+      excludedPrefixes,
+      onVisit: options.onVisit,
+    });
+    if (excludedPrefixes.length) value.excludedPrefixes = excludedPrefixes;
+  }
+  return value;
+}
+
+function nativeByteIdentity(target, stat = fs.lstatSync(target, { bigint: true })) {
+  let content;
+  let kind;
+  if (stat.isSymbolicLink()) {
+    kind = 'symlink';
+    content = Buffer.from(fs.readlinkSync(target));
+  } else if (stat.isFile()) {
+    kind = 'file';
+    content = fs.readFileSync(target);
+  } else {
+    throw new Error(`workspace tree retirement only supports byte leaves: ${target}`);
+  }
+  return {
+    kind,
+    exec: kind === 'file' && (stat.mode & 0o100n) !== 0n,
+    bytes: content.length,
+    sha256: crypto.createHash('sha256').update(content).digest('hex'),
+    ...((kind === 'file' || kind === 'symlink') ? {
+      dev: stat.dev.toString(),
+      ino: stat.ino.toString(),
+    } : {}),
+  };
+}
+
+/**
+ * Capture the exact leaf set before a destructive tree transition. The deep
+ * root identity proves nothing changed before staging; the leaf manifest lets
+ * cleanup retire unchanged bytes individually while retaining only a newer or
+ * still-open writer and the ancestors that writer needs.
+ */
+function removalPrecondition(target, options = {}) {
+  const entries = [];
+  const directories = [];
+  const excluded = excludedPathMatcher(options.excludedPrefixes);
+  const visit = (candidate, relativePath) => {
+    if (relativePath && excluded.matches(relativePath)) return;
+    if (typeof options.onVisit === 'function') options.onVisit(candidate, relativePath);
+    const stat = fs.lstatSync(candidate, { bigint: true });
+    if (stat.isDirectory()) {
+      directories.push({
+        relativePath,
+        dev: stat.dev.toString(),
+        ino: stat.ino.toString(),
+      });
+      for (const name of fs.readdirSync(candidate).sort()) {
+        visit(
+          path.join(candidate, name),
+          relativePath ? `${relativePath}/${name}` : name,
+        );
+      }
+      return;
+    }
+    entries.push({
+      relativePath,
+      identity: nativeByteIdentity(candidate, stat),
+    });
+  };
+  visit(target, '');
+  return {
+    identity: identity(target, {
+      excludedPrefixes: excluded.prefixes,
+    }),
+    retirement: { entries, directories },
+  };
+}
+
+function sameIdentity(target, expected) {
+  try {
+    return JSON.stringify(identity(target, {
+      deep: Object.prototype.hasOwnProperty.call(expected || {}, 'digest'),
+      excludedPrefixes: expected?.excludedPrefixes,
+    })) === JSON.stringify(expected);
+  } catch (error) {
+    if (isPathAbsentError(error)) return false;
+    throw error;
+  }
+}
+
+function exists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch (error) {
+    if (isPathAbsentError(error)) return false;
+    throw error;
+  }
+}
+
+function stagingRoot(plan) {
+  const id = crypto.createHash('sha256')
+    .update(
+      `${plan.contract || CONTRACT}\0${plan.resourceId}\0`
+      + `${plan.snapshotVersion ?? plan.version}\0${plan.snapshotChecksum || plan.mutationId}`,
+    )
+    .digest('hex')
+    .slice(0, 24);
+  // A receipt is not user content. Keep it beside the registered workspace so
+  // it remains on the same filesystem without ever entering that workspace's
+  // observer namespace.
+  return path.join(path.dirname(plan.rootPath), `.amalgm-tree-apply-${id}`);
+}
+
+function normalizeOperation(row) {
+  if (!row) return null;
+  return {
+    resourceId: row.resource_id,
+    mutationId: row.mutation_id,
+    version: Number(row.official_version),
+    plan: JSON.parse(row.plan_json),
+    state: row.materialization_state,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function getOperation(resourceId, mutationId, database = openLocalDb()) {
+  ensureSchema(database);
+  return normalizeOperation(database.prepare(`
+    SELECT * FROM workspace_tree_operation_materializations
+    WHERE resource_id = ? AND mutation_id = ?
+  `).get(resourceId, mutationId));
+}
+
+function listOperations(database = openLocalDb(), resourceId = null) {
+  ensureSchema(database);
+  const rows = resourceId
+    ? database.prepare(`
+      SELECT * FROM workspace_tree_operation_materializations
+      WHERE resource_id = ?
+      ORDER BY official_version ASC, created_at ASC
+    `).all(resourceId)
+    : database.prepare(`
+      SELECT * FROM workspace_tree_operation_materializations
+      ORDER BY created_at ASC, resource_id ASC, official_version ASC
+    `).all();
+  return rows.map(normalizeOperation);
+}
+
+function appendOperationSuccessor(
+  owner,
+  successorMutationId,
+  operation,
+  database = openLocalDb(),
+) {
+  ensureSchema(database);
+  // Cancellation may remove a prepared control row immediately before the
+  // observer discovers a structural successor. Recreate that exact owner in
+  // the same transaction as the first successor append: a crash may leave
+  // both facts or neither, never an orphan chain with no recovery plan.
+  if (!getOperation(owner.resourceId, owner.mutationId, database)) {
+    insertOperation(owner, database);
+  }
+  const operationJson = JSON.stringify(operation);
+  database.prepare(`
+    INSERT INTO workspace_tree_operation_successors (
+      resource_id, owner_mutation_id, successor_mutation_id, operation_json
+    ) VALUES (?, ?, ?, ?)
+    ON CONFLICT(resource_id, owner_mutation_id, successor_mutation_id)
+    DO UPDATE SET operation_json = excluded.operation_json
+  `).run(
+    owner.resourceId,
+    owner.mutationId,
+    successorMutationId,
+    operationJson,
+  );
+}
+
+function listOperationSuccessors(owner, database = openLocalDb()) {
+  ensureSchema(database);
+  return database.prepare(`
+    SELECT successor_mutation_id, operation_json
+    FROM workspace_tree_operation_successors
+    WHERE resource_id = ? AND owner_mutation_id = ?
+    ORDER BY successor_seq
+  `).all(owner.resourceId, owner.mutationId).map((row) => ({
+    mutationId: row.successor_mutation_id,
+    operation: JSON.parse(row.operation_json),
+  }));
+}
+
+function clearOperationSuccessors(owner, database = openLocalDb()) {
+  ensureSchema(database);
+  database.prepare(`
+    DELETE FROM workspace_tree_operation_successors
+    WHERE resource_id = ? AND owner_mutation_id = ?
+  `).run(owner.resourceId, owner.mutationId);
+}
+
+function insertOperation(plan, database = openLocalDb()) {
+  ensureSchema(database);
+  const body = JSON.stringify(plan);
+  database.prepare(`
+    INSERT INTO workspace_tree_operation_materializations (
+      resource_id, mutation_id, official_version, plan_json
+    ) VALUES (?, ?, ?, ?)
+    ON CONFLICT(resource_id, mutation_id) DO NOTHING
+  `).run(plan.resourceId, plan.mutationId, plan.version, body);
+  const held = getOperation(plan.resourceId, plan.mutationId, database);
+  if (!held || held.version !== plan.version || JSON.stringify(held.plan) !== body) {
+    throw new Error(
+      `workspace tree operation ${plan.resourceId}/${plan.mutationId} changed its physical plan`,
+    );
+  }
+  return held;
+}
+
+function replacePreparedOperation(held, plan, database = openLocalDb()) {
+  if (
+    !held
+    || held.state !== 'prepared'
+    || held.resourceId !== plan.resourceId
+    || held.mutationId !== plan.mutationId
+  ) {
+    throw new Error('workspace tree replacement plan has no prepared predecessor');
+  }
+  const body = JSON.stringify(plan);
+  const result = database.prepare(`
+    UPDATE workspace_tree_operation_materializations
+    SET official_version = ?,
+        plan_json = ?,
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ?
+      AND mutation_id = ?
+      AND materialization_state = 'prepared'
+  `).run(
+    plan.version,
+    body,
+    plan.resourceId,
+    plan.mutationId,
+  );
+  if (result.changes !== 1) {
+    throw new Error(
+      `workspace tree operation ${plan.resourceId}/${plan.mutationId} lost its prepared plan`,
+    );
+  }
+  const replaced = getOperation(plan.resourceId, plan.mutationId, database);
+  if (
+    !replaced
+    || replaced.version !== plan.version
+    || JSON.stringify(replaced.plan) !== body
+  ) {
+    throw new Error(
+      `workspace tree operation ${plan.resourceId}/${plan.mutationId} changed its replacement plan`,
+    );
+  }
+  return replaced;
+}
+
+/**
+ * A committed plan remains the durable owner of post-commit cleanup. Cleanup
+ * may acquire a named wait (for example, current authority forbids birthing
+ * retained writer bytes), so record that wait on the same immutable plan
+ * identity instead of creating a second control record.
+ */
+function updateCommittedPlan(held, plan, database = openLocalDb()) {
+  if (!held || held.state !== 'committed' || held.resourceId !== plan.resourceId) {
+    throw new Error('workspace tree committed plan update has no committed predecessor');
+  }
+  const operation = held.mutationId != null;
+  if (
+    operation
+      ? held.mutationId !== plan.mutationId || held.version !== Number(plan.version)
+      : held.snapshotVersion !== Number(plan.snapshotVersion)
+        || held.snapshotChecksum !== plan.snapshotChecksum
+  ) {
+    throw new Error('workspace tree committed plan update changed plan identity');
+  }
+  const body = JSON.stringify(plan);
+  const result = operation
+    ? database.prepare(`
+      UPDATE workspace_tree_operation_materializations
+      SET plan_json = ?,
+          updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+      WHERE resource_id = ?
+        AND mutation_id = ?
+        AND materialization_state = 'committed'
+    `).run(body, held.resourceId, held.mutationId)
+    : database.prepare(`
+      UPDATE workspace_tree_materializations
+      SET plan_json = ?,
+          updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+      WHERE resource_id = ?
+        AND snapshot_version = ?
+        AND snapshot_checksum = ?
+        AND materialization_state = 'committed'
+    `).run(
+      body,
+      held.resourceId,
+      held.snapshotVersion,
+      held.snapshotChecksum,
+    );
+  if (result.changes !== 1) {
+    throw new Error('workspace tree committed plan lost its durable owner');
+  }
+  const updated = operation
+    ? getOperation(held.resourceId, held.mutationId, database)
+    : get(held.resourceId, held.snapshotVersion, database);
+  if (!updated || updated.state !== 'committed' || JSON.stringify(updated.plan) !== body) {
+    throw new Error('workspace tree committed plan changed during durable update');
+  }
+  return updated;
+}
+
+function updateUncommittedPlan(held, plan, database = openLocalDb()) {
+  if (
+    !held
+    || held.state === 'committed'
+    || held.resourceId !== plan.resourceId
+    || held.snapshotVersion !== Number(plan.snapshotVersion)
+    || held.snapshotChecksum !== plan.snapshotChecksum
+  ) {
+    throw new Error('workspace tree uncommitted plan update has no exact predecessor');
+  }
+  const body = JSON.stringify(plan);
+  const result = database.prepare(`
+    UPDATE workspace_tree_materializations
+    SET plan_json = ?,
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ?
+      AND snapshot_version = ?
+      AND snapshot_checksum = ?
+      AND materialization_state = ?
+  `).run(
+    body,
+    held.resourceId,
+    held.snapshotVersion,
+    held.snapshotChecksum,
+    held.state,
+  );
+  if (result.changes !== 1) {
+    throw new Error('workspace tree uncommitted plan lost its durable owner');
+  }
+  const updated = get(held.resourceId, held.snapshotVersion, database);
+  if (
+    !updated
+    || updated.state !== held.state
+    || JSON.stringify(updated.plan) !== body
+  ) {
+    throw new Error('workspace tree uncommitted plan changed during durable update');
+  }
+  return updated;
+}
+
+function ensureDurableDirectory(directory) {
+  const target = path.resolve(directory);
+  const missing = [];
+  let current = target;
+  for (;;) {
+    try {
+      const stat = fs.lstatSync(current);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`workspace tree parent is not a physical directory: ${current}`);
+      }
+      break;
+    } catch (error) {
+      if (!isPathAbsentError(error)) throw error;
+      missing.push(current);
+      const parent = path.dirname(current);
+      if (parent === current) {
+        throw new Error(`workspace tree directory has no existing ancestor: ${target}`);
+      }
+      current = parent;
+    }
+  }
+  for (const candidate of missing.reverse()) {
+    try {
+      fs.mkdirSync(candidate);
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const stat = fs.lstatSync(candidate);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw error;
+    }
+    // The new name is not durable until its parent entry is synced. Sync the
+    // new directory too before another child can depend on it.
+    syncDirectory(path.dirname(candidate));
+    syncDirectory(candidate);
+  }
+  syncDirectory(target);
+  return identity(target, { deep: false });
+}
+
+function ensureOperationDirectory(directory) {
+  return ensureDurableDirectory(directory);
+}
+
+function createOperationTargetAt(target, action) {
+  if (exists(target)) {
+    throw new Error(`workspace tree operation prepared target already exists for ${action.nodeId}`);
+  }
+  ensureOperationDirectory(path.dirname(target));
+  if (action.kind === 'folder') ensureOperationDirectory(target);
+  else if (action.kind === 'file') {
+    const descriptor = fs.openSync(target, 'wx');
+    try {
+      fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    syncDirectory(path.dirname(target));
+  } else if (action.kind === 'symlink') {
+    fs.symlinkSync(action.symlinkTarget, target);
+    syncDirectory(path.dirname(target));
+  } else {
+    throw new Error(`unsupported workspace tree operation kind ${action.kind}`);
+  }
+}
+
+function receiptPath(plan, lane, nodeId) {
+  return path.join(stagingRoot(plan), 'receipts', `${lane}-${nodeId}.json`);
+}
+
+function readReceipt(plan, lane, nodeId) {
+  const file = receiptPath(plan, lane, nodeId);
+  if (!exists(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function writeReceipt(plan, lane, nodeId, value) {
+  const file = receiptPath(plan, lane, nodeId);
+  const body = JSON.stringify(value);
+  const existing = readReceipt(plan, lane, nodeId);
+  if (existing) {
+    if (JSON.stringify(existing) !== body) {
+      throw new Error(`workspace tree receipt changed for ${nodeId}`);
+    }
+    return existing;
+  }
+  ensureDirectory(plan, path.dirname(file));
+  const descriptor = fs.openSync(file, 'wx');
+  try {
+    fs.writeFileSync(descriptor, body);
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  syncDirectory(path.dirname(file));
+  return value;
+}
+
+function ownedIdentity(target, expected) {
+  if (!expected) return false;
+  try {
+    const observed = identity(target, { deep: false });
+    return observed.kind === expected.kind
+      && observed.dev === expected.dev
+      && observed.ino === expected.ino;
+  } catch (error) {
+    if (isPathAbsentError(error)) return false;
+    throw error;
+  }
+}
+
+function plannedParentIdentity(plan, nodeId, phase) {
+  if (!nodeId || nodeId === plan.resourceId) return plan.rootIdentity;
+  if (phase === 'target') {
+    const created = readReceipt(plan, 'creates', nodeId);
+    if (created) return created;
+    const projected = (plan.projectedBindings || [])
+      .find((binding) => binding.nodeId === nodeId);
+    if (projected) return projected.identity;
+  }
+  const rollback = (plan.rollbackBindings || plan.projectedBindings || [])
+    .find((binding) => binding.nodeId === nodeId);
+  if (rollback) return rollback.identity;
+  throw new Error(
+    `workspace tree ${phase} parent ${nodeId} has no physical binding`,
+  );
+}
+
+function requireOwnedDirectory(directory, expected, label) {
+  if (!expected || expected.kind !== 'folder' || !ownedIdentity(directory, expected)) {
+    throw parentRace(`workspace tree ${label} parent changed: ${directory}`);
+  }
+  syncDirectory(directory);
+}
+
+function sourceRace(message) {
+  return Object.assign(new Error(message), {
+    code: 'WORKSPACE_TREE_SOURCE_RACE',
+  });
+}
+
+function parentRace(message) {
+  return Object.assign(new Error(message), {
+    code: 'WORKSPACE_TREE_PARENT_RACE',
+  });
+}
+
+function operationRecoveryContext(plan, options = {}) {
+  const bindings = new Map(
+    (plan.rollbackBindings || []).map((binding) => [binding.nodeId, binding]),
+  );
+  const actions = new Map(
+    (plan.actions || []).map((action) => [action.nodeId, action]),
+  );
+  const operationIdentities = Array.from(actions.keys()).map((nodeId) => (
+    readReceipt(plan, 'create', nodeId)
+    || readReceipt(plan, 'move', nodeId)
+    || readReceipt(plan, 'remove', nodeId)
+  )).filter(Boolean);
+  let indexed = indexProjectedBindingLocations(plan, {
+    identities: operationIdentities,
+  });
+  let refreshed = false;
+  const indexedLocation = (expected) => {
+    const key = receiptIdentityKey(expected);
+    const candidates = indexed.get(key) || [];
+    const current = candidates.find((candidate) => ownedIdentity(candidate, expected));
+    if (current) return current;
+    if (!refreshed) {
+      indexed = indexProjectedBindingLocations(plan, {
+        identities: operationIdentities,
+      });
+      refreshed = true;
+      return (indexed.get(key) || [])
+        .find((candidate) => ownedIdentity(candidate, expected)) || null;
+    }
+    if (candidates.length && refreshed) {
+      throw sourceRace('workspace tree operation recovery index changed twice');
+    }
+    return null;
+  };
+  const nodeLocation = (nodeId) => {
+    if (!nodeId || nodeId === plan.resourceId) return plan.rootPath;
+    const action = actions.get(nodeId);
+    const binding = bindings.get(nodeId);
+    const expected = (
+      readReceipt(plan, 'create', nodeId)
+      || readReceipt(plan, 'move', nodeId)
+      || binding?.identity
+    );
+    if (!expected) return null;
+    const exact = [
+      action?.target,
+      action?.source,
+      action ? stagedPath(plan, 'moves', nodeId) : null,
+      action ? stagedPath(plan, 'creates', nodeId) : null,
+      binding?.from,
+    ].filter(Boolean).find((candidate) => ownedIdentity(candidate, expected));
+    return exact || indexedLocation(expected);
+  };
+  const parent = (action, phase) => {
+    const nodeId = action[`${phase}ParentNodeId`];
+    if (nodeId === plan.resourceId) {
+      return { path: plan.rootPath, identity: plan.rootIdentity };
+    }
+    if (nodeId) {
+      const location = nodeLocation(nodeId);
+      if (!location) return null;
+      if (options.allowRelocated !== true) {
+        const ownerAction = actions.get(nodeId);
+        const binding = bindings.get(nodeId);
+        const permitted = [
+          binding?.from,
+          (
+            ownerAction
+            && (
+              readReceipt(plan, 'move-installing', nodeId)
+              || readReceipt(plan, 'create-installing', nodeId)
+            )
+          ) ? ownerAction.target : null,
+          ownerAction ? stagedPath(plan, 'moves', nodeId) : null,
+          ownerAction ? stagedPath(plan, 'creates', nodeId) : null,
+        ].filter(Boolean);
+        if (!permitted.some((candidate) => ownedIdentity(candidate, identity(
+          location,
+          { deep: false },
+        )))) {
+          return null;
+        }
+      }
+      return {
+        path: location,
+        identity: identity(location, { deep: false }),
+      };
+    }
+    const spelled = path.dirname(action[phase]);
+    const expected = action[`${phase}ParentIdentity`];
+    if (!expected || !ownedIdentity(spelled, expected)) return null;
+    return { path: spelled, identity: expected };
+  };
+  return {
+    nodeLocation,
+    resolve(action, phase) {
+      const held = parent(action, phase);
+      if (!held) return null;
+      return {
+        path: path.join(held.path, path.basename(action[phase])),
+        parentIdentity: held.identity,
+      };
+    },
+  };
+}
+
+function retainPrivatePath(plan, staged, preferred, token, options = {}) {
+  const provenance = options.provenance || 'independent-occupant';
+  const existingOutputs = options.item && options.lane
+    ? (plan.retainedOutputs || []).filter((output) => (
+        output.removalNodeId === options.item.nodeId
+        && output.lane === options.lane
+        && output.provenance === provenance
+      ))
+    : [];
+  if (!exists(staged)) {
+    const retained = existingOutputs.filter((output) => (
+      ownedIdentity(output.path, output.identity)
+    ));
+    return retained.length === 1 ? retained[0].path : null;
+  }
+  const expected = identity(staged, { deep: false });
+  let target = preferred;
+  let targetParentIdentity = null;
+  if (target && exists(path.dirname(target))) {
+    const parent = identity(path.dirname(target), { deep: false });
+    if (parent.kind === 'folder') targetParentIdentity = parent;
+  }
+  if (!targetParentIdentity) {
+    target = path.join(
+      plan.rootPath,
+      `.amalgm-retained-${token}-${path.basename(preferred || staged)}`,
+    );
+    targetParentIdentity = plan.rootIdentity;
+  }
+  if (exists(target)) target = retainedConflictPath(target, token);
+  if (options.item && options.lane) {
+    const relativePath = provenance === 'carried-source'
+      ? ''
+      : `entry-${expected.kind}-${expected.dev}-${expected.ino}`;
+    const role = provenance === 'carried-source' ? 'carried' : 'occupant';
+    const outputId = retainedOutputId(
+      plan,
+      options.item,
+      options.lane,
+      relativePath,
+      role,
+    );
+    const existing = existingOutputs.find(
+      (output) => output.outputId === outputId,
+    );
+    if (existing) target = existing.path;
+    const retained = mergeRetained(
+      plan,
+      options.item,
+      staged,
+      target,
+      token,
+      {
+        ...(options.outputOptions || {}),
+        lane: options.lane,
+        provenance,
+        exclusive: true,
+        targetParentIdentity,
+      },
+      relativePath,
+    );
+    return retained.find((output) => output.outputId === outputId)?.path || target;
+  }
+  exclusiveRename(
+    plan,
+    staged,
+    target,
+    `retain-private-${token}`,
+    expected,
+    { targetParentIdentity },
+  );
+  return target;
+}
+
+function retainUnexpectedStage(
+  plan,
+  source,
+  staged,
+  nodeId,
+  sourceParentIdentity,
+) {
+  if (!exists(staged)) return null;
+  const unexpected = identity(staged, { deep: false });
+  const token = crypto.createHash('sha256')
+    .update(
+      `${plan.snapshotChecksum || plan.mutationId}\0source-race\0${nodeId}`,
+    )
+    .digest('hex')
+    .slice(0, 12);
+  const target = exists(source)
+    ? retainedConflictPath(source, token)
+    : source;
+  const result = exclusiveRename(
+    plan,
+    staged,
+    target,
+    `retain-raced-stage-${nodeId}`,
+    unexpected,
+    {
+      targetParentIdentity: sourceParentIdentity,
+      allowChanged: true,
+    },
+  );
+  if (result.status !== 'applied' && exists(staged)) {
+    throw new Error(`workspace tree raced stage could not be retained for ${nodeId}`);
+  }
+  return target;
+}
+
+function stageOwnedPath({
+  plan,
+  source,
+  staged,
+  nodeId,
+  receiptLane,
+  expected,
+  sourceParentIdentity,
+  operation,
+  renameTestHooks = {},
+}) {
+  let receipt = readReceipt(plan, receiptLane, nodeId);
+  if (!receipt) {
+    receipt = writeReceipt(plan, receiptLane, nodeId, {
+      kind: expected.kind,
+      dev: expected.dev,
+      ino: expected.ino,
+    });
+  }
+  if (ownedIdentity(staged, receipt)) return receipt;
+  if (exists(staged)) {
+    retainUnexpectedStage(
+      plan,
+      source,
+      staged,
+      nodeId,
+      sourceParentIdentity,
+    );
+    throw sourceRace(`workspace tree source raced staging for ${nodeId}`);
+  }
+  if (!ownedIdentity(source, receipt)) {
+    throw sourceRace(`workspace tree source changed before staging for ${nodeId}`);
+  }
+  ensureDirectory(plan, path.dirname(staged));
+  const result = exclusiveRename(
+    plan,
+    source,
+    staged,
+    operation,
+    receipt,
+    {
+      sourceParentIdentity,
+      allowChanged: true,
+      testHooks: renameTestHooks,
+    },
+  );
+  if (ownedIdentity(staged, receipt)) return receipt;
+  if (exists(staged)) {
+    retainUnexpectedStage(
+      plan,
+      source,
+      staged,
+      nodeId,
+      sourceParentIdentity,
+    );
+  }
+  throw sourceRace(
+    `workspace tree source could not be staged for ${nodeId}: `
+    + `${result.reason || 'source changed'}`,
+  );
+}
+
+function crossCreateAction(plan, action, context, testHooks = {}) {
+  const prepared = stagedPath(plan, 'creates', action.nodeId);
+  let receipt = readReceipt(plan, 'create', action.nodeId);
+  if (!receipt) {
+    if (!exists(prepared)) createOperationTargetAt(prepared, action);
+    receipt = writeReceipt(
+      plan,
+      'create',
+      action.nodeId,
+      identity(prepared, { deep: false }),
+    );
+  }
+  if (exists(prepared)) {
+    if (!ownedIdentity(prepared, receipt)) {
+      throw new Error(`workspace tree prepared create changed for ${plan.mutationId}`);
+    }
+    if (typeof testHooks.afterOperationCreatePrepared === 'function') {
+      testHooks.afterOperationCreatePrepared(action, prepared);
+    }
+    requireOwnedDirectory(
+      path.dirname(action.target),
+      action.targetParentIdentity,
+      'operation create',
+    );
+    writeReceipt(plan, 'create-installing', action.nodeId, receipt);
+    if (!installOwnedPath(
+      plan,
+      prepared,
+      action.target,
+      receipt,
+      `operation-create-install-${action.nodeId}`,
+      {
+        operationParent: true,
+        targetParentIdentity: action.targetParentIdentity,
+      },
+    )) {
+      throw new Error(`workspace tree create lost its receipt for ${plan.mutationId}`);
+    }
+    return;
+  }
+  const installing = readReceipt(
+    plan,
+    'create-installing',
+    action.nodeId,
+  );
+  if (installing && ownedIdentity(action.target, receipt)) return;
+  const installedLocation = installing
+    ? context.nodeLocation(action.nodeId)
+    : null;
+  if (
+    installedLocation
+    && !pathInside(installedLocation, stagingRoot(plan))
+    && ownedIdentity(installedLocation, receipt)
+  ) {
+    throw sourceRace(
+      `workspace tree installed create moved before recovery for ${plan.mutationId}`,
+    );
+  }
+  if (installing && !installedLocation) {
+    throw sourceRace(
+      `workspace tree installed create disappeared before recovery for ${plan.mutationId}`,
+    );
+  }
+  if (!installing || !ownedIdentity(action.target, receipt)) {
+    throw new Error(`workspace tree create has no crossing receipt for ${plan.mutationId}`);
+  }
+}
+
+function crossMoveAction(plan, action, testHooks = {}) {
+  const staged = stagedPath(plan, 'moves', action.nodeId);
+  const installedReceipt = readReceipt(plan, 'move-installed', action.nodeId);
+  if (installedReceipt && ownedIdentity(action.target, installedReceipt)) return;
+  const movingReceipt = readReceipt(plan, 'move', action.nodeId);
+  const installingReceipt = readReceipt(plan, 'move-installing', action.nodeId);
+  if (
+    movingReceipt
+    && installingReceipt
+    && !exists(staged)
+    && ownedIdentity(action.target, movingReceipt)
+  ) {
+    writeReceipt(plan, 'move-installed', action.nodeId, movingReceipt);
+    return;
+  }
+  const receipt = stageOwnedPath({
+    plan,
+    source: action.source,
+    staged,
+    nodeId: action.nodeId,
+    receiptLane: 'move',
+    expected: action.identity,
+    sourceParentIdentity: action.sourceParentIdentity,
+    operation: `operation-move-stage-${action.nodeId}`,
+    renameTestHooks: testHooks.operationStageRename || {},
+  });
+  if (exists(staged)) {
+    if (!ownedIdentity(staged, receipt)) {
+      throw new Error(`workspace tree staged move lost ownership for ${plan.mutationId}`);
+    }
+    requireOwnedDirectory(
+      path.dirname(action.target),
+      action.targetParentIdentity,
+      'operation move',
+    );
+    writeReceipt(plan, 'move-installing', action.nodeId, receipt);
+    if (!installOwnedPath(
+      plan,
+      staged,
+      action.target,
+      receipt,
+      `operation-move-install-${action.nodeId}`,
+      {
+        operationParent: true,
+        targetParentIdentity: action.targetParentIdentity,
+      },
+    )) {
+      throw new Error(`workspace tree move lost its receipt for ${plan.mutationId}`);
+    }
+    if (typeof testHooks.afterOperationMoveInstall === 'function') {
+      testHooks.afterOperationMoveInstall(action);
+    }
+    writeReceipt(plan, 'move-installed', action.nodeId, receipt);
+    return;
+  }
+  if (ownedIdentity(action.target, receipt)) {
+    throw sourceRace(
+      `workspace tree move target has no operation crossing receipt for ${plan.mutationId}`,
+    );
+  }
+  throw new Error(`workspace tree move has no crossing receipt for ${plan.mutationId}`);
+}
+
+function crossRemoveAction(plan, action, testHooks = {}) {
+  const staged = stagedPath(plan, 'removed', action.nodeId);
+  const receipt = stageOwnedPath({
+    plan,
+    source: action.source,
+    staged,
+    nodeId: action.nodeId,
+    receiptLane: 'remove',
+    expected: action.identity,
+    sourceParentIdentity: action.sourceParentIdentity,
+    operation: `operation-remove-stage-${action.nodeId}`,
+    renameTestHooks: testHooks.operationStageRename || {},
+  });
+  if (!ownedIdentity(staged, receipt)) {
+    throw new Error(`workspace tree removal has no crossing receipt for ${plan.mutationId}`);
+  }
+}
+
+function rollbackOperationCreate(
+  plan,
+  action,
+  context,
+  testHooks = {},
+  outputOptions = {},
+) {
+  const receipt = readReceipt(plan, 'create', action.nodeId);
+  if (!receipt) return;
+  const prepared = stagedPath(plan, 'creates', action.nodeId);
+  const cancelId = `cancel-operation-create-${action.nodeId}`;
+  const cancelled = stagedPath(plan, 'removed', cancelId);
+  if (exists(cancelled) && !ownedIdentity(cancelled, receipt)) {
+    retainPrivatePath(
+      plan,
+      cancelled,
+      action.target,
+      `cancel-create-unexpected-${action.nodeId}`,
+      {
+        item: { nodeId: `cancel-create-unexpected-${action.nodeId}` },
+        lane: 'cancel-create-unexpected',
+        outputOptions,
+      },
+    );
+  }
+  if (exists(prepared) && !ownedIdentity(prepared, receipt)) {
+    retainPrivatePath(
+      plan,
+      prepared,
+      action.target,
+      `cancel-create-prepared-${action.nodeId}`,
+      {
+        item: { nodeId: `cancel-create-prepared-${action.nodeId}` },
+        lane: 'cancel-create-prepared',
+        outputOptions,
+      },
+    );
+  }
+  if (ownedIdentity(prepared, receipt) && !exists(cancelled)) {
+    ensureDirectory(plan, path.dirname(cancelled));
+    writeReceipt(plan, 'create-cancelling', action.nodeId, receipt);
+    exclusiveRename(
+      plan,
+      prepared,
+      cancelled,
+      `cancel-operation-create-prepared-${action.nodeId}`,
+      receipt,
+    );
+  }
+  const resolved = context.resolve(action, 'target');
+  if (
+    !ownedIdentity(cancelled, receipt)
+    && readReceipt(plan, 'create-installing', action.nodeId)
+    && resolved
+    && ownedIdentity(resolved.path, receipt)
+  ) {
+    ensureDirectory(plan, path.dirname(cancelled));
+    writeReceipt(plan, 'create-cancelling', action.nodeId, receipt);
+    exclusiveRename(
+      plan,
+      resolved.path,
+      cancelled,
+      `cancel-operation-create-installed-${action.nodeId}`,
+      receipt,
+      { sourceParentIdentity: resolved.parentIdentity },
+    );
+  }
+  if (
+    ownedIdentity(cancelled, receipt)
+    && typeof testHooks.afterOperationCreateCancellationStage === 'function'
+  ) {
+    testHooks.afterOperationCreateCancellationStage(action, cancelled);
+  }
+  if (!ownedIdentity(cancelled, receipt)) return;
+  const retainedTarget = resolved?.path || action.target;
+  return retireRemoval(plan, {
+    nodeId: cancelId,
+    ownerNodeId: action.nodeId,
+    source: retainedTarget,
+    retainTarget: retainedTarget,
+    retirement: initialCreateRetirement(action, receipt),
+  }, {
+    ...outputOptions,
+    preparePlan(nextPlan, outputs) {
+      if (typeof outputOptions.preparePlan === 'function') {
+        outputOptions.preparePlan(nextPlan, outputs);
+      }
+      const carriedRoot = outputs.find((output) => (
+        output.provenance === 'carried-source'
+        && output.sourceRelativePath === ''
+      ));
+      if (carriedRoot) {
+        const bindings = Array.isArray(nextPlan.carriedCreates)
+          ? [...nextPlan.carriedCreates]
+          : [];
+        const replacement = {
+          nodeId: action.nodeId,
+          path: carriedRoot.path,
+          identity: carriedRoot.identity,
+        };
+        const index = bindings.findIndex(
+          (binding) => binding.nodeId === action.nodeId,
+        );
+        if (index === -1) bindings.push(replacement);
+        else bindings[index] = replacement;
+        bindings.sort((left, right) => left.nodeId.localeCompare(right.nodeId));
+        nextPlan.carriedCreates = bindings;
+        if (Array.isArray(nextPlan.carriedCreateDeletions)) {
+          nextPlan.carriedCreateDeletions = (
+            nextPlan.carriedCreateDeletions
+              .filter((binding) => binding.nodeId !== action.nodeId)
+          );
+        }
+        return;
+      }
+      if (!outputs.some((output) => (
+        output.provenance === 'independent-occupant'
+        && path.resolve(output.path) === path.resolve(retainedTarget)
+      ))) return;
+      const deletions = Array.isArray(nextPlan.carriedCreateDeletions)
+        ? [...nextPlan.carriedCreateDeletions]
+        : [];
+      if (!deletions.some((binding) => binding.nodeId === action.nodeId)) {
+        deletions.push({
+          nodeId: action.nodeId,
+          identity: receipt,
+        });
+        deletions.sort((left, right) => left.nodeId.localeCompare(right.nodeId));
+        nextPlan.carriedCreateDeletions = deletions;
+      }
+    },
+  });
+}
+
+function cancelPreparedOperation(
+  held,
+  database = openLocalDb(),
+  testHooks = {},
+) {
+  let current = getOperation(held.resourceId, held.mutationId, database);
+  if (!current) return true;
+  if (current.state !== 'prepared') return false;
+  let plan = current.plan;
+  const outputOptions = {
+    durable: true,
+    persistPlan(nextPlan) {
+      current = replacePreparedOperation(current, nextPlan, database);
+      plan = current.plan;
+    },
+    afterOutputReceipt: testHooks.afterOperationCancellationOutputReceipt,
+    afterOutputMove: testHooks.afterOperationCancellationOutputMove,
+  };
+  let context = operationRecoveryContext(plan, { allowRelocated: true });
+  const targetActions = plan.actions
+    .filter((action) => action.target)
+    .sort((left, right) => (
+      right.target.split(path.sep).length - left.target.split(path.sep).length
+    ));
+  const carriedCreates = Array.isArray(plan.carriedCreates)
+    ? [...plan.carriedCreates]
+    : [];
+  const carriedCreateDeletions = Array.isArray(plan.carriedCreateDeletions)
+    ? [...plan.carriedCreateDeletions]
+    : [];
+  const carriedCreateIds = new Set(
+    [...carriedCreates, ...carriedCreateDeletions]
+      .map((binding) => binding.nodeId),
+  );
+  for (const action of targetActions) {
+    if (action.type !== 'create' || carriedCreateIds.has(action.nodeId)) continue;
+    const receipt = readReceipt(plan, 'create', action.nodeId);
+    if (!receipt || !readReceipt(plan, 'create-installing', action.nodeId)) continue;
+    const location = context.nodeLocation(action.nodeId);
+    if (!location && !exists(stagedPath(plan, 'creates', action.nodeId))) {
+      const resolvedTarget = context.resolve(action, 'target')?.path
+        || action.target;
+      const replacementIdentity = exists(resolvedTarget)
+        ? identity(resolvedTarget, { deep: false })
+        : null;
+      if (
+        action.kind === 'file'
+        && replacementIdentity?.kind === 'file'
+      ) {
+        // A regular file keeps its document UUID across atomic same-path
+        // replacement. The new inode is later content, not a new tree node.
+        carriedCreates.push({
+          nodeId: action.nodeId,
+          path: resolvedTarget,
+          identity: replacementIdentity,
+          refreshAtSamePath: true,
+        });
+      } else {
+        // A missing original receipt proves the installed value was removed.
+        // Any different folder, symlink, or kind at its name is independent
+        // and will receive a fresh UUID after this one becomes local trash.
+        carriedCreateDeletions.push({
+          nodeId: action.nodeId,
+          identity: receipt,
+        });
+      }
+      carriedCreateIds.add(action.nodeId);
+      continue;
+    }
+    if (
+      !location
+      || pathInside(location, stagingRoot(plan))
+      || !ownedIdentity(location, receipt)
+    ) {
+      continue;
+    }
+    carriedCreates.push({
+      nodeId: action.nodeId,
+      path: location,
+      identity: receipt,
+    });
+    carriedCreateIds.add(action.nodeId);
+  }
+  if (carriedCreates.length || carriedCreateDeletions.length) {
+    // Once a plan-created inode becomes visible, its receipt is UUID
+    // provenance. Preserve a surviving binding or its physical disappearance
+    // in the control row before cleaning private staging so a parent/child
+    // race can replan through the same UUID instead of birthing a relocation
+    // or resurrecting a local delete.
+    plan.carriedCreates = carriedCreates;
+    plan.carriedCreateDeletions = carriedCreateDeletions;
+    replacePreparedOperation(current, plan, database);
+    if (typeof testHooks.afterOperationCarriedCreateCapture === 'function') {
+      testHooks.afterOperationCarriedCreateCapture(carriedCreates);
+    }
+    if (
+      carriedCreateDeletions.length
+      && typeof testHooks.afterOperationCarriedCreateDeletionCapture === 'function'
+    ) {
+      testHooks.afterOperationCarriedCreateDeletionCapture(
+        carriedCreateDeletions,
+      );
+    }
+  }
+  // First pull every installed operation-owned value back into private
+  // staging. The durable *-installing receipt is the only authority for
+  // interpreting an exact target inode as output of this plan.
+  for (const action of targetActions) {
+    if (action.type !== 'move') continue;
+    const receipt = readReceipt(plan, 'move', action.nodeId);
+    const installing = readReceipt(plan, 'move-installing', action.nodeId);
+    const staged = stagedPath(plan, 'moves', action.nodeId);
+    const resolved = context.resolve(action, 'target');
+    if (
+      receipt
+      && installing
+      && resolved
+      && !ownedIdentity(staged, receipt)
+      && ownedIdentity(resolved.path, receipt)
+    ) {
+      ensureDirectory(plan, path.dirname(staged));
+      exclusiveRename(
+        plan,
+        resolved.path,
+        staged,
+        `cancel-operation-extract-${action.nodeId}`,
+        receipt,
+        { sourceParentIdentity: resolved.parentIdentity },
+      );
+    }
+  }
+  context = operationRecoveryContext(plan, { allowRelocated: true });
+  const sourceActions = plan.actions
+    .filter((action) => action.type === 'move' || action.type === 'remove')
+    .sort((left, right) => (
+      left.source.split(path.sep).length - right.source.split(path.sep).length
+    ));
+  for (const action of sourceActions) {
+    const lane = action.type === 'move' ? 'move' : 'remove';
+    const stagedLane = action.type === 'move' ? 'moves' : 'removed';
+    const receipt = readReceipt(plan, lane, action.nodeId);
+    if (!receipt) continue;
+    const staged = stagedPath(plan, stagedLane, action.nodeId);
+    if (exists(staged) && !ownedIdentity(staged, receipt)) {
+      retainPrivatePath(
+        plan,
+        staged,
+        action.source,
+        `cancel-unexpected-${action.nodeId}`,
+        {
+          item: { nodeId: `cancel-unexpected-${action.nodeId}` },
+          lane: `cancel-unexpected-${lane}`,
+          outputOptions,
+        },
+      );
+      continue;
+    }
+    if (!ownedIdentity(staged, receipt)) continue;
+    const resolved = context.resolve(action, 'source');
+    if (!resolved) {
+      retainPrivatePath(
+        plan,
+        staged,
+        action.source,
+        `cancel-missing-parent-${action.nodeId}`,
+        {
+          item: { nodeId: action.nodeId },
+          lane: `cancel-missing-parent-${lane}`,
+          provenance: 'carried-source',
+          outputOptions,
+        },
+      );
+      continue;
+    }
+    installOwnedPath(
+      plan,
+      staged,
+      resolved.path,
+      receipt,
+      `cancel-operation-${action.nodeId}`,
+      {
+        targetParentIdentity: resolved.parentIdentity,
+        retainedCollision: {
+          item: { nodeId: `cancel-source-${action.nodeId}` },
+          lane: `cancel-source-${lane}`,
+          outputOptions,
+        },
+      },
+    );
+  }
+  for (const action of targetActions) {
+    if (action.type !== 'create') continue;
+    const cancellationStillPrivate = (
+      exists(stagedPath(plan, 'creates', action.nodeId))
+      || exists(stagedPath(
+        plan,
+        'removed',
+        `cancel-operation-create-${action.nodeId}`,
+      ))
+    );
+    if (carriedCreateIds.has(action.nodeId) && !cancellationStillPrivate) {
+      continue;
+    }
+    rollbackOperationCreate(
+      plan,
+      action,
+      context,
+      testHooks,
+      outputOptions,
+    );
+  }
+  cleanupStagingRoot(plan);
+  if (
+    carriedCreates.length
+    || carriedCreateDeletions.length
+    || (Array.isArray(plan.retainedOutputs) && plan.retainedOutputs.length)
+  ) return true;
+  const result = database.prepare(`
+    DELETE FROM workspace_tree_operation_materializations
+    WHERE resource_id = ? AND mutation_id = ? AND materialization_state = 'prepared'
+  `).run(current.resourceId, current.mutationId);
+  return result.changes === 1;
+}
+
+function resolvedOperationAction(plan, action, phase, context) {
+  if (!action[phase]) return action;
+  const resolved = context.resolve(action, phase);
+  if (!resolved) {
+    throw parentRace(
+      `workspace tree operation ${phase} parent changed for ${action.nodeId}`,
+    );
+  }
+  return {
+    ...action,
+    [phase]: resolved.path,
+    [`${phase}ParentIdentity`]: resolved.parentIdentity,
+  };
+}
+
+function stageOperationAction(plan, action, context, testHooks = {}) {
+  const resolved = resolvedOperationAction(plan, action, 'source', context);
+  const lane = action.type === 'move' ? 'move' : 'remove';
+  const stagedLane = action.type === 'move' ? 'moves' : 'removed';
+  stageOwnedPath({
+    plan,
+    source: resolved.source,
+    staged: stagedPath(plan, stagedLane, action.nodeId),
+    nodeId: action.nodeId,
+    receiptLane: lane,
+    expected: action.identity,
+    sourceParentIdentity: resolved.sourceParentIdentity,
+    operation: `operation-${lane}-stage-${action.nodeId}`,
+    renameTestHooks: testHooks.operationStageRename || {},
+  });
+}
+
+function crossOperation(held, database = openLocalDb(), testHooks = {}) {
+  if (!held) throw new Error('workspace tree operation plan is missing');
+  const plan = held.plan;
+  if (held.state === 'committed') return held;
+  if (held.state === 'crossed') {
+    const context = operationRecoveryContext(plan);
+    for (const action of plan.actions) {
+      const resolved = action.target
+        ? resolvedOperationAction(plan, action, 'target', context)
+        : action;
+      if (
+        action.type === 'create'
+        && !ownedIdentity(
+          resolved.target,
+          readReceipt(plan, 'create', action.nodeId),
+        )
+      ) {
+        throw new Error(`workspace tree create receipt changed for ${plan.mutationId}`);
+      }
+      if (
+        action.type === 'move'
+        && !ownedIdentity(
+          resolved.target,
+          readReceipt(plan, 'move-installed', action.nodeId),
+        )
+      ) {
+        throw new Error(`workspace tree move receipt changed for ${plan.mutationId}`);
+      }
+      if (action.type === 'remove') {
+        const staged = stagedPath(plan, 'removed', action.nodeId);
+        if (!ownedIdentity(staged, readReceipt(plan, 'remove', action.nodeId))) {
+          throw new Error(`workspace tree removal receipt changed for ${plan.mutationId}`);
+        }
+      }
+    }
+    return held;
+  }
+  requireRoot(plan, database);
+  if (
+    (Array.isArray(plan.carriedCreates) && plan.carriedCreates.length)
+    || (
+      Array.isArray(plan.carriedCreateDeletions)
+      && plan.carriedCreateDeletions.length
+    )
+    || (
+      Array.isArray(plan.retainedOutputs)
+      && plan.retainedOutputs.length
+    )
+  ) {
+    if (!cancelPreparedOperation(held, database, testHooks)) {
+      throw new Error(
+        `workspace tree carried create cancellation did not finish for ${plan.mutationId}`,
+      );
+    }
+    const error = sourceRace(
+      `workspace tree operation resumes from its carried create bindings for ${plan.mutationId}`,
+    );
+    error.operationPlan = (
+      getOperation(plan.resourceId, plan.mutationId, database)?.plan
+      || plan
+    );
+    throw error;
+  }
+  const cancellationStarted = plan.actions.some((action) => (
+    action.type === 'create'
+    && readReceipt(plan, 'create-cancelling', action.nodeId)
+  ));
+  if (cancellationStarted) {
+    if (!cancelPreparedOperation(held, database, testHooks)) {
+      throw new Error(
+        `workspace tree operation cancellation did not finish for ${plan.mutationId}`,
+      );
+    }
+    const error = sourceRace(
+      `workspace tree operation resumes from its durable cancellation for ${plan.mutationId}`,
+    );
+    error.operationPlan = plan;
+    throw error;
+  }
+  try {
+    let context = operationRecoveryContext(plan);
+    const extraction = plan.actions
+      .filter((action) => action.type === 'move' || action.type === 'remove')
+      .sort((left, right) => (
+        right.source.split(path.sep).length - left.source.split(path.sep).length
+      ));
+    for (const action of extraction) {
+      stageOperationAction(plan, action, context, testHooks);
+    }
+    if (typeof testHooks.afterOperationStaging === 'function') {
+      testHooks.afterOperationStaging(plan);
+    }
+    context = operationRecoveryContext(plan);
+    const installation = plan.actions
+      .filter((action) => action.type === 'create' || action.type === 'move')
+      .sort((left, right) => (
+        left.target.split(path.sep).length - right.target.split(path.sep).length
+      ));
+    for (const action of installation) {
+      const resolved = resolvedOperationAction(
+        plan,
+        action,
+        'target',
+        context,
+      );
+      if (action.type === 'create') {
+        crossCreateAction(plan, resolved, context, testHooks);
+      } else {
+        crossMoveAction(plan, resolved, testHooks);
+      }
+    }
+  } catch (error) {
+    if (
+      error?.code === 'WORKSPACE_TREE_SOURCE_RACE'
+      || error?.code === 'WORKSPACE_TREE_PARENT_RACE'
+    ) {
+      cancelPreparedOperation(held, database, testHooks);
+      error.operationPlan = (
+        getOperation(plan.resourceId, plan.mutationId, database)?.plan
+        || plan
+      );
+    }
+    throw error;
+  }
+  if (testHooks.crashAfterOperationPhysical === true) {
+    throw new Error('simulated workspace tree crash after official operation');
+  }
+  database.prepare(`
+    UPDATE workspace_tree_operation_materializations
+    SET materialization_state = 'crossed',
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ? AND mutation_id = ? AND materialization_state = 'prepared'
+  `).run(held.resourceId, held.mutationId);
+  return getOperation(held.resourceId, held.mutationId, database);
+}
+
+function markOperationCommitted(held, database = openLocalDb()) {
+  database.prepare(`
+    UPDATE workspace_tree_operation_materializations
+    SET materialization_state = 'committed',
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ? AND mutation_id = ? AND materialization_state = 'crossed'
+  `).run(held.resourceId, held.mutationId);
+  const current = getOperation(held.resourceId, held.mutationId, database);
+  if (!current || current.state !== 'committed') {
+    throw new Error(`workspace tree operation ${held.mutationId} did not commit`);
+  }
+  return current;
+}
+
+function retirementTransaction(plan, item, entry) {
+  const spelledRoot = stagingRoot(plan);
+  const root = fs.realpathSync(spelledRoot);
+  const rootStat = fs.statSync(root, { bigint: true });
+  const staged = stagedPath(plan, 'removed', item.nodeId);
+  const candidate = entry.relativePath
+    ? path.join(staged, ...entry.relativePath.split('/'))
+    : staged;
+  const relativePath = path.relative(spelledRoot, candidate).split(path.sep).join('/');
+  const id = crypto.createHash('sha256')
+    .update(
+      `${plan.contract}\0retire\0${plan.resourceId}\0`
+      + `${plan.snapshotVersion ?? plan.version}\0${plan.snapshotChecksum || plan.mutationId}`
+      + `\0${item.nodeId}\0${entry.relativePath}`,
+    )
+    .digest('hex');
+  return {
+    candidate,
+    scratch: path.join(path.dirname(candidate), `.amalgm-apply-${id}`),
+    transaction: {
+      root,
+      rootDev: rootStat.dev.toString(),
+      rootIno: rootStat.ino.toString(),
+      path: relativePath,
+      id,
+      operation: `workspace-tree-retire:${plan.resourceId}:${item.nodeId}:${entry.relativePath}`,
+      expected: entry.identity,
+      target: null,
+    },
+  };
+}
+
+function retireLeaf(plan, item, entry) {
+  const prepared = retirementTransaction(plan, item, entry);
+  let result;
+  if (exists(prepared.scratch)) {
+    result = nativeFileTransaction.run(prepared.transaction, 'recover');
+  } else if (!exists(prepared.candidate)) {
+    return false;
+  } else {
+    const stat = fs.lstatSync(prepared.candidate);
+    if (!stat.isFile() && !stat.isSymbolicLink()) return true;
+    result = nativeFileTransaction.run(prepared.transaction, 'apply');
+  }
+  if (result.status === 'applied') {
+    const released = nativeFileTransaction.run(prepared.transaction, 'release');
+    if (released.status !== 'released') {
+      throw new Error(
+        `workspace tree retirement receipt stayed ${released.status} for ${item.nodeId}`,
+      );
+    }
+    return false;
+  }
+  if (result.status === 'changed') return exists(prepared.candidate);
+  throw new Error(
+    `workspace tree retirement stayed ${result.status} for ${item.nodeId}: `
+    + `${result.reason || 'no reason'}`,
+  );
+}
+
+function removeEmptyDirectoryTree(target) {
+  if (!exists(target)) return true;
+  const stat = fs.lstatSync(target);
+  if (!stat.isDirectory()) return false;
+  for (const name of fs.readdirSync(target)) {
+    const child = path.join(target, name);
+    if (fs.lstatSync(child).isDirectory()) removeEmptyDirectoryTree(child);
+  }
+  if (fs.readdirSync(target).length !== 0) return false;
+  fs.rmdirSync(target);
+  syncDirectory(path.dirname(target));
+  return true;
+}
+
+function retainedConflictPath(target, token) {
+  const directory = path.dirname(target);
+  const extension = path.extname(target);
+  const stem = extension ? path.basename(target, extension) : path.basename(target);
+  let candidate = path.join(directory, `${stem}.amalgm-retained-${token}${extension}`);
+  let suffix = 2;
+  while (exists(candidate)) {
+    candidate = path.join(
+      directory,
+      `${stem}.amalgm-retained-${token}-${suffix}${extension}`,
+    );
+    suffix += 1;
+  }
+  return candidate;
+}
+
+function retainedRetry(message, reason) {
+  return Object.assign(new Error(message), {
+    code: 'WORKSPACE_TREE_RETRY_PENDING',
+    reason,
+    statusCode: 409,
+  });
+}
+
+function retainedOutputId(plan, item, lane, relativePath, role) {
+  return crypto.createHash('sha256')
+    .update(
+      `${plan.contract}\0retained-output\0${plan.resourceId}\0`
+      + `${plan.snapshotVersion ?? plan.version}\0`
+      + `${plan.snapshotChecksum || plan.mutationId}\0${item.nodeId}\0`
+      + `${lane}\0${relativePath}\0${role}`,
+    )
+    .digest('hex');
+}
+
+function sealRetainedOutputs(plan, outputs, options = {}) {
+  const current = Array.isArray(plan.retainedOutputs)
+    ? [...plan.retainedOutputs]
+    : [];
+  const byId = new Map(current.map((output) => [output.outputId, output]));
+  let changed = false;
+  const sealed = outputs.map((output) => {
+    const existing = byId.get(output.outputId);
+    if (existing) {
+      if (JSON.stringify(existing) !== JSON.stringify(output)) {
+        throw Object.assign(
+          retainedRetry(
+            `workspace tree retained output ${output.outputId} changed its ownership receipt`,
+            'retained-output-changed',
+          ),
+          { paths: [existing.path, output.path].filter(Boolean) },
+        );
+      }
+      return existing;
+    }
+    current.push(output);
+    byId.set(output.outputId, output);
+    changed = true;
+    return output;
+  });
+  if (!changed) return sealed;
+  current.sort((left, right) => left.outputId.localeCompare(right.outputId));
+  plan.retainedOutputs = current;
+  if (typeof options.preparePlan === 'function') {
+    options.preparePlan(plan, sealed);
+  }
+  if (options.durable === true && typeof options.persistPlan !== 'function') {
+    throw new Error('workspace tree retained output has no durable plan writer');
+  }
+  if (typeof options.persistPlan === 'function') options.persistPlan(plan);
+  if (typeof options.afterOutputReceipt === 'function') {
+    options.afterOutputReceipt(sealed, plan);
+  }
+  return sealed;
+}
+
+function retainedOutput(
+  plan,
+  item,
+  lane,
+  relativePath,
+  role,
+  outputPath,
+  physicalIdentity,
+  sourceRelativePath,
+  parentIdentity = null,
+  ownerNodeId = null,
+) {
+  return {
+    outputId: retainedOutputId(plan, item, lane, relativePath, role),
+    removalNodeId: item.nodeId,
+    lane,
+    relativePath,
+    path: outputPath,
+    identity: physicalIdentity,
+    provenance: role === 'carried' ? 'carried-source' : 'independent-occupant',
+    ownerNodeId: role === 'carried' ? ownerNodeId : null,
+    sourceRelativePath: role === 'carried' ? sourceRelativePath : null,
+    parentIdentity: parentIdentity || identity(path.dirname(outputPath), { deep: false }),
+  };
+}
+
+function retainedTreeOutputs(
+  plan,
+  item,
+  lane,
+  source,
+  target,
+  relativePath,
+  role,
+  sourceRelativePath,
+) {
+  const outputs = [];
+  const ownerBySourcePath = new Map(
+    (plan.rollbackBindings || [])
+      .filter((binding) => binding?.from != null && binding?.nodeId)
+      .map((binding) => [binding.from, binding.nodeId]),
+  );
+  const carriedOwner = (outputSourceRelativePath) => {
+    if (role !== 'carried') return null;
+    const sourcePath = item.from == null
+      ? null
+      : (
+          outputSourceRelativePath
+            ? `${item.from}/${outputSourceRelativePath}`
+            : item.from
+        );
+    if (sourcePath && ownerBySourcePath.has(sourcePath)) {
+      return ownerBySourcePath.get(sourcePath);
+    }
+    if (!outputSourceRelativePath && (item.ownerNodeId || item.nodeId)) {
+      return item.ownerNodeId || item.nodeId;
+    }
+    return null;
+  };
+  const visit = (
+    sourcePath,
+    targetPath,
+    outputRelativePath,
+    outputSourceRelativePath,
+  ) => {
+    const sourceIdentity = identity(sourcePath, { deep: false });
+    const outputParentIdentity = exists(path.dirname(targetPath))
+      ? identity(path.dirname(targetPath), { deep: false })
+      : identity(path.dirname(sourcePath), { deep: false });
+    outputs.push(retainedOutput(
+      plan,
+      item,
+      lane,
+      outputRelativePath,
+      role,
+      targetPath,
+      sourceIdentity,
+      role === 'carried' ? outputSourceRelativePath : null,
+      outputParentIdentity,
+      carriedOwner(outputSourceRelativePath),
+    ));
+    if (sourceIdentity.kind !== 'folder') return;
+    for (const name of fs.readdirSync(sourcePath).sort()) {
+      visit(
+        path.join(sourcePath, name),
+        path.join(targetPath, name),
+        outputRelativePath ? `${outputRelativePath}/${name}` : name,
+        outputSourceRelativePath ? `${outputSourceRelativePath}/${name}` : name,
+      );
+    }
+  };
+  visit(source, target, relativePath, sourceRelativePath);
+  return outputs;
+}
+
+function mergeRetained(
+  plan,
+  item,
+  source,
+  target,
+  token,
+  options = {},
+  relativePath = '',
+) {
+  if (!exists(source)) return [];
+  const sourceIdentity = identity(source, { deep: false });
+  const sourceRelativePath = options.sourceRelativePath == null
+    ? relativePath
+    : (
+        relativePath
+          ? `${options.sourceRelativePath}/${relativePath}`
+          : options.sourceRelativePath
+      );
+  if (!exists(target)) {
+    if (options.targetParentIdentity) {
+      requireOwnedDirectory(
+        path.dirname(target),
+        options.targetParentIdentity,
+        'retained output',
+      );
+    } else {
+      ensureOperationDirectory(path.dirname(target));
+    }
+    const role = options.provenance === 'independent-occupant'
+      ? 'occupant'
+      : 'carried';
+    const sealed = sealRetainedOutputs(
+      plan,
+      retainedTreeOutputs(
+        plan,
+        item,
+        options.lane,
+        source,
+        target,
+        relativePath,
+        role,
+        sourceRelativePath,
+      ),
+      options,
+    );
+    const carried = sealed.find((output) => output.relativePath === relativePath);
+    try {
+      exclusiveRename(
+        plan,
+        source,
+        carried.path,
+        `retain-install-${token}`,
+        sourceIdentity,
+        options.targetParentIdentity
+          ? { targetParentIdentity: options.targetParentIdentity }
+          : {},
+      );
+    } catch (error) {
+      if (options.exclusive === true && exists(target)) {
+        throw retainedRetry(
+          `workspace tree retained target became occupied: ${target}`,
+          'retained-target-occupied',
+        );
+      }
+      throw error;
+    }
+    if (typeof options.afterOutputMove === 'function') {
+      options.afterOutputMove([carried], plan);
+    }
+    return [carried];
+  }
+  if (options.exclusive === true) {
+    throw retainedRetry(
+      `workspace tree retained target is occupied: ${target}`,
+      'retained-target-occupied',
+    );
+  }
+  const sourceStat = fs.lstatSync(source);
+  const targetStat = fs.lstatSync(target);
+  if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+    const retained = sealRetainedOutputs(
+      plan,
+      retainedTreeOutputs(
+        plan,
+        item,
+        options.lane,
+        target,
+        target,
+        relativePath,
+        'occupant',
+        '',
+      ),
+      options,
+    );
+    for (const name of fs.readdirSync(source).sort()) {
+      retained.push(...mergeRetained(
+        plan,
+        item,
+        path.join(source, name),
+        path.join(target, name),
+        token,
+        options,
+        relativePath ? `${relativePath}/${name}` : name,
+      ));
+    }
+    removeEmptyDirectoryTree(source);
+    return retained;
+  }
+  const outputId = retainedOutputId(
+    plan,
+    item,
+    options.lane,
+    relativePath,
+    'carried',
+  );
+  const existing = (plan.retainedOutputs || []).find(
+    (output) => output.outputId === outputId,
+  );
+  const conflict = existing?.path || retainedConflictPath(target, token);
+  const sourceRole = options.provenance === 'independent-occupant'
+    ? 'occupant'
+    : 'carried';
+  const outputs = sealRetainedOutputs(plan, [
+    ...retainedTreeOutputs(
+      plan,
+      item,
+      options.lane,
+      target,
+      target,
+      relativePath,
+      'occupant',
+      '',
+    ),
+    ...retainedTreeOutputs(
+      plan,
+      item,
+      options.lane,
+      source,
+      conflict,
+      relativePath,
+      sourceRole,
+      sourceRelativePath,
+    ),
+  ], options);
+  const carriedRoot = outputs.find((output) => (
+    output.path === conflict
+    && output.provenance === (
+      sourceRole === 'carried' ? 'carried-source' : 'independent-occupant'
+    )
+  ));
+  exclusiveRename(
+    plan,
+    source,
+    carriedRoot.path,
+    `retain-conflict-${token}`,
+    sourceIdentity,
+  );
+  if (typeof options.afterOutputMove === 'function') {
+    options.afterOutputMove(outputs, plan);
+  }
+  return outputs;
+}
+
+function retireRemoval(plan, item, options = {}) {
+  const staged = stagedPath(plan, 'removed', item.nodeId);
+  const source = item.source || absolute(plan, item.from);
+  const target = item.retainTarget || source;
+  if (
+    item.retainTargetExclusive === true
+    && exists(target)
+    && (exists(staged) || (source !== target && exists(source)))
+  ) {
+    throw retainedRetry(
+      `workspace tree retained target is occupied: ${target}`,
+      'retained-target-occupied',
+    );
+  }
+  if (!item.retirement || !Array.isArray(item.retirement.entries)) {
+    throw new Error(`workspace tree removal ${item.nodeId} has no leaf retirement proof`);
+  }
+  for (const entry of [...item.retirement.entries].sort((left, right) => (
+    right.relativePath.split('/').length - left.relativePath.split('/').length
+  ))) {
+    retireLeaf(plan, item, entry);
+  }
+  removeEmptyDirectoryTree(staged);
+  const token = crypto.createHash('sha256')
+    .update(
+      `${plan.snapshotChecksum || plan.mutationId}\0${item.nodeId}`,
+    )
+    .digest('hex')
+    .slice(0, 12);
+  const retainedOutputs = [
+    ...mergeRetained(plan, item, staged, target, token, {
+      ...options,
+      exclusive: item.retainTargetExclusive === true,
+      targetParentIdentity: item.retainTargetParentIdentity || null,
+      lane: 'staged',
+      provenance: 'carried-source',
+    }),
+    ...(source === target ? [] : mergeRetained(plan, item, source, target, token, {
+      ...options,
+      exclusive: item.retainTargetExclusive === true,
+      targetParentIdentity: item.retainTargetParentIdentity || null,
+      lane: 'visible',
+      provenance: 'independent-occupant',
+    })),
+  ];
+  const existingOutputs = (plan.retainedOutputs || []).filter(
+    (output) => output.removalNodeId === item.nodeId,
+  );
+  if (
+    source === target
+    && exists(target)
+    && ![...retainedOutputs, ...existingOutputs].some(
+      (output) => output.path === target,
+    )
+  ) {
+    retainedOutputs.push(...sealRetainedOutputs(
+      plan,
+      retainedTreeOutputs(
+        plan,
+        item,
+        'visible',
+        target,
+        target,
+        '',
+        'occupant',
+      ),
+      options,
+    ));
+  }
+  const allOutputs = Array.from(new Map(
+    [...existingOutputs, ...retainedOutputs]
+      .map((output) => [output.outputId, output]),
+  ).values());
+  return {
+    nodeId: item.nodeId,
+    target,
+    retainedPaths: Array.from(new Set(allOutputs.map((output) => output.path))),
+    retainedOutputs: allOutputs,
+    retained: allOutputs.length > 0,
+  };
+}
+
+function cleanupStagingRoot(plan) {
+  const root = stagingRoot(plan);
+  if (!exists(root)) return;
+  for (const lane of ['creates', 'moves', 'move-successors', 'removed']) {
+    const target = path.join(root, lane);
+    if (!removeEmptyDirectoryTree(target)) {
+      throw new Error(`workspace tree staging lane still contains bytes: ${target}`);
+    }
+  }
+  // Receipts remain until every byte lane is durably empty. A crash during
+  // cleanup can therefore rerun classification; it can never strand staged
+  // bytes after deleting the evidence that owns them.
+  const receipts = path.join(root, 'receipts');
+  if (exists(receipts)) fs.rmSync(receipts, { recursive: true, force: true });
+  if (!removeEmptyDirectoryTree(root)) {
+    throw new Error(`workspace tree staging still contains unclassified bytes: ${root}`);
+  }
+  syncDirectory(path.dirname(plan.rootPath));
+}
+
+function initialCreateRetirement(action, receipt) {
+  const content = action.kind === 'symlink'
+    ? Buffer.from(action.symlinkTarget)
+    : Buffer.alloc(0);
+  return {
+    entries: [{
+      relativePath: '',
+      identity: {
+        kind: action.kind,
+        exec: false,
+        bytes: content.length,
+        sha256: crypto.createHash('sha256').update(content).digest('hex'),
+        ...((action.kind === 'file' || action.kind === 'symlink') ? {
+          dev: receipt.dev,
+          ino: receipt.ino,
+        } : {}),
+      },
+    }],
+    directories: [],
+  };
+}
+
+function rollbackCreatedNode(plan, action, testHooks = {}, outputOptions = {}) {
+  const receipt = readReceipt(plan, 'creates', action.nodeId);
+  if (!receipt) return;
+  const prepared = stagedPath(plan, 'creates', action.nodeId);
+  const target = absolute(plan, action.to);
+  const cancelId = `cancel-${action.nodeId}`;
+  const cancelled = stagedPath(plan, 'removed', cancelId);
+  if (exists(cancelled) && !ownedIdentity(cancelled, receipt)) {
+    retainPrivatePath(
+      plan,
+      cancelled,
+      target,
+      `rollback-create-unexpected-${action.nodeId}`,
+      {
+        item: { nodeId: `rollback-create-unexpected-${action.nodeId}` },
+        lane: 'rollback-create-unexpected',
+        outputOptions,
+      },
+    );
+  }
+  if (exists(prepared) && !ownedIdentity(prepared, receipt)) {
+    retainPrivatePath(
+      plan,
+      prepared,
+      target,
+      `rollback-create-prepared-${action.nodeId}`,
+      {
+        item: { nodeId: `rollback-create-prepared-${action.nodeId}` },
+        lane: 'rollback-create-prepared',
+        outputOptions,
+      },
+    );
+  }
+  if (ownedIdentity(prepared, receipt) && !ownedIdentity(cancelled, receipt)) {
+    ensureDirectory(plan, path.dirname(cancelled));
+    writeReceipt(plan, 'rollback-create', action.nodeId, receipt);
+    exclusiveRename(
+      plan,
+      prepared,
+      cancelled,
+      `rollback-create-prepared-${action.nodeId}`,
+      receipt,
+    );
+  }
+  if (
+    !ownedIdentity(cancelled, receipt)
+    && readReceipt(plan, 'create-installing', action.nodeId)
+    && ownedIdentity(target, receipt)
+  ) {
+    if (typeof testHooks.beforeRollbackCreatedFolderRetire === 'function') {
+      testHooks.beforeRollbackCreatedFolderRetire(target, action);
+    }
+    ensureDirectory(plan, path.dirname(cancelled));
+    writeReceipt(plan, 'rollback-create', action.nodeId, receipt);
+    exclusiveRename(
+      plan,
+      target,
+      cancelled,
+      `rollback-create-installed-${action.nodeId}`,
+      receipt,
+      {
+        sourceParentIdentity: plannedParentIdentity(
+          plan,
+          action.targetParentNodeId,
+          'target',
+        ),
+        allowChanged: true,
+        testHooks: testHooks.rollbackCreatedRename || {},
+      },
+    );
+  }
+  if (exists(cancelled) && !ownedIdentity(cancelled, receipt)) {
+    retainPrivatePath(
+      plan,
+      cancelled,
+      target,
+      `rollback-create-raced-${action.nodeId}`,
+      {
+        item: { nodeId: `rollback-create-raced-${action.nodeId}` },
+        lane: 'rollback-create-raced',
+        outputOptions,
+      },
+    );
+  }
+  if (!ownedIdentity(cancelled, receipt)) return;
+  retireRemoval(plan, {
+    nodeId: cancelId,
+    source: target,
+    retainTarget: target,
+    retirement: initialCreateRetirement(action, receipt),
+  }, outputOptions);
+}
+
+function moveAside(plan, target, token, options = {}) {
+  if (!options.item || !options.lane) {
+    if (!exists(target)) return null;
+    const conflict = retainedConflictPath(target, token);
+    exclusiveRename(plan, target, conflict, `move-aside-${token}`);
+    return conflict;
+  }
+  const existingOutputs = (plan.retainedOutputs || [])
+    .filter((output) => (
+      output.removalNodeId === options.item.nodeId
+      && output.lane === options.lane
+      && output.provenance === 'independent-occupant'
+    ))
+    .sort((left, right) => left.outputId.localeCompare(right.outputId));
+  if (!exists(target)) {
+    const retained = existingOutputs.filter((output) => (
+      ownedIdentity(output.path, output.identity)
+    ));
+    return retained.length === 1 ? retained[0].path : null;
+  }
+  const targetIdentity = identity(target, { deep: false });
+  const relativePath = (
+    `entry-${targetIdentity.kind}-${targetIdentity.dev}-${targetIdentity.ino}`
+  );
+  const outputId = retainedOutputId(
+    plan,
+    options.item,
+    options.lane,
+    relativePath,
+    'occupant',
+  );
+  const existing = existingOutputs.find((output) => output.outputId === outputId);
+  const conflict = existing?.path || retainedConflictPath(target, token);
+  const retained = mergeRetained(
+    plan,
+    options.item,
+    target,
+    conflict,
+    token,
+    {
+      ...(options.outputOptions || {}),
+      lane: options.lane,
+      provenance: 'independent-occupant',
+      exclusive: true,
+    },
+    relativePath,
+  );
+  return retained.find((output) => output.outputId === outputId)?.path || conflict;
+}
+
+function moveHeldAside(plan, held, basisTarget, token) {
+  if (!exists(held)) return null;
+  if (held === basisTarget) return moveAside(plan, held, token);
+  const conflict = retainedConflictPath(basisTarget, token);
+  requireExistingDirectory(plan, path.dirname(conflict), token);
+  exclusiveRename(plan, held, conflict, `move-held-aside-${token}`);
+  return conflict;
+}
+
+function duplicateRetirementId(plan, token) {
+  return crypto.createHash('sha256')
+    .update(
+      `${plan.contract}\0duplicate-entry\0${plan.resourceId}\0`
+      + `${plan.snapshotVersion ?? plan.version}\0`
+      + `${plan.snapshotChecksum || plan.mutationId}\0${token}`,
+    )
+    .digest('hex');
+}
+
+function duplicateScratchPath(plan, held, token) {
+  return path.join(
+    path.dirname(held),
+    `.amalgm-apply-${duplicateRetirementId(plan, token)}`,
+  );
+}
+
+function retireDuplicateEntry(plan, held, linkedTarget, receipt, token) {
+  const id = duplicateRetirementId(plan, token);
+  const scratch = duplicateScratchPath(plan, held, token);
+  const scratchSource = path.join(scratch, 'source');
+  const identitySource = ownedIdentity(held, receipt)
+    ? held
+    : ownedIdentity(linkedTarget, receipt)
+      ? linkedTarget
+      : ownedIdentity(scratchSource, receipt)
+        ? scratchSource
+        : null;
+  let expected = readReceipt(plan, 'duplicate', id);
+  if (!expected) {
+    if (!identitySource) return false;
+    expected = writeReceipt(
+      plan,
+      'duplicate',
+      id,
+      nativeByteIdentity(identitySource),
+    );
+  }
+  const root = fs.realpathSync(path.dirname(held));
+  const rootStat = fs.lstatSync(root, { bigint: true });
+  const transaction = {
+    root,
+    rootDev: rootStat.dev.toString(),
+    rootIno: rootStat.ino.toString(),
+    path: path.basename(held),
+    id,
+    operation: `workspace-tree-duplicate-entry:${plan.resourceId}:${token}`,
+    expected,
+    target: null,
+  };
+  if (!exists(held) && !exists(scratch)) return true;
+  const result = nativeFileTransaction.run(
+    transaction,
+    exists(scratch) ? 'recover' : 'apply',
+  );
+  if (result.status === 'changed') return !exists(held) && !exists(scratch);
+  if (result.status !== 'applied') {
+    throw new Error(
+      `workspace tree duplicate entry stayed ${result.status}: `
+      + `${result.reason || 'no reason'}`,
+    );
+  }
+  const released = nativeFileTransaction.run(transaction, 'release');
+  if (released.status !== 'released') {
+    throw new Error(
+      `workspace tree duplicate entry receipt stayed ${released.status}: `
+      + `${released.reason || 'no reason'}`,
+    );
+  }
+  return true;
+}
+
+function installOwnedPath(plan, held, target, receipt, token, options = {}) {
+  if (options.targetParentIdentity) {
+    requireOwnedDirectory(
+      path.dirname(target),
+      options.targetParentIdentity,
+      'install',
+    );
+  }
+  if (exists(duplicateScratchPath(plan, held, token))) {
+    if (!retireDuplicateEntry(plan, held, target, receipt, token)) {
+      throw new Error(`workspace tree duplicate recovery changed for ${token}`);
+    }
+    if (!ownedIdentity(target, receipt) && !ownedIdentity(held, receipt)) {
+      const error = sourceRace(
+        `workspace tree target changed after duplicate extraction for ${token}`,
+      );
+      if (exists(target)) {
+        error.duplicateSuccessor = {
+          path: target,
+          identity: identity(target, { deep: false }),
+        };
+      }
+      throw error;
+    }
+  }
+  if (ownedIdentity(target, receipt)) {
+    // File identity names an inode, not one directory entry. A local hardlink
+    // may have restored the source while the operation-owned staging name
+    // still references the same inode. Consume only that staging entry; the
+    // destination keeps the bytes and UUID, and cleanup cannot wedge.
+    if (
+      held !== target
+      && ownedIdentity(held, receipt)
+    ) {
+      const stat = fs.lstatSync(held);
+      if (stat.isDirectory()) {
+        throw new Error(`workspace tree receipt has duplicate directory entries: ${held}`);
+      }
+      if (!retireDuplicateEntry(plan, held, target, receipt, token)) {
+        throw new Error(`workspace tree duplicate entry changed for ${token}`);
+      }
+    }
+    return true;
+  }
+  if (!ownedIdentity(held, receipt)) return false;
+  if (exists(target)) {
+    moveAside(
+      plan,
+      target,
+      `${token}-collision`,
+      options.retainedCollision || {},
+    );
+  }
+  if (options.operationParent === true) {
+    requireOwnedDirectory(
+      path.dirname(target),
+      options.targetParentIdentity,
+      'operation install',
+    );
+  } else {
+    requireExistingDirectory(plan, path.dirname(target), token);
+  }
+  exclusiveRename(
+    plan,
+    held,
+    target,
+    `install-owned-${token}`,
+    receipt,
+    {
+      ...(options.sourceParentIdentity
+        ? { sourceParentIdentity: options.sourceParentIdentity }
+        : {}),
+      ...(options.targetParentIdentity
+        ? { targetParentIdentity: options.targetParentIdentity }
+        : {}),
+      ...(options.testHooks ? { testHooks: options.testHooks } : {}),
+    },
+  );
+  return true;
+}
+
+function receiptIdentityKey(value) {
+  return value ? `${value.kind}\0${value.dev}\0${value.ino}` : null;
+}
+
+function indexProjectedBindingLocations(plan, options = {}) {
+  const bindings = [
+    ...(plan.rollbackBindings || []),
+    ...(plan.projectedBindings || []),
+  ];
+  const wanted = new Set(
+    [
+      ...bindings.map((item) => item.identity),
+      ...(options.identities || []),
+    ]
+      .map(receiptIdentityKey)
+      .filter(Boolean),
+  );
+  const locations = new Map();
+  const visit = (directory, parentRelativePath) => {
+    let names;
+    try {
+      names = fs.readdirSync(directory).sort();
+    } catch (error) {
+      if (isPathAbsentError(error)) return;
+      throw error;
+    }
+    for (const name of names) {
+      const relativePath = parentRelativePath
+        ? `${parentRelativePath}/${name}`
+        : name;
+      if (!shouldEnroll(relativePath)) continue;
+      const candidate = path.join(directory, name);
+      if (typeof options.onVisit === 'function') {
+        options.onVisit(candidate, relativePath);
+      }
+      let stat;
+      try {
+        stat = fs.lstatSync(candidate, { bigint: true });
+      } catch (error) {
+        if (isPathAbsentError(error)) continue;
+        throw error;
+      }
+      const kind = stat.isSymbolicLink()
+        ? 'symlink'
+        : stat.isDirectory()
+          ? 'folder'
+          : stat.isFile()
+            ? 'file'
+            : 'other';
+      const key = `${kind}\0${stat.dev}\0${stat.ino}`;
+      if (wanted.has(key)) {
+        const held = locations.get(key) || [];
+        held.push(candidate);
+        locations.set(key, held);
+      }
+      if (
+        kind === 'folder'
+        && !exists(path.join(candidate, '.git'))
+      ) {
+        visit(candidate, relativePath);
+      }
+    }
+  };
+  visit(plan.rootPath, '');
+  return locations;
+}
+
+function locateOperationBindings(plan, bindings) {
+  const values = Array.isArray(bindings) ? bindings : [];
+  const indexed = indexProjectedBindingLocations(plan, {
+    identities: values.map((binding) => binding.identity).filter(Boolean),
+  });
+  return new Map(values.map((binding) => {
+    const candidates = Array.from(new Set([
+      binding.path,
+      ...(indexed.get(receiptIdentityKey(binding.identity)) || []),
+    ].filter(Boolean))).filter((candidate) => (
+      ownedIdentity(candidate, binding.identity)
+    ));
+    return [binding.nodeId, candidates];
+  }));
+}
+
+function moveRecoveryContext(plan, options = {}) {
+  const bindingsById = new Map(
+    [
+      ...(plan.rollbackBindings || []),
+      ...(plan.projectedBindings || []),
+    ].map((item) => [item.nodeId, item]),
+  );
+  const movesById = new Map(
+    (plan.moves || []).map((item) => [item.nodeId, item]),
+  );
+  let indexed = indexProjectedBindingLocations(plan, options);
+  let refreshed = false;
+  const indexedMatches = (expected) => {
+    const candidates = () => indexed.get(receiptIdentityKey(expected)) || [];
+    const find = () => candidates()
+      .filter((candidate) => ownedIdentity(candidate, expected));
+    let matches = find();
+    if (matches.length) return matches;
+    // The first unresolved identity seals one fresh, shared absence scan for
+    // the whole classification phase. Every later absence is answered from
+    // that same observation. If an entry named by the sealed scan moves
+    // again, abort this bounded attempt rather than treating stale cache as
+    // permission to adopt an unrelated endpoint.
+    if (!refreshed) {
+      indexed = indexProjectedBindingLocations(plan, options);
+      refreshed = true;
+      matches = find();
+    }
+    if (!matches.length && refreshed && candidates().length > 0) {
+      throw sourceRace('workspace tree recovery changed after its sealed scan');
+    }
+    return matches;
+  };
+  const location = (binding) => {
+    if (!binding) return null;
+    const move = movesById.get(binding.nodeId);
+    const expected = move
+      ? readReceipt(plan, 'moves', binding.nodeId) || binding.identity
+      : binding.identity;
+    const exactCandidates = move
+      ? [
+          stagedPath(plan, 'moves', move.nodeId),
+          absolute(plan, move.to),
+          absolute(plan, move.from),
+          absolute(plan, binding.to),
+          absolute(plan, binding.from),
+        ]
+      : [
+          absolute(plan, binding.to),
+          absolute(plan, binding.from),
+        ];
+    const exact = exactCandidates.find(
+      (candidate) => ownedIdentity(candidate, expected),
+    );
+    if (exact) return exact;
+    const matches = indexedMatches(expected);
+    // Multiple hardlink names may make the final UUID path ambiguous, but
+    // they still prove the original inode exists. Never turn ambiguity into
+    // permission to adopt an unrelated stale target as the successor.
+    return matches[0] || null;
+  };
+  return {
+    ownedLocation(item) {
+      return location(bindingsById.get(item.nodeId));
+    },
+    targetCarriedLocation(item) {
+      const carrier = bindingsById.get(item.targetCarrierNodeId);
+      const carrierLocation = location(carrier);
+      if (!carrierLocation || !item.targetCarrierSuffix) return null;
+      const candidate = path.join(
+        carrierLocation,
+        ...item.targetCarrierSuffix.split('/'),
+      );
+      const receipt = readReceipt(plan, 'moves', item.nodeId);
+      return ownedIdentity(candidate, receipt) ? candidate : null;
+    },
+    sourcePath(item) {
+      if (
+        !item.sourceParentNodeId
+        || item.sourceParentNodeId === plan.resourceId
+      ) {
+        return path.join(plan.rootPath, path.basename(item.from));
+      }
+      const directParent = bindingsById.get(item.sourceParentNodeId);
+      const directParentLocation = location(directParent);
+      if (directParentLocation) {
+        return path.join(directParentLocation, path.basename(item.from));
+      }
+      const carrier = bindingsById.get(item.sourceCarrierNodeId);
+      const carrierLocation = location(carrier);
+      if (!carrierLocation || !item.sourceCarrierSuffix) {
+        return absolute(plan, item.from);
+      }
+      return path.join(
+        carrierLocation,
+        ...item.sourceCarrierSuffix.split('/'),
+      );
+    },
+    sourceParentIdentity(item) {
+      if (
+        !item.sourceParentNodeId
+        || item.sourceParentNodeId === plan.resourceId
+      ) return plan.rootIdentity;
+      return bindingsById.get(item.sourceParentNodeId)?.identity || null;
+    },
+  };
+}
+
+function reclassifyUnexpectedMoveStage(plan, item, staged, receipt) {
+  if (!exists(staged) || ownedIdentity(staged, receipt)) return false;
+  const successorStaged = stagedPath(plan, 'move-successors', item.nodeId);
+  if (exists(successorStaged)) {
+    throw new Error(`workspace tree move has two unclassified successors for ${item.nodeId}`);
+  }
+  exclusiveRename(
+    plan,
+    staged,
+    successorStaged,
+    `rollback-raced-successor-${item.nodeId}`,
+  );
+  writeReceipt(
+    plan,
+    'move-successor',
+    item.nodeId,
+    identity(successorStaged, { deep: false }),
+  );
+  return true;
+}
+
+function extractRollbackMovedNode(plan, item, context) {
+  const receipt = readReceipt(plan, 'moves', item.nodeId);
+  if (!receipt) return false;
+  const staged = stagedPath(plan, 'moves', item.nodeId);
+  const target = absolute(plan, item.to);
+  const source = absolute(plan, item.from);
+  if (exists(staged)) {
+    if (ownedIdentity(staged, receipt)) return false;
+    reclassifyUnexpectedMoveStage(plan, item, staged, receipt);
+  }
+  const crossedLocation = ownedIdentity(target, receipt)
+    ? target
+    : context.targetCarriedLocation(item);
+  if (crossedLocation) {
+    ensureDirectory(plan, path.dirname(staged));
+    exclusiveRename(
+      plan,
+      crossedLocation,
+      staged,
+      `rollback-move-extract-${item.nodeId}`,
+      receipt,
+    );
+    if (ownedIdentity(staged, receipt)) return false;
+    reclassifyUnexpectedMoveStage(plan, item, staged, receipt);
+  }
+  // The official inode may already have returned to its old path. Anything
+  // now at the stale target is then an independent local node, not a
+  // successor of this UUID, and must remain for ordinary tree observation.
+  if (ownedIdentity(source, receipt)) return false;
+  // The original receipt-owned node may itself have been moved to a third
+  // local path. That is local overlay, and it proves any unrelated value at
+  // the stale target cannot be this UUID's successor.
+  if (context.ownedLocation(item)) return false;
+
+  // The receipt-owned node crossed and was then replaced at its new path.
+  // That third value is local work whose UUID ownership still needs
+  // classification. Move it to operation-owned staging before extracting any
+  // ancestor; restore/capture later only if its kind and receipt history prove
+  // it is the original UUID's successor.
+  const successorStaged = stagedPath(plan, 'move-successors', item.nodeId);
+  let successorReceipt = readReceipt(plan, 'move-successor', item.nodeId);
+  if (exists(successorStaged)) {
+    if (!successorReceipt) {
+      successorReceipt = writeReceipt(
+        plan,
+        'move-successor',
+        item.nodeId,
+        identity(successorStaged, { deep: false }),
+      );
+    }
+    if (!ownedIdentity(successorStaged, successorReceipt)) {
+      throw new Error(`workspace tree move successor changed for ${item.nodeId}`);
+    }
+    return true;
+  }
+  if (successorReceipt && ownedIdentity(source, successorReceipt)) return true;
+  if (successorReceipt) return false;
+  if (!exists(target)) return false;
+  ensureDirectory(plan, path.dirname(successorStaged));
+  exclusiveRename(
+    plan,
+    target,
+    successorStaged,
+    `rollback-successor-stage-${item.nodeId}`,
+  );
+  writeReceipt(
+    plan,
+    'move-successor',
+    item.nodeId,
+    identity(successorStaged, { deep: false }),
+  );
+  return true;
+}
+
+function sameMoveSuccessorKind(item, receipt, held) {
+  const expectedKind = item.kind || item.identity?.kind;
+  if (!receipt || receipt.kind !== expectedKind) return false;
+  if (expectedKind !== 'symlink') return true;
+  try {
+    return fs.readlinkSync(held) === item.symlinkTarget;
+  } catch {
+    return false;
+  }
+}
+
+function restoreRollbackMovedNode(plan, item, context) {
+  const receipt = readReceipt(plan, 'moves', item.nodeId);
+  const staged = stagedPath(plan, 'moves', item.nodeId);
+  const source = context.sourcePath(item);
+  const token = crypto.createHash('sha256')
+    .update(`${plan.snapshotChecksum}\0rollback-move\0${item.nodeId}`)
+    .digest('hex')
+    .slice(0, 12);
+  const sourceParentIdentity = context.sourceParentIdentity(item);
+  let officialAtSource = false;
+  if (
+    sourceParentIdentity
+    && ownedIdentity(path.dirname(source), sourceParentIdentity)
+  ) {
+    try {
+      officialAtSource = installOwnedPath(
+        plan,
+        staged,
+        source,
+        receipt,
+        `${token}-official`,
+        { targetParentIdentity: sourceParentIdentity },
+      );
+    } catch (error) {
+      if (!error?.duplicateSuccessor || error.duplicateSuccessor.path !== source) {
+        throw error;
+      }
+      writeReceipt(
+        plan,
+        'move-successor',
+        item.nodeId,
+        error.duplicateSuccessor.identity,
+      );
+      return true;
+    }
+  }
+
+  const successorReceipt = readReceipt(plan, 'move-successor', item.nodeId);
+  const successorStaged = stagedPath(plan, 'move-successors', item.nodeId);
+  const successorHeld = ownedIdentity(successorStaged, successorReceipt)
+    ? successorStaged
+    : ownedIdentity(source, successorReceipt)
+      ? source
+      : null;
+  if (!successorHeld) return false;
+
+  if (!officialAtSource && context.ownedLocation(item)) {
+    // The original receipt inode survived at another local path while a
+    // checked source raced into successor staging. Put that independent value
+    // back at its stale-target address (or retain it beside the old source if
+    // its parent disappeared); it cannot inherit the original UUID.
+    const independentTarget = absolute(plan, item.to);
+    if (exists(path.dirname(independentTarget))) {
+      installOwnedPath(
+        plan,
+        successorHeld,
+        independentTarget,
+        successorReceipt,
+        `${token}-independent-target`,
+      );
+    } else {
+      moveHeldAside(
+        plan,
+        successorHeld,
+        source,
+        `${token}-independent-target`,
+      );
+    }
+    return false;
+  }
+
+  if (
+    !officialAtSource
+    && sameMoveSuccessorKind(item, successorReceipt, successorHeld)
+  ) {
+    // The true same-kind successor wins the UUID path. An independently
+    // recreated old source is moved aside and will receive a fresh UUID from
+    // the observer; it must never steal the existing document channel.
+    return installOwnedPath(
+      plan,
+      successorHeld,
+      source,
+      successorReceipt,
+      `${token}-successor`,
+    );
+  }
+
+  // A kind-changing replacement cannot inherit the original UUID. Nor can a
+  // stale target after the receipt-owned node already returned to its source.
+  // Preserve either as independent local structure at a deterministic
+  // conflict path. The observer will trash the absent old UUID when needed
+  // and birth the independent node separately.
+  if (!officialAtSource && exists(source) && source !== successorHeld) {
+    moveAside(plan, source, `${token}-independent-source`);
+  }
+  moveHeldAside(
+    plan,
+    successorHeld,
+    source,
+    `${token}-independent-target`,
+  );
+  return false;
+}
+
+function rollbackRemovedNode(plan, item, outputOptions = {}) {
+  const receipt = readReceipt(plan, 'removed', item.nodeId);
+  const staged = stagedPath(plan, 'removed', item.nodeId);
+  if (!ownedIdentity(staged, receipt)) return;
+  mergeRetained(
+    plan,
+    item,
+    staged,
+    absolute(plan, item.from),
+    crypto.createHash('sha256')
+      .update(`${plan.snapshotChecksum}\0rollback-remove\0${item.nodeId}`)
+      .digest('hex')
+      .slice(0, 12),
+    {
+      ...outputOptions,
+      lane: 'rollback',
+      provenance: 'carried-source',
+    },
+  );
+}
+
+function structuralActions(plan, reverse = false) {
+  const actions = [
+    ...plan.creates
+      .filter((candidate) => candidate.kind === 'folder')
+      .map((item) => ({ type: 'create', item, target: item.to })),
+    ...plan.moves.map((item) => ({ type: 'move', item, target: item.to })),
+  ].sort((left, right) => (
+    left.target.split('/').length - right.target.split('/').length
+    || left.target.localeCompare(right.target)
+    || left.item.nodeId.localeCompare(right.item.nodeId)
+  ));
+  return reverse ? actions.reverse() : actions;
+}
+
+function sourceRestorations(plan) {
+  return [
+    ...plan.removals.map((item) => ({ type: 'remove', item, source: item.from })),
+    ...plan.moves.map((item) => ({ type: 'move', item, source: item.from })),
+  ].sort((left, right) => (
+    left.source.split('/').length - right.source.split('/').length
+    || left.source.localeCompare(right.source)
+    || left.item.nodeId.localeCompare(right.item.nodeId)
+  ));
+}
+
+/**
+ * A newer permission epoch may supersede a snapshot after the older plan has
+ * staged bytes but before it earned a database projection. Restore the exact
+ * prior floor from operation receipts, preserve any newer writer, then remove
+ * the obsolete plan. No stale authority is ever projected merely to make
+ * recovery convenient.
+ */
+function supersedeUncommitted(held, database = openLocalDb(), options = {}) {
+  let current = get(held.resourceId, held.snapshotVersion, database);
+  if (!current) return true;
+  if (current.state === 'committed') return false;
+  let plan = current.plan;
+  const outputOptions = {
+    durable: true,
+    persistPlan(nextPlan) {
+      current = updateUncommittedPlan(current, nextPlan, database);
+      plan = current.plan;
+    },
+    afterOutputReceipt: options.testHooks?.afterRetainedOutputReceipt,
+    afterOutputMove: options.testHooks?.afterRetainedOutputMove,
+  };
+  const moveContext = moveRecoveryContext(plan, {
+    onVisit: options.testHooks?.onRecoveryIndexVisit,
+  });
+  const creates = [...plan.creates].sort((left, right) => (
+    right.to.split('/').length - left.to.split('/').length
+  ));
+  const moveSuccessors = new Set();
+  // Leaves cross after every structural action, so they retire first. Folders
+  // and moves share the after-tree dependency graph. Reverse that one graph
+  // deepest-first so every created or moved descendant leaves before its
+  // parent, then rebuild the before tree parent-first from the same receipts.
+  // This remains valid when both a parent and descendant moved independently.
+  for (const action of creates.filter((candidate) => candidate.kind !== 'folder')) {
+    rollbackCreatedNode(plan, action, options.testHooks, outputOptions);
+  }
+  for (const action of structuralActions(plan, true)) {
+    if (action.type === 'create') {
+      rollbackCreatedNode(plan, action.item, options.testHooks, outputOptions);
+    }
+    else extractRollbackMovedNode(plan, action.item, moveContext);
+  }
+  if (options.testHooks?.crashAfterRollbackExtraction === true) {
+    throw new Error('simulated workspace tree crash after rollback extraction');
+  }
+  let restorationCount = 0;
+  for (const action of sourceRestorations(plan)) {
+    if (action.type === 'move') {
+      if (restoreRollbackMovedNode(plan, action.item, moveContext)) {
+        moveSuccessors.add(action.item.nodeId);
+      }
+    }
+    else rollbackRemovedNode(plan, action.item, outputOptions);
+    restorationCount += 1;
+    if (
+      restorationCount === Number(
+        options.testHooks?.crashAfterRollbackRestorationCount,
+      )
+    ) {
+      throw new Error('simulated workspace tree crash during rollback restoration');
+    }
+  }
+  if (options.testHooks?.crashAfterRollbackRestore === true) {
+    throw new Error('simulated workspace tree crash after rollback restore');
+  }
+  const capturedBindings = new Map();
+  for (const item of plan.moves) {
+    const receipt = readReceipt(plan, 'moves', item.nodeId);
+    const location = moveContext.ownedLocation(item);
+    if (receipt && location && ownedIdentity(location, receipt)) {
+      capturedBindings.set(item.nodeId, {
+        nodeId: item.nodeId,
+        identity: receipt,
+      });
+    }
+    if (!moveSuccessors.has(item.nodeId)) continue;
+    const successorReceipt = readReceipt(plan, 'move-successor', item.nodeId);
+    const source = moveContext.sourcePath(item);
+    if (
+      successorReceipt
+      && source
+      && ownedIdentity(source, successorReceipt)
+    ) {
+      capturedBindings.set(item.nodeId, {
+        nodeId: item.nodeId,
+        identity: successorReceipt,
+      });
+    }
+  }
+  if (capturedBindings.size) {
+    const values = Array.from(capturedBindings.values());
+    const now = new Date().toISOString();
+    database.transaction(() => {
+      for (const binding of values) {
+        database.prepare(`
+          UPDATE workspace_nodes
+          SET device_id = ?, inode = ?, missing_at = NULL, updated_at = ?
+          WHERE workspace_id = ? AND id = ?
+        `).run(
+          String(binding.identity.dev),
+          String(binding.identity.ino),
+          now,
+          plan.resourceId,
+          binding.nodeId,
+        );
+      }
+    })();
+    require('../state/docs').captureDocsByNodeIds(
+      new Set(values.map((binding) => binding.nodeId)),
+      { database },
+    );
+    if (typeof options.captureSuccessors === 'function') {
+      options.captureSuccessors(values, plan);
+    }
+  }
+  if (options.testHooks?.crashAfterRollbackSuccessorCapture === true) {
+    throw new Error('simulated workspace tree crash after rollback successor capture');
+  }
+  if (
+    Array.isArray(plan.retainedOutputs)
+    && plan.retainedOutputs.length
+    && typeof options.captureRetainedOutputs === 'function'
+  ) {
+    options.captureRetainedOutputs(plan.retainedOutputs, plan);
+  }
+  cleanupStagingRoot(plan);
+  const result = database.prepare(`
+    DELETE FROM workspace_tree_materializations
+    WHERE resource_id = ?
+      AND snapshot_version = ?
+      AND materialization_state != 'committed'
+  `).run(current.resourceId, current.snapshotVersion);
+  return result.changes === 1;
+}
+
+function retireWithIncrementalCapture(plan, items, options, retire) {
+  const retained = [];
+  for (const item of items) {
+    const result = retire(item);
+    if (!result.retained) continue;
+    retained.push(result);
+    if (typeof options.retain === 'function') {
+      options.retain([result], plan);
+    }
+    if (typeof options.afterRetain === 'function') {
+      options.afterRetain([result], plan);
+    }
+  }
+  return retained;
+}
+
+function finishOperation(held, database = openLocalDb(), options = {}) {
+  let current = getOperation(held.resourceId, held.mutationId, database);
+  if (!current) return;
+  if (current.state !== 'committed') {
+    throw new Error(`workspace tree operation ${held.mutationId} has not committed`);
+  }
+  const retained = retireWithIncrementalCapture(
+    current.plan,
+    current.plan.actions.filter((action) => action.type === 'remove'),
+    options,
+    (action) => retireRemoval(current.plan, action, {
+      durable: true,
+      persistPlan(plan) {
+        current = updateCommittedPlan(current, plan, database);
+      },
+      afterOutputReceipt: options.afterOutputReceipt,
+      afterOutputMove: options.afterOutputMove,
+    }),
+  );
+  cleanupStagingRoot(current.plan);
+  database.transaction(() => {
+    const deleted = database.prepare(`
+      DELETE FROM workspace_tree_operation_materializations
+      WHERE resource_id = ? AND mutation_id = ?
+        AND materialization_state = 'committed'
+    `).run(held.resourceId, held.mutationId);
+    if (deleted.changes !== 1) {
+      throw new Error(
+        `workspace tree operation ${held.mutationId} lost its control record`,
+      );
+    }
+    if (typeof options.finalizeControlState === 'function') {
+      options.finalizeControlState(current.plan);
+    }
+  })();
+  return { retained };
+}
+
+function stagedPath(plan, lane, nodeId) {
+  return path.join(stagingRoot(plan), lane, nodeId);
+}
+
+function absolute(plan, relative) {
+  return path.join(plan.rootPath, ...String(relative || '').split('/').filter(Boolean));
+}
+
+function pathInside(candidate, root) {
+  const held = path.resolve(candidate);
+  const boundary = path.resolve(root);
+  return held === boundary || held.startsWith(`${boundary}${path.sep}`);
+}
+
+function approvedRenameRoot(plan, candidate) {
+  const roots = [
+    plan.rootPath,
+    stagingRoot(plan),
+    ...(Array.isArray(plan.controlRoots) ? plan.controlRoots : []),
+  ].map((root) => path.resolve(root));
+  return roots
+    .filter((root) => pathInside(candidate, root))
+    .sort((left, right) => right.length - left.length)[0] || null;
+}
+
+function exclusiveRename(
+  plan,
+  source,
+  target,
+  operation,
+  expectedSource = null,
+  options = {},
+) {
+  const canonicalEntry = (candidate) => path.join(
+    fs.realpathSync(path.dirname(candidate)),
+    path.basename(candidate),
+  );
+  const sourceRoleRoot = approvedRenameRoot(plan, source);
+  const targetRoleRoot = approvedRenameRoot(plan, target);
+  if (!sourceRoleRoot || !targetRoleRoot) {
+    throw parentRace(
+      `workspace tree rename has an unapproved endpoint: ${source} -> ${target}`,
+    );
+  }
+  const sourceCanonical = canonicalEntry(source);
+  const targetCanonical = canonicalEntry(target);
+  const canonicalRoleRoot = (root) => (
+    exists(root)
+      ? fs.realpathSync(root)
+      : path.join(fs.realpathSync(path.dirname(root)), path.basename(root))
+  );
+  if (
+    !pathInside(sourceCanonical, canonicalRoleRoot(sourceRoleRoot))
+    || !pathInside(targetCanonical, canonicalRoleRoot(targetRoleRoot))
+  ) {
+    throw parentRace(
+      `workspace tree rename endpoint escaped its physical owner: ${source} -> ${target}`,
+    );
+  }
+  let boundary = path.dirname(sourceCanonical);
+  const targetParent = path.dirname(targetCanonical);
+  while (
+    targetParent !== boundary
+    && !targetParent.startsWith(`${boundary}${path.sep}`)
+  ) {
+    const parent = path.dirname(boundary);
+    if (parent === boundary) {
+      throw new Error(
+        `workspace tree rename has no safe shared boundary: ${source} -> ${target}`,
+      );
+    }
+    boundary = parent;
+  }
+  const boundaryStat = fs.lstatSync(boundary, { bigint: true });
+  if (!boundaryStat.isDirectory()) {
+    throw new Error(`workspace tree rename boundary is not a directory: ${boundary}`);
+  }
+  const relative = (candidate) => {
+    const value = path.relative(boundary, candidate);
+    if (!value || value.startsWith('..') || path.isAbsolute(value)) {
+      throw new Error(`workspace tree rename escapes its boundary: ${candidate}`);
+    }
+    return value.split(path.sep).join('/');
+  };
+  const sourceRelative = relative(sourceCanonical);
+  const targetRelative = relative(targetCanonical);
+  const expected = expectedSource || identity(sourceCanonical, { deep: false });
+  if (!expected?.kind || !expected?.dev || !expected?.ino) {
+    throw new Error(`workspace tree rename has no source identity: ${source}`);
+  }
+  const sourceParentIdentity = options.sourceParentIdentity
+    || identity(path.dirname(sourceCanonical), { deep: false });
+  const targetParentIdentity = options.targetParentIdentity
+    || identity(path.dirname(targetCanonical), { deep: false });
+  if (
+    sourceParentIdentity.kind !== 'folder'
+    || targetParentIdentity.kind !== 'folder'
+  ) {
+    throw new Error(`workspace tree rename has a non-folder parent: ${source} -> ${target}`);
+  }
+  const renameReceiptId = crypto.createHash('sha256')
+    .update(`${operation}\0${path.resolve(source)}\0${path.resolve(target)}`)
+    .digest('hex');
+  writeReceipt(plan, 'rename', renameReceiptId, {
+    source: path.resolve(source),
+    target: path.resolve(target),
+    sourceIdentity: expected,
+    sourceParentIdentity,
+    targetParentIdentity,
+  });
+  if (ownedIdentity(targetCanonical, expected)) {
+    return { status: 'applied', recovered: true };
+  }
+  if (!ownedIdentity(sourceCanonical, expected)) {
+    const result = {
+      status: 'changed',
+      reason: 'source changed before exclusive move',
+    };
+    if (options.allowChanged === true) return result;
+    throw new Error(
+      `workspace tree changed before exclusive rename ${operation}: ${result.reason}`,
+    );
+  }
+  const id = crypto.createHash('sha256')
+    .update(
+      `${plan.contract || CONTRACT}\0${plan.resourceId}\0`
+      + `${plan.snapshotVersion ?? plan.version}\0`
+      + `${plan.snapshotChecksum || plan.mutationId}\0`
+      + `${operation}\0${sourceRelative}\0${targetRelative}`,
+    )
+    .digest('hex');
+  const result = nativeFileTransaction.moveNoReplace({
+    root: boundary,
+    rootDev: boundaryStat.dev.toString(),
+    rootIno: boundaryStat.ino.toString(),
+    source: sourceRelative,
+    sourceIdentity: {
+      kind: expected.kind,
+      dev: expected.dev,
+      ino: expected.ino,
+    },
+    sourceParentIdentity,
+    targetParentIdentity,
+    path: targetRelative,
+    id,
+    operation,
+  }, options.testHooks || {});
+  if (result.status !== 'applied') {
+    if (options.allowChanged === true) return result;
+    if (String(result.reason || '').includes('parent changed')) {
+      throw parentRace(
+        `workspace tree changed before exclusive rename ${operation}: ${result.reason}`,
+      );
+    }
+    throw new Error(
+      `workspace tree changed before exclusive rename ${operation}: ${result.reason}`,
+    );
+  }
+  return result;
+}
+
+function syncDirectory(directory) {
+  const descriptor = fs.openSync(directory, fs.constants.O_RDONLY);
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function syncDirectoryChain(plan, directory) {
+  const boundary = path.dirname(plan.rootPath);
+  let current = directory;
+  for (;;) {
+    syncDirectory(current);
+    if (current === boundary) break;
+    const parent = path.dirname(current);
+    if (
+      parent === current
+      || (current !== plan.rootPath
+        && !current.startsWith(`${plan.rootPath}${path.sep}`)
+        && !current.startsWith(`${boundary}${path.sep}`))
+    ) {
+      throw new Error(`workspace tree directory escaped its root: ${directory}`);
+    }
+    current = parent;
+  }
+}
+
+function ensureDirectory(plan, directory) {
+  ensureDurableDirectory(directory);
+  syncDirectoryChain(plan, directory);
+}
+
+function requireExistingDirectory(plan, directory, nodeId) {
+  if (!exists(directory) || !fs.lstatSync(directory).isDirectory()) {
+    throw new Error(`workspace tree target parent is not installed for ${nodeId}`);
+  }
+  syncDirectoryChain(plan, directory);
+}
+
+function requireRoot(plan, database = openLocalDb()) {
+  let observed;
+  try {
+    observed = identity(plan.rootPath);
+  } catch (error) {
+    if (!isPathAbsentError(error)) throw error;
+    throw Object.assign(
+      retainedRetry(
+        `workspace tree root is missing: ${plan.rootPath}`,
+        'workspace-root-missing',
+      ),
+      { paths: [plan.rootPath] },
+    );
+  }
+  const bound = database.prepare(`
+    SELECT device_id, inode
+    FROM workspace_nodes
+    WHERE workspace_id = ? AND id = ?
+  `).get(plan.resourceId, plan.resourceId);
+  const bindingMayBeBornByThisPlan = (
+    plan.initial === true
+    && (!bound || (!bound.device_id && !bound.inode))
+  );
+  if (
+    observed.kind !== 'folder'
+    || observed.dev !== plan.rootIdentity.dev
+    || observed.ino !== plan.rootIdentity.ino
+    || (
+      !bindingMayBeBornByThisPlan
+      && (
+        !bound?.device_id
+        || !bound?.inode
+        || String(bound.device_id) !== String(plan.rootIdentity.dev)
+        || String(bound.inode) !== String(plan.rootIdentity.ino)
+      )
+    )
+  ) {
+    throw Object.assign(
+      retainedRetry(
+        `workspace tree root changed during materialization: ${plan.rootPath}`,
+        'workspace-root-replaced',
+      ),
+      { paths: [plan.rootPath] },
+    );
+  }
+}
+
+function stageOne(plan, item, lane, testHooks = {}) {
+  const source = absolute(plan, item.from);
+  const staged = stagedPath(plan, lane, item.nodeId);
+  const target = item.to == null ? null : absolute(plan, item.to);
+  const receipt = readReceipt(plan, lane, item.nodeId);
+  if (target && receipt && ownedIdentity(target, receipt)) return;
+  stageOwnedPath({
+    plan,
+    source,
+    staged,
+    nodeId: item.nodeId,
+    receiptLane: lane,
+    expected: item.identity,
+    sourceParentIdentity: plannedParentIdentity(
+      plan,
+      item.sourceParentNodeId,
+      'source',
+    ),
+    operation: `snapshot-stage-${lane}-${item.nodeId}`,
+    renameTestHooks: testHooks.snapshotStageRename || {},
+  });
+}
+
+function installMove(plan, item, testHooks = {}) {
+  const staged = stagedPath(plan, 'moves', item.nodeId);
+  const target = absolute(plan, item.to);
+  const receipt = readReceipt(plan, 'moves', item.nodeId);
+  if (!receipt) {
+    throw new Error(`workspace tree move has no operation receipt for ${item.nodeId}`);
+  }
+  if (!exists(staged)) {
+    if (
+      readReceipt(plan, 'move-installing', item.nodeId)
+      && ownedIdentity(target, receipt)
+    ) return;
+    throw new Error(`workspace tree staged move disappeared for ${item.nodeId}`);
+  }
+  if (!ownedIdentity(staged, receipt)) {
+    throw new Error(`workspace tree staged move changed for ${item.nodeId}`);
+  }
+  writeReceipt(plan, 'move-installing', item.nodeId, receipt);
+  if (!installOwnedPath(
+    plan,
+    staged,
+    target,
+    receipt,
+    `snapshot-move-install-${item.nodeId}`,
+    {
+      targetParentIdentity: plannedParentIdentity(
+        plan,
+        item.targetParentNodeId,
+        'target',
+      ),
+      testHooks: testHooks.snapshotInstallRename || {},
+    },
+  )) {
+    throw new Error(`workspace tree move lost its receipt for ${item.nodeId}`);
+  }
+}
+
+function createProjectedNode(plan, item) {
+  const target = absolute(plan, item.to);
+  const prepared = stagedPath(plan, 'creates', item.nodeId);
+  let receipt = readReceipt(plan, 'creates', item.nodeId);
+  if (!receipt) {
+    if (!exists(prepared)) {
+      createOperationTargetAt(prepared, {
+        nodeId: item.nodeId,
+        kind: item.kind,
+        symlinkTarget: item.symlinkTarget,
+      });
+    }
+    receipt = writeReceipt(
+      plan,
+      'creates',
+      item.nodeId,
+      identity(prepared, { deep: false }),
+    );
+  }
+  if (exists(prepared)) {
+    if (!ownedIdentity(prepared, receipt)) {
+      throw new Error(`workspace tree prepared create changed for ${item.nodeId}`);
+    }
+    writeReceipt(plan, 'create-installing', item.nodeId, receipt);
+    if (!installOwnedPath(
+      plan,
+      prepared,
+      target,
+      receipt,
+      `snapshot-create-install-${item.nodeId}`,
+      {
+        targetParentIdentity: plannedParentIdentity(
+          plan,
+          item.targetParentNodeId,
+          'target',
+        ),
+      },
+    )) {
+      throw new Error(`workspace tree create lost its receipt for ${item.nodeId}`);
+    }
+    return true;
+  }
+  if (
+    !readReceipt(plan, 'create-installing', item.nodeId)
+    || !ownedIdentity(target, receipt)
+  ) {
+    throw new Error(`workspace tree create has no crossing receipt for ${item.nodeId}`);
+  }
+  return false;
+}
+
+function verify(plan, database = openLocalDb()) {
+  requireRoot(plan, database);
+  const plannedTargets = new Set([
+    ...plan.moves.map((item) => item.to),
+    ...plan.creates.map((item) => item.to),
+  ]);
+  for (const item of plan.moves) {
+    if (!ownedIdentity(
+      absolute(plan, item.to),
+      readReceipt(plan, 'moves', item.nodeId),
+    )) {
+      throw new Error(`workspace tree move did not verify for ${item.nodeId}`);
+    }
+  }
+  for (const item of plan.removals) {
+    const source = absolute(plan, item.from);
+    if (exists(source) && !plannedTargets.has(item.from)) {
+      throw new Error(`workspace tree removal did not verify for ${item.nodeId}`);
+    }
+    if (!ownedIdentity(
+      stagedPath(plan, 'removed', item.nodeId),
+      readReceipt(plan, 'removed', item.nodeId),
+    )) {
+      throw new Error(`workspace tree removal receipt did not verify for ${item.nodeId}`);
+    }
+  }
+  for (const item of plan.creates) {
+    const target = absolute(plan, item.to);
+    if (!ownedIdentity(
+      target,
+      readReceipt(plan, 'creates', item.nodeId),
+    )) {
+      throw new Error(`workspace tree create did not verify for ${item.nodeId}`);
+    }
+    if (item.kind === 'symlink' && fs.readlinkSync(target) !== item.symlinkTarget) {
+      throw new Error(`workspace tree symlink did not verify for ${item.nodeId}`);
+    }
+  }
+  if (!Array.isArray(plan.projectedBindings)) {
+    throw new Error('workspace tree snapshot has no complete projected-node proof');
+  }
+  for (const item of plan.projectedBindings) {
+    const target = absolute(plan, item.to);
+    if (!ownedIdentity(target, item.identity)) {
+      throw new Error(`workspace tree projected node did not verify for ${item.nodeId}`);
+    }
+    if (item.kind === 'symlink' && fs.readlinkSync(target) !== item.symlinkTarget) {
+      throw new Error(`workspace tree projected symlink did not verify for ${item.nodeId}`);
+    }
+  }
+}
+
+function cross(held, database = openLocalDb(), testHooks = {}) {
+  if (!held) throw new Error('workspace tree materialization plan is missing');
+  let plan = held.plan;
+  if (held.state === 'committed') return held;
+  if (held.state === 'crossed') {
+    verify(plan, database);
+    return held;
+  }
+  requireRoot(plan, database);
+  const extraction = [
+    ...plan.moves.map((item) => ({ item, lane: 'moves' })),
+    ...plan.removals.map((item) => ({ item, lane: 'removed' })),
+  ].sort((left, right) => (
+    right.item.from.split('/').length - left.item.from.split('/').length
+  ));
+  // Prove the entire source set before the first rename. A changed file or a
+  // new descendant is local work, not permission to delete the new bytes
+  // under an old inode-only receipt.
+  try {
+    const resumingStagedPlan = exists(stagingRoot(plan));
+    for (const { item, lane } of extraction) {
+      const source = absolute(plan, item.from);
+      const staged = stagedPath(plan, lane, item.nodeId);
+      const target = item.to == null ? null : absolute(plan, item.to);
+      const expected = (
+        !resumingStagedPlan
+        && item.preflightIdentity
+      ) || item.identity;
+      if (
+        sameIdentity(source, expected)
+        || exists(staged)
+        || (target && sameIdentity(target, item.identity))
+      ) continue;
+      throw new Error(`workspace tree source content changed before snapshot for ${item.nodeId}`);
+    }
+  } catch (error) {
+    if (!exists(stagingRoot(plan))) {
+      database.prepare(`
+        DELETE FROM workspace_tree_materializations
+        WHERE resource_id = ? AND snapshot_version = ? AND materialization_state = 'prepared'
+      `).run(held.resourceId, held.snapshotVersion);
+    }
+    throw error;
+  }
+  try {
+    for (const { item, lane } of extraction) {
+      stageOne(plan, item, lane, testHooks);
+    }
+  } catch (error) {
+    if (error?.code === 'WORKSPACE_TREE_SOURCE_RACE') {
+      supersedeUncommitted(held, database);
+    }
+    throw error;
+  }
+  if (plan.removals.some((item) => item.preflightIdentity)) {
+    plan = {
+      ...plan,
+      removals: plan.removals.map((item) => ({
+        ...item,
+        identity: identity(stagedPath(plan, 'removed', item.nodeId)),
+      })),
+    };
+    database.prepare(`
+      UPDATE workspace_tree_materializations
+      SET plan_json = ?,
+          updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+      WHERE resource_id = ? AND snapshot_version = ? AND materialization_state = 'prepared'
+    `).run(JSON.stringify(plan), held.resourceId, held.snapshotVersion);
+    held = get(held.resourceId, held.snapshotVersion, database);
+    plan = held.plan;
+  }
+  if (testHooks.crashAfterStage === true) {
+    throw new Error('simulated workspace tree crash after staging');
+  }
+  try {
+    let created = 0;
+    const createOne = (item) => {
+      if (createProjectedNode(plan, item)) created += 1;
+      if (created > 0 && created === Number(testHooks.crashAfterCreates)) {
+        throw new Error('simulated workspace tree crash after create');
+      }
+    };
+    for (const action of structuralActions(plan)) {
+      if (action.type === 'create') createOne(action.item);
+      else installMove(plan, action.item, testHooks);
+    }
+    for (const item of plan.creates.filter((candidate) => candidate.kind !== 'folder')) {
+      createOne(item);
+    }
+    if (typeof testHooks.beforeTreePlanVerify === 'function') {
+      testHooks.beforeTreePlanVerify(plan);
+    }
+    verify(plan, database);
+  } catch (error) {
+    if (
+      error?.code === 'WORKSPACE_TREE_SOURCE_RACE'
+      || error?.code === 'WORKSPACE_TREE_PARENT_RACE'
+    ) {
+      supersedeUncommitted(held, database);
+    }
+    throw error;
+  }
+  database.prepare(`
+    UPDATE workspace_tree_materializations
+    SET materialization_state = 'crossed',
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ? AND snapshot_version = ?
+  `).run(held.resourceId, held.snapshotVersion);
+  return get(held.resourceId, held.snapshotVersion, database);
+}
+
+function markCommitted(held, database = openLocalDb()) {
+  const result = database.prepare(`
+    UPDATE workspace_tree_materializations
+    SET materialization_state = 'committed',
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE resource_id = ?
+      AND snapshot_version = ?
+      AND materialization_state = 'crossed'
+  `).run(held.resourceId, held.snapshotVersion);
+  if (result.changes !== 1) {
+    const current = get(held.resourceId, held.snapshotVersion, database);
+    if (!current || current.state !== 'committed') {
+      throw new Error(
+        `workspace tree snapshot ${held.resourceId}@${held.snapshotVersion} did not commit`,
+      );
+    }
+    return current;
+  }
+  return get(held.resourceId, held.snapshotVersion, database);
+}
+
+function finish(held, database = openLocalDb(), options = {}) {
+  let current = get(held.resourceId, held.snapshotVersion, database);
+  if (!current) return;
+  if (current.state !== 'committed') {
+    throw new Error(
+      `workspace tree snapshot ${held.resourceId}@${held.snapshotVersion} has not committed`,
+    );
+  }
+  const retained = retireWithIncrementalCapture(
+    current.plan,
+    current.plan.removals,
+    options,
+    (item) => retireRemoval(current.plan, item, {
+      durable: true,
+      persistPlan(plan) {
+        current = updateCommittedPlan(current, plan, database);
+      },
+      afterOutputReceipt: options.afterOutputReceipt,
+      afterOutputMove: options.afterOutputMove,
+    }),
+  );
+  cleanupStagingRoot(current.plan);
+  syncDirectory(current.plan.rootPath);
+  syncDirectory(path.dirname(current.plan.rootPath));
+  database.transaction(() => {
+    const result = database.prepare(`
+      DELETE FROM workspace_tree_materializations
+      WHERE resource_id = ? AND snapshot_version = ?
+        AND materialization_state = 'committed'
+    `).run(held.resourceId, held.snapshotVersion);
+    if (result.changes !== 1) {
+      throw new Error(
+        `workspace tree snapshot ${held.resourceId}@${held.snapshotVersion} lost its control record`,
+      );
+    }
+    if (typeof options.finalizeControlState === 'function') {
+      options.finalizeControlState(current.plan);
+    }
+  })();
+  return { retained };
+}
+
+module.exports = {
+  appendOperationSuccessor,
+  clearOperationSuccessors,
+  cross,
+  crossOperation,
+  cancelPreparedOperation,
+  finish,
+  finishOperation,
+  get,
+  getOperation,
+  identity,
+  insert,
+  insertOperation,
+  ensureDurableDirectory,
+  locateOperationBindings,
+  list,
+  listOperationSuccessors,
+  listOperations,
+  markCommitted,
+  markOperationCommitted,
+  replacePreparedOperation,
+  updateCommittedPlan,
+  updateUncommittedPlan,
+  removalPrecondition,
+  supersedeUncommitted,
+};