amalgm 0.1.255 → 0.1.257

package/lib/shared-realtime-tunnel.js

@@ -20,7 +20,7 @@ const REAUTHORIZE_MS = 30_000;
 const REPO_OBJECT_REQUEST_TIMEOUT_MS = 15_000;
 const COOKIE_PRIVATE_CONTRACT = 'browser-cookie-jar@1';
 const USER_HOME_PRIVATE_CONTRACT = 'amalgm-user-home@1';
-const ENTITY_REGISTRY_PRIVATE_CONTRACT = 'amalgm-entity-registry@1';
+const ENTITY_REGISTRY_PRIVATE_CONTRACT = 'amalgm-entity-registry@2';
 
 function createSharedRealtimeTunnel({
   send,

package/package.json

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

package/runtime/scripts/amalgm-mcp/registration/entity-cloud.js

@@ -11,7 +11,12 @@
 
 const crypto = require('crypto');
 
-const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
+// `@1` was an unreleased bootstrap experiment which could project arbitrary
+// pre-cloud local registrations into the first private head. A resource
+// contract names immutable authority semantics, so it is quarantined rather
+// than interpreted or overwritten. `@2` begins with only the verified user
+// home; later user ground enters exclusively through `amalgm register`.
+const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@2';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
 const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
 const SNAPSHOT_REPLACE_OPERATION = 'entity.snapshot.replace';
@@ -424,14 +429,23 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     }
   }
 
-  function bootstrap(registry) {
+  /**
+   * Create the first private entity-resource snapshot from the *already
+   * verified* bootstrap graph. This deliberately accepts records rather than
+   * a registry: login owns the declared user-home graph, but an older device
+   * can also hold unrelated local registrations which have never had cloud
+   * authority. Publishing those as an implicit local-wins merge would make
+   * sign-in a hidden `register` command.
+   */
+  function bootstrap(records) {
     const currentIdentity = identity();
     if (!currentIdentity.enabled) return currentIdentity;
     const existing = replica();
     if (existing?.state === 'active') {
       throw new Error('entity cloud registry already exists locally; cloud lookup must not create it again');
     }
-    const snapshot = cloudSnapshot(registry.syncRecords());
+    if (!Array.isArray(records)) throw new Error('entity cloud bootstrap requires verified records');
+    const snapshot = cloudSnapshot(records);
     const cutoff = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get().sequence;
     saveReplica({
       resourceId: currentIdentity.resourceId,
@@ -471,7 +485,6 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
       throw new Error('entity cloud registry authority is invalid');
     }
-    const local = cloudSnapshot(registry.syncRecords());
     const current = replica();
     const bootstrapping = current?.state === 'bootstrapping';
     const reconciling = current?.state === BOOTSTRAP_RECONCILIATION_STATE;
@@ -486,7 +499,12 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     // exactly the already-verified declared user home. This is not a general
     // local-wins merge: user-selected ground remains refused until an active
     // authoritative snapshot exists.
-    if (!current && emptyCloudGraph && trustedBootstrap && sameRecords(local.records, trustedBootstrap)) {
+    // The first entity resource contains only declared user-home truth. An
+    // old installation may also have local, pre-cloud user ground; that is
+    // deliberately excluded here and will join only through an explicit
+    // later `amalgm register`. The empty cloud resource is therefore repaired
+    // from the trusted bootstrap records, never from the whole local registry.
+    if (emptyCloudGraph && trustedBootstrap && (!current || bootstrapping)) {
       const next = {
         resourceId,
         deviceId: currentIdentity.deviceId,
@@ -515,8 +533,8 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     }
 
     if (reconciling) {
-      if (!trustedBootstrap || !sameRecords(local.records, trustedBootstrap)) {
-        throw new Error('entity bootstrap reconciliation no longer matches the verified user-home graph');
+      if (!trustedBootstrap) {
+        throw new Error('entity bootstrap reconciliation requires the verified user-home graph');
       }
       if (current.resourceId !== resourceId || Number(authorityEpoch) !== current.authorityEpoch
         || Number(headVersion) < current.headVersion || !recordsAreSubset(snapshot.records, trustedBootstrap)) {
@@ -547,13 +565,17 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         reconciling: !complete,
       };
     }
-    if (bootstrapping && !sameRecord(local, snapshot)) {
-      throw new Error('first cloud entity snapshot does not match the locally bootstrapped identity graph');
+    if (bootstrapping) {
+      const expected = trustedBootstrap ?? cloudSnapshot(registry.syncRecords()).records;
+      if (!sameRecords(expected, snapshot.records)) {
+        throw new Error('first cloud entity snapshot does not match the locally bootstrapped identity graph');
+      }
     }
     if (!bootstrapping) {
       const cloudByUuid = new Map(snapshot.records.map((record) => [record.uuid, record]));
-      for (const record of local.records) {
-        if (!sameRecord(record, cloudByUuid.get(record.uuid))) {
+      for (const local of registry.syncRecords()) {
+        const remote = cloudByUuid.get(local.uuid);
+        if (remote && !sameRecord(cloudRecord(local), remote)) {
           throw new Error('cloud entity graph conflicts with locally bound ground; resolve the local mutation before importing a new cloud head');
         }
       }

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

@@ -381,10 +381,10 @@ function createRegistrationService({
     };
   }
 
-  /** The only local graph allowed to repair an old empty entity resource is
-   * the exact home that the user-home handshake has already verified. Any
-   * extra local entity would be user-selected ground and must wait for an
-   * active entity-cloud authority instead. */
+  /** The only local graph eligible to repair an old empty entity resource is
+   * the exact home that the user-home handshake has already verified. Extra
+   * local entities are deliberately excluded rather than treated as a login
+   * merge: they become cloud-backed only through a later explicit register. */
   async function exactUserHomeCloudRecords() {
     const home = await bootstrapUserHome();
     const expected = new Map();
@@ -395,12 +395,9 @@ function createRegistrationService({
       // containers, with the registry's sync representation.
       expected.set(entry.record.uuid, boundary.current.registry.syncRecord(entry.record.uuid));
     }
-    const records = boundary.current.registry.syncRecords();
-    if (records.length !== expected.size) {
-      throw new Error('local entity graph contains ground outside the declared user home');
-    }
+    const records = [...expected.values()];
     for (const record of records) {
-      const declared = expected.get(record.uuid);
+      const declared = boundary.current.registry.syncRecord(record.uuid);
       if (!declared || ![
         'uuid', 'type', 'parentUUID', 'name', 'status', 'version', 'payloadVersion',
       ].every((field) => record[field] === declared[field])) {

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

@@ -135,9 +135,11 @@ async function handleEntityRoutes(ctx) {
       return true;
     }
     // A missing entity resource is first created from the same declared
-    // user-home graph that login owns. This is not an alternate registrar.
-    await service.bootstrapUserHome();
-    ctx.sendJson(200, service.entityCloud.bootstrap(service.registration.registry));
+    // user-home graph that login owns. This is not an alternate registrar:
+    // pre-cloud user registrations are deliberately excluded until their
+    // caller explicitly registers them after the bootstrap head is active.
+    const bootstrapRecords = await service.exactUserHomeCloudRecords();
+    ctx.sendJson(200, service.entityCloud.bootstrap(bootstrapRecords));
     return true;
   }
 
@@ -147,7 +149,8 @@ async function handleEntityRoutes(ctx) {
     const service = registrationService();
     try {
       const existing = service.entityCloud.replica();
-      let requiresBootstrapProof = existing?.state === 'reconciling-bootstrap';
+      let requiresBootstrapProof = existing?.state === 'bootstrapping'
+        || existing?.state === 'reconciling-bootstrap';
       try {
         const snapshot = JSON.parse(Buffer.from(String(body?.snapshotBase64 || ''), 'base64').toString('utf8'));
         requiresBootstrapProof ||= Number(body?.headVersion) === 0

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

@@ -25,7 +25,7 @@ test('the entity cloud snapshot establishes identity, then each later entity com
   assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
     'initial bootstrap identity is carried by the first immutable snapshot, not an unscoped tail');
 
-  const bootstrap = cloud.bootstrap(registry);
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
   const snapshot = parseSnapshot(Buffer.from(bootstrap.snapshotBase64, 'base64'));
   assert.deepEqual(snapshot.records.map((record) => record.uuid), [root.uuid]);
   cloud.install({
@@ -64,7 +64,7 @@ test('a signed-in registration is refused until the cloud entity resource is act
   const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
   assert.throws(() => cloud.assertRegistrationReady(), /entity cloud registry is not ready/);
   registry.enrollRoot({ type: 'workspace', name: 'bootstrap-only' });
-  const bootstrap = cloud.bootstrap(registry);
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
   cloud.install({
     registry,
     resourceId: bootstrap.resourceId,
@@ -81,7 +81,7 @@ test('a large registration replaces the complete graph in one cloud operation an
   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: 'large-ground' });
-  const bootstrap = cloud.bootstrap(registry);
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
   cloud.install({
     registry,
     resourceId: bootstrap.resourceId,
@@ -126,7 +126,7 @@ test('a large registration replaces the complete graph in one cloud operation an
   recipientDb.close();
 });
 
-test('only an exact verified bootstrap graph can repair a legacy empty entity resource', () => {
+test('a legacy empty entity resource repairs only the verified home and excludes unrelated local ground', () => {
   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 });
@@ -172,21 +172,28 @@ test('only an exact verified bootstrap graph can repair a legacy empty entity re
   assert.equal(cloud.replica().state, 'active');
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 
-  const unsafeDb = new Database(':memory:');
-  const unsafeCloud = createEntityCloud({ db: unsafeDb, userId: 'user-1', deviceId: 'unsafe-device' });
-  const unsafeRegistry = createRegistry({ db: unsafeDb, ephemeral: true, emit: () => {}, journal: unsafeCloud.journal });
-  const safeRoot = unsafeRegistry.enrollRoot({ type: 'workspace', name: 'agents' });
-  unsafeRegistry.create({ type: 'file.text', parentUUID: safeRoot.uuid, name: 'not-a-default.md', payloadVersion: 'a'.repeat(64) });
-  assert.throws(() => unsafeCloud.install({
-    registry: unsafeRegistry,
+  const legacyDb = new Database(':memory:');
+  const legacyCloud = createEntityCloud({ db: legacyDb, userId: 'user-1', deviceId: 'legacy-device' });
+  const legacyRegistry = createRegistry({ db: legacyDb, ephemeral: true, emit: () => {}, journal: legacyCloud.journal });
+  const safeRoot = legacyRegistry.enrollRoot({ type: 'workspace', name: 'agents' });
+  const legacyRepo = legacyRegistry.create({ type: 'repo.git', parentUUID: safeRoot.uuid, name: 'old-local-repo' });
+  const verifiedHome = legacyRegistry.syncRecords().filter((record) => record.uuid === safeRoot.uuid);
+  const repaired = legacyCloud.install({
+    registry: legacyRegistry,
     resourceId,
     authorityEpoch: 1,
     headVersion: 0,
     snapshotBase64: empty.toString('base64'),
     snapshotChecksum: require('crypto').createHash('sha256').update(empty).digest('hex'),
-    bootstrapRecords: unsafeRegistry.syncRecords().filter((record) => record.uuid === safeRoot.uuid),
-  }), /conflicts with locally bound ground/,
-    'an empty cloud resource never authorizes arbitrary local ground');
+    bootstrapRecords: verifiedHome,
+  });
+  assert.equal(repaired.reconciling, true);
+  const repair = legacyCloud.claim();
+  assert.equal(repair.length, 1);
+  assert.equal(repair[0].operation.record.uuid, safeRoot.uuid,
+    'only the verified home node is queued into the automatic cloud graph');
+  assert.equal(legacyRegistry.syncRecord(legacyRepo.uuid).uuid, legacyRepo.uuid,
+    'unrelated local ground remains local until its caller explicitly registers it');
 });
 
 test('a compacted remote snapshot enters the cloud catalog, not locally watched identity, and add claims its immutable content', () => {
@@ -270,7 +277,7 @@ test('add accepts only a catalog installed by the active compacted snapshot, nev
       envelope: {
         resourceId,
         mutationId: 'ent_remote_change',
-        contract: 'amalgm-entity-registry@1',
+        contract: 'amalgm-entity-registry@2',
         schemaVersion: 1,
         operationKind: 'entity.upsert',
         operation: { kind: 'entity.upsert', record: changed },

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

@@ -32,7 +32,7 @@ test('file bytes are captured as bounded immutable chunks, then acknowledged bef
   const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1', content });
   const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
   const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
-  const bootstrap = cloud.bootstrap(registry);
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
   cloud.install({
     registry,
     resourceId: bootstrap.resourceId,

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@1',
+        contract: 'amalgm-entity-registry@2',
         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@1', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@2', schemaVersion: 1,
         operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: sourceRegistry.syncRecord(changed.uuid) },
       },
       version: 42, committedAt: '2026-08-05T00:00:00.000Z',
@@ -344,7 +344,7 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     cloudUserId: 'user-1', cloudDeviceId: 'target-device',
   });
   try {
-    const bootstrap = source.entityCloud.bootstrap(source.registration.registry);
+    const bootstrap = source.entityCloud.bootstrap(source.registration.registry.syncRecords());
     source.entityCloud.install({
       registry: source.registration.registry, resourceId: bootstrap.resourceId,
       authorityEpoch: 1, headVersion: 0, snapshotBase64: bootstrap.snapshotBase64,
@@ -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@1', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@2', 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

@@ -233,6 +233,40 @@ test('user-home bootstrap creates only declared roots and registers them through
   );
 });
 
+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'),
+    homeDir: path.join(tempRoot, 'user-home-cloud-boundary'),
+    cloudUserId: 'user-home-cloud-boundary',
+    cloudDeviceId: 'computer-user-home-cloud-boundary',
+  });
+  services.push(service);
+  const home = await service.bootstrapUserHome();
+  const workspaces = home.roots.find((entry) => entry.key === 'workspaces').record;
+  const oldRepo = service.registration.registry.create({
+    type: 'repo.git', parentUUID: workspaces.uuid, name: 'old-local-repo', payloadVersion: null,
+  });
+
+  const records = await service.exactUserHomeCloudRecords();
+  assert.equal(records.length, 9);
+  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);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 1,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+    bootstrapRecords: records,
+  });
+  assert.doesNotThrow(() => service.entityCloud.assertRegistrationReady());
+});
+
 test('a fresh machine binds existing user-home UUIDs before it starts watching', async () => {
   const first = createRegistrationService({
     dir: path.join(tempRoot, 'state-user-home-origin'),
@@ -326,7 +360,7 @@ test('a signed-in register call writes every entity delivery intent in identity.
     cloudDeviceId: 'computer-cloud-register',
   });
   const home = await service.bootstrapUserHome();
-  const bootstrap = service.entityCloud.bootstrap(service.registration.registry);
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry.syncRecords());
   service.entityCloud.install({
     registry: service.registration.registry,
     resourceId: bootstrap.resourceId,
@@ -366,7 +400,7 @@ test('a large signed-in register call publishes one complete cloud graph before
     cloudUserId: 'user-cloud-register-large',
     cloudDeviceId: 'computer-cloud-register-large',
   });
-  const bootstrap = service.entityCloud.bootstrap(service.registration.registry);
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry.syncRecords());
   service.entityCloud.install({
     registry: service.registration.registry,
     resourceId: bootstrap.resourceId,