@git-stunts/git-warp 10.1.1

package/src/domain/errors/StorageError.js

@@ -0,0 +1,57 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Error thrown when a storage operation fails.
+ *
+ * This error indicates that a read or write operation to storage failed,
+ * typically due to I/O errors, permission issues, or storage unavailability.
+ *
+ * @class StorageError
+ * @extends IndexError
+ *
+ * @property {string} name - The error name ('StorageError')
+ * @property {string} code - Error code ('STORAGE_ERROR')
+ * @property {string} operation - The operation that failed ('read' or 'write')
+ * @property {string} oid - Object ID associated with the operation
+ * @property {Error} cause - The original error that caused the failure
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * try {
+ *   await storage.write(oid, data);
+ * } catch (err) {
+ *   throw new StorageError('Failed to write to storage', {
+ *     operation: 'write',
+ *     oid: 'abc123',
+ *     cause: err
+ *   });
+ * }
+ */
+export default class StorageError extends IndexError {
+  /**
+   * Creates a new StorageError.
+   *
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.operation] - The operation that failed ('read' or 'write')
+   * @param {string} [options.oid] - Object ID associated with the operation
+   * @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,
+      operation: options.operation,
+      oid: options.oid,
+    };
+
+    super(message, {
+      code: 'STORAGE_ERROR',
+      context,
+    });
+
+    this.operation = options.operation;
+    this.oid = options.oid;
+    this.cause = options.cause;
+  }
+}

package/src/domain/errors/SyncError.js

@@ -0,0 +1,30 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for sync transport and replication operations.
+ *
+ * SyncError is thrown when synchronization between WARP graph instances fails.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_SYNC_REMOTE_URL` | Invalid or unsupported remote URL |
+ * | `E_SYNC_NETWORK` | Network-level failure |
+ * | `E_SYNC_TIMEOUT` | Sync request exceeded timeout |
+ * | `E_SYNC_REMOTE` | Remote server returned a 5xx error |
+ * | `E_SYNC_PROTOCOL` | Protocol violation: 4xx, invalid JSON, or malformed response |
+ * | `SYNC_ERROR` | Generic/default sync error |
+ *
+ * @class SyncError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'SyncError' 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 SyncError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'SYNC_ERROR', options);
+  }
+}

package/src/domain/errors/TraversalError.js

@@ -0,0 +1,23 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for graph traversal operations.
+ *
+ * @class TraversalError
+ * @extends WarpError
+ *
+ * @property {string} name - The error name ('TraversalError')
+ * @property {string} code - Error code for programmatic handling (default: 'TRAVERSAL_ERROR')
+ * @property {Object} context - Serializable context object for debugging
+ *
+ * @example
+ * throw new TraversalError('Node not found in index', {
+ *   code: 'NODE_NOT_FOUND',
+ *   context: { sha: 'abc123', operation: 'bfs' }
+ * });
+ */
+export default class TraversalError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'TRAVERSAL_ERROR', options);
+  }
+}

package/src/domain/errors/WarpError.js

@@ -0,0 +1,31 @@
+/**
+ * Base error class for all WARP domain errors.
+ *
+ * Provides shared constructor logic: name (from constructor), code,
+ * context, and stack trace capture. Subclasses reduce to a one-line
+ * constructor calling super(message, defaultCode, options).
+ *
+ * @class WarpError
+ * @extends Error
+ *
+ * @property {string} name - Error name (set from constructor.name)
+ * @property {string} code - Machine-readable error code
+ * @property {Object} context - Serializable context for debugging
+ */
+export default class WarpError extends Error {
+  /**
+   * @param {string} message - Human-readable error message
+   * @param {string} defaultCode - Default error code if not overridden by options
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.code] - Override error code
+   * @param {Object} [options.context={}] - Serializable context for debugging
+   */
+  constructor(message, defaultCode, options = {}) {
+    super(message);
+    const opts = options || {};
+    this.name = this.constructor.name;
+    this.code = opts.code || defaultCode;
+    this.context = opts.context || {};
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+}

package/src/domain/errors/WormholeError.js

@@ -0,0 +1,28 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for wormhole compression operations.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_WORMHOLE_SHA_NOT_FOUND` | A specified SHA does not exist |
+ * | `E_WORMHOLE_INVALID_RANGE` | The from SHA is not an ancestor of to SHA |
+ * | `E_WORMHOLE_MULTI_WRITER` | The range spans multiple writers |
+ * | `E_WORMHOLE_EMPTY_RANGE` | No patches found in the specified range |
+ * | `E_WORMHOLE_NOT_PATCH` | A commit in the range is not a patch commit |
+ * | `WORMHOLE_ERROR` | Generic/default wormhole error |
+ *
+ * @class WormholeError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'WormholeError' 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 WormholeError extends WarpError {
+  constructor(message, options = {}) {
+    super(message, 'WORMHOLE_ERROR', options);
+  }
+}

package/src/domain/errors/WriterError.js

@@ -0,0 +1,39 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for Writer operations.
+ *
+ * Preserves the existing (code, message, cause) positional constructor
+ * signature used throughout PatchSession and PatchBuilderV2, while
+ * inheriting from WarpError for unified error hierarchy.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `EMPTY_PATCH` | Patch commit attempted with zero operations |
+ * | `WRITER_REF_ADVANCED` | Writer ref moved since beginPatch() |
+ * | `WRITER_CAS_CONFLICT` | Compare-and-swap failure during commit |
+ * | `PERSIST_WRITE_FAILED` | Git persistence operation failed |
+ * | `WRITER_ERROR` | Generic/default writer error |
+ *
+ * @class WriterError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'WriterError'
+ * @property {string} code - Machine-readable error code
+ * @property {Error} [cause] - Original error that caused this error
+ */
+export default class WriterError extends WarpError {
+  /**
+   * @param {string} code - Error code
+   * @param {string} message - Human-readable error message
+   * @param {Error} [cause] - Original error that caused this error
+   */
+  constructor(code, message, cause) {
+    super(message, 'WRITER_ERROR', { code });
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}

package/src/domain/errors/index.js

@@ -0,0 +1,21 @@
+/**
+ * Custom error classes for domain operations.
+ *
+ * @module domain/errors
+ */
+
+export { default as EmptyMessageError } from './EmptyMessageError.js';
+export { default as WarpError } from './WarpError.js';
+export { default as ForkError } from './ForkError.js';
+export { default as IndexError } from './IndexError.js';
+export { default as OperationAbortedError } from './OperationAbortedError.js';
+export { default as QueryError } from './QueryError.js';
+export { default as SyncError } from './SyncError.js';
+export { default as ShardCorruptionError } from './ShardCorruptionError.js';
+export { default as ShardLoadError } from './ShardLoadError.js';
+export { default as ShardValidationError } from './ShardValidationError.js';
+export { default as StorageError } from './StorageError.js';
+export { default as SchemaUnsupportedError } from './SchemaUnsupportedError.js';
+export { default as TraversalError } from './TraversalError.js';
+export { default as WriterError } from './WriterError.js';
+export { default as WormholeError } from './WormholeError.js';

package/src/domain/services/AnchorMessageCodec.js

@@ -0,0 +1,99 @@
+/**
+ * Anchor message encoding and decoding for WARP commit messages.
+ *
+ * Handles the 'anchor' message type which marks a merge point in the WARP
+ * DAG. See {@link module:domain/services/WarpMessageCodec} for the facade
+ * that re-exports all codec functions.
+ *
+ * @module domain/services/AnchorMessageCodec
+ */
+
+import { validateGraphName } from '../utils/RefLayout.js';
+import {
+  getCodec,
+  MESSAGE_TITLES,
+  TRAILER_KEYS,
+  validateSchema,
+} from './MessageCodecInternal.js';
+
+// -----------------------------------------------------------------------------
+// Encoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Encodes an anchor commit message.
+ *
+ * @param {Object} options - The anchor message options
+ * @param {string} options.graph - The graph name
+ * @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 = encodeAnchorMessage({ graph: 'events' });
+ */
+export function encodeAnchorMessage({ graph, schema = 2 }) {
+  // Validate inputs
+  validateGraphName(graph);
+  validateSchema(schema);
+
+  const codec = getCodec();
+  return codec.encode({
+    title: MESSAGE_TITLES.anchor,
+    trailers: {
+      [TRAILER_KEYS.kind]: 'anchor',
+      [TRAILER_KEYS.graph]: graph,
+      [TRAILER_KEYS.schema]: String(schema),
+    },
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Decoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Decodes an anchor commit message.
+ *
+ * @param {string} message - The raw commit message
+ * @returns {Object} The decoded anchor message
+ * @returns {string} return.kind - Always 'anchor'
+ * @returns {string} return.graph - The graph name
+ * @returns {number} return.schema - The schema version
+ * @throws {Error} If the message is not a valid anchor message
+ *
+ * @example
+ * const { kind, graph, schema } = decodeAnchorMessage(message);
+ */
+export function decodeAnchorMessage(message) {
+  const codec = getCodec();
+  const decoded = codec.decode(message);
+  const { trailers } = decoded;
+
+  // Validate kind discriminator
+  const kind = trailers[TRAILER_KEYS.kind];
+  if (kind !== 'anchor') {
+    throw new Error(`Invalid anchor message: eg-kind must be 'anchor', got '${kind}'`);
+  }
+
+  // Extract and validate required fields
+  const graph = trailers[TRAILER_KEYS.graph];
+  if (!graph) {
+    throw new Error('Invalid anchor message: missing required trailer eg-graph');
+  }
+
+  const schemaStr = trailers[TRAILER_KEYS.schema];
+  if (!schemaStr) {
+    throw new Error('Invalid anchor message: missing required trailer eg-schema');
+  }
+  const schema = parseInt(schemaStr, 10);
+  if (!Number.isInteger(schema) || schema < 1) {
+    throw new Error(`Invalid anchor message: eg-schema must be a positive integer, got '${schemaStr}'`);
+  }
+
+  return {
+    kind: 'anchor',
+    graph,
+    schema,
+  };
+}

package/src/domain/services/BitmapIndexBuilder.js

@@ -0,0 +1,225 @@
+import defaultCodec from '../utils/defaultCodec.js';
+import { getRoaringBitmap32, getNativeRoaringAvailable } from '../utils/roaring.js';
+import { canonicalStringify } from '../utils/canonicalStringify.js';
+import { SHARD_VERSION } from '../utils/shardVersion.js';
+
+// Re-export for backwards compatibility
+export { SHARD_VERSION };
+
+/**
+ * Computes a SHA-256 checksum of the given data.
+ * Uses canonical JSON stringification for deterministic output
+ * across different JavaScript engines.
+ *
+ * @param {Object} data - The data object to checksum
+ * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
+ * @returns {Promise<string|null>} Hex-encoded SHA-256 hash
+ */
+const computeChecksum = async (data, crypto) => {
+  if (!crypto) { return null; }
+  const json = canonicalStringify(data);
+  return await crypto.hash('sha256', json);
+};
+
+/** @type {boolean|null} Whether native Roaring bindings are available (null = unknown until first use) */
+export let NATIVE_ROARING_AVAILABLE = null;
+
+const ensureRoaringBitmap32 = () => {
+  const RoaringBitmap32 = getRoaringBitmap32();
+  if (NATIVE_ROARING_AVAILABLE === null) {
+    NATIVE_ROARING_AVAILABLE = getNativeRoaringAvailable();
+  }
+  return RoaringBitmap32;
+};
+
+/**
+ * Wraps data in a version/checksum envelope.
+ * @param {Object} data - The data to wrap
+ * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
+ * @returns {Promise<Object>} Envelope with version, checksum, and data
+ */
+const wrapShard = async (data, crypto) => ({
+  version: SHARD_VERSION,
+  checksum: await computeChecksum(data, crypto),
+  data,
+});
+
+/**
+ * Serializes a frontier Map into CBOR and JSON blobs in the given tree.
+ * @param {Map<string, string>} frontier - Writer→tip SHA map
+ * @param {Record<string, Buffer>} tree - Target tree to add entries to
+ * @param {import('../../ports/CodecPort.js').default} codec - Codec for CBOR serialization
+ */
+function serializeFrontierToTree(frontier, tree, codec) {
+  const sorted = {};
+  for (const key of Array.from(frontier.keys()).sort()) {
+    sorted[key] = frontier.get(key);
+  }
+  const envelope = { version: 1, writerCount: frontier.size, frontier: sorted };
+  tree['frontier.cbor'] = Buffer.from(codec.encode(envelope));
+  tree['frontier.json'] = Buffer.from(canonicalStringify(envelope));
+}
+
+/**
+ * Builder for constructing bitmap indexes in memory.
+ *
+ * This is a pure domain class with no infrastructure dependencies.
+ * Create an instance, add nodes and edges, then serialize to persist.
+ *
+ * Callers that persist the serialized output typically need
+ * BlobPort + TreePort + RefPort from the persistence layer.
+ *
+ * **Performance Note**: Uses Roaring Bitmaps for compression. Native bindings
+ * provide best performance. Check `NATIVE_ROARING_AVAILABLE` export if
+ * performance is critical.
+ *
+ * @example
+ * import BitmapIndexBuilder, { NATIVE_ROARING_AVAILABLE } from './BitmapIndexBuilder.js';
+ * if (NATIVE_ROARING_AVAILABLE === false) {
+ *   console.warn('Consider installing native Roaring bindings for better performance');
+ * }
+ * const builder = new BitmapIndexBuilder();
+ */
+export default class BitmapIndexBuilder {
+  /**
+   * Creates a new BitmapIndexBuilder instance.
+   *
+   * The builder tracks:
+   * - SHA to numeric ID mappings (for compact bitmap storage)
+   * - Forward edge bitmaps (parent → children)
+   * - Reverse edge bitmaps (child → parents)
+   *
+   * @param {Object} [options] - Configuration options
+   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for hashing
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+   */
+  constructor({ crypto, codec } = {}) {
+    /** @type {import('../../ports/CryptoPort.js').default} */
+    this._crypto = crypto;
+    /** @type {import('../../ports/CodecPort.js').default|undefined} */
+    this._codec = codec || defaultCodec;
+    /** @type {Map<string, number>} */
+    this.shaToId = new Map();
+    /** @type {string[]} */
+    this.idToSha = [];
+    /** @type {Map<string, RoaringBitmap32>} */
+    this.bitmaps = new Map();
+  }
+
+  /**
+   * Registers a node without adding edges.
+   * Useful for root nodes with no parents.
+   *
+   * @param {string} sha - The node's SHA
+   * @returns {number} The assigned numeric ID
+   */
+  registerNode(sha) {
+    return this._getOrCreateId(sha);
+  }
+
+  /**
+   * Adds a directed edge from source to target node.
+   *
+   * Updates both forward (src → tgt) and reverse (tgt → src) bitmaps.
+   *
+   * @param {string} srcSha - Source node SHA (parent)
+   * @param {string} tgtSha - Target node SHA (child)
+   * @returns {void}
+   */
+  addEdge(srcSha, tgtSha) {
+    const srcId = this._getOrCreateId(srcSha);
+    const tgtId = this._getOrCreateId(tgtSha);
+    this._addToBitmap({ sha: srcSha, id: tgtId, type: 'fwd' });
+    this._addToBitmap({ sha: tgtSha, id: srcId, type: 'rev' });
+  }
+
+  /**
+   * Serializes the index to a tree structure of buffers.
+   *
+   * Output structure (sharded by SHA prefix for lazy loading):
+   * - `meta_XX.json`: {version, checksum, data: {sha: id, ...}} for SHAs with prefix XX
+   * - `shards_fwd_XX.json`: {version, checksum, data: {sha: base64Bitmap, ...}} for forward edges
+   * - `shards_rev_XX.json`: {version, checksum, data: {sha: base64Bitmap, ...}} for reverse edges
+   *
+   * Each shard is wrapped in a version/checksum envelope for integrity verification.
+   *
+   * @param {Object} [options] - Serialization options
+   * @param {Map<string, string>} [options.frontier] - Writer→tip SHA map to include in the tree
+   * @returns {Promise<Record<string, Buffer>>} Map of path → serialized content
+   */
+  async serialize({ frontier } = {}) {
+    const tree = {};
+
+    // Serialize ID mappings (sharded by prefix)
+    const idShards = {};
+    for (const [sha, id] of this.shaToId) {
+      const prefix = sha.substring(0, 2);
+      if (!idShards[prefix]) {
+        idShards[prefix] = {};
+      }
+      idShards[prefix][sha] = id;
+    }
+    for (const [prefix, map] of Object.entries(idShards)) {
+      tree[`meta_${prefix}.json`] = Buffer.from(JSON.stringify(await wrapShard(map, this._crypto)));
+    }
+
+    // Serialize bitmaps (sharded by prefix, per-node within shard)
+    // Keys are constructed as '${type}_${sha}' by _addToBitmap (e.g., 'fwd_abc123', 'rev_def456')
+    const bitmapShards = { fwd: {}, rev: {} };
+    for (const [key, bitmap] of this.bitmaps) {
+      const [type, sha] = [key.substring(0, 3), key.substring(4)];
+      const prefix = sha.substring(0, 2);
+
+      if (!bitmapShards[type][prefix]) {
+        bitmapShards[type][prefix] = {};
+      }
+      // Encode bitmap as base64 for JSON storage
+      bitmapShards[type][prefix][sha] = bitmap.serialize(true).toString('base64');
+    }
+
+    for (const type of ['fwd', 'rev']) {
+      for (const [prefix, shardData] of Object.entries(bitmapShards[type])) {
+        tree[`shards_${type}_${prefix}.json`] = Buffer.from(JSON.stringify(await wrapShard(shardData, this._crypto)));
+      }
+    }
+
+    if (frontier) {
+      serializeFrontierToTree(frontier, tree, this._codec);
+    }
+
+    return tree;
+  }
+
+  /**
+   * Gets or creates a numeric ID for a SHA.
+   * @param {string} sha - The SHA to look up or register
+   * @returns {number} The numeric ID
+   * @private
+   */
+  _getOrCreateId(sha) {
+    if (this.shaToId.has(sha)) {
+      return this.shaToId.get(sha);
+    }
+    const id = this.idToSha.length;
+    this.idToSha.push(sha);
+    this.shaToId.set(sha, id);
+    return id;
+  }
+
+  /**
+   * Adds an ID to a node's bitmap.
+   * @param {Object} opts - Options
+   * @param {string} opts.sha - The SHA to use as key
+   * @param {number} opts.id - The ID to add to the bitmap
+   * @param {string} opts.type - 'fwd' or 'rev'
+   * @private
+   */
+  _addToBitmap({ sha, id, type }) {
+    const key = `${type}_${sha}`;
+    if (!this.bitmaps.has(key)) {
+      const RoaringBitmap32 = ensureRoaringBitmap32();
+      this.bitmaps.set(key, new RoaringBitmap32());
+    }
+    this.bitmaps.get(key).add(id);
+  }
+}