amalgm 0.1.214 → 0.1.216

package/package.json

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

package/runtime/scripts/amalgm-mcp/tests/workspace-checkpoint.test.js

@@ -243,6 +243,37 @@ test('a clean losing commit travels as parked metadata on a no-op checkpoint', (
   assert.deepEqual(checkpoint.parked, parked);
 });
 
+test('only this machine keeps announcing its parked commits', () => {
+  const baseOid = 'a'.repeat(40);
+  const localOid = 'b'.repeat(40);
+  const peerOid = 'c'.repeat(40);
+  const pendingOid = 'd'.repeat(40);
+  const existing = {
+    branch: 'main',
+    baseOid,
+    parked: [{ oid: localOid, objects: { kind: 'pending' } }],
+  };
+  const reduced = {
+    parked: [
+      { oid: localOid, version: 10, objects: { kind: 'pending' } },
+      { oid: peerOid, version: 11, objects: { kind: 'bundle' } },
+      { oid: pendingOid, objects: { kind: 'pending' } },
+    ],
+  };
+  const card = { head: { branch: 'main', oid: baseOid } };
+
+  assert.deepEqual(
+    _test.localParkedEntries(existing, reduced, card).map((entry) => entry.oid),
+    [localOid, pendingOid],
+  );
+  assert.deepEqual(
+    _test.localParkedEntries(existing, reduced, {
+      head: { branch: 'main', oid: 'e'.repeat(40) },
+    }).map((entry) => entry.oid),
+    [pendingOid],
+  );
+});
+
 test('a server rail number does not turn the same parked checkpoint into new work', () => {
   const value = { revision: null, indexDiff: '', worktreeDiff: '' };
   const checkpoint = {

package/runtime/scripts/amalgm-mcp/tests/workspace-publication-invariants.test.js

@@ -0,0 +1,270 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-publication-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+process.env.AMALGM_WORKSPACES_DIR = path.join(process.env.AMALGM_DIR, 'workspaces');
+process.env.AMALGM_COMPUTER_ID = 'machine-a';
+process.env.AMALGM_DEVICE_ID = 'device-a';
+fs.mkdirSync(process.env.AMALGM_DIR, { recursive: true });
+fs.writeFileSync(
+  path.join(process.env.AMALGM_DIR, 'computer.json'),
+  JSON.stringify({
+    computer_id: 'machine-a',
+    user_id: '11111111-1111-4111-8111-111111111111',
+  }),
+);
+
+const { closeLocalDb } = require('../state/db');
+const {
+  _test: checkpointTest,
+  CHECKPOINT_CONTRACT,
+  checkpointFile,
+  sameTransition,
+} = require('../workspace/checkpoint');
+const { parkedForState } = require('../workspace/reducer');
+const { compactWallText, hasLocalContribution, stampCards } = require('../workspace/wall');
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+const rules = {
+  card: {
+    identity: 'branch-and-commit-content',
+    ownership: 'originator-publishes',
+    liveness: 'shared-wall-outbox',
+    gating: 'defines-winning-card',
+  },
+  branch: {
+    identity: 'ref-name-and-commit-content',
+    ownership: 'originator-publishes',
+    liveness: 'shared-wall-outbox',
+    gating: 'per-ref-rail-order',
+  },
+  checkpoint: {
+    identity: 'from-and-to-content',
+    ownership: 'originator-publishes',
+    liveness: 'shared-wall-outbox',
+    gating: 'winning-card-only',
+  },
+  parked: {
+    identity: 'commit-and-object-content',
+    ownership: 'holder-publishes-until-acknowledged',
+    liveness: 'shared-wall-outbox',
+    gating: 'inside-winning-card-checkpoint',
+  },
+  compaction: {
+    identity: 'derived-deletion',
+    ownership: 'any-machine-may-compact',
+    liveness: 'not-semantic-state',
+    gating: 'commutative-with-writers',
+  },
+};
+
+test('the publication model has one explicit rule for every value and property', () => {
+  assert.deepEqual(Object.keys(rules), ['card', 'branch', 'checkpoint', 'parked', 'compaction']);
+  for (const rule of Object.values(rules)) {
+    assert.deepEqual(Object.keys(rule), ['identity', 'ownership', 'liveness', 'gating']);
+    assert.equal(Object.values(rule).every(Boolean), true);
+  }
+  assert.deepEqual(
+    new Set(['card', 'branch', 'checkpoint', 'parked'].map((name) => rules[name].liveness)),
+    new Set(['shared-wall-outbox']),
+  );
+});
+
+test('server rail numbers do not change checkpoint or parked identity', () => {
+  const oid = 'a'.repeat(40);
+  const transition = {
+    checkpoint: CHECKPOINT_CONTRACT,
+    machine: 'machine-a',
+    repoKey: 'root:test',
+    branch: 'main',
+    baseOid: oid,
+    from: { revision: null, indexDiff: '', worktreeDiff: '' },
+    to: { revision: 'work-a', indexDiff: '', worktreeDiff: 'patch-a' },
+    parked: [{
+      oid: 'b'.repeat(40),
+      ref: `refs/amalgm/parked/${'b'.repeat(40)}`,
+      objects: { kind: 'bundle', checksum: 'c'.repeat(64) },
+    }],
+  };
+  assert.equal(sameTransition(transition, {
+    ...transition,
+    mutationId: 'mut_server_metadata',
+    version: 41,
+    parked: transition.parked.map((entry) => ({ ...entry, version: 41 })),
+  }), true);
+  assert.equal(sameTransition(transition, {
+    ...transition,
+    to: { ...transition.to, revision: 'different-work' },
+  }), false);
+  assert.equal(sameTransition(transition, {
+    ...transition,
+    parked: transition.parked.map((entry) => ({
+      ...entry,
+      objects: { ...entry.objects, checksum: 'd'.repeat(64) },
+    })),
+  }), false);
+});
+
+test('receivers stay silent and only unacknowledged local parked work republishes', () => {
+  const head = 'a'.repeat(40);
+  const local = {
+    head: { branch: 'main', oid: head, detached: false },
+    refs: [{ name: 'main', oid: head }],
+  };
+  const transition = {
+    checkpoint: CHECKPOINT_CONTRACT,
+    machine: 'machine-a',
+    repoKey: 'root:test',
+    branch: 'main',
+    baseOid: head,
+    from: { revision: null, indexDiff: '', worktreeDiff: '' },
+    to: { revision: 'shared-work', indexDiff: '', worktreeDiff: 'patch' },
+    parked: [],
+  };
+  const plan = {
+    card: { head: { branch: 'main', oid: head, detached: false } },
+    branches: [{ name: 'main', oid: head }],
+    transitions: [{ ...transition, version: 9 }],
+  };
+  const baseline = {
+    branch: 'main',
+    baseOid: head,
+    branches: [{ name: 'main', oid: head }],
+  };
+  assert.equal(hasLocalContribution(local, plan, baseline, transition), false);
+
+  const localParked = { oid: 'b'.repeat(40), objects: { kind: 'bundle', checksum: 'local' } };
+  const unsentParked = { oid: 'c'.repeat(40), objects: { kind: 'bundle', checksum: 'unsent' } };
+  const peerParked = {
+    oid: 'd'.repeat(40),
+    objects: { kind: 'bundle', checksum: 'peer' },
+    version: 9,
+  };
+  assert.deepEqual(
+    checkpointTest.localParkedEntries(
+      { ...transition, parked: [localParked] },
+      { parked: [peerParked, unsentParked] },
+      local,
+    ),
+    [localParked, unsentParked],
+  );
+  assert.deepEqual(parkedForState([localParked], [], []), [localParked]);
+  assert.deepEqual(
+    parkedForState([localParked], [{ ...localParked, version: 10 }], []),
+    [{ ...localParked, version: 10 }],
+  );
+  assert.deepEqual(parkedForState([{ ...localParked, version: 10 }], [], []), []);
+});
+
+test('card, branch, checkpoint, and parked work ride one wall mutation', () => {
+  const repoKey = 'https://github.com/amalgm-inc/publication-invariant-test';
+  const head = 'a'.repeat(40);
+  const parkedOid = 'b'.repeat(40);
+  const checkpoint = {
+    checkpoint: CHECKPOINT_CONTRACT,
+    machine: 'machine-a',
+    repoKey,
+    branch: 'main',
+    baseOid: head,
+    from: { revision: null, indexDiff: '', worktreeDiff: '' },
+    to: { revision: 'work-a', indexDiff: '', worktreeDiff: 'patch-a' },
+    parked: [{
+      oid: parkedOid,
+      ref: `refs/amalgm/parked/${parkedOid}`,
+      objects: { kind: 'bundle', checksum: 'c'.repeat(64) },
+    }],
+  };
+  const file = checkpointFile('machine-a', repoKey);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(checkpoint)}\n`);
+
+  const mutationId = 'mut_one_shared_wall_outbox';
+  const stamped = stampCards([{
+    card: 'repo-card@2',
+    machine: 'machine-a',
+    replica: 'rpl_publication_test',
+    kind: 'primary',
+    repo: { remote: repoKey },
+    head: { branch: 'main', oid: head, detached: false },
+    refs: [
+      { name: 'main', oid: head },
+      { name: 'feature', oid: head },
+    ],
+    health: 'healthy',
+  }], [], null, null, mutationId, {
+    repoKey,
+    resourceId: 'shr_publication_invariant_test',
+  })[0];
+
+  assert.equal(stamped.positionMutationId, mutationId);
+  assert.equal(stamped.branches.every((ref) => ref.mutationId === mutationId), true);
+  assert.equal(stamped.checkpoints[0].mutationId, mutationId);
+  assert.equal(stamped.checkpoints[0].parked[0].oid, parkedOid);
+});
+
+test('two concurrent compacting publishers converge without losing either latest value', () => {
+  const Y = require('yjs');
+  const repoKey = 'root:compaction-collision';
+  const line = (machine, value) => JSON.stringify({
+    wall: 'code-project@3',
+    project: repoKey,
+    machine,
+    mutationId: `mut_${machine}_${value}`,
+    cards: [{ value }],
+  });
+  const baseText = [
+    line('machine-a', 'old-a'),
+    line('machine-b', 'old-b'),
+    line('machine-a', 'current-a'),
+    line('machine-b', 'current-b'),
+    '',
+  ].join('\n');
+  const compacted = compactWallText(baseText, repoKey);
+  const removedBytes = baseText.length - compacted.length;
+  assert.ok(removedBytes > 0);
+
+  const base = new Y.Doc();
+  base.getText('content').insert(0, baseText);
+  const baseUpdate = Y.encodeStateAsUpdate(base);
+  const baseVector = Y.encodeStateVector(base);
+  const publisherUpdate = (machine, value) => {
+    const writer = new Y.Doc();
+    Y.applyUpdate(writer, baseUpdate);
+    const text = writer.getText('content');
+    text.delete(0, removedBytes);
+    text.insert(text.length, `${line(machine, value)}\n`);
+    return Y.encodeStateAsUpdate(writer, baseVector);
+  };
+  const updateA = publisherUpdate('machine-a', 'latest-a');
+  const updateB = publisherUpdate('machine-b', 'latest-b');
+  const replicas = [
+    [updateA, updateB],
+    [updateB, updateA],
+  ].map((order) => {
+    const replica = new Y.Doc();
+    Y.applyUpdate(replica, baseUpdate);
+    for (const update of order) Y.applyUpdate(replica, update);
+    return replica.getText('content').toString();
+  });
+
+  assert.equal(replicas[0], replicas[1]);
+  const latest = new Map();
+  for (const raw of replicas[0].trim().split('\n')) {
+    const entry = JSON.parse(raw);
+    latest.set(entry.machine, entry.cards[0].value);
+  }
+  assert.deepEqual(Object.fromEntries(latest), {
+    'machine-a': 'latest-a',
+    'machine-b': 'latest-b',
+  });
+});

package/runtime/scripts/amalgm-mcp/tests/workspace-reducer.test.js

@@ -28,6 +28,7 @@ const {
   hydrateRepo,
   localCardMayMaterialize,
   materializeRepo,
+  parkedForState,
   pathForRepo,
   readRepoState,
   reduceCheckpoint,
@@ -175,6 +176,17 @@ test('a ready parked bundle never regresses to pending', () => {
   assert.equal(plan.parked[0].objects.kind, 'bundle');
 });
 
+test('an unpublished local parked commit stays active until the rail records it', () => {
+  const oid = 'f'.repeat(40);
+  const local = { oid, objects: { kind: 'bundle', checksum: 'local' } };
+  assert.deepEqual(parkedForState([local], [], []), [local]);
+  assert.deepEqual(parkedForState([local], [{ ...local, version: 7 }], []), [{
+    ...local,
+    version: 7,
+  }]);
+  assert.deepEqual(parkedForState([{ ...local, version: 7 }], [], []), []);
+});
+
 test('a stale lower rail card cannot roll back a newer branch and commit', () => {
   const newer = card('/newer', 'b'.repeat(40), 12);
   newer.head.branch = 'feature';
@@ -508,6 +520,17 @@ test('a losing commit is parked, the winning card lands exactly, and losing work
   assert.equal((await git(repo, 'status', '--porcelain')).trim().length > 0, true);
   assert.deepEqual(readRepoState('root:test').parked.map((entry) => entry.oid), [losingOid]);
 
+  const sharedParked = readRepoState('root:test').parked.map((entry) => ({
+    ...entry,
+    version: 2,
+  }));
+  await materializeRepo(card(repo, winningOid, 2), {
+    repoKey: 'root:test',
+    card: winningCard,
+    transitions: [],
+    parked: sharedParked,
+  });
+
   await git(repo, 'add', '.');
   await git(repo, 'commit', '-m', 'fold parked work');
   const foldedOid = (await git(repo, 'rev-parse', 'HEAD')).trim();
@@ -521,7 +544,9 @@ test('a losing commit is parked, the winning card lands exactly, and losing work
 
   assert.equal(folded.state, 'in-sync');
   assert.deepEqual(readRepoState('root:test').parked, []);
-  assert.equal((await git(repo, 'rev-parse', `refs/amalgm/parked/${losingOid}`)).trim(), losingOid);
+  await assert.rejects(
+    git(repo, 'rev-parse', '--verify', `refs/amalgm/parked/${losingOid}`),
+  );
 });
 
 test('rail-parked peer commits become one staged checkpoint on every machine', async () => {

package/runtime/scripts/amalgm-mcp/workspace/checkpoint.js

@@ -157,6 +157,17 @@ function checkpointForSharedState(existing, {
   };
 }
 
+function localParkedEntries(existing, reduced, card) {
+  const held = existing?.baseOid === card.head?.oid
+    && existing.branch === card.head?.branch
+    ? existing.parked || []
+    : [];
+  const unpublished = (reduced?.parked || []).filter((entry) => (
+    !Number.isInteger(entry.version) || entry.version < 1
+  ));
+  return [...new Map([...held, ...unpublished].map((entry) => [entry.oid, entry])).values()];
+}
+
 function readCheckpointValue(baseOid, value) {
   let indexDiff = typeof value?.indexDiff === 'string' ? value.indexDiff : '';
   let worktreeDiff = typeof value?.worktreeDiff === 'string' ? value.worktreeDiff : '';
@@ -228,7 +239,7 @@ async function publishPass(replicaId = null) {
       const localRevision = revisionOf(card.head.oid, captured.indexDiff, captured.worktreeDiff);
       const file = checkpointFile(machine, repoKey);
       const existing = readCheckpoint(machine, repoKey);
-      const parked = await Promise.all((reduced.parked || []).map(async (entry) => ({
+      const parked = await Promise.all(localParkedEntries(existing, reduced, card).map(async (entry) => ({
         ...entry,
         objects: await require('./objects').bundleSourceFor(card.path, repoKey, entry.oid),
       })));
@@ -393,6 +404,7 @@ module.exports = {
     checkpointBaseReady,
     checkpointForSharedState,
     checkpointMayPublish,
+    localParkedEntries,
   },
   CHECKPOINT_CONTRACT,
   MAX_INLINE_DIFF_BYTES,

package/runtime/scripts/amalgm-mcp/workspace/reducer.js

@@ -176,6 +176,18 @@ function uniqueParked(entries) {
   return order.map((oid) => byOid.get(oid));
 }
 
+function parkedForState(previous, shared, discovered) {
+  const sharedOids = new Set((shared || []).map((entry) => entry.oid));
+  const unpublished = (previous || []).filter((entry) => (
+    !validVersion(entry.version) && !sharedOids.has(entry.oid)
+  ));
+  return uniqueParked([
+    ...(shared || []),
+    ...unpublished,
+    ...(discovered || []),
+  ]);
+}
+
 async function obtainCardObjects(localCard, targetCard) {
   const oid = targetCard.head?.oid;
   if (!oid || await hasCommit(localCard.path, oid)) return { state: 'ready' };
@@ -348,7 +360,8 @@ async function moveToWinningCard(localCard, targetCard) {
 
 async function materializeParked(localCard, entries) {
   const waiting = [];
-  for (const entry of uniqueParked(entries)) {
+  const active = uniqueParked(entries);
+  for (const entry of active) {
     if (!(await hasCommit(localCard.path, entry.oid))) {
       if (entry.objects?.kind === 'bundle') {
         const imported = await require('./objects').importFromLocator(localCard.path, entry.objects);
@@ -363,6 +376,10 @@ async function materializeParked(localCard, entries) {
     }
     await transition.parkCommit(localCard.path, entry.oid);
   }
+  await transition.pruneParkedCommits(
+    localCard.path,
+    new Set(active.map((entry) => entry.oid)),
+  );
   return waiting;
 }
 
@@ -512,10 +529,11 @@ async function materializeRepo(localCardInput, plan) {
     ? await refreshRepoCard(refreshed.replica) || refreshed
     : refreshed;
   const previous = readRepoState(plan.repoKey);
-  const parked = uniqueParked([
-    ...(plan.parked || []),
-    ...(cardResult.parked || []),
-  ]);
+  const parked = parkedForState(
+    previous?.parked,
+    plan.parked,
+    cardResult.parked,
+  );
   const parkedWaiting = await materializeParked(localCard, parked);
   const planParked = new Set((plan.parked || []).map((entry) => entry.oid));
   const requiredParkedWaiting = parkedWaiting.filter((entry) => planParked.has(entry.oid));
@@ -784,6 +802,7 @@ module.exports = {
   localCardMayMaterialize,
   materializeRepo,
   pathForRepo,
+  parkedForState,
   readRepoState,
   reduceCheckpoint,
   reduceNow,

package/runtime/scripts/amalgm-mcp/workspace/transition.js

@@ -236,6 +236,20 @@ function parkCommit(worktreeRoot, oid) {
   ]).then(() => ref);
 }
 
+/** Delete internal parked refs that are no longer part of shared checkpoint state. */
+async function pruneParkedCommits(worktreeRoot, keepOids) {
+  const output = await run('list-parked-commits', worktreeRoot, [
+    '-C', worktreeRoot, 'for-each-ref', '--format=%(refname)', 'refs/amalgm/parked',
+  ], { journalResult: false });
+  const prefix = 'refs/amalgm/parked/';
+  for (const ref of output.trim().split('\n').filter(Boolean)) {
+    if (!ref.startsWith(prefix) || keepOids.has(ref.slice(prefix.length))) continue;
+    await run('remove-parked-commit', worktreeRoot, [
+      '-C', worktreeRoot, 'update-ref', '-d', ref,
+    ]);
+  }
+}
+
 function setBranchRef(worktreeRoot, branch, oid) {
   return run('set-branch-ref', worktreeRoot, [
     '-C', worktreeRoot, 'update-ref', `refs/heads/${branch}`, oid,
@@ -380,6 +394,7 @@ module.exports = {
   initializeRepo,
   moveToCard,
   parkCommit,
+  pruneParkedCommits,
   restoreInitialFiles,
   setBranchRef,
   setIndexTree,