amalgm 0.1.257 → 0.1.258

package/runtime/scripts/amalgm-mcp/tests/entity-cloud.test.js

@@ -76,6 +76,37 @@ test('a signed-in registration is refused until the cloud entity resource is act
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 });
 
+test('entity-cloud status reports an unsettled catalog as catching up without repairing it', () => {
+  const db = new Database(':memory:');
+  const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
+  const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+
+  const current = cloud.status();
+  assert.equal(current.catalog.current, true);
+  assert.equal(current.catalog.records[0].uuid, root.uuid);
+  assert.equal(current.outbox.pending, 0);
+
+  const child = registry.create({ type: 'folder', parentUUID: root.uuid, name: 'child' });
+  const catchingUp = cloud.status();
+  assert.equal(catchingUp.catalog.current, false, 'an unacknowledged local mutation never masquerades as an active cloud head');
+  assert.equal(catchingUp.outbox.pending, 1);
+  assert.equal(catchingUp.catalog.records.some((record) => record.uuid === child.uuid), true,
+    'status may show the local catalog projection while naming it catching up');
+
+  const after = cloud.status();
+  assert.deepEqual(after, catchingUp, 'status is read-only: it does not claim, retry, or repair delivery');
+});
+
 test('a large registration replaces the complete graph in one cloud operation and a recipient waits for its compacted snapshot', () => {
   const db = new Database(':memory:');
   const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
@@ -244,7 +275,7 @@ test('a compacted remote snapshot enters the cloud catalog, not locally watched
   fs.rmSync(targetDir, { recursive: true, force: true });
 });
 
-test('add accepts only a catalog installed by the active compacted snapshot, never a snapshot plus a mutation tail', () => {
+test('add follows in-order mirrored mutations and refuses after a version gap until the compacted snapshot returns', () => {
   const sourceDb = new Database(':memory:');
   const sourceCloud = createEntityCloud({ db: sourceDb, userId: 'user-1', deviceId: 'source-device' });
   const sourceRegistry = createRegistry({ db: sourceDb, ephemeral: true, emit: () => {}, journal: sourceCloud.journal });
@@ -277,7 +308,7 @@ test('add accepts only a catalog installed by the active compacted snapshot, nev
       envelope: {
         resourceId,
         mutationId: 'ent_remote_change',
-        contract: 'amalgm-entity-registry@2',
+        contract: 'amalgm-entity-registry@3',
         schemaVersion: 1,
         operationKind: 'entity.upsert',
         operation: { kind: 'entity.upsert', record: changed },
@@ -286,25 +317,53 @@ test('add accepts only a catalog installed by the active compacted snapshot, nev
       committedAt: '2026-08-04T00:00:00.000Z',
     });
 
+    // Version 13 arrived in official order on a snapshot-consistent catalog:
+    // the catalog IS the compacted head, so add needs no re-download.
+    const inOrder = path.join(targetDir, 'in-order');
+    fs.mkdirSync(inOrder);
+    assert.equal(
+      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: inOrder }).headVersion,
+      13,
+      'an in-order mirrored mutation keeps the catalog materializable at the new head',
+    );
+
+    // Version 15 skips 14: the catalog can no longer prove it equals the
+    // head, so add refuses until a fresh compacted snapshot is installed.
+    const gapped = { ...changed, name: 'gapped.md', version: 'd'.repeat(64) };
+    targetCloud.ingest({
+      registry: targetRegistry,
+      envelope: {
+        resourceId,
+        mutationId: 'ent_remote_gap',
+        contract: 'amalgm-entity-registry@3',
+        schemaVersion: 1,
+        operationKind: 'entity.upsert',
+        operation: { kind: 'entity.upsert', record: gapped },
+      },
+      version: 15,
+      committedAt: '2026-08-04T00:00:01.000Z',
+    });
+    const afterGap = path.join(targetDir, 'after-gap');
+    fs.mkdirSync(afterGap);
     assert.throws(
-      () => targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }),
+      () => targetCloud.startMaterialization({ uuid: root.uuid, targetPath: afterGap }),
       /catalog is not pinned to the active cloud head/,
-      'the mutation updated live catalog facts, but not the snapshot barrier',
+      'a version gap drops the snapshot barrier until compaction returns',
     );
 
     const cloudRoot = initialSnapshot.records.find((record) => record.uuid === root.uuid);
-    const compactedBytes = Buffer.from(JSON.stringify(snapshotFromRecords([cloudRoot, changed])), 'utf8');
+    const compactedBytes = Buffer.from(JSON.stringify(snapshotFromRecords([cloudRoot, gapped])), 'utf8');
     targetCloud.install({
       registry: targetRegistry,
       resourceId,
       authorityEpoch: 3,
-      headVersion: 13,
+      headVersion: 15,
       snapshotBase64: compactedBytes.toString('base64'),
       snapshotChecksum: require('crypto').createHash('sha256').update(compactedBytes).digest('hex'),
     });
     assert.equal(
-      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }).headVersion,
-      13,
+      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: afterGap }).headVersion,
+      15,
       'the fresh compacted snapshot—not a history replay—makes add available again',
     );
   } finally {

package/runtime/scripts/amalgm-mcp/tests/entity-materialization.test.js

@@ -189,7 +189,7 @@ test('an added ordinary workspace stays live: a later cloud file head replaces l
       envelope: {
         resourceId: sourceCloud.identity().resourceId,
         mutationId: 'ent_remote_file_change',
-        contract: 'amalgm-entity-registry@2',
+        contract: 'amalgm-entity-registry@3',
         schemaVersion: 1,
         operationKind: 'entity.upsert',
         operation: { kind: 'entity.upsert', record: remoteRecord },
@@ -296,7 +296,7 @@ test('add preserves a symlink UUID and later retargets the same literal link wit
     const ingested = target.ingestCloudMutation({
       envelope: {
         resourceId: sourceCloud.identity().resourceId, mutationId: 'ent_remote_link_change',
-        contract: 'amalgm-entity-registry@2', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@3', schemaVersion: 1,
         operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: sourceRegistry.syncRecord(changed.uuid) },
       },
       version: 42, committedAt: '2026-08-05T00:00:00.000Z',
@@ -420,7 +420,7 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     const ingested = target.ingestCloudMutation({
       envelope: {
         resourceId: bootstrap.resourceId, mutationId: 'ent_remote_repo_change',
-        contract: 'amalgm-entity-registry@2', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@3', schemaVersion: 1,
         operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: remoteRecord },
       },
       version: 2, committedAt: '2026-08-05T00:00:00.000Z',

package/runtime/scripts/amalgm-mcp/tests/registration.service.test.js

@@ -54,6 +54,7 @@ const { ENTITIES_DIR, createRegistrationService, registrationService } = require
 const { adapterFor } = require('../adapters');
 const { createRuntimeHttpServer } = require('../server/http-service');
 const { createLocalServiceRouter } = require('../server/local-service-router');
+const { SYSTEM_TOOL_ARTIFACTS } = require('../lib/layout');
 
 const services = [];
 let server;
@@ -203,6 +204,7 @@ test('user-home bootstrap creates only declared roots and registers them through
       ['agents-root', 'exact'], ['apps-root', 'exact'], ['automations-root', 'exact'],
       ['toolbox-root', 'exact'], ['workspaces-root', 'exact'], ['system-root', 'exact'],
       ['home-manifest', 'exact'], ['defaults', 'exact'], ['policy', 'exact'],
+      ...SYSTEM_TOOL_ARTIFACTS.map((entry) => [entry.key, 'exact']),
     ],
   );
   for (const entry of bootstrapped.exactManaged) {
@@ -218,7 +220,7 @@ test('user-home bootstrap creates only declared roots and registers them through
   }
 
   const cloudRecords = await service.exactUserHomeCloudRecords();
-  assert.equal(cloudRecords.length, 9,
+  assert.equal(cloudRecords.length, 16,
     'the declared home is the entire graph eligible to repair a legacy empty cloud registry');
   assert.deepEqual(
     new Set(cloudRecords.map((record) => record.uuid)),
@@ -233,6 +235,46 @@ test('user-home bootstrap creates only declared roots and registers them through
   );
 });
 
+test('an upgraded declared home registers every built-in tool through Detect and Record', async () => {
+  const home = path.join(tempRoot, 'user-home-upgrade');
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-upgrade'),
+    homeDir: home,
+  });
+  services.push(service);
+
+  for (const root of ['agents', 'apps', 'automations', 'toolbox', 'workspaces', 'system']) {
+    fs.mkdirSync(path.join(home, root), { recursive: true });
+  }
+  fs.mkdirSync(path.join(home, 'system', 'defaults'));
+  fs.mkdirSync(path.join(home, 'system', 'policy'));
+  fs.writeFileSync(path.join(home, 'system', 'home.json'), JSON.stringify({
+    schemaVersion: 1,
+    kind: 'amalgm-user-home',
+    roots: [],
+    exactManaged: [],
+  }));
+  service.registration.addMany(['agents', 'apps', 'automations', 'toolbox', 'workspaces', 'system']
+    .map((root) => path.join(home, root)));
+
+  const bootstrapped = await service.bootstrapUserHome();
+  const toolbox = bootstrapped.roots.find((entry) => entry.key === 'toolbox');
+  const browser = bootstrapped.exactManaged.find((entry) => entry.key === 'amalgm-browser');
+  const manifest = bootstrapped.exactManaged.find((entry) => entry.key === 'home-manifest');
+  assert.equal(browser.record.parentUUID, toolbox.record.uuid,
+    'the declared browser tool is a real child of the existing toolbox root');
+  assert.equal(browser.record.type, 'file.text');
+  assert.equal(service.registration.registry.syncRecord(manifest.record.uuid).payloadVersion, require('crypto')
+    .createHash('sha256')
+    .update(fs.readFileSync(path.join(home, 'system', 'home.json')))
+    .digest('hex'), 'the rewritten exact manifest is observed before its cloud identity is returned');
+  for (const artifact of SYSTEM_TOOL_ARTIFACTS) {
+    assert.ok(fs.existsSync(path.join(home, artifact.relativePath)), `${artifact.key} is materialized`);
+    assert.ok(bootstrapped.exactManaged.some((entry) => entry.key === artifact.key),
+      `${artifact.key} is an exact managed entity`);
+  }
+});
+
 test('entity-cloud bootstrap publishes only the verified user home when an old local repo exists', async () => {
   const service = createRegistrationService({
     dir: path.join(tempRoot, 'state-user-home-cloud-boundary'),
@@ -248,13 +290,13 @@ test('entity-cloud bootstrap publishes only the verified user home when an old l
   });
 
   const records = await service.exactUserHomeCloudRecords();
-  assert.equal(records.length, 9);
+  assert.equal(records.length, 16);
   assert.equal(records.some((record) => record.uuid === oldRepo.uuid), false,
     'login never turns existing user-selected ground into an implicit cloud registration');
 
   const bootstrap = service.entityCloud.bootstrap(records);
   const snapshot = JSON.parse(Buffer.from(bootstrap.snapshotBase64, 'base64').toString('utf8'));
-  assert.equal(snapshot.records.length, 9);
+  assert.equal(snapshot.records.length, 16);
   service.entityCloud.install({
     registry: service.registration.registry,
     resourceId: bootstrap.resourceId,

package/runtime/scripts/amalgm-mcp/tests/system-catalog.test.js

@@ -35,7 +35,7 @@ test('system toolbox catalog exposes first-party default tools', () => {
   );
 });
 
-test('system toolbox catalog merge preserves persisted records', () => {
+test('system toolbox catalog merge preserves user records but keeps built-ins authoritative', () => {
   const merged = mergeSystemToolboxCatalog({
     version: 1,
     tools: {
@@ -59,12 +59,9 @@ test('system toolbox catalog merge preserves persisted records', () => {
     },
   });
 
-  assert.equal(merged.tools.browser.name, 'Persisted Browser');
+  assert.equal(merged.tools.browser.name, 'Browser');
   assert.equal(merged.tools['custom.cli'].name, 'Custom CLI');
-  assert.equal(
-    merged.toolActions['browser.browser_open'].name,
-    'persisted_navigate',
-  );
+  assert.equal(merged.toolActions['browser.browser_open'], undefined);
   assert.equal(merged.toolActions['apps.apps_list'].name, 'apps_list');
 });
 

package/runtime/scripts/amalgm-mcp/tests/toolbox-artifacts.test.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const {
+  SYSTEM_TOOL_ARTIFACTS,
+  artifactPathForTool,
+  isSystemToolId,
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+  readToolArtifacts,
+  writeToolArtifact,
+} = require('../toolbox/artifacts');
+
+function temporaryToolbox() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-toolbox-artifacts-'));
+  const toolboxDir = path.join(home, 'toolbox');
+  fs.mkdirSync(toolboxDir);
+  return { home, toolboxDir };
+}
+
+test('each built-in tool materializes as one distinct managed artifact', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    const first = materializeSystemToolArtifacts({ toolboxDir });
+    assert.deepEqual(first.changedRelativePaths, SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.relativePath));
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.deepEqual(Object.keys(catalog.tools).sort(), SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.toolId).sort());
+    for (const entry of SYSTEM_TOOL_ARTIFACTS) {
+      const tool = catalog.tools[entry.toolId];
+      assert.equal(tool.origin, 'system');
+      assert.equal(tool.owner, 'amalgm');
+      assert.deepEqual(tool.source, { transport: 'amalgm-runtime', service: 'mcp' },
+        'the cloud artifact has no machine-local port');
+      assert.equal(path.basename(artifactPathForTool(tool, { toolboxDir })), path.basename(entry.relativePath));
+      assert.equal(isSystemToolId(tool.id), true);
+    }
+    assert.deepEqual(materializeSystemToolArtifacts({ toolboxDir }).changedRelativePaths, [],
+      'rerunning login does not rewrite an unchanged built-in tool');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a user tool is a sibling artifact and remains independent of built-in ownership', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    materializeSystemToolArtifacts({ toolboxDir });
+    const tool = { id: 'aayush.stock-price', name: 'Stock Price', origin: 'user', owner: 'aayush' };
+    const actions = [{ id: 'aayush.stock-price.lookup', toolId: tool.id, name: 'lookup' }];
+    const target = writeToolArtifact({ tool, actions }, { toolboxDir });
+    assert.equal(path.basename(target), 'tool-aayush.stock-price.json');
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools[tool.id].origin, 'user');
+    assert.equal(catalog.toolActions[actions[0].id].toolId, tool.id);
+    assert.equal(isSystemToolId(tool.id), false);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a legacy aggregate catalog becomes user tool artifacts before leaving the registered toolbox tree', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    fs.writeFileSync(path.join(toolboxDir, 'toolbox.json'), JSON.stringify({
+      version: 1,
+      tools: {
+        'user.example': { id: 'user.example', name: 'Example', origin: 'user', owner: 'user' },
+      },
+      toolActions: {
+        'user.example.run': { id: 'user.example.run', toolId: 'user.example', name: 'run' },
+      },
+    }));
+    const migrated = migrateLegacyToolboxCatalog({ toolboxDir });
+    assert.equal(migrated.migrated, true);
+    assert.equal(fs.existsSync(path.join(toolboxDir, 'toolbox.json')), false);
+    assert.equal(fs.existsSync(path.join(home, 'toolbox.legacy.json')), true);
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools['user.example'].name, 'Example');
+    assert.equal(catalog.toolActions['user.example.run'].name, 'run');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/runtime/scripts/amalgm-mcp/tests/toolbox-cloud-registration.test.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * The full automatic rail for a user-created tool:
+ *
+ * toolbox API write → one sibling artifact → existing toolbox watcher
+ * → UUID registry → durable entity-cloud outbox.
+ *
+ * This must run in its own test file because AMALGM_DIR is intentionally read
+ * once by the runtime composition root.
+ */
+
+const assert = require('node:assert/strict');
+const Database = require('better-sqlite3');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-toolbox-cloud-'));
+process.env.AMALGM_DIR = home;
+
+const { createRegistrationService } = require('../registration/service');
+const { deleteTool, updateTool, upsertTool } = require('../toolbox/store');
+
+let service = null;
+
+test.after(() => {
+  service?.close();
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+async function waitFor(read, message) {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const value = read();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  assert.fail(message);
+}
+
+test('a user tool becomes a cloud-backed entity through the existing toolbox watcher', async () => {
+  service = createRegistrationService({
+    dir: path.join(home, 'entities'),
+    homeDir: home,
+    cloudUserId: '11111111-1111-4111-8111-111111111111',
+    cloudDeviceId: 'toolbox-cloud-proof-device',
+  });
+  const userHome = await service.bootstrapUserHome();
+  const bootstrapRecords = await service.exactUserHomeCloudRecords();
+  const bootstrap = service.entityCloud.bootstrap(bootstrapRecords);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+    bootstrapRecords,
+  });
+
+  assert.throws(() => updateTool({ id: 'browser', name: 'Changed Browser' }),
+    /System tools cannot be modified/);
+  assert.throws(() => deleteTool('browser'), /System tools cannot be deleted/);
+
+  upsertTool({
+    id: 'proof.stock',
+    name: 'Proof Stock',
+    type: 'cli',
+    origin: 'user',
+    owner: 'user',
+    source: { command: 'echo' },
+  });
+
+  const toolbox = userHome.roots.find((entry) => entry.key === 'toolbox').record;
+  const artifact = await waitFor(
+    () => service.registration.registry.activeAt(toolbox.uuid, 'tool-proof.stock.json'),
+    'the watcher did not register the user tool artifact',
+  );
+  assert.ok(fs.existsSync(path.join(home, 'toolbox', 'tool-proof.stock.json')));
+
+  const db = new Database(path.join(home, 'entities', 'identity.db'), { readonly: true });
+  try {
+    const rows = db.prepare('SELECT operation_json FROM entity_cloud_mutations').all();
+    assert.equal(rows.some((row) => JSON.parse(row.operation_json).record?.uuid === artifact.uuid), true,
+      'registration wrote one durable cloud delivery intent for the tool entity');
+  } finally {
+    db.close();
+  }
+});

package/runtime/scripts/amalgm-mcp/toolbox/artifacts.js

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * Toolbox filesystem artifacts.
+ *
+ * Purpose: one tool must have one cloud-addressable file, so a user-created
+ * tool can travel between machines without ever granting it the authority of
+ * a built-in Amalgm tool.
+ *
+ * Axioms:
+ * - A tool definition and every action belonging to it live in one artifact.
+ * - Built-in artifact paths are the exact managed nodes declared by layout.
+ * - User artifacts are siblings, never children of a managed tool path.
+ * - Portable artifacts never carry a machine-local address or watcher fact.
+ * - The SQLite toolbox tables and toolbox.index.json are local derived caches;
+ *   artifact files are the portable representation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { AMALGM_DIR } = require('../config');
+const { SYSTEM_TOOL_ARTIFACTS } = require('../lib/layout');
+const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+
+const TOOL_ARTIFACT_SCHEMA_VERSION = 1;
+const TOOLBOX_DIR = path.join(AMALGM_DIR, 'toolbox');
+const TOOLBOX_INDEX_FILE = path.join(AMALGM_DIR, 'toolbox.index.json');
+const LEGACY_TOOLBOX_FILE_NAME = 'toolbox.json';
+
+function safeToolId(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, '.')
+    .replace(/\.+/g, '.')
+    .replace(/^[._-]+|[._-]+$/g, '');
+}
+
+function systemArtifactForTool(toolId) {
+  return SYSTEM_TOOL_ARTIFACTS.find((entry) => entry.toolId === toolId) || null;
+}
+
+function isSystemToolId(toolId) {
+  return !!systemArtifactForTool(toolId);
+}
+
+function userArtifactFileName(toolId) {
+  const id = safeToolId(toolId);
+  if (!id) throw new Error('tool artifact requires a stable tool id');
+  return `tool-${id}.json`;
+}
+
+function toolboxDirFor(options = {}) {
+  return path.resolve(options.toolboxDir || TOOLBOX_DIR);
+}
+
+function indexFileFor(toolboxDir) {
+  return path.join(path.dirname(toolboxDir), 'toolbox.index.json');
+}
+
+function artifactPathForTool(tool, options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const toolId = safeToolId(tool?.id || tool);
+  const system = systemArtifactForTool(toolId);
+  if (system) return path.join(toolboxDir, path.basename(system.relativePath));
+  return path.join(toolboxDir, userArtifactFileName(toolId));
+}
+
+function artifactDocument({ tool, actions = [] }) {
+  if (!tool || typeof tool !== 'object' || !safeToolId(tool.id)) {
+    throw new Error('tool artifact requires a tool with an id');
+  }
+  const toolId = safeToolId(tool.id);
+  const normalizedActions = Array.isArray(actions)
+    ? actions.filter((action) => action && action.toolId === toolId)
+    : [];
+  const portableTool = isSystemToolId(toolId)
+    ? {
+        ...tool,
+        id: toolId,
+        // `127.0.0.1:<port>` is a device binding, not tool identity. The
+        // system catalog resolves the current runtime endpoint when serving
+        // the local tool surface.
+        source: { transport: 'amalgm-runtime', service: 'mcp' },
+      }
+    : { ...tool, id: toolId };
+  return {
+    schemaVersion: TOOL_ARTIFACT_SCHEMA_VERSION,
+    kind: 'amalgm-tool',
+    tool: portableTool,
+    actions: normalizedActions
+      .map((action) => ({ ...action, toolId }))
+      .sort((left, right) => String(left.id).localeCompare(String(right.id))),
+  };
+}
+
+function validDocument(value) {
+  return !!value
+    && value.schemaVersion === TOOL_ARTIFACT_SCHEMA_VERSION
+    && value.kind === 'amalgm-tool'
+    && value.tool
+    && typeof value.tool === 'object'
+    && !!safeToolId(value.tool.id)
+    && Array.isArray(value.actions)
+    && value.actions.every((action) => action && action.toolId === safeToolId(value.tool.id));
+}
+
+function writeToolArtifact({ tool, actions }, options = {}) {
+  const target = artifactPathForTool(tool, options);
+  ensureDir(path.dirname(target));
+  const document = artifactDocument({ tool, actions });
+  const current = readJson(target, null);
+  if (JSON.stringify(current) !== JSON.stringify(document)) writeJsonAtomic(target, document);
+  return target;
+}
+
+function removeUserToolArtifact(toolId, options = {}) {
+  if (isSystemToolId(safeToolId(toolId))) {
+    throw new Error('System tool artifacts cannot be removed');
+  }
+  const target = artifactPathForTool(toolId, options);
+  try { fs.unlinkSync(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return target;
+}
+
+function readToolArtifacts(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const tools = {};
+  const toolActions = {};
+  let entries = [];
+  try { entries = fs.readdirSync(toolboxDir, { withFileTypes: true }); } catch { return { tools, toolActions }; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name === LEGACY_TOOLBOX_FILE_NAME) continue;
+    const document = readJson(path.join(toolboxDir, entry.name), null);
+    if (!validDocument(document)) continue;
+    const toolId = safeToolId(document.tool.id);
+    const expected = artifactPathForTool(toolId, { toolboxDir });
+    if (path.resolve(expected) !== path.resolve(path.join(toolboxDir, entry.name))) continue;
+    tools[toolId] = { ...document.tool, id: toolId };
+    for (const action of document.actions) toolActions[action.id] = { ...action, toolId };
+  }
+  return { tools, toolActions };
+}
+
+function writeToolboxIndex(toolbox, options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const target = options.indexFile || indexFileFor(toolboxDir);
+  const document = {
+    version: 1,
+    tools: toolbox?.tools || {},
+    toolActions: toolbox?.toolActions || {},
+  };
+  const current = readJson(target, null);
+  if (JSON.stringify(current) !== JSON.stringify(document)) writeJsonAtomic(target, document);
+  return target;
+}
+
+function materializeSystemToolArtifacts(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const { buildSystemToolboxCatalog } = require('./system-catalog');
+  const catalog = buildSystemToolboxCatalog();
+  const changedRelativePaths = [];
+  for (const system of SYSTEM_TOOL_ARTIFACTS) {
+    const tool = catalog.tools[system.toolId];
+    if (!tool) throw new Error(`built-in toolbox definition missing for ${system.toolId}`);
+    const target = artifactPathForTool(tool, { toolboxDir });
+    const document = artifactDocument({
+      tool,
+      actions: Object.values(catalog.toolActions).filter((action) => action.toolId === tool.id),
+    });
+    if (JSON.stringify(readJson(target, null)) !== JSON.stringify(document)) {
+      ensureDir(path.dirname(target));
+      writeJsonAtomic(target, document);
+      changedRelativePaths.push(system.relativePath);
+    }
+  }
+  return { catalog, changedRelativePaths };
+}
+
+/** Move the old aggregate catalog out of the registered toolbox tree only
+ * after all its user records have a per-tool replacement. The new index is a
+ * local cache next to, not inside, the cloud-backed toolbox folder. */
+function migrateLegacyToolboxCatalog(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const legacy = path.join(toolboxDir, LEGACY_TOOLBOX_FILE_NAME);
+  if (!fs.existsSync(legacy)) return { migrated: false, artifactPaths: [] };
+  const parsed = readJson(legacy, null);
+  if (!parsed || typeof parsed !== 'object' || !parsed.tools || typeof parsed.tools !== 'object') {
+    return { migrated: false, artifactPaths: [] };
+  }
+  const artifactPaths = [];
+  for (const [rawId, rawTool] of Object.entries(parsed.tools)) {
+    const toolId = safeToolId(rawTool?.id || rawId);
+    if (!toolId || isSystemToolId(toolId) || !rawTool || typeof rawTool !== 'object') continue;
+    const actions = Object.values(parsed.toolActions || {})
+      .filter((action) => action && action.toolId === toolId);
+    artifactPaths.push(writeToolArtifact({ tool: { ...rawTool, id: toolId }, actions }, { toolboxDir }));
+  }
+  writeToolboxIndex({ tools: parsed.tools || {}, toolActions: parsed.toolActions || {} }, { toolboxDir });
+  let migrated = path.join(path.dirname(toolboxDir), 'toolbox.legacy.json');
+  if (fs.existsSync(migrated)) migrated = path.join(path.dirname(toolboxDir), `toolbox.legacy-${Date.now()}.json`);
+  fs.renameSync(legacy, migrated);
+  return { migrated: true, artifactPaths };
+}
+
+module.exports = {
+  LEGACY_TOOLBOX_FILE_NAME,
+  SYSTEM_TOOL_ARTIFACTS,
+  TOOL_ARTIFACT_SCHEMA_VERSION,
+  TOOLBOX_DIR,
+  TOOLBOX_INDEX_FILE,
+  artifactDocument,
+  artifactPathForTool,
+  indexFileFor,
+  isSystemToolId,
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+  readToolArtifacts,
+  removeUserToolArtifact,
+  safeToolId,
+  userArtifactFileName,
+  writeToolArtifact,
+  writeToolboxIndex,
+};