amalgm 0.1.238 → 0.1.240

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')
+    )));
+  }
+});