amalgm 0.1.252 → 0.1.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.252",
+  "version": "0.1.254",
   "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

@@ -600,14 +600,14 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     if (typeof targetPath !== 'string' || !targetPath) throw new Error('materialization requires a destination path');
     const tree = catalogTree({ resourceId: current.resourceId, uuid });
     if (tree[0].status !== 'active') throw new Error(`cloud entity ${uuid} is not active`);
-    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
+    const unsupported = tree.find((record) => record.type === 'reference');
     if (unsupported) {
-      throw new Error(`cloud entity ${unsupported.uuid} is ${unsupported.type}; this first materializer supports ordinary workspace and file trees only`);
+      throw new Error(`cloud entity ${unsupported.uuid} is a managed reference; reference projection is not materialized by amalgm add yet`);
     }
     const prior = db.prepare(`
       SELECT * FROM entity_materializations
       WHERE resource_id = ? AND entity_uuid = ? AND target_path = ?
-        AND state IN ('waiting_for_content', 'materializing', 'complete')
+        AND state IN ('waiting_for_content', 'materializing')
       ORDER BY created_at DESC LIMIT 1
     `).get(current.resourceId, tree[0].uuid, targetPath);
     if (prior) return materialization(prior);

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) };
     }
@@ -546,11 +550,21 @@ function createRegistration(options) {
     // Start's first census must run before a parent lens is allowed to
     // conclude that a pre-registered nested repo is absent: unobserved is
     // not absent. Only then do evidence lenses reconcile that census.
-    observer.start(root.rootId);
-    ensureTrees();
-    reconcileInitialRepoWorktrees(root.path);
-    flushIfDirty();
-    requireLiveWatchers(root.path);
+    //
+    // An imported cloud tree is different only in authority, not in
+    // mechanics: its first census supplies local observer evidence but must
+    // never turn the authoritative snapshot back into a fresh outbound
+    // mutation. Keep the whole first Watch/Detect transition inside the
+    // existing journal boundary used for the seeded structural bind.
+    const startWatch = () => {
+      observer.start(root.rootId);
+      ensureTrees();
+      reconcileInitialRepoWorktrees(root.path);
+      flushIfDirty();
+      requireLiveWatchers(root.path);
+    };
+    if (suppressJournal) registry.withoutJournal(startWatch);
+    else startWatch();
     return { rootPath: root.path, record: rootRecordOf(root.rootId) };
   }
 

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

@@ -376,15 +376,18 @@ function createRegistrationService({
         return false;
       }
     }
-    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
-      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace, repository, and file trees only`);
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace, repository, file, and link trees only`);
     }
 
     const parent = fs.realpathSync(job.targetPath);
     const parentStat = fs.statSync(parent);
     if (!parentStat.isDirectory()) throw new Error(`add destination is not a directory: ${parent}`);
     const destination = path.join(parent, root.name);
-    if (fs.existsSync(destination)) throw new Error(`refusing to add ${root.name}: destination already exists at ${destination}`);
+    const destinationExists = (() => {
+      try { fs.lstatSync(destination); return true; } catch { return false; }
+    })();
+    if (destinationExists) throw new Error(`refusing to add ${root.name}: destination already exists at ${destination}`);
     const staging = path.join(parent, `.${root.name}.amalgm-materializing-${crypto.randomBytes(10).toString('hex')}`);
     let promoted = false;
 
@@ -404,6 +407,10 @@ function createRegistrationService({
         fs.writeFileSync(target, entityContent.bytes({ contentHash: record.payloadVersion }), { mode: 0o600, flag: 'wx' });
         return;
       }
+      if (record.type === 'link') {
+        fs.symlinkSync(record.payloadVersion, target);
+        return;
+      }
       throw new Error(`cloud entity ${record.uuid} is ${record.type}; this materializer cannot write it yet`);
     }
 
@@ -457,12 +464,12 @@ function createRegistrationService({
     const tree = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
     const root = tree[0];
     const active = tree.filter((record) => record.status === 'active');
-    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
+    const unsupported = tree.find((record) => record.type === 'reference');
     if (unsupported) {
       throw new Error(`live cloud add for ${unsupported.type} is not available yet; the binding was left unchanged`);
     }
-    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
-      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace, repository, and file trees only`);
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace, repository, file, and link trees only`);
     }
     for (const record of active) {
       if (['file.text', 'file.binary'].includes(record.type)
@@ -512,9 +519,11 @@ function createRegistrationService({
     // overwrite is still the byte named by the old authoritative record.
     // An unsent local edit or an out-of-band edit is a conflict, never an
     // implicit cloud-wins overwrite.
+    const locallyBound = new Set();
     for (const record of tree) {
       const current = localRecord(record.uuid);
       if (!current || current.version === record.version) continue;
+      locallyBound.add(record.uuid);
       if (entityCloud.hasUnsettledLocalMutation(record.uuid)) {
         throw new Error(`local change for ${record.uuid} is still waiting for cloud; refusing to overwrite it`);
       }
@@ -528,6 +537,15 @@ function createRegistrationService({
         }
         continue;
       }
+      if (current.type === 'link') {
+        const currentPath = addressOf(record.uuid);
+        let stat = null;
+        try { stat = currentPath ? fs.lstatSync(currentPath) : null; } catch {}
+        if (!stat || !stat.isSymbolicLink() || fs.readlinkSync(currentPath) !== current.payloadVersion) {
+          throw new Error(`local link ${currentPath || record.uuid} changed outside Amalgm; refusing to overwrite it`);
+        }
+        continue;
+      }
       if (!['file.text', 'file.binary'].includes(current.type)) continue;
       const currentPath = addressOf(record.uuid);
       if (!currentPath || !fs.existsSync(currentPath)) {
@@ -567,6 +585,16 @@ function createRegistrationService({
       }
     }
 
+    function atomicLink(file, target) {
+      const temporary = path.join(path.dirname(file), `.${path.basename(file)}.amalgm-live-${crypto.randomBytes(10).toString('hex')}`);
+      try {
+        fs.symlinkSync(target, temporary);
+        fs.renameSync(temporary, file);
+      } finally {
+        fs.rmSync(temporary, { force: true });
+      }
+    }
+
     function removeInactiveChild(parentRecord, name, target) {
       const known = boundary.current.registry.children(parentRecord.uuid)
         .find((candidate) => candidate.name === name);
@@ -579,6 +607,14 @@ function createRegistrationService({
           throw new Error(`local file ${target} changed outside Amalgm; refusing to remove it`);
         }
       }
+      if (known.type === 'link') {
+        const previous = localRecord(known.uuid);
+        let stat = null;
+        try { stat = fs.lstatSync(target); } catch {}
+        if (!stat || !stat.isSymbolicLink() || fs.readlinkSync(target) !== previous?.payloadVersion) {
+          throw new Error(`local link ${target} changed outside Amalgm; refusing to remove it`);
+        }
+      }
       fs.rmSync(target, { recursive: true, force: true });
     }
 
@@ -602,6 +638,26 @@ function createRegistrationService({
         applyRepo(target, repoState(record));
         return;
       }
+      if (record.type === 'link') {
+        let present = false;
+        try { fs.lstatSync(target); present = true; } catch {}
+        if (present) {
+          const stat = fs.lstatSync(target);
+          if (stat.isSymbolicLink() && fs.readlinkSync(target) === record.payloadVersion) return;
+          // This address was just proven to be the old authoritative UUID
+          // above. The registry now holds the new link head, so replace the
+          // literal projection atomically rather than treating its old target
+          // as unrelated ground. A brand-new cloud link retains the refusal:
+          // it may never overwrite an existing local address.
+          if (locallyBound.has(record.uuid)) {
+            atomicLink(target, record.payloadVersion);
+            return;
+          }
+          throw new Error(`cloud link ${record.uuid} conflicts with local ground ${target}`);
+        }
+        atomicLink(target, record.payloadVersion);
+        return;
+      }
       if (!['file.text', 'file.binary'].includes(record.type)) {
         throw new Error(`cloud entity ${record.uuid} is ${record.type}; this live materializer cannot write it`);
       }

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

@@ -172,7 +172,16 @@ function registerDirectory(dirPath, parentUUID, {
       const identity = seeded(entryRelativePath, {
         type: 'link', parentUUID, name: entry.name, root: false,
       });
-      registry.create({ type: identity.type, parentUUID, name: entry.name, uuid: identity.uuid });
+      registry.create({
+        type: identity.type,
+        parentUUID,
+        name: entry.name,
+        // A cloud materializer has already verified the literal link text.
+        // Preserve it through the structural bind; normal local registration
+        // still leaves this null until Watch observes the filesystem.
+        payloadVersion: identity.payloadVersion ?? null,
+        uuid: identity.uuid,
+      });
       continue;
     }
     if (stat.isDirectory()) {

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

@@ -183,6 +183,18 @@ function createRegistry(options) {
   let bellPending = false;
   const deferred = []; // bells born inside an open transaction: they ring at commit, or a rollback silences them
   let journalSuppression = 0;
+  // A container's head is derived from its active direct membership. A
+  // reconciliation may need that answer for many descendants, but it is
+  // unchanged until a child enters, leaves, moves, or is renamed. Cache the
+  // derivation here, at the registry boundary, and invalidate it with the
+  // membership transition itself.
+  const membershipHashes = new Map();
+
+  function invalidateMembership(...uuids) {
+    for (const uuid of uuids) {
+      if (uuid !== null && uuid !== undefined) membershipHashes.delete(uuid);
+    }
+  }
 
   function ring(event) {
     try {
@@ -273,8 +285,12 @@ function createRegistry(options) {
 
   /** Container payload: the sorted active direct membership (childUUID, name). */
   function membershipHash(uuid) {
+    const cached = membershipHashes.get(uuid);
+    if (cached) return cached;
     const pairs = store.activeChildrenOf(uuid).map((child) => [child.uuid, child.name]);
-    return crypto.createHash('sha256').update(JSON.stringify(pairs)).digest('hex');
+    const hash = crypto.createHash('sha256').update(JSON.stringify(pairs)).digest('hex');
+    membershipHashes.set(uuid, hash);
+    return hash;
   }
 
   function payloadFor(row) {
@@ -361,6 +377,9 @@ function createRegistry(options) {
     const previous = record(row);
     store.update(row.uuid, { ...row, ...changes });
     const nextRow = mustGet(row.uuid);
+    if (changes.status !== undefined && changes.status !== row.status) {
+      invalidateMembership(row.parentUuid);
+    }
     const next = record(nextRow);
     journalRecord(nextRow, row);
     publish({ type: 'entity.committed', record: next, previous });
@@ -451,6 +470,9 @@ function createRegistry(options) {
       const adoptedWorkspace = row.parentUuid === null && row.type === 'workspace';
       return { uuid, parentUuid: parentUUID, name, ...(adoptedWorkspace ? { type: 'folder' } : {}) };
     }));
+    for (const { uuid, parentUUID } of moves) {
+      invalidateMembership(rows.get(uuid).parentUuid, parentUUID);
+    }
     return moves.map(({ uuid }, index) => {
       const nextRow = mustGet(uuid);
       const next = record(nextRow);
@@ -536,6 +558,7 @@ function createRegistry(options) {
         status: 'active', payloadVersion,
       };
       store.insert(row);
+      invalidateMembership(parentUUID);
       const next = record(row);
       journalRecord(row, null);
       publish({ type: 'entity.committed', record: next, previous: null });
@@ -639,17 +662,21 @@ function createRegistry(options) {
         if (!previous && incoming.parentUuid !== null && !store.byUuid(incoming.parentUuid)) {
           throw new Error(`cloud entity ${incoming.uuid} names missing parent ${incoming.parentUuid}`);
         }
+        const previousRecord = previous ? record(previous) : null;
         if (previous) {
           store.update(incoming.uuid, incoming);
         } else {
           store.insert(incoming);
         }
         const current = mustGet(incoming.uuid);
+        if (!previous || previous.parentUuid !== current.parentUuid
+          || previous.name !== current.name || previous.status !== current.status) {
+          invalidateMembership(previous?.parentUuid, current.parentUuid);
+        }
         const synced = syncRecord(current);
         if (synced.version !== incoming.expectedVersion) {
           throw new Error(`cloud entity ${incoming.uuid} version does not match its logical record`);
         }
-        const previousRecord = previous ? record(previous) : null;
         if (!previous || !sameLogicalRecord(previous, current)) {
           publish({ type: 'entity.committed', record: record(current), previous: previousRecord });
         }

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

@@ -221,6 +221,11 @@ test('a compacted remote snapshot enters the cloud catalog, not locally watched
   assert.deepEqual(targetRegistry.syncRecords(), [], 'a remote graph does not pretend to be watched local ground');
   const job = targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir });
   assert.equal(job.state, 'waiting_for_content');
+  targetCloud.completeMaterialization({ jobId: job.jobId });
+  const retry = targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir });
+  assert.notEqual(retry.jobId, job.jobId,
+    'a completed job is historical evidence, not permission to claim a destination still exists');
+  assert.equal(retry.state, 'waiting_for_content');
   assert.deepEqual(targetCloud.catalogTree({ resourceId, uuid: root.uuid }).map((record) => record.uuid), [root.uuid, file.uuid]);
   assert.deepEqual(targetCloud.claimDownload(), {
     resourceId,

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

@@ -229,6 +229,95 @@ test('an added ordinary workspace stays live: a later cloud file head replaces l
   }
 });
 
+test('add preserves a symlink UUID and later retargets the same literal link without an echo', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-link-materialization-'));
+  const sourceDir = path.join(rootDir, 'source');
+  const targetState = path.join(rootDir, 'target-state');
+  const targetParent = path.join(rootDir, 'checkout');
+  fs.mkdirSync(sourceDir, { recursive: true });
+  fs.mkdirSync(targetParent, { recursive: true });
+  const firstBytes = Buffer.from('first target\n');
+  const secondBytes = Buffer.from('second target\n');
+  const firstHash = sha256(firstBytes);
+  const secondHash = sha256(secondBytes);
+  fs.writeFileSync(path.join(sourceDir, 'first.md'), firstBytes);
+  fs.writeFileSync(path.join(sourceDir, 'second.md'), secondBytes);
+  fs.symlinkSync('first.md', path.join(sourceDir, 'current.md'));
+
+  const sourceDb = new Database(':memory:');
+  const sourceContent = createEntityContent({ dir: sourceDir });
+  const sourceCloud = createEntityCloud({
+    db: sourceDb, userId: 'user-1', deviceId: 'source-device', content: sourceContent,
+  });
+  const sourceRegistry = createRegistry({ db: sourceDb, ephemeral: true, emit: () => {}, journal: sourceCloud.journal });
+  const root = sourceRegistry.enrollRoot({ type: 'workspace', name: 'project' });
+  sourceRegistry.create({ type: 'file.text', parentUUID: root.uuid, name: 'first.md', payloadVersion: firstHash });
+  sourceRegistry.create({ type: 'file.text', parentUUID: root.uuid, name: 'second.md', payloadVersion: secondHash });
+  const link = sourceRegistry.create({ type: 'link', parentUUID: root.uuid, name: 'current.md', payloadVersion: 'first.md' });
+  sourceContent.captureFile({ filePath: path.join(sourceDir, 'first.md'), contentHash: firstHash });
+  sourceContent.captureFile({ filePath: path.join(sourceDir, 'second.md'), contentHash: secondHash });
+  const initialParts = [
+    ...uploadedParts(sourceContent, sourceCloud.identity().resourceId, firstHash),
+    ...uploadedParts(sourceContent, sourceCloud.identity().resourceId, secondHash),
+  ];
+  const snapshot = snapshotFromRecords(sourceRegistry.syncRecords());
+  const snapshotBytes = Buffer.from(JSON.stringify(snapshot), 'utf8');
+  const target = createRegistrationService({
+    dir: targetState, homeDir: path.join(rootDir, 'target-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'target-device',
+  });
+  try {
+    target.entityCloud.install({
+      registry: target.registration.registry, resourceId: sourceCloud.identity().resourceId,
+      authorityEpoch: 7, headVersion: 41, snapshotBase64: snapshotBytes.toString('base64'),
+      snapshotChecksum: sha256(snapshotBytes),
+    });
+    for (const part of [...initialParts.filter((part) => part.kind === 'manifest'), ...initialParts.filter((part) => part.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: sourceCloud.identity().resourceId, contentHash: part.contentHash, kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex, sha256: part.sha256, dataBase64: part.dataBase64,
+      });
+    }
+    const job = await target.add({ uuid: root.uuid, targetPath: targetParent });
+    assert.equal(job.state, 'complete', job.error);
+    const destination = path.join(targetParent, 'project');
+    assert.equal(fs.readlinkSync(path.join(destination, 'current.md')), 'first.md');
+    assert.equal(target.registration.registry.syncRecord(link.uuid).uuid, link.uuid);
+    assert.equal(target.observer.status().find((entry) => entry.path === fs.realpathSync(destination))?.watching, true);
+    const afterAddDb = new Database(path.join(targetState, 'identity.db'), { readonly: true });
+    try {
+      assert.equal(afterAddDb.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
+        'the first authoritative link binding does not create an outbound mutation');
+    } finally {
+      afterAddDb.close();
+    }
+
+    const changed = sourceRegistry.attest(link.uuid, { type: 'link', payloadVersion: 'second.md' });
+    const ingested = target.ingestCloudMutation({
+      envelope: {
+        resourceId: sourceCloud.identity().resourceId, mutationId: 'ent_remote_link_change',
+        contract: 'amalgm-entity-registry@1', schemaVersion: 1,
+        operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: sourceRegistry.syncRecord(changed.uuid) },
+      },
+      version: 42, committedAt: '2026-08-05T00:00:00.000Z',
+    });
+    assert.equal(ingested.materializations.length, 1);
+    assert.equal(fs.readlinkSync(path.join(destination, 'current.md')), 'second.md');
+    assert.equal(target.registration.registry.syncRecord(link.uuid).payloadVersion, 'second.md');
+    const targetDb = new Database(path.join(targetState, 'identity.db'), { readonly: true });
+    try {
+      assert.equal(targetDb.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
+        'the receiving link watcher did not echo the authoritative retarget upstream');
+    } finally {
+      targetDb.close();
+    }
+  } finally {
+    target.close();
+    sourceDb.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
 test('add recreates an actual Git repository from verified Repocard cargo, then arms its local watcher', async () => {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-repo-materialization-'));
   const sourceState = path.join(rootDir, 'source-state');