@git-stunts/git-warp 10.1.1

package/src/domain/services/GCPolicy.js

@@ -0,0 +1,122 @@
+/**
+ * GCPolicy - Garbage collection policy for WARP V5.
+ */
+
+import { orsetCompact } from '../crdt/ORSet.js';
+import { collectGCMetrics } from './GCMetrics.js';
+
+/**
+ * @typedef {Object} GCPolicy
+ * @property {boolean} enabled - Whether automatic GC is enabled (default: false)
+ * @property {number} tombstoneRatioThreshold - Ratio of tombstones that triggers GC (0.0-1.0)
+ * @property {number} entryCountThreshold - Total entries that triggers GC
+ * @property {number} minPatchesSinceCompaction - Minimum patches between GCs
+ * @property {number} maxTimeSinceCompaction - Maximum time (ms) between GCs
+ * @property {boolean} compactOnCheckpoint - Whether to auto-compact on checkpoint
+ */
+
+/**
+ * @typedef {Object} GCShouldRunResult
+ * @property {boolean} shouldRun - Whether GC should run
+ * @property {string[]} reasons - Reasons for running (or not)
+ */
+
+/**
+ * @typedef {Object} GCExecuteResult
+ * @property {number} nodesCompacted - Number of node entries compacted
+ * @property {number} edgesCompacted - Number of edge entries compacted
+ * @property {number} tombstonesRemoved - Total tombstones removed
+ * @property {number} durationMs - Time taken in milliseconds
+ */
+
+/**
+ * @typedef {Object} GCInputMetrics
+ * @property {number} tombstoneRatio - Current tombstone ratio
+ * @property {number} totalEntries - Total entries in state
+ * @property {number} patchesSinceCompaction - Patches applied since last GC
+ * @property {number} timeSinceCompaction - Time (ms) since last GC
+ */
+
+/** @type {Readonly<GCPolicy>} */
+export const DEFAULT_GC_POLICY = Object.freeze({
+  enabled: false, // Must opt-in to automatic GC
+  tombstoneRatioThreshold: 0.3, // 30% tombstones triggers GC
+  entryCountThreshold: 50000, // 50K entries triggers GC
+  minPatchesSinceCompaction: 1000, // Min patches between GCs
+  maxTimeSinceCompaction: 86400000, // 24 hours max between GCs
+  compactOnCheckpoint: true, // Auto-compact on checkpoint
+});
+
+/**
+ * Determines if GC should run based on metrics and policy.
+ * @param {GCInputMetrics} metrics
+ * @param {GCPolicy} policy
+ * @returns {GCShouldRunResult}
+ */
+export function shouldRunGC(metrics, policy) {
+  const reasons = [];
+
+  // Check tombstone ratio threshold
+  if (metrics.tombstoneRatio > policy.tombstoneRatioThreshold) {
+    reasons.push(
+      `Tombstone ratio ${(metrics.tombstoneRatio * 100).toFixed(1)}% exceeds threshold ${(policy.tombstoneRatioThreshold * 100).toFixed(1)}%`
+    );
+  }
+
+  // Check entry count threshold
+  if (metrics.totalEntries > policy.entryCountThreshold) {
+    reasons.push(
+      `Entry count ${metrics.totalEntries} exceeds threshold ${policy.entryCountThreshold}`
+    );
+  }
+
+  // Check patches since compaction
+  if (metrics.patchesSinceCompaction > policy.minPatchesSinceCompaction) {
+    reasons.push(
+      `Patches since compaction ${metrics.patchesSinceCompaction} exceeds minimum ${policy.minPatchesSinceCompaction}`
+    );
+  }
+
+  // Check time since compaction
+  if (metrics.timeSinceCompaction > policy.maxTimeSinceCompaction) {
+    reasons.push(
+      `Time since compaction ${metrics.timeSinceCompaction}ms exceeds maximum ${policy.maxTimeSinceCompaction}ms`
+    );
+  }
+
+  return {
+    shouldRun: reasons.length > 0,
+    reasons,
+  };
+}
+
+/**
+ * Executes GC on state. Only compacts tombstoned dots <= appliedVV.
+ * Mutates state in place.
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state - State to compact (mutated!)
+ * @param {import('../crdt/VersionVector.js').VersionVector} appliedVV - Version vector cutoff
+ * @returns {GCExecuteResult}
+ */
+export function executeGC(state, appliedVV) {
+  const startTime = performance.now();
+
+  // Collect metrics before compaction
+  const beforeMetrics = collectGCMetrics(state);
+
+  // Compact both ORSets
+  orsetCompact(state.nodeAlive, appliedVV);
+  orsetCompact(state.edgeAlive, appliedVV);
+
+  // Collect metrics after compaction
+  const afterMetrics = collectGCMetrics(state);
+
+  const endTime = performance.now();
+
+  return {
+    nodesCompacted: beforeMetrics.nodeEntries - afterMetrics.nodeEntries,
+    edgesCompacted: beforeMetrics.edgeEntries - afterMetrics.edgeEntries,
+    tombstonesRemoved: beforeMetrics.totalTombstones - afterMetrics.totalTombstones,
+    durationMs: endTime - startTime,
+  };
+}

package/src/domain/services/GitLogParser.js

@@ -0,0 +1,205 @@
+import GraphNode from '../entities/GraphNode.js';
+import { checkAborted } from '../utils/cancellation.js';
+
+/**
+ * NUL byte (0x00) - Delimits commit records in git log output.
+ *
+ * Git commit messages cannot contain NUL bytes - git rejects them at commit time.
+ * This makes NUL a perfectly safe delimiter that cannot appear in any field,
+ * eliminating the possibility of message injection attacks.
+ *
+ * The git log format produces records in this exact structure:
+ *
+ * ```
+ * <SHA>\n
+ * <author>\n
+ * <date>\n
+ * <parents (space-separated)>\n
+ * <message body (may contain newlines)>\x00
+ * ```
+ *
+ * Fields within each record are separated by newlines. The first 4 lines are
+ * fixed fields (SHA, author, date, parents), and all remaining content up to
+ * the NUL terminator is the message body.
+ *
+ * @see https://git-scm.com/docs/git-log (see -z option documentation)
+ * @const {string}
+ */
+export const RECORD_SEPARATOR = '\x00';
+
+/**
+ * Parser for git log output streams.
+ *
+ * Handles UTF-8 decoding, record splitting, and node instantiation as separate
+ * concerns. Designed as an injectable dependency for WarpGraph to enable
+ * testing and alternative implementations.
+ *
+ * **Binary-First Processing**: The parser works directly with binary data for
+ * performance. Buffer.indexOf(0) is faster than string indexOf('\0') because:
+ * - No UTF-8 decoding overhead during scanning
+ * - Native C++ implementation in Node.js Buffer
+ * - Byte-level comparison vs character-level
+ *
+ * UTF-8 decoding only happens once per complete record, not during scanning.
+ * This is especially beneficial for large commit histories where most of the
+ * data is being scanned to find record boundaries.
+ *
+ * **Log Format Contract**: Each record is NUL-terminated and contains fields
+ * separated by newlines:
+ * 1. SHA (40 hex chars)
+ * 2. Author name
+ * 3. Date string
+ * 4. Parent SHAs (space-separated, empty string for root commits)
+ * 5. Message body (may span multiple lines, everything until NUL terminator)
+ *
+ * **Why NUL delimiter?** Git commit messages cannot contain NUL bytes - git
+ * rejects them at commit time. This makes NUL a perfectly safe record delimiter
+ * that eliminates parsing ambiguity, unlike 0x1E which can theoretically appear
+ * in message content.
+ *
+ * @example
+ * // Basic usage
+ * const parser = new GitLogParser();
+ * for await (const node of parser.parse(stream)) {
+ *   console.log(node.sha, node.message);
+ * }
+ *
+ * @example
+ * // Inject into WarpGraph for testing
+ * const mockParser = { parse: async function*() { yield mockNode; } };
+ * const graph = new WarpGraph({ persistence, parser: mockParser });
+ */
+export default class GitLogParser {
+  /**
+   * Parses a stream of git log output and yields GraphNode instances.
+   *
+   * **Binary-first processing for performance**:
+   * - Accepts Buffer, Uint8Array, or string chunks
+   * - Finds NUL bytes (0x00) directly in binary using Buffer.indexOf(0)
+   * - Buffer.indexOf(0) is faster than string indexOf('\0') - native C++ vs JS
+   * - UTF-8 decoding only happens for complete records, not during scanning
+   *
+   * Handles:
+   * - UTF-8 sequences split across chunk boundaries (via binary accumulation)
+   * - Records terminated by NUL bytes (0x00)
+   * - Streaming without loading entire history into memory
+   * - Backwards compatibility with string chunks
+   * - Cancellation via AbortSignal
+   *
+   * @param {AsyncIterable<Buffer|Uint8Array|string>} stream - The git log output stream.
+   *   May yield Buffer, Uint8Array, or string chunks.
+   * @param {Object} [options] - Parse options
+   * @param {AbortSignal} [options.signal] - Optional abort signal for cancellation
+   * @yields {GraphNode} Parsed graph nodes. Invalid records are silently skipped.
+   * @throws {OperationAbortedError} If signal is aborted during parsing
+   *
+   * @example
+   * const stream = persistence.logNodesStream({ ref: 'main', limit: 100, format });
+   * for await (const node of parser.parse(stream)) {
+   *   console.log(node.sha);
+   * }
+   *
+   * @example
+   * // With cancellation support
+   * const controller = new AbortController();
+   * for await (const node of parser.parse(stream, { signal: controller.signal })) {
+   *   console.log(node.sha);
+   * }
+   */
+  async *parse(stream, { signal } = {}) {
+    let buffer = Buffer.alloc(0); // Binary buffer accumulator
+
+    for await (const chunk of stream) {
+      checkAborted(signal, 'GitLogParser.parse');
+
+      // Convert string chunks to Buffer, keep Buffer chunks as-is
+      const chunkBuffer =
+        typeof chunk === 'string'
+          ? Buffer.from(chunk, 'utf-8')
+          : Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(chunk); // Uint8Array
+
+      // Append to accumulator
+      buffer = Buffer.concat([buffer, chunkBuffer]);
+
+      // Find NUL bytes (0x00) in binary - faster than string indexOf
+      let nullIndex;
+      while ((nullIndex = buffer.indexOf(0)) !== -1) {
+        checkAborted(signal, 'GitLogParser.parse');
+
+        // Extract record bytes and decode to string
+        const recordBytes = buffer.subarray(0, nullIndex);
+        buffer = buffer.subarray(nullIndex + 1);
+
+        // Only decode UTF-8 for complete records
+        const block = recordBytes.toString('utf-8');
+        const node = this.parseNode(block);
+        if (node) {
+          yield node;
+        }
+      }
+    }
+
+    // Process any remaining data (final record without trailing NUL)
+    if (buffer.length > 0) {
+      const block = buffer.toString('utf-8');
+      if (block) {
+        const node = this.parseNode(block);
+        if (node) {
+          yield node;
+        }
+      }
+    }
+  }
+
+  /**
+   * Parses a single record block into a GraphNode.
+   *
+   * Expected format (fields separated by newlines):
+   * - Line 0: SHA (required, non-empty)
+   * - Line 1: Author name
+   * - Line 2: Date string
+   * - Line 3: Parent SHAs (space-separated, may be empty for root commits)
+   * - Lines 4+: Message body (preserved exactly, not trimmed)
+   *
+   * The block should not include the trailing NUL terminator - that is stripped
+   * by the parse() method before calling parseNode().
+   *
+   * @param {string} block - Raw block text (without trailing NUL terminator)
+   * @returns {GraphNode|null} Parsed node, or null if the block is malformed
+   *   or has an empty message (GraphNode requires non-empty message)
+   *
+   * @example
+   * const block = 'abc123\nAuthor\n2026-01-28\nparent1 parent2\nCommit message';
+   * const node = parser.parseNode(block);
+   * // node.sha === 'abc123'
+   * // node.parents === ['parent1', 'parent2']
+   */
+  parseNode(block) {
+    const lines = block.split('\n');
+    // Need at least 4 lines: SHA, author, date, parents
+    // Message (lines 4+) may be empty
+    if (lines.length < 4) {
+      return null;
+    }
+
+    const sha = lines[0];
+    if (!sha) {
+      return null;
+    }
+
+    const author = lines[1];
+    const date = lines[2];
+    const parents = lines[3] ? lines[3].split(' ').filter(Boolean) : [];
+    // Preserve message exactly as-is (may be empty, may have leading/trailing whitespace)
+    const message = lines.slice(4).join('\n');
+
+    // GraphNode requires non-empty message, return null for empty
+    if (!message) {
+      return null;
+    }
+
+    return new GraphNode({ sha, author, date, message, parents });
+  }
+}

package/src/domain/services/HealthCheckService.js

@@ -0,0 +1,246 @@
+import nullLogger from '../utils/nullLogger.js';
+import CachedValue from '../utils/CachedValue.js';
+
+/**
+ * Default TTL for health check cache in milliseconds.
+ * @const {number}
+ */
+const DEFAULT_CACHE_TTL_MS = 5000;
+
+/**
+ * Health status constants.
+ * @readonly
+ * @enum {string}
+ */
+export const HealthStatus = {
+  HEALTHY: 'healthy',
+  DEGRADED: 'degraded',
+  UNHEALTHY: 'unhealthy',
+};
+
+/**
+ * Service for performing health checks on the graph system.
+ *
+ * Follows hexagonal architecture by depending on ports, not adapters.
+ * Provides K8s-style probes (liveness vs readiness) and detailed component health.
+ *
+ * @example
+ * const healthService = new HealthCheckService({
+ *   persistence,
+ *   clock,
+ *   cacheTtlMs: 10000,
+ *   logger,
+ * });
+ *
+ * // K8s liveness probe - am I running?
+ * const alive = await healthService.isAlive();
+ *
+ * // K8s readiness probe - can I serve requests?
+ * const ready = await healthService.isReady();
+ *
+ * // Detailed health breakdown
+ * const health = await healthService.getHealth();
+ * console.log(health.status); // 'healthy' | 'degraded' | 'unhealthy'
+ */
+export default class HealthCheckService {
+  /**
+   * Creates a HealthCheckService instance.
+   * @param {Object} options
+   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Persistence port for repository checks
+   * @param {import('../../ports/ClockPort.js').default} options.clock - Clock port for timing operations
+   * @param {number} [options.cacheTtlMs=5000] - How long to cache health results in milliseconds
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging
+   */
+  constructor({ persistence, clock, cacheTtlMs = DEFAULT_CACHE_TTL_MS, logger = nullLogger }) {
+    this._persistence = persistence;
+    this._clock = clock;
+    this._logger = logger;
+
+    /** @type {import('./BitmapIndexReader.js').default|null} */
+    this._indexReader = null;
+
+    // Health check cache
+    this._healthCache = new CachedValue({
+      clock,
+      ttlMs: cacheTtlMs,
+      compute: () => this._computeHealth(),
+    });
+  }
+
+  /**
+   * Sets the index reader for index health checks.
+   * Call this when an index is loaded.
+   *
+   * @param {import('./BitmapIndexReader.js').default|null} reader - The index reader, or null to clear
+   * @returns {void}
+   */
+  setIndexReader(reader) {
+    this._indexReader = reader;
+    this._healthCache.invalidate();
+  }
+
+  /**
+   * K8s-style liveness probe: Is the service running?
+   *
+   * Returns true if the repository is accessible.
+   * A failed liveness check typically triggers a container restart.
+   *
+   * @returns {Promise<boolean>}
+   */
+  async isAlive() {
+    const health = await this.getHealth();
+    // Alive if repository is reachable (even if degraded)
+    return health.components.repository.status !== HealthStatus.UNHEALTHY;
+  }
+
+  /**
+   * K8s-style readiness probe: Can the service serve requests?
+   *
+   * Returns true if all critical components are healthy.
+   * A failed readiness check removes the pod from load balancer.
+   *
+   * @returns {Promise<boolean>}
+   */
+  async isReady() {
+    const health = await this.getHealth();
+    return health.status === HealthStatus.HEALTHY;
+  }
+
+  /**
+   * Gets detailed health information for all components.
+   *
+   * Results are cached for the configured TTL to prevent
+   * excessive health check calls under load.
+   *
+   * @returns {Promise<HealthResult>}
+   *
+   * @typedef {Object} HealthResult
+   * @property {'healthy'|'degraded'|'unhealthy'} status - Overall health status
+   * @property {Object} components - Component health breakdown
+   * @property {RepositoryHealth} components.repository - Repository health
+   * @property {IndexHealth} components.index - Index health
+   * @property {string} [cachedAt] - ISO timestamp if result is cached
+   *
+   * @typedef {Object} RepositoryHealth
+   * @property {'healthy'|'unhealthy'} status - Repository status
+   * @property {number} latencyMs - Ping latency in milliseconds
+   *
+   * @typedef {Object} IndexHealth
+   * @property {'healthy'|'degraded'|'unhealthy'} status - Index status
+   * @property {boolean} loaded - Whether an index is loaded
+   * @property {number} [shardCount] - Number of shards (if loaded)
+   */
+  async getHealth() {
+    const { value, cachedAt, fromCache } = await this._healthCache.getWithMetadata();
+
+    if (cachedAt) {
+      return { ...value, cachedAt };
+    }
+
+    // Log only for fresh computations
+    if (!fromCache) {
+      this._logger.debug('Health check completed', {
+        operation: 'getHealth',
+        status: value.status,
+        repositoryStatus: value.components.repository.status,
+        indexStatus: value.components.index.status,
+      });
+    }
+
+    return value;
+  }
+
+  /**
+   * Computes health by checking all components.
+   * This is called by CachedValue when the cache is stale.
+   * @returns {Promise<Object>}
+   * @private
+   */
+  async _computeHealth() {
+    // Check repository health
+    const repositoryHealth = await this._checkRepository();
+
+    // Check index health
+    const indexHealth = this._checkIndex();
+
+    // Determine overall status
+    const status = this._computeOverallStatus(repositoryHealth, indexHealth);
+
+    return {
+      status,
+      components: {
+        repository: repositoryHealth,
+        index: indexHealth,
+      },
+    };
+  }
+
+  /**
+   * Checks repository health by pinging the persistence layer.
+   * @returns {Promise<RepositoryHealth>}
+   * @private
+   */
+  async _checkRepository() {
+    try {
+      const pingResult = await this._persistence.ping();
+      return {
+        status: pingResult.ok ? HealthStatus.HEALTHY : HealthStatus.UNHEALTHY,
+        latencyMs: Math.round(pingResult.latencyMs * 100) / 100, // Round to 2 decimal places
+      };
+    } catch (err) {
+      this._logger.warn('Repository ping failed', {
+        operation: 'checkRepository',
+        error: err.message,
+      });
+      return {
+        status: HealthStatus.UNHEALTHY,
+        latencyMs: 0,
+      };
+    }
+  }
+
+  /**
+   * Checks index health based on loaded state and shard count.
+   * @returns {IndexHealth}
+   * @private
+   */
+  _checkIndex() {
+    if (!this._indexReader) {
+      return {
+        status: HealthStatus.DEGRADED,
+        loaded: false,
+      };
+    }
+
+    // Index is loaded - count shards
+    const shardCount = this._indexReader.shardOids?.size ?? 0;
+
+    return {
+      status: HealthStatus.HEALTHY,
+      loaded: true,
+      shardCount,
+    };
+  }
+
+  /**
+   * Computes overall health status from component health.
+   * @param {RepositoryHealth} repositoryHealth
+   * @param {IndexHealth} indexHealth
+   * @returns {'healthy'|'degraded'|'unhealthy'}
+   * @private
+   */
+  _computeOverallStatus(repositoryHealth, indexHealth) {
+    // If repository is unhealthy, overall is unhealthy
+    if (repositoryHealth.status === HealthStatus.UNHEALTHY) {
+      return HealthStatus.UNHEALTHY;
+    }
+
+    // If index is degraded (not loaded), overall is degraded
+    if (indexHealth.status === HealthStatus.DEGRADED) {
+      return HealthStatus.DEGRADED;
+    }
+
+    // All components healthy
+    return HealthStatus.HEALTHY;
+  }
+}