amalgm 0.1.137 → 0.1.138

package/runtime/scripts/amalgm-mcp/agent-bundles/bundles.js

@@ -9,6 +9,7 @@ const { hydrateConfigSkills } = require('../skills/store');
 const { defaultToolboxService } = require('../toolbox/service');
 const { exportAutomationEntry, installAutomationEntry } = require('./automation-entries');
 const { exportAppEntry, installAppEntry } = require('./app-entries');
+const { annotateAppBoundPaths, rewriteAppBoundPaths } = require('./tool-bindings');
 
 // Agent-only bundles keep the legacy kind so older runtimes can still install
 // them; bundles that carry automations or apps use the general kind so older
@@ -157,28 +158,7 @@ function scrubSecrets(value, path, requires) {
   return out;
 }
 
-function sourceBindingRequirements(tool, requires) {
-  const source = isObject(tool?.source) ? tool.source : {};
-  if (typeof source.cwd === 'string' && source.cwd.trim()) {
-    addUnique(requires.bindings, `tool:${tool.id}:cwd`);
-  }
-  for (const key of ['command', 'url', 'baseUrl', 'specUrl', 'specPath']) {
-    const value = source[key];
-    if (typeof value === 'string' && value.startsWith('/')) {
-      addUnique(requires.bindings, `tool:${tool.id}:source.${key}`);
-    }
-  }
-  if (Array.isArray(source.args)) {
-    source.args.forEach((arg, index) => {
-      if (typeof arg === 'string' && arg.startsWith('/')) {
-        addUnique(requires.bindings, `tool:${tool.id}:source.args[${index}]`);
-      }
-    });
-  }
-}
-
 function portableTool(tool, requires) {
-  sourceBindingRequirements(tool, requires);
   return scrubSecrets(cloneJson(tool), `tools.${tool.id}`, requires);
 }
 
@@ -626,14 +606,26 @@ function createBundle(input = {}, options = {}) {
   }
 
   const apps = [];
+  const appCwdBySourceId = new Map();
   let skippedAppFiles = 0;
   for (const appId of appIds) {
     const exported = exportAppEntry(appId);
     apps.push(exported.entry);
+    appCwdBySourceId.set(exported.entry.sourceAppId, exported.sourceCwd);
     skippedAppFiles += exported.skipped.length;
   }
 
   const { tools, toolActions } = collectToolRecords([...loadoutToolIds, ...toolIds], requires);
+
+  // Tool files that live inside a shared app travel with that app: record
+  // app-relative bindings so install rewrites them to the recipient's copy.
+  // Absolute paths no shared app covers stay machine-bound requirements.
+  for (const record of [...tools, ...toolActions]) {
+    if (record.origin === 'system') continue;
+    const kind = record.toolId ? 'toolAction' : 'tool';
+    const { unbound } = annotateAppBoundPaths(record, appCwdBySourceId);
+    for (const label of unbound) addUnique(requires.bindings, `${kind}:${record.id}:${label}`);
+  }
   // Standalone tool heads must resolve to a real catalog tool — a dependency
   // tool that is missing degrades to a placeholder, but a head cannot.
   const sharedToolIds = toolIds.filter((toolId) => tools.some((tool) => tool.id === toolId));
@@ -816,12 +808,19 @@ function validateBundle(bundle) {
   return withBundleGraph(bundle);
 }
 
-function installTools(bundle) {
+function installTools(bundle, appDirBySourceId = new Map()) {
+  const warnings = [];
+  const rewrite = (record) => {
+    const result = rewriteAppBoundPaths(record, appDirBySourceId);
+    warnings.push(...result.warnings);
+    return result.record;
+  };
+
   const toolActionsByToolId = new Map();
   for (const action of Array.isArray(bundle.toolActions) ? bundle.toolActions : []) {
     if (!action?.toolId) continue;
     const existing = toolActionsByToolId.get(action.toolId) || [];
-    existing.push(action);
+    existing.push(rewrite(action));
     toolActionsByToolId.set(action.toolId, existing);
   }
 
@@ -829,13 +828,13 @@ function installTools(bundle) {
   for (const tool of Array.isArray(bundle.tools) ? bundle.tools : []) {
     if (!tool?.id || tool.origin === 'system') continue;
     const result = defaultToolboxService.registerTool({
-      ...tool,
+      ...rewrite(tool),
       origin: tool.origin === 'catalog' ? 'catalog' : 'user',
       actions: toolActionsByToolId.get(tool.id) || [],
     });
     installed.push(result.tool);
   }
-  return installed;
+  return { installed, warnings };
 }
 
 function installBundleAgents(bundle, options = {}) {
@@ -897,34 +896,40 @@ function installBundleAgents(bundle, options = {}) {
 }
 
 function defaultAppsInstallRoot() {
-  const { getWorkspaceRoot } = require('../workspace/rest');
-  return getWorkspaceRoot();
+  // Installed apps are Amalgm-owned state: they live under the user's apps
+  // primitive root (<user dir>/apps), not in the projects workspace.
+  return require('../config').APPS_DIR;
 }
 
 /**
- * Install every primitive in a validated bundle: tools first (agents and
- * automations reference them), then agents, automations, and apps. Apps
- * materialize into the local workspace root, build, and start.
+ * Install every primitive in a validated bundle. Apps first — they
+ * materialize into the user's apps root, build, and start, and their
+ * installed directories anchor the app-bound tool path rewrites. Then tools
+ * (agents and automations reference them), agents, and automations.
  */
 async function installBundle(input, options = {}) {
   const bundle = validateBundle(input);
-  const installedTools = installTools(bundle);
-  const { idMap, installedAgents } = installBundleAgents(bundle, options);
-
-  const installedAutomations = [];
-  for (const entry of Array.isArray(bundle.automations) ? bundle.automations : []) {
-    installedAutomations.push(installAutomationEntry(entry, { source: 'agent-bundles:install' }));
-  }
 
   const installedApps = [];
+  const appDirBySourceId = new Map();
   const appEntries = Array.isArray(bundle.apps) ? bundle.apps : [];
   if (appEntries.length > 0) {
     const rootDir = options.appsRootDir || defaultAppsInstallRoot();
     for (const entry of appEntries) {
-      installedApps.push(await installAppEntry(entry, { rootDir, register: options.registerApp }));
+      const installed = await installAppEntry(entry, { rootDir, register: options.registerApp });
+      appDirBySourceId.set(appEntryId(entry), installed.cwd);
+      installedApps.push(installed);
     }
   }
 
+  const { installed: installedTools, warnings: bindingWarnings } = installTools(bundle, appDirBySourceId);
+  const { idMap, installedAgents } = installBundleAgents(bundle, options);
+
+  const installedAutomations = [];
+  for (const entry of Array.isArray(bundle.automations) ? bundle.automations : []) {
+    installedAutomations.push(installAutomationEntry(entry, { source: 'agent-bundles:install' }));
+  }
+
   return {
     ok: true,
     bundleId: bundle.bundleId,
@@ -934,7 +939,7 @@ async function installBundle(input, options = {}) {
     installedTools,
     installedAutomations,
     installedApps,
-    warnings: bundle.warnings || [],
+    warnings: [...(bundle.warnings || []), ...bindingWarnings],
   };
 }
 

package/runtime/scripts/amalgm-mcp/agent-bundles/tool-bindings.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * Portable bindings between toolbox tools and the apps that carry their files.
+ *
+ * A local CLI tool is only shareable if its files travel with the bundle. When
+ * a tool's cwd, command args, or guide/skill paths live inside a shared app's
+ * directory, export records app-relative bindings instead of trusting the
+ * sharer's absolute paths; install rewrites the bound fields against the
+ * freshly materialized app directory. Absolute paths no shared app covers are
+ * reported as binding requirements — the recipient must rebind those by hand.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BINDINGS_KEY = 'appPathBindings';
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** '' when target equals rootDir, a relative path when inside, null outside. */
+function relativeWithin(rootDir, target) {
+  const relative = path.relative(canonicalFsPath(rootDir), canonicalFsPath(target));
+  if (relative === '') return '';
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return relative;
+}
+
+function canonicalFsPath(value) {
+  try {
+    return fs.realpathSync.native(path.resolve(value));
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function getAtAddress(record, address) {
+  let current = record;
+  for (const step of address) {
+    if (current == null) return undefined;
+    current = current[step];
+  }
+  return current;
+}
+
+function setAtAddress(record, address, value) {
+  let current = record;
+  for (const step of address.slice(0, -1)) current = current[step];
+  current[address[address.length - 1]] = value;
+}
+
+function* deepStringAddresses(value, address) {
+  if (typeof value === 'string') {
+    yield [address, value];
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      yield* deepStringAddresses(value[index], [...address, index]);
+    }
+    return;
+  }
+  if (isObject(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      yield* deepStringAddresses(child, [...address, key]);
+    }
+  }
+}
+
+/** Every field of a tool/action record that may carry a local filesystem path. */
+function* pathCandidates(record) {
+  for (const section of ['source', 'sourceAction']) {
+    if (record[section] !== undefined) yield* deepStringAddresses(record[section], [section]);
+  }
+  for (const address of [['guidePath'], ['skillPath'], ['guide', 'path'], ['skill', 'path']]) {
+    const value = getAtAddress(record, address);
+    if (typeof value === 'string') yield [address, value];
+  }
+}
+
+function addressLabel(address) {
+  if (address.length === 2 && address[0] === 'source' && address[1] === 'cwd') return 'cwd';
+  return address.reduce(
+    (label, step) => (typeof step === 'number' ? `${label}[${step}]` : label ? `${label}.${step}` : String(step)),
+    '',
+  );
+}
+
+/**
+ * Record app-relative bindings on every tool/action whose absolute paths live
+ * under a shared app's source directory. Returns the requirement labels for
+ * the absolute paths no app covers (still machine-bound after install).
+ */
+function annotateAppBoundPaths(record, appCwdBySourceId) {
+  const bindings = [];
+  const unbound = [];
+
+  for (const [address, value] of pathCandidates(record)) {
+    if (!value.startsWith('/')) continue;
+    let bound = false;
+    for (const [appId, appCwd] of appCwdBySourceId) {
+      const relative = appCwd ? relativeWithin(appCwd, value) : null;
+      if (relative === null) continue;
+      bindings.push({ appId, path: address, relative });
+      bound = true;
+      break;
+    }
+    if (!bound) unbound.push(addressLabel(address));
+  }
+
+  if (bindings.length > 0) record[BINDINGS_KEY] = bindings;
+  return { unbound };
+}
+
+/**
+ * Rewrite a record's bound paths against the installed app directories.
+ * Returns warnings for bindings whose app is not part of this install; those
+ * fields keep the sharer's original path and stay machine-bound.
+ */
+function rewriteAppBoundPaths(record, appDirBySourceId) {
+  const bindings = Array.isArray(record[BINDINGS_KEY]) ? record[BINDINGS_KEY] : [];
+  if (bindings.length === 0) return { record, warnings: [] };
+
+  const rewritten = JSON.parse(JSON.stringify(record));
+  const warnings = [];
+  for (const binding of bindings) {
+    const appDir = appDirBySourceId.get(binding.appId);
+    if (!appDir) {
+      warnings.push(
+        `${record.id || 'tool'}: ${addressLabel(binding.path)} is bound to app ${binding.appId}, which is not part of this install`,
+      );
+      continue;
+    }
+    setAtAddress(rewritten, binding.path, binding.relative ? path.join(appDir, binding.relative) : appDir);
+  }
+  delete rewritten[BINDINGS_KEY];
+  return { record: rewritten, warnings };
+}
+
+module.exports = {
+  BINDINGS_KEY,
+  annotateAppBoundPaths,
+  rewriteAppBoundPaths,
+};

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

@@ -14,8 +14,10 @@ const PORT = parseInt(process.env.AMALGM_MCP_PORT || '8083', 10);
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 const CLI_HOMES_BACKFILL_ID = 'cli-homes-merge-v1';
 
-const AMALGM_DIR = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
-const AMALGM_HOME = process.env.AMALGM_HOME || path.join(os.homedir(), '.amalgm');
+// Layout-aware home: visible ~/amalgm once initialized, legacy ~/.amalgm
+// otherwise. Explicit env always wins (isolated runtimes, tests).
+const AMALGM_HOME = require('./lib/layout').resolveAmalgmHome(process.env);
+const AMALGM_DIR = process.env.AMALGM_DIR || AMALGM_HOME;
 const AMALGM_RUNTIME_LABEL = normalizeRuntimeLabel(process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH);
 const AMALGM_RUNTIME_STATE_DIR = process.env.AMALGM_RUNTIME_STATE_DIR
   || path.join(AMALGM_DIR, 'runtimes', AMALGM_RUNTIME_LABEL);

package/runtime/scripts/amalgm-mcp/lib/computer.js

@@ -39,7 +39,8 @@ function runtimeLabel() {
 }
 
 function candidateComputerFiles() {
-  const home = process.env.AMALGM_HOME || path.join(os.homedir(), '.amalgm');
+  const layout = require('./layout');
+  const home = layout.resolveAmalgmHome(process.env);
   const label = runtimeLabel();
   const files = [
     COMPUTER_RECORD_FILE,
@@ -48,9 +49,10 @@ function candidateComputerFiles() {
     path.join(home, 'computer.json'),
   ];
   if (AMALGM_USER_ID) {
+    const userDir = layout.resolveUserDir(home, AMALGM_USER_ID);
     files.push(
-      path.join(home, 'users', AMALGM_USER_ID, 'computer.json'),
-      path.join(home, 'users', AMALGM_USER_ID, 'runtimes', label, 'runtime-state.json'),
+      path.join(userDir, 'computer.json'),
+      path.join(userDir, 'runtimes', label, 'runtime-state.json'),
     );
   }
   return [...new Set(files)];

package/runtime/scripts/amalgm-mcp/lib/layout.js

@@ -0,0 +1,337 @@
+'use strict';
+
+/**
+ * Amalgm filesystem layout — the one module that knows where Amalgm state
+ * lives on a user's machine.
+ *
+ * Canonical layout (visible root):
+ *
+ *   ~/amalgm/
+ *     .amalgm-root.json          installation identity + user-folder index
+ *     users/
+ *       aayush@example.com/      human-readable folder name; NOT the identity
+ *         .amalgm-user.json      stable identity — userId is authoritative
+ *         agents/ apps/ automations/ toolbox/ workspaces/ ...
+ *
+ * Rules:
+ * - The folder name is presentation; `.amalgm-user.json` is identity. If a
+ *   folder is renamed, resolution recovers by scanning user manifests.
+ * - Legacy layouts (hidden ~/.amalgm, uuid-named user folders) keep working:
+ *   resolution falls back to them, and migrate-layout leaves compat symlinks
+ *   at the old locations.
+ * - Explicit env (AMALGM_HOME / AMALGM_DIR) always wins — isolated runtimes
+ *   and tests depend on that.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT_MANIFEST_NAME = '.amalgm-root.json';
+const USER_MANIFEST_NAME = '.amalgm-user.json';
+const LAYOUT_VERSION = 1;
+
+// Per-user roots for platform primitives. Everything Amalgm owns for a user
+// lives under one of these; anything else on disk is the user's own project.
+const PRIMITIVE_DIRS = Object.freeze([
+  'agents',
+  'apps',
+  'automations',
+  'toolbox',
+  'workspaces',
+]);
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch {
+    return null;
+  }
+}
+
+/** Same charset as runtime-identity's sanitizeScopeSegment — kept identical so
+ *  legacy uuid folders resolve to the exact names they were created with. */
+function sanitizeFolderSegment(value, fallback = 'local') {
+  const clean = String(value || '')
+    .trim()
+    .replace(/[^A-Za-z0-9_.@-]/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return clean || fallback;
+}
+
+/** Folder name for a user identified by email: lowercased, same charset. */
+function emailFolderName(email) {
+  return sanitizeFolderSegment(String(email || '').trim().toLowerCase(), '');
+}
+
+function visibleRootPath() {
+  return path.join(os.homedir(), 'amalgm');
+}
+
+function hiddenRootPath() {
+  return path.join(os.homedir(), '.amalgm');
+}
+
+function rootManifestPath(homeDir) {
+  return path.join(homeDir, ROOT_MANIFEST_NAME);
+}
+
+function userManifestPath(userDir) {
+  return path.join(userDir, USER_MANIFEST_NAME);
+}
+
+function isAmalgmRoot(dir) {
+  return fs.existsSync(rootManifestPath(dir));
+}
+
+/**
+ * Where Amalgm state lives on this machine.
+ *
+ * Order: explicit AMALGM_HOME → initialized visible root (~/amalgm with a
+ * root manifest) → migrated hidden alias (~/.amalgm symlink → its target) →
+ * legacy hidden root (~/.amalgm directory) → visible root for fresh installs.
+ */
+function resolveAmalgmHome(env = process.env) {
+  if (env.AMALGM_HOME) return path.resolve(env.AMALGM_HOME);
+
+  const visible = visibleRootPath();
+  if (isAmalgmRoot(visible)) return visible;
+
+  const hidden = hiddenRootPath();
+  const hiddenStat = lstatOrNull(hidden);
+  if (hiddenStat?.isSymbolicLink()) {
+    try {
+      const target = fs.realpathSync(hidden);
+      return samePath(target, visible) ? visible : target;
+    } catch {
+      return visible;
+    }
+  }
+  if (hiddenStat) return hidden;
+  return visible;
+}
+
+/** Compare paths through realpath so macOS aliases like /var → /private/var match. */
+function samePath(a, b) {
+  const canonical = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return canonical(a) === canonical(b);
+}
+
+function readRootManifest(homeDir) {
+  return readJson(rootManifestPath(homeDir), null);
+}
+
+function ensureRootManifest(homeDir) {
+  const existing = readRootManifest(homeDir);
+  if (existing?.installationId) return existing;
+  const manifest = {
+    schemaVersion: LAYOUT_VERSION,
+    installationId: existing?.installationId || crypto.randomBytes(8).toString('hex'),
+    createdAt: existing?.createdAt || new Date().toISOString(),
+    users: existing?.users || {},
+  };
+  writeJson(rootManifestPath(homeDir), manifest);
+  return manifest;
+}
+
+/** Record a user folder in the root manifest's index. The index is a cache —
+ *  user-manifest scans stay authoritative — but it makes the mapping legible. */
+function indexUserFolder(homeDir, folderName, { userId, email }) {
+  const manifest = ensureRootManifest(homeDir);
+  const entry = manifest.users?.[folderName];
+  if (entry?.userId === userId && (entry?.canonicalEmail || '') === (email || '')) return;
+  manifest.users = { ...manifest.users, [folderName]: { userId, canonicalEmail: email || '' } };
+  writeJson(rootManifestPath(homeDir), manifest);
+}
+
+function readUserManifest(userDir) {
+  const manifest = readJson(userManifestPath(userDir), null);
+  return typeof manifest?.userId === 'string' && manifest.userId.trim() ? manifest : null;
+}
+
+function writeUserManifest(userDir, { userId, email }) {
+  const existing = readUserManifest(userDir);
+  const canonicalEmail = String(email || existing?.canonicalEmail || '').trim().toLowerCase();
+  const emailHistory = Array.isArray(existing?.emailHistory) ? [...existing.emailHistory] : [];
+  if (canonicalEmail && !emailHistory.includes(canonicalEmail)) emailHistory.push(canonicalEmail);
+  const manifest = {
+    schemaVersion: LAYOUT_VERSION,
+    userId: String(userId).trim(),
+    canonicalEmail,
+    emailHistory,
+    createdAt: existing?.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  writeJson(userManifestPath(userDir), manifest);
+  return manifest;
+}
+
+/** All user folders under <homeDir>/users. Real directories first, compat
+ *  symlinks after, both sorted — so scans prefer canonical folders. */
+function listUserEntries(homeDir) {
+  const usersDir = path.join(homeDir, 'users');
+  let names = [];
+  try {
+    names = fs.readdirSync(usersDir);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const name of names.sort()) {
+    const dir = path.join(usersDir, name);
+    const stat = lstatOrNull(dir);
+    if (!stat) continue;
+    const isSymlink = stat.isSymbolicLink();
+    if (!isSymlink && !stat.isDirectory()) continue;
+    if (isSymlink && !fs.existsSync(dir)) continue; // broken link
+    entries.push({ name, dir, isSymlink, manifest: readUserManifest(dir) });
+  }
+  return [...entries.filter((e) => !e.isSymlink), ...entries.filter((e) => e.isSymlink)];
+}
+
+/** Find a user's folder by stable identity, regardless of its display name. */
+function findUserDirByUserId(homeDir, userId) {
+  const clean = String(userId || '').trim();
+  if (!clean) return null;
+  for (const entry of listUserEntries(homeDir)) {
+    if (entry.manifest?.userId === clean) return entry.dir;
+  }
+  return null;
+}
+
+/**
+ * Resolve the storage folder for a user scope (userId or 'local').
+ * Manifest identity wins; otherwise fall back to the legacy scope-named
+ * folder (which may itself be a compat symlink into the new layout).
+ */
+function resolveUserDir(homeDir, scope) {
+  const byId = findUserDirByUserId(homeDir, scope);
+  if (byId) return byId;
+  return path.join(homeDir, 'users', sanitizeFolderSegment(scope));
+}
+
+/**
+ * Ensure a user folder exists with its identity manifest. When the email is
+ * known the folder gets the readable email name (renaming a legacy uuid
+ * folder in place, leaving a compat symlink behind).
+ */
+function ensureUserDir(homeDir, { userId, email }) {
+  const cleanId = String(userId || '').trim();
+  if (!cleanId) throw new Error('ensureUserDir requires a userId');
+  const cleanEmail = String(email || '').trim().toLowerCase();
+
+  const existing = findUserDirByUserId(homeDir, cleanId);
+  if (existing) {
+    if (cleanEmail && readUserManifest(existing)?.canonicalEmail !== cleanEmail) {
+      return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    }
+    indexUserFolder(homeDir, path.basename(existing), { userId: cleanId, email: cleanEmail });
+    return existing;
+  }
+
+  const legacyDir = path.join(homeDir, 'users', sanitizeFolderSegment(cleanId));
+  if (lstatOrNull(legacyDir)?.isDirectory()) {
+    writeUserManifest(legacyDir, { userId: cleanId, email: cleanEmail });
+    if (cleanEmail) return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    indexUserFolder(homeDir, path.basename(legacyDir), { userId: cleanId, email: '' });
+    return legacyDir;
+  }
+
+  const folderName = (cleanEmail && emailFolderName(cleanEmail)) || sanitizeFolderSegment(cleanId);
+  const dir = path.join(homeDir, 'users', folderName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeUserManifest(dir, { userId: cleanId, email: cleanEmail });
+  indexUserFolder(homeDir, folderName, { userId: cleanId, email: cleanEmail });
+  return dir;
+}
+
+/**
+ * Give a user's folder its readable email name. Renames the current folder
+ * and leaves a relative compat symlink at the old name so recorded absolute
+ * paths keep resolving. Idempotent; refuses to stomp an unrelated folder.
+ */
+function adoptUserEmail(homeDir, { userId, email }) {
+  const cleanId = String(userId || '').trim();
+  const folderName = emailFolderName(email);
+  if (!cleanId || !folderName) throw new Error('adoptUserEmail requires userId and email');
+
+  const current = findUserDirByUserId(homeDir, cleanId)
+    || (lstatOrNull(path.join(homeDir, 'users', sanitizeFolderSegment(cleanId)))?.isDirectory()
+      ? path.join(homeDir, 'users', sanitizeFolderSegment(cleanId))
+      : null);
+  if (!current) throw new Error(`No storage folder found for user ${cleanId}`);
+
+  writeUserManifest(current, { userId: cleanId, email });
+  const target = path.join(homeDir, 'users', folderName);
+  if (path.basename(current) === folderName) {
+    indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+    return { dir: current, renamed: false };
+  }
+
+  const targetStat = lstatOrNull(target);
+  if (targetStat) {
+    const claimed = targetStat.isDirectory() ? readUserManifest(target)?.userId : null;
+    if (claimed !== cleanId) {
+      return { dir: current, renamed: false, conflict: folderName };
+    }
+    indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+    return { dir: target, renamed: false };
+  }
+
+  fs.renameSync(current, target);
+  fs.symlinkSync(folderName, current); // relative sibling link, relocatable
+  indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+  return { dir: target, renamed: true, from: current };
+}
+
+function userPrimitiveRoot(userDir, kind) {
+  if (!PRIMITIVE_DIRS.includes(kind)) {
+    throw new Error(`Unknown primitive root "${kind}". Use one of: ${PRIMITIVE_DIRS.join(', ')}`);
+  }
+  return path.join(userDir, kind);
+}
+
+module.exports = {
+  samePath,
+  LAYOUT_VERSION,
+  PRIMITIVE_DIRS,
+  ROOT_MANIFEST_NAME,
+  USER_MANIFEST_NAME,
+  adoptUserEmail,
+  emailFolderName,
+  ensureRootManifest,
+  ensureUserDir,
+  findUserDirByUserId,
+  hiddenRootPath,
+  isAmalgmRoot,
+  indexUserFolder,
+  listUserEntries,
+  readRootManifest,
+  readUserManifest,
+  resolveAmalgmHome,
+  resolveUserDir,
+  sanitizeFolderSegment,
+  userPrimitiveRoot,
+  visibleRootPath,
+  writeUserManifest,
+};