amalgm 0.1.253 → 0.1.255

package/package.json

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

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

@@ -505,8 +505,12 @@ function createRegistration(options) {
     }
     const covering = treeRootCovering(ground);
     if (covering) {
-      ensureTrees();
-      tryFollow();
+      // This address is already registered ground. Its prior Register →
+      // Watch transition remains the proof of its identity; repeating a
+      // harmless "ensure the safe home exists" request must not rescan every
+      // edge and repository in every tree. Doorbells own later convergence.
+      // We still prove the one property this caller may rely on now: that
+      // the existing watcher is live (and retry its own failed birth once).
       requireLiveWatchers(covering.path);
       return { rootPath: covering.path, record: rootRecordOf(covering.rootId) };
     }

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

@@ -230,6 +230,24 @@ function createRegistrationService({
     };
   }
 
+  /** A bootstrap rekey is safe only before this installation has accepted
+   * ordinary entity-cloud state. After that point a UUID graph has an
+   * independent authority and an operator must resolve any disagreement
+   * explicitly; a login handshake never chooses a winner for it. */
+  function assertBootstrapRekeyAvailable() {
+    const state = identityDb.prepare(`
+      SELECT
+        (SELECT COUNT(*) FROM entity_cloud_replica) AS replicas,
+        (SELECT COUNT(*) FROM entity_cloud_mutations) AS mutations,
+        (SELECT COUNT(*) FROM entity_cloud_catalog_state) AS catalog_states,
+        (SELECT COUNT(*) FROM entity_cloud_catalog) AS catalog_records,
+        (SELECT COUNT(*) FROM entity_materializations) AS materializations
+    `).get();
+    if (Object.values(state).some((count) => Number(count) !== 0)) {
+      throw new Error('cannot adopt cloud user-home UUIDs after ordinary entity-cloud state exists');
+    }
+  }
+
   /**
    * Bootstrap a logged-in person's declared Amalgm home through the SAME
    * operation as `amalgm register`. `ensureUserHome` only creates the safe shape;
@@ -243,23 +261,18 @@ function createRegistrationService({
   async function bootstrapUserHome({ identitySnapshot = null } = {}) {
     const declaration = ensureUserHome(homeDir);
     const seeds = identitySeeds(identitySnapshot, declaration);
-    const roots = [];
     const addedRoots = boundary.current.addMany(declaration.roots.map((entry) => ({
       targetPath: entry.path,
       identityAt: seeds?.forRoot(entry.key) ?? null,
     })));
-    for (let index = 0; index < declaration.roots.length; index += 1) {
-      const entry = declaration.roots[index];
+    let roots = declaration.roots.map((entry, index) => {
       const added = addedRoots[index];
-      if (seeds && added.record.uuid !== seeds.root(entry.key).uuid) {
-        throw new Error(`local user-home root ${entry.key} does not match its cloud UUID`);
-      }
-      roots.push({
+      return {
         key: entry.key,
         path: added.rootPath,
         record: added.record,
-      });
-    }
+      };
+    });
 
     const system = roots.find((entry) => entry.key === 'system');
     if (!system) throw new Error('declared user home has no system root');
@@ -275,15 +288,12 @@ function createRegistrationService({
       return record;
     };
 
-    const exactManaged = declaration.exactManaged.map((entry) => {
+    let exactManaged = declaration.exactManaged.map((entry) => {
       const root = roots.find((candidate) => candidate.key === entry.rootKey);
       const isRoot = entry.relativePath === entry.rootKey;
       const relativePath = isRoot ? '' : entry.relativePath.slice(entry.rootKey.length + 1);
       const record = isRoot ? root?.record : recordAt(relativePath);
       if (!record) throw new Error(`declared user-home managed target was not registered: ${entry.relativePath}`);
-      if (seeds && record.uuid !== seeds.managed(entry.key).uuid) {
-        throw new Error(`local user-home managed target ${entry.key} does not match its cloud UUID`);
-      }
       return {
         key: entry.key,
         rootKey: entry.rootKey,
@@ -294,6 +304,65 @@ function createRegistrationService({
       };
     });
 
+    if (seeds) {
+      const bindings = [
+        ...roots.map((entry) => ({
+          key: entry.key,
+          local: entry.record,
+          authoritative: seeds.root(entry.key),
+        })),
+        ...exactManaged.map((entry) => ({
+          key: entry.key,
+          local: entry.record,
+          authoritative: seeds.managed(entry.key),
+        })),
+      ];
+      for (const binding of bindings) {
+        const remote = binding.authoritative;
+        const local = binding.local;
+        if (!remote || remote.type !== local.type || remote.name !== local.name || remote.status !== local.status) {
+          throw new Error(`cloud user-home node ${binding.key} does not match its declared local shape`);
+        }
+      }
+      if (bindings.some(({ local, authoritative }) => local.uuid !== authoritative.uuid)) {
+        assertBootstrapRekeyAvailable();
+        // The six roots appear once more in `exactManaged` to name their
+        // governance. They are the same nodes, not a second rekey.
+        const uniqueBindings = [...new Map(bindings.map((binding) => [binding.local.uuid, binding])).values()];
+        boundary.current.registry.rebindBootstrapIdentities(uniqueBindings.map(({ local, authoritative }) => ({
+          oldUUID: local.uuid,
+          newUUID: authoritative.uuid,
+          newParentUUID: authoritative.parentUUID,
+          type: authoritative.type,
+          name: authoritative.name,
+        })));
+        roots = roots.map((entry) => ({
+          ...entry,
+          record: boundary.current.registry.syncRecord(seeds.root(entry.key).uuid),
+        }));
+        const reboundSystem = roots.find((entry) => entry.key === 'system');
+        const reboundTree = boundary.current.tree(reboundSystem.path);
+        if (!reboundTree?.root()) throw new Error('cloud user-home rekey lost the declared system root');
+        exactManaged = exactManaged.map((entry) => {
+          const remote = seeds.managed(entry.key);
+          return {
+            ...entry,
+            record: boundary.current.registry.syncRecord(remote.uuid),
+          };
+        });
+      }
+      for (const entry of roots) {
+        if (entry.record.uuid !== seeds.root(entry.key).uuid) {
+          throw new Error(`local user-home root ${entry.key} does not match its cloud UUID`);
+        }
+      }
+      for (const entry of exactManaged) {
+        if (entry.record.uuid !== seeds.managed(entry.key).uuid) {
+          throw new Error(`local user-home managed target ${entry.key} does not match its cloud UUID`);
+        }
+      }
+    }
+
     const cloudSnapshot = {
       schemaVersion: USER_HOME_CLOUD_SCHEMA_VERSION,
       kind: 'amalgm-user-home',

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

@@ -684,6 +684,67 @@ function createRegistry(options) {
       });
     },
 
+    /**
+     * First cloud bootstrap may meet a pre-cloud local safe home. Its six
+     * roots and three exact managed nodes are platform truth, so they may
+     * adopt the authenticated cloud UUIDs without changing any user-owned
+     * descendant identity. This is one atomic graph rekey, never a delete or
+     * local-wins merge, and callers must prove that no ordinary entity-cloud
+     * history has begun before asking for it.
+     */
+    rebindBootstrapIdentities(bindings) {
+      if (!Array.isArray(bindings) || bindings.length === 0) {
+        throw new Error('bootstrap identity rebind requires one or more bindings');
+      }
+      return transaction(() => {
+        const byOld = new Map();
+        const byNew = new Map();
+        const mappings = bindings.map((binding) => {
+          if (!binding || typeof binding.oldUUID !== 'string' || typeof binding.newUUID !== 'string'
+            || !UUID.test(binding.oldUUID) || !UUID.test(binding.newUUID)
+            || (binding.newParentUUID !== null && (!UUID.test(binding.newParentUUID)))) {
+            throw new Error('bootstrap identity rebind has an invalid UUID binding');
+          }
+          const oldUuid = binding.oldUUID.toLowerCase();
+          const newUuid = binding.newUUID.toLowerCase();
+          if (byOld.has(oldUuid) || byNew.has(newUuid)) {
+            throw new Error('bootstrap identity rebind repeats an identity');
+          }
+          const row = mustGet(oldUuid);
+          if (row.status !== 'active' || row.type !== binding.type || row.name !== binding.name) {
+            throw new Error(`bootstrap identity ${oldUuid} does not match its declared local node`);
+          }
+          if (newUuid !== oldUuid && store.byUuid(newUuid)) {
+            throw new Error(`bootstrap identity ${newUuid} is already registered locally`);
+          }
+          const mapping = {
+            oldUuid,
+            newUuid,
+            newParentUuid: binding.newParentUUID === null ? null : binding.newParentUUID.toLowerCase(),
+            type: row.type,
+            name: row.name,
+            status: row.status,
+            payloadVersion: row.payloadVersion,
+            oldParentUuid: row.parentUuid,
+          };
+          byOld.set(oldUuid, mapping);
+          byNew.set(newUuid, mapping);
+          return mapping;
+        });
+        for (const mapping of mappings) {
+          const translatedParent = mapping.oldParentUuid === null
+            ? null
+            : (byOld.get(mapping.oldParentUuid)?.newUuid ?? mapping.oldParentUuid);
+          if (translatedParent !== mapping.newParentUuid) {
+            throw new Error(`bootstrap identity ${mapping.oldUuid} has a different authoritative parent`);
+          }
+        }
+        store.rebindIdentities(mappings);
+        membershipHashes.clear();
+        return mappings.map((mapping) => syncRecord(mustGet(mapping.newUuid)));
+      });
+    },
+
     record: (uuid) => record(mustGet(uuid)),
     syncRecord: (uuid) => syncRecord(mustGet(uuid)),
     /** Full logical graph for cloud snapshots. Machine bindings and evidence

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

@@ -300,6 +300,63 @@ function createStore(db) {
         WHERE uuid = ?
       `).run(type, parentUuid, name, status, payloadVersion, uuid);
     },
+    /**
+     * Rekey a small, already-validated identity set in one invisible SQLite
+     * transition. This is deliberately a store primitive, not a generic
+     * public CRUD verb: trusted bootstrap migration is the only caller.
+     *
+     * The old row is retired just long enough to free its active slot, a new
+     * row is born with the authoritative UUID, every direct child follows the
+     * new parent, then the retired row is removed. Nothing outside the
+     * transaction can observe the temporary state. UUID references held by
+     * local evidence, Git state, and managed references follow as well.
+     */
+    rebindIdentities(mappings) {
+      const retired = mappings.filter((mapping) => mapping.oldUuid !== mapping.newUuid);
+      const retire = db.prepare("UPDATE entities SET status = 'trashed' WHERE uuid = ?");
+      const insert = db.prepare(`
+        INSERT INTO entities (uuid, type, parent_uuid, name, status, payload_version)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `);
+      const reparent = db.prepare('UPDATE entities SET parent_uuid = ? WHERE parent_uuid = ?');
+      const rebindChannels = db.prepare('UPDATE channel_bindings SET entity_uuid = ? WHERE entity_uuid = ?');
+      const rebindClaims = db.prepare('UPDATE contested_ground SET claimant_uuid = ? WHERE claimant_uuid = ?');
+      const rebindRepoState = db.prepare('UPDATE repo_states SET entity_uuid = ? WHERE entity_uuid = ?');
+      const rebindReference = db.prepare("UPDATE entities SET payload_version = ? WHERE type = 'reference' AND payload_version = ?");
+      const remove = db.prepare('DELETE FROM entities WHERE uuid = ?');
+
+      db.transaction(() => {
+        for (const mapping of retired) retire.run(mapping.oldUuid);
+
+        const remaining = new Map(retired.map((mapping) => [mapping.newUuid, mapping]));
+        while (remaining.size > 0) {
+          let inserted = false;
+          for (const mapping of [...remaining.values()]) {
+            if (remaining.has(mapping.newParentUuid)) continue;
+            insert.run(
+              mapping.newUuid,
+              mapping.type,
+              mapping.newParentUuid,
+              mapping.name,
+              mapping.status,
+              mapping.payloadVersion,
+            );
+            remaining.delete(mapping.newUuid);
+            inserted = true;
+          }
+          if (!inserted) throw new Error('identity rebind has a cyclic authoritative parent map');
+        }
+
+        for (const mapping of retired) reparent.run(mapping.newUuid, mapping.oldUuid);
+        for (const mapping of retired) {
+          rebindChannels.run(mapping.newUuid, mapping.oldUuid);
+          rebindClaims.run(mapping.newUuid, mapping.oldUuid);
+          rebindRepoState.run(mapping.newUuid, mapping.oldUuid);
+          rebindReference.run(mapping.newUuid, mapping.oldUuid);
+        }
+        for (const mapping of retired) remove.run(mapping.oldUuid);
+      })();
+    },
     /**
      * One address permutation as one write. Movers may hold each other's
      * slots, and the live unique index cannot be threaded one row at a

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

@@ -262,6 +262,62 @@ test('a fresh machine binds existing user-home UUIDs before it starts watching',
     'only the bound identities enter Watch');
 });
 
+test('an older pre-cloud home adopts authenticated platform UUIDs without changing user descendants', async () => {
+  const authority = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-authority'),
+    homeDir: path.join(tempRoot, 'user-home-authority'),
+  });
+  const local = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-pre-cloud'),
+    homeDir: path.join(tempRoot, 'user-home-pre-cloud'),
+  });
+  services.push(authority, local);
+  const authoritative = await authority.bootstrapUserHome();
+  const before = await local.bootstrapUserHome();
+  const oldWorkspaces = before.roots.find((entry) => entry.key === 'workspaces').record;
+  const userProject = local.registration.registry.create({
+    type: 'folder', parentUUID: oldWorkspaces.uuid, name: 'user-project',
+  });
+
+  const snapshot = JSON.parse(JSON.stringify(authoritative.cloudSnapshot));
+  const rootIds = new Map();
+  for (const root of snapshot.roots) {
+    root.record.uuid = crypto.randomUUID();
+    rootIds.set(root.key, root.record.uuid);
+  }
+  for (const managed of snapshot.exactManaged) {
+    if (managed.relativePath === managed.key.replace(/-root$/, '')) {
+      managed.record.uuid = rootIds.get(managed.key.replace(/-root$/, ''));
+      managed.record.parentUUID = null;
+    } else {
+      managed.record.uuid = crypto.randomUUID();
+      managed.record.parentUUID = rootIds.get(managed.relativePath.split('/')[0]);
+    }
+  }
+
+  const rebound = await local.bootstrapUserHome({ identitySnapshot: snapshot });
+  const reboundWorkspaces = rebound.roots.find((entry) => entry.key === 'workspaces').record;
+  assert.equal(reboundWorkspaces.uuid, rootIds.get('workspaces'));
+  assert.equal(local.registration.registry.syncRecord(userProject.uuid).uuid, userProject.uuid,
+    'the user project keeps its permanent identity');
+  assert.equal(local.registration.registry.syncRecord(userProject.uuid).parentUUID, reboundWorkspaces.uuid,
+    'only its parent now names the cloud-authoritative platform root');
+  assert.deepEqual(
+    rebound.exactManaged.map((entry) => entry.record.uuid),
+    snapshot.exactManaged.map((entry) => entry.record.uuid),
+    'the three exact system nodes and six roots now use the signed cloud identities',
+  );
+  const db = new Database(path.join(local.dir, 'identity.db'), { readonly: true });
+  try {
+    assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entities WHERE uuid = ?').get(oldWorkspaces.uuid).count, 0,
+      'the superseded platform root is not retained as a second active identity');
+  } finally {
+    db.close();
+  }
+  assert.equal(local.observer.status().every((root) => root.watching && !root.degraded), true,
+    'rekeying identity preserves every existing watcher');
+});
+
 test('a signed-in register call writes every entity delivery intent in identity.db before Watch begins', async () => {
   const service = createRegistrationService({
     dir: path.join(tempRoot, 'state-cloud-register'),