@git-stunts/git-warp 10.1.1

package/src/domain/utils/cancellation.js

@@ -0,0 +1,33 @@
+/**
+ * Cancellation utilities for async operations.
+ *
+ * @module domain/utils/cancellation
+ */
+
+import OperationAbortedError from '../errors/OperationAbortedError.js';
+
+/**
+ * Checks if an abort signal has been aborted and throws if so.
+ *
+ * @param {AbortSignal} [signal] - The abort signal to check
+ * @param {string} [operation] - Name of the operation being checked
+ * @throws {OperationAbortedError} If signal is aborted
+ */
+export function checkAborted(signal, operation) {
+  if (signal?.aborted) {
+    throw new OperationAbortedError(operation || 'unknown', { context: { operation } });
+  }
+}
+
+/**
+ * Creates an AbortSignal that will abort after the specified timeout.
+ *
+ * Note: This signal cannot be manually cancelled. If callers need early
+ * cancellation, they should use AbortController directly.
+ *
+ * @param {number} ms - Timeout in milliseconds
+ * @returns {AbortSignal} The abort signal
+ */
+export function createTimeoutSignal(ms) {
+  return AbortSignal.timeout(ms);
+}

package/src/domain/utils/canonicalStringify.js

@@ -0,0 +1,42 @@
+/**
+ * Recursively stringifies a value with sorted object keys for deterministic output.
+ * Used for computing checksums that must match across builders and readers.
+ *
+ * Matches JSON.stringify semantics:
+ * - Top-level undefined returns "null"
+ * - Array elements that are undefined/function/symbol become "null"
+ * - Object properties with undefined/function/symbol values are omitted
+ *
+ * @param {*} value - Any JSON-serializable value
+ * @returns {string} Canonical JSON string with sorted keys
+ */
+export function canonicalStringify(value) {
+  if (value === undefined) {
+    return 'null';
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    // Map elements: undefined/function/symbol -> "null", others recurse
+    const elements = value.map(el => {
+      if (el === undefined || typeof el === 'function' || typeof el === 'symbol') {
+        return 'null';
+      }
+      return canonicalStringify(el);
+    });
+    return `[${elements.join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    // Filter out keys with undefined/function/symbol values, then sort
+    const keys = Object.keys(value)
+      .filter(k => {
+        const v = value[k];
+        return v !== undefined && typeof v !== 'function' && typeof v !== 'symbol';
+      })
+      .sort();
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(value[k])}`);
+    return `{${pairs.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/domain/utils/defaultClock.js

@@ -0,0 +1,20 @@
+/**
+ * Default clock implementation for domain services.
+ *
+ * Uses standard globalThis.performance.now() for high-resolution timing
+ * and Date for wall-clock timestamps, avoiding concrete adapter imports.
+ *
+ * @module domain/utils/defaultClock
+ */
+
+/** @type {import('../../ports/ClockPort.js').default} */
+const defaultClock = {
+  now() {
+    return performance.now();
+  },
+  timestamp() {
+    return new Date().toISOString();
+  },
+};
+
+export default defaultClock;

package/src/domain/utils/defaultCodec.js

@@ -0,0 +1,51 @@
+/**
+ * Default codec implementation for domain services.
+ *
+ * Provides canonical CBOR encoding/decoding using cbor-x directly,
+ * avoiding concrete adapter imports from the infrastructure layer.
+ * This follows the same pattern as defaultClock.js.
+ *
+ * Keys are recursively sorted before encoding for deterministic output,
+ * which is critical for content-addressed storage (Git SHA matching).
+ *
+ * @module domain/utils/defaultCodec
+ */
+
+import { Encoder, decode as cborDecode } from 'cbor-x';
+
+const encoder = new Encoder({
+  useRecords: false,
+  mapsAsObjects: true,
+});
+
+function sortKeys(value) {
+  if (value === null || value === undefined) { return value; }
+  if (Array.isArray(value)) { return value.map(sortKeys); }
+  if (value instanceof Map) {
+    const sorted = {};
+    for (const key of Array.from(value.keys()).sort()) {
+      sorted[key] = sortKeys(value.get(key));
+    }
+    return sorted;
+  }
+  if (typeof value === 'object' && (value.constructor === Object || value.constructor === undefined)) {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/** @type {import('../../ports/CodecPort.js').default} */
+const defaultCodec = {
+  encode(data) {
+    return encoder.encode(sortKeys(data));
+  },
+  decode(buffer) {
+    return cborDecode(buffer);
+  },
+};
+
+export default defaultCodec;

package/src/domain/utils/nullLogger.js

@@ -0,0 +1,21 @@
+/**
+ * Null-object logger for use as a default when no logger is provided.
+ *
+ * All methods are no-ops. This keeps the domain layer free of
+ * adapter dependencies by providing an inline null object.
+ *
+ * @module domain/utils/nullLogger
+ */
+
+/** @type {import('../../ports/LoggerPort.js').default} */
+const nullLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+  child() {
+    return nullLogger;
+  },
+};
+
+export default nullLogger;

package/src/domain/utils/roaring.js

@@ -0,0 +1,181 @@
+/**
+ * Lazy-loading wrapper for the roaring-wasm/roaring native bitmap library.
+ *
+ * This module provides deferred loading of the `roaring` npm package to avoid
+ * incurring the startup cost of loading native C++ bindings until they are
+ * actually needed. The roaring package provides highly efficient compressed
+ * bitmap data structures used by the bitmap index system for O(1) neighbor lookups.
+ *
+ * ## Why Lazy Loading?
+ *
+ * The `roaring` package includes native C++ bindings that can take 50-100ms to
+ * initialize on cold start. By deferring the load until first use,
+ * applications that don't use bitmap indexes avoid this overhead entirely.
+ *
+ * ## Module Caching
+ *
+ * Once loaded, the module reference is cached in `roaringModule` and reused
+ * for all subsequent calls. Similarly, native availability is cached after
+ * the first check to avoid repeated introspection.
+ *
+ * @module roaring
+ * @see BitmapIndexBuilder - Primary consumer of roaring bitmaps
+ * @see StreamingBitmapIndexBuilder - Memory-bounded variant
+ */
+
+/**
+ * Sentinel indicating availability has not been checked yet.
+ * @const {symbol}
+ * @private
+ */
+const NOT_CHECKED = Symbol('NOT_CHECKED');
+
+/**
+ * Cached reference to the loaded roaring module.
+ * @type {Object|null}
+ * @private
+ */
+let roaringModule = null;
+
+/**
+ * Cached result of native availability check.
+ * `NOT_CHECKED` means not yet checked, `null` means indeterminate.
+ * @type {boolean|symbol|null}
+ * @private
+ */
+let nativeAvailability = NOT_CHECKED;
+
+/**
+ * Lazily loads and caches the roaring module.
+ *
+ * Uses a top-level-await-friendly pattern with dynamic import.
+ * The module is cached after first load.
+ *
+ * @returns {Object} The roaring module exports
+ * @throws {Error} If the roaring package is not installed or fails to load
+ * @private
+ */
+function loadRoaring() {
+  if (!roaringModule) {
+    throw new Error('Roaring module not loaded. Call initRoaring() first or ensure top-level await import completed.');
+  }
+  return roaringModule;
+}
+
+/**
+ * Initializes the roaring module. Must be called before getRoaringBitmap32().
+ * This is called automatically via top-level await when the module is imported,
+ * but can also be called manually with a pre-loaded module for testing.
+ *
+ * @param {Object} [mod] - Pre-loaded roaring module (for testing/DI)
+ * @returns {Promise<void>}
+ */
+export async function initRoaring(mod) {
+  if (mod) {
+    roaringModule = mod;
+    return;
+  }
+  if (!roaringModule) {
+    roaringModule = await import('roaring');
+    // Handle both ESM default export and CJS module.exports
+    if (roaringModule.default && roaringModule.default.RoaringBitmap32) {
+      roaringModule = roaringModule.default;
+    }
+  }
+}
+
+// Auto-initialize on module load (top-level await)
+try {
+  await initRoaring();
+} catch {
+  // Roaring may not be installed; functions will throw on use
+}
+
+/**
+ * Returns the RoaringBitmap32 class from the roaring library.
+ *
+ * RoaringBitmap32 is a compressed bitmap implementation that provides
+ * efficient set operations (union, intersection, difference) on large
+ * sets of 32-bit integers. It's used by the bitmap index system to
+ * store edge adjacency lists in a highly compressed format.
+ *
+ * @returns {typeof import('roaring').RoaringBitmap32} The RoaringBitmap32 constructor
+ * @throws {Error} If the roaring package is not installed
+ *
+ * @example
+ * const RoaringBitmap32 = getRoaringBitmap32();
+ * const bitmap = new RoaringBitmap32([1, 2, 3, 100, 1000]);
+ * bitmap.has(100); // true
+ * bitmap.size; // 5
+ *
+ * @example
+ * // Set operations
+ * const a = new RoaringBitmap32([1, 2, 3]);
+ * const b = new RoaringBitmap32([2, 3, 4]);
+ * const union = RoaringBitmap32.or(a, b); // [1, 2, 3, 4]
+ * const intersection = RoaringBitmap32.and(a, b); // [2, 3]
+ */
+export function getRoaringBitmap32() {
+  return loadRoaring().RoaringBitmap32;
+}
+
+/**
+ * Checks whether the native C++ roaring implementation is available.
+ *
+ * The `roaring` package can operate in two modes:
+ * - **Native mode**: Uses prebuilt C++ bindings for maximum performance
+ * - **WASM fallback**: Uses WebAssembly when native bindings aren't available
+ *
+ * This function checks which mode is active by introspecting the loaded
+ * module. The result is cached after the first call.
+ *
+ * @returns {boolean|null} `true` if native bindings are installed,
+ *   `false` if using WASM fallback or if loading failed,
+ *   `null` if the installation status could not be determined
+ *
+ * @example
+ * if (getNativeRoaringAvailable()) {
+ *   console.log('Using native roaring bindings (fastest)');
+ * } else if (getNativeRoaringAvailable() === false) {
+ *   console.log('Using WASM fallback (slower but portable)');
+ * } else {
+ *   console.log('Could not determine roaring installation type');
+ * }
+ *
+ * @example
+ * // Useful for diagnostics and performance tuning
+ * const diagnostics = {
+ *   roaringNative: getNativeRoaringAvailable(),
+ *   // ... other system info
+ * };
+ */
+export function getNativeRoaringAvailable() {
+  if (nativeAvailability !== NOT_CHECKED) {
+    return nativeAvailability;
+  }
+
+  try {
+    const roaring = loadRoaring();
+    const { RoaringBitmap32 } = roaring;
+
+    // Try the method-based API first (roaring >= 2.x)
+    if (typeof RoaringBitmap32.isNativelyInstalled === 'function') {
+      nativeAvailability = RoaringBitmap32.isNativelyInstalled();
+      return nativeAvailability;
+    }
+
+    // Fall back to property-based API (roaring 1.x)
+    if (roaring.isNativelyInstalled !== undefined) {
+      nativeAvailability = roaring.isNativelyInstalled;
+      return nativeAvailability;
+    }
+
+    // Could not determine - leave as null (indeterminate)
+    nativeAvailability = null;
+    return nativeAvailability;
+  } catch {
+    // Loading failed entirely - definitely not available
+    nativeAvailability = false;
+    return nativeAvailability;
+  }
+}

package/src/domain/utils/shardVersion.js

@@ -0,0 +1,9 @@
+/**
+ * Shared shard format version constant.
+ * Used by BitmapIndexBuilder, StreamingBitmapIndexBuilder, and BitmapIndexReader.
+ *
+ * Increment when changing the shard structure to ensure reader/writer compatibility.
+ *
+ * @const {number}
+ */
+export const SHARD_VERSION = 2;

package/src/domain/warp/PatchSession.js

@@ -0,0 +1,217 @@
+/**
+ * PatchSession - Fluent patch builder with CAS-safe commit.
+ *
+ * A PatchSession is created by Writer.beginPatch() and provides a fluent API
+ * for building graph mutations. The commit uses compare-and-swap semantics
+ * to prevent concurrent forks of the writer chain.
+ *
+ * @module domain/warp/PatchSession
+ * @see WARP Writer Spec v1
+ */
+
+import { buildWriterRef } from '../utils/RefLayout.js';
+import WriterError from '../errors/WriterError.js';
+
+/**
+ * Fluent patch session for building and committing graph mutations.
+ */
+export class PatchSession {
+  /**
+   * Creates a new PatchSession.
+   *
+   * @param {Object} options
+   * @param {import('../services/PatchBuilderV2.js').PatchBuilderV2} options.builder - Internal builder
+   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
+   * @param {string} options.graphName - Graph namespace
+   * @param {string} options.writerId - Writer ID
+   * @param {string|null} options.expectedOldHead - Expected parent SHA for CAS
+   */
+  constructor({ builder, persistence, graphName, writerId, expectedOldHead }) {
+    /** @type {import('../services/PatchBuilderV2.js').PatchBuilderV2} */
+    this._builder = builder;
+
+    /** @type {import('../../ports/GraphPersistencePort.js').default} */
+    this._persistence = persistence;
+
+    /** @type {string} */
+    this._graphName = graphName;
+
+    /** @type {string} */
+    this._writerId = writerId;
+
+    /** @type {string|null} */
+    this._expectedOldHead = expectedOldHead;
+
+    /** @type {boolean} */
+    this._committed = false;
+  }
+
+  /**
+   * Gets the expected old head SHA (for testing).
+   * @returns {string|null}
+   * @internal
+   */
+  get _expectedOldHeadForTest() {
+    return this._expectedOldHead;
+  }
+
+  /**
+   * Adds a node to the graph.
+   *
+   * @param {string} nodeId - The node ID to add
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  addNode(nodeId) {
+    this._ensureNotCommitted();
+    this._builder.addNode(nodeId);
+    return this;
+  }
+
+  /**
+   * Removes a node from the graph.
+   *
+   * Uses observed dots from materialized state for OR-Set removal.
+   *
+   * @param {string} nodeId - The node ID to remove
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  removeNode(nodeId) {
+    this._ensureNotCommitted();
+    this._builder.removeNode(nodeId);
+    return this;
+  }
+
+  /**
+   * Adds an edge between two nodes.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  addEdge(from, to, label) {
+    this._ensureNotCommitted();
+    this._builder.addEdge(from, to, label);
+    return this;
+  }
+
+  /**
+   * Removes an edge between two nodes.
+   *
+   * Uses observed dots from materialized state for OR-Set removal.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  removeEdge(from, to, label) {
+    this._ensureNotCommitted();
+    this._builder.removeEdge(from, to, label);
+    return this;
+  }
+
+  /**
+   * Sets a property on a node.
+   *
+   * @param {string} nodeId - The node ID
+   * @param {string} key - Property key
+   * @param {*} value - Property value (must be JSON-serializable)
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  setProperty(nodeId, key, value) {
+    this._ensureNotCommitted();
+    this._builder.setProperty(nodeId, key, value);
+    return this;
+  }
+
+  /**
+   * Builds the PatchV2 object without committing.
+   *
+   * @returns {import('../types/WarpTypesV2.js').PatchV2} The constructed patch
+   */
+  build() {
+    return this._builder.build();
+  }
+
+  /**
+   * Commits the patch to the graph with CAS protection.
+   *
+   * @returns {Promise<string>} The commit SHA of the new patch
+   * @throws {WriterError} EMPTY_PATCH if no operations were added
+   * @throws {WriterError} WRITER_REF_ADVANCED if CAS fails (ref moved since beginPatch)
+   * @throws {WriterError} PERSIST_WRITE_FAILED if git operations fail
+   *
+   * @example
+   * const sha = await patch.commit();
+   */
+  async commit() {
+    this._ensureNotCommitted();
+
+    // Validate not empty
+    if (this._builder.ops.length === 0) {
+      throw new WriterError('EMPTY_PATCH', 'Cannot commit empty patch: no operations added');
+    }
+
+    const writerRef = buildWriterRef(this._graphName, this._writerId);
+
+    // Pre-commit CAS check: verify ref hasn't moved
+    const currentHead = await this._persistence.readRef(writerRef);
+    if (currentHead !== this._expectedOldHead) {
+      throw new WriterError(
+        'WRITER_REF_ADVANCED',
+        `Writer ref ${writerRef} has advanced since beginPatch(). ` +
+        `Expected ${this._expectedOldHead || '(none)'}, found ${currentHead || '(none)'}. ` +
+        `Call beginPatch() again to retry.`
+      );
+    }
+
+    try {
+      // Delegate to PatchBuilderV2.commit() which handles the git operations
+      const sha = await this._builder.commit();
+      this._committed = true;
+      return sha;
+    } catch (err) {
+      // Check if it's a concurrent commit error from PatchBuilderV2
+      if (err.message?.includes('Concurrent commit detected') ||
+          err.message?.includes('has advanced')) {
+        throw new WriterError(
+          'WRITER_REF_ADVANCED',
+          err.message,
+          err
+        );
+      }
+
+      // Wrap other errors
+      throw new WriterError(
+        'PERSIST_WRITE_FAILED',
+        `Failed to persist patch: ${err.message}`,
+        err
+      );
+    }
+  }
+
+  /**
+   * Gets the number of operations in this patch.
+   * @returns {number}
+   */
+  get opCount() {
+    return this._builder.ops.length;
+  }
+
+  /**
+   * Ensures the session hasn't been committed yet.
+   * @throws {Error} If already committed
+   * @private
+   */
+  _ensureNotCommitted() {
+    if (this._committed) {
+      throw new Error('PatchSession already committed. Call beginPatch() to create a new session.');
+    }
+  }
+}