amalgm 0.1.239 → 0.1.241

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

@@ -25,16 +25,38 @@ fs.writeFileSync(
 const { closeLocalDb } = require('../state/db');
 const { hasCommit, headOid } = require('../workspace/git');
 const {
+  _test: { locatorChecksum },
   acknowledgeUpload,
   claimDownload,
   claimUpload,
+  failUpload,
   importFromLocator,
   objectSourceFor,
+  prepareBundleImport,
   publishPayload,
   readPayload,
   receiveDownload,
 } = require('../workspace/objects');
 
+const PROJECT = '018f0000-0000-7000-8000-000000000030';
+const PROJECT_BINDING = require('../workspace/wall').bindProject(
+  PROJECT,
+  '11111111-1111-4111-8111-111111111111',
+  tempRoot,
+);
+const REPO_KEY = PROJECT_BINDING.repoKey;
+
+test('a locator checksum binds the exact ordered chunk list', () => {
+  const first = { sha256: 'a'.repeat(64), bytes: 3 };
+  const second = { sha256: 'b'.repeat(64), bytes: 4 };
+  assert.equal(locatorChecksum([first, second]), locatorChecksum([first, second]));
+  assert.notEqual(locatorChecksum([first, second]), locatorChecksum([second, first]));
+  assert.notEqual(
+    locatorChecksum([first, second]),
+    locatorChecksum([first, { ...second, bytes: 5 }]),
+  );
+});
+
 test.after(() => {
   closeLocalDb();
   fs.rmSync(tempRoot, { recursive: true, force: true });
@@ -49,7 +71,7 @@ async function git(cwd, ...args) {
   return stdout;
 }
 
-test('an unpushed commit travels as card-owned chunks and imports without moving a ref', async () => {
+test('every committed card travels as project-owned chunks and imports without moving a ref', async () => {
   const origin = path.join(tempRoot, 'origin.git');
   await git(tempRoot, 'init', '--bare', '-b', 'main', origin);
   const source = path.join(tempRoot, 'source');
@@ -61,12 +83,12 @@ test('an unpushed commit travels as card-owned chunks and imports without moving
 
   const destination = path.join(tempRoot, 'destination');
   await git(tempRoot, 'clone', '-q', origin, destination);
-  assert.equal((await objectSourceFor(source, 'repo:test', await headOid(source))).kind, 'remote');
+  assert.equal((await objectSourceFor(source, REPO_KEY, await headOid(source))).kind, 'pending');
 
   fs.appendFileSync(path.join(source, 'app.js'), 'two\n');
   await git(source, 'commit', '-am', 'two');
   const unpushedOid = await headOid(source);
-  assert.equal((await objectSourceFor(source, 'repo:test', unpushedOid)).kind, 'pending');
+  assert.equal((await objectSourceFor(source, REPO_KEY, unpushedOid)).kind, 'pending');
 
   const uploaded = new Map();
   const deadline = Date.now() + 10_000;
@@ -78,10 +100,10 @@ test('an unpushed commit travels as card-owned chunks and imports without moving
     }
     uploaded.set(upload.sha256, upload.dataBase64);
     acknowledgeUpload(upload.resourceId, upload.sha256);
-    const sourceState = await objectSourceFor(source, 'repo:test', unpushedOid);
+    const sourceState = await objectSourceFor(source, REPO_KEY, unpushedOid);
     if (sourceState.kind === 'bundle') break;
   }
-  const locator = await objectSourceFor(source, 'repo:test', unpushedOid);
+  const locator = await objectSourceFor(source, REPO_KEY, unpushedOid);
   assert.equal(locator.kind, 'bundle');
   assert.ok(locator.chunks.length > 0);
 
@@ -103,7 +125,7 @@ test('an unpushed commit travels as card-owned chunks and imports without moving
 
 test('a large checkpoint uses the same verified chunk lane', () => {
   const content = Buffer.alloc(1_300_000, 0x61);
-  assert.equal(publishPayload('large-checkpoint', content, 'repo:test').kind, 'pending');
+  assert.equal(publishPayload('large-checkpoint', content, REPO_KEY).kind, 'pending');
 
   const uploaded = new Map();
   while (true) {
@@ -112,7 +134,7 @@ test('a large checkpoint uses the same verified chunk lane', () => {
     uploaded.set(upload.sha256, upload.dataBase64);
     acknowledgeUpload(upload.resourceId, upload.sha256);
   }
-  const locator = publishPayload('large-checkpoint', content, 'repo:test');
+  const locator = publishPayload('large-checkpoint', content, REPO_KEY);
   assert.equal(locator.kind, 'chunks');
   assert.ok(locator.chunks.length >= 3);
 
@@ -130,9 +152,135 @@ test('a large checkpoint uses the same verified chunk lane', () => {
   assert.equal(received.state, 'ready');
   assert.deepEqual(received.bytes, content);
   assert.equal(
-    publishPayload('same-content-after-download', content, 'repo:test').kind,
+    publishPayload('same-content-after-download', content, REPO_KEY).kind,
     'chunks',
     'verified downloaded content is immediately reusable by a later checkpoint',
   );
   assert.equal(claimUpload(), null);
 });
+
+test('zero-byte chunks are not legal transport work', () => {
+  const chunks = [
+    { sha256: '0'.repeat(64), bytes: 0 },
+    { sha256: '1'.repeat(64), bytes: 1 },
+  ];
+  const common = {
+    resourceId: PROJECT,
+    checksum: locatorChecksum(chunks),
+    bytes: 1,
+    chunks,
+  };
+  assert.throws(
+    () => readPayload({
+      kind: 'chunks',
+      contract: 'opaque-chunks@2',
+      ...common,
+    }),
+    /invalid checkpoint payload locator/,
+  );
+  assert.throws(
+    () => prepareBundleImport({
+      kind: 'bundle',
+      contract: 'git-bundle-chunks@2',
+      oid: 'a'.repeat(40),
+      ref: `refs/amalgm/exports/${'a'.repeat(40)}`,
+      ...common,
+    }),
+    /invalid git bundle locator/,
+  );
+});
+
+test('a corrupt pending upload is retired and rebuilt from the writer', () => {
+  const content = Buffer.from('rebuild this upload');
+  assert.equal(publishPayload('corrupt-upload', content, REPO_KEY).kind, 'pending');
+  const first = claimUpload();
+  assert.ok(first);
+  const chunkFile = path.join(
+    process.env.AMALGM_DIR,
+    'state',
+    'repo-objects',
+    'chunks',
+    `${first.sha256}.bin`,
+  );
+  fs.writeFileSync(chunkFile, 'corrupt');
+  assert.equal(claimUpload(), null, 'the corrupt manifest is retired instead of retrying forever');
+
+  assert.equal(publishPayload('corrupt-upload', content, REPO_KEY).kind, 'pending');
+  const rebuilt = claimUpload();
+  assert.equal(rebuilt.sha256, first.sha256);
+  assert.equal(Buffer.from(rebuilt.dataBase64, 'base64').toString(), content.toString());
+  acknowledgeUpload(rebuilt.resourceId, rebuilt.sha256);
+});
+
+test('one malformed download request cannot block valid requests behind it', () => {
+  const content = Buffer.from('download me');
+  const chunks = [{
+    sha256: require('crypto').createHash('sha256').update(content).digest('hex'),
+    bytes: content.length,
+  }];
+  const locator = {
+    kind: 'chunks',
+    contract: 'opaque-chunks@2',
+    resourceId: PROJECT,
+    checksum: locatorChecksum(chunks),
+    bytes: content.length,
+    chunks,
+  };
+  fs.rmSync(path.join(
+    process.env.AMALGM_DIR,
+    'state',
+    'repo-objects',
+    'chunks',
+    `${chunks[0].sha256}.bin`,
+  ), { force: true });
+  assert.equal(readPayload(locator).state, 'downloading');
+  const requests = path.join(process.env.AMALGM_DIR, 'state', 'repo-objects', 'requests');
+  fs.writeFileSync(path.join(requests, '000-malformed.json'), '{');
+
+  const claimed = claimDownload();
+  assert.equal(claimed.resourceId, PROJECT);
+  assert.equal(claimed.sha256, chunks[0].sha256);
+  assert.equal(fs.existsSync(path.join(requests, '000-malformed.json')), false);
+  receiveDownload(PROJECT, chunks[0].sha256, content.toString('base64'));
+});
+
+test('failed uploads yield the bulk lane to later durable objects', () => {
+  for (const content of ['first queued object', 'second queued object', 'third queued object']) {
+    assert.equal(
+      publishPayload(`fair-${content}`, Buffer.from(content), REPO_KEY).kind,
+      'pending',
+    );
+  }
+
+  const first = claimUpload();
+  assert.ok(first);
+  const retry = failUpload(first.resourceId, first.sha256, {
+    retryable: true,
+    code: 'temporary_object_failure',
+    message: 'try this object later',
+  });
+  assert.equal(retry.changed, true);
+  assert.equal(retry.terminal, false);
+  assert.ok(Date.parse(retry.retryAfter) > Date.now());
+
+  const second = claimUpload();
+  assert.ok(second);
+  assert.notEqual(second.sha256, first.sha256);
+  const terminal = failUpload(second.resourceId, second.sha256, {
+    retryable: false,
+    code: 'shared_resource_read_forbidden',
+    message: 'the stale rail is no longer readable',
+  });
+  assert.equal(terminal.changed, true);
+  assert.equal(terminal.terminal, true);
+
+  const third = claimUpload();
+  assert.ok(third);
+  assert.notEqual(third.sha256, first.sha256);
+  assert.notEqual(third.sha256, second.sha256);
+
+  acknowledgeUpload(first.resourceId, first.sha256);
+  acknowledgeUpload(second.resourceId, second.sha256);
+  acknowledgeUpload(third.resourceId, third.sha256);
+  assert.equal(claimUpload(), null);
+});

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

@@ -0,0 +1,185 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const provenance = require('../workspace/provenance');
+
+const {
+  ACTION,
+  CLASS,
+  STATE,
+  TRANSITIONS,
+  allStates,
+  provenanceClass,
+  publicationState,
+  requireTransition,
+} = provenance;
+
+const key = (from, action, to) => `${from} --${action}--> ${to}`;
+
+test('managed bytes have exactly three provenance classes', () => {
+  assert.deepEqual(Object.values(CLASS), [
+    'officially-applied',
+    'journaled-local-intent',
+    'unknown-provenance',
+  ]);
+  assert.deepEqual(
+    [...new Set(allStates.map(provenanceClass))].sort(),
+    Object.values(CLASS).sort(),
+  );
+  assert.equal(allStates.every((state) => provenanceClass(state) !== null), true);
+});
+
+test('the complete provenance transition relation has no implicit branch', () => {
+  const legal = new Set(TRANSITIONS.map((entry) => key(
+    entry.from,
+    entry.action,
+    entry.to,
+  )));
+  assert.equal(legal.size, TRANSITIONS.length, 'every transition is named once');
+
+  for (const from of allStates) {
+    for (const action of Object.values(ACTION)) {
+      for (const to of allStates) {
+        const transitionKey = key(from, action, to);
+        if (legal.has(transitionKey)) {
+          const entry = TRANSITIONS.find((candidate) => (
+            key(candidate.from, candidate.action, candidate.to) === transitionKey
+          ));
+          assert.ok(entry.facts.length > 0, `${transitionKey} names its durable facts`);
+          assert.equal(
+            requireTransition(from, action, to, entry.facts),
+            entry,
+            transitionKey,
+          );
+        } else {
+          assert.throws(
+            () => requireTransition(from, action, to),
+            /illegal provenance transition/,
+            transitionKey,
+          );
+        }
+      }
+    }
+  }
+});
+
+test('publication substates keep numbering, folding, and physical apply distinct', () => {
+  const publication = {
+    mutationId: 'mutation_provenance_state_01',
+    numberedVersion: null,
+    numberedAt: null,
+    foldedAt: null,
+  };
+  assert.equal(publicationState(null), STATE.CAPTURED);
+  assert.equal(publicationState(publication), STATE.RESERVED);
+  assert.equal(publicationState({
+    ...publication,
+    numberedVersion: 51,
+    numberedAt: '2026-07-27T00:00:00.000Z',
+  }), STATE.NUMBERED);
+  assert.equal(publicationState({
+    ...publication,
+    numberedVersion: 51,
+    numberedAt: '2026-07-27T00:00:00.000Z',
+    foldedAt: '2026-07-27T00:00:01.000Z',
+  }), STATE.FOLDED);
+
+  assert.throws(
+    () => requireTransition(
+      STATE.RESERVED,
+      ACTION.NUMBER,
+      STATE.NUMBERED,
+      ['publication-id', 'official-version'],
+    ),
+    /server-receipt/,
+  );
+  assert.throws(
+    () => requireTransition(
+      STATE.NUMBERED,
+      ACTION.APPLY,
+      STATE.OFFICIAL,
+      [],
+    ),
+    /illegal provenance transition/,
+    'numbered work must fold before physical apply',
+  );
+});
+
+test('unknown bytes can only verify, capture, or remain unknown', () => {
+  const outgoing = TRANSITIONS
+    .filter((entry) => entry.from === STATE.UNKNOWN)
+    .map((entry) => [entry.action, entry.to])
+    .sort();
+  assert.deepEqual(outgoing, [
+    [ACTION.CAPTURE, STATE.CAPTURED],
+    [ACTION.OBSERVE_UNKNOWN, STATE.UNKNOWN],
+    [ACTION.RECOVER, STATE.UNKNOWN],
+    [ACTION.SNAPSHOT, STATE.OFFICIAL],
+    [ACTION.SNAPSHOT, STATE.UNKNOWN],
+    [ACTION.VERIFY, STATE.OFFICIAL],
+  ].sort());
+  assert.equal(
+    outgoing.some(([action]) => (
+      action === ACTION.RESERVE
+      || action === ACTION.RETRY
+      || action === ACTION.APPLY
+    )),
+    false,
+  );
+});
+
+test('server compaction, local journal prune, and intent retirement are distinct', () => {
+  const prunes = TRANSITIONS.filter((entry) => entry.action === ACTION.PRUNE);
+  assert.deepEqual(prunes[0], {
+    from: STATE.FOLDED,
+    action: ACTION.PRUNE,
+    to: STATE.FOLDED,
+    facts: [
+      'official-fold',
+      'durable-folded-intent',
+    ],
+  });
+  assert.deepEqual(prunes[1], {
+    from: STATE.OFFICIAL,
+    action: ACTION.PRUNE,
+    to: STATE.OFFICIAL,
+    facts: [
+      'official-fold',
+      'physical-verification',
+      'applied-cursor',
+    ],
+  });
+  const compact = TRANSITIONS.find((entry) => entry.action === ACTION.COMPACT);
+  assert.deepEqual(compact.facts, [
+    'retained-server-receipt',
+    'verified-server-snapshot',
+  ]);
+  const physicalApply = TRANSITIONS.find((entry) => (
+    entry.from === STATE.FOLDED
+    && entry.action === ACTION.APPLY
+    && entry.to === STATE.OFFICIAL
+  ));
+  assert.deepEqual(physicalApply.facts.slice(-3), [
+    'physical-verification',
+    'applied-cursor',
+    'intent-retired',
+  ]);
+});
+
+test('WAL recovery keeps source and target provenance but exposes any third value', () => {
+  for (const state of allStates.filter((candidate) => candidate !== STATE.UNKNOWN)) {
+    assert.ok(TRANSITIONS.some((entry) => (
+      entry.from === state
+      && entry.action === ACTION.RECOVER
+      && entry.to === state
+    )));
+    assert.ok(TRANSITIONS.some((entry) => (
+      entry.from === state
+      && entry.action === ACTION.RECOVER
+      && entry.to === STATE.UNKNOWN
+      && entry.facts.includes('exact-third-value-observation')
+    )));
+  }
+});