@git-stunts/git-warp 10.1.1

package/src/domain/crdt/VersionVector.js

@@ -0,0 +1,222 @@
+import { createDot } from './Dot.js';
+
+/**
+ * @fileoverview VersionVector - Causality Tracking via Join-Semilattice
+ *
+ * A version vector is a fundamental data structure for tracking causality in
+ * distributed systems. It maps each writer ID to the highest operation counter
+ * observed from that writer, forming a compact summary of "what has been seen."
+ *
+ * ## Semilattice Structure
+ *
+ * Version vectors form a **join-semilattice** under the pointwise maximum
+ * operation (vvMerge). A join-semilattice is a partially ordered set where
+ * every pair of elements has a least upper bound (join).
+ *
+ * The semilattice properties of vvMerge:
+ *
+ * - **Commutative**: vvMerge(a, b) = vvMerge(b, a)
+ *   Order of merge doesn't matter
+ *
+ * - **Associative**: vvMerge(vvMerge(a, b), c) = vvMerge(a, vvMerge(b, c))
+ *   Grouping of merges doesn't matter
+ *
+ * - **Idempotent**: vvMerge(a, a) = a
+ *   Merging with self is a no-op
+ *
+ * These properties guarantee that any replica can merge updates from any other
+ * replica in any order, and all will converge to the same state. This is the
+ * foundation of conflict-free replicated data types (CRDTs).
+ *
+ * ## Concurrent Conflict-Free Merges
+ *
+ * Version vectors enable concurrent merges without coordination:
+ *
+ * 1. **No locks needed**: Any replica can accept updates at any time
+ * 2. **Eventual consistency**: All replicas converge given sufficient communication
+ * 3. **Order independence**: Updates can arrive in any order
+ *
+ * When two writers concurrently create patches, each has a version vector that
+ * doesn't include the other's patch. When merged, the result includes both,
+ * and the semilattice properties ensure consistency.
+ *
+ * ## Relationship to Patch Causality
+ *
+ * In git-warp, each patch carries a version vector representing its causal
+ * context - all patches it has observed. This enables:
+ *
+ * - **Happens-before detection**: If vv_a <= vv_b, then a happens-before b
+ * - **Concurrency detection**: If neither vv_a <= vv_b nor vv_b <= vv_a, they're concurrent
+ * - **Dot containment**: A dot (writerId, counter) is "observed" if vv[writerId] >= counter
+ *
+ * The version vector grows monotonically: each patch advances at least its own
+ * writer's counter, and may advance others via merge.
+ *
+ * ## Partial Order
+ *
+ * Version vectors are partially ordered by vvDescends (componentwise <=):
+ * - vv_a <= vv_b iff for all writerIds w: vv_a[w] <= vv_b[w]
+ *
+ * This forms a **causal order** where vv_a <= vv_b means "a causally precedes b"
+ * or "b has observed all of a's history." Incomparable vectors represent
+ * concurrent states.
+ *
+ * @module crdt/VersionVector
+ */
+
+/**
+ * VersionVector - A map from writerId to counter representing observed operations.
+ * Used to track causality and determine what operations a writer has observed.
+ *
+ * @typedef {Map<string, number>} VersionVector
+ */
+
+/**
+ * Creates an empty VersionVector.
+ *
+ * @returns {VersionVector}
+ */
+export function createVersionVector() {
+  return new Map();
+}
+
+/**
+ * Increments the counter for a writer and returns the new Dot.
+ * This mutates the VersionVector.
+ *
+ * @param {VersionVector} vv - The version vector to mutate
+ * @param {string} writerId - The writer to increment
+ * @returns {import('./Dot.js').Dot} The new dot representing this operation
+ */
+export function vvIncrement(vv, writerId) {
+  const current = vv.get(writerId) || 0;
+  const newCounter = current + 1;
+  vv.set(writerId, newCounter);
+  return createDot(writerId, newCounter);
+}
+
+/**
+ * Merges two VersionVectors by taking the pointwise maximum.
+ * Returns a new VersionVector; does not mutate inputs.
+ *
+ * Properties:
+ * - Commutative: vvMerge(a, b) === vvMerge(b, a)
+ * - Associative: vvMerge(vvMerge(a, b), c) === vvMerge(a, vvMerge(b, c))
+ * - Idempotent: vvMerge(a, a) === a
+ *
+ * @param {VersionVector} a
+ * @param {VersionVector} b
+ * @returns {VersionVector}
+ */
+export function vvMerge(a, b) {
+  const result = new Map(a);
+
+  for (const [writerId, counter] of b) {
+    const existing = result.get(writerId) || 0;
+    result.set(writerId, Math.max(existing, counter));
+  }
+
+  return result;
+}
+
+/**
+ * Checks if VersionVector a descends from (is >= than) VersionVector b.
+ * a >= b means for every entry in b, a has an equal or greater counter.
+ *
+ * @param {VersionVector} a - The potentially descending vector
+ * @param {VersionVector} b - The potential ancestor vector
+ * @returns {boolean} True if a >= b componentwise
+ */
+export function vvDescends(a, b) {
+  for (const [writerId, counter] of b) {
+    const aCounter = a.get(writerId) || 0;
+    if (aCounter < counter) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Checks if a dot is contained within (observed by) the VersionVector.
+ * A dot is contained if dot.counter <= vv[dot.writerId].
+ *
+ * @param {VersionVector} vv
+ * @param {import('./Dot.js').Dot} dot
+ * @returns {boolean}
+ */
+export function vvContains(vv, dot) {
+  const counter = vv.get(dot.writerId) || 0;
+  return dot.counter <= counter;
+}
+
+/**
+ * Serializes a VersionVector to a plain object for CBOR encoding.
+ * Keys are sorted for deterministic serialization.
+ *
+ * @param {VersionVector} vv
+ * @returns {Object<string, number>}
+ */
+export function vvSerialize(vv) {
+  const obj = {};
+  const sortedKeys = [...vv.keys()].sort();
+
+  for (const key of sortedKeys) {
+    obj[key] = vv.get(key);
+  }
+
+  return obj;
+}
+
+/**
+ * Deserializes a plain object back to a VersionVector.
+ *
+ * @param {Object<string, number>} obj
+ * @returns {VersionVector}
+ * @throws {Error} If any counter value is not a non-negative integer
+ */
+export function vvDeserialize(obj) {
+  const vv = new Map();
+
+  for (const [writerId, counter] of Object.entries(obj)) {
+    if (typeof counter !== 'number' || !Number.isInteger(counter) || counter < 0) {
+      throw new Error(`Invalid counter for writerId "${writerId}": ${counter}`);
+    }
+    if (counter > 0) {
+      vv.set(writerId, counter);
+    }
+  }
+
+  return vv;
+}
+
+/**
+ * Clones a VersionVector.
+ *
+ * @param {VersionVector} vv
+ * @returns {VersionVector}
+ */
+export function vvClone(vv) {
+  return new Map(vv);
+}
+
+/**
+ * Checks if two VersionVectors are equal.
+ *
+ * @param {VersionVector} a
+ * @param {VersionVector} b
+ * @returns {boolean}
+ */
+export function vvEqual(a, b) {
+  if (a.size !== b.size) {
+    return false;
+  }
+
+  for (const [writerId, counter] of a) {
+    if (b.get(writerId) !== counter) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/domain/entities/GraphNode.js

@@ -0,0 +1,60 @@
+/**
+ * Immutable domain entity representing a node in the graph.
+ *
+ * Each GraphNode corresponds to a Git commit pointing to the Empty Tree.
+ * Instances are frozen after construction to ensure immutability.
+ *
+ * @example
+ * // Create a node from parsed git log data
+ * const node = new GraphNode({
+ *   sha: 'abc123def456...',
+ *   message: '{"type":"UserCreated","payload":{...}}',
+ *   author: 'Alice',
+ *   date: '2026-01-29',
+ *   parents: ['def456...']
+ * });
+ *
+ * @example
+ * // Access properties (all readonly)
+ * console.log(node.sha);      // 'abc123def456...'
+ * console.log(node.message);  // '{"type":"UserCreated",...}'
+ * console.log(node.parents);  // ['def456...'] (frozen array)
+ *
+ * @example
+ * // Attempting to modify throws in strict mode
+ * node.sha = 'new-sha';       // TypeError: Cannot assign to read only property
+ * node.parents.push('xyz');   // TypeError: Cannot add property
+ */
+export default class GraphNode {
+  /**
+   * Creates a new immutable GraphNode.
+   *
+   * @param {Object} data - Node data
+   * @param {string} data.sha - The commit SHA (40 hex characters). Required.
+   * @param {string} data.message - The commit message/payload. Required.
+   * @param {string} [data.author] - The commit author name. Optional.
+   * @param {string} [data.date] - The commit date string. Optional.
+   * @param {string[]} [data.parents=[]] - Array of parent commit SHAs. Defaults to empty array.
+   * @throws {Error} If sha is missing or not a string
+   * @throws {Error} If message is missing or not a string
+   * @throws {Error} If parents is not an array
+   */
+  constructor({ sha, message, author, date, parents = [] }) {
+    if (!sha || typeof sha !== 'string') {
+      throw new Error('GraphNode requires a valid sha string');
+    }
+    if (!message || typeof message !== 'string') {
+      throw new Error('GraphNode requires a valid message string');
+    }
+    if (!Array.isArray(parents)) {
+      throw new Error('GraphNode parents must be an array');
+    }
+
+    this.sha = sha;
+    this.message = message;
+    this.author = author;
+    this.date = date;
+    this.parents = Object.freeze([...parents]);
+    Object.freeze(this);
+  }
+}

package/src/domain/errors/EmptyMessageError.js

@@ -0,0 +1,47 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Error thrown when a message is empty or contains only whitespace.
+ *
+ * This error indicates that an operation received an empty message
+ * where content was required.
+ *
+ * @class EmptyMessageError
+ * @extends IndexError
+ *
+ * @property {string} name - The error name ('EmptyMessageError')
+ * @property {string} code - Error code ('EMPTY_MESSAGE')
+ * @property {string} operation - The operation that failed due to empty message
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * if (!message || message.trim() === '') {
+ *   throw new EmptyMessageError('Message cannot be empty', {
+ *     operation: 'createNode',
+ *     context: { nodeType: 'commit' }
+ *   });
+ * }
+ */
+export default class EmptyMessageError extends IndexError {
+  /**
+   * Creates a new EmptyMessageError.
+   *
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.operation] - The operation that failed
+   * @param {Object} [options.context={}] - Additional context for debugging
+   */
+  constructor(message, options = {}) {
+    const context = {
+      ...options.context,
+      operation: options.operation,
+    };
+
+    super(message, {
+      code: 'EMPTY_MESSAGE',
+      context,
+    });
+
+    this.operation = options.operation;
+  }
+}

package/src/domain/errors/ForkError.js

@@ -0,0 +1,30 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for graph fork operations.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_FORK_INVALID_ARGS` | Required fork parameters are missing or invalid |
+ * | `E_FORK_WRITER_NOT_FOUND` | The specified writer does not exist |
+ * | `E_FORK_PATCH_NOT_FOUND` | The specified patch SHA does not exist |
+ * | `E_FORK_PATCH_NOT_IN_CHAIN` | The patch SHA is not in the writer's chain |
+ * | `E_FORK_NAME_INVALID` | The fork graph name is invalid |
+ * | `E_FORK_WRITER_ID_INVALID` | The fork writer ID is invalid |
+ * | `E_FORK_ALREADY_EXISTS` | A graph with the fork name already exists |
+ * | `FORK_ERROR` | Generic/default fork error |
+ *
+ * @class ForkError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'ForkError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Object} context - Serializable context object with error details
+ */
+export default class ForkError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'FORK_ERROR', options);
+  }
+}

package/src/domain/errors/IndexError.js

@@ -0,0 +1,23 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Base error class for bitmap index operations.
+ *
+ * @class IndexError
+ * @extends WarpError
+ *
+ * @property {string} name - The error name ('IndexError')
+ * @property {string} code - Error code for programmatic handling (default: 'INDEX_ERROR')
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * throw new IndexError('Failed to process index', {
+ *   code: 'CUSTOM_ERROR',
+ *   context: { operation: 'merge', shardCount: 5 }
+ * });
+ */
+export default class IndexError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'INDEX_ERROR', options);
+  }
+}

package/src/domain/errors/OperationAbortedError.js

@@ -0,0 +1,22 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for aborted operations.
+ *
+ * @class OperationAbortedError
+ * @extends WarpError
+ *
+ * @property {string} name - The error name ('OperationAbortedError')
+ * @property {string} code - Error code for programmatic handling (default: 'OPERATION_ABORTED')
+ * @property {string} operation - The name of the operation that was aborted
+ * @property {string} reason - The reason the operation was aborted
+ * @property {Object} context - Serializable context object for debugging
+ */
+export default class OperationAbortedError extends WarpError {
+  constructor(operation, options = {}) {
+    const reason = options.reason || 'Operation was aborted';
+    super(`Operation '${operation}' aborted: ${reason}`, 'OPERATION_ABORTED', options);
+    this.operation = operation;
+    this.reason = reason;
+  }
+}

package/src/domain/errors/QueryError.js

@@ -0,0 +1,39 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for query builder and graph query operations.
+ *
+ * QueryError is thrown when a query operation fails due to invalid input,
+ * missing state, or constraint violations. It provides structured error
+ * information via error codes and context objects for programmatic handling.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_NO_STATE` | No cached state available; call `materialize()` first |
+ * | `E_STALE_STATE` | Cached state is outdated; call `materialize()` to refresh |
+ * | `E_QUERY_MATCH_TYPE` | Invalid type passed to `match()` (expected string) |
+ * | `E_QUERY_WHERE_TYPE` | Invalid type passed to `where()` (expected function or object) |
+ * | `E_QUERY_WHERE_VALUE` | Non-primitive value in where() object shorthand |
+ * | `E_QUERY_LABEL_TYPE` | Invalid type for edge label (expected string) |
+ * | `E_QUERY_DEPTH_TYPE` | Invalid depth value (expected non-negative integer or [min, max] array) |
+ * | `E_QUERY_DEPTH_RANGE` | Invalid depth range (min > max) |
+ * | `E_QUERY_SELECT_TYPE` | Invalid type passed to `select()` (expected array) |
+ * | `E_QUERY_SELECT_FIELD` | Unknown field name in select() |
+ * | `E_QUERY_AGGREGATE_TYPE` | Invalid type passed to `aggregate()` |
+ * | `E_QUERY_AGGREGATE_TERMINAL` | Method called after aggregate() which is terminal |
+ * | `QUERY_ERROR` | Generic/default query error |
+ *
+ * @class QueryError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'QueryError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Object} context - Serializable context object with error details
+ */
+export default class QueryError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'QUERY_ERROR', options);
+  }
+}

package/src/domain/errors/SchemaUnsupportedError.js

@@ -0,0 +1,17 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error thrown when a patch contains operations unsupported by the current schema version.
+ *
+ * @class SchemaUnsupportedError
+ * @extends WarpError
+ *
+ * @property {string} name - The error name ('SchemaUnsupportedError')
+ * @property {string} code - Error code ('E_SCHEMA_UNSUPPORTED')
+ * @property {Object} context - Serializable context object for debugging
+ */
+export default class SchemaUnsupportedError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'E_SCHEMA_UNSUPPORTED', options);
+  }
+}

package/src/domain/errors/ShardCorruptionError.js

@@ -0,0 +1,56 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Error thrown when shard data is corrupted or invalid.
+ *
+ * This error indicates that a shard file contains invalid or corrupted data,
+ * such as invalid checksums, unsupported versions, or malformed content.
+ *
+ * @class ShardCorruptionError
+ * @extends IndexError
+ *
+ * @property {string} name - The error name ('ShardCorruptionError')
+ * @property {string} code - Error code ('SHARD_CORRUPTION_ERROR')
+ * @property {string} shardPath - Path to the corrupted shard file
+ * @property {string} oid - Object ID associated with the shard
+ * @property {string} reason - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * if (!validateChecksum(data)) {
+ *   throw new ShardCorruptionError('Shard checksum mismatch', {
+ *     shardPath: '/path/to/shard',
+ *     oid: 'abc123',
+ *     reason: 'invalid_checksum'
+ *   });
+ * }
+ */
+export default class ShardCorruptionError extends IndexError {
+  /**
+   * Creates a new ShardCorruptionError.
+   *
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.shardPath] - Path to the corrupted shard file
+   * @param {string} [options.oid] - Object ID associated with the shard
+   * @param {string} [options.reason] - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
+   * @param {Object} [options.context={}] - Additional context for debugging
+   */
+  constructor(message, options = {}) {
+    const context = {
+      ...options.context,
+      shardPath: options.shardPath,
+      oid: options.oid,
+      reason: options.reason,
+    };
+
+    super(message, {
+      code: 'SHARD_CORRUPTION_ERROR',
+      context,
+    });
+
+    this.shardPath = options.shardPath;
+    this.oid = options.oid;
+    this.reason = options.reason;
+  }
+}

package/src/domain/errors/ShardLoadError.js

@@ -0,0 +1,57 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Error thrown when a shard fails to load.
+ *
+ * This error indicates that a shard file could not be read or parsed,
+ * typically due to I/O errors, missing files, or permission issues.
+ *
+ * @class ShardLoadError
+ * @extends IndexError
+ *
+ * @property {string} name - The error name ('ShardLoadError')
+ * @property {string} code - Error code ('SHARD_LOAD_ERROR')
+ * @property {string} shardPath - Path to the shard file that failed to load
+ * @property {string} oid - Object ID associated with the shard
+ * @property {Error} cause - The original error that caused the load failure
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * try {
+ *   await loadShard(path);
+ * } catch (err) {
+ *   throw new ShardLoadError('Failed to load shard', {
+ *     shardPath: '/path/to/shard',
+ *     oid: 'abc123',
+ *     cause: err
+ *   });
+ * }
+ */
+export default class ShardLoadError extends IndexError {
+  /**
+   * Creates a new ShardLoadError.
+   *
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.shardPath] - Path to the shard file
+   * @param {string} [options.oid] - Object ID associated with the shard
+   * @param {Error} [options.cause] - The original error that caused the failure
+   * @param {Object} [options.context={}] - Additional context for debugging
+   */
+  constructor(message, options = {}) {
+    const context = {
+      ...options.context,
+      shardPath: options.shardPath,
+      oid: options.oid,
+    };
+
+    super(message, {
+      code: 'SHARD_LOAD_ERROR',
+      context,
+    });
+
+    this.shardPath = options.shardPath;
+    this.oid = options.oid;
+    this.cause = options.cause;
+  }
+}

package/src/domain/errors/ShardValidationError.js

@@ -0,0 +1,61 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Error thrown when shard validation fails.
+ *
+ * This error indicates that a shard file failed validation checks,
+ * where expected values do not match actual values for specific fields.
+ *
+ * @class ShardValidationError
+ * @extends IndexError
+ *
+ * @property {string} name - The error name ('ShardValidationError')
+ * @property {string} code - Error code ('SHARD_VALIDATION_ERROR')
+ * @property {string} shardPath - Path to the shard file that failed validation
+ * @property {*} expected - The expected value for the field
+ * @property {*} actual - The actual value found in the shard
+ * @property {string} field - The field that failed validation (e.g., 'checksum', 'version')
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * if (shard.version !== EXPECTED_VERSION) {
+ *   throw new ShardValidationError('Shard version mismatch', {
+ *     shardPath: '/path/to/shard',
+ *     expected: EXPECTED_VERSION,
+ *     actual: shard.version,
+ *     field: 'version'
+ *   });
+ * }
+ */
+export default class ShardValidationError extends IndexError {
+  /**
+   * Creates a new ShardValidationError.
+   *
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.shardPath] - Path to the shard file
+   * @param {*} [options.expected] - The expected value
+   * @param {*} [options.actual] - The actual value found
+   * @param {string} [options.field] - The field that failed validation (e.g., 'checksum', 'version')
+   * @param {Object} [options.context={}] - Additional context for debugging
+   */
+  constructor(message, options = {}) {
+    const context = {
+      ...options.context,
+      shardPath: options.shardPath,
+      expected: options.expected,
+      actual: options.actual,
+      field: options.field,
+    };
+
+    super(message, {
+      code: 'SHARD_VALIDATION_ERROR',
+      context,
+    });
+
+    this.shardPath = options.shardPath;
+    this.expected = options.expected;
+    this.actual = options.actual;
+    this.field = options.field;
+  }
+}