amalgm 0.1.161 → 0.1.162

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

@@ -0,0 +1,666 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { openLocalDb } = require('../state/db');
+const { applyTreeOperation } = require('./tree/reducer');
+const { can } = require('./tree/access');
+const { relativeWorkspacePath, shouldEnroll, shouldSync } = require('./tree/inclusion');
+const {
+  hasAncestorInSet,
+  materializeOperation,
+  persistNodes,
+  relativePathForNode,
+  rowToNode,
+  workspaceRow,
+} = require('./tree/local-state');
+const { normalizeTreeOperation } = require('./tree/operations');
+const { uuidV7 } = require('./tree/identity');
+
+const TREE_RESOURCE_PREFIX = 'workspace-tree:';
+
+function invalid(message, statusCode = 400) {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function workspaceForPath(absolutePath, database = openLocalDb()) {
+  const resolved = path.resolve(absolutePath);
+  return database.prepare(`
+    SELECT * FROM workspaces
+    WHERE path IS NOT NULL
+      AND (? = path OR substr(?, 1, length(path) + 1) = path || ?)
+    ORDER BY length(path) DESC
+    LIMIT 1
+  `).get(resolved, resolved, path.sep) || null;
+}
+
+function listWorkspaceNodes(workspaceId, options = {}) {
+  const database = options.database || openLocalDb();
+  const clauses = ['workspace_id = ?'];
+  if (options.includeMissing !== true) clauses.push('missing_at IS NULL');
+  if (options.includePurged !== true) clauses.push('purged_at IS NULL');
+  if (options.includeTrashed !== true) clauses.push('trashed_at IS NULL');
+  return database.prepare(`
+    SELECT * FROM workspace_nodes
+    WHERE ${clauses.join(' AND ')}
+    ORDER BY length(relative_path), relative_path
+  `).all(workspaceId).map(rowToNode);
+}
+
+function nodeForPath(absolutePath, options = {}) {
+  const database = options.database || openLocalDb();
+  const workspace = workspaceForPath(absolutePath, database);
+  if (!workspace) return null;
+  const relativePath = path.resolve(absolutePath) === path.resolve(workspace.path)
+    ? ''
+    : relativeWorkspacePath(workspace.path, path.resolve(absolutePath));
+  if (relativePath == null) return null;
+  const row = database.prepare(`
+    SELECT * FROM workspace_nodes
+    WHERE workspace_id = ? AND relative_path = ?
+      AND missing_at IS NULL AND purged_at IS NULL AND trashed_at IS NULL
+    LIMIT 1
+  `).get(workspace.id, relativePath);
+  const node = rowToNode(row);
+  return node ? { workspace, node } : null;
+}
+
+function absolutePathForNode(nodeId, options = {}) {
+  const database = options.database || openLocalDb();
+  const row = database.prepare(`
+    SELECT workspace_nodes.*, workspaces.path AS workspace_path
+    FROM workspace_nodes
+    JOIN workspaces ON workspaces.id = workspace_nodes.workspace_id
+    WHERE workspace_nodes.id = ?
+  `).get(nodeId);
+  if (!row || row.purged_at || row.missing_at) return null;
+  return row.relative_path
+    ? path.join(row.workspace_path, ...row.relative_path.split('/'))
+    : row.workspace_path;
+}
+
+function statIdentity(stats) {
+  return { deviceId: String(stats.dev), inode: String(stats.ino) };
+}
+
+function scanDirectory(rootPath) {
+  const entries = [];
+  const visit = (directory, parentRelativePath) => {
+    const children = fs.readdirSync(directory, { withFileTypes: true })
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const child of children) {
+      const relativePath = parentRelativePath ? `${parentRelativePath}/${child.name}` : child.name;
+      if (!shouldEnroll(relativePath)) continue;
+      const absolutePath = path.join(directory, child.name);
+      const stats = fs.lstatSync(absolutePath);
+      const kind = stats.isSymbolicLink() ? 'symlink' : stats.isDirectory() ? 'folder' : 'file';
+      entries.push({
+        relativePath,
+        parentRelativePath,
+        name: child.name,
+        kind,
+        symlinkTarget: kind === 'symlink' ? fs.readlinkSync(absolutePath) : null,
+        ...statIdentity(stats),
+      });
+      if (kind === 'folder') visit(absolutePath, relativePath);
+    }
+  };
+  visit(rootPath, '');
+  return entries;
+}
+
+/**
+ * Enroll current disk state without turning a path into identity. Existing
+ * paths retain their UUID; a same-filesystem rename is recognized by inode;
+ * new nodes receive UUIDv7. Missing nodes are held as missing, never silently
+ * deleted, so an offline or transient filesystem gap cannot erase history.
+ */
+function enrollWorkspace(identifier, options = {}) {
+  const database = options.database || openLocalDb();
+  const workspace = workspaceRow(identifier, database);
+  if (!workspace) throw invalid('workspace not found', 404);
+  const rootPath = path.resolve(workspace.path || '');
+  const rootStats = fs.statSync(rootPath);
+  if (!rootStats.isDirectory()) throw invalid('workspace path is not a folder', 409);
+
+  const scanned = scanDirectory(rootPath);
+  const existing = database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id);
+  const byPath = new Map(existing.map((row) => [row.relative_path, row]));
+  const byIdentity = new Map();
+  for (const row of existing) {
+    if (!row.device_id || !row.inode || row.purged_at) continue;
+    const key = `${row.device_id}:${row.inode}`;
+    const matches = byIdentity.get(key) || [];
+    matches.push(row);
+    byIdentity.set(key, matches);
+  }
+
+  const nodeIdByPath = new Map([['', workspace.id]]);
+  const seenIds = new Set([workspace.id]);
+  const renamed = [];
+  let created = 0;
+  const now = new Date().toISOString();
+
+  database.transaction(() => {
+    database.prepare(`
+      UPDATE workspace_nodes
+      SET name = ?, device_id = ?, inode = ?, missing_at = NULL, updated_at = ?
+      WHERE id = ?
+    `).run(workspace.name, String(rootStats.dev), String(rootStats.ino), now, workspace.id);
+
+    for (const entry of scanned) {
+      const parentId = nodeIdByPath.get(entry.parentRelativePath);
+      if (!parentId) throw invalid(`missing enrolled parent for ${entry.relativePath}`, 500);
+      let row = byPath.get(entry.relativePath) || null;
+      if (!row) {
+        const inodeMatches = byIdentity.get(`${entry.deviceId}:${entry.inode}`) || [];
+        const eligible = inodeMatches.filter((candidate) => !seenIds.has(candidate.id));
+        if (eligible.length === 1) row = eligible[0];
+      }
+
+      const id = row?.id || uuidV7();
+      nodeIdByPath.set(entry.relativePath, id);
+      seenIds.add(id);
+      if (row) {
+        if (row.relative_path !== entry.relativePath) {
+          renamed.push({
+            nodeId: id,
+            oldPath: path.join(rootPath, ...row.relative_path.split('/')),
+            newPath: path.join(rootPath, ...entry.relativePath.split('/')),
+          });
+        }
+        database.prepare(`
+          UPDATE workspace_nodes
+          SET parent_id = ?, kind = ?, name = ?, relative_path = ?,
+              symlink_target = ?, device_id = ?, inode = ?, missing_at = NULL,
+              updated_at = ?
+          WHERE id = ?
+        `).run(
+          parentId,
+          entry.kind,
+          entry.name,
+          entry.relativePath,
+          entry.symlinkTarget,
+          entry.deviceId,
+          entry.inode,
+          now,
+          id,
+        );
+      } else {
+        database.prepare(`
+          INSERT INTO workspace_nodes (
+            id, workspace_id, parent_id, kind, name, relative_path,
+            symlink_target, device_id, inode, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          id,
+          workspace.id,
+          parentId,
+          entry.kind,
+          entry.name,
+          entry.relativePath,
+          entry.symlinkTarget,
+          entry.deviceId,
+          entry.inode,
+          now,
+          now,
+        );
+        created += 1;
+      }
+    }
+
+    const markMissing = database.prepare(`
+      UPDATE workspace_nodes SET missing_at = ?, updated_at = ?
+      WHERE workspace_id = ? AND id = ? AND purged_at IS NULL AND trashed_at IS NULL
+    `);
+    for (const row of existing) {
+      if (row.id !== workspace.id && !seenIds.has(row.id)) {
+        markMissing.run(now, now, workspace.id, row.id);
+      }
+    }
+  })();
+
+  if (renamed.length) {
+    try {
+      require('../state/docs').rebindNodePaths(renamed);
+    } catch (error) {
+      console.warn('[WorkspaceTree] live document rebind after scan failed:', error?.message || error);
+    }
+  }
+  return { workspaceId: workspace.id, created, renamed: renamed.length, nodes: listWorkspaceNodes(workspace.id, { database }) };
+}
+
+function lstatOrNull(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function capabilityForOperation(kind) {
+  return {
+    'tree.create': 'create',
+    'tree.rename': 'rename',
+    'tree.move': 'move',
+    'tree.trash': 'trash',
+    'tree.restore': 'restore',
+    'tree.purge': 'purge',
+  }[kind];
+}
+
+function requirePathCapability(pathInput, capability, options = {}) {
+  const database = options.database || openLocalDb();
+  const targetPath = path.resolve(pathInput);
+  const workspace = workspaceForPath(targetPath, database);
+  if (!workspace) return null;
+
+  let currentPath = targetPath;
+  let found = null;
+  while (!found) {
+    found = nodeForPath(currentPath, { database });
+    if (found || currentPath === workspace.path) break;
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) break;
+    currentPath = parentPath;
+  }
+  if (!found) throw invalid('workspace root is not enrolled', 409);
+  const role = options.role || require('./access-store').currentUserRole(found.node.id, { database });
+  if (!can(role, capability)) throw invalid('workspace path operation is forbidden', 403);
+  return { ...found, role };
+}
+
+function commitTreeOperation(input, options = {}) {
+  let operation = normalizeTreeOperation(input);
+  const database = options.database || openLocalDb();
+  const accessNodeId = operation.kind === 'tree.create' ? operation.parentId : operation.nodeId;
+  const role = options.role || require('./access-store').currentUserRole(accessNodeId, { database });
+  if (!can(role, capabilityForOperation(operation.kind))) throw invalid('tree operation is forbidden', 403);
+  const workspace = workspaceRow(operation.workspaceId, database);
+  if (!workspace) throw invalid('workspace not found', 404);
+  const before = new Map(
+    database.prepare('SELECT * FROM workspace_nodes WHERE workspace_id = ?').all(workspace.id)
+      .map(rowToNode)
+      .map((node) => [node.id, node]),
+  );
+  if (operation.kind === 'tree.move' && !operation.previousParentId) {
+    operation = { ...operation, previousParentId: before.get(operation.nodeId)?.parentId || null };
+  }
+  const after = applyTreeOperation(before, operation);
+  const mutationId = options.mutationId || `mut_${crypto.randomBytes(16).toString('base64url')}`;
+  const localResource = `${TREE_RESOURCE_PREFIX}${workspace.id}`;
+  const targetBefore = before.get(operation.nodeId);
+  const targetAfter = after.get(operation.nodeId);
+  const targetRelativePath = targetBefore
+    ? relativePathForNode(before, targetBefore.id)
+    : targetAfter ? relativePathForNode(after, targetAfter.id) : '';
+  const replica = shouldSync(targetRelativePath)
+    ? require('../state/replicas').getReplicaByLocalResource(localResource, { database })
+    : null;
+  let paths = null;
+
+  const result = require('../state/mutations').commitLocalMutation({
+    channelId: replica ? `resource:${replica.resourceId}` : localResource,
+    localResource,
+    sharedResourceId: replica?.resourceId,
+    mutationId,
+    deviceId: replica ? process.env.AMALGM_DEVICE_ID : null,
+    authorityEpoch: replica?.authorityEpoch || 0,
+    baseCloudVersion: replica?.appliedVersion || 0,
+    contract: 'workspace-tree@1',
+    schemaVersion: 1,
+    operationKind: operation.kind,
+    operation,
+  }, {
+    database,
+    materialize() {
+      if (operation.kind === 'tree.trash' || operation.kind === 'tree.purge') {
+        const affectedNodeIds = new Set();
+        for (const node of before.values()) {
+          let current = node.id;
+          const seen = new Set();
+          while (current && !seen.has(current)) {
+            seen.add(current);
+            if (current === operation.nodeId) {
+              affectedNodeIds.add(node.id);
+              break;
+            }
+            current = before.get(current)?.parentId || null;
+          }
+        }
+        require('../state/docs').closeDocsByNodeIds(affectedNodeIds);
+      }
+      paths = options.diskAlreadyApplied === true
+        ? { oldPath: null, newPath: null }
+        : materializeOperation(workspace, before, after, operation);
+      database.transaction(() => {
+        paths.changedPaths = persistNodes(database, before, after, workspace.id);
+      })();
+    },
+    event: () => ({
+      resource: localResource,
+      op: 'update',
+      id: operation.nodeId,
+      patch: operation,
+      source: options.source || 'workspace-tree:local',
+    }),
+  });
+
+  const changedPaths = paths?.changedPaths || [];
+  if (changedPaths.length) require('../state/docs').rebindNodePaths(changedPaths);
+  return { operation, mutation: result.mutation, event: result.event, paths };
+}
+
+function commitPathRename(oldPathInput, newPathInput, options = {}) {
+  const database = options.database || openLocalDb();
+  let found = nodeForPath(oldPathInput, { database });
+  if (!found) {
+    const workspace = workspaceForPath(path.resolve(oldPathInput), database);
+    const relative = workspace ? relativeWorkspacePath(workspace.path, path.resolve(oldPathInput)) : null;
+    const stats = lstatOrNull(path.resolve(oldPathInput));
+    if (workspace && relative && shouldEnroll(relative) && stats) {
+      const nodeKind = stats.isSymbolicLink() ? 'symlink' : stats.isDirectory() ? 'folder' : 'file';
+      commitPathCreate(oldPathInput, nodeKind, {
+        ...options,
+        database,
+        symlinkTarget: nodeKind === 'symlink' ? fs.readlinkSync(path.resolve(oldPathInput)) : undefined,
+      });
+      found = nodeForPath(oldPathInput, { database });
+    }
+  }
+  if (!found) {
+    requirePathCapability(oldPathInput, 'rename', { ...options, database });
+    return null;
+  }
+  const newPath = path.resolve(newPathInput);
+  const relative = relativeWorkspacePath(found.workspace.path, newPath);
+  if (!relative || !shouldEnroll(relative)) throw invalid('rename destination must stay inside the workspace', 409);
+  const parentPath = path.dirname(newPath);
+  let parent = nodeForPath(parentPath, { database });
+  if (!parent) {
+    commitPathCreate(parentPath, 'folder', { ...options, database });
+    parent = nodeForPath(parentPath, { database });
+  }
+  if (!parent || parent.workspace.id !== found.workspace.id || parent.node.kind !== 'folder') {
+    throw invalid('rename destination folder is not enrolled', 409);
+  }
+  const name = path.basename(newPath);
+  if (parent.node.id === found.node.parentId) {
+    return commitTreeOperation({
+      kind: 'tree.rename',
+      workspaceId: found.workspace.id,
+      nodeId: found.node.id,
+      name,
+    }, { ...options, database });
+  }
+  return commitTreeOperation({
+    kind: 'tree.move',
+    workspaceId: found.workspace.id,
+    nodeId: found.node.id,
+    parentId: parent.node.id,
+    name,
+  }, { ...options, database });
+}
+
+function commitPathCreate(pathInput, nodeKind, options = {}) {
+  const targetPath = path.resolve(pathInput);
+  const database = options.database || openLocalDb();
+  const workspace = workspaceForPath(targetPath, database);
+  if (!workspace) return null;
+  const existingNode = nodeForPath(targetPath, { database });
+  if (existingNode) return null;
+
+  const diskEntry = lstatOrNull(targetPath);
+  if (diskEntry) {
+    const diskKind = diskEntry.isSymbolicLink() ? 'symlink' : diskEntry.isDirectory() ? 'folder' : 'file';
+    if (diskKind !== nodeKind) throw invalid(`create destination is a ${diskKind}, not a ${nodeKind}`, 409);
+  }
+
+  const parentPath = path.dirname(targetPath);
+  let parent = nodeForPath(parentPath, { database });
+  if (!parent && parentPath !== targetPath && parentPath !== path.dirname(workspace.path)) {
+    const { nodeId: _nodeId, symlinkTarget: _symlinkTarget, ...parentOptions } = options;
+    commitPathCreate(parentPath, 'folder', { ...parentOptions, database });
+    parent = nodeForPath(parentPath, { database });
+  }
+  if (!parent || parent.workspace.id !== workspace.id || parent.node.kind !== 'folder') {
+    throw invalid('create destination folder is not enrolled', 409);
+  }
+  return commitTreeOperation({
+    kind: 'tree.create',
+    workspaceId: workspace.id,
+    nodeId: options.nodeId || uuidV7(),
+    parentId: parent.node.id,
+    nodeKind,
+    name: path.basename(targetPath),
+    symlinkTarget: options.symlinkTarget,
+  }, {
+    ...options,
+    database,
+    diskAlreadyApplied: options.diskAlreadyApplied === true || Boolean(diskEntry),
+  });
+}
+
+function commitPathTrash(pathInput, options = {}) {
+  const database = options.database || openLocalDb();
+  let found = nodeForPath(pathInput, { database });
+  if (!found) {
+    const workspace = workspaceForPath(path.resolve(pathInput), database);
+    const relative = workspace ? relativeWorkspacePath(workspace.path, path.resolve(pathInput)) : null;
+    const stats = lstatOrNull(path.resolve(pathInput));
+    if (workspace && relative && shouldEnroll(relative) && stats) {
+      const nodeKind = stats.isSymbolicLink() ? 'symlink' : stats.isDirectory() ? 'folder' : 'file';
+      commitPathCreate(pathInput, nodeKind, {
+        ...options,
+        database,
+        symlinkTarget: nodeKind === 'symlink' ? fs.readlinkSync(path.resolve(pathInput)) : undefined,
+      });
+      found = nodeForPath(pathInput, { database });
+    }
+  }
+  if (!found) {
+    requirePathCapability(pathInput, 'trash', { ...options, database });
+    return null;
+  }
+  if (found.node.id === found.workspace.id) throw invalid('a workspace root cannot be trashed through the file API', 409);
+  return commitTreeOperation({
+    kind: 'tree.trash',
+    workspaceId: found.workspace.id,
+    nodeId: found.node.id,
+  }, { ...options, database });
+}
+
+function enrollRegisteredWorkspaces(options = {}) {
+  const database = options.database || openLocalDb();
+  const workspaces = database.prepare('SELECT id FROM workspaces ORDER BY created_at').all();
+  const results = [];
+  for (const workspace of workspaces) {
+    try {
+      const result = enrollWorkspace(workspace.id, { database });
+      ensureWorkspaceTreePromotion(workspace.id, { database });
+      results.push(result);
+    } catch (error) {
+      console.warn(`[WorkspaceTree] enrollment failed for ${workspace.id}:`, error?.message || error);
+    }
+  }
+  return results;
+}
+
+/**
+ * Turn tree changes made by shells, editors, and agents directly on disk into
+ * the same durable operations as the REST file API. File bytes remain the
+ * document rail's job; this observer only reconciles identity and structure.
+ */
+function reconcileWorkspaceTree(identifier, options = {}) {
+  const database = options.database || openLocalDb();
+  const workspace = workspaceRow(identifier, database);
+  if (!workspace || !fs.existsSync(workspace.path)) return { operations: [] };
+  const operations = [];
+  const held = [];
+  const heldNodeIds = new Set();
+  const heldPaths = new Set();
+  const source = options.source || 'workspace-tree:observed';
+
+  const applyObserved = (operation) => {
+    try {
+      const result = commitTreeOperation(operation, { database, source, diskAlreadyApplied: true });
+      operations.push(result.operation);
+      return true;
+    } catch (error) {
+      if (error?.statusCode !== 403) throw error;
+      held.push({ operation, reason: 'forbidden' });
+      return false;
+    }
+  };
+
+  const scanned = scanDirectory(workspace.path);
+  let rows = listWorkspaceNodes(workspace.id, {
+    database,
+    includeTrashed: true,
+    includeMissing: true,
+  });
+  const scannedByPath = new Map(scanned.map((entry) => [entry.relativePath, entry]));
+  const liveRows = rows.filter((node) => node.id !== workspace.id && !node.trashedAt && !node.purgedAt);
+  const liveByPath = new Map(liveRows.map((node) => [node.relativePath, node]));
+  const liveByInode = new Map();
+  for (const node of liveRows) {
+    if (!node.deviceId || !node.inode) continue;
+    const key = `${node.deviceId}:${node.inode}`;
+    const matches = liveByInode.get(key) || [];
+    matches.push(node);
+    liveByInode.set(key, matches);
+  }
+
+  const renamedIds = new Set();
+  for (const entry of scanned) {
+    if (liveByPath.has(entry.relativePath)) continue;
+    const matches = (liveByInode.get(`${entry.deviceId}:${entry.inode}`) || [])
+      .filter((node) => !renamedIds.has(node.id));
+    if (matches.length !== 1) continue;
+    const node = matches[0];
+    const rowsById = new Map(rows.map((item) => [item.id, item]));
+    if (hasAncestorInSet(node, rowsById, renamedIds)) continue;
+    const parent = nodeForPath(path.dirname(path.join(workspace.path, ...entry.relativePath.split('/'))), { database });
+    if (!parent) continue;
+    const applied = applyObserved(parent.node.id === node.parentId
+      ? { kind: 'tree.rename', workspaceId: workspace.id, nodeId: node.id, name: entry.name }
+      : { kind: 'tree.move', workspaceId: workspace.id, nodeId: node.id, parentId: parent.node.id, name: entry.name });
+    if (!applied) {
+      heldNodeIds.add(node.id);
+      heldPaths.add(entry.relativePath);
+      continue;
+    }
+    renamedIds.add(node.id);
+  }
+
+  for (const entry of scanned) {
+    if (heldPaths.has(entry.relativePath)) continue;
+    if (nodeForPath(path.join(workspace.path, ...entry.relativePath.split('/')), { database })) continue;
+    const parent = nodeForPath(
+      entry.parentRelativePath
+        ? path.join(workspace.path, ...entry.parentRelativePath.split('/'))
+        : workspace.path,
+      { database },
+    );
+    if (!parent) continue;
+    applyObserved({
+      kind: 'tree.create',
+      workspaceId: workspace.id,
+      nodeId: uuidV7(),
+      parentId: parent.node.id,
+      nodeKind: entry.kind,
+      name: entry.name,
+      symlinkTarget: entry.symlinkTarget,
+    });
+  }
+
+  rows = listWorkspaceNodes(workspace.id, { database });
+  const rowsById = new Map(rows.map((node) => [node.id, node]));
+  const missingIds = new Set(
+    rows
+      .filter((node) => node.id !== workspace.id && !scannedByPath.has(node.relativePath))
+      .filter((node) => !heldNodeIds.has(node.id))
+      .map((node) => node.id),
+  );
+  for (const node of rows) {
+    if (!missingIds.has(node.id) || hasAncestorInSet(node, rowsById, missingIds)) continue;
+    applyObserved({ kind: 'tree.trash', workspaceId: workspace.id, nodeId: node.id });
+  }
+  return { workspaceId: workspace.id, operations, held };
+}
+
+function reconcileRegisteredWorkspaceTrees(options = {}) {
+  const database = options.database || openLocalDb();
+  const results = [];
+  for (const workspace of database.prepare('SELECT id FROM workspaces ORDER BY created_at').all()) {
+    try {
+      results.push(reconcileWorkspaceTree(workspace.id, { database }));
+    } catch (error) {
+      console.warn(`[WorkspaceTree] observation failed for ${workspace.id}:`, error?.message || error);
+    }
+  }
+  return results;
+}
+
+let enrollmentStarted = false;
+function startTreeEnrollmentService() {
+  if (enrollmentStarted) return;
+  enrollmentStarted = true;
+  const timer = setTimeout(() => enrollRegisteredWorkspaces(), 0);
+  if (typeof timer.unref === 'function') timer.unref();
+  const observationTimer = setInterval(() => reconcileRegisteredWorkspaceTrees(), 2_000);
+  if (typeof observationTimer.unref === 'function') observationTimer.unref();
+  const promotionTimer = setInterval(() => {
+    try {
+      promoteEligibleWorkspaceTextFiles();
+    } catch (error) {
+      console.warn('[WorkspaceTree] text promotion pass failed:', error?.message || error);
+    }
+  }, 15_000);
+  if (typeof promotionTimer.unref === 'function') promotionTimer.unref();
+}
+
+function workspaceTreeSnapshot(workspaceId, options = {}) {
+  return require('./tree-cloud').workspaceTreeSnapshot(workspaceId, options);
+}
+
+function installCloudTreeSnapshot(pathInput, input, options = {}) {
+  return require('./tree-cloud').installCloudTreeSnapshot(pathInput, input, options);
+}
+
+function applyCloudTreeMutation(input, options = {}) {
+  return require('./tree-cloud').applyCloudTreeMutation(input, options);
+}
+
+function ensureWorkspaceTreePromotion(workspaceId, options = {}) {
+  return require('./tree-promotion').ensureWorkspaceTreePromotion(workspaceId, options);
+}
+
+function promoteEligibleWorkspaceTextFiles(options = {}) {
+  return require('./tree-promotion').promoteEligibleWorkspaceTextFiles(options);
+}
+
+module.exports = {
+  TREE_RESOURCE_PREFIX,
+  absolutePathForNode,
+  commitPathCreate,
+  commitPathRename,
+  commitPathTrash,
+  commitTreeOperation,
+  enrollWorkspace,
+  enrollRegisteredWorkspaces,
+  ensureWorkspaceTreePromotion,
+  installCloudTreeSnapshot,
+  listWorkspaceNodes,
+  nodeForPath,
+  startTreeEnrollmentService,
+  applyCloudTreeMutation,
+  promoteEligibleWorkspaceTextFiles,
+  reconcileRegisteredWorkspaceTrees,
+  reconcileWorkspaceTree,
+  requirePathCapability,
+  workspaceTreeSnapshot,
+  workspaceForPath,
+};