amalgm 0.1.239 → 0.1.241

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

@@ -3,17 +3,19 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const { AMALGM_DIR } = require('../config');
+const { isPathAbsentError } = require('./tree/path-state');
 const { openLocalDb } = require('../state/db');
-const { applyTreeOperation } = require('./tree/reducer');
+const { applyTreeOperation, descendantsInclude } = require('./tree/reducer');
 const { relativeWorkspacePath, shouldSync } = require('./tree/inclusion');
 const { normalizeTreeOperation } = require('./tree/operations');
 const { normalizeTreeSnapshot } = require('./tree/snapshot');
+const { validateLiveSymlinkTargets } = require('./tree/symlinks');
 const {
   hasAncestorInSet,
-  materializeOperation,
   persistNodes,
+  relativePathForNode,
   rowToNode,
+  trashPath,
   workspaceRow,
 } = require('./tree/local-state');
 
@@ -75,7 +77,7 @@ function safeSymlinkTarget(rootPath, linkPath, target) {
 }
 
 function activeNode(node) {
-  return Boolean(node && !node.trashedAt && !node.purgedAt);
+  return Boolean(node && !node.missingAt && !node.trashedAt && !node.purgedAt);
 }
 
 function normalizeSnapshotPermissions(input, snapshot) {
@@ -100,7 +102,15 @@ function normalizeSnapshotPermissions(input, snapshot) {
   });
 }
 
-function replaceTreeProjection(database, workspaceId, snapshot, paths, permissions, authorityEpoch) {
+function replaceTreeProjection(
+  database,
+  workspaceId,
+  rootPath,
+  snapshot,
+  paths,
+  permissions,
+  authorityEpoch,
+) {
   const ordered = Array.from(snapshot.nodes.values()).sort((left, right) => {
     const leftPath = paths.get(left.id);
     const rightPath = paths.get(right.id);
@@ -112,7 +122,11 @@ function replaceTreeProjection(database, workspaceId, snapshot, paths, permissio
       .filter((nodeId) => !snapshot.nodes.has(nodeId));
     if (removedIds.length) {
       const placeholders = removedIds.map(() => '?').join(',');
-      database.prepare(`DELETE FROM doc_states WHERE node_id IN (${placeholders})`).run(...removedIds);
+      if (database.prepare(`
+        SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'doc_states'
+      `).get()) {
+        database.prepare(`DELETE FROM doc_states WHERE node_id IN (${placeholders})`).run(...removedIds);
+      }
       database.prepare(`DELETE FROM shared_resource_replicas WHERE resource_id IN (${placeholders})`).run(...removedIds);
       database.prepare(`DELETE FROM shared_resource_attachments WHERE resource_id IN (${placeholders})`).run(...removedIds);
     }
@@ -121,14 +135,25 @@ function replaceTreeProjection(database, workspaceId, snapshot, paths, permissio
     const insert = database.prepare(`
       INSERT INTO workspace_nodes (
         id, workspace_id, parent_id, kind, name, relative_path, symlink_target,
-        trashed_at, purged_at, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        device_id, inode, trashed_at, trash_component_id, purged_at,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     for (const node of ordered) {
+      const relativePath = paths.get(node.id);
+      const physicalPath = relativePath
+        ? path.join(rootPath, ...relativePath.split('/'))
+        : rootPath;
+      let physical = null;
+      if (activeNode(node) && pathExists(physicalPath)) {
+        const stats = fs.lstatSync(physicalPath);
+        physical = { deviceId: String(stats.dev), inode: String(stats.ino) };
+      }
       insert.run(
         node.id, node.workspaceId, node.parentId, node.kind, node.name,
-        paths.get(node.id), node.symlinkTarget, node.trashedAt, node.purgedAt,
-        node.createdAt, node.updatedAt,
+        relativePath, node.symlinkTarget, physical?.deviceId || null,
+        physical?.inode || null, node.trashedAt, node.trashComponentId,
+        node.purgedAt, node.createdAt, node.updatedAt,
       );
     }
     const insertPermission = database.prepare(`
@@ -145,80 +170,889 @@ function replaceTreeProjection(database, workspaceId, snapshot, paths, permissio
   return ordered;
 }
 
-function createProjectedNode(rootPath, node, relativePath) {
-  const target = path.join(rootPath, ...relativePath.split('/'));
-  if (node.kind === 'folder') fs.mkdirSync(target, { recursive: true });
-  else if (node.kind === 'file') {
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    if (!fs.existsSync(target)) fs.writeFileSync(target, '');
-  } else if (!fs.existsSync(target) && safeSymlinkTarget(rootPath, target, node.symlinkTarget)) {
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.symlinkSync(node.symlinkTarget, target);
+function projectedAuthorityEpoch(workspaceId, database) {
+  return Number(database.prepare(`
+    SELECT authority_epoch FROM workspace_access_state WHERE workspace_id = ?
+  `).get(workspaceId)?.authority_epoch || 0);
+}
+
+function snapshotRecord(snapshot) {
+  return {
+    schemaVersion: 1,
+    workspaceId: snapshot.workspaceId,
+    version: snapshot.version,
+    nodes: Array.from(snapshot.nodes.values()),
+  };
+}
+
+function activeCopy(node) {
+  return {
+    ...node,
+    missingAt: null,
+    trashedAt: null,
+    purgedAt: null,
+  };
+}
+
+function pendingTreeMutations(resourceId, throughVersion, database) {
+  return require('../state/mutations')
+    .listLocalOverlayMutations(resourceId, { database, throughVersion })
+    .filter((mutation) => (
+      mutation.localResource === `${TREE_RESOURCE_PREFIX}${resourceId}`
+      && mutation.contract === 'workspace-tree@1'
+    ));
+}
+
+function pendingContentNodeIds(before, database) {
+  const nodeIds = new Set(before.keys());
+  const pending = new Set();
+  const rows = database.prepare(`
+    SELECT shared_resource_id, local_resource
+    FROM mutation_journal
+    WHERE mutation_origin = 'local'
+      AND (mutation_state != 'synced' OR official_projected_at IS NULL)
+    ORDER BY journal_id ASC
+  `).all();
+  for (const row of rows) {
+    if (row.shared_resource_id && nodeIds.has(row.shared_resource_id)) {
+      pending.add(row.shared_resource_id);
+    }
+    const localResource = String(row.local_resource || '');
+    if (localResource.startsWith('doc:')) {
+      const nodeId = localResource.slice('doc:'.length);
+      if (nodeIds.has(nodeId)) pending.add(nodeId);
+    }
   }
+  return pending;
 }
 
-function materializeTreeProjection(rootPath, before, afterSnapshot, beforePaths, afterPaths) {
-  const after = afterSnapshot.nodes;
+/**
+ * A snapshot moves only the official floor. Local tree operations remain an
+ * overlay. Other resource contracts can also own a tree node: a pending
+ * document mutation keeps its UUID and ancestor chain present even when the
+ * incoming tree prefix omits it.
+ */
+function snapshotWithLocalOverlay(official, before, resourceId, database) {
+  let nodes = new Map(official.nodes);
+  const importAncestors = (nodeId) => {
+    if (!nodeId || nodes.has(nodeId)) return;
+    const node = before.get(nodeId);
+    if (!node) throw invalid(`local tree intent lost ancestor ${nodeId}`, 409);
+    importAncestors(node.parentId);
+    nodes.set(node.id, activeCopy(node));
+  };
+  // Structural births own membership. Apply them before content ownership so
+  // one locally created document does not import its UUID and then collide
+  // with its own pending tree.create.
+  for (const mutation of pendingTreeMutations(resourceId, official.version, database)) {
+    const operation = normalizeTreeOperation(mutation.operation);
+    if (operation.kind === 'tree.create') {
+      importAncestors(operation.parentId);
+    } else {
+      // Import the UUID the local operation names, but not untouched
+      // descendants. Descendants come from the newer official projection, so
+      // a local folder rename cannot resurrect a child another writer deleted.
+      importAncestors(operation.nodeId);
+      if (operation.parentId) importAncestors(operation.parentId);
+    }
+    nodes = applyTreeOperation(nodes, operation);
+  }
+  for (const nodeId of pendingContentNodeIds(before, database)) importAncestors(nodeId);
+  return { ...official, nodes };
+}
+
+function pathExists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch (error) {
+    if (isPathAbsentError(error)) return false;
+    throw error;
+  }
+}
+
+function physicalBindingAtPath(target, database) {
+  let stats;
+  try {
+    stats = fs.lstatSync(target);
+  } catch (error) {
+    if (isPathAbsentError(error)) return null;
+    throw error;
+  }
+  const kind = stats.isSymbolicLink()
+    ? 'symlink'
+    : stats.isDirectory()
+      ? 'folder'
+      : 'file';
+  const held = localTree().nodeForPath(target, { database });
+  if (
+    !held
+    || held.node.kind !== kind
+    || held.node.deviceId !== String(stats.dev)
+    || held.node.inode !== String(stats.ino)
+  ) {
+    return null;
+  }
+  return {
+    node: held.node,
+    kind,
+    deviceId: String(stats.dev),
+    inode: String(stats.ino),
+  };
+}
+
+function retainedBindingFailures(plan, database) {
+  const failures = [];
+  for (const output of plan.retainedOutputs || []) {
+    const atPath = localTree().nodeForPath(output.path, { database });
+    if (!pathExists(output.path)) {
+      if (atPath) failures.push(output.path);
+      continue;
+    }
+    if (!physicalBindingAtPath(output.path, database)) {
+      failures.push(output.path);
+    }
+  }
+  return failures;
+}
+
+function settleRetainedOutputBindings(plan, database, options = {}) {
+  const operations = [];
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const observed = localTree().reconcileWorkspaceTree(plan.resourceId, {
+      database,
+      skipRecovery: true,
+      source: options.source || 'workspace-tree:retained-binding',
+      persistObservedOperation: options.persistObservedOperation,
+    });
+    operations.push(...(observed.operations || []));
+    if (observed.held?.length) {
+      options.hold(
+        observed.held[0]?.reason || 'retained-birth-pending',
+        observed.held.flatMap((item) => item.paths || []),
+        operations,
+      );
+    }
+    if (
+      attempt === 0
+      && typeof options.testHooks?.afterRetainedBindingReconcile === 'function'
+    ) {
+      options.testHooks.afterRetainedBindingReconcile(
+        plan.retainedOutputs || [],
+        plan,
+      );
+    }
+    const failures = retainedBindingFailures(plan, database);
+    if (!failures.length) {
+      if (typeof options.afterSettled === 'function') {
+        options.afterSettled(operations);
+      }
+      if (
+        typeof options.testHooks?.afterRetainedBindingSettle === 'function'
+      ) {
+        options.testHooks.afterRetainedBindingSettle(
+          plan.retainedOutputs || [],
+          plan,
+        );
+      }
+      return operations;
+    }
+    if (attempt === 1) {
+      options.hold(
+        'retained-physical-binding-changed',
+        failures.map((target) => path.relative(plan.rootPath, target)),
+        operations,
+      );
+    }
+  }
+  return operations;
+}
+
+function captureRemovalPreconditions(rootPath, before, after, beforePaths) {
   const removedIds = new Set();
   for (const node of before.values()) {
     if (node.id === node.workspaceId || !activeNode(node)) continue;
-    if (!activeNode(after.get(node.id))) removedIds.add(node.id);
+    if (!activeNode(after.nodes.get(node.id))) removedIds.add(node.id);
+  }
+  const components = removedComponentIndex(removedIds, before);
+  const excludedPrefixesByRoot = new Map();
+  // A surviving node whose old parent is removed is the one physical boundary
+  // between two removed components. The outer precondition must stop there:
+  // the survivor is moved intact, and any removed descendants below it are
+  // captured by their own component. This partitions the forest so every
+  // byte is read by at most one destructive precondition.
+  for (const node of before.values()) {
+    if (
+      node.id === node.workspaceId
+      || !activeNode(node)
+      || !activeNode(after.nodes.get(node.id))
+      || !removedIds.has(node.parentId)
+    ) continue;
+    const rootId = components.rootById.get(node.parentId);
+    const rootPathBefore = beforePaths.get(rootId);
+    const nodePathBefore = beforePaths.get(node.id);
+    const prefix = descendantSuffix(nodePathBefore, rootPathBefore);
+    if (!rootId || !prefix) {
+      throw invalid(`workspace tree survivor ${node.id} has no removal boundary`, 409);
+    }
+    const prefixes = excludedPrefixesByRoot.get(rootId) || [];
+    prefixes.push(prefix);
+    excludedPrefixesByRoot.set(rootId, prefixes);
   }
-  const removedRoots = Array.from(removedIds)
-    .map((id) => before.get(id))
-    .filter((node) => !hasAncestorInSet(node, before, removedIds));
-  require('../state/docs').closeDocsByNodeIds(removedIds);
-  for (const node of removedRoots) {
+  const materialization = require('./tree-materialization');
+  const preconditions = new Map();
+  for (const node of components.roots) {
     const relative = beforePaths.get(node.id);
-    if (relative) fs.rmSync(path.join(rootPath, ...relative.split('/')), { recursive: true, force: true });
+    const source = relative
+      ? path.join(rootPath, ...relative.split('/'))
+      : null;
+    if (source && pathExists(source)) {
+      preconditions.set(node.id, materialization.removalPrecondition(source, {
+        excludedPrefixes: excludedPrefixesByRoot.get(node.id) || [],
+      }));
+    }
+  }
+  return { preconditions, removedIds };
+}
+
+function removedComponentIndex(removedIds, nodes) {
+  const rootById = new Map();
+  for (const id of removedIds) {
+    if (rootById.has(id)) continue;
+    const trail = [];
+    let currentId = id;
+    let rootId = null;
+    while (removedIds.has(currentId) && !rootById.has(currentId)) {
+      const node = nodes.get(currentId);
+      if (!node) break;
+      trail.push(currentId);
+      if (!removedIds.has(node.parentId)) {
+        rootId = currentId;
+        break;
+      }
+      currentId = node.parentId;
+    }
+    if (!rootId) rootId = rootById.get(currentId) || currentId;
+    for (const trailId of trail) rootById.set(trailId, rootId);
+  }
+  const rootIds = new Set(rootById.values());
+  return {
+    rootById,
+    roots: Array.from(rootIds)
+      .map((id) => nodes.get(id))
+      .filter(Boolean),
+  };
+}
+
+function matchesPathPrefix(prefixes) {
+  const root = { terminal: false, children: new Map() };
+  for (const relativePath of prefixes) {
+    let current = root;
+    for (const segment of relativePath.split('/').filter(Boolean)) {
+      if (current.terminal) break;
+      if (!current.children.has(segment)) {
+        current.children.set(segment, { terminal: false, children: new Map() });
+      }
+      current = current.children.get(segment);
+    }
+    current.terminal = true;
+    current.children.clear();
+  }
+  return (relativePath) => {
+    let current = root;
+    if (current.terminal) return true;
+    for (const segment of relativePath.split('/').filter(Boolean)) {
+      current = current.children.get(segment);
+      if (!current) return false;
+      if (current.terminal) return true;
+    }
+    return false;
+  };
+}
+
+function retirementAfterPlannedMoves(retirement, excludedPrefixes) {
+  if (!retirement) return null;
+  const excludedByMove = matchesPathPrefix(excludedPrefixes);
+  const remains = (relativePath) => !excludedByMove(relativePath);
+  return {
+    entries: retirement.entries.filter((entry) => remains(entry.relativePath)),
+    directories: retirement.directories.filter((entry) => remains(entry.relativePath)),
+  };
+}
+
+function descendantSuffix(relativePath, ancestorPath) {
+  if (
+    !relativePath
+    || !ancestorPath
+    || relativePath === ancestorPath
+    || !relativePath.startsWith(`${ancestorPath}/`)
+  ) {
+    return null;
   }
+  return relativePath.slice(ancestorPath.length + 1);
+}
 
+function physicalPlan({
+  rootPath,
+  rootIdentity = null,
+  before,
+  officialSnapshot,
+  afterSnapshot,
+  beforePaths,
+  afterPaths,
+  envelope,
+  checksum,
+  permissions,
+  contentResources,
+  initial,
+  removalPreconditions = null,
+}) {
+  const after = afterSnapshot.nodes;
+  const removedIds = new Set();
+  for (const node of before.values()) {
+    if (node.id === node.workspaceId || !activeNode(node)) continue;
+    if (!activeNode(after.get(node.id))) removedIds.add(node.id);
+  }
+  const removedComponents = removedComponentIndex(removedIds, before);
+  const removedRoots = removedComponents.roots;
   const changedIds = new Set();
   for (const node of after.values()) {
-    if (node.id === afterSnapshot.workspaceId || !activeNode(node) || !activeNode(before.get(node.id))) continue;
-    if (beforePaths.get(node.id) !== afterPaths.get(node.id)) changedIds.add(node.id);
+    if (
+      node.id === afterSnapshot.workspaceId
+      || !activeNode(node)
+      || !activeNode(before.get(node.id))
+    ) continue;
+    const previous = before.get(node.id);
+    if (
+      beforePaths.get(node.id) !== afterPaths.get(node.id)
+      || previous.parentId !== node.parentId
+    ) {
+      changedIds.add(node.id);
+    }
   }
-  const changedRoots = Array.from(changedIds)
+  const treeMaterialization = require('./tree-materialization');
+  // Bind every surviving UUID to the physical object that currently owns it.
+  // Move roots alone are not a complete proof: a child can rename while its
+  // parent moves, in which case moving only the parent leaves the child at the
+  // wrong suffix while the database claims the snapshot is installed.
+  const rollbackBindings = Array.from(before.values())
+    .filter((node) => (
+      node.id !== afterSnapshot.workspaceId
+      && activeNode(node)
+    ))
+    .sort((left, right) => left.id.localeCompare(right.id))
+    .map((node) => {
+      const previous = node;
+      const projected = after.get(node.id);
+      if (
+        activeNode(projected)
+        && (
+          previous.kind !== projected.kind
+          || previous.symlinkTarget !== projected.symlinkTarget
+        )
+      ) {
+        throw invalid(
+          `workspace tree node ${node.id} changed its immutable physical identity`,
+          409,
+        );
+      }
+      const from = beforePaths.get(node.id);
+      const source = path.join(rootPath, ...from.split('/'));
+      if (!pathExists(source)) {
+        throw invalid(`workspace tree node ${node.id} has no physical source`, 409);
+      }
+      return {
+        nodeId: node.id,
+        from,
+        to: activeNode(projected) ? afterPaths.get(node.id) : null,
+        kind: previous.kind,
+        symlinkTarget: previous.symlinkTarget,
+        identity: treeMaterialization.identity(source, { deep: false }),
+      };
+    });
+  const rollbackBindingByNodeId = new Map(
+    rollbackBindings.map((binding) => [binding.nodeId, binding]),
+  );
+  const projectedBindings = Array.from(after.values())
+    .filter((node) => (
+      node.id !== afterSnapshot.workspaceId
+      && activeNode(node)
+      && activeNode(before.get(node.id))
+    ))
+    .sort((left, right) => left.id.localeCompare(right.id))
+    .map((node) => {
+      const binding = rollbackBindingByNodeId.get(node.id);
+      if (!binding) {
+        throw invalid(`workspace tree node ${node.id} has no rollback binding`, 409);
+      }
+      return {
+        ...binding,
+        to: afterPaths.get(node.id),
+      };
+    });
+  const bindingByNodeId = new Map(
+    projectedBindings.map((binding) => [binding.nodeId, binding]),
+  );
+  // A changed descendant may ride inside an already planned ancestor only
+  // when that ancestor carries the descendant to its exact final suffix.
+  // Otherwise stage both nodes independently: deepest sources extract first,
+  // then target-depth order installs the parent before the child.
+  const moves = [];
+  const carrierStack = [];
+  const changedNodes = Array.from(changedIds)
     .map((id) => after.get(id))
-    .filter((node) => !hasAncestorInSet(node, after, changedIds));
-  const stagingRoot = path.join(AMALGM_DIR, 'staging', 'workspace-tree', crypto.randomBytes(12).toString('hex'));
-  const staged = [];
-  for (const node of changedRoots) {
-    const oldRelative = beforePaths.get(node.id);
-    const oldPath = path.join(rootPath, ...oldRelative.split('/'));
-    if (!fs.existsSync(oldPath)) continue;
-    const stagedPath = path.join(stagingRoot, node.id);
-    fs.mkdirSync(path.dirname(stagedPath), { recursive: true });
-    fs.renameSync(oldPath, stagedPath);
-    staged.push({ node, stagedPath });
-  }
-  for (const item of staged) {
-    const nextPath = path.join(rootPath, ...afterPaths.get(item.node.id).split('/'));
-    fs.mkdirSync(path.dirname(nextPath), { recursive: true });
-    fs.renameSync(item.stagedPath, nextPath);
-  }
-  fs.rmSync(stagingRoot, { recursive: true, force: true });
-
-  const ordered = Array.from(after.values()).sort((left, right) => {
-    const leftPath = afterPaths.get(left.id);
-    const rightPath = afterPaths.get(right.id);
-    return (leftPath ? leftPath.split('/').length : 0) - (rightPath ? rightPath.split('/').length : 0);
+    .sort((left, right) => {
+      const leftPath = beforePaths.get(left.id);
+      const rightPath = beforePaths.get(right.id);
+      if (leftPath !== rightPath) return leftPath < rightPath ? -1 : 1;
+      return left.id.localeCompare(right.id);
+    });
+  for (const node of changedNodes) {
+    const from = beforePaths.get(node.id);
+    const to = afterPaths.get(node.id);
+    const parentChanged = before.get(node.id).parentId !== node.parentId;
+    while (
+      carrierStack.length
+      && descendantSuffix(from, carrierStack[carrierStack.length - 1].from) === null
+    ) {
+      carrierStack.pop();
+    }
+    const carrier = carrierStack[carrierStack.length - 1] || null;
+    const carriedSuffix = carrier ? descendantSuffix(from, carrier.from) : null;
+    if (
+      !parentChanged
+      && carrier
+      && `${carrier.to}/${carriedSuffix}` === to
+    ) {
+      continue;
+    }
+    const binding = bindingByNodeId.get(node.id);
+    if (!binding) {
+      throw invalid(`workspace tree move ${node.id} has no physical binding`, 409);
+    }
+    const move = {
+      nodeId: node.id,
+      from,
+      to,
+      sourceParentNodeId: before.get(node.id)?.parentId || afterSnapshot.workspaceId,
+      targetParentNodeId: node.parentId || afterSnapshot.workspaceId,
+      kind: binding.kind,
+      symlinkTarget: binding.symlinkTarget,
+      identity: binding.identity,
+    };
+    moves.push(move);
+    carrierStack.push(move);
+  }
+  // Rollback must be able to reverse an independently staged descendant even
+  // when a local tool carried it inside any surviving parent, including one
+  // that the official snapshot did not move. Derive carriers from UUID
+  // ancestry and the complete projected binding set, never pathname sort.
+  const annotateCarrier = (move, node, nodes, paths, bindingPath, prefix) => {
+    let parentId = node?.parentId || null;
+    while (parentId) {
+      const carrier = bindingByNodeId.get(parentId);
+      if (carrier) {
+        const suffix = descendantSuffix(
+          paths.get(move.nodeId),
+          carrier[bindingPath],
+        );
+        if (!suffix) {
+          throw invalid(
+            `workspace tree move ${move.nodeId} has an invalid ${prefix} carrier`,
+            409,
+          );
+        }
+        move[`${prefix}CarrierNodeId`] = carrier.nodeId;
+        move[`${prefix}CarrierSuffix`] = suffix;
+        return;
+      }
+      parentId = nodes.get(parentId)?.parentId || null;
+    }
+  };
+  for (const move of moves) {
+    annotateCarrier(
+      move,
+      before.get(move.nodeId),
+      before,
+      beforePaths,
+      'from',
+      'source',
+    );
+    annotateCarrier(
+      move,
+      after.get(move.nodeId),
+      after,
+      afterPaths,
+      'to',
+      'target',
+    );
+  }
+  // A surviving node can split exactly one removed component: the component
+  // containing its direct old parent. Assign that boundary once by UUID
+  // ancestry instead of rescanning every move for every removed root.
+  const movedPrefixesByRemovalRoot = new Map();
+  for (const move of moves) {
+    const oldParentId = before.get(move.nodeId)?.parentId;
+    if (!removedIds.has(oldParentId)) continue;
+    const rootId = removedComponents.rootById.get(oldParentId);
+    const removedFrom = beforePaths.get(rootId);
+    const suffix = descendantSuffix(move.from, removedFrom);
+    if (!rootId || !suffix) {
+      throw invalid(
+        `workspace tree move ${move.nodeId} has no removed-component boundary`,
+        409,
+      );
+    }
+    const prefixes = movedPrefixesByRemovalRoot.get(rootId) || [];
+    prefixes.push(suffix);
+    movedPrefixesByRemovalRoot.set(rootId, prefixes);
+  }
+  const removals = removedRoots.flatMap((node) => {
+    const from = beforePaths.get(node.id);
+    const source = path.join(rootPath, ...from.split('/'));
+    if (!from || !pathExists(source)) return [];
+    const precondition = removalPreconditions?.get(node.id) || null;
+    if (removalPreconditions && !precondition) {
+      throw invalid(`workspace tree removal ${node.id} has no capture precondition`, 409);
+    }
+    return [{
+        nodeId: node.id,
+        from,
+        to: null,
+        sourceParentNodeId: before.get(node.id)?.parentId || afterSnapshot.workspaceId,
+        // The deep preflight binds every byte before the first planned move.
+        // The later staging step uses only the root inode because moving a
+        // planned descendant legitimately changes its ancestor's digest.
+        identity: treeMaterialization.identity(source, { deep: false }),
+        preflightIdentity: precondition?.identity || null,
+        retirement: retirementAfterPlannedMoves(
+          precondition?.retirement || treeMaterialization.removalPrecondition(source).retirement,
+          movedPrefixesByRemovalRoot.get(node.id) || [],
+        ),
+      }];
   });
-  for (const node of ordered) {
-    if (node.id === afterSnapshot.workspaceId || !activeNode(node)) continue;
-    const target = path.join(rootPath, ...afterPaths.get(node.id).split('/'));
-    if (!fs.existsSync(target)) createProjectedNode(rootPath, node, afterPaths.get(node.id));
-  }
-  const changedPaths = Array.from(changedIds).map((nodeId) => ({
-    nodeId,
-    oldPath: path.join(rootPath, ...beforePaths.get(nodeId).split('/')),
-    newPath: path.join(rootPath, ...afterPaths.get(nodeId).split('/')),
-  }));
-  if (changedPaths.length) require('../state/docs').rebindNodePaths(changedPaths);
+  const creates = Array.from(after.values())
+    .filter((node) => (
+      node.id !== afterSnapshot.workspaceId
+      && activeNode(node)
+      && !activeNode(before.get(node.id))
+    ))
+    .sort((left, right) => (
+      afterPaths.get(left.id).split('/').length - afterPaths.get(right.id).split('/').length
+    ))
+    .map((node) => {
+      const to = afterPaths.get(node.id);
+      const target = path.join(rootPath, ...to.split('/'));
+      if (
+        node.kind === 'symlink'
+        && !safeSymlinkTarget(rootPath, target, node.symlinkTarget)
+      ) {
+        throw invalid(`workspace tree symlink escapes its root: ${to}`, 409);
+      }
+      return {
+        nodeId: node.id,
+        to,
+        targetParentNodeId: node.parentId || afterSnapshot.workspaceId,
+        kind: node.kind,
+        symlinkTarget: node.symlinkTarget,
+      };
+    });
+  const verifiedRootIdentity = rootIdentity
+    || treeMaterialization.identity(rootPath, { deep: false });
+  return {
+    contract: 'workspace-tree-materialization@1',
+    resourceId: envelope.resourceId,
+    snapshotVersion: envelope.snapshotVersion,
+    snapshotChecksum: checksum,
+    rootPath,
+    rootIdentity: {
+      kind: 'folder',
+      dev: String(verifiedRootIdentity.dev ?? verifiedRootIdentity.deviceId),
+      ino: String(verifiedRootIdentity.ino ?? verifiedRootIdentity.inode),
+    },
+    envelope,
+    officialSnapshot: snapshotRecord(officialSnapshot || afterSnapshot),
+    snapshot: snapshotRecord(afterSnapshot),
+    permissions,
+    contentResources: Array.isArray(contentResources) ? contentResources : [],
+    initial,
+    workspaceName: after.get(afterSnapshot.workspaceId).name,
+    beforeNodes: Array.from(before.values()),
+    rollbackBindings,
+    projectedBindings,
+    moves,
+    removals,
+    creates,
+    removedNodeIds: Array.from(removedIds),
+    changedPaths: Array.from(changedIds).map((nodeId) => ({
+      nodeId,
+      oldPath: path.join(rootPath, ...beforePaths.get(nodeId).split('/')),
+      newPath: path.join(rootPath, ...afterPaths.get(nodeId).split('/')),
+    })),
+  };
+}
+
+function applyStoredTreePlan(held, database, testHooks = {}) {
+  const treeMaterialization = require('./tree-materialization');
+  const plan = held.plan;
+  const replicas = require('../state/replicas');
+  const existingReplica = replicas.getReplicaByResourceId(plan.resourceId, { database });
+  const previousProjectedAuthority = projectedAuthorityEpoch(plan.resourceId, database);
+  if (held.state === 'committed') {
+    const workspace = workspaceRow(plan.resourceId, database);
+    const replica = require('../state/replicas')
+      .getReplicaByResourceId(plan.resourceId, { database });
+    if (!workspace || !replica || replica.appliedVersion < plan.snapshotVersion) {
+      throw invalid('committed workspace tree snapshot is missing its projection', 409);
+    }
+    finishTreeSnapshotPlan(held, database, testHooks);
+    return {
+      workspace,
+      replica,
+      contentAttachments: [],
+      duplicate: true,
+      recovered: true,
+    };
+  }
+  if (
+    existingReplica
+    && Number(plan.envelope.authorityEpoch) < existingReplica.authorityEpoch
+  ) {
+    throw invalid(
+      `workspace tree plan ${plan.resourceId}@${plan.snapshotVersion} has stale authority`,
+      409,
+    );
+  }
+  if (existingReplica) {
+    // A recovery record is not authority. Prove that its permission epoch is
+    // still the newest advertised epoch before closing documents or moving a
+    // single filesystem entry.
+    if (plan.projectionOnly !== true) {
+      const disposition = replicas.inspectReplicaSnapshot({
+        resourceId: plan.resourceId,
+        snapshotVersion: plan.snapshotVersion,
+        snapshotChecksum: plan.snapshotChecksum,
+        authorityEpoch: plan.envelope.authorityEpoch,
+      }, {
+        database,
+        allowAuthorityProjection: true,
+        projectedAuthorityEpoch: previousProjectedAuthority || existingReplica.authorityEpoch,
+      });
+      if (disposition.action !== 'install') {
+        throw invalid(
+          `workspace tree plan ${plan.resourceId}@${plan.snapshotVersion} is no longer installable`,
+          409,
+        );
+      }
+    }
+  }
+  const snapshot = normalizeTreeSnapshot(plan.snapshot);
+  const officialSnapshot = normalizeTreeSnapshot(plan.officialSnapshot || plan.snapshot);
+  const paths = pathMapForSnapshot(snapshot);
+  require('../state/docs').closeDocsByNodeIds(new Set(plan.removedNodeIds));
+  if (typeof testHooks.beforeTreePlanCross === 'function') {
+    testHooks.beforeTreePlanCross(plan);
+  }
+  try {
+    held = treeMaterialization.cross(held, database, testHooks);
+  } catch (error) {
+    holdClassifiedPlanRetry(plan, error, database);
+  }
+  if (testHooks.crashAfterTreePlanCross === true) {
+    throw new Error('simulated workspace tree crash after snapshot crossing');
+  }
+
+  let workspace = workspaceRow(plan.resourceId, database);
+  if (!workspace) {
+    if (!plan.initial) {
+      throw invalid('workspace tree recovery has no local workspace', 409);
+    }
+    workspace = require('./store').upsertWorkspace({
+      id: plan.resourceId,
+      path: plan.rootPath,
+      name: plan.workspaceName,
+      source: 'cloud',
+    }, { source: 'workspace:cloud-attach', seedOwner: false });
+  }
+  const events = require('../state/events');
+  let registered;
+  let contentAttachments;
+  let event;
+  let finishDocRebind = null;
+  const attachmentEvents = [];
+  // The physical plan is already crossed. Publish every database fact that
+  // claims that result—including the cursor and the WAL commit—in one
+  // transaction. A crash may therefore leave the plan crossed and retryable,
+  // or committed and fully represented, but can never leave an advanced
+  // cursor pointing at an uncommitted plan.
+  database.transaction(() => {
+    replaceTreeProjection(
+      database,
+      workspace.id,
+      plan.rootPath,
+      snapshot,
+      paths,
+      plan.permissions,
+      plan.envelope.authorityEpoch,
+    );
+    if (plan.projectionOnly !== true) {
+      require('./tree/floor').write(
+        officialSnapshot,
+        plan.envelope.authorityEpoch,
+        { database },
+      );
+    }
+
+    const existing = replicas.getReplicaByResourceId(plan.resourceId, { database });
+    registered = plan.projectionOnly === true
+      ? { replica: existing }
+      : existing
+      ? {
+        replica: replicas.advanceReplicaSnapshot({
+          resourceId: plan.resourceId,
+          snapshotVersion: plan.snapshotVersion,
+          snapshotChecksum: plan.snapshotChecksum,
+          authorityEpoch: plan.envelope.authorityEpoch,
+        }, {
+          database,
+          allowAuthorityProjection: true,
+          projectedAuthorityEpoch: previousProjectedAuthority || existing.authorityEpoch,
+        }),
+      }
+      : replicas.registerReplica({
+        resourceId: plan.resourceId,
+        localResource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
+        localPath: plan.rootPath,
+        contract: 'workspace-tree@1',
+        schemaVersion: 1,
+        authorityEpoch: plan.envelope.authorityEpoch,
+        appliedVersion: plan.snapshotVersion,
+        snapshotVersion: plan.snapshotVersion,
+        snapshotChecksum: plan.snapshotChecksum,
+      }, { database });
+    if (testHooks.crashAfterSnapshotReplicaAdvance === true) {
+      throw new Error('simulated workspace tree crash after snapshot replica advance');
+    }
+
+    if (plan.changedPaths.length) {
+      finishDocRebind = require('../state/docs').rebindNodePaths(
+        plan.changedPaths,
+        { database, deferOpenDocs: true },
+      );
+    }
+    contentAttachments = enqueueProjectedContentAttachments(
+      plan.rootPath,
+      snapshot,
+      paths,
+      {
+        contentResources: plan.contentResources,
+        deferredEvents: attachmentEvents,
+      },
+      database,
+    );
+    if (testHooks.crashAfterSnapshotAttachmentEnqueue === true) {
+      throw new Error('simulated workspace tree crash after snapshot attachment enqueue');
+    }
+    if (plan.projectionOnly !== true) {
+      require('../state/mutations').completeOfficialSnapshotFold(
+        plan.resourceId,
+        plan.snapshotVersion,
+        { database, contract: 'workspace-tree@1' },
+      );
+    }
+    event = events.insertStateEvent(database, {
+      resource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
+      op: 'update',
+      id: workspace.id,
+      value: workspaceTreeSnapshot(workspace.id, { database }),
+      sharedResourceId: workspace.id,
+      source: plan.projectionOnly === true
+        ? 'workspace-tree:overlay-fold'
+        : plan.initial
+          ? 'workspace-tree:cloud-snapshot'
+          : 'workspace-tree:cloud-resnapshot',
+      resourceVersion: plan.snapshotVersion,
+    });
+    held = treeMaterialization.markCommitted(held, database);
+  })();
+  if (finishDocRebind) finishDocRebind();
+  for (const attachmentEvent of attachmentEvents) {
+    events.publishStateEvent(attachmentEvent);
+  }
+  events.publishStateEvent(event);
+  if (testHooks.crashAfterCommit === true) {
+    throw new Error('simulated workspace tree crash after commit');
+  }
+  finishTreeSnapshotPlan(held, database, testHooks);
+  return {
+    workspace,
+    replica: registered.replica,
+    contentAttachments,
+    duplicate: false,
+    recovered: true,
+  };
+}
+
+function recoverTreePlans(resourceId, database, testHooks = {}, options = {}) {
+  let result = null;
+  const materialization = require('./tree-materialization');
+  for (const held of materialization.list(database, resourceId)) {
+    if (
+      options.minimumAuthorityEpoch != null
+      && Number(held.plan?.envelope?.authorityEpoch) < Number(options.minimumAuthorityEpoch)
+    ) {
+      if (held.state === 'committed') {
+        result = applyStoredTreePlan(held, database, testHooks);
+        continue;
+      }
+      let superseded = false;
+      try {
+        superseded = materialization.supersedeUncommitted(held, database, {
+          testHooks,
+          captureRetainedOutputs(retainedOutputs, plan) {
+            retainRemovalSuccessors(
+              plan,
+              [{ retainedOutputs }],
+              database,
+              { reuseIds: true },
+            );
+          },
+        });
+      } catch (error) {
+        holdClassifiedPlanRetry(held.plan, error, database);
+      }
+      if (!superseded) {
+        throw invalid(
+          `workspace tree stale plan ${held.resourceId}@${held.snapshotVersion} could not roll back`,
+          409,
+        );
+      }
+      continue;
+    }
+    result = applyStoredTreePlan(held, database, testHooks);
+  }
+  return result;
+}
+
+function recoverAllTreePlans(options = {}) {
+  const database = options.database || openLocalDb();
+  const results = [];
+  for (const held of require('./tree-materialization').list(database)) {
+    results.push(applyStoredTreePlan(held, database, options.testHooks));
+  }
+  for (const held of require('./tree-materialization').listOperations(database)) {
+    results.push(applyStoredTreeOperationPlan(held, database, options.testHooks));
+  }
+  // A legacy carrier can be temporarily absent while one of the plans above
+  // owns it in private staging. Only the recovered physical slot may assign
+  // its component UUID; timestamps are never a fallback.
+  require('../state/db').backfillWorkspaceTrashComponents(database);
+  return results;
 }
 
 function enqueueProjectedContentAttachments(rootPath, snapshot, paths, input, database) {
   const resources = Array.isArray(input?.contentResources) ? input.contentResources : [];
+  const deferredEvents = Array.isArray(input?.deferredEvents) ? input.deferredEvents : null;
   const queued = [];
   for (const resource of resources) {
     const nodeId = String(resource?.node_id || resource?.nodeId || '').toLowerCase();
@@ -227,11 +1061,13 @@ function enqueueProjectedContentAttachments(rootPath, snapshot, paths, input, da
     if (require('../state/replicas').getReplicaByResourceId(nodeId, { database })) continue;
     if (require('../state/attachments').getAttachmentByResource(nodeId, { database })) continue;
     const localPath = path.join(rootPath, ...paths.get(nodeId).split('/'));
-    queued.push(require('../state/attachments').enqueueAttachment({
+    const result = require('../state/attachments').enqueueAttachment({
       attachmentId: `att_${crypto.randomBytes(16).toString('base64url')}`,
       resourceId: nodeId,
       localPath,
-    }, { database }).attachment);
+    }, { database, deferEvent: deferredEvents !== null });
+    queued.push(result.attachment);
+    if (deferredEvents && result.deferredEvent) deferredEvents.push(result.deferredEvent);
   }
   return queued;
 }
@@ -253,139 +1089,2618 @@ function enqueueWorkspaceContentAttachments(workspaceId, contentResources, optio
   );
 }
 
-function installCloudTreeSnapshot(pathInput, input, options = {}) {
-  if (input?.contract !== 'workspace-tree@1' || Number(input?.schemaVersion) !== 1) {
-    throw invalid('unsupported workspace tree contract', 409);
+/**
+ * A document mutation can temporarily own tree membership while an official
+ * tree snapshot omits that UUID. When the last document overlay folds, derive
+ * the physical tree again from the unchanged official floor plus the now
+ * smaller durable overlay. This is an explicit projection transition, not an
+ * observer guess.
+ */
+function reconcileContentOverlay(nodeId, options = {}) {
+  const database = options.database || openLocalDb();
+  const row = database.prepare(`
+    SELECT workspace_id FROM workspace_nodes WHERE id = ?
+  `).get(nodeId);
+  if (!row) return { changed: false, reason: 'node-not-projected' };
+  const workspace = workspaceRow(row.workspace_id, database);
+  const replica = require('../state/replicas')
+    .getReplicaByResourceId(row.workspace_id, { database });
+  const floor = require('./tree/floor').read(row.workspace_id, { database });
+  if (!workspace || !replica || !floor) {
+    return { changed: false, reason: 'tree-not-cloud-backed' };
+  }
+  const rootProof = localTree().verifiedWorkspaceRoot(workspace, { database });
+  const before = new Map(
+    database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
+      .map(rowToNode)
+      .map((node) => [node.id, node]),
+  );
+  let projected = snapshotWithLocalOverlay(
+    floor.snapshot,
+    before,
+    workspace.id,
+    database,
+  );
+  if (projectionIdentity(before) === projectionIdentity(projected.nodes)) {
+    return { changed: false, reason: 'projection-current' };
   }
+  const beforePaths = pathMapForSnapshot({ workspaceId: workspace.id, nodes: before });
+  const removalCapture = captureRemovalPreconditions(
+    workspace.path,
+    before,
+    projected,
+    beforePaths,
+  );
+  require('../state/docs').captureDocsByNodeIds(
+    removalCapture.removedIds,
+    { database },
+  );
+  projected = snapshotWithLocalOverlay(
+    floor.snapshot,
+    before,
+    workspace.id,
+    database,
+  );
+  if (projectionIdentity(before) === projectionIdentity(projected.nodes)) {
+    return { changed: false, reason: 'newer-document-overlay' };
+  }
+  const afterPaths = pathMapForSnapshot(projected);
+  const permissions = database.prepare(`
+    SELECT node_id AS nodeId, user_id AS userId, role
+    FROM workspace_node_permissions
+    WHERE workspace_id = ? AND revoked_at IS NULL
+  `).all(workspace.id);
+  const checksum = crypto.createHash('sha256')
+    .update(JSON.stringify({
+      kind: 'workspace-tree-overlay-fold@1',
+      nodeId,
+      floorVersion: floor.version,
+      projection: snapshotRecord(projected),
+    }))
+    .digest('hex');
+  const plan = {
+    ...physicalPlan({
+      rootPath: workspace.path,
+      rootIdentity: rootProof.identity,
+      before,
+      officialSnapshot: floor.snapshot,
+      afterSnapshot: projected,
+      beforePaths,
+      afterPaths,
+      envelope: {
+        resourceId: workspace.id,
+        contract: 'workspace-tree@1',
+        schemaVersion: 1,
+        authorityEpoch: floor.authorityEpoch,
+        snapshotVersion: floor.version,
+        headVersion: replica.appliedVersion,
+      },
+      checksum,
+      permissions,
+      contentResources: [],
+      initial: false,
+      removalPreconditions: removalCapture.preconditions,
+    }),
+    projectionOnly: true,
+    overlayFoldNodeId: nodeId,
+  };
+  const held = require('./tree-materialization').insert(plan, database);
+  const result = applyStoredTreePlan(held, database, options.testHooks);
+  return { ...result, changed: true };
+}
+
+function installCloudTreeSnapshot(pathInput, input, options = {}) {
+  const replicas = require('../state/replicas');
+  const envelope = replicas.validateSnapshotEnvelope(input, {
+    contract: 'workspace-tree@1',
+    schemaVersion: 1,
+  });
   const database = options.database || openLocalDb();
   const { checksum, snapshot } = decodeTreeSnapshot(input);
   if (snapshot.workspaceId !== input.resourceId) throw invalid('workspace tree identity mismatch', 409);
+  if (snapshot.version !== envelope.snapshotVersion) {
+    throw invalid('workspace tree snapshot version mismatch', 409);
+  }
   const rootPath = path.resolve(pathInput);
-  fs.mkdirSync(rootPath, { recursive: true });
-  const existingReplica = require('../state/replicas').getReplicaByResourceId(input.resourceId, { database });
+  let existingReplica = replicas.getReplicaByResourceId(input.resourceId, { database });
+  let rootProof = null;
   const paths = pathMapForSnapshot(snapshot);
   const permissions = normalizeSnapshotPermissions(input, snapshot);
   if (existingReplica) {
+    const existingWorkspace = workspaceRow(input.resourceId, database);
+    if (!existingWorkspace) {
+      throw invalid('workspace tree has no registered local folder', 409);
+    }
+    rootProof = localTree().verifiedWorkspaceRoot(existingWorkspace, { database });
     if (existingReplica.localPath !== rootPath) throw invalid('workspace tree is bound to another folder', 409);
+    const incomingVersion = envelope.snapshotVersion;
+    // Validate the incoming authority before recovering any old physical
+    // plan. A prepared plan from an older permission epoch is canceled while
+    // it is still only a control record; it is never allowed to touch disk.
+    replicas.inspectReplicaSnapshot({
+      resourceId: envelope.resourceId,
+      snapshotVersion: incomingVersion,
+      snapshotChecksum: checksum,
+      authorityEpoch: envelope.authorityEpoch,
+    }, {
+      database,
+      allowAuthorityProjection: true,
+      projectedAuthorityEpoch: projectedAuthorityEpoch(envelope.resourceId, database)
+        || existingReplica.authorityEpoch,
+    });
+    recoverTreePlans(
+      envelope.resourceId,
+      database,
+      options.testHooks,
+      { minimumAuthorityEpoch: envelope.authorityEpoch },
+    );
+    existingReplica = replicas.getReplicaByResourceId(input.resourceId, { database });
+    const disposition = replicas.inspectReplicaSnapshot({
+      resourceId: envelope.resourceId,
+      snapshotVersion: incomingVersion,
+      snapshotChecksum: checksum,
+      authorityEpoch: envelope.authorityEpoch,
+    }, {
+      database,
+      allowAuthorityProjection: true,
+      projectedAuthorityEpoch: projectedAuthorityEpoch(envelope.resourceId, database)
+        || existingReplica.authorityEpoch,
+    });
+    if (disposition.action !== 'install') {
+      const checked = replicas.advanceReplicaSnapshot({
+        resourceId: envelope.resourceId,
+        snapshotVersion: incomingVersion,
+        snapshotChecksum: checksum,
+        authorityEpoch: envelope.authorityEpoch,
+      }, {
+        database,
+        allowAuthorityProjection: true,
+        projectedAuthorityEpoch: projectedAuthorityEpoch(envelope.resourceId, database)
+          || existingReplica.authorityEpoch,
+      });
+      if (
+        disposition.action === 'duplicate'
+        || disposition.action === 'metadata'
+      ) {
+        return { replica: checked, contentAttachments: [], duplicate: true };
+      }
+      return {
+        replica: checked,
+        contentAttachments: [],
+        duplicate: true,
+        stale: true,
+      };
+    }
+    const captureBefore = new Map(
+      database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(snapshot.workspaceId)
+        .map(rowToNode)
+        .map((node) => [node.id, node]),
+    );
+    const captureBeforePaths = pathMapForSnapshot({
+      workspaceId: snapshot.workspaceId,
+      nodes: captureBefore,
+    });
+    const captureProjected = snapshotWithLocalOverlay(
+      snapshot,
+      captureBefore,
+      envelope.resourceId,
+      database,
+    );
+    const removalCapture = captureRemovalPreconditions(
+      rootPath,
+      captureBefore,
+      captureProjected,
+      captureBeforePaths,
+    );
+    // A save already present when this snapshot arrives gets its document
+    // birth certificate after the physical predecessor was sealed. A save
+    // after this point changes the sealed subtree digest and stops crossing.
+    require('../state/docs').captureDocsByNodeIds(
+      removalCapture.removedIds,
+      { database },
+    );
+    const observed = localTree().reconcileWorkspaceTree(snapshot.workspaceId, {
+      database,
+      source: 'workspace-tree:pre-snapshot',
+    });
+    if (observed.held?.length) {
+      throw invalid('workspace tree has held local changes', 409);
+    }
+    if (typeof options.testHooks?.afterTreeReconcile === 'function') {
+      options.testHooks.afterTreeReconcile();
+    }
     const before = new Map(
       database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(snapshot.workspaceId)
         .map(rowToNode)
         .map((node) => [node.id, node]),
     );
     const beforePaths = pathMapForSnapshot({ workspaceId: snapshot.workspaceId, nodes: before });
-    materializeTreeProjection(rootPath, before, snapshot, beforePaths, paths);
-    replaceTreeProjection(database, snapshot.workspaceId, snapshot, paths, permissions, input.authorityEpoch);
-    const replica = require('../state/replicas').advanceReplicaSnapshot({
-      resourceId: input.resourceId,
-      snapshotVersion: input.snapshotVersion,
-      snapshotChecksum: checksum,
-      authorityEpoch: input.authorityEpoch,
-    }, { database });
-    const contentAttachments = enqueueProjectedContentAttachments(rootPath, snapshot, paths, input, database);
-    require('../state/events').appendStateEvent({
-      resource: `${TREE_RESOURCE_PREFIX}${snapshot.workspaceId}`,
-      op: 'update', id: snapshot.workspaceId,
-      value: workspaceTreeSnapshot(snapshot.workspaceId, { database }),
-      sharedResourceId: snapshot.workspaceId,
-      source: 'workspace-tree:cloud-resnapshot',
-      resourceVersion: Number(input.snapshotVersion),
+    const projected = snapshotWithLocalOverlay(
+      snapshot,
+      before,
+      envelope.resourceId,
+      database,
+    );
+    const projectedPaths = pathMapForSnapshot(projected);
+    const plan = physicalPlan({
+      rootPath,
+      rootIdentity: rootProof.identity,
+      before,
+      officialSnapshot: snapshot,
+      afterSnapshot: projected,
+      beforePaths,
+      afterPaths: projectedPaths,
+      envelope,
+      checksum,
+      permissions,
+      contentResources: input.contentResources,
+      initial: false,
+      removalPreconditions: removalCapture.preconditions,
     });
-    return { replica, contentAttachments, duplicate: false };
+    const held = require('./tree-materialization').insert(plan, database);
+    return applyStoredTreePlan(held, database, options.testHooks);
   }
+  const recovered = recoverTreePlans(
+    envelope.resourceId,
+    database,
+    options.testHooks,
+    { minimumAuthorityEpoch: envelope.authorityEpoch },
+  );
+  if (recovered) return recovered;
+  fs.mkdirSync(rootPath, { recursive: true });
   if (fs.readdirSync(rootPath).length > 0) {
     throw invalid('cloud workspace attachment requires an empty folder', 409);
   }
 
-  const root = snapshot.nodes.get(snapshot.workspaceId);
-  const workspace = require('./store').upsertWorkspace({
-    id: snapshot.workspaceId,
-    path: rootPath,
-    name: root.name,
-    source: 'cloud',
-  }, { source: 'workspace:cloud-attach', seedOwner: false });
-  const ordered = replaceTreeProjection(
-    database, workspace.id, snapshot, paths, permissions, input.authorityEpoch,
-  );
-  for (const node of ordered) {
-    if (node.id === workspace.id || node.trashedAt || node.purgedAt) continue;
-    createProjectedNode(rootPath, node, paths.get(node.id));
+  const plan = physicalPlan({
+    rootPath,
+    before: new Map(),
+    officialSnapshot: snapshot,
+    afterSnapshot: snapshot,
+    beforePaths: new Map(),
+    afterPaths: paths,
+    envelope,
+    checksum,
+    permissions,
+    contentResources: input.contentResources,
+    initial: true,
+  });
+  const held = require('./tree-materialization').insert(plan, database);
+  return applyStoredTreePlan(held, database, options.testHooks);
+}
+
+function operationPath(workspace, nodes, nodeId) {
+  const relative = relativePathForNode(nodes, nodeId);
+  return relative ? path.join(workspace.path, ...relative.split('/')) : workspace.path;
+}
+
+function retainedRecoveryTarget(workspace, nodes, nodeId, mutationId) {
+  const node = nodes.get(nodeId);
+  let parent = node ? nodes.get(node.parentId) : null;
+  while (parent && (parent.trashedAt || parent.purgedAt)) {
+    parent = nodes.get(parent.parentId) || null;
   }
+  if (!node || !parent || parent.kind !== 'folder') {
+    throw invalid(`purge retention has no live parent for ${nodeId}`, 409);
+  }
+  const extension = node.kind === 'folder' ? '' : path.extname(node.name);
+  const stem = extension ? node.name.slice(0, -extension.length) : node.name;
+  const token = crypto.createHash('sha256')
+    .update(`${mutationId}\0${nodeId}`)
+    .digest('hex')
+    .slice(0, 12);
+  const marker = `.amalgm-retained-${token}`;
+  const keptExtension = extension.slice(-32);
+  const keptStem = stem.slice(0, Math.max(1, 255 - marker.length - keptExtension.length));
+  return {
+    path: path.join(
+      operationPath(workspace, nodes, parent.id),
+      `${keptStem}${marker}${keptExtension}`,
+    ),
+    parentNodeId: parent.id,
+  };
+}
 
-  const registered = require('../state/replicas').registerReplica({
-    resourceId: input.resourceId,
-    localResource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
-    localPath: rootPath,
-    contract: input.contract,
-    schemaVersion: input.schemaVersion,
-    authorityEpoch: input.authorityEpoch,
-    appliedVersion: input.snapshotVersion,
-    snapshotVersion: input.snapshotVersion,
-    snapshotChecksum: checksum,
-  }, { database });
-  const contentAttachments = enqueueProjectedContentAttachments(rootPath, snapshot, paths, input, database);
-  require('../state/events').appendStateEvent({
-    resource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
-    op: 'update',
-    id: workspace.id,
-    value: workspaceTreeSnapshot(workspace.id, { database }),
-    sharedResourceId: workspace.id,
-    source: 'workspace-tree:cloud-snapshot',
-    resourceVersion: Number(input.snapshotVersion),
-  });
-  return { workspace, replica: registered.replica, contentAttachments, duplicate: false };
+function trashComponentRoot(nodes, nodeId) {
+  const node = nodes.get(nodeId);
+  if (!node?.trashedAt || node.purgedAt) return null;
+  const root = nodes.get(node.trashComponentId || node.id);
+  if (
+    !root
+    || !root.trashedAt
+    || root.purgedAt
+    || !descendantsInclude(nodes, root.id, node.id)
+  ) {
+    throw invalid(`trash component ${node.trashComponentId || node.id} is invalid`, 409);
+  }
+  return root;
 }
 
-function applyCloudTreeMutation(input, options = {}) {
-  const envelope = input?.envelope || {};
-  if (envelope.contract !== 'workspace-tree@1') throw invalid('unsupported workspace tree mutation', 409);
-  const operation = normalizeTreeOperation(envelope.operation);
-  if (operation.workspaceId !== envelope.resourceId || operation.kind !== envelope.operationKind) {
-    throw invalid('workspace tree mutation identity mismatch', 409);
+function physicalNodePath(workspace, nodes, nodeId, options = {}) {
+  const node = nodes.get(nodeId);
+  if (!node || node.id === workspace.id || node.purgedAt) return null;
+  if (!node.trashedAt) return operationPath(workspace, nodes, nodeId);
+  const root = trashComponentRoot(nodes, nodeId);
+  if (!root) return null;
+  if (
+    options.availableTrashRoots
+    && !options.availableTrashRoots.has(root.id)
+  ) {
+    return null;
   }
-  const database = options.database || openLocalDb();
-  const tree = localTree();
-  const workspace = workspaceRow(operation.workspaceId, database);
-  if (!workspace) throw invalid('workspace tree has no local folder', 404);
-  const before = new Map(
-    database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
-      .map(rowToNode)
-      .map((node) => [node.id, node]),
-  );
-  const after = applyTreeOperation(before, operation);
-  let paths;
-  return require('../state/mutations').ingestCloudMutation({
-    ...input,
-    localResource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
-  }, {
-    database,
-    materialize() {
-      if (operation.kind === 'tree.trash' || operation.kind === 'tree.purge') {
-        const affected = new Set(
-          Array.from(before.values())
-            .filter((node) => node.id === operation.nodeId || hasAncestorInSet(node, before, new Set([operation.nodeId])))
-            .map((node) => node.id),
-        );
-        require('../state/docs').closeDocsByNodeIds(affected);
-      }
-      paths = materializeOperation(workspace, before, after, operation);
-      paths.changedPaths = persistNodes(database, before, after, workspace.id);
-      if (paths.changedPaths.length) require('../state/docs').rebindNodePaths(paths.changedPaths);
-    },
-    event: () => ({
-      resource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
-      op: 'update',
-      id: operation.nodeId,
-      patch: operation,
-      sharedResourceId: workspace.id,
+  const rootPath = trashPath(workspace.id, root.id, workspace.path);
+  if (root.id === node.id) return rootPath;
+  const relative = relativePathForNode(nodes, node.id);
+  const rootRelative = relativePathForNode(nodes, root.id);
+  const suffix = descendantSuffix(relative, rootRelative);
+  return suffix ? path.join(rootPath, ...suffix.split('/')) : null;
+}
+
+function physicalParentNodeId(workspace, nodes, nodeId) {
+  const node = nodes.get(nodeId);
+  if (!node || node.id === workspace.id) return null;
+  if (!node.trashedAt) return node.parentId || workspace.id;
+  const root = trashComponentRoot(nodes, nodeId);
+  return root?.id === node.id ? null : node.parentId;
+}
+
+function completeOperationBindings(workspace, nodes) {
+  const bindings = [];
+  for (const node of Array.from(nodes.values()).sort((left, right) => (
+    left.id.localeCompare(right.id)
+  ))) {
+    if (node.id === workspace.id || node.purgedAt) continue;
+    const source = physicalNodePath(workspace, nodes, node.id);
+    if (!source || !pathExists(source)) continue;
+    bindings.push({
+      nodeId: node.id,
+      from: source,
+      kind: node.kind,
+      symlinkTarget: node.symlinkTarget,
+      identity: require('./tree-materialization').identity(source, { deep: false }),
+    });
+  }
+  return bindings;
+}
+
+function fullPhysicalDeltaActions(workspace, before, after) {
+  const treeMaterialization = require('./tree-materialization');
+  const beforePaths = new Map();
+  const availableTrashRoots = new Set();
+  for (const node of before.values()) {
+    if (node.id === workspace.id || node.purgedAt) continue;
+    const source = physicalNodePath(workspace, before, node.id);
+    if (source && pathExists(source)) {
+      beforePaths.set(node.id, source);
+      const root = trashComponentRoot(before, node.id);
+      if (root && root.id === node.id) availableTrashRoots.add(root.id);
+    }
+  }
+  // A visible component that this transition trashes carries its complete
+  // physical subtree into the deterministic trash root. If the root folder
+  // itself disappeared but any descendant inode survived, create that root
+  // explicitly so the survivor has a physical destination. A wholly absent
+  // component stays absent; the planner never invents empty trash merely to
+  // make the database shape easier to realize.
+  for (const node of after.values()) {
+    if (!beforePaths.has(node.id)) continue;
+    const root = trashComponentRoot(after, node.id);
+    if (root) availableTrashRoots.add(root.id);
+  }
+  const afterPaths = new Map();
+  for (const node of after.values()) {
+    if (node.id === workspace.id || node.purgedAt) continue;
+    const target = physicalNodePath(workspace, after, node.id, {
+      availableTrashRoots,
+    });
+    if (target) afterPaths.set(node.id, target);
+  }
+
+  const moveIds = new Set();
+  for (const [nodeId, source] of beforePaths) {
+    const target = afterPaths.get(nodeId);
+    if (!target) continue;
+    const previous = before.get(nodeId);
+    const projected = after.get(nodeId);
+    if (
+      source !== target
+      || previous?.parentId !== projected?.parentId
+      || previous?.trashedAt !== projected?.trashedAt
+    ) {
+      moveIds.add(nodeId);
+    }
+  }
+  const moves = [];
+  const carriers = [];
+  for (const nodeId of Array.from(moveIds).sort((left, right) => (
+    beforePaths.get(left).localeCompare(beforePaths.get(right))
+  ))) {
+    const source = beforePaths.get(nodeId);
+    const target = afterPaths.get(nodeId);
+    while (
+      carriers.length
+      && !source.startsWith(`${carriers[carriers.length - 1].source}${path.sep}`)
+    ) {
+      carriers.pop();
+    }
+    const carrier = carriers[carriers.length - 1] || null;
+    if (carrier) {
+      const suffix = path.relative(carrier.source, source);
+      if (
+        suffix
+        && path.join(carrier.target, suffix) === target
+        && before.get(nodeId)?.parentId === after.get(nodeId)?.parentId
+      ) {
+        continue;
+      }
+    }
+    const node = before.get(nodeId);
+    const projected = after.get(nodeId);
+    const move = {
+      type: 'move',
+      nodeId,
+      source,
+      target,
+      sourceParentNodeId: physicalParentNodeId(workspace, before, nodeId),
+      targetParentNodeId: physicalParentNodeId(workspace, after, nodeId),
+      kind: node.kind,
+      symlinkTarget: node.symlinkTarget,
+      identity: treeMaterialization.identity(source, { deep: false }),
+    };
+    moves.push(move);
+    carriers.push(move);
+    if (
+      node.kind !== projected.kind
+      || node.symlinkTarget !== projected.symlinkTarget
+    ) {
+      throw invalid(`workspace tree node ${nodeId} changed physical kind`, 409);
+    }
+  }
+
+  const movedSources = moves.map((move) => move.source);
+  const removedIds = new Set(
+    Array.from(beforePaths.keys()).filter((nodeId) => !afterPaths.has(nodeId)),
+  );
+  const removalRoots = Array.from(removedIds).filter((nodeId) => {
+    let parentId = before.get(nodeId)?.parentId;
+    while (parentId) {
+      if (removedIds.has(parentId)) return false;
+      parentId = before.get(parentId)?.parentId;
+    }
+    return true;
+  });
+  const removals = removalRoots.map((nodeId) => {
+    const source = beforePaths.get(nodeId);
+    const excludedPrefixes = movedSources
+      .filter((candidate) => candidate.startsWith(`${source}${path.sep}`))
+      .map((candidate) => path.relative(source, candidate).split(path.sep).join('/'));
+    const precondition = treeMaterialization.removalPrecondition(source, {
+      excludedPrefixes,
+    });
+    return {
+      type: 'remove',
+      nodeId,
+      source,
+      sourceParentNodeId: physicalParentNodeId(workspace, before, nodeId),
+      retainTarget: source,
+      identity: precondition.identity,
+      retirement: precondition.retirement,
+    };
+  });
+
+  const creates = [];
+  for (const [nodeId, target] of afterPaths) {
+    if (beforePaths.has(nodeId)) continue;
+    const node = after.get(nodeId);
+    if (before.has(nodeId)) {
+      if (node.kind !== 'folder') {
+        throw invalid(
+          `workspace tree node ${nodeId} has no physical source for projection`,
+          409,
+        );
+      }
+      // A missing trash root is created only when a surviving descendant
+      // needs it as an explicit carrier.
+      if (node.trashedAt && !availableTrashRoots.has(node.id)) continue;
+    }
+    creates.push({
+      type: 'create',
+      nodeId,
+      target,
+      targetParentNodeId: physicalParentNodeId(workspace, after, nodeId),
+      kind: node.kind,
+      symlinkTarget: node.symlinkTarget,
+    });
+  }
+  return [...moves, ...removals, ...creates];
+}
+
+function projectionIdentity(nodes) {
+  return JSON.stringify(Array.from(nodes.values())
+    .map((node) => ({
+      id: node.id,
+      workspaceId: node.workspaceId,
+      parentId: node.parentId,
+      kind: node.kind,
+      name: node.name,
+      symlinkTarget: node.symlinkTarget,
+      trashedAt: node.trashedAt,
+      purgedAt: node.purgedAt,
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id)));
+}
+
+function physicalOperationPlan(
+  workspace,
+  before,
+  after,
+  operation,
+  input,
+  officialAfter = null,
+  options = {},
+) {
+  const treeMaterialization = require('./tree-materialization');
+  validateLiveSymlinkTargets(after, workspace.id);
+  const verifiedRootIdentity = options.rootIdentity || localTree()
+    .verifiedWorkspaceRoot(workspace, { database: options.database })
+    .identity;
+  let actions = [];
+  const physicalNoop = options.diskAlreadyApplied === true
+    || projectionIdentity(before) === projectionIdentity(after);
+  if (physicalNoop) {
+    // The numbered event moved the official floor underneath an identical
+    // local overlay. Its physical echo is deliberately empty.
+  } else if (options.projectFullDelta === true) {
+    actions = fullPhysicalDeltaActions(workspace, before, after);
+  } else if (operation.kind === 'tree.create') {
+    const target = operationPath(workspace, after, operation.nodeId);
+    if (pathExists(target)) {
+      throw invalid('create destination already exists', 409);
+    }
+    if (
+      operation.nodeKind === 'symlink'
+      && !safeSymlinkTarget(workspace.path, target, operation.symlinkTarget)
+    ) {
+      throw invalid(`workspace tree symlink escapes its root: ${target}`, 409);
+    }
+    actions.push({
+      type: 'create',
+      nodeId: operation.nodeId,
+      target,
+      targetParentNodeId: after.get(operation.nodeId)?.parentId || workspace.id,
+      kind: operation.nodeKind,
+      symlinkTarget: operation.symlinkTarget || null,
+    });
+  } else if (operation.kind === 'tree.rename' || operation.kind === 'tree.move') {
+    const source = operationPath(workspace, before, operation.nodeId);
+    actions.push({
+      type: 'move',
+      nodeId: operation.nodeId,
+      source,
+      target: operationPath(workspace, after, operation.nodeId),
+      sourceParentNodeId: before.get(operation.nodeId)?.parentId || workspace.id,
+      targetParentNodeId: after.get(operation.nodeId)?.parentId || workspace.id,
+      identity: treeMaterialization.identity(source, { deep: false }),
+    });
+  } else if (operation.kind === 'tree.trash') {
+    const source = operationPath(workspace, before, operation.nodeId);
+    actions.push({
+      type: 'move',
+      nodeId: operation.nodeId,
+      source,
+      target: trashPath(workspace.id, operation.nodeId, workspace.path),
+      sourceParentNodeId: before.get(operation.nodeId)?.parentId || workspace.id,
+      targetParentNodeId: null,
+      identity: treeMaterialization.identity(source, { deep: false }),
+    });
+  } else if (operation.kind === 'tree.restore') {
+    const source = physicalNodePath(workspace, before, operation.nodeId);
+    if (!source || !pathExists(source)) {
+      throw invalid(`restore source does not exist for ${operation.nodeId}`, 409);
+    }
+    actions.push({
+      type: 'move',
+      nodeId: operation.nodeId,
+      source,
+      target: operationPath(workspace, after, operation.nodeId),
+      sourceParentNodeId: physicalParentNodeId(workspace, before, operation.nodeId),
+      targetParentNodeId: after.get(operation.nodeId)?.parentId || workspace.id,
+      identity: treeMaterialization.identity(source, { deep: false }),
+    });
+  } else if (operation.kind === 'tree.purge') {
+    // One trashed component has one physical carrier. Address the requested
+    // subtree through its shared locator, then add only independently trashed
+    // descendant component roots. This retires each physical component once:
+    // never one guessed UUID trash slot per logical descendant.
+    const logicalRoots = new Set([operation.nodeId]);
+    for (const node of before.values()) {
+      if (
+        node.id === operation.nodeId
+        || !hasAncestorInSet(node, before, new Set([operation.nodeId]))
+      ) continue;
+      const componentRoot = trashComponentRoot(before, node.id);
+      if (componentRoot?.id === node.id) logicalRoots.add(node.id);
+    }
+    for (const nodeId of logicalRoots) {
+      const source = physicalNodePath(workspace, before, nodeId);
+      if (!source || !pathExists(source)) continue;
+      const precondition = treeMaterialization.removalPrecondition(source);
+      const recovery = retainedRecoveryTarget(
+        workspace,
+        before,
+        nodeId,
+        input.envelope.mutationId,
+      );
+      actions.push({
+        type: 'remove',
+        nodeId,
+        source,
+        sourceParentNodeId: physicalParentNodeId(
+          workspace,
+          before,
+          nodeId,
+        ),
+        // Writer-held bytes cannot return below a parent that remains
+        // trashed. The immutable plan names one deterministic recovery
+        // location below the nearest live ancestor before removal begins.
+        retainTarget: recovery.path,
+        retainTargetParentNodeId: recovery.parentNodeId,
+        retainTargetExclusive: true,
+        identity: precondition.identity,
+        retirement: precondition.retirement,
+      });
+    }
+  }
+  const rollbackBindings = completeOperationBindings(workspace, before);
+  const bindingByNodeId = new Map(
+    rollbackBindings.map((binding) => [binding.nodeId, binding]),
+  );
+  const createdNodeIds = new Set(
+    actions
+      .filter((action) => action.type === 'create')
+      .map((action) => action.nodeId),
+  );
+  const controlRoots = new Set();
+  const isWorkspacePath = (candidate) => (
+    candidate === workspace.path
+    || candidate.startsWith(`${workspace.path}${path.sep}`)
+  );
+  for (const action of actions) {
+    if (action.source) {
+      const sourceParent = path.dirname(action.source);
+      if (!isWorkspacePath(sourceParent)) controlRoots.add(sourceParent);
+      const sourceParentIdentity = (
+        action.sourceParentNodeId
+        && bindingByNodeId.get(action.sourceParentNodeId)?.identity
+      ) || treeMaterialization.identity(sourceParent, { deep: false });
+      if (sourceParentIdentity.kind !== 'folder') {
+        throw invalid(`workspace tree source parent is not a folder: ${sourceParent}`, 409);
+      }
+      action.sourceParentIdentity = sourceParentIdentity;
+    }
+    if (action.target) {
+      const targetParent = path.dirname(action.target);
+      if (!isWorkspacePath(targetParent)) {
+        treeMaterialization.ensureDurableDirectory(targetParent);
+        controlRoots.add(targetParent);
+      }
+      if (
+        action.targetParentNodeId
+        && createdNodeIds.has(action.targetParentNodeId)
+      ) {
+        action.targetParentIdentity = null;
+        continue;
+      }
+      const targetParentIdentity = (
+        action.targetParentNodeId
+        && bindingByNodeId.get(action.targetParentNodeId)?.identity
+      ) || treeMaterialization.identity(targetParent, { deep: false });
+      if (targetParentIdentity.kind !== 'folder') {
+        throw invalid(`workspace tree target parent is not a folder: ${targetParent}`, 409);
+      }
+      action.targetParentIdentity = targetParentIdentity;
+    }
+  }
+  return {
+    contract: 'workspace-tree-operation-materialization@1',
+    resourceId: workspace.id,
+    mutationId: String(input.envelope.mutationId),
+    channelId: options.channelId || `resource:${workspace.id}`,
+    version: Number(input.version),
+    authorityEpoch: Number(input.envelope.authorityEpoch),
+    rootPath: workspace.path,
+    rootIdentity: {
+      kind: 'folder',
+      dev: String(verifiedRootIdentity.dev ?? verifiedRootIdentity.deviceId),
+      ino: String(verifiedRootIdentity.ino ?? verifiedRootIdentity.inode),
+    },
+    controlRoots: Array.from(controlRoots).sort(),
+    rollbackBindings,
+    operation,
+    beforeNodes: Array.from(before.values()),
+    afterNodes: Array.from(after.values()),
+    officialAfterNodes: officialAfter ? Array.from(officialAfter.values()) : null,
+    actions,
+    event: {
+      resource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
+      op: 'update',
+      id: operation.nodeId,
+      patch: operation,
+      sharedResourceId: workspace.id,
+      source: options.source || 'workspace-tree:cloud',
+      ...(options.resourceVersion === false
+        ? {}
+        : { resourceVersion: Number(input.version) }),
+    },
+  };
+}
+
+function localTreeOperationPlan(
+  workspace,
+  before,
+  after,
+  operation,
+  mutation,
+  options = {},
+) {
+  return {
+    ...physicalOperationPlan(
+      workspace,
+      before,
+      after,
+      operation,
+      {
+        envelope: {
+          mutationId: mutation.mutationId,
+          authorityEpoch: mutation.authorityEpoch || 1,
+        },
+        version: mutation.baseCloudVersion || 0,
+      },
+      null,
+      {
+        channelId: mutation.channelId,
+        diskAlreadyApplied: options.diskAlreadyApplied === true,
+        source: options.source || 'workspace-tree:local',
+        resourceVersion: false,
+        rootIdentity: options.rootIdentity,
+      },
+    ),
+    origin: 'local',
+  };
+}
+
+function planNodes(plan, key) {
+  return new Map((plan[key] || []).map((node) => [node.id, node]));
+}
+
+function deterministicUuid(seed) {
+  const bytes = crypto.createHash('sha256').update(seed).digest().subarray(0, 16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-`
+    + `${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function retentionMutationId(plan, nodeId, operationKind, outputId = '') {
+  return `mut_${crypto.createHash('sha256')
+    .update(
+      `workspace-tree-retained@1\0${plan.resourceId}\0`
+      + `${plan.snapshotChecksum || plan.mutationId}\0${nodeId}\0`
+      + `${operationKind}\0${outputId}`,
+    )
+    .digest('hex')}`;
+}
+
+function treePlanHoldScope(plan) {
+  const operationPlan = (
+    plan.contract === 'workspace-tree-operation-materialization@1'
+  );
+  return {
+    ownerKind: 'recovery-plan',
+    ownerId: operationPlan
+      ? `operation:${plan.mutationId}`
+      : `snapshot:${plan.snapshotVersion}`,
+  };
+}
+
+function clearTreePlanHoldInTransaction(plan, database) {
+  return require('./store').replaceTreeObservationInTransaction(
+    plan.resourceId,
+    [],
+    {
+      database,
+      ...treePlanHoldScope(plan),
+      source: 'workspace-tree:recovery-plan-settled',
+    },
+  );
+}
+
+function holdRetainedSuccessors(
+  plan,
+  reason,
+  operations,
+  database,
+  paths = [],
+) {
+  const materialization = require('./tree-materialization');
+  const held = plan.contract === 'workspace-tree-operation-materialization@1'
+    ? materialization.getOperation(plan.resourceId, plan.mutationId, database)
+    : materialization.get(plan.resourceId, plan.snapshotVersion, database);
+  if (!held) {
+    throw invalid('workspace tree retained-byte hold lost its durable plan', 409);
+  }
+  const hold = {
+    reason,
+    operations,
+    paths: Array.from(new Set(paths)).sort(),
+  };
+  const field = reason === 'forbidden' ? 'permissionHold' : 'retainedHold';
+  const nextPlan = { ...held.plan, [field]: hold };
+  require('./store').commitCompletedTreeObservation(
+    plan.resourceId,
+    [{ reason, paths: hold.paths }],
+    {
+      database,
+      ...treePlanHoldScope(plan),
+      source: 'workspace-tree:recovery-plan-hold',
+      mutate() {
+        if (JSON.stringify(held.plan[field] || null) === JSON.stringify(hold)) {
+          return;
+        }
+        if (held.state === 'committed') {
+          materialization.updateCommittedPlan(held, nextPlan, database);
+        } else if (held.state === 'prepared') {
+          materialization.replacePreparedOperation(held, nextPlan, database);
+        } else {
+          materialization.updateUncommittedPlan(held, nextPlan, database);
+        }
+      },
+    },
+  );
+  throw Object.assign(
+    new Error(`workspace tree retained bytes are held: ${reason}`),
+    {
+      code: 'WORKSPACE_TREE_RETRY_PENDING',
+      reason,
+      statusCode: 409,
+      paths: hold.paths,
+    },
+  );
+}
+
+function holdClassifiedPlanRetry(plan, error, database) {
+  if (error?.code !== 'WORKSPACE_TREE_RETRY_PENDING') throw error;
+  const paths = Array.from(new Set(
+    (Array.isArray(error.paths) ? error.paths : [])
+      .filter(Boolean)
+      .map((target) => (
+        path.isAbsolute(target)
+          ? path.relative(plan.rootPath, target)
+          : target
+      )),
+  )).sort();
+  holdRetainedSuccessors(
+    plan,
+    error.reason || 'materialization-retry-pending',
+    [],
+    database,
+    paths,
+  );
+}
+
+/**
+ * Physical cleanup can discover a writer that was already holding an inode
+ * when an official removal staged it. Choose and persist the UUID attached to
+ * each exact retained identity before issuing any birth. The mutation journal
+ * bridges the only remaining crash window (birth committed, plan not yet
+ * marked born), so recovery never re-applies an obsolete receipt to a newer
+ * object at the same spelling.
+ */
+function retainRemovalSuccessors(plan, retained, database, options = {}) {
+  const before = planNodes(plan, 'beforeNodes');
+  const outputs = Array.from(new Map(
+    retained.flatMap((item) => (
+      Array.isArray(item.retainedOutputs) ? item.retainedOutputs : []
+    )).map((output) => [output.outputId, output]),
+  ).values()).sort((left, right) => (
+    left.path.split(path.sep).length - right.path.split(path.sep).length
+    || left.path.localeCompare(right.path)
+    || left.outputId.localeCompare(right.outputId)
+  ));
+  const tree = localTree();
+  const attempted = [];
+  const materialization = require('./tree-materialization');
+  let currentPlan = plan;
+
+  const heldPlan = () => {
+    const held = currentPlan.contract === 'workspace-tree-operation-materialization@1'
+      ? materialization.getOperation(
+          currentPlan.resourceId,
+          currentPlan.mutationId,
+          database,
+        )
+      : materialization.get(
+          currentPlan.resourceId,
+          currentPlan.snapshotVersion,
+          database,
+        );
+    if (!held) {
+      throw invalid('workspace tree retained adoption lost its committed plan', 409);
+    }
+    return held;
+  };
+  const persistAdoptions = (adoptions) => {
+    const held = heldPlan();
+    const nextPlan = {
+      ...held.plan,
+      retainedOutputAdoptions: [...adoptions].sort((left, right) => (
+        left.outputId.localeCompare(right.outputId)
+      )),
+    };
+    if (JSON.stringify(held.plan) !== JSON.stringify(nextPlan)) {
+      currentPlan = (
+        held.state === 'committed'
+          ? materialization.updateCommittedPlan(held, nextPlan, database)
+          : materialization.updateUncommittedPlan(held, nextPlan, database)
+      ).plan;
+    } else {
+      currentPlan = held.plan;
+    }
+    return currentPlan;
+  };
+  const oldNodeForOutput = (output) => {
+    if (output.provenance !== 'carried-source') return null;
+    if (!Object.prototype.hasOwnProperty.call(output, 'ownerNodeId')) {
+      holdChanged('retained-owner-unresolved', [output.path], [output]);
+    }
+    if (output.ownerNodeId == null) return null;
+    const owner = before.get(output.ownerNodeId);
+    if (!owner || owner.kind !== output.identity.kind) {
+      holdChanged('retained-owner-unresolved', [output.path], [output]);
+    }
+    return owner;
+  };
+  const expectedAdoption = (output, currentPath = output.path) => {
+    const oldNode = oldNodeForOutput(output);
+    const reuseOldId = (
+      output.provenance === 'carried-source'
+      && options.reuseIds !== false
+      && oldNode
+      && oldNode.kind === output.identity.kind
+    );
+    const nodeId = reuseOldId
+      ? oldNode.id
+      : deterministicUuid(
+        `workspace-tree-retained-output@1\0${plan.resourceId}\0`
+        + `${plan.snapshotChecksum || plan.mutationId}\0${output.outputId}\0`
+        + `${oldNode?.id || ''}\0${output.identity.kind}`,
+      );
+    return {
+      outputId: output.outputId,
+      path: currentPath,
+      nodeId,
+      oldNodeId: oldNode?.id || null,
+      reuseOldId: Boolean(reuseOldId),
+      identity: {
+        kind: output.identity.kind,
+        deviceId: String(output.identity.dev),
+        inode: String(output.identity.ino),
+      },
+    };
+  };
+  const birthRow = (adoption) => {
+    if (!adoption.mutationId) return null;
+    return database.prepare(`
+      SELECT mutation_state, materialized_at
+      FROM mutation_journal
+      WHERE local_resource = ? AND mutation_id = ?
+    `).get(
+      `${TREE_RESOURCE_PREFIX}${currentPlan.resourceId}`,
+      adoption.mutationId,
+    ) || null;
+  };
+  const birthCompleted = (adoption) => {
+    if (adoption.born === true) return true;
+    return birthRow(adoption)?.materialized_at != null;
+  };
+  const adoptionMap = () => new Map(
+    (currentPlan.retainedOutputAdoptions || [])
+      .map((adoption) => [adoption.outputId, adoption]),
+  );
+  const persistAdoption = (adoption) => {
+    const byId = adoptionMap();
+    byId.set(adoption.outputId, adoption);
+    persistAdoptions(Array.from(byId.values()));
+    return adoptionMap().get(adoption.outputId);
+  };
+  const holdChanged = (reason, heldPaths, operations = outputs) => {
+    const relativePaths = Array.from(new Set(heldPaths))
+      .map((target) => path.relative(currentPlan.rootPath, target))
+      .sort();
+    holdRetainedSuccessors(
+      currentPlan,
+      reason,
+      operations,
+      database,
+      relativePaths,
+    );
+  };
+  const planBirth = (adoption, output) => {
+    if (adoption.operation && adoption.mutationId) return adoption;
+    const target = adoption.path;
+    const parentPath = path.dirname(target);
+    const parentBinding = physicalBindingAtPath(parentPath, database);
+    if (!parentBinding || parentBinding.kind !== 'folder') {
+      holdChanged('retained-parent-unavailable', [parentPath]);
+    }
+    const oldNode = adoption.oldNodeId
+      ? before.get(adoption.oldNodeId)
+      : null;
+    const current = adoption.reuseOldId
+      ? database.prepare('SELECT * FROM workspace_nodes WHERE id = ?')
+          .get(adoption.nodeId)
+      : null;
+    const operation = adoption.reuseOldId
+      && current
+      && current.trashed_at
+      && !current.purged_at
+      ? {
+          kind: 'tree.restore',
+          workspaceId: currentPlan.resourceId,
+          nodeId: adoption.nodeId,
+          parentId: parentBinding.node.id,
+          name: path.basename(target),
+          changedAt: oldNode.updatedAt || oldNode.createdAt,
+        }
+      : {
+          kind: 'tree.create',
+          workspaceId: currentPlan.resourceId,
+          nodeId: adoption.nodeId,
+          parentId: parentBinding.node.id,
+          nodeKind: adoption.identity.kind,
+          name: path.basename(target),
+          symlinkTarget: adoption.identity.kind === 'symlink'
+            ? fs.readlinkSync(target)
+            : undefined,
+          createdAt: adoption.reuseOldId ? oldNode.createdAt : undefined,
+          changedAt: oldNode?.updatedAt || oldNode?.createdAt,
+        };
+    return persistAdoption({
+      ...adoption,
+      mutationId: retentionMutationId(
+        currentPlan,
+        adoption.nodeId,
+        operation.kind,
+        output.outputId,
+      ),
+      operation,
+      parentIdentity: {
+        path: parentPath,
+        kind: parentBinding.kind,
+        deviceId: parentBinding.deviceId,
+        inode: parentBinding.inode,
+      },
+    });
+  };
+  const capture = (output) => {
+    let adoption = adoptionMap().get(output.outputId);
+    if (!adoption) {
+      throw invalid(
+        `retained tree output ${output.outputId} has no durable adoption`,
+        409,
+      );
+    }
+    if (birthCompleted(adoption)) {
+      if (adoption.born !== true) {
+        adoption = persistAdoption({
+          ...adoption,
+          born: true,
+        });
+      }
+      return;
+    }
+    if (adoption.delegatedToObserver === true) return;
+    const atPath = tree.nodeForPath(adoption.path, { database });
+    const owner = heldPlan();
+    if (owner.state !== 'committed') {
+      // A superseded snapshot is returning the prior floor, whose UUID rows
+      // are already durable. Once the exact retained identities and their
+      // current paths are sealed above, reconciliation—not a new create—is
+      // the only legal way to rebind that floor and classify extra occupants.
+      persistAdoption({
+        ...adoption,
+        delegatedToObserver: true,
+      });
+      return;
+    }
+    if (atPath && !adoption.mutationId) {
+      if (adoption.reuseOldId && atPath.node.id !== adoption.nodeId) {
+        holdChanged(
+          'retained-uuid-mismatch',
+          [adoption.path],
+          attempted.length ? attempted : outputs,
+        );
+      }
+      // This spelling already has a durable logical owner. The ordinary
+      // observer is the only component allowed to decide whether the exact
+      // retained identity is that owner's refresh or a fresh successor.
+      persistAdoption({
+        ...adoption,
+        delegatedToObserver: true,
+      });
+      return;
+    }
+    adoption = planBirth(adoption, output);
+    if (atPath && atPath.node.id !== adoption.nodeId) {
+      holdChanged(
+        'retained-uuid-mismatch',
+        [adoption.path],
+        attempted.length ? attempted : outputs,
+      );
+    }
+    if (typeof options.testHooks?.beforeRetainedOutputBirth === 'function') {
+      options.testHooks.beforeRetainedOutputBirth(output, adoption);
+    }
+    attempted.push(adoption.operation);
+    tree.commitTreeOperation(adoption.operation, {
+      database,
+      diskAlreadyApplied: true,
+      source: 'workspace-tree:retained-after-apply',
+      mutationId: adoption.mutationId,
+      expectedDiskIdentity: {
+        path: adoption.path,
+        ...adoption.identity,
+      },
+      expectedParentDiskIdentity: adoption.parentIdentity,
+    });
+    persistAdoption({
+      ...adoption,
+      born: true,
+    });
+  };
+  try {
+    const changedOutputs = [];
+    const ambiguousOutputs = [];
+    const existingAdoptions = adoptionMap();
+    const pendingOutputs = outputs.filter((output) => {
+      const adoption = existingAdoptions.get(output.outputId);
+      return !adoption || (
+        adoption.delegatedToObserver !== true
+        && !birthCompleted(adoption)
+      );
+    });
+    const locations = materialization.locateOperationBindings(
+      currentPlan,
+      pendingOutputs.map((output) => ({
+        nodeId: output.outputId,
+        path: output.path,
+        identity: output.identity,
+      })),
+    );
+    const currentPaths = new Map();
+    for (const output of pendingOutputs) {
+      const candidates = locations.get(output.outputId) || [];
+      if (candidates.length === 0) {
+        changedOutputs.push(output.path);
+        continue;
+      }
+      if (candidates.length > 1) {
+        ambiguousOutputs.push(...candidates);
+        continue;
+      }
+      currentPaths.set(output.outputId, candidates[0]);
+    }
+    if (changedOutputs.length || ambiguousOutputs.length) {
+      const reason = ambiguousOutputs.length
+        ? 'ambiguous-physical-alias'
+        : 'retained-output-changed';
+      holdChanged(
+        reason,
+        ambiguousOutputs.length ? ambiguousOutputs : changedOutputs,
+      );
+    }
+
+    const adoptions = adoptionMap();
+    for (const output of outputs) {
+      let existing = adoptions.get(output.outputId);
+      const currentPath = currentPaths.get(output.outputId)
+        || existing?.path
+        || output.path;
+      const expected = expectedAdoption(output, currentPath);
+      if (existing) {
+        if (
+          existing.path !== currentPath
+          && (existing.operation || existing.mutationId)
+        ) {
+          // A planned envelope is immutable only after the journal has
+          // accepted it. Before that point the exact retained object may move
+          // again; replace the plan-local envelope and let planBirth derive
+          // the same UUID at its verified current parent.
+          if (birthRow(existing)) {
+            holdChanged('retained-output-changed', [existing.path, currentPath]);
+          }
+          existing = {
+            ...existing,
+            path: currentPath,
+            operation: undefined,
+            mutationId: undefined,
+            parentIdentity: undefined,
+          };
+          adoptions.set(output.outputId, existing);
+        }
+        const immutable = {
+          outputId: existing.outputId,
+          path: currentPath,
+          nodeId: existing.nodeId,
+          oldNodeId: existing.oldNodeId || null,
+          reuseOldId: existing.reuseOldId === true,
+          identity: existing.identity,
+        };
+        if (JSON.stringify(immutable) !== JSON.stringify(expected)) {
+          throw invalid(
+            `retained tree output ${output.outputId} changed its durable adoption`,
+            409,
+          );
+        }
+        if (existing.path !== currentPath) {
+          adoptions.set(output.outputId, {
+            ...existing,
+            path: currentPath,
+          });
+        }
+      } else {
+        adoptions.set(output.outputId, expected);
+      }
+    }
+    persistAdoptions(Array.from(adoptions.values()));
+
+    for (const output of outputs) capture(output);
+
+    const completeDelegatedAdoptions = () => {
+      const delegated = Array.from(adoptionMap().values())
+        .filter((adoption) => (
+          adoption.delegatedToObserver === true
+          && adoption.disposition == null
+        ));
+      if (!delegated.length) return;
+      const locations = materialization.locateOperationBindings(
+        currentPlan,
+        delegated.map((adoption) => ({
+          nodeId: adoption.outputId,
+          path: adoption.path,
+          identity: {
+            kind: adoption.identity.kind,
+            dev: adoption.identity.deviceId,
+            ino: adoption.identity.inode,
+          },
+        })),
+      );
+      const completed = adoptionMap();
+      for (const adoption of delegated) {
+        const candidates = locations.get(adoption.outputId) || [];
+        if (candidates.length > 1) {
+          holdChanged('ambiguous-physical-alias', candidates);
+        }
+        if (candidates.length === 1) {
+          const binding = physicalBindingAtPath(candidates[0], database);
+          if (!binding) {
+            holdChanged('retained-birth-pending', candidates);
+          }
+          completed.set(adoption.outputId, {
+            ...adoption,
+            path: candidates[0],
+            born: true,
+            actualNodeId: binding.node.id,
+            disposition: 'active',
+          });
+          continue;
+        }
+        const prior = adoption.reuseOldId
+          ? database.prepare(`
+              SELECT trashed_at, purged_at
+              FROM workspace_nodes
+              WHERE workspace_id = ? AND id = ?
+            `).get(currentPlan.resourceId, adoption.nodeId)
+          : null;
+        completed.set(adoption.outputId, {
+          ...adoption,
+          actualNodeId: prior ? adoption.nodeId : null,
+          disposition: prior?.purged_at
+            ? 'purged'
+            : prior?.trashed_at
+              ? 'trashed'
+              : 'absent',
+        });
+      }
+      persistAdoptions(Array.from(completed.values()));
+    };
+
+    settleRetainedOutputBindings(currentPlan, database, {
+      source: 'workspace-tree:retained-after-apply',
+      testHooks: options.testHooks,
+      afterSettled: completeDelegatedAdoptions,
+      hold(reason, paths, operations) {
+        holdRetainedSuccessors(
+          currentPlan,
+          reason,
+          operations.length ? operations : outputs,
+          database,
+          paths,
+        );
+      },
+    });
+  } catch (error) {
+    if (error?.code === 'WORKSPACE_TREE_PHYSICAL_BINDING_CHANGED') {
+      holdChanged(
+        'retained-output-changed',
+        outputs.map((output) => output.path),
+        attempted.length ? attempted : outputs,
+      );
+    }
+    if (error?.statusCode !== 403) throw error;
+    holdRetainedSuccessors(
+      currentPlan,
+      'forbidden',
+      attempted,
+      database,
+      outputs.map((output) => path.relative(currentPlan.rootPath, output.path)),
+    );
+  }
+}
+
+function finishTreeSnapshotPlan(held, database, testHooks = {}) {
+  let observationCommit = null;
+  let finished;
+  try {
+    finished = require('./tree-materialization').finish(held, database, {
+      afterOutputReceipt(outputs, plan) {
+        if (typeof testHooks.afterRetainedOutputReceipt === 'function') {
+          testHooks.afterRetainedOutputReceipt(outputs, plan);
+        }
+        if (testHooks.crashAfterRetainedOutputReceipt === true) {
+          throw new Error('simulated workspace tree crash after retained output receipt');
+        }
+      },
+      afterOutputMove(outputs, plan) {
+        if (typeof testHooks.afterRetainedOutputMove === 'function') {
+          testHooks.afterRetainedOutputMove(outputs, plan);
+        }
+        if (testHooks.crashAfterRetainedOutputMove === true) {
+          throw new Error('simulated workspace tree crash after retained output move');
+        }
+      },
+      retain(retained, plan) {
+        retainRemovalSuccessors(plan, retained, database, {
+          reuseIds: true,
+          testHooks,
+        });
+      },
+      afterRetain() {
+        if (testHooks.crashAfterRetainedBirths === true) {
+          throw new Error('simulated workspace tree crash after retained births');
+        }
+      },
+      finalizeControlState(finalPlan) {
+        observationCommit = clearTreePlanHoldInTransaction(finalPlan, database);
+      },
+    });
+  } catch (error) {
+    holdClassifiedPlanRetry(held.plan, error, database);
+  }
+  require('./store').publishTreeObservationCommit(observationCommit);
+  return finished;
+}
+
+function settlePurgeRetentionTargets(held, database) {
+  const materialization = require('./tree-materialization');
+  let current = materialization.getOperation(
+    held.resourceId,
+    held.mutationId,
+    database,
+  );
+  if (
+    !current
+    || current.state !== 'committed'
+    || current.plan.operation?.kind !== 'tree.purge'
+  ) {
+    return current || held;
+  }
+
+  // A committed physical projection is the floor. Before its cleanup returns
+  // writer-held bytes, capture any local parent moves or replacement entries
+  // that appeared while the runtime was down. The ordinary observer already
+  // has the complete UUID/device/inode rules for that classification.
+  const observed = localTree().reconcileWorkspaceTree(current.plan.resourceId, {
+    database,
+    skipRecovery: true,
+    source: 'workspace-tree:retained-parent-before-cleanup',
+  });
+  if (observed.held?.length) {
+    holdRetainedSuccessors(
+      current.plan,
+      observed.held[0]?.reason || 'retained-parent-pending',
+      observed.held.map((item) => item.operation || item),
+      database,
+    );
+  }
+
+  current = materialization.getOperation(
+    held.resourceId,
+    held.mutationId,
+    database,
+  );
+  const workspace = workspaceRow(current.plan.resourceId, database);
+  const nodes = new Map(localTree().listWorkspaceNodes(workspace.id, {
+    database,
+    includeTrashed: true,
+    includePurged: true,
+  }).map((node) => [node.id, node]));
+  const before = planNodes(current.plan, 'beforeNodes');
+  const bindings = new Map(
+    (current.plan.rollbackBindings || [])
+      .map((binding) => [binding.nodeId, binding]),
+  );
+  let changed = false;
+  const actions = current.plan.actions.map((action) => {
+    if (action.type !== 'remove' || !action.retainTargetParentNodeId) {
+      return action;
+    }
+    let parentId = action.retainTargetParentNodeId;
+    let resolved = null;
+    while (parentId) {
+      const parent = nodes.get(parentId);
+      if (parent && activeNode(parent)) {
+        const parentPath = operationPath(workspace, nodes, parentId);
+        const expected = parentId === workspace.id
+          ? current.plan.rootIdentity
+          : bindings.get(parentId)?.identity;
+        if (expected && pathExists(parentPath)) {
+          const actual = materialization.identity(parentPath, { deep: false });
+          if (
+            actual.kind === 'folder'
+            && actual.dev === expected.dev
+            && actual.ino === expected.ino
+          ) {
+            resolved = {
+              parentId,
+              parentPath,
+              parentIdentity: actual,
+            };
+            break;
+          }
+        }
+      }
+      if (parentId === workspace.id) break;
+      parentId = before.get(parentId)?.parentId || null;
+    }
+    if (!resolved) {
+      holdRetainedSuccessors(
+        current.plan,
+        'retained-parent-unavailable',
+        [],
+        database,
+        [path.relative(current.plan.rootPath, action.retainTarget)],
+      );
+    }
+    const retainTarget = path.join(
+      resolved.parentPath,
+      path.basename(action.retainTarget),
+    );
+    if (
+      retainTarget !== action.retainTarget
+      || resolved.parentId !== action.retainTargetParentNodeId
+      || JSON.stringify(resolved.parentIdentity)
+        !== JSON.stringify(action.retainTargetParentIdentity || null)
+    ) {
+      changed = true;
+    }
+    return {
+      ...action,
+      retainTarget,
+      retainTargetParentNodeId: resolved.parentId,
+      retainTargetParentIdentity: resolved.parentIdentity,
+    };
+  });
+  if (!changed) return current;
+  return materialization.updateCommittedPlan(
+    current,
+    { ...current.plan, actions },
+    database,
+  );
+}
+
+function captureRetainedPurgeOutputs(plan, retained, database) {
+  const observed = localTree().reconcileWorkspaceTree(plan.resourceId, {
+    database,
+    skipRecovery: true,
+    source: 'workspace-tree:retained-after-purge',
+  });
+  if (observed.held?.length) {
+    holdRetainedSuccessors(
+      plan,
+      observed.held[0]?.reason || 'retained-birth-pending',
+      observed.held.map((item) => item.operation || item),
+      database,
+    );
+  }
+  for (const item of retained) {
+    for (const retainedPath of item.retainedPaths || []) {
+      if (
+        pathExists(retainedPath)
+        && !localTree().nodeForPath(retainedPath, { database })
+      ) {
+        holdRetainedSuccessors(
+          plan,
+          'retained-birth-pending',
+          [],
+          database,
+          [path.relative(plan.rootPath, retainedPath)],
+        );
+      }
+    }
+  }
+}
+
+function finishTreeOperationPlan(held, database, testHooks = {}) {
+  const materialization = require('./tree-materialization');
+  let settled = held;
+  let observationCommit = null;
+  try {
+    settled = settlePurgeRetentionTargets(held, database);
+    const finished = materialization.finishOperation(settled, database, {
+      afterOutputReceipt(outputs, plan) {
+        if (typeof testHooks.afterRetainedOutputReceipt === 'function') {
+          testHooks.afterRetainedOutputReceipt(outputs, plan);
+        }
+        if (testHooks.crashAfterRetainedOutputReceipt === true) {
+          throw new Error('simulated workspace tree crash after retained output receipt');
+        }
+      },
+      afterOutputMove(outputs, plan) {
+        if (typeof testHooks.afterRetainedOutputMove === 'function') {
+          testHooks.afterRetainedOutputMove(outputs, plan);
+        }
+        if (testHooks.crashAfterRetainedOutputMove === true) {
+          throw new Error('simulated workspace tree crash after retained output move');
+        }
+      },
+      retain(retained, plan) {
+        if (plan.operation?.kind === 'tree.purge') {
+          captureRetainedPurgeOutputs(plan, retained, database);
+        }
+      },
+      afterRetain() {
+        if (testHooks.crashAfterRetainedBirths === true) {
+          throw new Error('simulated workspace tree crash after retained births');
+        }
+      },
+      finalizeControlState(finalPlan) {
+        materialization.clearOperationSuccessors(finalPlan, database);
+        observationCommit = clearTreePlanHoldInTransaction(
+          finalPlan,
+          database,
+        );
+      },
+    });
+    require('./store').publishTreeObservationCommit(observationCommit);
+    return finished;
+  } catch (error) {
+    if (error?.code === 'WORKSPACE_TREE_PARENT_RACE') {
+      holdRetainedSuccessors(
+        settled.plan,
+        'retained-parent-moved',
+        [],
+        database,
+      );
+    }
+    const current = materialization.getOperation(
+      held.resourceId,
+      held.mutationId,
+      database,
+    );
+    holdClassifiedPlanRetry(current?.plan || settled.plan, error, database);
+  }
+}
+
+function projectStoredTreeOperation(held, database) {
+  const before = planNodes(held.plan, 'beforeNodes');
+  const after = planNodes(held.plan, 'afterNodes');
+  const changedPaths = persistNodes(
+    database,
+    before,
+    after,
+    held.plan.resourceId,
+  );
+  if (Array.isArray(held.plan.officialAfterNodes)) {
+    require('./tree/floor').write({
+      schemaVersion: 1,
+      workspaceId: held.plan.resourceId,
+      version: held.plan.version,
+      nodes: new Map(held.plan.officialAfterNodes.map((node) => [node.id, node])),
+    }, held.plan.authorityEpoch, { database });
+  }
+  if (changedPaths.length) require('../state/docs').rebindNodePaths(changedPaths);
+  return changedPaths;
+}
+
+function causalSuccessorMutationId(plan, operation, index) {
+  return `mut_${crypto.createHash('sha256')
+    .update(
+      `workspace-tree-causal-successor@1\0${plan.resourceId}\0`
+      + `${plan.mutationId}\0${index}\0${operation.kind}\0`
+      + `${operation.nodeId}\0${operation.parentId || ''}\0${operation.name || ''}`,
+    )
+    .digest('hex')}`;
+}
+
+function holdCarriedSuccessorsForPermission(plan, operations, database) {
+  holdRetainedSuccessors(plan, 'forbidden', operations, database);
+}
+
+function adoptCarriedCreateBindings(plan, database, testHooks = {}) {
+  let bindings = Array.isArray(plan.carriedCreates)
+    ? [...plan.carriedCreates]
+    : [];
+  let deletionBindings = Array.isArray(plan.carriedCreateDeletions)
+    ? [...plan.carriedCreateDeletions]
+    : [];
+  let causalSuccessors = Array.isArray(plan.causalSuccessors)
+    ? [...plan.causalSuccessors]
+    : [];
+  if (!bindings.length && !deletionBindings.length) return [];
+  const workspace = workspaceRow(plan.resourceId, database);
+  if (!workspace) {
+    throw invalid('workspace tree carried create lost its workspace', 409);
+  }
+  const materialization = require('./tree-materialization');
+  const intended = planNodes(plan, 'afterNodes');
+  const persistCarriedState = () => {
+    const held = materialization.getOperation(
+      plan.resourceId,
+      plan.mutationId,
+      database,
+    );
+    if (!held || held.state !== 'prepared') {
+      throw invalid(
+        `workspace tree carried state lost operation ${plan.mutationId}`,
+        409,
+      );
+    }
+    const nextPlan = {
+      ...held.plan,
+      carriedCreates: bindings,
+      carriedCreateDeletions: deletionBindings,
+      causalSuccessors,
+    };
+    if (JSON.stringify(held.plan) !== JSON.stringify(nextPlan)) {
+      materialization.replacePreparedOperation(held, nextPlan, database);
+    }
+    plan = nextPlan;
+  };
+
+  let locations = bindings.length
+    ? materialization.locateOperationBindings(plan, bindings)
+    : new Map();
+  let bindingsChanged = false;
+  const refreshedBindings = [];
+  for (const binding of bindings) {
+    const candidates = locations.get(binding.nodeId) || [];
+    if (candidates.length !== 0) {
+      refreshedBindings.push(binding);
+      continue;
+    }
+    let successorIdentity = null;
+    try {
+      successorIdentity = materialization.identity(
+        binding.path,
+        { deep: false },
+      );
+    } catch (error) {
+      if (!isPathAbsentError(error)) throw error;
+    }
+    bindingsChanged = true;
+    if (
+      intended.get(binding.nodeId)?.kind === 'file'
+      && successorIdentity?.kind === 'file'
+    ) {
+      refreshedBindings.push({
+        ...binding,
+        identity: successorIdentity,
+        refreshAtSamePath: true,
+      });
+    } else if (
+      !deletionBindings.some((entry) => entry.nodeId === binding.nodeId)
+    ) {
+      deletionBindings.push({
+        nodeId: binding.nodeId,
+        identity: binding.identity,
+      });
+    }
+  }
+  if (bindingsChanged) {
+    bindings = refreshedBindings;
+    persistCarriedState();
+    locations = bindings.length
+      ? materialization.locateOperationBindings(plan, bindings)
+      : new Map();
+  }
+  const resolved = bindings.map((binding) => {
+    const candidates = locations.get(binding.nodeId) || [];
+    if (candidates.length !== 1) {
+      holdRetainedSuccessors(
+        plan,
+        candidates.length > 1
+          ? 'ambiguous-physical-alias'
+          : 'retained-output-changed',
+        [],
+        database,
+        (candidates.length ? candidates : [binding.path])
+          .map((target) => path.relative(plan.rootPath, target)),
+      );
+    }
+    const relativePath = relativeWorkspacePath(workspace.path, candidates[0]);
+    if (!relativePath || !shouldSync(relativePath)) {
+      throw invalid(
+        `workspace tree carried create ${binding.nodeId} left its visible workspace`,
+        409,
+      );
+    }
+    return {
+      ...binding,
+      path: candidates[0],
+      relativePath,
+    };
+  }).sort((left, right) => (
+    left.relativePath.split('/').length - right.relativePath.split('/').length
+    || left.relativePath.localeCompare(right.relativePath)
+  ));
+  const resolvedById = new Map(
+    resolved.map((binding) => [binding.nodeId, binding]),
+  );
+  let pathsChanged = false;
+  bindings = bindings.map((binding) => {
+    const resolvedBinding = resolvedById.get(binding.nodeId);
+    if (!resolvedBinding || binding.path === resolvedBinding.path) {
+      return binding;
+    }
+    pathsChanged = true;
+    return {
+      ...binding,
+      path: resolvedBinding.path,
+    };
+  });
+  if (pathsChanged) persistCarriedState();
+  if (
+    (bindingsChanged || pathsChanged)
+    && typeof testHooks.afterCarriedCreateRefresh === 'function'
+  ) {
+    testHooks.afterCarriedCreateRefresh(bindings, deletionBindings);
+  }
+
+  const before = new Map(
+    database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?')
+      .all(plan.resourceId)
+      .map(rowToNode)
+      .map((node) => [node.id, node]),
+  );
+  let causalState = new Map(intended);
+  for (const operation of causalSuccessors) {
+    causalState = applyTreeOperation(causalState, operation);
+  }
+  const augmented = new Map(before);
+  const carriedByPath = new Map(
+    resolved.map((binding) => [path.resolve(binding.path), binding.nodeId]),
+  );
+  const physicalParentId = (parentPath) => {
+    if (!pathExists(parentPath)) return null;
+    const stat = fs.lstatSync(parentPath);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
+    const matches = database.prepare(`
+      SELECT id
+      FROM workspace_nodes
+      WHERE workspace_id = ?
+        AND kind = 'folder'
+        AND device_id = ?
+        AND inode = ?
+        AND missing_at IS NULL
+        AND trashed_at IS NULL
+        AND purged_at IS NULL
+    `).all(
+      plan.resourceId,
+      String(stat.dev),
+      String(stat.ino),
+    );
+    return matches.length === 1 ? matches[0].id : null;
+  };
+  const newSuccessors = [];
+  const resolvingParents = new Set();
+  const resolvePhysicalParent = (parentPath) => {
+    const resolvedPath = path.resolve(parentPath);
+    if (resolvedPath === path.resolve(workspace.path)) return workspace.id;
+    const carriedId = carriedByPath.get(resolvedPath);
+    if (carriedId) return carriedId;
+    const nodeId = (
+      localTree().nodeForPath(parentPath, { database })?.node.id
+      || physicalParentId(parentPath)
+    );
+    if (!nodeId || resolvingParents.has(nodeId)) return null;
+    const template = causalState.get(nodeId);
+    if (!template) return null;
+    resolvingParents.add(nodeId);
+    const parentId = resolvePhysicalParent(path.dirname(parentPath));
+    resolvingParents.delete(nodeId);
+    if (!parentId) return null;
+    const name = path.basename(parentPath);
+    if (template.parentId !== parentId || template.name !== name) {
+      const successor = template.parentId === parentId
+        ? {
+            kind: 'tree.rename',
+            workspaceId: plan.resourceId,
+            nodeId,
+            name,
+            changedAt: template.updatedAt || template.createdAt,
+          }
+        : {
+            kind: 'tree.move',
+            workspaceId: plan.resourceId,
+            nodeId,
+            parentId,
+            previousParentId: template.parentId,
+            name,
+            changedAt: template.updatedAt || template.createdAt,
+          };
+      newSuccessors.push(successor);
+      causalState = applyTreeOperation(causalState, successor);
+    }
+    augmented.set(nodeId, {
+      ...causalState.get(nodeId),
+      missingAt: null,
+    });
+    return nodeId;
+  };
+  const deletedIds = new Set(
+    deletionBindings.map((binding) => binding.nodeId),
+  );
+  const topLevelDeletions = deletionBindings.filter((binding) => {
+    let parentId = causalState.get(binding.nodeId)?.parentId || null;
+    const seen = new Set();
+    while (parentId && !seen.has(parentId)) {
+      if (deletedIds.has(parentId)) return false;
+      seen.add(parentId);
+      parentId = causalState.get(parentId)?.parentId || null;
+    }
+    return true;
+  }).sort((left, right) => left.nodeId.localeCompare(right.nodeId));
+  for (const binding of topLevelDeletions) {
+    const template = causalState.get(binding.nodeId);
+    if (!template) {
+      throw invalid(
+        `workspace tree deleted carried create ${binding.nodeId} has no logical node`,
+        409,
+      );
+    }
+    if (template.trashedAt) continue;
+    if (!template.parentId || !augmented.has(template.parentId)) {
+      throw invalid(
+        `workspace tree deleted carried create ${binding.nodeId} lost its logical parent`,
+        409,
+      );
+    }
+    const changedAt = template.updatedAt || template.createdAt;
+    const successor = {
+      kind: 'tree.trash',
+      workspaceId: plan.resourceId,
+      nodeId: binding.nodeId,
+      changedAt,
+      trashedAt: changedAt,
+    };
+    newSuccessors.push(successor);
+    causalState = applyTreeOperation(causalState, successor);
+  }
+
+  const desiredRelocations = [];
+  for (const binding of resolved) {
+    const template = causalState.get(binding.nodeId);
+    if (!template) {
+      throw invalid(
+        `workspace tree carried create ${binding.nodeId} has no logical node`,
+        409,
+      );
+    }
+    const parentPath = path.dirname(binding.path);
+    const parentId = resolvePhysicalParent(parentPath);
+    if (!parentId || !augmented.has(parentId)) {
+      throw invalid(
+        `workspace tree carried create ${binding.nodeId} lost its logical parent`,
+        409,
+      );
+    }
+    const name = path.basename(binding.path);
+    augmented.set(binding.nodeId, {
+      ...template,
+      parentId,
+      name,
+      trashedAt: null,
+      purgedAt: null,
+      missingAt: null,
+    });
+    if (template.parentId === parentId && template.name === name) continue;
+    const changedAt = template.updatedAt || template.createdAt;
+    desiredRelocations.push({
+      binding,
+      changedAt,
+      name,
+      parentId,
+    });
+  }
+
+  const relocatingIds = new Set(
+    desiredRelocations.map(({ binding }) => binding.nodeId),
+  );
+  const blockers = new Set();
+  for (const desired of desiredRelocations) {
+    const occupant = Array.from(causalState.values()).find((node) => (
+      node.workspaceId === plan.resourceId
+      && node.parentId === desired.parentId
+      && node.name === desired.name
+      && node.id !== desired.binding.nodeId
+      && !node.purgedAt
+      && !node.trashedAt
+    ));
+    if (!occupant) continue;
+    if (!relocatingIds.has(occupant.id)) {
+      throw invalid(
+        `workspace tree carried destination ${desired.binding.relativePath} `
+        + `is still owned by ${occupant.id}`,
+        409,
+      );
+    }
+    blockers.add(occupant.id);
+  }
+
+  // A carried path permutation is one set transition. Vacate every logical
+  // endpoint that blocks another endpoint before any node enters its final
+  // slot. The temporary names are deterministic, syncable path segments and
+  // become durable in causalSuccessors before the first journal birth.
+  for (const nodeId of [...blockers].sort()) {
+    const template = causalState.get(nodeId);
+    const digest = crypto.createHash('sha256')
+      .update(
+        `workspace-tree-carried-vacancy@1\0${plan.resourceId}\0`
+        + `${plan.mutationId}\0${nodeId}`,
+      )
+      .digest('hex')
+      .slice(0, 24);
+    let suffix = 0;
+    let name;
+    do {
+      name = `amalgm-relocation-${digest}${suffix ? `-${suffix}` : ''}`;
+      suffix += 1;
+    } while (Array.from(causalState.values()).some((node) => (
+      node.workspaceId === plan.resourceId
+      && node.parentId === template.parentId
+      && node.name === name
+      && node.id !== nodeId
+      && !node.purgedAt
+      && !node.trashedAt
+    )));
+    const successor = {
+      kind: 'tree.rename',
+      workspaceId: plan.resourceId,
+      nodeId,
+      name,
+      changedAt: template.updatedAt || template.createdAt,
+    };
+    newSuccessors.push(successor);
+    causalState = applyTreeOperation(causalState, successor);
+  }
+
+  for (const desired of desiredRelocations) {
+    const template = causalState.get(desired.binding.nodeId);
+    const successor = template.parentId === desired.parentId
+      ? {
+          kind: 'tree.rename',
+          workspaceId: plan.resourceId,
+          nodeId: desired.binding.nodeId,
+          name: desired.name,
+          changedAt: desired.changedAt,
+        }
+      : {
+          kind: 'tree.move',
+          workspaceId: plan.resourceId,
+          nodeId: desired.binding.nodeId,
+          parentId: desired.parentId,
+          previousParentId: template.parentId,
+          name: desired.name,
+          changedAt: desired.changedAt,
+        };
+    newSuccessors.push(successor);
+    causalState = applyTreeOperation(causalState, successor);
+  }
+  persistNodes(database, before, augmented, plan.resourceId);
+  if (newSuccessors.length) {
+    causalSuccessors = [...causalSuccessors, ...newSuccessors];
+    persistCarriedState();
+    if (typeof testHooks.afterCarriedSuccessorPlan === 'function') {
+      testHooks.afterCarriedSuccessorPlan(causalSuccessors);
+    }
+  }
+
+  try {
+    let chainBefore = new Map(intended);
+    for (const [index, operation] of causalSuccessors.entries()) {
+      const mutationId = causalSuccessorMutationId(
+        plan,
+        operation,
+        index,
+      );
+      const existing = database.prepare(`
+        SELECT mutation_state
+        FROM mutation_journal
+        WHERE local_resource = ? AND mutation_id = ?
+      `).get(`${TREE_RESOURCE_PREFIX}${plan.resourceId}`, mutationId);
+      const chainAfter = applyTreeOperation(chainBefore, operation);
+      if (existing && existing.mutation_state !== 'saving-local') {
+        chainBefore = chainAfter;
+        continue;
+      }
+      const operationBefore = new Map(
+        database.prepare(
+          'SELECT * FROM workspace_nodes WHERE workspace_id = ?',
+        ).all(plan.resourceId)
+          .map(rowToNode)
+          .map((node) => [node.id, node]),
+      );
+      const logicalTarget = chainBefore.get(operation.nodeId);
+      if (!logicalTarget) {
+        throw invalid(
+          `workspace tree causal successor ${operation.nodeId} lost its logical node`,
+          409,
+        );
+      }
+      operationBefore.set(operation.nodeId, logicalTarget);
+      const targetExists = Boolean(database.prepare(`
+        SELECT 1 AS present
+        FROM workspace_nodes
+        WHERE workspace_id = ? AND id = ?
+      `).get(plan.resourceId, operation.nodeId));
+      localTree().commitTreeOperation(operation, {
+        database,
+        beforeNodes: operationBefore,
+        diskAlreadyApplied: true,
+        mutationId,
+        source: 'workspace-tree:causal-successor',
+        ...(!targetExists ? {
+          role: require('./access-store').currentUserRole(
+            logicalTarget.parentId,
+            { database },
+          ),
+        } : {}),
+      });
+      chainBefore = chainAfter;
+    }
+  } catch (error) {
+    if (error?.statusCode !== 403) throw error;
+    holdCarriedSuccessorsForPermission(
+      plan,
+      causalSuccessors,
+      database,
+    );
+  }
+  if (typeof testHooks.afterCarriedSuccessorBirth === 'function') {
+    testHooks.afterCarriedSuccessorBirth(causalSuccessors);
+  }
+  return causalSuccessors;
+}
+
+function holdPreparedRetainedOutputs(plan, reason, paths, database) {
+  holdRetainedSuccessors(
+    plan,
+    reason,
+    [],
+    database,
+    Array.from(new Set(paths)).sort(),
+  );
+}
+
+function validatePreparedRetainedOutputs(plan, database) {
+  const outputs = Array.isArray(plan.retainedOutputs)
+    ? plan.retainedOutputs
+    : [];
+  if (!outputs.length || plan.retainedOutputsAdopted === true) return;
+  const changed = [];
+  const fileIdentities = new Set();
+  for (const output of outputs) {
+    if (!pathExists(output.path)) {
+      changed.push(output.path);
+      continue;
+    }
+    const actual = fs.lstatSync(output.path);
+    const kind = actual.isSymbolicLink()
+      ? 'symlink'
+      : actual.isDirectory()
+        ? 'folder'
+        : 'file';
+    if (
+      kind !== output.identity.kind
+      || String(actual.dev) !== String(output.identity.dev)
+      || String(actual.ino) !== String(output.identity.ino)
+    ) {
+      changed.push(output.path);
+      continue;
+    }
+    if (kind === 'file') fileIdentities.add(`${actual.dev}:${actual.ino}`);
+  }
+  if (changed.length) {
+    holdPreparedRetainedOutputs(
+      plan,
+      'retained-output-changed',
+      changed.map((target) => path.relative(plan.rootPath, target)),
+      database,
+    );
+  }
+  const aliases = localTree().scanWorkspacePhysicalAliases(
+    plan.resourceId,
+    { database },
+  ).filter((group) => (
+    fileIdentities.has(`${group.deviceId}:${group.inode}`)
+  )).flatMap((group) => group.paths);
+  if (aliases.length) {
+    holdPreparedRetainedOutputs(
+      plan,
+      'ambiguous-physical-alias',
+      aliases,
+      database,
+    );
+  }
+}
+
+function claimPreparedRetainedOutputs(plan, database) {
+  if (
+    plan.retainedOutputsAdopted === true
+    || !Array.isArray(plan.retainedOutputs)
+    || !plan.retainedOutputs.length
+  ) {
+    return plan;
+  }
+  const materialization = require('./tree-materialization');
+  const held = materialization.getOperation(
+    plan.resourceId,
+    plan.mutationId,
+    database,
+  );
+  if (!held || held.state !== 'prepared') {
+    throw invalid(
+      `workspace tree retained output claim lost operation ${plan.mutationId}`,
+      409,
+    );
+  }
+  return materialization.replacePreparedOperation(
+    held,
+    {
+      ...held.plan,
+      // The exact output receipts were just verified. From this durable point
+      // onward, any different disk identity is a locally owned successor for
+      // the carried chain (or a fresh independent birth), never an excuse to
+      // re-apply the obsolete receipt after a crash.
+      retainedOutputsAdopted: true,
+    },
+    database,
+  ).plan;
+}
+
+function verifyPreparedRetainedBirths(plan, database, causallyProjected) {
+  const projectedPaths = pathMapForSnapshot({
+    workspaceId: plan.resourceId,
+    nodes: causallyProjected,
+  });
+  const activeByPath = new Map();
+  for (const node of causallyProjected.values()) {
+    if (!activeNode(node)) continue;
+    activeByPath.set(projectedPaths.get(node.id), node);
+  }
+  for (const output of plan.retainedOutputs || []) {
+    const relativePath = relativeWorkspacePath(plan.rootPath, output.path);
+    const expected = relativePath == null ? null : activeByPath.get(relativePath);
+    const physical = physicalBindingAtPath(output.path, database);
+    if (!pathExists(output.path)) {
+      if (!expected) continue;
+      holdPreparedRetainedOutputs(
+        plan,
+        'retained-output-changed',
+        [path.relative(plan.rootPath, output.path)],
+        database,
+      );
+    }
+    if (!physical || !expected || physical.node.id !== expected.id) {
+      holdPreparedRetainedOutputs(
+        plan,
+        'retained-birth-pending',
+        [path.relative(plan.rootPath, output.path)],
+        database,
+      );
+    }
+  }
+  const carriedOwnerIds = new Set(
+    (plan.retainedOutputs || [])
+      .filter((output) => (
+        output.provenance === 'carried-source' && output.ownerNodeId
+      ))
+      .map((output) => output.ownerNodeId),
+  );
+  for (const ownerNodeId of carriedOwnerIds) {
+    const owner = rowToNode(database.prepare(`
+      SELECT *
+      FROM workspace_nodes
+      WHERE workspace_id = ? AND id = ?
+    `).get(plan.resourceId, ownerNodeId));
+    if (owner?.trashedAt || owner?.purgedAt) continue;
+    const expected = causallyProjected.get(ownerNodeId);
+    if (!owner || !expected || !activeNode(expected)) {
+      holdPreparedRetainedOutputs(
+        plan,
+        'retained-uuid-mismatch',
+        [],
+        database,
+      );
+    }
+    const ownerRelativePath = projectedPaths.get(ownerNodeId);
+    const ownerPath = ownerRelativePath
+      ? path.join(plan.rootPath, ...ownerRelativePath.split('/'))
+      : plan.rootPath;
+    const physical = physicalBindingAtPath(ownerPath, database);
+    if (!physical || physical.node.id !== ownerNodeId) {
+      holdPreparedRetainedOutputs(
+        plan,
+        'retained-uuid-mismatch',
+        [ownerRelativePath],
+        database,
+      );
+    }
+  }
+}
+
+function crossTreeOperationWithRaceCapture(held, database, testHooks = {}) {
+  const materialization = require('./tree-materialization');
+  let current = held;
+  const maxAttempts = 4;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      return materialization.crossOperation(current, database, testHooks);
+    } catch (error) {
+      if (
+        !['WORKSPACE_TREE_SOURCE_RACE', 'WORKSPACE_TREE_PARENT_RACE']
+          .includes(error?.code)
+        || !error.operationPlan
+      ) {
+        throw error;
+      }
+      let retainedPlan = error.operationPlan;
+      validatePreparedRetainedOutputs(retainedPlan, database);
+      retainedPlan = claimPreparedRetainedOutputs(retainedPlan, database);
+      const carriedSuccessors = adoptCarriedCreateBindings(
+        retainedPlan,
+        database,
+        testHooks,
+      );
+      retainedPlan = materialization.getOperation(
+        retainedPlan.resourceId,
+        retainedPlan.mutationId,
+        database,
+      )?.plan || retainedPlan;
+      const persistObservedOperation = (operation, mutationId) => {
+        materialization.appendOperationSuccessor(
+          retainedPlan,
+          mutationId,
+          operation,
+          database,
+        );
+      };
+      const observedNow = settleRetainedOutputBindings(
+        retainedPlan,
+        database,
+        {
+          source: 'workspace-tree:source-race',
+          testHooks,
+          persistObservedOperation,
+          hold(reason, paths) {
+            holdPreparedRetainedOutputs(
+              retainedPlan,
+              reason,
+              paths,
+              database,
+            );
+          },
+        },
+      );
+      retainedPlan = materialization.getOperation(
+        retainedPlan.resourceId,
+        retainedPlan.mutationId,
+        database,
+      )?.plan || retainedPlan;
+      const durableObserved = materialization.listOperationSuccessors(
+        retainedPlan,
+        database,
+      ).map((entry) => entry.operation);
+      const observedOperations = durableObserved.length
+        ? durableObserved
+        : observedNow;
+      let causallyProjected = retainedPlan.sourceRaceCaptured === true
+        ? planNodes(retainedPlan, 'afterNodes')
+        : applyTreeOperation(
+          planNodes(retainedPlan, 'beforeNodes'),
+          normalizeTreeOperation(retainedPlan.operation),
+        );
+      for (const successor of carriedSuccessors) {
+        causallyProjected = applyTreeOperation(causallyProjected, successor);
+      }
+      for (const successor of observedOperations) {
+        causallyProjected = applyTreeOperation(causallyProjected, successor);
+      }
+      verifyPreparedRetainedBirths(
+        retainedPlan,
+        database,
+        causallyProjected,
+      );
+      const currentNodes = database.prepare(
+        'SELECT * FROM workspace_nodes WHERE workspace_id = ?',
+      ).all(retainedPlan.resourceId).map(rowToNode);
+      const workspace = workspaceRow(retainedPlan.resourceId, database);
+      if (!workspace) throw invalid('workspace tree source race lost its workspace', 409);
+      const replacement = {
+        ...physicalOperationPlan(
+          workspace,
+          new Map(currentNodes.map((node) => [node.id, node])),
+          causallyProjected,
+          normalizeTreeOperation(retainedPlan.operation),
+          {
+            envelope: {
+              mutationId: retainedPlan.mutationId,
+              authorityEpoch: retainedPlan.authorityEpoch,
+            },
+            version: retainedPlan.version,
+          },
+          Array.isArray(retainedPlan.officialAfterNodes)
+            ? new Map(
+              retainedPlan.officialAfterNodes
+                .map((node) => [node.id, node]),
+            )
+            : null,
+          {
+            channelId: retainedPlan.channelId,
+            database,
+            source: retainedPlan.event?.source,
+            resourceVersion: retainedPlan.event?.resourceVersion != null,
+            projectFullDelta: true,
+          },
+        ),
+        event: retainedPlan.event,
+        origin: retainedPlan.origin,
+        sourceRaceCaptured: true,
+      };
+      const predecessor = materialization.getOperation(
+        replacement.resourceId,
+        replacement.mutationId,
+        database,
+      );
+      current = predecessor
+        ? materialization.replacePreparedOperation(
+            predecessor,
+            replacement,
+            database,
+          )
+        : materialization.insertOperation(replacement, database);
+    }
+  }
+  holdRetainedSuccessors(
+    current.plan,
+    'source-race-retry-exhausted',
+    [],
+    database,
+  );
+}
+
+function applyStoredTreeOperationPlan(held, database, testHooks = {}) {
+  const treeMaterialization = require('./tree-materialization');
+  if (held.state === 'committed') {
+    finishTreeOperationPlan(held, database, testHooks);
+    return { duplicate: true, recovered: true };
+  }
+  const operation = normalizeTreeOperation(held.plan.operation);
+  validateLiveSymlinkTargets(
+    planNodes(held.plan, 'afterNodes'),
+    held.plan.resourceId,
+  );
+  if (operation.kind === 'tree.trash' || operation.kind === 'tree.purge') {
+    const before = planNodes(held.plan, 'beforeNodes');
+    const affected = new Set(
+      Array.from(before.values())
+        .filter((node) => (
+          node.id === operation.nodeId
+          || hasAncestorInSet(node, before, new Set([operation.nodeId]))
+        ))
+        .map((node) => node.id),
+    );
+    require('../state/docs').closeDocsByNodeIds(affected);
+  }
+  try {
+    held = crossTreeOperationWithRaceCapture(held, database, testHooks);
+  } catch (error) {
+    holdClassifiedPlanRetry(held.plan, error, database);
+  }
+  projectStoredTreeOperation(held, database);
+  if (testHooks.crashAfterOperationProjection === true) {
+    throw new Error('simulated workspace tree crash after operation projection');
+  }
+  const mutations = require('../state/mutations');
+  const mutation = mutations.getMutation(
+    held.plan.channelId,
+    held.plan.mutationId,
+    { database, revealOperation: true },
+  );
+  if (!mutation) {
+    throw invalid(`workspace tree operation ${held.plan.mutationId} lost its journal row`, 409);
+  }
+  const completed = (
+    mutation.origin === 'local'
+    && mutation.state === 'synced'
+    && mutation.officialCloudVersion != null
+  ) ? mutations.completeOfficialMaterialization(
+      held.plan.channelId,
+      held.plan.mutationId,
+      held.plan.event,
+      {
+        database,
+        finalize() {
+          held = treeMaterialization.markOperationCommitted(held, database);
+        },
+      },
+    )
+    : mutations.completeMaterializedMutation(
+      held.plan.channelId,
+      held.plan.mutationId,
+      held.plan.event,
+      {
+        database,
+        finalize() {
+          held = treeMaterialization.markOperationCommitted(held, database);
+        },
+      },
+    );
+  if (testHooks.crashAfterOperationCommit === true) {
+    throw new Error('simulated workspace tree crash after operation commit');
+  }
+  finishTreeOperationPlan(held, database, testHooks);
+  return { ...completed, recovered: true };
+}
+
+function recoverTreeOperationPlans(resourceId, database, testHooks = {}) {
+  let result = null;
+  for (const held of require('./tree-materialization').listOperations(database, resourceId)) {
+    result = applyStoredTreeOperationPlan(held, database, testHooks);
+  }
+  return result;
+}
+
+function applyCloudTreeMutation(input, options = {}) {
+  const envelope = input?.envelope || {};
+  if (envelope.contract !== 'workspace-tree@1') throw invalid('unsupported workspace tree mutation', 409);
+  const operation = normalizeTreeOperation(envelope.operation);
+  if (operation.workspaceId !== envelope.resourceId || operation.kind !== envelope.operationKind) {
+    throw invalid('workspace tree mutation identity mismatch', 409);
+  }
+  const database = options.database || openLocalDb();
+  recoverTreePlans(envelope.resourceId, database);
+  recoverTreeOperationPlans(envelope.resourceId, database);
+  const workspace = workspaceRow(operation.workspaceId, database);
+  if (!workspace) throw invalid('workspace tree has no local folder', 404);
+  let held = null;
+  const result = require('../state/mutations').ingestCloudMutation({
+    ...input,
+    localResource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
+  }, {
+    database,
+    materialize() {
+      const before = new Map(
+        database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
+          .map(rowToNode)
+          .map((node) => [node.id, node]),
+      );
+      const replica = require('../state/replicas')
+        .getReplicaByResourceId(workspace.id, { database });
+      let floor = require('./tree/floor').read(workspace.id, { database });
+      if (!floor) {
+        floor = require('./tree/floor').ensure({
+          schemaVersion: 1,
+          workspaceId: workspace.id,
+          version: replica?.appliedVersion || 0,
+          nodes: before,
+        }, projectedAuthorityEpoch(workspace.id, database) || envelope.authorityEpoch, {
+          database,
+        });
+      }
+      if (floor.version !== Number(input.version) - 1) {
+        throw invalid(
+          `workspace tree floor gap: expected ${Number(input.version) - 1}, found ${floor.version}`,
+          409,
+        );
+      }
+      const officialAfterNodes = applyTreeOperation(floor.snapshot.nodes, operation);
+      const officialAfter = {
+        schemaVersion: 1,
+        workspaceId: workspace.id,
+        version: Number(input.version),
+        nodes: officialAfterNodes,
+      };
+      const projected = snapshotWithLocalOverlay(
+        officialAfter,
+        before,
+        workspace.id,
+        database,
+      );
+      held = require('./tree-materialization').insertOperation(
+        physicalOperationPlan(
+          workspace,
+          before,
+          projected.nodes,
+          operation,
+          input,
+          officialAfterNodes,
+          { database },
+        ),
+        database,
+      );
+      if (typeof options.testHooks?.afterOperationPlan === 'function') {
+        options.testHooks.afterOperationPlan(held.plan);
+      }
+      try {
+        held = crossTreeOperationWithRaceCapture(
+          held,
+          database,
+          options.testHooks,
+        );
+      } catch (error) {
+        holdClassifiedPlanRetry(held.plan, error, database);
+      }
+      projectStoredTreeOperation(held, database);
+      if (options.testHooks?.crashAfterOperationProjection === true) {
+        throw new Error('simulated workspace tree crash after operation projection');
+      }
+    },
+    event: () => ({
+      resource: `${TREE_RESOURCE_PREFIX}${workspace.id}`,
+      op: 'update',
+      id: operation.nodeId,
+      patch: operation,
+      sharedResourceId: workspace.id,
       source: 'workspace-tree:cloud',
       resourceVersion: Number(input.version),
     }),
+    finalize() {
+      if (!held) return;
+      held = require('./tree-materialization').markOperationCommitted(held, database);
+    },
   });
+  if (held) {
+    if (options.testHooks?.crashAfterOperationCommit === true) {
+      throw new Error('simulated workspace tree crash after operation commit');
+    }
+    finishTreeOperationPlan(held, database, options.testHooks);
+  }
+  return result;
 }
 
 module.exports = {
   applyCloudTreeMutation,
+  crossTreeOperationWithRaceCapture,
   enqueueWorkspaceContentAttachments,
+  finishTreeOperationPlan,
+  holdClassifiedPlanRetry,
   installCloudTreeSnapshot,
+  localTreeOperationPlan,
+  projectStoredTreeOperation,
+  reconcileContentOverlay,
+  recoverAllTreePlans,
   workspaceTreeSnapshot,
 };