@git-stunts/git-warp 10.1.1

package/src/domain/services/PatchMessageCodec.js

@@ -0,0 +1,140 @@
+/**
+ * Patch message encoding and decoding for WARP commit messages.
+ *
+ * Handles the 'patch' message type which contains graph mutations from a
+ * single writer. See {@link module:domain/services/WarpMessageCodec} for the
+ * facade that re-exports all codec functions.
+ *
+ * @module domain/services/PatchMessageCodec
+ */
+
+import { validateGraphName, validateWriterId } from '../utils/RefLayout.js';
+import {
+  getCodec,
+  MESSAGE_TITLES,
+  TRAILER_KEYS,
+  validateOid,
+  validatePositiveInteger,
+  validateSchema,
+} from './MessageCodecInternal.js';
+
+// -----------------------------------------------------------------------------
+// Encoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Encodes a patch commit message.
+ *
+ * @param {Object} options - The patch message options
+ * @param {string} options.graph - The graph name
+ * @param {string} options.writer - The writer ID
+ * @param {number} options.lamport - The Lamport timestamp (must be a positive integer)
+ * @param {string} options.patchOid - The OID of the patch blob
+ * @param {number} [options.schema=2] - The schema version (defaults to 2 for new messages)
+ * @returns {string} The encoded commit message
+ * @throws {Error} If any validation fails
+ *
+ * @example
+ * const message = encodePatchMessage({
+ *   graph: 'events',
+ *   writer: 'node-1',
+ *   lamport: 42,
+ *   patchOid: 'abc123...' // 40-char hex
+ * });
+ */
+export function encodePatchMessage({ graph, writer, lamport, patchOid, schema = 2 }) {
+  // Validate inputs
+  validateGraphName(graph);
+  validateWriterId(writer);
+  validatePositiveInteger(lamport, 'lamport');
+  validateOid(patchOid, 'patchOid');
+  validateSchema(schema);
+
+  const codec = getCodec();
+  return codec.encode({
+    title: MESSAGE_TITLES.patch,
+    trailers: {
+      [TRAILER_KEYS.kind]: 'patch',
+      [TRAILER_KEYS.graph]: graph,
+      [TRAILER_KEYS.writer]: writer,
+      [TRAILER_KEYS.lamport]: String(lamport),
+      [TRAILER_KEYS.patchOid]: patchOid,
+      [TRAILER_KEYS.schema]: String(schema),
+    },
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Decoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Decodes a patch commit message.
+ *
+ * @param {string} message - The raw commit message
+ * @returns {Object} The decoded patch message
+ * @returns {string} return.kind - Always 'patch'
+ * @returns {string} return.graph - The graph name
+ * @returns {string} return.writer - The writer ID
+ * @returns {number} return.lamport - The Lamport timestamp
+ * @returns {string} return.patchOid - The patch blob OID
+ * @returns {number} return.schema - The schema version
+ * @throws {Error} If the message is not a valid patch message
+ *
+ * @example
+ * const { kind, graph, writer, lamport, patchOid, schema } = decodePatchMessage(message);
+ */
+export function decodePatchMessage(message) {
+  const codec = getCodec();
+  const decoded = codec.decode(message);
+  const { trailers } = decoded;
+
+  // Validate kind discriminator
+  const kind = trailers[TRAILER_KEYS.kind];
+  if (kind !== 'patch') {
+    throw new Error(`Invalid patch message: eg-kind must be 'patch', got '${kind}'`);
+  }
+
+  // Extract and validate required fields
+  const graph = trailers[TRAILER_KEYS.graph];
+  if (!graph) {
+    throw new Error('Invalid patch message: missing required trailer eg-graph');
+  }
+
+  const writer = trailers[TRAILER_KEYS.writer];
+  if (!writer) {
+    throw new Error('Invalid patch message: missing required trailer eg-writer');
+  }
+
+  const lamportStr = trailers[TRAILER_KEYS.lamport];
+  if (!lamportStr) {
+    throw new Error('Invalid patch message: missing required trailer eg-lamport');
+  }
+  const lamport = parseInt(lamportStr, 10);
+  if (!Number.isInteger(lamport) || lamport < 1) {
+    throw new Error(`Invalid patch message: eg-lamport must be a positive integer, got '${lamportStr}'`);
+  }
+
+  const patchOid = trailers[TRAILER_KEYS.patchOid];
+  if (!patchOid) {
+    throw new Error('Invalid patch message: missing required trailer eg-patch-oid');
+  }
+
+  const schemaStr = trailers[TRAILER_KEYS.schema];
+  if (!schemaStr) {
+    throw new Error('Invalid patch message: missing required trailer eg-schema');
+  }
+  const schema = parseInt(schemaStr, 10);
+  if (!Number.isInteger(schema) || schema < 1) {
+    throw new Error(`Invalid patch message: eg-schema must be a positive integer, got '${schemaStr}'`);
+  }
+
+  return {
+    kind: 'patch',
+    graph,
+    writer,
+    lamport,
+    patchOid,
+    schema,
+  };
+}

package/src/domain/services/ProvenanceIndex.js

@@ -0,0 +1,337 @@
+import defaultCodec from '../utils/defaultCodec.js';
+
+/**
+ * ProvenanceIndex - Node-to-Patch SHA Index
+ *
+ * Implements HG/IO/2: Build nodeId-to-patchSha index from I/O declarations.
+ * This enables quick answers to "which patches affected node X?" without
+ * replaying all patches.
+ *
+ * The index maps:
+ * - nodeId -> Set<patchSha> (patches that read or wrote this node)
+ *
+ * This supports the computational holography theorem from Paper III:
+ * given a target node, we can compute its backward causal cone D(v)
+ * by walking the index.
+ *
+ * @module domain/services/ProvenanceIndex
+ */
+
+/**
+ * ProvenanceIndex - Maps node/edge IDs to contributing patch SHAs.
+ *
+ * This index is built incrementally during materialization by extracting
+ * the `reads` and `writes` arrays from each patch's I/O declarations
+ * (implemented by HG/IO/1).
+ *
+ * ## Usage
+ *
+ * ```javascript
+ * const index = new ProvenanceIndex();
+ *
+ * // During materialization, add each patch's I/O declarations
+ * index.addPatch(patchSha, patch.reads, patch.writes);
+ *
+ * // Query: which patches affected this node?
+ * const shas = index.patchesFor('user:alice');
+ * // Returns: ['abc123', 'def456', ...]
+ * ```
+ *
+ * ## Persistence
+ *
+ * The index can be serialized for checkpoint storage:
+ * ```javascript
+ * const buffer = index.serialize();
+ * // Store in checkpoint tree as provenanceIndex.cbor
+ *
+ * // Later, restore from checkpoint
+ * const index = ProvenanceIndex.deserialize(buffer);
+ * ```
+ */
+class ProvenanceIndex {
+  /**
+   * Internal index mapping nodeId/edgeKey to Set of patch SHAs.
+   * @type {Map<string, Set<string>>}
+   * @private
+   */
+  #index;
+
+  /**
+   * Creates a new ProvenanceIndex.
+   *
+   * @param {Map<string, Set<string>>} [initialIndex] - Optional initial index data (defensively copied)
+   */
+  constructor(initialIndex) {
+    if (initialIndex) {
+      // Defensive copy to prevent external mutation
+      this.#index = new Map();
+      for (const [k, v] of initialIndex) {
+        this.#index.set(k, new Set(v));
+      }
+    } else {
+      this.#index = new Map();
+    }
+  }
+
+  /**
+   * Creates an empty ProvenanceIndex.
+   *
+   * @returns {ProvenanceIndex} A fresh, empty index
+   */
+  static empty() {
+    return new ProvenanceIndex();
+  }
+
+  /**
+   * Adds a patch's I/O declarations to the index.
+   *
+   * Both reads and writes are indexed because both indicate that
+   * the patch "affected" the entity:
+   * - Writes: the patch modified the entity
+   * - Reads: the patch's result depends on the entity's state
+   *
+   * This enables computing the full backward causal cone for slicing.
+   *
+   * @param {string} patchSha - The Git SHA of the patch commit
+   * @param {string[]|undefined} reads - Array of nodeIds/edgeKeys read by this patch
+   * @param {string[]|undefined} writes - Array of nodeIds/edgeKeys written by this patch
+   * @returns {ProvenanceIndex} This index for chaining
+   */
+  addPatch(patchSha, reads, writes) {
+    // Index all reads
+    if (reads && reads.length > 0) {
+      for (const entityId of reads) {
+        this.#addEntry(entityId, patchSha);
+      }
+    }
+
+    // Index all writes
+    if (writes && writes.length > 0) {
+      for (const entityId of writes) {
+        this.#addEntry(entityId, patchSha);
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Adds a single entry to the index.
+   *
+   * @param {string} entityId - The node ID or edge key
+   * @param {string} patchSha - The patch SHA
+   * @private
+   */
+  #addEntry(entityId, patchSha) {
+    let shas = this.#index.get(entityId);
+    if (!shas) {
+      shas = new Set();
+      this.#index.set(entityId, shas);
+    }
+    shas.add(patchSha);
+  }
+
+  /**
+   * Returns all patch SHAs that affected a given node or edge.
+   *
+   * "Affected" means the patch either read from or wrote to the entity.
+   * The returned array is sorted alphabetically for determinism.
+   *
+   * @param {string} entityId - The node ID or edge key to query
+   * @returns {string[]} Array of patch SHAs, sorted alphabetically
+   *
+   * @example
+   * const shas = index.patchesFor('user:alice');
+   * // Returns: ['abc123', 'def456', 'ghi789']
+   */
+  patchesFor(entityId) {
+    const shas = this.#index.get(entityId);
+    if (!shas || shas.size === 0) {
+      return [];
+    }
+    return [...shas].sort();
+  }
+
+  /**
+   * Returns whether the index has any entries for a given entity.
+   *
+   * @param {string} entityId - The node ID or edge key to check
+   * @returns {boolean} True if the entity has at least one contributing patch
+   */
+  has(entityId) {
+    const shas = this.#index.get(entityId);
+    return shas !== undefined && shas.size > 0;
+  }
+
+  /**
+   * Returns the number of entities in the index.
+   *
+   * @returns {number} Count of indexed entities
+   */
+  get size() {
+    return this.#index.size;
+  }
+
+  /**
+   * Returns all entity IDs in the index.
+   *
+   * @returns {string[]} Array of entity IDs, sorted alphabetically
+   */
+  entities() {
+    return [...this.#index.keys()].sort();
+  }
+
+  /**
+   * Clears all entries from the index.
+   *
+   * @returns {ProvenanceIndex} This index for chaining
+   */
+  clear() {
+    this.#index.clear();
+    return this;
+  }
+
+  /**
+   * Merges another index into this one.
+   *
+   * All entries from the other index are added to this index.
+   * This is useful for combining indexes from different sources
+   * (e.g., checkpoint index + incremental patches).
+   *
+   * @param {ProvenanceIndex} other - The index to merge in
+   * @returns {ProvenanceIndex} This index for chaining
+   */
+  merge(other) {
+    for (const [entityId, shas] of other.#index) {
+      for (const sha of shas) {
+        this.#addEntry(entityId, sha);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Creates a clone of this index.
+   *
+   * @returns {ProvenanceIndex} A new index with the same data
+   */
+  clone() {
+    const clonedMap = new Map();
+    for (const [entityId, shas] of this.#index) {
+      clonedMap.set(entityId, new Set(shas));
+    }
+    return new ProvenanceIndex(clonedMap);
+  }
+
+  /**
+   * Returns sorted entries for deterministic output.
+   *
+   * @returns {Array<[string, string[]]>} Sorted array of [entityId, sortedShas[]] pairs
+   * @private
+   */
+  #sortedEntries() {
+    const entries = [];
+    for (const [entityId, shas] of this.#index) {
+      entries.push([entityId, [...shas].sort()]);
+    }
+    entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return entries;
+  }
+
+  /**
+   * Serializes the index to CBOR format for checkpoint storage.
+   *
+   * The serialized format is a sorted array of [entityId, sortedShas[]] pairs
+   * for deterministic output.
+   *
+   * @param {Object} [options]
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+   * @returns {Buffer} CBOR-encoded index
+   */
+  serialize({ codec } = {}) {
+    const c = codec || defaultCodec;
+    return c.encode({ version: 1, entries: this.#sortedEntries() });
+  }
+
+  /**
+   * Builds an index Map from an entries array.
+   *
+   * @param {Array<[string, string[]]>} entries - Array of [entityId, shas[]] pairs
+   * @returns {Map<string, Set<string>>} The built index
+   * @private
+   */
+  static #buildIndex(entries) {
+    const index = new Map();
+    for (const [entityId, shas] of entries) {
+      index.set(entityId, new Set(shas));
+    }
+    return index;
+  }
+
+  /**
+   * Deserializes an index from CBOR format.
+   *
+   * @param {Buffer} buffer - CBOR-encoded index
+   * @param {Object} [options]
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+   * @returns {ProvenanceIndex} The deserialized index
+   * @throws {Error} If the buffer contains an unsupported version
+   */
+  static deserialize(buffer, { codec } = {}) {
+    const c = codec || defaultCodec;
+    const obj = c.decode(buffer);
+
+    if (obj.version !== 1) {
+      throw new Error(`Unsupported ProvenanceIndex version: ${obj.version}`);
+    }
+
+    if (!obj.entries || !Array.isArray(obj.entries)) {
+      throw new Error('Missing or invalid ProvenanceIndex entries');
+    }
+
+    return new ProvenanceIndex(ProvenanceIndex.#buildIndex(obj.entries));
+  }
+
+  /**
+   * Returns a JSON-serializable representation of this index.
+   *
+   * @returns {Object} Object with version and entries array
+   */
+  toJSON() {
+    return { version: 1, entries: this.#sortedEntries() };
+  }
+
+  /**
+   * Creates a ProvenanceIndex from a JSON representation.
+   *
+   * @param {Object} json - Object with version and entries array
+   * @returns {ProvenanceIndex} The deserialized index
+   * @throws {Error} If the JSON contains an unsupported version
+   */
+  static fromJSON(json) {
+    if (json.version !== 1) {
+      throw new Error(`Unsupported ProvenanceIndex version: ${json.version}`);
+    }
+
+    if (!json.entries || !Array.isArray(json.entries)) {
+      throw new Error('Missing or invalid ProvenanceIndex entries');
+    }
+
+    return new ProvenanceIndex(ProvenanceIndex.#buildIndex(json.entries || []));
+  }
+
+  /**
+   * Returns an iterator over [entityId, patchShas[]] pairs in deterministic order.
+   * Uses #sortedEntries() to ensure consistent ordering across iterations.
+   *
+   * @returns {Iterator<[string, string[]]>} Iterator over index entries
+   */
+  *[Symbol.iterator]() {
+    for (const entry of this.#sortedEntries()) {
+      yield entry;
+    }
+  }
+}
+
+export default ProvenanceIndex;
+export { ProvenanceIndex };

package/src/domain/services/ProvenancePayload.js

@@ -0,0 +1,242 @@
+/**
+ * ProvenancePayload - Transferable Provenance as a Monoid
+ *
+ * Implements the provenance payload from Paper III (Computational Holography):
+ * P = (mu_0, ..., mu_{n-1}) - an ordered sequence of tick patches.
+ *
+ * The payload monoid (Payload, ., epsilon):
+ * - Composition is concatenation
+ * - Identity is empty sequence
+ *
+ * Monoid laws hold:
+ * - identity.concat(p) === p (left identity)
+ * - p.concat(identity) === p (right identity)
+ * - (a.concat(b)).concat(c) === a.concat(b.concat(c)) (associativity)
+ *
+ * @module domain/services/ProvenancePayload
+ */
+
+import { reduceV5, createEmptyStateV5, cloneStateV5 } from './JoinReducer.js';
+
+/**
+ * A single patch entry in the provenance payload.
+ *
+ * @typedef {Object} PatchEntry
+ * @property {Object} patch - The decoded patch object (writer, lamport, ops, context)
+ * @property {string} sha - The Git SHA of the patch commit
+ */
+
+/**
+ * ProvenancePayload - Immutable sequence of patches forming a monoid.
+ *
+ * This class packages an ordered sequence of patches as a transferable
+ * provenance payload. Combined with an initial state (boundary encoding),
+ * it enables deterministic replay (computational holography).
+ *
+ * ## Monoid Structure
+ *
+ * ProvenancePayload forms a monoid under concatenation:
+ * - **Identity**: `ProvenancePayload.identity()` returns the empty payload
+ * - **Composition**: `a.concat(b)` concatenates two payloads
+ *
+ * ## Computational Holography
+ *
+ * Given a boundary encoding B = (U_0, P) where:
+ * - U_0 is the initial state
+ * - P is the provenance payload
+ *
+ * The `replay(U_0)` method uniquely determines the interior worldline,
+ * producing the final materialized state.
+ *
+ * @example
+ * ```javascript
+ * // Create payload from patches
+ * const payload = new ProvenancePayload([
+ *   { patch: patch1, sha: 'abc123' },
+ *   { patch: patch2, sha: 'def456' },
+ * ]);
+ *
+ * // Monoid operations
+ * const empty = ProvenancePayload.identity();
+ * const combined = payload1.concat(payload2);
+ *
+ * // Replay to materialize state
+ * const state = payload.replay();
+ * ```
+ */
+class ProvenancePayload {
+  /**
+   * The internal array of patch entries. Frozen after construction.
+   * @type {ReadonlyArray<PatchEntry>}
+   * @private
+   */
+  #patches;
+
+  /**
+   * Creates a new ProvenancePayload from an ordered sequence of patches.
+   *
+   * The payload is immutable after construction - the patches array is
+   * frozen to prevent modification.
+   *
+   * @param {Array<PatchEntry>} patches - Ordered sequence of patch entries.
+   *   Each entry must have { patch, sha } where patch is the decoded patch
+   *   object and sha is the Git commit SHA.
+   * @throws {TypeError} If patches is not an array
+   */
+  constructor(patches = []) {
+    if (!Array.isArray(patches)) {
+      throw new TypeError('ProvenancePayload requires an array of patches');
+    }
+
+    // Shallow copy and freeze to ensure immutability
+    this.#patches = Object.freeze([...patches]);
+
+    // Freeze the instance itself
+    Object.freeze(this);
+  }
+
+  /**
+   * Returns the identity element of the payload monoid.
+   *
+   * The identity payload contains no patches. It satisfies:
+   * - `identity.concat(p)` equals `p` for any payload `p`
+   * - `p.concat(identity)` equals `p` for any payload `p`
+   *
+   * @returns {ProvenancePayload} The empty/identity payload
+   */
+  static identity() {
+    return new ProvenancePayload([]);
+  }
+
+  /**
+   * Returns the number of patches in this payload.
+   *
+   * @returns {number} The patch count
+   */
+  get length() {
+    return this.#patches.length;
+  }
+
+  /**
+   * Concatenates this payload with another, forming a new payload.
+   *
+   * This is the monoid composition operation. The resulting payload
+   * contains all patches from this payload followed by all patches
+   * from the other payload.
+   *
+   * Monoid laws:
+   * - `identity.concat(p) === p` (left identity)
+   * - `p.concat(identity) === p` (right identity)
+   * - `(a.concat(b)).concat(c) === a.concat(b.concat(c))` (associativity)
+   *
+   * @param {ProvenancePayload} other - The payload to append
+   * @returns {ProvenancePayload} A new payload with combined patches
+   * @throws {TypeError} If other is not a ProvenancePayload
+   */
+  concat(other) {
+    if (!(other instanceof ProvenancePayload)) {
+      throw new TypeError('concat requires a ProvenancePayload');
+    }
+
+    // Optimization: avoid array allocation for identity cases
+    if (this.#patches.length === 0) {
+      return other;
+    }
+    if (other.#patches.length === 0) {
+      return this;
+    }
+
+    return new ProvenancePayload([...this.#patches, ...other.#patches]);
+  }
+
+  /**
+   * Replays the payload to produce a materialized state.
+   *
+   * This implements the computational holography theorem (Paper III):
+   * Given a boundary encoding B = (U_0, P), Replay(B) uniquely
+   * determines the interior worldline.
+   *
+   * The replay applies patches in order using CRDT merge semantics:
+   * - Nodes/edges use OR-Set (add-wins)
+   * - Properties use LWW (Last-Write-Wins)
+   *
+   * @param {import('./JoinReducer.js').WarpStateV5} [initialState] - The initial
+   *   state U_0 to replay from. If omitted, starts from empty state.
+   * @returns {import('./JoinReducer.js').WarpStateV5} The final materialized state
+   */
+  replay(initialState) {
+    // Handle empty payload - return clone of initial or fresh empty state
+    if (this.#patches.length === 0) {
+      return initialState ? cloneStateV5(initialState) : createEmptyStateV5();
+    }
+
+    // Use JoinReducer's reduceV5 for deterministic materialization.
+    // Note: reduceV5 returns { state, receipts } when options.receipts is truthy,
+    // but returns bare WarpStateV5 when no options passed (as here).
+    return reduceV5(this.#patches, initialState);
+  }
+
+  /**
+   * Returns an iterator over the patch entries.
+   *
+   * This allows using the payload in for...of loops and spread syntax.
+   *
+   * @returns {Iterator<PatchEntry>} Iterator over patch entries
+   */
+  [Symbol.iterator]() {
+    return this.#patches[Symbol.iterator]();
+  }
+
+  /**
+   * Returns the patch entry at the given index.
+   *
+   * Supports negative indices like Array.prototype.at() (e.g., -1 for last element).
+   *
+   * @param {number} index - The index (negative indices count from end)
+   * @returns {PatchEntry|undefined} The patch entry, or undefined if out of bounds
+   */
+  at(index) {
+    return this.#patches.at(index);
+  }
+
+  /**
+   * Returns a new payload containing a slice of this payload's patches.
+   *
+   * This enables the slicing operation from Paper III: materializing
+   * only the causal cone for a target value.
+   *
+   * @param {number} [start=0] - Start index (inclusive)
+   * @param {number} [end] - End index (exclusive), defaults to length
+   * @returns {ProvenancePayload} A new payload with the sliced patches
+   */
+  slice(start = 0, end = this.#patches.length) {
+    const sliced = this.#patches.slice(start, end);
+    return new ProvenancePayload(sliced);
+  }
+
+  /**
+   * Returns a JSON-serializable representation of this payload.
+   *
+   * The serialized form is an array of patch entries, suitable for
+   * transmission as a Boundary Transition Record (BTR).
+   *
+   * @returns {Array<PatchEntry>} Array of patch entries
+   */
+  toJSON() {
+    return [...this.#patches];
+  }
+
+  /**
+   * Creates a ProvenancePayload from a JSON-serialized array.
+   *
+   * @param {Array<PatchEntry>} json - Array of patch entries
+   * @returns {ProvenancePayload} The deserialized payload
+   * @throws {TypeError} If json is not an array
+   */
+  static fromJSON(json) {
+    return new ProvenancePayload(json);
+  }
+}
+
+export default ProvenancePayload;
+export { ProvenancePayload };