amalgm 0.1.249 → 0.1.251

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

@@ -3,6 +3,7 @@
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
@@ -12,6 +13,8 @@ const { createRegistry } = require('../registry');
 const { createEntityCloud, snapshotFromRecords } = require('../registration/entity-cloud');
 const { createEntityContent } = require('../registration/entity-content');
 const { createRegistrationService } = require('../registration/service');
+const { capture, verify } = require('../repocard');
+const { transportBytes, localState } = require('../registration/repo-states');
 
 function sha256(bytes) {
   return crypto.createHash('sha256').update(bytes).digest('hex');
@@ -28,6 +31,10 @@ function uploadedParts(content, resourceId, contentHash) {
   }
 }
 
+function git(repo, args) {
+  execFileSync('git', args, { cwd: repo, stdio: 'pipe' });
+}
+
 test('add materializes one compacted cloud head, preserves its UUIDs, and starts a local watcher without creating an outbound history replay', async () => {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-materialization-'));
   const sourceDir = path.join(rootDir, 'source');
@@ -93,7 +100,7 @@ test('add materializes one compacted cloud head, preserves its UUIDs, and starts
     }
 
     const job = await target.add({ uuid: root.uuid, targetPath: targetParent });
-    assert.equal(job.state, 'complete');
+    assert.equal(job.state, 'complete', job.error);
     const destination = path.join(targetParent, 'project');
     assert.deepEqual(fs.readFileSync(path.join(destination, 'readme.md')), bytes);
     assert.equal(target.registration.registry.syncRecord(root.uuid).uuid, root.uuid);
@@ -116,3 +123,237 @@ 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 });
+  }
+});
+
+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');
+  const targetState = path.join(rootDir, 'target-state');
+  const sourceRepo = path.join(rootDir, 'source-repo');
+  const targetParent = path.join(rootDir, 'checkout');
+  fs.mkdirSync(sourceRepo, { recursive: true });
+  fs.mkdirSync(targetParent, { recursive: true });
+  git(sourceRepo, ['init', '--quiet']);
+  git(sourceRepo, ['config', 'user.email', 'test@example.com']);
+  git(sourceRepo, ['config', 'user.name', 'Amalgm Test']);
+  fs.writeFileSync(path.join(sourceRepo, 'tracked.md'), '# committed\n');
+  git(sourceRepo, ['add', 'tracked.md']);
+  git(sourceRepo, ['commit', '--quiet', '-m', 'initial']);
+  fs.writeFileSync(path.join(sourceRepo, 'tracked.md'), '# changed locally\n');
+  fs.writeFileSync(path.join(sourceRepo, 'untracked.txt'), 'not committed\n');
+
+  const source = createRegistrationService({
+    dir: sourceState, homeDir: path.join(rootDir, 'source-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'source-device',
+  });
+  const target = createRegistrationService({
+    dir: targetState, homeDir: path.join(rootDir, 'target-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'target-device',
+  });
+  try {
+    const bootstrap = source.entityCloud.bootstrap(source.registration.registry);
+    source.entityCloud.install({
+      registry: source.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 0, snapshotBase64: bootstrap.snapshotBase64,
+      snapshotChecksum: bootstrap.snapshotChecksum,
+    });
+    const registered = await source.register(sourceRepo);
+    const sourceDb = new Database(path.join(sourceState, 'identity.db'), { readonly: true });
+    const operations = sourceDb.prepare('SELECT operation_json FROM entity_cloud_mutations ORDER BY sequence').all()
+      .map((row) => JSON.parse(row.operation_json));
+    sourceDb.close();
+    const repoCloudRecord = operations.map((operation) => operation.record)
+      .find((record) => record?.uuid === registered.record.uuid);
+    assert.ok(repoCloudRecord?.transportVersion, 'the repo entity names immutable Repocard transport cargo');
+    const records = source.registration.registry.syncRecords().map((record) => (
+      record.uuid === registered.record.uuid ? repoCloudRecord : record
+    ));
+    const snapshot = snapshotFromRecords(records);
+    const snapshotBytes = Buffer.from(JSON.stringify(snapshot), 'utf8');
+    target.entityCloud.install({
+      registry: target.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 1, snapshotBase64: snapshotBytes.toString('base64'),
+      snapshotChecksum: sha256(snapshotBytes),
+    });
+
+    const heads = new Set(records.flatMap((record) => {
+      if (['file.text', 'file.binary'].includes(record.type) && record.payloadVersion) return [record.payloadVersion];
+      if (record.type === 'repo.git' && record.transportVersion) return [record.transportVersion];
+      return [];
+    }));
+    for (const head of heads) {
+      const parts = uploadedParts(source.entityContent, bootstrap.resourceId, head);
+      for (const part of [...parts.filter((entry) => entry.kind === 'manifest'), ...parts.filter((entry) => entry.kind === 'chunk')]) {
+        target.receiveCloudContent({
+          resourceId: bootstrap.resourceId, contentHash: head, kind: part.kind,
+          partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+          sha256: part.sha256, dataBase64: part.dataBase64,
+        });
+      }
+    }
+
+    const job = await target.add({ uuid: registered.record.uuid, targetPath: targetParent });
+    assert.equal(job.state, 'complete', job.error);
+    const destination = path.join(targetParent, path.basename(sourceRepo));
+    const expected = source.registration.repoState(registered.record.uuid);
+    assert.equal(verify(destination, expected).ok, true, 'the downloaded Git state reproduces its Card + Checkpoint IDs');
+    assert.equal(target.registration.registry.syncRecord(registered.record.uuid).uuid, registered.record.uuid);
+    assert.equal(target.observer.status().find((entry) => entry.path === fs.realpathSync(destination))?.watching, true,
+      'the same successful add starts the destination repository watcher');
+
+    // A Git-only change exercises the ongoing Add binding without also
+    // changing child-file heads: the repo entity must remain a live source
+    // of truth after its first materialization, and the receiver must not
+    // echo its own applied state back into the cloud outbox.
+    git(sourceRepo, ['tag', 'amalgm-live-proof']);
+    const changedState = capture(sourceRepo, { withBundle: true });
+    const changedTransport = source.entityContent.captureBytes({ bytes: transportBytes(changedState) });
+    const changedLocalState = localState(changedState, changedTransport.contentHash);
+    let changedRecord;
+    source.registration.registry.transaction(() => {
+      source.registration.repoStates.put(registered.record.uuid, changedLocalState);
+      changedRecord = source.registration.registry.attest(registered.record.uuid, {
+        type: 'repo.git', payloadVersion: changedState.stateId,
+      });
+    });
+    const latest = new Database(path.join(sourceState, 'identity.db'), { readonly: true });
+    const remoteRecord = JSON.parse(latest.prepare(`
+      SELECT operation_json FROM entity_cloud_mutations
+      WHERE json_extract(operation_json, '$.record.uuid') = ?
+      ORDER BY sequence DESC LIMIT 1
+    `).get(registered.record.uuid).operation_json).record;
+    latest.close();
+    assert.equal(remoteRecord.transportVersion, changedTransport.contentHash);
+    const ingested = target.ingestCloudMutation({
+      envelope: {
+        resourceId: bootstrap.resourceId, mutationId: 'ent_remote_repo_change',
+        contract: 'amalgm-entity-registry@1', schemaVersion: 1,
+        operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: remoteRecord },
+      },
+      version: 2, committedAt: '2026-08-05T00:00:00.000Z',
+    });
+    assert.equal(ingested.materializations.length, 1, 'the finished repository add becomes a live pending application');
+    const changedParts = uploadedParts(source.entityContent, bootstrap.resourceId, changedTransport.contentHash);
+    for (const part of [...changedParts.filter((entry) => entry.kind === 'manifest'), ...changedParts.filter((entry) => entry.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: bootstrap.resourceId, contentHash: changedTransport.contentHash,
+        kind: part.kind, partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256, dataBase64: part.dataBase64,
+      });
+    }
+    assert.equal(verify(destination, changedLocalState).ok, true,
+      'a later cloud repo state re-materializes exactly on the existing checkout');
+    const targetDb = new Database(path.join(targetState, 'identity.db'), { readonly: true });
+    assert.equal(targetDb.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
+      'the receiver never echoes its downloaded Git state upstream');
+    targetDb.close();
+  } finally {
+    source.close();
+    target.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

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

@@ -303,6 +303,43 @@ test('a signed-in register call writes every entity delivery intent in identity.
   }
 });
 
+test('a large signed-in register call publishes one complete cloud graph before Watch begins', async () => {
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-cloud-register-large'),
+    homeDir: path.join(tempRoot, 'cloud-user-home-large'),
+    cloudUserId: 'user-cloud-register-large',
+    cloudDeviceId: 'computer-cloud-register-large',
+  });
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const ground = makeGround('cloud-register-large');
+  for (let index = 0; index < 500; index += 1) fs.mkdirSync(path.join(ground, `folder-${index}`));
+
+  try {
+    const registered = await service.register(ground);
+    const db = new Database(path.join(service.dir, 'identity.db'), { readonly: true });
+    const rows = db.prepare('SELECT operation_json, mutation_state FROM entity_cloud_mutations ORDER BY sequence').all();
+    db.close();
+    assert.equal(rows.length, 1, 'the cloud never sees a partially registered large tree');
+    const operation = JSON.parse(rows[0].operation_json);
+    assert.equal(operation.kind, 'entity.snapshot.replace');
+    assert.equal(operation.snapshot.records.length, 501, 'the root and every folder share one authoritative graph');
+    assert.equal(rows[0].mutation_state, 'pending');
+    assert.equal(service.observer.status().some((root) => (
+      root.path === registered.rootPath && root.watching && !root.degraded
+    )), true, 'the same registered root begins local watching');
+  } finally {
+    service.close();
+  }
+});
+
 test('register registers the named ground and every file beneath it', async () => {
   const service = makeService('add');
   const ground = makeGround('add');