amalgm 0.1.161 → 0.1.162

package/lib/shared-realtime-tunnel.js

@@ -369,9 +369,13 @@ function createSharedRealtimeTunnel({
       snapshotBase64: frame.snapshot_b64,
       contract: frame.contract,
       schemaVersion: frame.schema_version,
+      role: frame.role,
+      permissions: frame.permissions,
+      contentResources: frame.content_resources,
     }).then(() => {
       attachmentInflight.delete(frame.request_id);
       void joinReplicas();
+      scheduleAttachmentDrain();
     }).catch((error) => {
       void localStateJson('POST', '/state/shared/attachments/fail', {
         attachmentId: identity.attachmentId,
@@ -457,7 +461,11 @@ function createSharedRealtimeTunnel({
     const joinedResource = joinInflight.get(frame.request_id);
     if (joinedResource) {
       joinInflight.delete(frame.request_id);
-      if (frame.code === 'shared_tail_pruned' || frame.code === 'shared_tail_too_large') {
+      if (
+        frame.code === 'shared_tail_pruned'
+        || frame.code === 'shared_tail_too_large'
+        || frame.code === 'workspace_tree_snapshot_required'
+      ) {
         // The official tail can no longer reach this replica's cursor —
         // compaction pruned past it, or the gap outgrew incremental
         // recovery. Recover through a fresh snapshot attachment; its ack
@@ -547,6 +555,13 @@ function createSharedRealtimeTunnel({
       case 'shared.resource.attached':
         handleAttached(frame);
         return true;
+      case 'shared.resource.resync':
+        void localStateJson('POST', '/state/shared/replicas/rehydrate', {
+          resourceId: frame.resource_id,
+        }).then(() => scheduleAttachmentDrain()).catch((error) => {
+          warn(`shared tree resync request failed for ${frame.resource_id}: ${error?.message || error}`);
+        });
+        return true;
       case 'shared.mutation.committed':
         handleCommitted(frame);
         return true;
@@ -561,6 +576,20 @@ function createSharedRealtimeTunnel({
           headVersion: frame.head_version,
           contract: frame.contract,
           schemaVersion: frame.schema_version,
+        }).then(async (replica) => {
+          if (frame.contract === 'workspace-tree@1' && replica.authorityChanged) {
+            await localStateJson('POST', '/state/shared/replicas/rehydrate', {
+              resourceId: frame.resource_id,
+            });
+            scheduleAttachmentDrain();
+            return;
+          }
+          if (frame.contract !== 'workspace-tree@1' || !Array.isArray(frame.content_resources)) return;
+          await localStateJson('POST', '/state/shared/workspace-content/discover', {
+            workspaceId: frame.resource_id,
+            contentResources: frame.content_resources,
+          });
+          scheduleAttachmentDrain();
         }).catch(() => {});
         return true;
       case 'private.resource.ready':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.161",
+  "version": "0.1.162",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/fs/rest.js

@@ -704,6 +704,10 @@ async function handleWrite(body, sendJson) {
       ? Buffer.from(String(body.content), 'base64')
       : Buffer.from(String(body.content), 'utf-8');
 
+    const tree = require('../workspace/tree-store');
+    const existingNode = tree.nodeForPath(targetPath);
+    if (existingNode) tree.requirePathCapability(targetPath, 'edit');
+    else tree.commitPathCreate(targetPath, 'file', { source: 'fs:write:create' });
     await fs.promises.mkdir(path.dirname(targetPath), { recursive: true });
     await fs.promises.writeFile(targetPath, data);
     notifyProjectContextPathChanged(targetPath, 'fs:write');
@@ -720,7 +724,10 @@ async function handleDelete(body, sendJson) {
   try {
     const targetPath = await resolveSafePath(body.path);
     const stats = await fs.promises.lstat(targetPath).catch(() => null);
-    await fs.promises.rm(targetPath, { recursive: true, force: true });
+    const treeResult = require('../workspace/tree-store').commitPathTrash(targetPath, {
+      source: 'fs:trash',
+    });
+    if (!treeResult) await fs.promises.rm(targetPath, { recursive: true, force: true });
     notifyProjectContextPathChanged(targetPath, 'fs:delete');
     await publishFilesystemChange([targetPath], 'fs:delete');
     if (stats?.isDirectory()) {
@@ -732,7 +739,12 @@ async function handleDelete(body, sendJson) {
         source: 'fs:delete',
       });
     }
-    sendJson(200, { success: true, path: targetPath });
+    sendJson(200, {
+      success: true,
+      path: targetPath,
+      trashed: Boolean(treeResult),
+      nodeId: treeResult?.operation?.nodeId || null,
+    });
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Failed to delete';
     sendJson(statusForError(error), { error: message });
@@ -742,10 +754,12 @@ async function handleDelete(body, sendJson) {
 async function handleMkdir(body, sendJson) {
   try {
     const targetPath = await resolveSafePath(body.path, { forCreate: true });
-    await fs.promises.mkdir(targetPath, { recursive: true, mode: 0o755 });
+    const treeResult = require('../workspace/tree-store')
+      .commitPathCreate(targetPath, 'folder', { source: 'fs:mkdir' });
+    if (!treeResult) await fs.promises.mkdir(targetPath, { recursive: true, mode: 0o755 });
     await publishFilesystemChange([targetPath], 'fs:mkdir');
     await publishFilesResourceForPath(targetPath, 'fs:mkdir');
-    sendJson(200, { success: true, path: targetPath });
+    sendJson(200, { success: true, path: targetPath, nodeId: treeResult?.operation?.nodeId || null });
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Failed to create folder';
     sendJson(statusForError(error), { error: message });
@@ -757,8 +771,13 @@ async function handleRename(body, sendJson) {
     const oldPath = await resolveSafePath(body.oldPath);
     const newPath = await resolveSafePath(body.newPath, { forCreate: true });
     const stats = await fs.promises.lstat(oldPath).catch(() => null);
-    await fs.promises.mkdir(path.dirname(newPath), { recursive: true });
-    await fs.promises.rename(oldPath, newPath);
+    const treeResult = require('../workspace/tree-store').commitPathRename(oldPath, newPath, {
+      source: 'fs:rename',
+    });
+    if (!treeResult) {
+      await fs.promises.mkdir(path.dirname(newPath), { recursive: true });
+      await fs.promises.rename(oldPath, newPath);
+    }
     notifyProjectContextPathChanged(oldPath, 'fs:rename');
     notifyProjectContextPathChanged(newPath, 'fs:rename');
     await publishFilesystemChange([oldPath, newPath], 'fs:rename');
@@ -772,7 +791,7 @@ async function handleRename(body, sendJson) {
       });
       await publishFilesResourceForPath(newPath, 'fs:rename');
     }
-    sendJson(200, { success: true, oldPath, newPath });
+    sendJson(200, { success: true, oldPath, newPath, nodeId: treeResult?.operation?.nodeId || null });
   } catch (error) {
     const message = error instanceof Error ? error.message : 'Failed to rename';
     sendJson(statusForError(error), { error: message });

package/runtime/scripts/amalgm-mcp/index.js

@@ -128,7 +128,10 @@ async function boot() {
   startHealthMonitor();
   require('./state/ports').startPortsBridge();
   require('./workspace/cards').startRepoCardService();
+  require('./workspace/tree-store').startTreeEnrollmentService();
   require('./workspace/wall').startWallService();
+  require('./workspace/checkpoint').startCheckpointService();
+  require('./workspace/reconcile').startWorkspaceReconciler();
 }
 
 boot().catch((err) => {

package/runtime/scripts/amalgm-mcp/server/routes/state.js

@@ -103,6 +103,10 @@ async function handleStateRoutes(ctx) {
       await sharedRest.handleReplicaRehydrate(await ctx.readJsonBody(), ctx.sendJson);
       return true;
     }
+    if (ctx.pathname === '/state/shared/workspace-content/discover') {
+      await sharedRest.handleWorkspaceContentDiscover(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
     if (ctx.pathname === '/state/shared/promote') {
       await sharedRest.handlePromotionStart(await ctx.readJsonBody(), ctx.sendJson);
       return true;

package/runtime/scripts/amalgm-mcp/server/routes/workspace.js

@@ -67,6 +67,38 @@ async function handleWorkspaceRoutes(ctx) {
     workspaceRest.handleWorkspaceMachines(ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/workspace/tree' && ctx.method === 'GET') {
+    workspaceRest.handleTreeList(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/tree/enroll' && ctx.method === 'POST') {
+    workspaceRest.handleTreeEnroll(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/tree/mutations' && ctx.method === 'POST') {
+    workspaceRest.handleTreeMutation(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/cloud-attachments' && ctx.method === 'POST') {
+    await workspaceRest.handleCloudWorkspaceAttachment(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/access' && ctx.method === 'GET') {
+    workspaceRest.handleAccessRead(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/access' && ctx.method === 'PUT') {
+    workspaceRest.handleAccessSet(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/access' && ctx.method === 'DELETE') {
+    workspaceRest.handleAccessClear(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/access/revoke-user' && ctx.method === 'POST') {
+    workspaceRest.handleAccessRevokeUser(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   return false;
 }
 

package/runtime/scripts/amalgm-mcp/state/attachments.js

@@ -3,9 +3,9 @@
 const crypto = require('crypto');
 
 const { cachedStatement, openLocalDb } = require('./db');
+const { isSharedResourceId } = require('./cloud-resource-id');
 const { appendStateEvent } = require('./events');
 
-const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
 const ATTACHMENT_ID = /^[A-Za-z0-9_-]{16,160}$/;
 
 function invalid(message, statusCode = 400) {
@@ -40,7 +40,7 @@ function enqueueAttachment(input, options = {}) {
   const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
   const localPath = requiredText(input?.localPath, 'localPath');
   if (!ATTACHMENT_ID.test(attachmentId)) throw invalid('attachmentId has an invalid format');
-  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  if (!isSharedResourceId(resourceId)) throw invalid('resourceId must be a node UUID or legacy shared id');
   const database = options.database || openLocalDb();
   const existing = cachedStatement(
     database,
@@ -127,7 +127,9 @@ function acknowledgeAttachment(attachmentIdInput, payload, options = {}) {
     throw invalid('attachment response resource mismatch', 409);
   }
 
-  const installed = require('./docs').installCloudDocSnapshot(attachment.localPath, payload);
+  const installed = payload?.contract === 'workspace-tree@1'
+    ? require('../workspace/tree-store').installCloudTreeSnapshot(attachment.localPath, payload, { database })
+    : require('./docs').installCloudDocSnapshot(attachment.localPath, payload);
   const now = new Date().toISOString();
   cachedStatement(database, `
     UPDATE shared_resource_attachments
@@ -180,7 +182,7 @@ function failAttachment(attachmentIdInput, failure, options = {}) {
  */
 function requestRehydration(input, options = {}) {
   const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
-  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  if (!isSharedResourceId(resourceId)) throw invalid('resourceId must be a node UUID or legacy shared id');
   const database = options.database || openLocalDb();
   const replica = require('./replicas').getReplicaByResourceId(resourceId, { database });
   if (!replica) throw invalid(`shared resource ${resourceId} has no local replica`, 404);
@@ -248,7 +250,7 @@ function getAttachmentByResource(resourceId, options = {}) {
  */
 function retryAttachment(resourceIdInput, options = {}) {
   const resourceId = requiredText(resourceIdInput, 'resourceId', 132);
-  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  if (!isSharedResourceId(resourceId)) throw invalid('resourceId must be a node UUID or legacy shared id');
   const database = options.database || openLocalDb();
   const now = new Date().toISOString();
   const result = cachedStatement(database, `

package/runtime/scripts/amalgm-mcp/state/cloud-resource-id.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { isUuid } = require('../workspace/tree/identity');
+
+const LEGACY_SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const PRIVATE_RESOURCE_ID = /^pvr_[A-Za-z0-9_-]{16,128}$/;
+
+function isSharedResourceId(value) {
+  return typeof value === 'string' && (LEGACY_SHARED_RESOURCE_ID.test(value) || isUuid(value));
+}
+
+function isCloudResourceId(value) {
+  return isSharedResourceId(value) || (typeof value === 'string' && PRIVATE_RESOURCE_ID.test(value));
+}
+
+module.exports = { isCloudResourceId, isSharedResourceId };

package/runtime/scripts/amalgm-mcp/state/db.js

@@ -532,6 +532,70 @@ function migrate(database = openLocalDb()) {
     CREATE INDEX IF NOT EXISTS workspaces_location_type_idx
       ON workspaces(location_type);
 
+    -- Permanent workspace/tree identity. A workspace's root node uses the
+    -- workspace UUID itself, so the root never acquires a second durable id.
+    CREATE TABLE IF NOT EXISTS workspace_id_aliases (
+      alias_id TEXT PRIMARY KEY,
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS workspace_id_aliases_workspace_idx
+      ON workspace_id_aliases(workspace_id);
+
+    CREATE TABLE IF NOT EXISTS workspace_nodes (
+      id TEXT PRIMARY KEY,
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      parent_id TEXT REFERENCES workspace_nodes(id) ON UPDATE CASCADE,
+      kind TEXT NOT NULL CHECK (kind IN ('folder', 'file', 'symlink')),
+      name TEXT NOT NULL,
+      relative_path TEXT NOT NULL,
+      symlink_target TEXT,
+      device_id TEXT,
+      inode TEXT,
+      trashed_at TEXT,
+      purged_at TEXT,
+      missing_at TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK ((id = workspace_id AND parent_id IS NULL AND relative_path = '')
+        OR (id <> workspace_id AND parent_id IS NOT NULL AND relative_path <> ''))
+    );
+
+    DROP INDEX IF EXISTS workspace_nodes_live_path_idx;
+    CREATE UNIQUE INDEX workspace_nodes_live_path_idx
+      ON workspace_nodes(workspace_id, relative_path)
+      WHERE purged_at IS NULL AND missing_at IS NULL AND trashed_at IS NULL;
+
+    CREATE INDEX IF NOT EXISTS workspace_nodes_parent_idx
+      ON workspace_nodes(workspace_id, parent_id);
+
+    CREATE INDEX IF NOT EXISTS workspace_nodes_inode_idx
+      ON workspace_nodes(workspace_id, device_id, inode)
+      WHERE device_id IS NOT NULL AND inode IS NOT NULL AND purged_at IS NULL;
+
+    CREATE TABLE IF NOT EXISTS workspace_access_state (
+      workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      authority_epoch INTEGER NOT NULL DEFAULT 1 CHECK (authority_epoch > 0),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS workspace_node_permissions (
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      node_id TEXT NOT NULL REFERENCES workspace_nodes(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      user_id TEXT NOT NULL,
+      role TEXT NOT NULL CHECK (role IN ('owner', 'editor', 'viewer', 'no_access')),
+      permission_version INTEGER NOT NULL DEFAULT 1 CHECK (permission_version > 0),
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      revoked_at TEXT,
+      PRIMARY KEY (node_id, user_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS workspace_node_permissions_user_idx
+      ON workspace_node_permissions(user_id, workspace_id)
+      WHERE revoked_at IS NULL;
+
     CREATE TABLE IF NOT EXISTS repo_replicas (
       git_dir TEXT PRIMARY KEY,
       replica_id TEXT NOT NULL UNIQUE,
@@ -681,6 +745,16 @@ function ensureDocStatesSchema(database = openLocalDb()) {
   } catch {
     // Column already exists.
   }
+  try {
+    database.exec('ALTER TABLE doc_states ADD COLUMN node_id TEXT');
+  } catch {
+    // Column already exists.
+  }
+  database.exec(`
+    CREATE UNIQUE INDEX IF NOT EXISTS doc_states_node_id_idx
+      ON doc_states(node_id)
+      WHERE node_id IS NOT NULL;
+  `);
 }
 
 // App-registered resources (state/app-resources.js): the engine-side mirror

package/runtime/scripts/amalgm-mcp/state/docs.js

@@ -179,13 +179,23 @@ function liveEditsSinceLastDiskState(entry) {
 }
 
 function docResourceName(absolutePath) {
+  try {
+    const found = require('../workspace/tree-store').nodeForPath(absolutePath);
+    if (found?.node?.kind === 'file') return `${DOC_RESOURCE_PREFIX}${found.node.id}`;
+  } catch {
+    // Unenrolled files keep the legacy path-derived local resource.
+  }
   return `${DOC_RESOURCE_PREFIX}${fsPrivate().base64UrlEncode(absolutePath)}`;
 }
 
 function pathFromDocResource(resource) {
   if (typeof resource !== 'string' || !resource.startsWith(DOC_RESOURCE_PREFIX)) return null;
+  const identity = resource.slice(DOC_RESOURCE_PREFIX.length);
+  if (require('../workspace/tree/identity').isUuid(identity)) {
+    return require('../workspace/tree-store').absolutePathForNode(identity);
+  }
   try {
-    return fsPrivate().base64UrlDecode(resource.slice(DOC_RESOURCE_PREFIX.length));
+    return fsPrivate().base64UrlDecode(identity);
   } catch {
     return null;
   }
@@ -282,6 +292,16 @@ function spliceDocText(Y, entry, nextText, source) {
   return { mutationId: newMutationId(), update: origin.patch.yjs, bytes: null };
 }
 
+function canCurrentUserEditDoc(entry) {
+  if (!entry.nodeId) return true;
+  const role = require('../workspace/access-store').currentUserRole(entry.nodeId);
+  return require('../workspace/tree/access').can(role, 'edit');
+}
+
+function requireCurrentUserDocEdit(entry) {
+  if (!canCurrentUserEditDoc(entry)) throw invalid('document edit is forbidden', 403);
+}
+
 /**
  * The one door. Every locally produced document edit — a client Yjs update,
  * a whole-text API write, a disk reconcile — becomes exactly one journal
@@ -361,14 +381,16 @@ function publishConflictOnly(entry, source) {
 // through it.
 function persistDocState(Y, entry) {
   cachedStatement(openLocalDb(), `
-    INSERT INTO doc_states (path, state, updated_at, last_disk_hash)
-    VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), ?)
+    INSERT INTO doc_states (path, node_id, state, updated_at, last_disk_hash)
+    VALUES (?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), ?)
     ON CONFLICT(path) DO UPDATE SET
+      node_id = excluded.node_id,
       state = excluded.state,
       updated_at = excluded.updated_at,
       last_disk_hash = excluded.last_disk_hash
   `).run(
     entry.path,
+    entry.nodeId,
     Buffer.from(Y.encodeStateAsUpdate(entry.doc)),
     entry.lastDiskHash,
   );
@@ -475,6 +497,11 @@ function reconcileFromDisk(Y, entry) {
     // of disk (write-back still debounced) would "reconcile" the stale disk
     // text back over live edits. (This is also the THEIRS === BASE no-op.)
     if (onDisk === entry.lastDiskText) return;
+    if (!canCurrentUserEditDoc(entry)) {
+      entry.heldDiskChange = { reason: 'forbidden', at: new Date().toISOString() };
+      return;
+    }
+    entry.heldDiskChange = null;
     const ytext = entry.doc.getText(TEXT_KEY);
     const ours = ytext.toString();
     const base = entry.lastDiskText;
@@ -548,6 +575,18 @@ function reconcileFromDisk(Y, entry) {
 function seedFromDisk(Y, entry, persisted) {
   const knownHash = persisted?.last_disk_hash;
   if (!knownHash) {
+    if (!canCurrentUserEditDoc(entry)) {
+      try {
+        const onDisk = fs.readFileSync(entry.path, 'utf8');
+        const origin = { amalgmMutation: true, source: 'doc:read-only-seed', patch: null };
+        spliceTextInto(Y, entry.doc, entry.doc.getText(TEXT_KEY), onDisk, origin);
+        setLastDiskText(entry, onDisk, 'open');
+        persistDocState(Y, entry);
+      } catch {
+        // Unreadable/deleted: same posture as reconcile — stop following disk.
+      }
+      return;
+    }
     reconcileFromDisk(Y, entry);
     return;
   }
@@ -720,9 +759,17 @@ function loadDocEntry(pathInput) {
   ensureDocStatesSchema(database);
 
   const doc = new Y.Doc();
+  let nodeId = null;
+  try {
+    const found = require('../workspace/tree-store').nodeForPath(resolved);
+    nodeId = found?.node?.kind === 'file' ? found.node.id : null;
+  } catch {
+    // The document remains available even when tree enrollment is unavailable.
+  }
   const entry = {
     path: resolved,
     resource: docResourceName(resolved),
+    nodeId,
     doc,
     reconcileTimer: null,
     diskWriteTimer: null,
@@ -745,7 +792,14 @@ function loadDocEntry(pathInput) {
     pathAliases: new Set([pathInput]),
   };
 
-  let persisted = cachedStatement(database, 'SELECT state, last_disk_hash FROM doc_states WHERE path = ?').get(resolved) || null;
+  let persisted = nodeId
+    ? cachedStatement(database, `
+      SELECT state, last_disk_hash FROM doc_states
+      WHERE node_id = ? OR path = ?
+      ORDER BY CASE WHEN node_id = ? THEN 0 ELSE 1 END
+      LIMIT 1
+    `).get(nodeId, resolved, nodeId) || null
+    : cachedStatement(database, 'SELECT state, last_disk_hash FROM doc_states WHERE path = ?').get(resolved) || null;
   if (persisted?.state) {
     try {
       Y.applyUpdate(doc, new Uint8Array(persisted.state), 'persisted');
@@ -772,6 +826,10 @@ function loadDocEntry(pathInput) {
   // that merely lags our persisted state (the process died inside the disk
   // write debounce) gets the doc written back out — never spliced over it.
   seedFromDisk(Y, entry, persisted);
+  if (nodeId) {
+    cachedStatement(database, 'UPDATE doc_states SET node_id = ?, path = ? WHERE node_id = ? OR path = ?')
+      .run(nodeId, resolved, nodeId, resolved);
+  }
 
   // A process can die after the durable journal insert but before Y.Doc/file
   // materialization or event projection. Replay those exact operation IDs
@@ -797,6 +855,7 @@ function openDoc(pathInput) {
   const entry = loadDocEntry(pathInput);
   return {
     resource: entry.resource,
+    nodeId: entry.nodeId,
     path: entry.path,
     state: Buffer.from(Y.encodeStateAsUpdate(entry.doc)).toString('base64'),
     // The versioned-write handshake: hash of the exact current text; a writer
@@ -865,6 +924,7 @@ function writeDocText(pathInput, textInput, options = {}) {
 
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
+  requireCurrentUserDocEdit(entry);
   // Every respond() below acknowledges saved state, so it must stand on a
   // settled journal — most pointedly the noop return: a retry of a write
   // whose disk flush failed finds the text already in memory, and without
@@ -972,6 +1032,7 @@ function applyDocMutations(pathInput, mutationsInput) {
   if (mutations.length === 0) return { applied: 0, seq: currentSeq(), mutationIds: [] };
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
+  requireCurrentUserDocEdit(entry);
   const results = mutations.map((mutation) => commitDocMutation(Y, entry, mutation, 'doc:update'));
 
   return {
@@ -1125,6 +1186,60 @@ function getDocText(pathInput) {
   return entry.doc.getText(TEXT_KEY).toString();
 }
 
+/**
+ * Repoint persisted and open document materializations after tree identity
+ * moved. The resource remains doc:<node UUID>; only the local path changes.
+ */
+function rebindNodePaths(changes) {
+  const database = openLocalDb();
+  ensureDocStatesSchema(database);
+  for (const change of changes || []) {
+    if (!change?.nodeId || !change?.newPath || change.oldPath === change.newPath) continue;
+    database.transaction(() => {
+      database.prepare('UPDATE doc_states SET path = ? WHERE node_id = ? OR path = ?')
+        .run(change.newPath, change.nodeId, change.oldPath);
+      database.prepare('UPDATE shared_resource_replicas SET local_path = ?, updated_at = ? WHERE local_resource = ? OR local_path = ?')
+        .run(change.newPath, new Date().toISOString(), `${DOC_RESOURCE_PREFIX}${change.nodeId}`, change.oldPath);
+      database.prepare('UPDATE shared_resource_promotions SET local_path = ?, updated_at = ? WHERE local_resource = ? OR local_path = ?')
+        .run(change.newPath, new Date().toISOString(), `${DOC_RESOURCE_PREFIX}${change.nodeId}`, change.oldPath);
+      database.prepare('UPDATE shared_resource_attachments SET local_path = ?, updated_at = ? WHERE local_path = ?')
+        .run(change.newPath, new Date().toISOString(), change.oldPath);
+    })();
+
+    const entry = Array.from(openDocs.values()).find((candidate) => (
+      candidate.nodeId === change.nodeId || candidate.path === change.oldPath
+    ));
+    if (!entry) continue;
+    unwatchDocFile(entry);
+    openDocs.delete(entry.path);
+    entry.path = change.newPath;
+    entry.nodeId = change.nodeId;
+    entry.resource = `${DOC_RESOURCE_PREFIX}${change.nodeId}`;
+    entry.pathAliases.add(change.newPath);
+    resolvedPathCache.set(change.newPath, change.newPath);
+    openDocs.set(change.newPath, entry);
+    watchDocFile(loadYjs(), entry);
+  }
+}
+
+function closeDocByNode(nodeId) {
+  const entry = Array.from(openDocs.values()).find((candidate) => candidate.nodeId === nodeId);
+  if (!entry) return false;
+  closeDocEntry(loadYjs(), entry);
+  return true;
+}
+
+function closeDocsByNodeIds(nodeIds) {
+  const ids = nodeIds instanceof Set ? nodeIds : new Set(nodeIds || []);
+  let closed = 0;
+  for (const entry of Array.from(openDocs.values())) {
+    if (!entry.nodeId || !ids.has(entry.nodeId)) continue;
+    closeDocEntry(loadYjs(), entry);
+    closed += 1;
+  }
+  return closed;
+}
+
 /** Test/shutdown helper: flush and close every open document. */
 function closeAllDocs() {
   let Y;
@@ -1141,6 +1256,8 @@ module.exports = {
   applyCloudDocMutation,
   applyDocMutations,
   applyDocUpdates,
+  closeDocByNode,
+  closeDocsByNodeIds,
   closeAllDocs,
   docResourceName,
   getDocText,
@@ -1148,6 +1265,7 @@ module.exports = {
   openDoc,
   pathFromDocResource,
   readDocResource,
+  rebindNodePaths,
   writeDocText,
   // Test hooks only — not part of the module contract.
   _private: { openDocs },

package/runtime/scripts/amalgm-mcp/state/migrations.js

@@ -110,9 +110,71 @@ function removeInheritedHarnessTools(database) {
   }
 }
 
+function migrateWorkspaceIds(database) {
+  const { isUuidV7, uuidV7 } = require('../workspace/tree/identity');
+  const rows = database.prepare('SELECT * FROM workspaces').all();
+
+  database.transaction(() => {
+    for (const row of rows) {
+      if (isUuidV7(row.id)) continue;
+      let workspaceId = uuidV7();
+      while (database.prepare('SELECT 1 FROM workspaces WHERE id = ?').get(workspaceId)) {
+        workspaceId = uuidV7();
+      }
+
+      let workspaceJson = {};
+      try {
+        workspaceJson = JSON.parse(row.workspace_json || '{}');
+      } catch {
+        // Typed columns remain authoritative when legacy JSON is malformed.
+      }
+      workspaceJson.id = workspaceId;
+
+      database.prepare(`
+        UPDATE workspaces
+        SET id = ?, workspace_json = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE id = ?
+      `).run(workspaceId, JSON.stringify(workspaceJson), row.id);
+      database.prepare(`
+        INSERT OR IGNORE INTO workspace_id_aliases(alias_id, workspace_id)
+        VALUES (?, ?)
+      `).run(row.id, workspaceId);
+      database.prepare('UPDATE project_context SET project_id = ? WHERE project_id = ?')
+        .run(workspaceId, row.id);
+    }
+
+    database.prepare(`
+      INSERT OR IGNORE INTO workspace_nodes (
+        id, workspace_id, parent_id, kind, name, relative_path, created_at, updated_at
+      )
+      SELECT id, id, NULL, 'folder', name, '', created_at, updated_at
+      FROM workspaces
+    `).run();
+    database.prepare(`
+      INSERT OR IGNORE INTO workspace_access_state(workspace_id, authority_epoch)
+      SELECT id, 1 FROM workspaces
+    `).run();
+  })();
+}
+
+function backfillLocalWorkspaceOwners(database) {
+  const ownerUserId = require('../workspace/identity').userId();
+  if (!ownerUserId) return;
+  database.prepare(`
+    INSERT OR IGNORE INTO workspace_node_permissions (
+      workspace_id, node_id, user_id, role
+    )
+    SELECT id, id, ?, 'owner'
+    FROM workspaces
+    WHERE source <> 'cloud'
+  `).run(ownerUserId);
+}
+
 function runLegacyMigrations(database) {
   migrateLegacyToolboxTables(database);
   removeInheritedHarnessTools(database);
+  migrateWorkspaceIds(database);
+  backfillLocalWorkspaceOwners(database);
 }
 
 module.exports = { runLegacyMigrations };