amalgm 0.1.246 → 0.1.247

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

@@ -90,23 +90,64 @@ CREATE TABLE IF NOT EXISTS entity_cloud_mutations (
 );
 CREATE INDEX IF NOT EXISTS entity_cloud_mutations_pending
   ON entity_cloud_mutations (resource_id, mutation_state, sequence);
+CREATE TABLE IF NOT EXISTS entity_cloud_catalog_state (
+  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+  resource_id TEXT NOT NULL,
+  authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
+  snapshot_version INTEGER NOT NULL CHECK (snapshot_version >= 0),
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS entity_cloud_catalog (
+  resource_id TEXT NOT NULL,
+  entity_uuid TEXT NOT NULL,
+  record_json TEXT NOT NULL,
+  snapshot_epoch INTEGER NOT NULL CHECK (snapshot_epoch >= 1),
+  snapshot_version INTEGER NOT NULL CHECK (snapshot_version >= 0),
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (resource_id, entity_uuid)
+);
+CREATE INDEX IF NOT EXISTS entity_cloud_catalog_snapshot
+  ON entity_cloud_catalog (resource_id, snapshot_epoch, snapshot_version);
+CREATE TABLE IF NOT EXISTS entity_materializations (
+  job_id TEXT PRIMARY KEY,
+  resource_id TEXT NOT NULL,
+  entity_uuid TEXT NOT NULL,
+  target_path TEXT NOT NULL,
+  authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
+  head_version INTEGER NOT NULL CHECK (head_version >= 0),
+  state TEXT NOT NULL CHECK (state IN ('waiting_for_content', 'materializing', 'complete', 'failed')),
+  error TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS entity_materializations_pending
+  ON entity_materializations (resource_id, state, created_at);
 `;
 
 const CORE_TABLES = ['registry_meta', 'entities', 'channel_bindings', 'contested_ground'];
 const REPO_STATE_TABLES = [...CORE_TABLES, 'repo_states'];
-const TABLES = [...REPO_STATE_TABLES, 'entity_cloud_replica', 'entity_cloud_mutations'];
+const CLOUD_TABLES = ['entity_cloud_replica', 'entity_cloud_mutations'];
+const MATERIALIZATION_TABLES = ['entity_cloud_catalog_state', 'entity_cloud_catalog', 'entity_materializations'];
+const TABLES = [...REPO_STATE_TABLES, ...CLOUD_TABLES, ...MATERIALIZATION_TABLES];
 
 // The schema generation this code speaks, stamped as PRAGMA user_version at
 // creation — completeness is judged against a declared shape, never
 // guessed. Generation 3 adds the current Card + Checkpoint document for
 // each repo.git entity. Generation 4 adds the entity-cloud replica and its
 // durable outbox to that SAME identity database: a local entity mutation and
-// the cloud delivery intent must commit together. Generations 2 and 3 are
+// the cloud delivery intent must commit together. Generation 5 adds the
+// cloud-only catalog and durable materialization jobs: remote graph facts may
+// be known locally before any observer is bound, so they cannot masquerade
+// as local registered ground. Generation 6 records the one snapshot version
+// that populated that catalog; a later mutation tail cannot pose as a fresh
+// active head for `amalgm add`. Generations 2 and 3 are
 // additive predecessors: migrations only add tables beside existing identity
 // records, never rewrite UUIDs or evidence bindings. The per-tree era never
 // stamped a version and reads 0 — an older generation, refused distinctly
 // from loss until an explicit migration exists.
-const GENERATION = 4;
+const GENERATION = 6;
+const MATERIALIZATION_GENERATION = 5;
+const CLOUD_GENERATION = 4;
 const REPO_STATE_GENERATION = 3;
 const PREVIOUS_GENERATION = 2;
 
@@ -132,15 +173,25 @@ function inspect(db) {
 
 function isMigratableGenerationShape(db, inspection) {
   const generation = db.pragma('user_version', { simple: true });
+  if (generation === MATERIALIZATION_GENERATION) {
+    return inspection.missing.length === 1
+      && inspection.missing[0] === 'entity_cloud_catalog_state'
+      && TABLES.filter((name) => name !== 'entity_cloud_catalog_state').every((name) => !inspection.missing.includes(name));
+  }
+  if (generation === CLOUD_GENERATION) {
+    return inspection.missing.length === MATERIALIZATION_TABLES.length
+      && MATERIALIZATION_TABLES.every((name) => inspection.missing.includes(name))
+      && [...REPO_STATE_TABLES, ...CLOUD_TABLES].every((name) => !inspection.missing.includes(name));
+  }
   if (generation === PREVIOUS_GENERATION) {
-    return inspection.missing.length === 3
-      && ['repo_states', 'entity_cloud_replica', 'entity_cloud_mutations']
+    return inspection.missing.length === ['repo_states', ...CLOUD_TABLES, ...MATERIALIZATION_TABLES].length
+      && ['repo_states', ...CLOUD_TABLES, ...MATERIALIZATION_TABLES]
         .every((name) => inspection.missing.includes(name))
       && CORE_TABLES.every((name) => !inspection.missing.includes(name));
   }
   return generation === REPO_STATE_GENERATION
-    && inspection.missing.length === 2
-    && ['entity_cloud_replica', 'entity_cloud_mutations']
+    && inspection.missing.length === [...CLOUD_TABLES, ...MATERIALIZATION_TABLES].length
+    && [...CLOUD_TABLES, ...MATERIALIZATION_TABLES]
       .every((name) => inspection.missing.includes(name))
     && REPO_STATE_TABLES.every((name) => !inspection.missing.includes(name));
 }

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

@@ -31,6 +31,14 @@ async function handleAutomationRoutes(ctx) {
     await automationsRest.handleRuns(await ctx.readJsonBody(), ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/automations/deliveries' && ctx.method === 'POST') {
+    await automationsRest.handleDeliveries(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/deliveries/retry' && ctx.method === 'POST') {
+    await automationsRest.handleDeliveryRetry(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   if (ctx.pathname === '/automations/validate' && ctx.method === 'POST') {
     await automationsRest.handleValidate(await ctx.readJsonBody(), ctx.sendJson);
     return true;

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

@@ -211,6 +211,37 @@ async function handleEntityRoutes(ctx) {
     return true;
   }
 
+  // Cloud-to-local content is claimed by the existing realtime tunnel. A
+  // materialization job never opens R2 itself; it asks the authenticated
+  // gateway for the exact immutable manifest/chunk named by its pinned
+  // snapshot, then retries safely until its local content cache verifies it.
+  if (ctx.pathname === '/entities/cloud/content/downloads/claim' && ctx.method === 'POST') {
+    const service = registrationService();
+    service.advanceMaterializations();
+    ctx.sendJson(200, { download: service.entityCloud.claimDownload() });
+    return true;
+  }
+
+  if (ctx.pathname === '/entities/cloud/content/downloads/receive' && ctx.method === 'POST') {
+    const body = await ctx.readJsonBody();
+    const service = registrationService();
+    try {
+      const received = service.entityCloud.receiveDownload({
+        resourceId: body?.resourceId,
+        contentHash: body?.contentHash,
+        kind: body?.kind,
+        partIndex: body?.partIndex,
+        sha256: body?.sha256,
+        dataBase64: body?.dataBase64,
+      });
+      service.advanceMaterializations();
+      ctx.sendJson(200, { ...received });
+    } catch (error) {
+      ctx.sendJson(400, { error: error.message });
+    }
+    return true;
+  }
+
   if (ctx.pathname === '/entities/cloud/mutations/ack' && ctx.method === 'POST') {
     const body = await ctx.readJsonBody();
     try {
@@ -257,6 +288,31 @@ async function handleEntityRoutes(ctx) {
     return true;
   }
 
+  if (ctx.pathname === '/entities/add' && ctx.method === 'POST') {
+    const body = await ctx.readJsonBody();
+    const service = registrationService();
+    try {
+      const job = await service.add({ uuid: body?.uuid, targetPath: body?.path });
+      ctx.sendJson(job.state === 'complete' ? 200 : 202, job);
+    } catch (error) {
+      ctx.sendJson(409, { error: error.message });
+    }
+    return true;
+  }
+
+  const materializationMatch = /^\/entities\/add\/(mat_[A-Za-z0-9_-]+)$/.exec(ctx.pathname);
+  if (materializationMatch && ctx.method === 'GET') {
+    const service = registrationService();
+    service.advanceMaterializations();
+    const job = service.entityCloud.materializationStatus(materializationMatch[1]);
+    if (!job) {
+      ctx.sendJson(404, { error: 'cloud materialization does not exist' });
+    } else {
+      ctx.sendJson(200, job);
+    }
+    return true;
+  }
+
   if (ctx.pathname !== '/entities/register' || ctx.method !== 'POST') return false;
 
   const body = await ctx.readJsonBody();

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

@@ -87,6 +87,20 @@ async function handleWorkspaceRoutes(ctx) {
     await workspaceRest.handleCloudWorkspaceAttachment(await ctx.readJsonBody(), ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/workspace/materialize' && ctx.method === 'POST') {
+    try {
+      const result = await require('../../workspace/materialize').materializeWorkspace(
+        await ctx.readJsonBody(),
+      );
+      ctx.sendJson(200, result);
+    } catch (error) {
+      ctx.sendJson(Number(error?.statusCode) || 500, {
+        error: error instanceof Error ? error.message : 'Workspace materialization failed',
+        code: error?.code || 'workspace_materialization_failed',
+      });
+    }
+    return true;
+  }
   if (ctx.pathname === '/workspace/access' && ctx.method === 'GET') {
     workspaceRest.handleAccessRead(ctx.getQuery(), ctx.sendJson);
     return true;

package/runtime/scripts/amalgm-mcp/tests/adapters.test.js

@@ -231,7 +231,7 @@ test('a membership that cannot be read completely is unsettled — never quietly
 });
 
 test('STITCH: production detection and the adapter speak one truth — no parallel detector', () => {
-  // The observer's content decision (safeHash) now reads through the
+  // The observer's content decision (safeContent) now reads through the
   // adapter socket. Prove agreement on real ground: the hash the
   // production observer records for a file is byte-identical to the
   // truth the adapter answers for the same ground.

package/runtime/scripts/amalgm-mcp/tests/doorbell.matrix.watch.test.js

@@ -42,7 +42,7 @@ async function live(lay, run) {
   try {
     const dir = makeDir('live');
     lay(dir);
-    const { observer, events } = makeObserver({ settleMs: 25 });
+    const { observer, events } = makeObserver({ settleMs: 25, prove: fake.prove });
     const root = observer.enrollRoot(dir);
     observer.start();
     try {
@@ -174,7 +174,7 @@ test('entrance — the single-file root\'s parent doorbell: the parent hears wha
     const holder = makeDir('single');
     const file = path.join(holder, 'solo.md');
     fs.writeFileSync(file, 'v1');
-    const { observer, events } = makeObserver({ settleMs: 25 });
+    const { observer, events } = makeObserver({ settleMs: 25, prove: fake.prove });
     const root = observer.enrollRoot(file);
     assert.equal(root.kind, 'file', 'the smallest root: one channel');
     observer.start();

package/runtime/scripts/amalgm-mcp/tests/email-render-goldens/citations.html

@@ -1,5 +1,5 @@
-<p style="margin:0;line-height:1.75;color:#ffffff">Inline file citation: <span title="Project notes" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>notes.md</span> mid-sentence.</p>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Every icon kind: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-react" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>app.tsx</span> letter-react, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-letter-ts-3178c6-ffffff" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>main.ts</span> letter, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>readme.md</span> path, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-braces-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>data.json</span> lucide, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-filetext-f87171" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>report.pdf</span> lucide-color.</p></div>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Special filenames: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-package-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>package.json</span> and <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-lock-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>.env.local</span> and <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-package-38bdf8" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>Dockerfile</span>.</p></div>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Folder: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-folder-d6d3d1" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>src</span>, skill: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-box-d6d3d1" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>pdf-tools</span>, agent: <span title="Research agent" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-atsign-ffffff" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>@researcher</span>.</p></div>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Unknown extension falls back: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-lucide-file-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>blob.xyz</span>.</p></div>
+<p style="margin:0;line-height:1.75;color:#ffffff">Inline file citation: <span title="Project notes" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>notes.md</span> mid-sentence.</p>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Every icon kind: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-react" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>app.tsx</span> letter-react, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-letter-ts-3178c6-ffffff" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>main.ts</span> letter, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>readme.md</span> path, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-braces-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>data.json</span> lucide, <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-filetext-f87171" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>report.pdf</span> lucide-color.</p></div>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Special filenames: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-package-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>package.json</span> and <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-lock-facc15" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>.env.local</span> and <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-package-38bdf8" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>Dockerfile</span>.</p></div>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Folder: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-folder-d6d3d1" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>src</span>, skill: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-box-d6d3d1" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>pdf-tools</span>, agent: <span title="Research agent" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-atsign-ffffff" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>@researcher</span>.</p></div>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Unknown extension falls back: <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-lucide-file-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>blob.xyz</span>.</p></div>

package/runtime/scripts/amalgm-mcp/tests/email-render-goldens/links.html

@@ -1,3 +1,3 @@
-<p style="margin:0;line-height:1.75;color:#ffffff">Web citation: read <a href="https://www.anthropic.com/news" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="https://www.google.com/s2/favicons?domain=www.anthropic.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>Anthropic</a> for details.</p>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Bare-ish label: <a href="https://example.com/" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="https://www.google.com/s2/favicons?domain=example.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>example.com</a> and a deep link <a href="https://amalgm.ai/tab?kind=tasks&amp;id=run-1" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="https://www.google.com/s2/favicons?domain=amalgm.ai&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>View run</a>.</p></div>
-<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">A link with <strong style="color:#ffffff;font-weight:600">bold</strong> around it: <strong style="color:#ffffff;font-weight:600">see <a href="https://docs.example.dev/guide" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="https://www.google.com/s2/favicons?domain=docs.example.dev&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>docs</a></strong> now.</p></div>
+<p style="margin:0;line-height:1.75;color:#ffffff">Web citation: read <a href="https://www.anthropic.com/news" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="https://www.google.com/s2/favicons?domain=www.anthropic.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>Anthropic</a> for details.</p>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Bare-ish label: <a href="https://example.com/" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="https://www.google.com/s2/favicons?domain=example.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>example.com</a> and a deep link <a href="https://amalgm.ai/tab?kind=tasks&amp;id=run-1" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="https://www.google.com/s2/favicons?domain=amalgm.ai&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>View run</a>.</p></div>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">A link with <strong style="color:#ffffff;font-weight:600">bold</strong> around it: <strong style="color:#ffffff;font-weight:600">see <a href="https://docs.example.dev/guide" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="https://www.google.com/s2/favicons?domain=docs.example.dev&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>docs</a></strong> now.</p></div>

package/runtime/scripts/amalgm-mcp/tests/email-render-goldens/notification-shell.html

@@ -3,7 +3,7 @@
 <body style="margin:0;padding:0;background:#000000;font-family:"SF Pro Text", "SF Pro Display", -apple-system, BlinkMacSystemFont, system-ui, sans-serif">
 <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#000000"><tr><td align="center" style="padding:0">
   <table role="presentation" width="520" cellpadding="0" cellspacing="0" style="max-width:520px;width:100%"><tr><td style="padding:40px 28px 48px">
-    <div style="font-size:14px;color:#ffffff"><p style="margin:0;line-height:1.75;color:#ffffff">Run finished. See <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>notes.md</span>.</p></div>
+    <div style="font-size:14px;color:#ffffff"><p style="margin:0;line-height:1.75;color:#ffffff">Run finished. See <span class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="cid:amalgm-icon-path-markdown-a8a29e" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;vertical-align:-1px"></span>notes.md</span>.</p></div>
     <p style="margin:24px 0 0"><a href="https://amalgm.ai/tab?kind=tasks&amp;id=run-1" style="color:#60a5fa;text-decoration:none;font-size:14px">View details &rarr;</a></p>
     <p style="margin:48px 0 0;font-size:12px;color:#ffffff">amalgm.ai</p>
   </td></tr></table>

package/runtime/scripts/amalgm-mcp/tests/email-render-goldens/share-invite.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
+<body style="margin:0;padding:0;background:#000000;font-family:'SF Pro Text', 'SF Pro Display', -apple-system, BlinkMacSystemFont, system-ui, sans-serif">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#000000"><tr><td align="center" style="padding:0">
+  <table role="presentation" width="520" cellpadding="0" cellspacing="0" style="max-width:520px;width:100%;background:#000000;border:1px solid #292524;border-radius:8px;border-collapse:separate;overflow:hidden"><tr><td style="padding:40px 28px 48px">
+    <div style="font-size:14px;color:#ffffff"><h2 style="margin:0;font-size:16px;font-weight:400;color:#ffffff;line-height:1.35"><strong style="font-weight:650">Aayush Trivedi</strong> shared a file with you</h2>
+<div style="margin:15px 0 0"><a href="https://amalgm.ai/s/s1i_abcdefghijklmnopqrstuvwxyzABCDEFGH123456789" target="_blank" style="text-decoration:none;display:block;background:#000000;border:1px solid #1c1917;border-radius:12px;padding:0;margin:2px 0"><table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border-collapse:collapse"><tr><td style="padding:8px 0 8px 12px;vertical-align:middle;line-height:0;width:14px"><img src="cid:amalgm-icon-lucide-filetext-f87171" alt="" width="14" height="14" style="display:inline-block;width:14px;height:14px;border:0"></td><td style="padding:8px 12px 8px 10px;vertical-align:middle"><span style="font-size:14px;line-height:18px;color:#ffffff;font-weight:650;white-space:nowrap">Q3 launch brief.pdf</span></td><td align="right" style="padding:8px 12px 8px 0;vertical-align:middle;line-height:0;width:14px"><img src="cid:amalgm-icon-lucide-externallink-ffffff" alt="" width="14" height="14" style="display:inline-block;width:14px;height:14px;border:0"></td></tr></table></a></div>
+<div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">You can <strong style="color:#ffffff;font-weight:600">edit</strong> this file.</p></div>
+<div style="margin:15px 0 0"><blockquote style="margin:0;line-height:1.75;font-style:italic;padding:0 0 0 16px;border-left:3px solid #292524;color:#d6d3d1">sam@acme.com &mdash; sign in with this address to accept.</blockquote></div></div>
+    <p style="margin:48px 0 0;font-size:12px;color:#ffffff">amalgm.ai</p>
+  </td></tr></table>
+</td></tr></table>
+</body></html>

package/runtime/scripts/amalgm-mcp/tests/email-render-goldens/text.html

@@ -2,7 +2,7 @@
 <div style="margin:15px 0 0"><h2 style="margin:0;font-size:16px;font-weight:650;color:#ffffff;line-height:1.35">Heading two</h2></div>
 <div style="margin:15px 0 0"><h3 style="margin:0;font-size:15px;font-weight:650;color:#ffffff;line-height:1.35">Heading three</h3></div>
 <div style="margin:15px 0 0"><p style="margin:0;line-height:1.75;color:#ffffff">Body text with <strong style="color:#ffffff;font-weight:600">bold</strong>, <em>italic</em>, <strong style="color:#ffffff;font-weight:600"><em>bold italic</em></strong>, and <code style="background:#0a0a0a;border:1px solid #1c1917;padding:1.875px 7.5px;border-radius:5.625px;font-size:12px;line-height:1.2;font-family:'JetBrains Mono', 'SFMono-Regular', Menlo, monospace;color:#f5f5f4">inline code</code>.</p></div>
-<div style="margin:15px 0 0"><ul style="margin:0;padding-left:24px;color:#ffffff"><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">bullet one</li><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">bullet two with <a href="https://example.com/a" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:middle"><img src="https://www.google.com/s2/favicons?domain=example.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>a link</a></li></ul></div>
+<div style="margin:15px 0 0"><ul style="margin:0;padding-left:24px;color:#ffffff"><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">bullet one</li><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">bullet two with <a href="https://example.com/a" target="_blank" rel="noreferrer" class="render-citation" style="display:inline;vertical-align:baseline;font:inherit;font-size:inherit;line-height:inherit;color:#60a5fa;text-decoration:none;white-space:nowrap;padding:0;background:transparent;border:none;"><span style="display:inline-block;width:12px;height:12px;font-size:12px;line-height:12px;margin-right:0.3em;vertical-align:-0.1em"><img src="https://www.google.com/s2/favicons?domain=example.com&amp;sz=32" alt="" width="12" height="12" style="display:inline-block;width:12px;height:12px;border:0;border-radius:3px;vertical-align:-1px"></span>a link</a></li></ul></div>
 <div style="margin:15px 0 0"><ol style="margin:0;padding-left:24px;color:#ffffff"><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">ordered one</li><li style="margin:4px 0;padding:3.75px 0;line-height:1.5;color:#ffffff">ordered two</li></ol></div>
 <div style="margin:15px 0 0"><blockquote style="margin:0;line-height:1.75;font-style:italic;padding:0 0 0 16px;border-left:3px solid #292524;color:#d6d3d1">A quote line continues here.</blockquote></div>
 <div style="margin:15px 0 0"><div style="border:1px solid #292524;border-radius:12px;overflow:hidden;margin:0"><table style="width:100%;border-collapse:collapse"><thead><tr><th style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;border-right:1px solid #292524;border-bottom:1px solid #292524;background:#0c0b0a;font-weight:500;color:#ffffff">Metric</th><th style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;border-bottom:1px solid #292524;background:#0c0b0a;font-weight:500;color:#ffffff">Value</th></tr></thead><tbody><tr><td style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;border-right:1px solid #292524;border-bottom:1px solid #292524;color:#ffffff">Sessions</td><td style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;border-bottom:1px solid #292524;color:#ffffff">42</td></tr><tr><td style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;border-right:1px solid #292524;color:#ffffff">Errors</td><td style="padding:5.625px 11.25px;text-align:left;vertical-align:top;font-size:14px;line-height:1.5;color:#ffffff">0</td></tr></tbody></table></div></div>

package/runtime/scripts/amalgm-mcp/tests/email-render.test.js

@@ -17,7 +17,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 const test = require('node:test');
 
-const { markdownToEmailHtml, formatNotificationEmail } = require('../lib/email-md');
+const {
+  markdownToEmailHtml,
+  formatNotificationEmail,
+  formatShareInviteEmail,
+} = require('../lib/email-md');
 const { prepareEmailIconAttachments } = require('../lib/email-icons');
 
 const FIXTURE_DIR = path.join(__dirname, 'email-render-fixtures');
@@ -56,6 +60,18 @@ test('email render golden: notification shell', () => {
   assertGolden('notification-shell.html', `${html}\n`);
 });
 
+test('email render golden: share invite shell', () => {
+  const html = formatShareInviteEmail({
+    sharerName: 'Aayush Trivedi',
+    recipientEmail: 'sam@acme.com',
+    entityName: 'Q3 launch brief.pdf',
+    entityType: 'file',
+    inviteUrl: 'https://amalgm.ai/s/s1i_abcdefghijklmnopqrstuvwxyzABCDEFGH123456789',
+    access: 'edit',
+  });
+  assertGolden('share-invite.html', `${html}\n`);
+});
+
 test('every cid icon referenced by goldens has a PNG asset', () => {
   const htmls = fs
     .readdirSync(GOLDEN_DIR)

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

@@ -0,0 +1,189 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const Database = require('better-sqlite3');
+const { createRegistry } = require('../registry');
+const { createEntityCloud, parseSnapshot, snapshotFromRecords } = require('../registration/entity-cloud');
+const { createEntityContent } = require('../registration/entity-content');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+test('the entity cloud snapshot establishes identity, then each later entity commit has one durable ordered outbox row', () => {
+  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' });
+  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 snapshot = parseSnapshot(Buffer.from(bootstrap.snapshotBase64, 'base64'));
+  assert.deepEqual(snapshot.records.map((record) => record.uuid), [root.uuid]);
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+
+  const first = registry.create({ type: 'file.text', parentUUID: root.uuid, name: 'one.md', payloadVersion: 'head-one' });
+  const second = registry.create({ type: 'file.text', parentUUID: root.uuid, name: 'two.md', payloadVersion: 'head-two' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 2);
+
+  const firstClaim = cloud.claim();
+  assert.equal(firstClaim.length, 1, 'one resource emits one operation at a time so base versions cannot race');
+  assert.equal(firstClaim[0].baseVersion, 0);
+  assert.equal(firstClaim[0].operation.record.uuid, first.uuid);
+  cloud.acknowledge({
+    resourceId: firstClaim[0].resourceId,
+    mutationId: firstClaim[0].mutationId,
+    version: 1,
+    committedAt: '2026-08-04T00:00:00.000Z',
+  });
+
+  const secondClaim = cloud.claim();
+  assert.equal(secondClaim.length, 1);
+  assert.equal(secondClaim[0].baseVersion, 1, 'the next head starts from the acknowledged cloud version');
+  assert.equal(secondClaim[0].operation.record.uuid, second.uuid);
+});
+
+test('a signed-in registration is refused until the cloud entity resource is active', () => {
+  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 });
+  assert.throws(() => cloud.assertRegistrationReady(), /entity cloud registry is not ready/);
+  registry.enrollRoot({ type: 'workspace', name: 'bootstrap-only' });
+  const bootstrap = cloud.bootstrap(registry);
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  assert.doesNotThrow(() => cloud.assertRegistrationReady());
+});
+
+test('a compacted remote snapshot enters the cloud catalog, not locally watched identity, and add claims its immutable content', () => {
+  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 });
+  const root = sourceRegistry.enrollRoot({ type: 'workspace', name: 'project' });
+  const contentHash = 'b'.repeat(64);
+  const file = sourceRegistry.create({
+    type: 'file.text', parentUUID: root.uuid, name: 'readme.md', payloadVersion: contentHash,
+  });
+  const snapshot = snapshotFromRecords(sourceRegistry.syncRecords());
+  const bytes = Buffer.from(JSON.stringify(snapshot), 'utf8');
+
+  const targetDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-entity-catalog-'));
+  const targetDb = new Database(':memory:');
+  const targetContent = createEntityContent({ dir: targetDir });
+  const targetCloud = createEntityCloud({
+    db: targetDb, userId: 'user-1', deviceId: 'target-device', content: targetContent,
+  });
+  const targetRegistry = createRegistry({ db: targetDb, ephemeral: true, emit: () => {}, journal: targetCloud.journal });
+  const resourceId = sourceCloud.identity().resourceId;
+  targetCloud.install({
+    registry: targetRegistry,
+    resourceId,
+    authorityEpoch: 3,
+    headVersion: 12,
+    snapshotBase64: bytes.toString('base64'),
+    snapshotChecksum: require('crypto').createHash('sha256').update(bytes).digest('hex'),
+  });
+
+  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');
+  assert.deepEqual(targetCloud.catalogTree({ resourceId, uuid: root.uuid }).map((record) => record.uuid), [root.uuid, file.uuid]);
+  assert.deepEqual(targetCloud.claimDownload(), {
+    resourceId,
+    contentHash,
+    kind: 'manifest',
+    partIndex: 0,
+    sha256: null,
+  });
+  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', () => {
+  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 });
+  const root = sourceRegistry.enrollRoot({ type: 'workspace', name: 'project' });
+  const file = sourceRegistry.create({
+    type: 'file.text', parentUUID: root.uuid, name: 'readme.md', payloadVersion: 'b'.repeat(64),
+  });
+  const initialSnapshot = snapshotFromRecords(sourceRegistry.syncRecords());
+  const initialBytes = Buffer.from(JSON.stringify(initialSnapshot), 'utf8');
+
+  const targetDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-active-head-'));
+  const targetDb = new Database(':memory:');
+  const targetCloud = createEntityCloud({ db: targetDb, userId: 'user-1', deviceId: 'target-device' });
+  const targetRegistry = createRegistry({ db: targetDb, ephemeral: true, emit: () => {}, journal: targetCloud.journal });
+  const resourceId = sourceCloud.identity().resourceId;
+  try {
+    targetCloud.install({
+      registry: targetRegistry,
+      resourceId,
+      authorityEpoch: 3,
+      headVersion: 12,
+      snapshotBase64: initialBytes.toString('base64'),
+      snapshotChecksum: require('crypto').createHash('sha256').update(initialBytes).digest('hex'),
+    });
+
+    const cloudFile = initialSnapshot.records.find((record) => record.uuid === file.uuid);
+    const changed = { ...cloudFile, name: 'renamed.md', version: 'c'.repeat(64) };
+    targetCloud.ingest({
+      registry: targetRegistry,
+      envelope: {
+        resourceId,
+        mutationId: 'ent_remote_change',
+        contract: 'amalgm-entity-registry@1',
+        schemaVersion: 1,
+        operationKind: 'entity.upsert',
+        operation: { kind: 'entity.upsert', record: changed },
+      },
+      version: 13,
+      committedAt: '2026-08-04T00:00:00.000Z',
+    });
+
+    assert.throws(
+      () => targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }),
+      /catalog is not pinned to the active cloud head/,
+      'the mutation updated live catalog facts, but not the snapshot barrier',
+    );
+
+    const cloudRoot = initialSnapshot.records.find((record) => record.uuid === root.uuid);
+    const compactedBytes = Buffer.from(JSON.stringify(snapshotFromRecords([cloudRoot, changed])), 'utf8');
+    targetCloud.install({
+      registry: targetRegistry,
+      resourceId,
+      authorityEpoch: 3,
+      headVersion: 13,
+      snapshotBase64: compactedBytes.toString('base64'),
+      snapshotChecksum: require('crypto').createHash('sha256').update(compactedBytes).digest('hex'),
+    });
+    assert.equal(
+      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }).headVersion,
+      13,
+      'the fresh compacted snapshot—not a history replay—makes add available again',
+    );
+  } finally {
+    sourceDb.close();
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+});