amalgm 0.1.239 → 0.1.241

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

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * The official workspace-tree floor.
+ *
+ * `workspace_nodes` is the physical view (official floor plus durable local
+ * overlay), so it cannot also answer what an incoming official operation is
+ * allowed to reduce against. This table keeps that one separate fact.
+ */
+
+const { openLocalDb } = require('../../state/db');
+const { normalizeTreeSnapshot } = require('./snapshot');
+
+function ensureSchema(database = openLocalDb()) {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS workspace_tree_floors (
+      resource_id TEXT PRIMARY KEY,
+      rail_version INTEGER NOT NULL CHECK (rail_version >= 0),
+      authority_epoch INTEGER NOT NULL CHECK (authority_epoch > 0),
+      snapshot_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+  `);
+}
+
+function snapshotRecord(snapshot) {
+  return {
+    schemaVersion: 1,
+    workspaceId: snapshot.workspaceId,
+    version: snapshot.version,
+    nodes: Array.from(snapshot.nodes.values()),
+  };
+}
+
+function normalize(row) {
+  if (!row) return null;
+  const snapshot = normalizeTreeSnapshot(JSON.parse(row.snapshot_json));
+  if (
+    snapshot.workspaceId !== row.resource_id
+    || snapshot.version !== Number(row.rail_version)
+  ) {
+    throw new Error(`workspace tree floor ${row.resource_id} is inconsistent`);
+  }
+  return {
+    resourceId: row.resource_id,
+    version: Number(row.rail_version),
+    authorityEpoch: Number(row.authority_epoch),
+    snapshot,
+    updatedAt: row.updated_at,
+  };
+}
+
+function read(resourceId, options = {}) {
+  const database = options.database || openLocalDb();
+  ensureSchema(database);
+  return normalize(database.prepare(`
+    SELECT * FROM workspace_tree_floors WHERE resource_id = ?
+  `).get(resourceId));
+}
+
+function write(snapshotInput, authorityEpochInput, options = {}) {
+  const database = options.database || openLocalDb();
+  ensureSchema(database);
+  const snapshot = normalizeTreeSnapshot(snapshotRecord(snapshotInput));
+  const authorityEpoch = Number(authorityEpochInput);
+  if (!Number.isSafeInteger(authorityEpoch) || authorityEpoch < 1) {
+    throw new Error('workspace tree floor authority epoch is invalid');
+  }
+  database.prepare(`
+    INSERT INTO workspace_tree_floors (
+      resource_id, rail_version, authority_epoch, snapshot_json, updated_at
+    ) VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(resource_id) DO UPDATE SET
+      rail_version = excluded.rail_version,
+      authority_epoch = excluded.authority_epoch,
+      snapshot_json = excluded.snapshot_json,
+      updated_at = excluded.updated_at
+  `).run(
+    snapshot.workspaceId,
+    snapshot.version,
+    authorityEpoch,
+    JSON.stringify(snapshotRecord(snapshot)),
+    new Date().toISOString(),
+  );
+  return read(snapshot.workspaceId, { database });
+}
+
+function ensure(snapshot, authorityEpoch, options = {}) {
+  const database = options.database || openLocalDb();
+  const existing = read(snapshot.workspaceId, { database });
+  if (existing) return existing;
+  return write(snapshot, authorityEpoch, { database });
+}
+
+module.exports = {
+  ensure,
+  read,
+  snapshotRecord,
+  write,
+};

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

@@ -57,7 +57,13 @@ function isPrivateFile(name) {
 // enrolled as leaf nodes and are never followed by the scanner.
 function shouldEnroll(relativePath) {
   const parts = partsFor(relativePath);
-  if (parts.length === 0 || parts.some((part) => EXCLUDED_DIRECTORIES.has(part))) return false;
+  if (
+    parts.length === 0
+    || parts.some((part) => (
+      EXCLUDED_DIRECTORIES.has(part)
+      || part.startsWith('.amalgm-tree-apply-')
+    ))
+  ) return false;
   const name = parts.at(-1);
   if (EXCLUDED_FILES.has(name) || isPrivateFile(name)) return false;
   return !name.startsWith('.#') && !name.endsWith('~') && !/\.(?:swp|swo)$/i.test(name);

package/runtime/scripts/amalgm-mcp/workspace/tree/local-state.js

@@ -4,7 +4,6 @@ const fs = require('fs');
 const path = require('path');
 const { AMALGM_DIR } = require('../../config');
 const { openLocalDb } = require('../../state/db');
-const { descendantsInclude } = require('./reducer');
 
 function invalid(message, statusCode = 400) {
   return Object.assign(new Error(message), { statusCode });
@@ -23,6 +22,7 @@ function rowToNode(row) {
     deviceId: row.device_id || null,
     inode: row.inode || null,
     trashedAt: row.trashed_at || null,
+    trashComponentId: row.trash_component_id || null,
     purgedAt: row.purged_at || null,
     missingAt: row.missing_at || null,
     createdAt: row.created_at,
@@ -53,56 +53,22 @@ function relativePathForNode(nodes, nodeId, memo = new Map()) {
   return relativePath;
 }
 
-function trashPath(workspaceId, nodeId) {
-  return path.join(AMALGM_DIR, 'trash', 'workspaces', workspaceId, nodeId);
-}
-
-function requireMissing(targetPath, message) {
-  try {
-    fs.lstatSync(targetPath);
-    throw invalid(message, 409);
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
+function trashPath(workspaceId, nodeId, workspacePath = null) {
+  if (workspacePath) {
+    // Tree trash participates in the same rename-only WAL as the visible
+    // workspace. Keep it beside that workspace so arbitrary registered
+    // folders (including external volumes) never turn trash/restore into an
+    // impossible cross-device rename.
+    return path.join(
+      path.dirname(path.resolve(workspacePath)),
+      `.amalgm-tree-trash-${workspaceId}`,
+      nodeId,
+    );
   }
-}
-
-function materializeOperation(workspace, before, after, operation) {
-  const oldNode = before.get(operation.nodeId) || null;
-  const newNode = after.get(operation.nodeId) || null;
-  const oldRelative = oldNode ? relativePathForNode(before, oldNode.id) : null;
-  const newRelative = newNode ? relativePathForNode(after, newNode.id) : null;
-  const oldPath = oldRelative ? path.join(workspace.path, ...oldRelative.split('/')) : null;
-  const newPath = newRelative ? path.join(workspace.path, ...newRelative.split('/')) : null;
-
-  if (operation.kind === 'tree.create') {
-    requireMissing(newPath, 'create destination already exists');
-    fs.mkdirSync(path.dirname(newPath), { recursive: true });
-    if (operation.nodeKind === 'folder') fs.mkdirSync(newPath);
-    else if (operation.nodeKind === 'symlink') fs.symlinkSync(operation.symlinkTarget, newPath);
-    else fs.writeFileSync(newPath, '');
-  } else if (operation.kind === 'tree.rename' || operation.kind === 'tree.move') {
-    requireMissing(newPath, 'move destination already exists');
-    fs.mkdirSync(path.dirname(newPath), { recursive: true });
-    fs.renameSync(oldPath, newPath);
-  } else if (operation.kind === 'tree.trash') {
-    const destination = trashPath(workspace.id, operation.nodeId);
-    requireMissing(destination, 'trash destination already exists');
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    fs.renameSync(oldPath, destination);
-  } else if (operation.kind === 'tree.restore') {
-    const source = trashPath(workspace.id, operation.nodeId);
-    requireMissing(newPath, 'restore destination already exists');
-    fs.mkdirSync(path.dirname(newPath), { recursive: true });
-    fs.renameSync(source, newPath);
-  } else if (operation.kind === 'tree.purge') {
-    for (const node of before.values()) {
-      if (node.id === operation.nodeId || descendantsInclude(before, operation.nodeId, node.id)) {
-        fs.rmSync(trashPath(workspace.id, node.id), { recursive: true, force: true });
-      }
-    }
-  }
-
-  return { oldPath, newPath };
+  // Compatibility for callers that only need the historical locator. New
+  // materialization plans always pass workspacePath and persist the exact
+  // same-filesystem location in their action.
+  return path.join(AMALGM_DIR, 'trash', 'workspaces', workspaceId, nodeId);
 }
 
 function absolutePathForWorkspace(workspaceId, relativePath, database) {
@@ -115,32 +81,78 @@ function persistNodes(database, before, after, workspaceId) {
   const now = new Date().toISOString();
   const pathMemo = new Map();
   const changedPaths = [];
+  const persisted = new Map(
+    database.prepare(
+      'SELECT * FROM workspace_nodes WHERE workspace_id = ?',
+    ).all(workspaceId)
+      .map(rowToNode)
+      .map((node) => [node.id, node]),
+  );
   for (const node of after.values()) {
     const relativePath = relativePathForNode(after, node.id, pathMemo);
-    const previous = before.get(node.id);
-    const previousRelative = previous ? relativePathForNode(before, previous.id) : null;
-    if (!previous) {
+    const previousFromBefore = before.get(node.id);
+    const previous = previousFromBefore || persisted.get(node.id);
+    const previousRelative = previousFromBefore
+      ? relativePathForNode(before, previousFromBefore.id)
+      : previous?.relativePath || null;
+    if (!persisted.has(node.id)) {
       const absolutePath = relativePath ? absolutePathForWorkspace(workspaceId, relativePath, database) : null;
-      const stats = absolutePath ? fs.lstatSync(absolutePath) : null;
+      const stats = absolutePath && !node.trashedAt && !node.purgedAt
+        ? fs.lstatSync(absolutePath)
+        : null;
       database.prepare(`
         INSERT INTO workspace_nodes (
           id, workspace_id, parent_id, kind, name, relative_path, symlink_target,
-          device_id, inode, trashed_at, purged_at, missing_at, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)
+          device_id, inode, trashed_at, trash_component_id, purged_at,
+          missing_at, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          workspace_id = excluded.workspace_id,
+          parent_id = excluded.parent_id,
+          kind = excluded.kind,
+          name = excluded.name,
+          relative_path = excluded.relative_path,
+          symlink_target = excluded.symlink_target,
+          device_id = excluded.device_id,
+          inode = excluded.inode,
+          trashed_at = excluded.trashed_at,
+          trash_component_id = excluded.trash_component_id,
+          purged_at = excluded.purged_at,
+          missing_at = NULL,
+          updated_at = excluded.updated_at
       `).run(
         node.id, node.workspaceId, node.parentId, node.kind, node.name,
         relativePath, node.symlinkTarget, stats ? String(stats.dev) : null,
-        stats ? String(stats.ino) : null, node.trashedAt, node.purgedAt,
+        stats ? String(stats.ino) : null, node.trashedAt,
+        node.trashComponentId, node.purgedAt,
         node.createdAt, now,
       );
     } else {
       database.prepare(`
         UPDATE workspace_nodes
         SET parent_id = ?, name = ?, relative_path = ?, trashed_at = ?,
-            purged_at = ?, missing_at = NULL, updated_at = ?
+            trash_component_id = ?, purged_at = ?, missing_at = NULL,
+            updated_at = ?
         WHERE id = ?
-      `).run(node.parentId, node.name, relativePath, node.trashedAt, node.purgedAt, now, node.id);
-      if (previousRelative !== relativePath) {
+      `).run(
+        node.parentId,
+        node.name,
+        relativePath,
+        node.trashedAt,
+        node.trashComponentId,
+        node.purgedAt,
+        now,
+        node.id,
+      );
+      // Trashed and purged rows are UUID tombstones, not live document
+      // locations. Multiple tombstones may legally retain the same logical
+      // path, so only a resulting live node may participate in document path
+      // rebinding.
+      if (
+        previousRelative !== relativePath
+        && !node.trashedAt
+        && !node.purgedAt
+      ) {
         changedPaths.push({
           nodeId: node.id,
           oldPath: absolutePathForWorkspace(workspaceId, previousRelative, database),
@@ -165,9 +177,9 @@ function hasAncestorInSet(node, nodesById, ids) {
 
 module.exports = {
   hasAncestorInSet,
-  materializeOperation,
   persistNodes,
   relativePathForNode,
   rowToNode,
+  trashPath,
   workspaceRow,
 };

package/runtime/scripts/amalgm-mcp/workspace/tree/observation-holds.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function stableHold(input) {
+  const operation = input?.operation || null;
+  const operationKind = typeof operation?.kind === 'string' ? operation.kind : null;
+  const explicitNodeId = typeof input?.nodeId === 'string' ? input.nodeId : null;
+  const operationNodeId = (
+    operationKind !== 'tree.create'
+    && typeof operation?.nodeId === 'string'
+  ) ? operation.nodeId : null;
+  return {
+    reason: typeof input?.reason === 'string' && input.reason
+      ? input.reason
+      : 'observation-pending',
+    nodeId: explicitNodeId || operationNodeId,
+    operationKind,
+    paths: Array.from(new Set(
+      Array.isArray(input?.paths)
+        ? input.paths.filter((value) => typeof value === 'string' && value)
+        : [],
+    )).sort(),
+  };
+}
+
+function ownerScope(options = {}) {
+  return {
+    ownerKind: typeof options.ownerKind === 'string' && options.ownerKind
+      ? options.ownerKind
+      : 'observer',
+    ownerId: typeof options.ownerId === 'string' && options.ownerId
+      ? options.ownerId
+      : 'workspace-tree-observer',
+  };
+}
+
+function holdKey(owner, hold) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify({ ...owner, hold }))
+    .digest('hex');
+}
+
+function normalize(rows) {
+  return rows.map((row) => ({
+    id: row.hold_key,
+    ownerKind: row.owner_kind,
+    ownerId: row.owner_id,
+    reason: row.reason,
+    nodeId: row.node_id || null,
+    operationKind: row.operation_kind || null,
+    paths: JSON.parse(row.paths_json),
+    firstObservedAt: row.first_observed_at,
+  }));
+}
+
+function list(workspaceId, database) {
+  return normalize(database.prepare(`
+    SELECT *
+    FROM workspace_tree_observation_holds
+    WHERE workspace_id = ?
+    ORDER BY owner_kind, owner_id, reason, hold_key
+  `).all(workspaceId));
+}
+
+function replace(workspaceId, inputs, database, options = {}) {
+  const owner = ownerScope(options);
+  const next = (Array.isArray(inputs) ? inputs : [])
+    .map(stableHold)
+    .map((hold) => ({ ...hold, key: holdKey(owner, hold) }))
+    .sort((left, right) => left.key.localeCompare(right.key));
+  const current = database.prepare(`
+    SELECT *
+    FROM workspace_tree_observation_holds
+    WHERE workspace_id = ? AND owner_kind = ? AND owner_id = ?
+    ORDER BY hold_key
+  `).all(workspaceId, owner.ownerKind, owner.ownerId);
+  const currentShape = current.map((row) => ({
+    key: row.hold_key,
+    reason: row.reason,
+    nodeId: row.node_id || null,
+    operationKind: row.operation_kind || null,
+    paths: JSON.parse(row.paths_json),
+  }));
+  const nextShape = next.map((hold) => ({
+    key: hold.key,
+    reason: hold.reason,
+    nodeId: hold.nodeId,
+    operationKind: hold.operationKind,
+    paths: hold.paths,
+  }));
+  if (JSON.stringify(currentShape) === JSON.stringify(nextShape)) return false;
+
+  const firstObservedByKey = new Map(
+    current.map((row) => [row.hold_key, row.first_observed_at]),
+  );
+  const now = new Date().toISOString();
+  database.prepare(`
+    DELETE FROM workspace_tree_observation_holds
+    WHERE workspace_id = ? AND owner_kind = ? AND owner_id = ?
+  `).run(workspaceId, owner.ownerKind, owner.ownerId);
+  const insert = database.prepare(`
+    INSERT INTO workspace_tree_observation_holds (
+      workspace_id, hold_key, owner_kind, owner_id, reason, node_id,
+      operation_kind, paths_json, first_observed_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  for (const hold of next) {
+    insert.run(
+      workspaceId,
+      hold.key,
+      owner.ownerKind,
+      owner.ownerId,
+      hold.reason,
+      hold.nodeId,
+      hold.operationKind,
+      JSON.stringify(hold.paths),
+      firstObservedByKey.get(hold.key) || now,
+    );
+  }
+  return true;
+}
+
+module.exports = {
+  list,
+  replace,
+};

package/runtime/scripts/amalgm-mcp/workspace/tree/path-state.js

@@ -0,0 +1,12 @@
+'use strict';
+
+/**
+ * A pathname has no final entry when either that entry is missing or an
+ * ancestor stopped being a directory. Recovery must classify both as
+ * absence; the latter is not an I/O failure and must never wedge a WAL.
+ */
+function isPathAbsentError(error) {
+  return error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
+}
+
+module.exports = { isPathAbsentError };

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

@@ -1,6 +1,7 @@
 'use strict';
 
 const { normalizeTreeOperation } = require('./operations');
+const { validateLiveSymlinkTargets } = require('./symlinks');
 
 function toMap(nodes) {
   if (nodes instanceof Map) return new Map(nodes);
@@ -19,6 +20,25 @@ function descendantsInclude(nodes, ancestorId, candidateId) {
   return false;
 }
 
+function descendantIds(nodes, ancestorId) {
+  const children = new Map();
+  for (const node of nodes.values()) {
+    if (!node.parentId) continue;
+    const siblings = children.get(node.parentId) || [];
+    siblings.push(node.id);
+    children.set(node.parentId, siblings);
+  }
+  const descendants = [];
+  const queue = [ancestorId];
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    for (const childId of children.get(queue[cursor]) || []) {
+      descendants.push(childId);
+      queue.push(childId);
+    }
+  }
+  return descendants;
+}
+
 function ensureAvailableName(nodes, workspaceId, parentId, name, exceptId = null) {
   const duplicate = Array.from(nodes.values()).find((node) => (
     node.workspaceId === workspaceId
@@ -51,10 +71,12 @@ function applyTreeOperation(inputNodes, inputOperation) {
       name: operation.name,
       symlinkTarget: operation.symlinkTarget || null,
       trashedAt: null,
+      trashComponentId: null,
       purgedAt: null,
       createdAt: operation.createdAt,
       updatedAt: operation.createdAt,
     });
+    validateLiveSymlinkTargets(nodes, operation.workspaceId);
     return nodes;
   }
 
@@ -72,6 +94,7 @@ function applyTreeOperation(inputNodes, inputOperation) {
   }
 
   const next = { ...existing, updatedAt: operation.changedAt };
+  const existingTrashComponentId = existing.trashComponentId || existing.id;
   if (operation.kind === 'tree.rename') {
     ensureAvailableName(nodes, operation.workspaceId, existing.parentId, operation.name, existing.id);
     next.name = operation.name;
@@ -92,6 +115,7 @@ function applyTreeOperation(inputNodes, inputOperation) {
       throw Object.assign(new Error('a node is already trashed'), { statusCode: 409 });
     }
     next.trashedAt = operation.trashedAt;
+    next.trashComponentId = operation.nodeId;
   } else if (operation.kind === 'tree.restore') {
     if (!existing.trashedAt) {
       throw Object.assign(new Error('a node must be trashed before it can be restored'), { statusCode: 409 });
@@ -109,26 +133,47 @@ function applyTreeOperation(inputNodes, inputOperation) {
     next.parentId = parentId;
     next.name = name;
     next.trashedAt = null;
+    next.trashComponentId = null;
   } else if (operation.kind === 'tree.purge') {
     if (!existing.trashedAt) {
       throw Object.assign(new Error('a node must be trashed before permanent removal'), { statusCode: 409 });
     }
     next.purgedAt = operation.purgedAt;
+    next.trashComponentId = null;
   }
 
   nodes.set(next.id, next);
   if (operation.kind === 'tree.trash' || operation.kind === 'tree.restore' || operation.kind === 'tree.purge') {
-    for (const child of nodes.values()) {
-      if (child.id === next.id || !descendantsInclude(nodes, next.id, child.id)) continue;
+    for (const childId of descendantIds(nodes, next.id)) {
+      const child = nodes.get(childId);
       if (operation.kind === 'tree.trash' && !child.trashedAt) {
-        nodes.set(child.id, { ...child, trashedAt: operation.trashedAt, updatedAt: operation.changedAt });
-      } else if (operation.kind === 'tree.restore' && child.trashedAt === existing.trashedAt) {
-        nodes.set(child.id, { ...child, trashedAt: null, updatedAt: operation.changedAt });
+        nodes.set(child.id, {
+          ...child,
+          trashedAt: operation.trashedAt,
+          trashComponentId: operation.nodeId,
+          updatedAt: operation.changedAt,
+        });
+      } else if (
+        operation.kind === 'tree.restore'
+        && (child.trashComponentId || child.id) === existingTrashComponentId
+      ) {
+        nodes.set(child.id, {
+          ...child,
+          trashedAt: null,
+          trashComponentId: null,
+          updatedAt: operation.changedAt,
+        });
       } else if (operation.kind === 'tree.purge') {
-        nodes.set(child.id, { ...child, purgedAt: operation.purgedAt, updatedAt: operation.changedAt });
+        nodes.set(child.id, {
+          ...child,
+          trashComponentId: null,
+          purgedAt: operation.purgedAt,
+          updatedAt: operation.changedAt,
+        });
       }
     }
   }
+  validateLiveSymlinkTargets(nodes, operation.workspaceId);
   return nodes;
 }
 

package/runtime/scripts/amalgm-mcp/workspace/tree/root-binding.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isPathAbsentError } = require('./path-state');
+
+const ROOT_HOLD_REASONS = new Set([
+  'workspace-root-missing',
+  'workspace-root-replaced',
+  'workspace-root-binding-incomplete',
+  'workspace-root-enrollment-pending',
+]);
+
+function physicalDirectory(rootPath) {
+  try {
+    const stats = fs.lstatSync(rootPath);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) return null;
+    return {
+      kind: 'folder',
+      deviceId: String(stats.dev),
+      inode: String(stats.ino),
+      dev: String(stats.dev),
+      ino: String(stats.ino),
+    };
+  } catch (error) {
+    if (isPathAbsentError(error)) return null;
+    throw error;
+  }
+}
+
+function inspectWorkspaceRoot(workspace, database) {
+  const rootPath = path.resolve(workspace?.path || '');
+  const row = workspace?.id
+    ? database.prepare(`
+        SELECT device_id, inode
+        FROM workspace_nodes
+        WHERE workspace_id = ? AND id = ?
+      `).get(workspace.id, workspace.id)
+    : null;
+  const expectedDeviceId = row?.device_id == null ? null : String(row.device_id);
+  const expectedInode = row?.inode == null ? null : String(row.inode);
+  const actual = physicalDirectory(rootPath);
+
+  if ((expectedDeviceId == null) !== (expectedInode == null)) {
+    return {
+      state: 'held',
+      reason: 'workspace-root-binding-incomplete',
+      workspaceId: workspace.id,
+      rootPath,
+      expected: { deviceId: expectedDeviceId, inode: expectedInode },
+      actual,
+    };
+  }
+  if (expectedDeviceId == null) {
+    return {
+      state: 'unbound',
+      workspaceId: workspace.id,
+      rootPath,
+      actual,
+    };
+  }
+  if (!actual) {
+    return {
+      state: 'held',
+      reason: fs.existsSync(rootPath)
+        ? 'workspace-root-replaced'
+        : 'workspace-root-missing',
+      workspaceId: workspace.id,
+      rootPath,
+      expected: { deviceId: expectedDeviceId, inode: expectedInode },
+      actual: null,
+    };
+  }
+  if (
+    actual.deviceId !== expectedDeviceId
+    || actual.inode !== expectedInode
+  ) {
+    return {
+      state: 'held',
+      reason: 'workspace-root-replaced',
+      workspaceId: workspace.id,
+      rootPath,
+      expected: { deviceId: expectedDeviceId, inode: expectedInode },
+      actual,
+    };
+  }
+  return {
+    state: 'verified',
+    workspaceId: workspace.id,
+    rootPath,
+    identity: actual,
+  };
+}
+
+function rootBindingError(proof) {
+  const reason = proof?.reason || (
+    proof?.state === 'unbound'
+      ? 'workspace-root-enrollment-pending'
+      : 'workspace-root-replaced'
+  );
+  return Object.assign(
+    new Error(`workspace tree root is not verified: ${reason}`),
+    {
+      code: 'WORKSPACE_TREE_ROOT_UNVERIFIED',
+      reason,
+      statusCode: 409,
+      paths: proof?.rootPath ? [proof.rootPath] : [],
+      proof,
+    },
+  );
+}
+
+function requireVerifiedWorkspaceRoot(workspace, database) {
+  const proof = inspectWorkspaceRoot(workspace, database);
+  if (proof.state !== 'verified') throw rootBindingError(proof);
+  return proof;
+}
+
+module.exports = {
+  ROOT_HOLD_REASONS,
+  inspectWorkspaceRoot,
+  physicalDirectory,
+  requireVerifiedWorkspaceRoot,
+  rootBindingError,
+};