@git-stunts/git-warp 10.1.1

package/src/domain/utils/LRUCache.js

@@ -0,0 +1,112 @@
+/**
+ * A simple LRU (Least Recently Used) cache implementation.
+ *
+ * Uses Map's insertion order to track access recency. When the cache
+ * exceeds maxSize, the oldest (least recently used) entry is evicted.
+ *
+ * @class LRUCache
+ * @template K, V
+ */
+class LRUCache {
+  /**
+   * Creates an LRU cache with the specified maximum size.
+   *
+   * @param {number} maxSize - Maximum number of entries to cache
+   * @throws {Error} If maxSize is not a positive integer
+   */
+  constructor(maxSize) {
+    if (!Number.isInteger(maxSize) || maxSize < 1) {
+      throw new Error('LRUCache maxSize must be a positive integer');
+    }
+    /** @type {number} */
+    this.maxSize = maxSize;
+    /** @type {Map<K, V>} */
+    this._cache = new Map();
+  }
+
+  /**
+   * Gets a value from the cache and marks it as recently used.
+   *
+   * @param {K} key - The key to look up
+   * @returns {V|undefined} The cached value, or undefined if not found
+   */
+  get(key) {
+    if (!this._cache.has(key)) {
+      return undefined;
+    }
+    // Move to end (most recently used) by deleting and re-inserting
+    const value = this._cache.get(key);
+    this._cache.delete(key);
+    this._cache.set(key, value);
+    return value;
+  }
+
+  /**
+   * Sets a value in the cache, evicting the oldest entry if at capacity.
+   *
+   * If the key already exists, it is updated and marked as recently used.
+   *
+   * @param {K} key - The key to set
+   * @param {V} value - The value to cache
+   * @returns {LRUCache} The cache instance for chaining
+   */
+  set(key, value) {
+    // If key exists, delete it first so it moves to the end
+    if (this._cache.has(key)) {
+      this._cache.delete(key);
+    }
+
+    // Add the new entry
+    this._cache.set(key, value);
+
+    // Evict oldest entry if over capacity
+    if (this._cache.size > this.maxSize) {
+      const oldestKey = this._cache.keys().next().value;
+      this._cache.delete(oldestKey);
+    }
+
+    return this;
+  }
+
+  /**
+   * Checks if a key exists in the cache.
+   *
+   * Note: This does NOT update the access order (use get() for that).
+   *
+   * @param {K} key - The key to check
+   * @returns {boolean} True if the key exists
+   */
+  has(key) {
+    return this._cache.has(key);
+  }
+
+  /**
+   * Deletes an entry from the cache.
+   *
+   * @param {K} key - The key to delete
+   * @returns {boolean} True if the entry was deleted, false if it didn't exist
+   */
+  delete(key) {
+    return this._cache.delete(key);
+  }
+
+  /**
+   * Clears all entries from the cache.
+   *
+   * @returns {void}
+   */
+  clear() {
+    this._cache.clear();
+  }
+
+  /**
+   * Gets the current number of entries in the cache.
+   *
+   * @returns {number} The number of cached entries
+   */
+  get size() {
+    return this._cache.size;
+  }
+}
+
+export default LRUCache;

package/src/domain/utils/MinHeap.js

@@ -0,0 +1,114 @@
+/**
+ * MinHeap/PriorityQueue implementation optimized for Dijkstra's algorithm.
+ * Items with lowest priority are extracted first.
+ *
+ * @class MinHeap
+ */
+class MinHeap {
+  /**
+   * Creates an empty MinHeap.
+   */
+  constructor() {
+    /** @type {Array<{item: *, priority: number}>} */
+    this.heap = [];
+  }
+
+  /**
+   * Insert an item with given priority.
+   *
+   * @param {*} item - The item to insert
+   * @param {number} priority - Priority value (lower = higher priority)
+   * @returns {void}
+   */
+  insert(item, priority) {
+    this.heap.push({ item, priority });
+    this._bubbleUp(this.heap.length - 1);
+  }
+
+  /**
+   * Extract and return the item with minimum priority.
+   *
+   * @returns {*} The item with lowest priority, or undefined if empty
+   */
+  extractMin() {
+    if (this.heap.length === 0) { return undefined; }
+    if (this.heap.length === 1) { return this.heap.pop().item; }
+
+    const min = this.heap[0];
+    this.heap[0] = this.heap.pop();
+    this._bubbleDown(0);
+    return min.item;
+  }
+
+  /**
+   * Check if the heap is empty.
+   *
+   * @returns {boolean} True if empty
+   */
+  isEmpty() {
+    return this.heap.length === 0;
+  }
+
+  /**
+   * Get the number of items in the heap.
+   *
+   * @returns {number} Number of items
+   */
+  size() {
+    return this.heap.length;
+  }
+
+  /**
+   * Peek at the minimum priority without removing the item.
+   *
+   * @returns {number} The minimum priority value, or Infinity if empty
+   */
+  peekPriority() {
+    return this.heap.length > 0 ? this.heap[0].priority : Infinity;
+  }
+
+  /**
+   * Restore heap property by bubbling up from index.
+   *
+   * @private
+   * @param {number} pos - Starting index
+   */
+  _bubbleUp(pos) {
+    let current = pos;
+    while (current > 0) {
+      const parentIndex = Math.floor((current - 1) / 2);
+      if (this.heap[parentIndex].priority <= this.heap[current].priority) { break; }
+      [this.heap[parentIndex], this.heap[current]] = [this.heap[current], this.heap[parentIndex]];
+      current = parentIndex;
+    }
+  }
+
+  /**
+   * Restore heap property by bubbling down from index.
+   *
+   * @private
+   * @param {number} pos - Starting index
+   */
+  _bubbleDown(pos) {
+    const {length} = this.heap;
+    let current = pos;
+    while (true) {
+      const leftChild = 2 * current + 1;
+      const rightChild = 2 * current + 2;
+      let smallest = current;
+
+      if (leftChild < length && this.heap[leftChild].priority < this.heap[smallest].priority) {
+        smallest = leftChild;
+      }
+      if (rightChild < length && this.heap[rightChild].priority < this.heap[smallest].priority) {
+        smallest = rightChild;
+      }
+      if (smallest === current) { break; }
+
+      [this.heap[current], this.heap[smallest]] = [this.heap[smallest], this.heap[current]];
+      current = smallest;
+    }
+  }
+}
+
+export default MinHeap;

package/src/domain/utils/RefLayout.js

@@ -0,0 +1,280 @@
+/**
+ * Ref layout constants and helpers for WARP (Write-Ahead Reference Protocol).
+ *
+ * Provides functions for building, parsing, and validating Git ref paths
+ * used by the WARP protocol. All refs live under the refs/warp/ namespace.
+ *
+ * Ref layout:
+ * - refs/warp/<graph>/writers/<writer_id>
+ * - refs/warp/<graph>/checkpoints/head
+ * - refs/warp/<graph>/coverage/head
+ *
+ * @module domain/utils/RefLayout
+ */
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+/**
+ * The prefix for all warp refs.
+ * @type {string}
+ */
+export const REF_PREFIX = 'refs/warp';
+
+/**
+ * Maximum length for a writer ID.
+ * @type {number}
+ */
+export const MAX_WRITER_ID_LENGTH = 64;
+
+/**
+ * Regex pattern for valid writer IDs.
+ * ASCII ref-safe characters: [A-Za-z0-9._-], 1-64 chars
+ * @type {RegExp}
+ */
+const WRITER_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Pattern to detect path traversal sequences.
+ * @type {RegExp}
+ */
+const PATH_TRAVERSAL_PATTERN = /\.\./;
+
+// -----------------------------------------------------------------------------
+// Validators
+// -----------------------------------------------------------------------------
+
+/**
+ * Validates a graph name and throws if invalid.
+ *
+ * Graph names must not contain:
+ * - Path traversal sequences (`../`)
+ * - Semicolons (`;`)
+ * - Spaces
+ * - Null bytes (`\0`)
+ * - Empty strings
+ *
+ * @param {string} name - The graph name to validate
+ * @throws {Error} If the graph name is invalid
+ * @returns {void}
+ *
+ * @example
+ * validateGraphName('events'); // OK
+ * validateGraphName('../etc'); // throws
+ * validateGraphName('my graph'); // throws
+ */
+export function validateGraphName(name) {
+  if (typeof name !== 'string') {
+    throw new Error(`Invalid graph name: expected string, got ${typeof name}`);
+  }
+
+  if (name.length === 0) {
+    throw new Error('Invalid graph name: cannot be empty');
+  }
+
+  if (PATH_TRAVERSAL_PATTERN.test(name)) {
+    throw new Error(`Invalid graph name: contains path traversal sequence '..': ${name}`);
+  }
+
+  if (name.includes(';')) {
+    throw new Error(`Invalid graph name: contains semicolon: ${name}`);
+  }
+
+  if (name.includes(' ')) {
+    throw new Error(`Invalid graph name: contains space: ${name}`);
+  }
+
+  if (name.includes('\0')) {
+    throw new Error(`Invalid graph name: contains null byte: ${name}`);
+  }
+}
+
+/**
+ * Validates a writer ID and throws if invalid.
+ *
+ * Writer IDs must:
+ * - Be ASCII ref-safe: only [A-Za-z0-9._-]
+ * - Be 1-64 characters long
+ * - Not contain `/`, `..`, whitespace, or NUL
+ *
+ * @param {string} id - The writer ID to validate
+ * @throws {Error} If the writer ID is invalid
+ * @returns {void}
+ *
+ * @example
+ * validateWriterId('node-1'); // OK
+ * validateWriterId('a/b'); // throws (contains /)
+ * validateWriterId('x'.repeat(65)); // throws (too long)
+ */
+export function validateWriterId(id) {
+  if (typeof id !== 'string') {
+    throw new Error(`Invalid writer ID: expected string, got ${typeof id}`);
+  }
+
+  if (id.length === 0) {
+    throw new Error('Invalid writer ID: cannot be empty');
+  }
+
+  if (id.length > MAX_WRITER_ID_LENGTH) {
+    throw new Error(
+      `Invalid writer ID: exceeds maximum length of ${MAX_WRITER_ID_LENGTH} characters: ${id.length}`
+    );
+  }
+
+  // Check for path traversal before pattern check for clearer error message
+  if (PATH_TRAVERSAL_PATTERN.test(id)) {
+    throw new Error(`Invalid writer ID: contains path traversal sequence '..': ${id}`);
+  }
+
+  // Check for forward slash before pattern check for clearer error message
+  if (id.includes('/')) {
+    throw new Error(`Invalid writer ID: contains forward slash: ${id}`);
+  }
+
+  // Check for null byte
+  if (id.includes('\0')) {
+    throw new Error(`Invalid writer ID: contains null byte: ${id}`);
+  }
+
+  // Check for whitespace (space, tab, newline, etc.)
+  if (/\s/.test(id)) {
+    throw new Error(`Invalid writer ID: contains whitespace: ${id}`);
+  }
+
+  // Check overall pattern for ref-safe characters
+  if (!WRITER_ID_PATTERN.test(id)) {
+    throw new Error(`Invalid writer ID: contains invalid characters (only [A-Za-z0-9._-] allowed): ${id}`);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Builders
+// -----------------------------------------------------------------------------
+
+/**
+ * Builds a writer ref path for the given graph and writer ID.
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} writerId - The writer's unique identifier
+ * @returns {string} The full ref path
+ * @throws {Error} If graphName or writerId is invalid
+ *
+ * @example
+ * buildWriterRef('events', 'node-1');
+ * // => 'refs/warp/events/writers/node-1'
+ */
+export function buildWriterRef(graphName, writerId) {
+  validateGraphName(graphName);
+  validateWriterId(writerId);
+  return `${REF_PREFIX}/${graphName}/writers/${writerId}`;
+}
+
+/**
+ * Builds the checkpoint head ref path for the given graph.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCheckpointRef('events');
+ * // => 'refs/warp/events/checkpoints/head'
+ */
+export function buildCheckpointRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/checkpoints/head`;
+}
+
+/**
+ * Builds the coverage head ref path for the given graph.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCoverageRef('events');
+ * // => 'refs/warp/events/coverage/head'
+ */
+export function buildCoverageRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/coverage/head`;
+}
+
+/**
+ * Builds the writers prefix path for the given graph.
+ * Useful for listing all writer refs under a graph.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The writers prefix path
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildWritersPrefix('events');
+ * // => 'refs/warp/events/writers/'
+ */
+export function buildWritersPrefix(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/writers/`;
+}
+
+// -----------------------------------------------------------------------------
+// Parsers
+// -----------------------------------------------------------------------------
+
+/**
+ * Parses and extracts the writer ID from a writer ref path.
+ *
+ * @param {string} refPath - The full ref path
+ * @returns {string|null} The writer ID, or null if the path is not a valid writer ref
+ *
+ * @example
+ * parseWriterIdFromRef('refs/warp/events/writers/alice');
+ * // => 'alice'
+ *
+ * parseWriterIdFromRef('refs/heads/main');
+ * // => null
+ */
+export function parseWriterIdFromRef(refPath) {
+  if (typeof refPath !== 'string') {
+    return null;
+  }
+
+  // Match pattern: refs/warp/<graph>/writers/<writerId>
+  const prefix = `${REF_PREFIX}/`;
+  if (!refPath.startsWith(prefix)) {
+    return null;
+  }
+
+  const rest = refPath.slice(prefix.length);
+  const parts = rest.split('/');
+
+  // We expect: <graph>/writers/<writerId>
+  // So parts should be: [graphName, 'writers', writerId]
+  if (parts.length < 3) {
+    return null;
+  }
+
+  // Find the 'writers' segment
+  const writersIndex = parts.indexOf('writers');
+  if (writersIndex === -1 || writersIndex === 0) {
+    return null;
+  }
+
+  // The writer ID is everything after 'writers'
+  // (should be exactly one segment for valid writer IDs)
+  if (writersIndex !== parts.length - 2) {
+    return null;
+  }
+
+  const writerId = parts[parts.length - 1];
+
+  // Validate the extracted writer ID
+  try {
+    validateWriterId(writerId);
+    return writerId;
+  } catch {
+    return null;
+  }
+}

package/src/domain/utils/WriterId.js

@@ -0,0 +1,205 @@
+/**
+ * WriterId - CRDT-safe writer identity generation and resolution.
+ *
+ * Provides utilities for generating stable, globally unique writer IDs
+ * that are safe for use in Git refs and CRDT version vectors.
+ *
+ * @module domain/utils/WriterId
+ * @see WARP WriterId Spec v1
+ */
+
+import { validateWriterId } from './RefLayout.js';
+
+/**
+ * Error class for WriterId operations.
+ */
+export class WriterIdError extends Error {
+  /**
+   * @param {string} code - Error code (e.g., 'CSPRNG_UNAVAILABLE')
+   * @param {string} message - Human-readable error message
+   * @param {Error} [cause] - Original error that caused this error
+   */
+  constructor(code, message, cause) {
+    super(message);
+    this.name = 'WriterIdError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+// Crockford base32 alphabet (lowercase), excluding i,l,o,u
+const CROCKFORD32 = '0123456789abcdefghjkmnpqrstvwxyz';
+
+/**
+ * Regex for canonical writer ID format.
+ * - Prefix: w_
+ * - Body: 26 chars Crockford Base32 (lowercase)
+ * - Total length: 28 chars
+ */
+const CANONICAL_RE = /^w_[0-9a-hjkmnp-tv-z]{26}$/;
+
+/**
+ * Validates that a writer ID is in canonical format.
+ *
+ * Canonical format:
+ * - Prefix: `w_`
+ * - Body: 26 chars Crockford Base32 (lowercase)
+ * - Total length: 28 chars
+ *
+ * @param {string} id - The writer ID to validate
+ * @returns {void}
+ * @throws {WriterIdError} If the ID is not canonical
+ *
+ * @example
+ * validateWriterIdCanonical('w_0123456789abcdefghjkmnpqrs'); // OK
+ * validateWriterIdCanonical('alice'); // throws INVALID_CANONICAL
+ */
+export function validateWriterIdCanonical(id) {
+  if (typeof id !== 'string') {
+    throw new WriterIdError('INVALID_TYPE', 'writerId must be a string');
+  }
+  if (!CANONICAL_RE.test(id)) {
+    throw new WriterIdError('INVALID_CANONICAL', `writerId is not canonical: ${id}`);
+  }
+}
+
+/**
+ * Default random bytes generator using Web Crypto API.
+ *
+ * @param {number} n - Number of bytes to generate
+ * @returns {Uint8Array} Random bytes
+ * @throws {WriterIdError} If no secure random generator is available
+ * @private
+ */
+function defaultRandomBytes(n) {
+  if (typeof globalThis?.crypto?.getRandomValues === 'function') {
+    const out = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+  }
+  throw new WriterIdError('CSPRNG_UNAVAILABLE', 'No secure random generator available');
+}
+
+/**
+ * Encodes bytes as Crockford Base32 (lowercase).
+ *
+ * @param {Uint8Array} bytes - Bytes to encode
+ * @returns {string} Base32-encoded string
+ * @private
+ */
+function crockfordBase32(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = '';
+
+  for (const b of bytes) {
+    value = (value << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      const idx = (value >>> (bits - 5)) & 31;
+      out += CROCKFORD32[idx];
+      bits -= 5;
+    }
+  }
+
+  if (bits > 0) {
+    const idx = (value << (5 - bits)) & 31;
+    out += CROCKFORD32[idx];
+  }
+
+  return out;
+}
+
+/**
+ * Generates a new canonical writer ID.
+ *
+ * Uses 128 bits of entropy (16 bytes) encoded as Crockford Base32.
+ * The result is prefixed with `w_` for a total length of 28 characters.
+ *
+ * @param {Object} [options]
+ * @param {(n: number) => Uint8Array} [options.randomBytes] - Custom RNG for testing
+ * @returns {string} A canonical writer ID (e.g., 'w_0123456789abcdefghjkmnpqrs')
+ * @throws {WriterIdError} If RNG is unavailable or returns wrong shape
+ *
+ * @example
+ * const id = generateWriterId();
+ * // => 'w_abc123...' (26 random chars after prefix)
+ *
+ * @example
+ * // With custom RNG for deterministic testing
+ * const id = generateWriterId({ randomBytes: mySeededRng });
+ */
+export function generateWriterId({ randomBytes } = {}) {
+  const rb = randomBytes ?? defaultRandomBytes;
+  const bytes = rb(16); // 128-bit
+
+  if (!(bytes instanceof Uint8Array) || bytes.length !== 16) {
+    throw new WriterIdError('CSPRNG_UNAVAILABLE', 'randomBytes() must return Uint8Array(16)');
+  }
+
+  return `w_${crockfordBase32(bytes).toLowerCase()}`;
+}
+
+/**
+ * Resolves a writer ID with repo-local persistence.
+ *
+ * Resolution order:
+ * 1. If `explicitWriterId` is provided, validate (ref-safe) and return it
+ * 2. Load from git config key `warp.writerId.<graphName>`
+ * 3. If missing or invalid, generate new canonical ID, persist, and return
+ *
+ * @param {Object} args
+ * @param {string} args.graphName - The graph name
+ * @param {string|undefined} args.explicitWriterId - Optional explicit writer ID
+ * @param {(key: string) => Promise<string|null>} args.configGet - Function to read git config
+ * @param {(key: string, value: string) => Promise<void>} args.configSet - Function to write git config
+ * @returns {Promise<string>} The resolved writer ID
+ * @throws {WriterIdError} If config operations fail
+ *
+ * @example
+ * const writerId = await resolveWriterId({
+ *   graphName: 'events',
+ *   explicitWriterId: undefined,
+ *   configGet: async (key) => git.config.get(key),
+ *   configSet: async (key, val) => git.config.set(key, val),
+ * });
+ */
+export async function resolveWriterId({ graphName, explicitWriterId, configGet, configSet }) {
+  const key = `warp.writerId.${graphName}`;
+
+  // 1) Explicit wins
+  if (explicitWriterId !== null && explicitWriterId !== undefined) {
+    validateWriterId(explicitWriterId); // ref-safe validation
+    return explicitWriterId;
+  }
+
+  // 2) Load from config
+  let existing;
+  try {
+    existing = await configGet(key);
+  } catch (e) {
+    throw new WriterIdError('CONFIG_READ_FAILED', `Failed to read git config key ${key}`, e);
+  }
+
+  if (existing) {
+    try {
+      validateWriterId(existing);
+      return existing;
+    } catch {
+      // Invalid format in config, fall through to regenerate
+    }
+  }
+
+  // 3) Generate & persist
+  const fresh = generateWriterId();
+  validateWriterId(fresh);           // Should always pass
+  validateWriterIdCanonical(fresh);  // Guaranteed canonical
+
+  try {
+    await configSet(key, fresh);
+  } catch (e) {
+    throw new WriterIdError('CONFIG_WRITE_FAILED', `Failed to persist writerId to git config key ${key}`, e);
+  }
+
+  return fresh;
+}