@git-stunts/git-warp 10.1.1

package/src/domain/services/WormholeService.js

@@ -0,0 +1,353 @@
+/**
+ * WormholeService - Wormhole Compression for WARP Graphs
+ *
+ * Implements wormhole compression from Paper III (Computational Holography):
+ * Compress multi-tick segments into single edges carrying sub-payloads.
+ *
+ * A wormhole is a compressed representation of a contiguous range of patches
+ * from a single writer. It preserves provenance by storing the original
+ * patches as a ProvenancePayload that can be replayed during materialization.
+ *
+ * ## Key Properties
+ *
+ * - **Provenance Preservation**: The wormhole contains the full sub-payload,
+ *   allowing exact replay of the compressed segment.
+ * - **Monoid Composition**: Two consecutive wormholes can be composed by
+ *   concatenating their sub-payloads.
+ * - **Materialization Equivalence**: A wormhole + remaining patches produces
+ *   the same state as materializing all patches.
+ *
+ * @module domain/services/WormholeService
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import ProvenancePayload from './ProvenancePayload.js';
+import WormholeError from '../errors/WormholeError.js';
+import { detectMessageKind, decodePatchMessage } from './WarpMessageCodec.js';
+
+/**
+ * Validates that a SHA parameter is a non-empty string.
+ * @param {*} sha - The SHA to validate
+ * @param {string} paramName - Parameter name for error messages
+ * @throws {WormholeError} If SHA is invalid
+ * @private
+ */
+function validateSha(sha, paramName) {
+  if (!sha || typeof sha !== 'string') {
+    throw new WormholeError(`${paramName} is required and must be a string`, {
+      code: 'E_WORMHOLE_SHA_NOT_FOUND',
+      context: { [paramName]: sha },
+    });
+  }
+}
+
+/**
+ * Verifies that a SHA exists in the repository.
+ * @param {Object} persistence - Git persistence adapter
+ * @param {string} sha - The SHA to verify
+ * @param {string} paramName - Parameter name for error messages
+ * @throws {WormholeError} If SHA doesn't exist
+ * @private
+ */
+async function verifyShaExists(persistence, sha, paramName) {
+  const exists = await persistence.nodeExists(sha);
+  if (!exists) {
+    throw new WormholeError(`Patch SHA '${sha}' does not exist`, {
+      code: 'E_WORMHOLE_SHA_NOT_FOUND',
+      context: { sha, which: paramName },
+    });
+  }
+}
+
+/**
+ * Processes a single commit in the wormhole chain.
+ * @param {Object} opts - Options
+ * @param {Object} opts.persistence - Git persistence adapter
+ * @param {string} opts.sha - The commit SHA
+ * @param {string} opts.graphName - Expected graph name
+ * @param {string|null} opts.expectedWriter - Expected writer ID (null for first commit)
+ * @returns {Promise<{patch: Object, sha: string, writerId: string, parentSha: string|null}>}
+ * @throws {WormholeError} On validation errors
+ * @private
+ */
+async function processCommit({ persistence, sha, graphName, expectedWriter, codec: codecOpt }) {
+  const codec = codecOpt || defaultCodec;
+  const nodeInfo = await persistence.getNodeInfo(sha);
+  const { message, parents } = nodeInfo;
+
+  const kind = detectMessageKind(message);
+  if (kind !== 'patch') {
+    throw new WormholeError(`Commit '${sha}' is not a patch commit (kind: ${kind})`, {
+      code: 'E_WORMHOLE_NOT_PATCH',
+      context: { sha, kind },
+    });
+  }
+
+  const patchMeta = decodePatchMessage(message);
+
+  if (patchMeta.graph !== graphName) {
+    throw new WormholeError(`Patch '${sha}' belongs to graph '${patchMeta.graph}', not '${graphName}'`, {
+      code: 'E_WORMHOLE_INVALID_RANGE',
+      context: { sha, expectedGraph: graphName, actualGraph: patchMeta.graph },
+    });
+  }
+
+  if (expectedWriter !== null && patchMeta.writer !== expectedWriter) {
+    throw new WormholeError(`Patches span multiple writers: '${expectedWriter}' and '${patchMeta.writer}'`, {
+      code: 'E_WORMHOLE_MULTI_WRITER',
+      context: { sha, expectedWriter, actualWriter: patchMeta.writer },
+    });
+  }
+
+  const patchBuffer = await persistence.readBlob(patchMeta.patchOid);
+  const patch = codec.decode(patchBuffer);
+
+  return {
+    patch,
+    sha,
+    writerId: patchMeta.writer,
+    parentSha: parents && parents.length > 0 ? parents[0] : null,
+  };
+}
+
+/**
+ * Represents a compressed range of patches (wormhole).
+ *
+ * A WormholeEdge contains:
+ * - The SHA of the first (oldest) patch in the range (fromSha)
+ * - The SHA of the last (newest) patch in the range (toSha)
+ * - The writer ID who created all patches in the range
+ * - A ProvenancePayload containing all patches for replay
+ *
+ * @typedef {Object} WormholeEdge
+ * @property {string} fromSha - SHA of the first (oldest) patch commit
+ * @property {string} toSha - SHA of the last (newest) patch commit
+ * @property {string} writerId - Writer ID of all patches in the range
+ * @property {ProvenancePayload} payload - Sub-payload for replay
+ * @property {number} patchCount - Number of patches compressed
+ */
+
+/**
+ * Creates a wormhole compressing a range of patches.
+ *
+ * The range is specified by two patch SHAs from the same writer. The `fromSha`
+ * must be an ancestor of `toSha` in the writer's patch chain. Both endpoints
+ * are inclusive in the wormhole.
+ *
+ * @param {Object} options - Wormhole creation options
+ * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {string} options.graphName - Name of the graph
+ * @param {string} options.fromSha - SHA of the first (oldest) patch commit
+ * @param {string} options.toSha - SHA of the last (newest) patch commit
+ * @returns {Promise<WormholeEdge>} The created wormhole
+ * @throws {WormholeError} If fromSha or toSha doesn't exist (E_WORMHOLE_SHA_NOT_FOUND)
+ * @throws {WormholeError} If fromSha is not an ancestor of toSha (E_WORMHOLE_INVALID_RANGE)
+ * @throws {WormholeError} If commits span multiple writers (E_WORMHOLE_MULTI_WRITER)
+ * @throws {WormholeError} If a commit is not a patch commit (E_WORMHOLE_NOT_PATCH)
+ */
+export async function createWormhole({ persistence, graphName, fromSha, toSha, codec }) {
+  validateSha(fromSha, 'fromSha');
+  validateSha(toSha, 'toSha');
+  await verifyShaExists(persistence, fromSha, 'fromSha');
+  await verifyShaExists(persistence, toSha, 'toSha');
+
+  const patches = await collectPatchRange({ persistence, graphName, fromSha, toSha, codec });
+
+  // Reverse to get oldest-first order (as required by ProvenancePayload)
+  patches.reverse();
+
+  const writerId = patches.length > 0 ? patches[0].writerId : null;
+  // Strip writerId to match ProvenancePayload's PatchEntry typedef ({patch, sha})
+  const payload = new ProvenancePayload(patches.map(({ patch, sha }) => ({ patch, sha })));
+
+  return { fromSha, toSha, writerId, payload, patchCount: patches.length };
+}
+
+/**
+ * Collects patches from toSha back to fromSha (newest-first order).
+ *
+ * Walks the parent chain from toSha towards fromSha, collecting and
+ * validating each commit along the way.
+ *
+ * @param {Object} options
+ * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {string} options.graphName - Expected graph name
+ * @param {string} options.fromSha - SHA of the first (oldest) patch commit
+ * @param {string} options.toSha - SHA of the last (newest) patch commit
+ * @returns {Promise<Array<{patch: Object, sha: string, writerId: string}>>} Patches in newest-first order
+ * @throws {WormholeError} If fromSha is not an ancestor of toSha or range is empty
+ * @private
+ */
+async function collectPatchRange({ persistence, graphName, fromSha, toSha, codec }) {
+  const patches = [];
+  let currentSha = toSha;
+  let writerId = null;
+
+  while (currentSha) {
+    const result = await processCommit({ persistence, sha: currentSha, graphName, expectedWriter: writerId, codec });
+    writerId = result.writerId;
+    patches.push({ patch: result.patch, sha: result.sha, writerId: result.writerId });
+
+    if (currentSha === fromSha) {
+      break;
+    }
+
+    if (!result.parentSha) {
+      throw new WormholeError(`'${fromSha}' is not an ancestor of '${toSha}'`, {
+        code: 'E_WORMHOLE_INVALID_RANGE',
+        context: { fromSha, toSha },
+      });
+    }
+    currentSha = result.parentSha;
+  }
+
+  if (currentSha !== fromSha) {
+    throw new WormholeError(`'${fromSha}' is not an ancestor of '${toSha}'`, {
+      code: 'E_WORMHOLE_INVALID_RANGE',
+      context: { fromSha, toSha },
+    });
+  }
+
+  if (patches.length === 0) {
+    throw new WormholeError('No patches found in the specified range', {
+      code: 'E_WORMHOLE_EMPTY_RANGE',
+      context: { fromSha, toSha },
+    });
+  }
+
+  return patches;
+}
+
+/**
+ * Composes two consecutive wormholes into a single wormhole.
+ *
+ * The wormholes must be consecutive: the first wormhole's toSha must be
+ * the parent of the second wormhole's fromSha.
+ *
+ * This leverages the ProvenancePayload monoid structure:
+ * `composed.payload = first.payload.concat(second.payload)`
+ *
+ * @param {WormholeEdge} first - The earlier (older) wormhole
+ * @param {WormholeEdge} second - The later (newer) wormhole
+ * @param {Object} [options] - Composition options
+ * @param {import('../../ports/GraphPersistencePort.js').default} [options.persistence] - Git persistence adapter (for validation)
+ * @returns {Promise<WormholeEdge>} The composed wormhole
+ * @throws {WormholeError} If wormholes are from different writers (E_WORMHOLE_MULTI_WRITER)
+ * @throws {WormholeError} If wormholes are not consecutive (E_WORMHOLE_INVALID_RANGE)
+ */
+export async function composeWormholes(first, second, options = {}) {
+  // Validate writer consistency
+  if (first.writerId !== second.writerId) {
+    throw new WormholeError(`Cannot compose wormholes from different writers: '${first.writerId}' and '${second.writerId}'`, {
+      code: 'E_WORMHOLE_MULTI_WRITER',
+      context: { firstWriter: first.writerId, secondWriter: second.writerId },
+    });
+  }
+
+  // If persistence is provided, validate that wormholes are consecutive
+  if (options.persistence) {
+    const secondFirstInfo = await options.persistence.getNodeInfo(second.fromSha);
+    const parents = secondFirstInfo.parents || [];
+
+    if (!parents.includes(first.toSha)) {
+      throw new WormholeError('Wormholes are not consecutive', {
+        code: 'E_WORMHOLE_INVALID_RANGE',
+        context: {
+          firstToSha: first.toSha,
+          secondFromSha: second.fromSha,
+          secondParents: parents,
+        },
+      });
+    }
+  }
+
+  // Compose using payload monoid concatenation
+  const composedPayload = first.payload.concat(second.payload);
+
+  return {
+    fromSha: first.fromSha,
+    toSha: second.toSha,
+    writerId: first.writerId,
+    payload: composedPayload,
+    patchCount: first.patchCount + second.patchCount,
+  };
+}
+
+/**
+ * Replays a wormhole's sub-payload to materialize the compressed state.
+ *
+ * This is equivalent to materializing all the patches in the wormhole
+ * individually. The replay uses CRDT merge semantics as defined in JoinReducer.
+ *
+ * @param {WormholeEdge} wormhole - The wormhole to replay
+ * @param {import('./JoinReducer.js').WarpStateV5} [initialState] - Optional initial state
+ * @returns {import('./JoinReducer.js').WarpStateV5} The materialized state
+ */
+export function replayWormhole(wormhole, initialState) {
+  return wormhole.payload.replay(initialState);
+}
+
+/**
+ * Serializes a wormhole to a JSON-serializable object.
+ *
+ * @param {WormholeEdge} wormhole - The wormhole to serialize
+ * @returns {Object} JSON-serializable representation
+ */
+export function serializeWormhole(wormhole) {
+  return {
+    fromSha: wormhole.fromSha,
+    toSha: wormhole.toSha,
+    writerId: wormhole.writerId,
+    patchCount: wormhole.patchCount,
+    payload: wormhole.payload.toJSON(),
+  };
+}
+
+/**
+ * Deserializes a wormhole from a JSON object.
+ *
+ * @param {Object} json - The JSON object to deserialize
+ * @returns {WormholeEdge} The deserialized wormhole
+ * @throws {WormholeError} If the JSON structure is invalid
+ */
+export function deserializeWormhole(json) {
+  // Validate required fields
+  if (!json || typeof json !== 'object') {
+    throw new WormholeError('Invalid wormhole JSON: expected object', {
+      code: 'E_INVALID_WORMHOLE_JSON',
+    });
+  }
+
+  const requiredFields = ['fromSha', 'toSha', 'writerId', 'patchCount', 'payload'];
+  for (const field of requiredFields) {
+    if (json[field] === undefined) {
+      throw new WormholeError(`Invalid wormhole JSON: missing required field '${field}'`, {
+        code: 'E_INVALID_WORMHOLE_JSON',
+        context: { missingField: field },
+      });
+    }
+  }
+
+  if (typeof json.patchCount !== 'number' || json.patchCount < 0) {
+    throw new WormholeError('Invalid wormhole JSON: patchCount must be a non-negative number', {
+      code: 'E_INVALID_WORMHOLE_JSON',
+      context: { patchCount: json.patchCount },
+    });
+  }
+
+  return {
+    fromSha: json.fromSha,
+    toSha: json.toSha,
+    writerId: json.writerId,
+    patchCount: json.patchCount,
+    payload: ProvenancePayload.fromJSON(json.payload),
+  };
+}
+
+export default {
+  createWormhole,
+  composeWormholes,
+  replayWormhole,
+  serializeWormhole,
+  deserializeWormhole,
+};

package/src/domain/types/TickReceipt.js

@@ -0,0 +1,285 @@
+/**
+ * TickReceipt — immutable record of per-operation outcomes from a single patch application.
+ *
+ * A tick receipt captures what happened to each operation in a patch during
+ * materialization: whether it was applied, superseded by a concurrent write,
+ * or redundant (already present in the state).
+ *
+ * This is a type definition only — emission logic lives in LH/RECEIPTS/2.
+ *
+ * @module TickReceipt
+ * @see Paper II, Section 5 — Tick receipts: event posets recording accepted/rejected matches
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Valid operation types that can appear in a tick receipt.
+ * @type {ReadonlyArray<string>}
+ */
+export const OP_TYPES = Object.freeze([
+  'NodeAdd',
+  'NodeTombstone',
+  'EdgeAdd',
+  'EdgeTombstone',
+  'PropSet',
+  'BlobValue',
+]);
+
+/**
+ * Valid result values for an operation outcome.
+ * @type {ReadonlyArray<string>}
+ */
+export const RESULT_TYPES = Object.freeze([
+  'applied',
+  'superseded',
+  'redundant',
+]);
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+const opTypeSet = new Set(OP_TYPES);
+const resultTypeSet = new Set(RESULT_TYPES);
+
+/**
+ * Asserts that a value is a non-null object.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isObject(value) {
+  return value !== null && typeof value === 'object';
+}
+
+/**
+ * Validates a single operation outcome entry.
+ *
+ * @param {unknown} op - The operation outcome to validate
+ * @param {number} index - Index within the ops array (for error messages)
+ * @throws {Error} If validation fails
+ */
+function validateOp(op, index) {
+  if (!isObject(op)) {
+    throw new Error(`ops[${index}] must be an object`);
+  }
+
+  validateOpType(op.op, index);
+  validateOpTarget(op.target, index);
+  validateOpResult(op.result, index);
+
+  if (op.reason !== undefined && typeof op.reason !== 'string') {
+    throw new Error(`ops[${index}].reason must be a string or undefined`);
+  }
+}
+
+/**
+ * Validates that an operation type is one of the allowed OP_TYPES.
+ *
+ * Valid operation types correspond to the six patch operations defined
+ * in PatchBuilderV2: NodeAdd, NodeTombstone, EdgeAdd, EdgeTombstone,
+ * PropSet, and BlobValue.
+ *
+ * @param {unknown} value - The operation type to validate
+ * @param {number} i - Index of the operation in the ops array (for error messages)
+ * @returns {void}
+ * @throws {Error} If value is not a string or not one of the valid OP_TYPES
+ *
+ * @example
+ * validateOpType('NodeAdd', 0); // OK
+ * validateOpType('InvalidOp', 0); // throws Error
+ * validateOpType(123, 0); // throws Error
+ */
+function validateOpType(value, i) {
+  if (typeof value !== 'string' || !opTypeSet.has(value)) {
+    throw new Error(`ops[${i}].op must be one of: ${OP_TYPES.join(', ')}`);
+  }
+}
+
+/**
+ * Validates that an operation target is a non-empty string.
+ *
+ * The target identifies what entity was affected by the operation:
+ * - For node operations: the node ID (e.g., "user:alice")
+ * - For edge operations: the edge key (e.g., "user:alice\0user:bob\0follows")
+ * - For property operations: the property key (e.g., "user:alice\0name")
+ *
+ * @param {unknown} value - The target to validate
+ * @param {number} i - Index of the operation in the ops array (for error messages)
+ * @returns {void}
+ * @throws {Error} If value is not a non-empty string
+ *
+ * @example
+ * validateOpTarget('user:alice', 0); // OK
+ * validateOpTarget('', 0); // throws Error
+ * validateOpTarget(null, 0); // throws Error
+ */
+function validateOpTarget(value, i) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`ops[${i}].target must be a non-empty string`);
+  }
+}
+
+/**
+ * Validates that an operation result is one of the allowed RESULT_TYPES.
+ *
+ * Valid results describe the outcome of applying the operation:
+ * - `'applied'`: The operation was successfully applied to the state
+ * - `'superseded'`: The operation was overridden by a concurrent write
+ *   (e.g., LWW register where another writer had a higher timestamp)
+ * - `'redundant'`: The operation had no effect because the state already
+ *   reflected it (e.g., adding a node that was already present)
+ *
+ * @param {unknown} value - The result to validate
+ * @param {number} i - Index of the operation in the ops array (for error messages)
+ * @returns {void}
+ * @throws {Error} If value is not a string or not one of the valid RESULT_TYPES
+ *
+ * @example
+ * validateOpResult('applied', 0); // OK
+ * validateOpResult('superseded', 1); // OK
+ * validateOpResult('failed', 0); // throws Error
+ */
+function validateOpResult(value, i) {
+  if (typeof value !== 'string' || !resultTypeSet.has(value)) {
+    throw new Error(`ops[${i}].result must be one of: ${RESULT_TYPES.join(', ')}`);
+  }
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+/**
+ * @typedef {Object} OpOutcome
+ * @property {string} op - Operation type ('NodeAdd' | 'NodeTombstone' | 'EdgeAdd' | 'EdgeTombstone' | 'PropSet' | 'BlobValue')
+ * @property {string} target - Node ID or edge key
+ * @property {'applied' | 'superseded' | 'redundant'} result - Outcome of the operation
+ * @property {string} [reason] - Human-readable explanation (e.g., "LWW: writer bob at lamport 43 wins")
+ */
+
+/**
+ * @typedef {Object} TickReceipt
+ * @property {string} patchSha - SHA of the patch commit
+ * @property {string} writer - Writer ID that produced the patch
+ * @property {number} lamport - Lamport timestamp of the patch
+ * @property {ReadonlyArray<Readonly<OpOutcome>>} ops - Per-operation outcomes (frozen)
+ */
+
+/**
+ * Creates an immutable TickReceipt.
+ *
+ * @param {Object} params
+ * @param {string} params.patchSha - SHA of the patch commit
+ * @param {string} params.writer - Writer ID
+ * @param {number} params.lamport - Lamport timestamp (non-negative integer)
+ * @param {OpOutcome[]} params.ops - Per-operation outcome records
+ * @returns {Readonly<TickReceipt>} Frozen tick receipt
+ * @throws {Error} If any parameter is invalid
+ */
+export function createTickReceipt({ patchSha, writer, lamport, ops }) {
+  // --- patchSha ---
+  if (typeof patchSha !== 'string' || patchSha.length === 0) {
+    throw new Error('patchSha must be a non-empty string');
+  }
+
+  // --- writer ---
+  if (typeof writer !== 'string' || writer.length === 0) {
+    throw new Error('writer must be a non-empty string');
+  }
+
+  // --- lamport ---
+  if (!Number.isInteger(lamport) || lamport < 0) {
+    throw new Error('lamport must be a non-negative integer');
+  }
+
+  // --- ops ---
+  if (!Array.isArray(ops)) {
+    throw new Error('ops must be an array');
+  }
+
+  for (let i = 0; i < ops.length; i++) {
+    validateOp(ops[i], i);
+  }
+
+  // Build frozen op copies (defensive: don't alias caller's objects)
+  const frozenOps = Object.freeze(
+    ops.map((o) => {
+      const entry = { op: o.op, target: o.target, result: o.result };
+      if (o.reason !== undefined) {
+        entry.reason = o.reason;
+      }
+      return Object.freeze(entry);
+    }),
+  );
+
+  return Object.freeze({
+    patchSha,
+    writer,
+    lamport,
+    ops: frozenOps,
+  });
+}
+
+// ============================================================================
+// Canonical JSON Serialization
+// ============================================================================
+
+/**
+ * Produces a deterministic JSON string for a TickReceipt.
+ *
+ * Keys are sorted alphabetically at every nesting level, ensuring
+ * identical receipts always produce identical byte strings regardless
+ * of property insertion order.
+ *
+ * @param {TickReceipt} receipt - A TickReceipt (as returned by createTickReceipt)
+ * @returns {string} Deterministic JSON string
+ */
+export function canonicalJson(receipt) {
+  return JSON.stringify(receipt, sortedReplacer);
+}
+
+/**
+ * JSON.stringify replacer callback that sorts object keys alphabetically.
+ *
+ * This function is passed as the second argument to `JSON.stringify()` and
+ * is called recursively for every key-value pair in the object being serialized.
+ * For plain objects, it returns a new object with keys in sorted order, ensuring
+ * deterministic JSON output regardless of property insertion order.
+ *
+ * Arrays are passed through unchanged since their order is semantically significant.
+ * Primitive values (strings, numbers, booleans, null) are also passed through unchanged.
+ *
+ * This is essential for producing canonical JSON representations that can be
+ * compared byte-for-byte or hashed consistently.
+ *
+ * @param {string} _key - The current property key being processed (unused)
+ * @param {unknown} value - The current value being processed
+ * @returns {unknown} For objects: a new object with alphabetically sorted keys.
+ *   For arrays and primitives: the value unchanged.
+ *
+ * @example
+ * // Used internally by canonicalJson
+ * JSON.stringify({ b: 1, a: 2 }, sortedReplacer);
+ * // Returns: '{"a":2,"b":1}'
+ *
+ * @example
+ * // Nested objects are also sorted
+ * JSON.stringify({ z: { b: 1, a: 2 }, y: 3 }, sortedReplacer);
+ * // Returns: '{"y":3,"z":{"a":2,"b":1}}'
+ *
+ * @private
+ */
+function sortedReplacer(_key, value) {
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = value[k];
+    }
+    return sorted;
+  }
+  return value;
+}