@git-stunts/git-warp 10.1.1

package/src/domain/services/LegacyAnchorDetector.js

@@ -0,0 +1,67 @@
+/**
+ * Legacy Anchor Detector for v3 backward compatibility.
+ *
+ * This module provides functions to detect legacy v3 JSON anchors
+ * ({"_type":"anchor"}) alongside v4 trailer-based anchors for
+ * backward compatibility in E-plane traversals.
+ *
+ * @module domain/services/LegacyAnchorDetector
+ * @see WARP Spec Section 17 - Backward Compatibility
+ */
+
+/**
+ * Detects if a commit message is a legacy v3 anchor.
+ * v3 anchors are JSON objects with _type: "anchor"
+ *
+ * @param {string} message - The commit message to check
+ * @returns {boolean} True if the message is a v3 JSON anchor
+ *
+ * @example
+ * isLegacyAnchor('{"_type":"anchor"}'); // true
+ * isLegacyAnchor('{"_type":"node"}'); // false
+ * isLegacyAnchor('plain text'); // false
+ */
+export function isLegacyAnchor(message) {
+  if (typeof message !== 'string') {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(message.trim());
+    return parsed && parsed._type === 'anchor';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detects if a commit is any type of anchor (v3 JSON or v4 trailer).
+ *
+ * This function provides unified anchor detection that works across
+ * both protocol versions, ensuring anchors are correctly filtered
+ * from E-plane traversals regardless of format.
+ *
+ * @param {string} message - The commit message to check
+ * @returns {boolean} True if the message is any type of anchor
+ *
+ * @example
+ * // v4 trailer anchor
+ * isAnyAnchor('warp:anchor\n\neg-kind: anchor\neg-graph: test'); // true
+ *
+ * // v3 JSON anchor
+ * isAnyAnchor('{"_type":"anchor"}'); // true
+ *
+ * // Regular message
+ * isAnyAnchor('Some node content'); // false
+ */
+export function isAnyAnchor(message) {
+  if (typeof message !== 'string') {
+    return false;
+  }
+
+  // Check v4 trailer-based anchor
+  if (message.includes('eg-kind: anchor')) {
+    return true;
+  }
+  // Check v3 JSON anchor
+  return isLegacyAnchor(message);
+}

package/src/domain/services/LogicalTraversal.js

@@ -0,0 +1,351 @@
+/**
+ * LogicalTraversal - Traversal utilities for the logical WARP graph.
+ *
+ * Provides deterministic BFS/DFS/shortestPath/connectedComponent over
+ * the materialized logical graph (node/edge OR-Sets), not the Git DAG.
+ */
+
+import TraversalError from '../errors/TraversalError.js';
+
+const DEFAULT_MAX_DEPTH = 1000;
+
+/**
+ * Validates and normalizes an edge direction parameter.
+ *
+ * @param {string|undefined} direction - The direction to validate ('out', 'in', or 'both')
+ * @returns {'out'|'in'|'both'} The validated direction, defaulting to 'out' if undefined
+ * @throws {TraversalError} If the direction is not one of the valid values
+ */
+function assertDirection(direction) {
+  if (direction === undefined) {
+    return 'out';
+  }
+  if (direction === 'out' || direction === 'in' || direction === 'both') {
+    return direction;
+  }
+  throw new TraversalError(`Invalid direction: ${direction}`, {
+    code: 'INVALID_DIRECTION',
+    context: { direction },
+  });
+}
+
+/**
+ * Normalizes a label filter into a Set for efficient lookup.
+ *
+ * Accepts a single label string, an array of labels, or undefined. Returns
+ * a Set containing the label(s) or null if no filter is specified.
+ *
+ * @param {string|string[]|undefined} labelFilter - The label filter to normalize
+ * @returns {Set<string>|null} A Set of labels for filtering, or null if no filter
+ * @throws {TraversalError} If labelFilter is neither a string, array, nor undefined
+ */
+function normalizeLabelFilter(labelFilter) {
+  if (labelFilter === undefined) {
+    return null;
+  }
+  if (Array.isArray(labelFilter)) {
+    return new Set(labelFilter);
+  }
+  if (typeof labelFilter === 'string') {
+    return new Set([labelFilter]);
+  }
+  throw new TraversalError('labelFilter must be a string or array', {
+    code: 'INVALID_LABEL_FILTER',
+    context: { receivedType: typeof labelFilter },
+  });
+}
+
+/**
+ * Filters a list of neighbor edges by label.
+ *
+ * If no label set is provided (null), returns all neighbors unchanged.
+ * If an empty label set is provided, returns an empty array.
+ * Otherwise, returns only edges whose label is in the set.
+ *
+ * @param {Array<{neighborId: string, label: string}>} neighbors - The list of neighbor edges to filter
+ * @param {Set<string>|null} labelSet - The set of allowed labels, or null to allow all
+ * @returns {Array<{neighborId: string, label: string}>} The filtered list of neighbor edges
+ */
+function filterByLabel(neighbors, labelSet) {
+  if (!labelSet) {
+    return neighbors;
+  }
+  if (labelSet.size === 0) {
+    return [];
+  }
+  return neighbors.filter((edge) => labelSet.has(edge.label));
+}
+
+/**
+ * Retrieves neighbors of a node based on direction and label filter.
+ *
+ * Returns outgoing neighbors for 'out', incoming neighbors for 'in', or
+ * a merged and sorted list of both for 'both'. Results are filtered by
+ * label if a label set is provided.
+ *
+ * For 'both' direction, neighbors are sorted first by neighborId, then by label,
+ * ensuring deterministic traversal order.
+ *
+ * @param {Object} params - The neighbor lookup parameters
+ * @param {string} params.nodeId - The node ID to get neighbors for
+ * @param {'out'|'in'|'both'} params.direction - The edge direction to follow
+ * @param {Object} params.adjacency - The adjacency structure from materialized graph
+ * @param {Map<string, Array<{neighborId: string, label: string}>>} params.adjacency.outgoing - Outgoing edge map
+ * @param {Map<string, Array<{neighborId: string, label: string}>>} params.adjacency.incoming - Incoming edge map
+ * @param {Set<string>|null} params.labelSet - The set of allowed labels, or null to allow all
+ * @returns {Array<{neighborId: string, label: string}>} The list of neighbor edges
+ */
+function getNeighbors({ nodeId, direction, adjacency, labelSet }) {
+  const outgoing = filterByLabel(adjacency.outgoing.get(nodeId) || [], labelSet);
+  const incoming = filterByLabel(adjacency.incoming.get(nodeId) || [], labelSet);
+
+  if (direction === 'out') {
+    return outgoing;
+  }
+  if (direction === 'in') {
+    return incoming;
+  }
+
+  const merged = outgoing.concat(incoming);
+  merged.sort((a, b) => {
+    if (a.neighborId !== b.neighborId) {
+      return a.neighborId < b.neighborId ? -1 : 1;
+    }
+    return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+  });
+  return merged;
+}
+
+/**
+ * Deterministic graph traversal engine for the materialized WARP graph.
+ *
+ * Provides BFS, DFS, shortest path (Dijkstra/A*), topological sort, and
+ * connected component algorithms over the logical node/edge OR-Sets.
+ * All traversals produce deterministic results via sorted neighbor ordering.
+ */
+export default class LogicalTraversal {
+  /**
+   * Creates a new LogicalTraversal.
+   *
+   * @param {import('../WarpGraph.js').default} graph - The WarpGraph instance to traverse
+   */
+  constructor(graph) {
+    this._graph = graph;
+  }
+
+  /**
+   * Prepares common traversal state by materializing the graph and validating inputs.
+   *
+   * This private method is called by all traversal methods to ensure the graph is
+   * materialized, the start node exists, and options are normalized.
+   *
+   * @private
+   * @param {string} start - The starting node ID for traversal
+   * @param {Object} options - The traversal options to normalize
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {number} [options.maxDepth] - Maximum depth to traverse
+   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: Object, depthLimit: number}>}
+   *   The normalized traversal parameters
+   * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
+   * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
+   * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
+   */
+  async _prepare(start, { dir, labelFilter, maxDepth }) {
+    const materialized = await this._graph._materializeGraph();
+
+    if (!(await this._graph.hasNode(start))) {
+      throw new TraversalError(`Start node not found: ${start}`, {
+        code: 'NODE_NOT_FOUND',
+        context: { start },
+      });
+    }
+
+    const resolvedDir = assertDirection(dir);
+    const labelSet = normalizeLabelFilter(labelFilter);
+    const { adjacency } = materialized;
+    const depthLimit = maxDepth ?? DEFAULT_MAX_DEPTH;
+
+    return { dir: resolvedDir, labelSet, adjacency, depthLimit };
+  }
+
+  /**
+   * Breadth-first traversal.
+   *
+   * @param {string} start - Starting node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum depth to traverse
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @returns {Promise<string[]>} Node IDs in visit order
+   * @throws {TraversalError} If the start node is not found or direction is invalid
+   */
+  async bfs(start, options = {}) {
+    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(start, options);
+    const visited = new Set();
+    const queue = [{ nodeId: start, depth: 0 }];
+    const result = [];
+
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (visited.has(current.nodeId)) {
+        continue;
+      }
+      if (current.depth > depthLimit) {
+        continue;
+      }
+
+      visited.add(current.nodeId);
+      result.push(current.nodeId);
+
+      if (current.depth === depthLimit) {
+        continue;
+      }
+
+      const neighbors = getNeighbors({
+        nodeId: current.nodeId,
+        direction: dir,
+        adjacency,
+        labelSet,
+      });
+
+      for (const edge of neighbors) {
+        if (!visited.has(edge.neighborId)) {
+          queue.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Depth-first traversal (pre-order).
+   *
+   * @param {string} start - Starting node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum depth to traverse
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @returns {Promise<string[]>} Node IDs in visit order
+   * @throws {TraversalError} If the start node is not found or direction is invalid
+   */
+  async dfs(start, options = {}) {
+    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(start, options);
+    const visited = new Set();
+    const stack = [{ nodeId: start, depth: 0 }];
+    const result = [];
+
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (visited.has(current.nodeId)) {
+        continue;
+      }
+      if (current.depth > depthLimit) {
+        continue;
+      }
+
+      visited.add(current.nodeId);
+      result.push(current.nodeId);
+
+      if (current.depth === depthLimit) {
+        continue;
+      }
+
+      const neighbors = getNeighbors({
+        nodeId: current.nodeId,
+        direction: dir,
+        adjacency,
+        labelSet,
+      });
+
+      for (let i = neighbors.length - 1; i >= 0; i -= 1) {
+        const edge = neighbors[i];
+        if (!visited.has(edge.neighborId)) {
+          stack.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Shortest path (unweighted) using BFS.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum search depth
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @returns {Promise<{found: boolean, path: string[], length: number}>}
+   *   When `found` is true, `path` contains the node IDs from `from` to `to` and
+   *   `length` is the hop count. When `found` is false, `path` is empty and `length` is -1.
+   * @throws {TraversalError} If the start node is not found or direction is invalid
+   */
+  async shortestPath(from, to, options = {}) {
+    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(from, options);
+
+    if (from === to) {
+      return { found: true, path: [from], length: 0 };
+    }
+
+    const visited = new Set();
+    const queue = [{ nodeId: from, depth: 0 }];
+    const parent = new Map();
+
+    visited.add(from);
+
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.depth >= depthLimit) {
+        continue;
+      }
+
+      const neighbors = getNeighbors({
+        nodeId: current.nodeId,
+        direction: dir,
+        adjacency,
+        labelSet,
+      });
+
+      for (const edge of neighbors) {
+        if (visited.has(edge.neighborId)) {
+          continue;
+        }
+        visited.add(edge.neighborId);
+        parent.set(edge.neighborId, current.nodeId);
+
+        if (edge.neighborId === to) {
+          const path = [to];
+          let cursor = current.nodeId;
+          while (cursor) {
+            path.push(cursor);
+            cursor = parent.get(cursor) || null;
+          }
+          path.reverse();
+          return { found: true, path, length: path.length - 1 };
+        }
+
+        queue.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
+      }
+    }
+
+    return { found: false, path: [], length: -1 };
+  }
+
+  /**
+   * Connected component (undirected by default).
+   *
+   * @param {string} start - Starting node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum depth to traverse (default: 1000)
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @returns {Promise<string[]>} Node IDs in visit order
+   * @throws {TraversalError} If the start node is not found
+   */
+  async connectedComponent(start, options = {}) {
+    return await this.bfs(start, { ...options, dir: 'both' });
+  }
+}

package/src/domain/services/MessageCodecInternal.js

@@ -0,0 +1,132 @@
+/**
+ * Shared internals for WARP message codecs.
+ *
+ * This module provides the lazy TrailerCodec singleton, constants, and
+ * validation helpers used by PatchMessageCodec, CheckpointMessageCodec,
+ * AnchorMessageCodec, and MessageSchemaDetector.
+ *
+ * Not part of the public API — consumers should import from
+ * WarpMessageCodec.js (the facade) or the individual sub-codecs.
+ *
+ * @module domain/services/MessageCodecInternal
+ * @private
+ */
+
+import { TrailerCodec, TrailerCodecService } from '@git-stunts/trailer-codec';
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+/**
+ * Message title prefixes for each WARP commit type.
+ * @type {Object<string, string>}
+ */
+export const MESSAGE_TITLES = {
+  patch: 'warp:patch',
+  checkpoint: 'warp:checkpoint',
+  anchor: 'warp:anchor',
+};
+
+/**
+ * Standard trailer keys used across WARP messages.
+ * @type {Object<string, string>}
+ */
+export const TRAILER_KEYS = {
+  kind: 'eg-kind',
+  graph: 'eg-graph',
+  writer: 'eg-writer',
+  lamport: 'eg-lamport',
+  patchOid: 'eg-patch-oid',
+  stateHash: 'eg-state-hash',
+  frontierOid: 'eg-frontier-oid',
+  indexOid: 'eg-index-oid',
+  schema: 'eg-schema',
+  checkpointVersion: 'eg-checkpoint',
+};
+
+/**
+ * Pattern for valid Git OIDs (40-character hex for SHA-1 or 64-character for SHA-256).
+ * @type {RegExp}
+ */
+const OID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+
+/**
+ * Pattern for valid SHA-256 state hashes (64-character hex).
+ * @type {RegExp}
+ */
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+
+// -----------------------------------------------------------------------------
+// Codec Instance
+// -----------------------------------------------------------------------------
+
+// Lazy singleton codec instance
+let _codec = null;
+
+/**
+ * Returns the lazy singleton TrailerCodec instance.
+ * @returns {TrailerCodec}
+ */
+export function getCodec() {
+  if (!_codec) {
+    const service = new TrailerCodecService();
+    _codec = new TrailerCodec({ service });
+  }
+  return _codec;
+}
+
+// -----------------------------------------------------------------------------
+// Validation Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Validates that a value is a valid Git OID.
+ * @param {string} oid - The OID to validate
+ * @param {string} fieldName - Name of the field for error messages
+ * @throws {Error} If the OID is invalid
+ */
+export function validateOid(oid, fieldName) {
+  if (typeof oid !== 'string') {
+    throw new Error(`Invalid ${fieldName}: expected string, got ${typeof oid}`);
+  }
+  if (!OID_PATTERN.test(oid)) {
+    throw new Error(`Invalid ${fieldName}: must be a 40 or 64 character hex string, got '${oid}'`);
+  }
+}
+
+/**
+ * Validates that a value is a valid SHA-256 hash.
+ * @param {string} hash - The hash to validate
+ * @param {string} fieldName - Name of the field for error messages
+ * @throws {Error} If the hash is invalid
+ */
+export function validateSha256(hash, fieldName) {
+  if (typeof hash !== 'string') {
+    throw new Error(`Invalid ${fieldName}: expected string, got ${typeof hash}`);
+  }
+  if (!SHA256_PATTERN.test(hash)) {
+    throw new Error(`Invalid ${fieldName}: must be a 64 character hex string, got '${hash}'`);
+  }
+}
+
+/**
+ * Validates that a value is a positive integer.
+ * @param {number} value - The value to validate
+ * @param {string} fieldName - Name of the field for error messages
+ * @throws {Error} If the value is not a positive integer
+ */
+export function validatePositiveInteger(value, fieldName) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    throw new Error(`Invalid ${fieldName}: must be a positive integer, got ${value}`);
+  }
+}
+
+/**
+ * Validates that a schema version is valid.
+ * @param {number} schema - The schema version to validate
+ * @throws {Error} If the schema version is invalid
+ */
+export function validateSchema(schema) {
+  validatePositiveInteger(schema, 'schema');
+}

package/src/domain/services/MessageSchemaDetector.js

@@ -0,0 +1,145 @@
+/**
+ * Schema version detection and compatibility validation for WARP messages.
+ *
+ * Provides utilities to detect schema versions from patch operations,
+ * detect message kinds from raw commit messages, and validate operation
+ * compatibility with a reader's maximum supported schema version.
+ *
+ * See {@link module:domain/services/WarpMessageCodec} for the facade
+ * that re-exports all functions from this module.
+ *
+ * @module domain/services/MessageSchemaDetector
+ */
+
+import { EDGE_PROP_PREFIX } from './KeyCodec.js';
+import SchemaUnsupportedError from '../errors/SchemaUnsupportedError.js';
+import { getCodec, TRAILER_KEYS } from './MessageCodecInternal.js';
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+/**
+ * Schema version for classic node-only patches (V5 format).
+ * @type {number}
+ */
+export const SCHEMA_V2 = 2;
+
+/**
+ * Schema version for patches that may contain edge property PropSet ops.
+ * @type {number}
+ */
+export const SCHEMA_V3 = 3;
+
+// -----------------------------------------------------------------------------
+// Schema Version Detection
+// -----------------------------------------------------------------------------
+
+/**
+ * Detects the appropriate schema version for a set of patch operations.
+ *
+ * Returns schema 3 if ANY PropSet op has a `node` field starting with the
+ * edge property prefix (`\x01`), indicating edge property support is required.
+ * Otherwise returns schema 2 for backward compatibility.
+ *
+ * @param {Array<{type: string, node?: string}>} ops - Array of patch operations
+ * @returns {number} The schema version (2 or 3)
+ */
+export function detectSchemaVersion(ops) {
+  if (!Array.isArray(ops)) {
+    return SCHEMA_V2;
+  }
+  for (const op of ops) {
+    if (op.type === 'PropSet' && typeof op.node === 'string' && op.node.startsWith(EDGE_PROP_PREFIX)) {
+      return SCHEMA_V3;
+    }
+  }
+  return SCHEMA_V2;
+}
+
+// -----------------------------------------------------------------------------
+// Schema Compatibility Validation
+// -----------------------------------------------------------------------------
+
+/**
+ * Asserts that a set of decoded patch operations is compatible with a given
+ * maximum supported schema version. Throws {@link SchemaUnsupportedError} if
+ * any operation requires a higher schema version than `maxSchema`.
+ *
+ * Currently the only schema boundary is v2 -> v3:
+ * - Schema v3 introduces edge property PropSet ops (node starts with `\x01`).
+ * - A v2-only reader MUST reject patches containing such ops to prevent
+ *   silent data loss.
+ * - A v3 patch that contains only classic node/edge ops is accepted by v2
+ *   readers — the schema number alone is NOT a rejection criterion.
+ *
+ * @param {Array<{type: string, node?: string}>} ops - Decoded patch operations
+ * @param {number} maxSchema - Maximum schema version the reader supports
+ * @throws {SchemaUnsupportedError} If ops require a schema version > maxSchema
+ *
+ * @example
+ * import { assertOpsCompatible, SCHEMA_V2 } from './MessageSchemaDetector.js';
+ * assertOpsCompatible(patch.ops, SCHEMA_V2); // throws if edge prop ops found
+ */
+export function assertOpsCompatible(ops, maxSchema) {
+  if (maxSchema >= SCHEMA_V3) {
+    return; // v3 readers understand everything up to v3
+  }
+  // For v2 readers: scan for edge property ops (the v3 feature)
+  if (!Array.isArray(ops)) {
+    return;
+  }
+  for (const op of ops) {
+    if (
+      op.type === 'PropSet' &&
+      typeof op.node === 'string' &&
+      op.node.startsWith(EDGE_PROP_PREFIX)
+    ) {
+      throw new SchemaUnsupportedError(
+        'Upgrade to >=7.3.0 (WEIGHTED) to sync edge properties.',
+        {
+          context: {
+            requiredSchema: SCHEMA_V3,
+            maxSupportedSchema: maxSchema,
+          },
+        }
+      );
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Detection Helper
+// -----------------------------------------------------------------------------
+
+/**
+ * Detects the WARP message kind from a raw commit message.
+ *
+ * @param {string} message - The raw commit message
+ * @returns {'patch'|'checkpoint'|'anchor'|null} The message kind, or null if not a WARP message
+ *
+ * @example
+ * const kind = detectMessageKind(message);
+ * if (kind === 'patch') {
+ *   const data = decodePatchMessage(message);
+ * }
+ */
+export function detectMessageKind(message) {
+  if (typeof message !== 'string') {
+    return null;
+  }
+
+  try {
+    const codec = getCodec();
+    const decoded = codec.decode(message);
+    const kind = decoded.trailers[TRAILER_KEYS.kind];
+
+    if (kind === 'patch' || kind === 'checkpoint' || kind === 'anchor') {
+      return kind;
+    }
+    return null;
+  } catch {
+    // Not a valid message format
+    return null;
+  }
+}