@git-stunts/git-warp 11.5.0 → 11.5.1

package/README.md

@@ -55,6 +55,10 @@ const result = await graph.query()
 
 ## How It Works
 
+<p align="center">
+  <img src="docs/diagrams/fig-data-storage.svg" alt="WARP data storage — invisible to normal Git workflows" width="700">
+</p>
+
 ### The Multi-Writer Problem (and How It's Solved)
 
 Multiple people (or machines, or processes) can write to the same graph **simultaneously, without any coordination**. There's no central server, no locking, no "wait your turn."
@@ -73,6 +77,10 @@ Every operation gets a unique **EventId** — `(lamport, writerId, patchSha, opI
 
 ## Multi-Writer Collaboration
 
+<p align="center">
+  <img src="docs/diagrams/fig-multi-writer.svg" alt="Multi-writer convergence — independent chains, deterministic merge" width="700">
+</p>
+
 Writers operate independently on the same Git repository. Sync happens through standard Git transport (push/pull) or the built-in HTTP sync protocol.
 
 ```javascript
@@ -457,6 +465,10 @@ When a seek cursor is active, `query`, `info`, `materialize`, and `history` auto
 
 ## Architecture
 
+<p align="center">
+  <img src="docs/diagrams/fig-architecture.svg" alt="Hexagonal architecture — dependency rule: arrows point inward only" width="700">
+</p>
+
 The codebase follows hexagonal architecture with ports and adapters:
 
 **Ports** define abstract interfaces for infrastructure:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "11.5.0",
+  "version": "11.5.1",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",

package/src/domain/WarpGraph.js

@@ -18,12 +18,12 @@ import defaultCrypto from './utils/defaultCrypto.js';
 import defaultClock from './utils/defaultClock.js';
 import LogicalTraversal from './services/LogicalTraversal.js';
 import LRUCache from './utils/LRUCache.js';
+import SyncController from './services/SyncController.js';
 import { wireWarpMethods } from './warp/_wire.js';
 import * as queryMethods from './warp/query.methods.js';
 import * as subscribeMethods from './warp/subscribe.methods.js';
 import * as provenanceMethods from './warp/provenance.methods.js';
 import * as forkMethods from './warp/fork.methods.js';
-import * as syncMethods from './warp/sync.methods.js';
 import * as checkpointMethods from './warp/checkpoint.methods.js';
 import * as patchMethods from './warp/patch.methods.js';
 import * as materializeMethods from './warp/materialize.methods.js';
@@ -172,6 +172,9 @@ export default class WarpGraph {
 
     /** @type {number} */
     this._auditSkipCount = 0;
+
+    /** @type {SyncController} */
+    this._syncController = new SyncController(this);
   }
 
   /**
@@ -410,9 +413,26 @@ wireWarpMethods(WarpGraph, [
   subscribeMethods,
   provenanceMethods,
   forkMethods,
-  syncMethods,
   checkpointMethods,
   patchMethods,
   materializeMethods,
   materializeAdvancedMethods,
 ]);
+
+// ── Sync methods: direct delegation to SyncController (no stub file) ────────
+const syncDelegates = /** @type {const} */ ([
+  'getFrontier', 'hasFrontierChanged', 'status',
+  'createSyncRequest', 'processSyncRequest', 'applySyncResponse',
+  'syncNeeded', 'syncWith', 'serve',
+]);
+for (const method of syncDelegates) {
+  Object.defineProperty(WarpGraph.prototype, method, {
+    // eslint-disable-next-line object-shorthand -- function keyword needed for `this` binding
+    value: /** @this {WarpGraph} @param {*[]} args */ function (...args) {
+      return this._syncController[method](...args);
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+}

package/src/domain/services/BitmapIndexReader.js

@@ -4,6 +4,7 @@ import nullLogger from '../utils/nullLogger.js';
 import LRUCache from '../utils/LRUCache.js';
 import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
+import { isValidShardOid } from '../utils/validateShardOid.js';
 
 /** @typedef {import('../../ports/IndexStoragePort.js').default} IndexStoragePort */
 /** @typedef {import('../types/WarpPersistence.js').IndexStorage} IndexStorage */
@@ -50,24 +51,24 @@ const computeChecksum = async (data, version, crypto) => {
  * - {@link ShardCorruptionError} for invalid shard format
  * - {@link ShardValidationError} for version or checksum mismatches
  *
- * In non-strict mode (default), validation failures are logged as warnings
+ * In non-strict mode (strict: false), validation failures are logged as warnings
  * and an empty shard is returned for graceful degradation.
  *
  * **Note**: Storage errors (e.g., `storage.readBlob` failures) always throw
  * {@link ShardLoadError} regardless of strict mode.
  *
  * @example
- * // Non-strict mode (default) - graceful degradation on validation errors
+ * // Strict mode (default) - throws on any validation failure
  * const reader = new BitmapIndexReader({ storage });
  * reader.setup(shardOids);
  * const parents = await reader.getParents('abc123...');
  *
  * @example
- * // Strict mode - throws on any validation failure
- * const strictReader = new BitmapIndexReader({ storage, strict: true });
- * strictReader.setup(shardOids);
+ * // Non-strict mode - graceful degradation on validation errors
+ * const lenientReader = new BitmapIndexReader({ storage, strict: false });
+ * lenientReader.setup(shardOids);
  * try {
- *   const parents = await strictReader.getParents('abc123...');
+ *   const parents = await lenientReader.getParents('abc123...');
  * } catch (err) {
  *   if (err instanceof ShardValidationError) {
  *     console.error('Shard validation failed:', err.field, err.expected, err.actual);
@@ -83,14 +84,14 @@ export default class BitmapIndexReader {
    * Creates a BitmapIndexReader instance.
    * @param {Object} options
    * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
-   * @param {boolean} [options.strict=false] - If true, throw errors on validation failures; if false, log warnings and return empty shards
+   * @param {boolean} [options.strict=true] - If true, throw errors on validation failures; if false, log warnings and return empty shards
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
    * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
    *   When exceeded, least recently used shards are evicted to free memory.
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
    */
-  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
+  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -132,8 +133,29 @@ export default class BitmapIndexReader {
    * const parents = await reader.getParents('abcd1234...'); // loads meta_ab, shards_rev_ab
    */
   setup(shardOids) {
-    this.shardOids = new Map(Object.entries(shardOids));
-    this._idToShaCache = null; // Clear cache when shards change
+    const entries = Object.entries(shardOids);
+    /** @type {[string, string][]} */
+    const validEntries = [];
+    for (const [path, oid] of entries) {
+      if (isValidShardOid(oid)) {
+        validEntries.push([path, oid]);
+      } else if (this.strict) {
+        throw new ShardCorruptionError('Invalid shard OID', {
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      } else {
+        this.logger.warn('Skipping shard with invalid OID', {
+          operation: 'setup',
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      }
+    }
+    this.shardOids = new Map(validEntries);
+    this._idToShaCache = null;
     this.loadedShards.clear();
   }
 

package/src/domain/services/JoinReducer.js

@@ -342,48 +342,55 @@ function foldPatchDot(frontier, writer, lamport) {
 }
 
 /**
- * Joins a patch into state, applying all operations in order.
- *
- * This is the primary function for incorporating a single patch into WARP state.
- * It iterates through all operations in the patch, creates EventIds for causality
- * tracking, and applies each operation using `applyOpV2`.
- *
- * **Receipt Collection Mode**:
- * When `collectReceipts` is true, this function also computes the outcome of each
- * operation (applied, redundant, or superseded) and returns a TickReceipt for
- * provenance tracking. This has a small performance cost, so it's disabled by default.
- *
- * **Warning**: This function mutates `state` in place. For immutable operations,
- * clone the state first using `cloneStateV5()`.
+ * Merges a patch's context into state and folds the patch dot.
+ * @param {WarpStateV5} state
+ * @param {Object} patch
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ */
+function updateFrontierFromPatch(state, patch) {
+  const contextVV = patch.context instanceof Map
+    ? patch.context
+    : vvDeserialize(patch.context || {});
+  state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+  foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
+}
+
+/**
+ * Applies a patch to state without receipt collection (zero overhead).
  *
- * @param {WarpStateV5} state - The state to mutate. Modified in place.
+ * @param {WarpStateV5} state - The state to mutate in place
  * @param {Object} patch - The patch to apply
- * @param {string} patch.writer - Writer ID who created this patch
- * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
- * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
- * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
- * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
- * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
- *          Returns mutated state directly when collectReceipts is false;
- *          returns {state, receipt} object when collectReceipts is true
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {string} patchSha - Git SHA of the patch commit
+ * @returns {WarpStateV5} The mutated state
  */
-export function join(state, patch, patchSha, collectReceipts) {
-  // ZERO-COST: when collectReceipts is falsy, skip all receipt logic
-  if (!collectReceipts) {
-    for (let i = 0; i < patch.ops.length; i++) {
-      const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
-      applyOpV2(state, patch.ops[i], eventId);
-    }
-    const contextVV = patch.context instanceof Map
-      ? patch.context
-      : vvDeserialize(patch.context);
-    state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
-    foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
-    return state;
+export function applyFast(state, patch, patchSha) {
+  for (let i = 0; i < patch.ops.length; i++) {
+    const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
+    applyOpV2(state, patch.ops[i], eventId);
   }
+  updateFrontierFromPatch(state, patch);
+  return state;
+}
 
-  // Receipt-enabled path
+/**
+ * Applies a patch to state with receipt collection for provenance tracking.
+ *
+ * @param {WarpStateV5} state - The state to mutate in place
+ * @param {Object} patch - The patch to apply
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {string} patchSha - Git SHA of the patch commit
+ * @returns {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
+ */
+export function applyWithReceipt(state, patch, patchSha) {
   /** @type {import('../types/TickReceipt.js').OpOutcome[]} */
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
@@ -433,11 +440,7 @@ export function join(state, patch, patchSha, collectReceipts) {
     opResults.push(entry);
   }
 
-  const contextVV = patch.context instanceof Map
-    ? patch.context
-    : vvDeserialize(patch.context);
-  state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
-  foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
+  updateFrontierFromPatch(state, patch);
 
   const receipt = createTickReceipt({
     patchSha,
@@ -449,6 +452,39 @@ export function join(state, patch, patchSha, collectReceipts) {
   return { state, receipt };
 }
 
+/**
+ * Joins a patch into state, applying all operations in order.
+ *
+ * This is the primary function for incorporating a single patch into WARP state.
+ * It iterates through all operations in the patch, creates EventIds for causality
+ * tracking, and applies each operation using `applyOpV2`.
+ *
+ * **Receipt Collection Mode**:
+ * When `collectReceipts` is true, this function also computes the outcome of each
+ * operation (applied, redundant, or superseded) and returns a TickReceipt for
+ * provenance tracking. This has a small performance cost, so it's disabled by default.
+ *
+ * **Warning**: This function mutates `state` in place. For immutable operations,
+ * clone the state first using `cloneStateV5()`.
+ *
+ * @param {WarpStateV5} state - The state to mutate. Modified in place.
+ * @param {Object} patch - The patch to apply
+ * @param {string} patch.writer - Writer ID who created this patch
+ * @param {number} patch.lamport - Lamport timestamp of this patch
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
+ * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
+ * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
+ * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
+ *          Returns mutated state directly when collectReceipts is false;
+ *          returns {state, receipt} object when collectReceipts is true
+ */
+export function join(state, patch, patchSha, collectReceipts) {
+  return collectReceipts
+    ? applyWithReceipt(state, patch, patchSha)
+    : applyFast(state, patch, patchSha);
+}
+
 /**
  * Joins two V5 states together using CRDT merge semantics.
  *
@@ -560,14 +596,14 @@ export function reduceV5(patches, initialState, options) {
   if (options && options.receipts) {
     const receipts = [];
     for (const { patch, sha } of patches) {
-      const result = /** @type {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (join(state, patch, sha, true));
+      const result = applyWithReceipt(state, patch, sha);
       receipts.push(result.receipt);
     }
     return { state, receipts };
   }
 
   for (const { patch, sha } of patches) {
-    join(state, patch, sha);
+    applyFast(state, patch, sha);
   }
   return state;
 }