amalgm 0.1.238 → 0.1.240

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

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * The complete provenance transition relation for managed repo bytes.
+ *
+ * This is deliberately data, not a second reconciler. Runtime code may name
+ * one of these transitions, and tests exhaust the whole relation.
+ */
+
+const CLASS = Object.freeze({
+  OFFICIAL: 'officially-applied',
+  INTENT: 'journaled-local-intent',
+  UNKNOWN: 'unknown-provenance',
+});
+
+const STATE = Object.freeze({
+  OFFICIAL: CLASS.OFFICIAL,
+  UNKNOWN: CLASS.UNKNOWN,
+  CAPTURED: `${CLASS.INTENT}:captured`,
+  RESERVED: `${CLASS.INTENT}:reserved`,
+  NUMBERED: `${CLASS.INTENT}:numbered`,
+  FOLDED: `${CLASS.INTENT}:folded`,
+});
+
+const ACTION = Object.freeze({
+  SAVE: 'save',
+  VERIFY: 'verify',
+  CAPTURE: 'capture',
+  RESERVE: 'reserve',
+  RETRY: 'retry',
+  NUMBER: 'number',
+  FOLD: 'fold',
+  APPLY: 'apply',
+  SNAPSHOT: 'snapshot',
+  COMPACT: 'compact',
+  PRUNE: 'prune',
+  RECOVER: 'recover',
+  OBSERVE_UNKNOWN: 'observe-unknown',
+});
+
+const allStates = Object.freeze(Object.values(STATE));
+
+function transition(from, action, to, facts) {
+  return Object.freeze({
+    from,
+    action,
+    to,
+    facts: Object.freeze(facts),
+  });
+}
+
+const transitions = [
+  transition(STATE.OFFICIAL, ACTION.SAVE, STATE.UNKNOWN, [
+    'previous-provenance-preserved',
+  ]),
+  ...[
+    STATE.CAPTURED,
+    STATE.RESERVED,
+    STATE.NUMBERED,
+    STATE.FOLDED,
+  ].map((from) => transition(from, ACTION.SAVE, STATE.UNKNOWN, [
+    'previous-provenance-preserved',
+  ])),
+  transition(STATE.UNKNOWN, ACTION.OBSERVE_UNKNOWN, STATE.UNKNOWN, [
+    'exact-physical-observation',
+  ]),
+  transition(STATE.UNKNOWN, ACTION.VERIFY, STATE.OFFICIAL, [
+    'official-target',
+    'physical-verification',
+    'applied-cursor',
+  ]),
+  transition(STATE.UNKNOWN, ACTION.CAPTURE, STATE.CAPTURED, [
+    'verified-base',
+    'exact-local-state',
+    'physical-digest',
+    'intent-record',
+  ]),
+  transition(STATE.CAPTURED, ACTION.RESERVE, STATE.RESERVED, [
+    'intent-record',
+    'publication-id',
+  ]),
+  transition(STATE.RESERVED, ACTION.RESERVE, STATE.RESERVED, [
+    'same-publication-id',
+    'same-envelope',
+  ]),
+  transition(STATE.RESERVED, ACTION.RETRY, STATE.RESERVED, [
+    'same-publication-id',
+    'same-envelope',
+  ]),
+  transition(STATE.RESERVED, ACTION.NUMBER, STATE.NUMBERED, [
+    'publication-id',
+    'official-version',
+    'server-receipt',
+  ]),
+  transition(STATE.NUMBERED, ACTION.NUMBER, STATE.NUMBERED, [
+    'same-publication-id',
+    'same-official-version',
+  ]),
+  transition(STATE.NUMBERED, ACTION.FOLD, STATE.FOLDED, [
+    'predecessor-folded',
+    'official-event',
+    'official-snapshot',
+  ]),
+  transition(STATE.FOLDED, ACTION.FOLD, STATE.FOLDED, [
+    'same-official-version',
+    'official-snapshot',
+  ]),
+  transition(STATE.FOLDED, ACTION.APPLY, STATE.OFFICIAL, [
+    'official-target',
+    'apply-wal',
+    'physical-verification',
+    'applied-cursor',
+    'intent-retired',
+  ]),
+  transition(STATE.OFFICIAL, ACTION.APPLY, STATE.OFFICIAL, [
+    'contiguous-official-target',
+    'apply-wal',
+    'physical-verification',
+    'applied-cursor',
+  ]),
+  ...[
+    STATE.CAPTURED,
+    STATE.RESERVED,
+    STATE.NUMBERED,
+  ].map((state) => transition(state, ACTION.APPLY, state, [
+    'contiguous-official-target',
+    'apply-wal',
+    'pending-intent-preserved',
+    'physical-verification',
+    'applied-cursor',
+  ])),
+  transition(STATE.OFFICIAL, ACTION.SNAPSHOT, STATE.OFFICIAL, [
+    'verified-snapshot',
+    'apply-wal',
+    'physical-verification',
+    'applied-cursor',
+  ]),
+  transition(STATE.UNKNOWN, ACTION.SNAPSHOT, STATE.OFFICIAL, [
+    'empty-path',
+    'verified-snapshot',
+    'apply-wal',
+    'physical-verification',
+    'applied-cursor',
+  ]),
+  transition(STATE.UNKNOWN, ACTION.SNAPSHOT, STATE.UNKNOWN, [
+    'unknown-bytes-preserved',
+  ]),
+  ...[
+    STATE.CAPTURED,
+    STATE.RESERVED,
+  ].map((state) => transition(state, ACTION.SNAPSHOT, state, [
+    'verified-snapshot',
+    'apply-wal',
+    'pending-intent-preserved',
+    'physical-verification',
+    'applied-cursor',
+  ])),
+  ...[
+    STATE.NUMBERED,
+    STATE.FOLDED,
+  ].map((state) => transition(state, ACTION.SNAPSHOT, STATE.OFFICIAL, [
+    'numbered-event-in-snapshot',
+    'verified-snapshot',
+    'apply-wal',
+    'physical-verification',
+    'applied-cursor',
+    'intent-retired',
+  ])),
+  transition(STATE.OFFICIAL, ACTION.COMPACT, STATE.OFFICIAL, [
+    'retained-server-receipt',
+    'verified-server-snapshot',
+  ]),
+  transition(STATE.FOLDED, ACTION.PRUNE, STATE.FOLDED, [
+    'official-fold',
+    'durable-folded-intent',
+  ]),
+  transition(STATE.OFFICIAL, ACTION.PRUNE, STATE.OFFICIAL, [
+    'official-fold',
+    'physical-verification',
+    'applied-cursor',
+  ]),
+  ...allStates.map((state) => transition(state, ACTION.RECOVER, state, [
+    'durable-provenance-record',
+    'apply-wal-before-destructive-write',
+  ])),
+  ...[
+    STATE.OFFICIAL,
+    STATE.CAPTURED,
+    STATE.RESERVED,
+    STATE.NUMBERED,
+    STATE.FOLDED,
+  ].map((state) => transition(state, ACTION.RECOVER, STATE.UNKNOWN, [
+    'apply-wal',
+    'exact-third-value-observation',
+    'previous-provenance-preserved',
+  ])),
+];
+
+const TRANSITIONS = Object.freeze(transitions);
+const transitionByKey = new Map(
+  TRANSITIONS.map((entry) => [`${entry.from}\u0000${entry.action}\u0000${entry.to}`, entry]),
+);
+
+function provenanceClass(state) {
+  if (state === STATE.OFFICIAL) return CLASS.OFFICIAL;
+  if (state === STATE.UNKNOWN) return CLASS.UNKNOWN;
+  if (typeof state === 'string' && state.startsWith(`${CLASS.INTENT}:`)) {
+    return CLASS.INTENT;
+  }
+  return null;
+}
+
+function publicationState(publication) {
+  if (!publication) return STATE.CAPTURED;
+  if (publication.foldedAt != null) return STATE.FOLDED;
+  if (publication.numberedVersion != null) return STATE.NUMBERED;
+  return STATE.RESERVED;
+}
+
+function requireTransition(from, action, to, availableFacts = []) {
+  const entry = transitionByKey.get(`${from}\u0000${action}\u0000${to}`);
+  if (!entry) throw new Error(`illegal provenance transition: ${from} --${action}--> ${to}`);
+  const available = new Set(availableFacts);
+  const missing = entry.facts.filter((fact) => !available.has(fact));
+  if (missing.length > 0) {
+    throw new Error(`provenance transition ${action} is missing: ${missing.join(', ')}`);
+  }
+  return entry;
+}
+
+module.exports = {
+  ACTION,
+  CLASS,
+  STATE,
+  TRANSITIONS,
+  allStates,
+  provenanceClass,
+  publicationState,
+  requireTransition,
+};