amalgm 0.1.249 → 0.1.250

package/lib/cli.js

@@ -1456,6 +1456,8 @@ async function register(positionals) {
   const targets = (positionals.length > 0 ? positionals : [process.cwd()])
     .map((target) => path.resolve(target));
 
+  console.log(`Registering ${targets.length === 1 ? targets[0] : `${targets.length} locations`}…`);
+
   // A resolved port is not a running runtime — the manifest supplies a
   // default whether or not anything listens — so both "no port for this
   // scope" and "nothing answered" mean the same thing to the user.
@@ -1487,6 +1489,8 @@ async function register(positionals) {
     const target = targets[index];
     console.log(`Registered ${rootPath}`);
     console.log(`  ${record.type}  ${record.uuid}`);
+    console.log('  Watching: on');
+    console.log('  Cloud: queued');
     if (rootPath !== target) console.log(`  (${target} is already covered by this tree)`);
   }
 }
@@ -1504,6 +1508,7 @@ async function add(positionals) {
     throw new Error('amalgm add requires a cloud entity UUID');
   }
   const targetPath = path.resolve(positionals[1] || process.cwd());
+  console.log(`Adding ${uuid} to ${targetPath}…`);
   const port = servicePorts().find(([name]) => name === 'amalgm-mcp')?.[1];
   let answer = null;
   if (port) {
@@ -1539,6 +1544,9 @@ async function add(positionals) {
     return;
   }
   let job = answer.payload;
+  if (job?.state === 'waiting_for_content' || job?.state === 'materializing') {
+    console.log('  Downloading cloud content…');
+  }
   const deadline = Date.now() + 120_000;
   while (job?.state === 'waiting_for_content' || job?.state === 'materializing') {
     if (Date.now() > deadline) {
@@ -1555,6 +1563,8 @@ async function add(positionals) {
     return;
   }
   console.log(`Added ${job.entityUuid} to ${job.targetPath}`);
+  console.log('  Watching: on');
+  console.log('  Cloud: live');
 }
 
 /** POST JSON to a local runtime service, carrying the runtime token. */

package/lib/runtime-identity.js

@@ -50,7 +50,10 @@ function runtimeBranchForLabel(label, env = process.env) {
 }
 
 function npmTagForRuntimeLabel(label) {
-  return label === 'preview' ? 'canary' : 'latest';
+  // Releases are promoted deliberately to `main`; `latest` is retained as
+  // the public compatibility channel and may therefore lag the runtime we
+  // boot. A main installation must update from the channel it actually runs.
+  return label === 'preview' ? 'canary' : 'main';
 }
 
 function sanitizeScopeSegment(value, fallback = 'local') {

package/package.json

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

@@ -613,6 +613,45 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
   }
 
+  /** A completed add is a live binding, not a one-time download.  A remote
+   * record beneath that binding moves the durable job back to its content
+   * gate.  The service owns the later filesystem application; this module
+   * owns only the durable intent to do it. */
+  function refreshMaterializations({ resourceId, record, version }) {
+    const refreshed = [];
+    for (const job of db.prepare(`
+      SELECT * FROM entity_materializations
+      WHERE resource_id = ? AND state = 'complete'
+      ORDER BY created_at ASC
+    `).all(resourceId)) {
+      const tree = catalogTree({ resourceId, uuid: job.entity_uuid });
+      if (!tree.some((candidate) => candidate.uuid === record.uuid)) continue;
+      db.prepare(`
+        UPDATE entity_materializations
+        SET head_version = ?, state = 'waiting_for_content', error = NULL, updated_at = ?
+        WHERE job_id = ?
+      `).run(Number(version), now(), job.job_id);
+      refreshed.push(job.job_id);
+    }
+    return refreshed;
+  }
+
+  function hasUnsettledLocalMutation(uuid) {
+    const rows = db.prepare(`
+      SELECT operation_json FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+      ORDER BY sequence ASC
+    `).all(replica()?.resourceId || '');
+    return rows.some((row) => {
+      try {
+        return JSON.parse(row.operation_json)?.record?.uuid === uuid;
+      } catch {
+        // A corrupt local outbox must never authorize an overwrite.
+        return true;
+      }
+    });
+  }
+
   function claim({ limit = 16, leaseMs = 30_000 } = {}) {
     const current = replica();
     if (!current || !['active', BOOTSTRAP_RECONCILIATION_STATE].includes(current.state)) return [];
@@ -781,9 +820,13 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     // Remote mutations update the cloud-only catalog. They never create a
     // local watcher; `amalgm add` alone turns catalog identity into ground.
+    // A pre-existing local record is normally a conflict, except for a
+    // completed add binding with no unsent local edit. That binding will
+    // apply the authoritative cloud record through its own watcher-safe
+    // materializer below; it must not be stranded at its first snapshot.
     let local;
     try { local = registry.syncRecord(record.uuid); } catch { local = null; }
-    if (local && !sameRecord(local, record)) {
+    if (local && !sameRecord(local, record) && hasUnsettledLocalMutation(record.uuid)) {
       throw new Error('remote entity mutation conflicts with this device; refresh the compacted cloud head before applying it locally');
     }
     upsertCatalogRecord({
@@ -793,7 +836,11 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       record,
     });
     if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
-    return { duplicate: true, version: Number(version) };
+    return {
+      duplicate: true,
+      version: Number(version),
+      materializations: refreshMaterializations({ resourceId: current.resourceId, record, version }),
+    };
   }
 
   return {
@@ -816,6 +863,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     completeMaterialization,
     failMaterialization,
     materializationStatus,
+    hasUnsettledLocalMutation,
     catalogTree,
     replica,
   };

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

@@ -744,6 +744,7 @@ function createRegistration(options) {
 
     /** The latest edge pass's refusals — visible, never silent. */
     reported: () => [...reported],
+    addressOf,
     repoState: (uuid) => repoStates.get(uuid),
     tree: treeAt,
     trees: () => new Map(treeRoots()

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

@@ -369,11 +369,167 @@ function createRegistrationService({
     }
   }
 
+  /** The local replica of `amalgm add` is Amalgm-managed ground.  This is
+   * deliberately not a two-way directory merger: if local bytes have drifted
+   * from the last authoritative record, the import stops rather than choosing
+   * a winner behind the user's back.  Otherwise a remote cloud head is
+   * projected into the existing binding, with journal suppression so the
+   * receiver never echoes its own download back to cloud. */
+  function applyLiveCloudTree(job) {
+    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) => ['repo.git', 'link', 'reference'].includes(record.type));
+    if (unsupported) {
+      throw new Error(`live cloud add for ${unsupported.type} is not available yet; the binding was left unchanged`);
+    }
+    if (!['workspace', 'file.text', 'file.binary'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace and file trees only`);
+    }
+    for (const record of active) {
+      if (['file.text', 'file.binary'].includes(record.type)
+        && !entityContent.complete({ contentHash: record.payloadVersion })) return false;
+    }
+
+    const parent = fs.realpathSync(job.targetPath);
+    const destination = path.join(parent, root.name);
+    const boundRoot = boundary.current.tree(destination)?.root();
+    if (!boundRoot || boundRoot.uuid !== root.uuid) {
+      throw new Error(`cloud binding ${root.uuid} no longer owns ${destination}; refusing to overwrite local ground`);
+    }
+
+    const children = new Map();
+    for (const record of active) {
+      if (record.parentUUID === null) continue;
+      const group = children.get(record.parentUUID) || [];
+      group.push(record);
+      children.set(record.parentUUID, group);
+    }
+    for (const group of children.values()) group.sort((left, right) => left.name.localeCompare(right.name));
+
+    function localRecord(uuid) {
+      try { return boundary.current.registry.syncRecord(uuid); } catch { return null; }
+    }
+
+    function addressOf(uuid) {
+      try { return boundary.current.addressOf(uuid); } catch { return null; }
+    }
+
+    function fileHash(file) {
+      return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+
+    // Before changing logical identity, prove that every local byte we could
+    // 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.
+    for (const record of tree) {
+      const current = localRecord(record.uuid);
+      if (!current || current.version === record.version) continue;
+      if (entityCloud.hasUnsettledLocalMutation(record.uuid)) {
+        throw new Error(`local change for ${record.uuid} is still waiting for cloud; refusing to overwrite it`);
+      }
+      if (!['file.text', 'file.binary'].includes(current.type)) continue;
+      const currentPath = addressOf(record.uuid);
+      if (!currentPath || !fs.existsSync(currentPath)) {
+        throw new Error(`local file for ${record.uuid} is missing; refusing to overwrite an unverified binding`);
+      }
+      if (fileHash(currentPath) !== current.payloadVersion) {
+        throw new Error(`local file ${currentPath} changed outside Amalgm; refusing to overwrite it`);
+      }
+    }
+
+    function applyKnownRecords() {
+      // Catalog container versions are deliberately regenerated by the
+      // authority after child mutations.  Applying an unchanged container
+      // before its later child would therefore compare an old derived version.
+      // Only import records whose stored logical fields actually changed; the
+      // local registry derives the same container version after the child lands.
+      const depth = new Map([[root.uuid, 0]]);
+      for (const record of tree) {
+        if (record.parentUUID !== null) depth.set(record.uuid, (depth.get(record.parentUUID) || 0) + 1);
+      }
+      for (const record of [...tree].sort((left, right) => (depth.get(left.uuid) || 0) - (depth.get(right.uuid) || 0))) {
+        const current = localRecord(record.uuid);
+        if (current && current.type === record.type && current.parentUUID === record.parentUUID
+          && current.name === record.name && current.status === record.status
+          && current.payloadVersion === record.payloadVersion) continue;
+        boundary.current.registry.applyCloudRecord(record);
+      }
+    }
+
+    function atomicWrite(file, bytes) {
+      const temporary = path.join(path.dirname(file), `.${path.basename(file)}.amalgm-live-${crypto.randomBytes(10).toString('hex')}`);
+      try {
+        fs.writeFileSync(temporary, bytes, { mode: 0o600, flag: 'wx' });
+        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);
+      if (!known || known.status === 'active') {
+        throw new Error(`local item ${target} is not owned by this cloud binding; refusing to remove it`);
+      }
+      if (['file.text', 'file.binary'].includes(known.type) && fs.existsSync(target)) {
+        const previous = localRecord(known.uuid);
+        if (previous?.payloadVersion && fileHash(target) !== previous.payloadVersion) {
+          throw new Error(`local file ${target} changed outside Amalgm; refusing to remove it`);
+        }
+      }
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+
+    function project(record, target) {
+      if (record.type === 'workspace' || record.type === 'folder') {
+        if (fs.existsSync(target)) {
+          if (!fs.statSync(target).isDirectory()) {
+            throw new Error(`cloud container ${record.uuid} conflicts with local non-directory ${target}`);
+          }
+        } else {
+          fs.mkdirSync(target, { mode: 0o700 });
+        }
+        const wanted = new Set((children.get(record.uuid) || []).map((child) => child.name));
+        for (const child of children.get(record.uuid) || []) project(child, path.join(target, child.name));
+        for (const entry of fs.readdirSync(target)) {
+          if (!wanted.has(entry)) removeInactiveChild(record, entry, path.join(target, entry));
+        }
+        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`);
+      }
+      if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+        throw new Error(`cloud file ${record.uuid} conflicts with local directory ${target}`);
+      }
+      const bytes = entityContent.bytes({ contentHash: record.payloadVersion });
+      if (fs.existsSync(target) && Buffer.compare(fs.readFileSync(target), bytes) === 0) return;
+      atomicWrite(target, bytes);
+    }
+
+    boundary.current.registry.withoutJournal(() => {
+      applyKnownRecords();
+      project(root, destination);
+      const observerRoot = observer.listRoots().find((entry) => entry.path === destination);
+      if (!observerRoot) throw new Error(`cloud binding ${root.uuid} has no local watcher root at ${destination}`);
+      observer.scanNow(observerRoot.rootId);
+      boundary.current.flushIfDirty();
+    });
+    return { destination, root };
+  }
+
   function advanceMaterializations() {
     for (const job of entityCloud.pendingMaterializations()) {
       if (job.state !== 'waiting_for_content') continue;
       try {
-        const result = materializeCloudTree(job);
+        const root = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid })[0];
+        const destination = path.join(fs.realpathSync(job.targetPath), root.name);
+        const result = boundary.current.tree(destination)?.root()?.uuid === root.uuid
+          ? applyLiveCloudTree(job)
+          : materializeCloudTree(job);
         if (result) entityCloud.completeMaterialization({ jobId: job.jobId });
       } catch (error) {
         entityCloud.failMaterialization({ jobId: job.jobId, message: error.message });
@@ -402,6 +558,27 @@ function createRegistrationService({
       advanceMaterializations();
       return entityCloud.materializationStatus(job.jobId);
     },
+    /** The inbound realtime rail is part of the add binding.  Routes call
+     * these composition methods so receiving an authoritative record or one
+     * of its immutable content parts immediately advances the local replica;
+     * users never run a separate sync command. */
+    ingestCloudMutation: ({ envelope, version, committedAt }) => {
+      const ingested = entityCloud.ingest({
+        registry: boundary.current.registry,
+        envelope,
+        version,
+        committedAt,
+      });
+      advanceMaterializations();
+      return ingested;
+    },
+    receiveCloudContent: ({ resourceId, contentHash, kind, partIndex, sha256, dataBase64 }) => {
+      const received = entityCloud.receiveDownload({
+        resourceId, contentHash, kind, partIndex, sha256, dataBase64,
+      });
+      advanceMaterializations();
+      return received;
+    },
     advanceMaterializations,
     bootstrapUserHome,
     exactUserHomeCloudRecords,

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

@@ -240,7 +240,7 @@ async function handleEntityRoutes(ctx) {
     const body = await ctx.readJsonBody();
     const service = registrationService();
     try {
-      const received = service.entityCloud.receiveDownload({
+      const received = service.receiveCloudContent({
         resourceId: body?.resourceId,
         contentHash: body?.contentHash,
         kind: body?.kind,
@@ -248,7 +248,6 @@ async function handleEntityRoutes(ctx) {
         sha256: body?.sha256,
         dataBase64: body?.dataBase64,
       });
-      service.advanceMaterializations();
       ctx.sendJson(200, { ...received });
     } catch (error) {
       ctx.sendJson(400, { error: error.message });
@@ -290,12 +289,12 @@ async function handleEntityRoutes(ctx) {
     const body = await ctx.readJsonBody();
     const service = registrationService();
     try {
-      ctx.sendJson(200, service.entityCloud.ingest({
-        registry: service.registration.registry,
+      const ingested = service.ingestCloudMutation({
         envelope: body?.envelope,
         version: body?.version,
         committedAt: body?.committedAt,
-      }));
+      });
+      ctx.sendJson(200, ingested);
     } catch (error) {
       ctx.sendJson(409, { error: error.message });
     }

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

@@ -116,3 +116,108 @@ test('add materializes one compacted cloud head, preserves its UUIDs, and starts
     fs.rmSync(rootDir, { recursive: true, force: true });
   }
 });
+
+test('an added ordinary workspace stays live: a later cloud file head replaces local bytes without producing an echo mutation', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-live-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 authoritative content\n');
+  const firstHash = sha256(firstBytes);
+  fs.writeFileSync(path.join(sourceDir, 'readme.md'), firstBytes);
+  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' });
+  const file = sourceRegistry.create({
+    type: 'file.text', parentUUID: root.uuid, name: 'readme.md', payloadVersion: firstHash,
+  });
+  sourceContent.captureFile({ filePath: path.join(sourceDir, 'readme.md'), contentHash: firstHash });
+  const initialParts = uploadedParts(sourceContent, sourceCloud.identity().resourceId, firstHash);
+  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.entityCloud.receiveDownload({
+        resourceId: sourceCloud.identity().resourceId,
+        contentHash: firstHash,
+        kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256,
+        dataBase64: part.dataBase64,
+      });
+    }
+    assert.equal((await target.add({ uuid: root.uuid, targetPath: targetParent })).state, 'complete');
+
+    const secondBytes = Buffer.from('second authoritative content\n');
+    const secondHash = sha256(secondBytes);
+    fs.writeFileSync(path.join(sourceDir, 'readme.md'), secondBytes);
+    sourceContent.captureFile({ filePath: path.join(sourceDir, 'readme.md'), contentHash: secondHash });
+    const secondParts = uploadedParts(sourceContent, sourceCloud.identity().resourceId, secondHash);
+    const changed = sourceRegistry.attest(file.uuid, { type: 'file.text', payloadVersion: secondHash });
+    const remoteRecord = sourceRegistry.syncRecord(changed.uuid);
+
+    const ingested = target.ingestCloudMutation({
+      envelope: {
+        resourceId: sourceCloud.identity().resourceId,
+        mutationId: 'ent_remote_file_change',
+        contract: 'amalgm-entity-registry@1',
+        schemaVersion: 1,
+        operationKind: 'entity.upsert',
+        operation: { kind: 'entity.upsert', record: remoteRecord },
+      },
+      version: 42,
+      committedAt: '2026-08-05T00:00:00.000Z',
+    });
+    assert.equal(ingested.materializations.length, 1, 'the completed add became a live pending application');
+    assert.equal(fs.readFileSync(path.join(targetParent, 'project', 'readme.md'), 'utf8'), firstBytes.toString(),
+      'the destination waits for verified immutable bytes');
+
+    for (const part of [...secondParts.filter((part) => part.kind === 'manifest'), ...secondParts.filter((part) => part.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: sourceCloud.identity().resourceId,
+        contentHash: secondHash,
+        kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256,
+        dataBase64: part.dataBase64,
+      });
+    }
+    assert.deepEqual(fs.readFileSync(path.join(targetParent, 'project', 'readme.md')), secondBytes);
+    assert.equal(target.registration.registry.syncRecord(file.uuid).payloadVersion, secondHash);
+    assert.equal(target.observer.status().find((entry) => entry.path === fs.realpathSync(path.join(targetParent, 'project')))?.watching, true);
+
+    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 watcher did not echo the imported cloud edit as a new local mutation');
+    } finally {
+      targetDb.close();
+    }
+  } finally {
+    target.close();
+    sourceDb.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});