amalgm 0.1.161 → 0.1.162

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

@@ -62,6 +62,10 @@ function ensureProjectMemory(workspace, source = 'workspace') {
   }
 }
 
+function enrollWorkspaceTree(workspace) {
+  return require('./tree-store').enrollWorkspace(workspace.id);
+}
+
 async function uniqueProjectPath(workspaceRoot, requestedName) {
   const name = sanitizeProjectName(requestedName);
   let candidate = path.join(workspaceRoot, name);
@@ -211,6 +215,7 @@ async function handleProjectRegister(body, sendJson) {
       source: 'workspace:register',
     });
     ensureProjectMemory(workspace, 'workspace:register');
+    const tree = enrollWorkspaceTree(workspace);
 
     sendJson(200, {
       success: true,
@@ -219,6 +224,7 @@ async function handleProjectRegister(body, sendJson) {
       name: workspace.name,
       uri: workspace.uri,
       workspaceRoot,
+      tree: { nodes: tree.nodes.length, created: tree.created },
     });
   } catch (error) {
     sendJson(500, {
@@ -302,6 +308,7 @@ async function handleImport(body, sendJson) {
         source: 'workspace:import',
       });
       ensureProjectMemory(workspace, 'workspace:import');
+      const tree = enrollWorkspaceTree(workspace);
       sendJson(200, {
         success: true,
         path: workspace.path,
@@ -309,6 +316,7 @@ async function handleImport(body, sendJson) {
         workspace,
         workspaceRoot,
         alreadyInWorkspace: true,
+        tree: { nodes: tree.nodes.length, created: tree.created },
       });
       return;
     }
@@ -333,6 +341,7 @@ async function handleImport(body, sendJson) {
       source: 'workspace:import',
     });
     ensureProjectMemory(workspace, 'workspace:import');
+    const tree = enrollWorkspaceTree(workspace);
 
     sendJson(200, {
       success: true,
@@ -341,6 +350,7 @@ async function handleImport(body, sendJson) {
       workspace,
       workspaceRoot,
       alreadyInWorkspace: false,
+      tree: { nodes: tree.nodes.length, created: tree.created },
     });
   } catch (error) {
     sendJson(500, {
@@ -380,7 +390,15 @@ async function handleClone(body, sendJson) {
         source: 'workspace:clone',
       });
       ensureProjectMemory(workspace, 'workspace:clone');
-      sendJson(200, { success: true, path: workspace.path, workspace, workspaceRoot, alreadyExists: true });
+      const tree = enrollWorkspaceTree(workspace);
+      sendJson(200, {
+        success: true,
+        path: workspace.path,
+        workspace,
+        workspaceRoot,
+        alreadyExists: true,
+        tree: { nodes: tree.nodes.length, created: tree.created },
+      });
       return;
     }
     sendJson(409, {
@@ -416,8 +434,16 @@ async function handleClone(body, sendJson) {
     source: 'workspace:clone',
   });
   ensureProjectMemory(workspace, 'workspace:clone');
+  const tree = enrollWorkspaceTree(workspace);
 
-  sendJson(200, { success: true, path: workspace.path, workspace, workspaceRoot, alreadyExists: false });
+  sendJson(200, {
+    success: true,
+    path: workspace.path,
+    workspace,
+    workspaceRoot,
+    alreadyExists: false,
+    tree: { nodes: tree.nodes.length, created: tree.created },
+  });
 }
 
 async function handleBranches(query, sendJson) {
@@ -654,6 +680,8 @@ function handleWorkspaceSyncStats(sendJson) {
       cards: { total: cards.length, ...health },
       service: repoCardServiceStats(),
       wall: wallStats(),
+      checkpoints: require('./checkpoint').checkpointStats(),
+      reconciliation: require('./reconcile').reconciliationStats(),
     });
   } catch (error) {
     sendJson(500, { error: error instanceof Error ? error.message : 'Failed to read sync stats' });
@@ -685,6 +713,150 @@ function handleWorkspaceMachines(sendJson) {
   }
 }
 
+function sendWorkspaceDomainError(error, sendJson) {
+  sendJson(Number(error?.statusCode) || 500, {
+    error: error instanceof Error ? error.message : 'Workspace operation failed',
+  });
+}
+
+function handleTreeList(query, sendJson) {
+  try {
+    const pathInput = query?.path;
+    if (typeof pathInput === 'string' && pathInput) {
+      const found = require('./tree-store').nodeForPath(pathInput);
+      if (!found) throw Object.assign(new Error('workspace item not found'), { statusCode: 404 });
+      const actorUserId = require('./identity').userId();
+      sendJson(200, {
+        workspaceId: found.workspace.id,
+        workspace: found.workspace,
+        node: found.node,
+        access: actorUserId
+          ? require('./access-store').resolveAccess(found.node.id, actorUserId)
+          : null,
+      });
+      return;
+    }
+    const workspaceId = query?.workspaceId || query?.workspace_id;
+    if (typeof workspaceId !== 'string' || !workspaceId) throw Object.assign(new Error('workspaceId is required'), { statusCode: 400 });
+    sendJson(200, {
+      workspaceId,
+      nodes: require('./tree-store').listWorkspaceNodes(workspaceId, {
+        includeTrashed: query?.includeTrashed === 'true',
+        includePurged: query?.includePurged === 'true',
+        includeMissing: query?.includeMissing === 'true',
+      }),
+    });
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleTreeEnroll(body, sendJson) {
+  try {
+    sendJson(200, require('./tree-store').enrollWorkspace(body?.workspaceId || body?.path));
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleTreeMutation(body, sendJson) {
+  try {
+    const actorUserId = require('./identity').userId();
+    if (!actorUserId) throw Object.assign(new Error('this runtime is not enrolled to a user'), { statusCode: 401 });
+    const operation = body?.operation || body;
+    const accessNodeId = operation?.kind === 'tree.create' ? operation?.parentId : operation?.nodeId;
+    const access = require('./access-store').resolveAccess(accessNodeId, actorUserId);
+    if (!access?.role) throw Object.assign(new Error('tree operation is forbidden'), { statusCode: 403 });
+    sendJson(200, require('./tree-store').commitTreeOperation(operation, {
+      mutationId: body?.mutationId,
+      role: access.role,
+      source: 'workspace-tree:api',
+    }));
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+async function handleCloudWorkspaceAttachment(body, sendJson) {
+  let targetPath = null;
+  try {
+    const resourceId = typeof body?.workspaceId === 'string' ? body.workspaceId.toLowerCase() : '';
+    if (!require('./tree/identity').isUuid(resourceId)) {
+      throw Object.assign(new Error('workspaceId must be a UUID'), { statusCode: 400 });
+    }
+    const existing = require('../state/replicas').getReplicaByResourceId(resourceId);
+    if (existing) {
+      sendJson(200, { attached: true, duplicate: true, replica: existing });
+      return;
+    }
+    const workspaceRoot = await ensureWorkspaceRoot();
+    targetPath = await uniqueProjectPath(workspaceRoot, body?.name || 'Shared workspace');
+    await fs.promises.mkdir(targetPath, { recursive: false });
+    const attachment = require('../state/attachments').enqueueAttachment({
+      attachmentId: `att_${require('crypto').randomBytes(16).toString('base64url')}`,
+      resourceId,
+      localPath: targetPath,
+    }).attachment;
+    sendJson(202, { attached: false, duplicate: false, path: targetPath, attachment });
+  } catch (error) {
+    if (targetPath) {
+      try { await fs.promises.rmdir(targetPath); } catch { /* Preserve a non-empty or externally-touched folder. */ }
+    }
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleAccessRead(query, sendJson) {
+  try {
+    const actorUserId = require('./identity').userId();
+    const userId = query?.userId || actorUserId;
+    if (!actorUserId || !userId) throw Object.assign(new Error('userId is required'), { statusCode: 400 });
+    sendJson(200, { access: require('./access-store').resolveAccess(query?.nodeId, userId) });
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleAccessSet(body, sendJson) {
+  try {
+    const actorUserId = require('./identity').userId();
+    sendJson(200, require('./access-store').setNodePermission({
+      actorUserId,
+      nodeId: body?.nodeId,
+      userId: body?.userId,
+      role: body?.role,
+    }));
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleAccessClear(body, sendJson) {
+  try {
+    const actorUserId = require('./identity').userId();
+    sendJson(200, require('./access-store').clearNodePermission({
+      actorUserId,
+      nodeId: body?.nodeId,
+      userId: body?.userId,
+    }));
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
+function handleAccessRevokeUser(body, sendJson) {
+  try {
+    const actorUserId = require('./identity').userId();
+    sendJson(200, require('./access-store').revokeWorkspaceUser({
+      actorUserId,
+      workspaceId: body?.workspaceId,
+      userId: body?.userId,
+    }));
+  } catch (error) {
+    sendWorkspaceDomainError(error, sendJson);
+  }
+}
+
 module.exports = {
   getWorkspaceRoot,
   handleProjects,
@@ -703,4 +875,12 @@ module.exports = {
   handleRepoCardsRefresh,
   handleWorkspaceMachines,
   handleWorkspaceSyncStats,
+  handleTreeList,
+  handleTreeEnroll,
+  handleTreeMutation,
+  handleCloudWorkspaceAttachment,
+  handleAccessRead,
+  handleAccessSet,
+  handleAccessClear,
+  handleAccessRevokeUser,
 };

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

@@ -1,6 +1,5 @@
 'use strict';
 
-const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { AMALGM_COMPUTER_ID } = require('../config');
@@ -10,6 +9,7 @@ const {
   canonicalProjectPath,
   isLegacyManagedWorkspacePath,
 } = require('../../lib/project-paths');
+const { isUuidV7, uuidV7 } = require('./tree/identity');
 
 function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : '';
@@ -31,10 +31,6 @@ function workspaceUriForPath(localPath, computerId) {
   return `computer://${encodeURIComponent(stableComputerId(computerId))}${encodePathForUri(normalizedPath)}`;
 }
 
-function workspaceIdForUri(uri) {
-  return `ws_${crypto.createHash('sha256').update(uri).digest('hex').slice(0, 20)}`;
-}
-
 function isWithin(root, target) {
   const relative = path.relative(root, target);
   return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
@@ -73,7 +69,8 @@ function normalizeWorkspaceRecord(input, options = {}) {
   const resolvedPath = canonicalProjectPath(localPath);
   const computerId = stableComputerId(input.computerId || input.computer_id || options.computerId);
   const uri = cleanString(input.uri) || workspaceUriForPath(resolvedPath, computerId);
-  const id = cleanString(input.id) || workspaceIdForUri(uri);
+  const requestedId = cleanString(input.id);
+  const id = isUuidV7(requestedId) ? requestedId.toLowerCase() : uuidV7();
   const createdAt = cleanString(input.createdAt || input.created_at) || nowIso();
   const updatedAt = nowIso();
   const managed = input.managed !== undefined
@@ -104,6 +101,41 @@ function normalizeWorkspaceRecord(input, options = {}) {
   };
 }
 
+function workspaceRow(database, identifier) {
+  return database.prepare(`
+    SELECT workspaces.*
+    FROM workspaces
+    LEFT JOIN workspace_id_aliases ON workspace_id_aliases.workspace_id = workspaces.id
+    WHERE workspaces.id = ? OR workspaces.path = ? OR workspace_id_aliases.alias_id = ?
+    LIMIT 1
+  `).get(identifier, identifier, identifier) || null;
+}
+
+function ensureWorkspaceIdentityRows(database, workspace, options = {}) {
+  const now = workspace.createdAt || nowIso();
+  database.prepare(`
+    INSERT INTO workspace_nodes (
+      id, workspace_id, parent_id, kind, name, relative_path,
+      created_at, updated_at
+    ) VALUES (?, ?, NULL, 'folder', ?, '', ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      updated_at = excluded.updated_at
+  `).run(workspace.id, workspace.id, workspace.name, now, workspace.updatedAt);
+  database.prepare(`
+    INSERT OR IGNORE INTO workspace_access_state(workspace_id, authority_epoch)
+    VALUES (?, 1)
+  `).run(workspace.id);
+
+  const ownerUserId = options.seedOwner === false ? null : require('./identity').userId();
+  if (ownerUserId) {
+    database.prepare(`
+      INSERT OR IGNORE INTO workspace_node_permissions(workspace_id, node_id, user_id, role)
+      VALUES (?, ?, ?, 'owner')
+    `).run(workspace.id, workspace.id, ownerUserId);
+  }
+}
+
 function rowToWorkspace(row) {
   if (!row) return null;
   const parsed = parseJson(row.workspace_json, {});
@@ -165,9 +197,17 @@ function upsertWorkspace(input, options = {}) {
 
   db.transaction(() => {
     workspace = normalizeWorkspaceRecord(input, options);
-    const existing = db
-      .prepare('SELECT * FROM workspaces WHERE id = ? OR uri = ? OR path = ? LIMIT 1')
-      .get(workspace.id, workspace.uri, workspace.path);
+    const requestedId = cleanString(input.id);
+    const existing = db.prepare(`
+      SELECT workspaces.*
+      FROM workspaces
+      LEFT JOIN workspace_id_aliases ON workspace_id_aliases.workspace_id = workspaces.id
+      WHERE workspaces.id = ?
+         OR workspaces.uri = ?
+         OR workspaces.path = ?
+         OR workspace_id_aliases.alias_id = ?
+      LIMIT 1
+    `).get(workspace.id, workspace.uri, workspace.path, requestedId);
     if (existing) {
       const old = rowToWorkspace(existing);
       workspace = {
@@ -222,6 +262,14 @@ function upsertWorkspace(input, options = {}) {
       JSON.stringify(workspace),
     );
 
+    if (requestedId && requestedId !== workspace.id) {
+      db.prepare(`
+        INSERT OR IGNORE INTO workspace_id_aliases(alias_id, workspace_id)
+        VALUES (?, ?)
+      `).run(requestedId, workspace.id);
+    }
+    ensureWorkspaceIdentityRows(db, workspace, options);
+
     events = publishWorkspaceEvents(db, existing ? 'update' : 'insert', workspace, options.source || 'workspace:upsert');
   })();
 
@@ -238,7 +286,7 @@ function renameWorkspace(identifier, name, options = {}) {
   let events = [];
 
   db.transaction(() => {
-    const row = db.prepare('SELECT * FROM workspaces WHERE id = ? OR path = ? LIMIT 1').get(identifier, identifier);
+    const row = workspaceRow(db, identifier);
     if (!row) throw new Error('Workspace not found');
     workspace = {
       ...rowToWorkspace(row),
@@ -263,7 +311,7 @@ function removeWorkspace(identifier, options = {}) {
   let events = [];
 
   db.transaction(() => {
-    const row = db.prepare('SELECT * FROM workspaces WHERE id = ? OR path = ? LIMIT 1').get(identifier, identifier);
+    const row = workspaceRow(db, identifier);
     if (!row) return;
     workspace = rowToWorkspace(row);
     db.prepare('DELETE FROM workspaces WHERE id = ?').run(workspace.id);
@@ -280,6 +328,5 @@ module.exports = {
   removeWorkspace,
   renameWorkspace,
   upsertWorkspace,
-  workspaceIdForUri,
   workspaceUriForPath,
 };

package/runtime/scripts/amalgm-mcp/workspace/transition.js

@@ -0,0 +1,141 @@
+'use strict';
+
+/**
+ * Executed git movements — the one place the workspace layer changes a
+ * repository. `git.js` observes and never mutates; this module mutates
+ * and does nothing else, under the workspace-sync.md frozen boundaries:
+ * no shell, pinned cwd, no prompts, and config armor so repo-configured
+ * programs (hooks, fsmonitor) can never run under an executed transition.
+ *
+ * The verbs are deliberately few and exact — fetch one branch from a
+ * named remote, fast-forward to an exact commit, apply or reverse a
+ * captured patch. Anything messier is a human act on one machine; the
+ * rail carries its settled outcome. Every execution, success or failure,
+ * lands as one line in a visible journal before control returns.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const { AMALGM_DIR } = require('../config');
+
+const execFileAsync = promisify(execFile);
+
+const JOURNAL_FILE = path.join(AMALGM_DIR, 'state', 'workspace-transitions.jsonl');
+
+const TRANSITION_ENV = {
+  GIT_TERMINAL_PROMPT: '0',
+  LC_ALL: 'C',
+  GIT_CONFIG_COUNT: '2',
+  GIT_CONFIG_KEY_0: 'core.hooksPath',
+  GIT_CONFIG_VALUE_0: '/dev/null',
+  GIT_CONFIG_KEY_1: 'core.fsmonitor',
+  GIT_CONFIG_VALUE_1: 'false',
+};
+
+class TransitionError extends Error {
+  constructor(action, worktreeRoot, stderr) {
+    super(`${action} in ${worktreeRoot} failed: ${stderr}`);
+    this.name = 'TransitionError';
+    this.action = action;
+    this.worktreeRoot = worktreeRoot;
+    this.stderr = stderr;
+  }
+}
+
+function journal(entry) {
+  try {
+    fs.mkdirSync(path.dirname(JOURNAL_FILE), { recursive: true });
+    fs.appendFileSync(JOURNAL_FILE, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
+  } catch (error) {
+    console.warn('[WorkspaceTransition] journal write failed:', error.message);
+  }
+}
+
+async function run(action, worktreeRoot, args, { timeoutMs = 120_000 } = {}) {
+  try {
+    const { stdout } = await execFileAsync('git', args, {
+      cwd: worktreeRoot,
+      env: { ...process.env, ...TRANSITION_ENV },
+      timeout: timeoutMs,
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    journal({ action, worktree: worktreeRoot, args, ok: true });
+    return stdout;
+  } catch (error) {
+    const stderr = String(error.stderr ?? error.message).trim();
+    journal({ action, worktree: worktreeRoot, args, ok: false, error: stderr.slice(0, 500) });
+    throw new TransitionError(action, worktreeRoot, stderr);
+  }
+}
+
+/** Bring one branch's objects and remote-tracking ref in from a named remote. */
+function fetchBranch(worktreeRoot, remote, branch) {
+  return run('fetch-branch', worktreeRoot, [
+    '-C', worktreeRoot, 'fetch', '--no-tags', remote,
+    `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`,
+  ]);
+}
+
+/** Fast-forward the current branch to an exact commit. Refuses anything but a ff. */
+function fastForwardTo(worktreeRoot, oid) {
+  return run('fast-forward', worktreeRoot, ['-C', worktreeRoot, 'merge', '--ff-only', oid], {
+    timeoutMs: 60_000,
+  });
+}
+
+/**
+ * Apply a captured worktree patch — or reverse one — from a file on disk.
+ * The patch file lives outside the repo (in the state dir), so what was
+ * applied stays inspectable after the fact.
+ */
+function applyPatch(worktreeRoot, patchFile, { reverse = false } = {}) {
+  return run(reverse ? 'reverse-patch' : 'apply-patch', worktreeRoot, [
+    '-C', worktreeRoot, 'apply', ...(reverse ? ['-R'] : []), '--whitespace=nowarn', patchFile,
+  ], { timeoutMs: 60_000 });
+}
+
+/**
+ * Land a merged write set in a working tree — the coexistence engine's
+ * only mutation path. Each entry is { path, content, mode } (content a
+ * Buffer, mode '100644' | '100755' | '120000') or { path, content: null }
+ * for a deletion. Paths are confined to the worktree; the whole set lands
+ * as one journal line.
+ */
+function applyMergedFiles(worktreeRoot, writes, label) {
+  const root = path.resolve(worktreeRoot);
+  const written = [];
+  const removed = [];
+  try {
+    for (const write of writes) {
+      const abs = path.resolve(root, write.path);
+      if (abs !== root && !abs.startsWith(root + path.sep)) {
+        throw new Error(`unsafe path: ${write.path}`);
+      }
+      if (write.content === null) {
+        fs.rmSync(abs, { force: true });
+        removed.push(write.path);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      if (write.mode === '120000') {
+        fs.rmSync(abs, { force: true });
+        fs.symlinkSync(write.content.toString('utf8'), abs);
+      } else {
+        fs.writeFileSync(abs, write.content);
+        fs.chmodSync(abs, write.mode === '100755' ? 0o755 : 0o644);
+      }
+      written.push(write.path);
+    }
+    journal({ action: 'merge-files', worktree: root, label, written, removed, ok: true });
+  } catch (error) {
+    journal({
+      action: 'merge-files', worktree: root, label, written, removed, ok: false,
+      error: String(error.message).slice(0, 500),
+    });
+    throw new TransitionError('merge-files', root, String(error.message));
+  }
+}
+
+module.exports = { TransitionError, applyMergedFiles, applyPatch, fastForwardTo, fetchBranch };

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

@@ -0,0 +1,62 @@
+'use strict';
+
+const ROLES = Object.freeze(['owner', 'editor', 'viewer', 'no_access']);
+
+const CAPABILITIES = Object.freeze({
+  owner: Object.freeze([
+    'view',
+    'edit',
+    'create',
+    'rename',
+    'move',
+    'trash',
+    'restore',
+    'manage_access',
+    'purge',
+  ]),
+  editor: Object.freeze(['view', 'edit', 'create', 'rename', 'move', 'trash', 'restore']),
+  viewer: Object.freeze(['view', 'live_follow', 'download']),
+  no_access: Object.freeze([]),
+});
+
+function isRole(value) {
+  return ROLES.includes(value);
+}
+
+function capabilitiesForRole(role) {
+  return isRole(role) ? CAPABILITIES[role] : Object.freeze([]);
+}
+
+function can(role, capability) {
+  return capabilitiesForRole(role).includes(capability);
+}
+
+/**
+ * Resolve the closest explicit permission. `parentByNode` and `roleByNode`
+ * may be Maps or plain objects. Only explicit values are stored; absence means
+ * continue to the parent. A cycle or broken parent chain fails closed.
+ */
+function resolveEffectiveRole(nodeId, parentByNode, roleByNode) {
+  const parentOf = (id) => parentByNode instanceof Map ? parentByNode.get(id) : parentByNode?.[id];
+  const explicitRole = (id) => roleByNode instanceof Map ? roleByNode.get(id) : roleByNode?.[id];
+  const seen = new Set();
+  let current = nodeId;
+
+  while (current) {
+    if (seen.has(current)) return null;
+    seen.add(current);
+    const role = explicitRole(current);
+    if (role !== undefined) return isRole(role) ? role : null;
+    current = parentOf(current) || null;
+  }
+  return null;
+}
+
+module.exports = {
+  CAPABILITIES,
+  ROLES,
+  can,
+  capabilitiesForRole,
+  isRole,
+  resolveEffectiveRole,
+};

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

@@ -0,0 +1,53 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const UUID_V7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function bytesToUuid(bytes) {
+  const hex = Buffer.from(bytes).toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Mint an RFC 9562 UUIDv7. The timestamp makes offline-created nodes roughly
+ * creation ordered; the remaining 74 bits are random, so no coordinator is
+ * needed and the id never depends on a machine, path, or name.
+ */
+function uuidV7(now = Date.now(), randomBytes = crypto.randomBytes) {
+  if (!Number.isSafeInteger(now) || now < 0 || now > 0xffffffffffff) {
+    throw new TypeError('UUIDv7 timestamp must be an integer between 0 and 2^48 - 1');
+  }
+  const bytes = Buffer.from(randomBytes(16));
+  if (bytes.length !== 16) throw new TypeError('UUIDv7 random source must return 16 bytes');
+
+  let timestamp = BigInt(now);
+  for (let index = 5; index >= 0; index -= 1) {
+    bytes[index] = Number(timestamp & 0xffn);
+    timestamp >>= 8n;
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  return bytesToUuid(bytes);
+}
+
+function isUuid(value) {
+  return typeof value === 'string' && UUID_RE.test(value);
+}
+
+function isUuidV7(value) {
+  return typeof value === 'string' && UUID_V7_RE.test(value);
+}
+
+function uuidV7Timestamp(value) {
+  if (!isUuidV7(value)) return null;
+  return Number.parseInt(value.replaceAll('-', '').slice(0, 12), 16);
+}
+
+module.exports = {
+  isUuid,
+  isUuidV7,
+  uuidV7,
+  uuidV7Timestamp,
+};