@git-stunts/git-warp 11.5.0 → 12.0.0

package/src/domain/services/TemporalQuery.js

@@ -26,7 +26,7 @@
  * @see Paper IV - Echo and the WARP Core (CTL* temporal logic on histories)
  */
 
-import { createEmptyStateV5, join as joinPatch } from './JoinReducer.js';
+import { createEmptyStateV5, cloneStateV5, join as joinPatch } from './JoinReducer.js';
 import { decodePropKey } from './KeyCodec.js';
 import { orsetContains } from '../crdt/ORSet.js';
 
@@ -83,6 +83,64 @@ function extractNodeSnapshot(state, nodeId) {
   return { id: nodeId, exists, props };
 }
 
+/**
+ * Evaluates checkpoint boundary semantics for `always()`.
+ *
+ * @param {Object} params
+ * @param {import('./JoinReducer.js').WarpStateV5} params.state
+ * @param {string} params.nodeId
+ * @param {Function} params.predicate
+ * @param {number|null} params.checkpointMaxLamport
+ * @param {number} params.since
+ * @returns {{ nodeEverExisted: boolean, shouldReturn: boolean, returnValue: boolean }}
+ * @private
+ */
+function evaluateAlwaysCheckpointBoundary({
+  state,
+  nodeId,
+  predicate,
+  checkpointMaxLamport,
+  since,
+}) {
+  if (checkpointMaxLamport !== since) {
+    return { nodeEverExisted: false, shouldReturn: false, returnValue: false };
+  }
+  const snapshot = extractNodeSnapshot(state, nodeId);
+  if (!snapshot.exists) {
+    return { nodeEverExisted: false, shouldReturn: false, returnValue: false };
+  }
+  if (!predicate(snapshot)) {
+    return { nodeEverExisted: true, shouldReturn: true, returnValue: false };
+  }
+  return { nodeEverExisted: true, shouldReturn: false, returnValue: false };
+}
+
+/**
+ * Evaluates checkpoint boundary semantics for `eventually()`.
+ *
+ * @param {Object} params
+ * @param {import('./JoinReducer.js').WarpStateV5} params.state
+ * @param {string} params.nodeId
+ * @param {Function} params.predicate
+ * @param {number|null} params.checkpointMaxLamport
+ * @param {number} params.since
+ * @returns {boolean}
+ * @private
+ */
+function evaluateEventuallyCheckpointBoundary({
+  state,
+  nodeId,
+  predicate,
+  checkpointMaxLamport,
+  since,
+}) {
+  if (checkpointMaxLamport !== since) {
+    return false;
+  }
+  const snapshot = extractNodeSnapshot(state, nodeId);
+  return snapshot.exists && predicate(snapshot);
+}
+
 /**
  * TemporalQuery provides temporal logic operators over graph history.
  *
@@ -94,10 +152,14 @@ export class TemporalQuery {
    * @param {Object} options
    * @param {Function} options.loadAllPatches - Async function that returns
    *   all patches as Array<{ patch, sha }> in causal order.
+   * @param {Function} [options.loadCheckpoint] - Async function returning
+   *   { state: WarpStateV5, maxLamport: number } or null.
    */
-  constructor({ loadAllPatches }) {
+  constructor({ loadAllPatches, loadCheckpoint }) {
     /** @type {Function} */
     this._loadAllPatches = loadAllPatches;
+    /** @type {Function|null} */
+    this._loadCheckpoint = loadCheckpoint || null;
   }
 
   /**
@@ -128,19 +190,27 @@ export class TemporalQuery {
     const since = options.since ?? 0;
     const allPatches = await this._loadAllPatches();
 
-    const state = createEmptyStateV5();
-    let nodeEverExisted = false;
+    const { state, startIdx, checkpointMaxLamport } = await this._resolveStart(allPatches, since);
+    const boundary = evaluateAlwaysCheckpointBoundary({
+      state,
+      nodeId,
+      predicate,
+      checkpointMaxLamport,
+      since,
+    });
+    if (boundary.shouldReturn) {
+      return boundary.returnValue;
+    }
+    let { nodeEverExisted } = boundary;
 
-    for (const { patch, sha } of allPatches) {
-      // Apply the patch to state
+    for (let i = startIdx; i < allPatches.length; i++) {
+      const { patch, sha } = allPatches[i];
       joinPatch(state, patch, sha);
 
-      // Skip patches before the `since` threshold
       if (patch.lamport < since) {
         continue;
       }
 
-      // Extract node snapshot at this tick
       const snapshot = extractNodeSnapshot(state, nodeId);
 
       if (snapshot.exists) {
@@ -151,7 +221,6 @@ export class TemporalQuery {
       }
     }
 
-    // If the node never existed in the range, return false
     return nodeEverExisted;
   }
 
@@ -181,18 +250,26 @@ export class TemporalQuery {
     const since = options.since ?? 0;
     const allPatches = await this._loadAllPatches();
 
-    const state = createEmptyStateV5();
+    const { state, startIdx, checkpointMaxLamport } = await this._resolveStart(allPatches, since);
 
-    for (const { patch, sha } of allPatches) {
-      // Apply the patch to state
+    if (evaluateEventuallyCheckpointBoundary({
+      state,
+      nodeId,
+      predicate,
+      checkpointMaxLamport,
+      since,
+    })) {
+      return true;
+    }
+
+    for (let i = startIdx; i < allPatches.length; i++) {
+      const { patch, sha } = allPatches[i];
       joinPatch(state, patch, sha);
 
-      // Skip patches before the `since` threshold
       if (patch.lamport < since) {
         continue;
       }
 
-      // Extract node snapshot at this tick
       const snapshot = extractNodeSnapshot(state, nodeId);
 
       if (snapshot.exists && predicate(snapshot)) {
@@ -202,4 +279,41 @@ export class TemporalQuery {
 
     return false;
   }
+
+  /**
+   * Resolves the initial state and start index for temporal replay.
+   *
+   * When `since > 0` and a checkpoint is available with
+   * `maxLamport <= since`, uses the checkpoint state and skips
+   * patches already covered by it. Otherwise falls back to an
+   * empty state starting from index 0.
+   *
+   * **Checkpoint `maxLamport` invariant**: The checkpoint's `maxLamport` value
+   * MUST represent a fully-closed Lamport tick — i.e. ALL patches with
+   * `lamport <= maxLamport` are included in the checkpoint state. The
+   * `findIndex` below uses strict `>` to locate the first patch *after* the
+   * checkpoint boundary. If a checkpoint were created mid-tick (some but not
+   * all patches at a given Lamport value included), this would silently skip
+   * the remaining same-tick patches. Checkpoint creators MUST guarantee the
+   * all-or-nothing inclusion property for any given Lamport tick.
+   *
+   * @param {Array<{patch: {lamport: number, [k: string]: unknown}, sha: string}>} allPatches
+   * @param {number} since - Minimum Lamport tick
+   * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, startIdx: number, checkpointMaxLamport: number|null}>}
+   * @private
+   */
+  async _resolveStart(allPatches, since) {
+    if (since > 0 && this._loadCheckpoint) {
+      const ck = /** @type {{ state: import('./JoinReducer.js').WarpStateV5, maxLamport: number } | null} */ (await this._loadCheckpoint());
+      if (ck && ck.state && ck.maxLamport <= since) {
+        const idx = allPatches.findIndex(
+          ({ patch }) => patch.lamport > ck.maxLamport,
+        );
+        const startIdx = idx < 0 ? allPatches.length : idx;
+        // Replay mutates state in-place; isolate checkpoint provider caches from query runs.
+        return { state: cloneStateV5(ck.state), startIdx, checkpointMaxLamport: ck.maxLamport };
+      }
+    }
+    return { state: createEmptyStateV5(), startIdx: 0, checkpointMaxLamport: null };
+  }
 }

package/src/domain/types/PatchDiff.js

@@ -0,0 +1,90 @@
+/**
+ * PatchDiff — captures alive-ness transitions during patch application.
+ *
+ * A diff entry is produced only when the alive-ness state of a node or edge
+ * actually changes, or when an LWW property winner changes. Redundant ops
+ * (e.g. NodeAdd on an already-alive node) produce no diff entries.
+ *
+ * @module domain/types/PatchDiff
+ */
+
+/**
+ * @typedef {Object} EdgeDiffEntry
+ * @property {string} from  - Source node ID
+ * @property {string} to    - Target node ID
+ * @property {string} label - Edge label
+ */
+
+/**
+ * @typedef {Object} PropDiffEntry
+ * @property {string} nodeId   - Node (or edge-prop owner) ID
+ * @property {string} key      - Property key
+ * @property {unknown} value   - New LWW winner value
+ * @property {unknown} prevValue - Previous LWW winner value (undefined if none)
+ */
+
+/**
+ * @typedef {Object} PatchDiff
+ * @property {string[]} nodesAdded           - Nodes that transitioned not-alive → alive
+ * @property {string[]} nodesRemoved         - Nodes that transitioned alive → not-alive
+ * @property {EdgeDiffEntry[]} edgesAdded    - Edges that transitioned not-alive → alive
+ * @property {EdgeDiffEntry[]} edgesRemoved  - Edges that transitioned alive → not-alive
+ * @property {PropDiffEntry[]} propsChanged  - Properties whose LWW winner actually changed
+ */
+
+/**
+ * Creates an empty PatchDiff.
+ *
+ * @returns {PatchDiff}
+ */
+export function createEmptyDiff() {
+  return {
+    nodesAdded: [],
+    nodesRemoved: [],
+    edgesAdded: [],
+    edgesRemoved: [],
+    propsChanged: [],
+  };
+}
+
+/**
+ * Merges two PatchDiff objects into a net diff by cancelling out
+ * contradictory add/remove pairs.
+ *
+ * - A node that appears in `a.nodesAdded` and `b.nodesRemoved` (or vice-versa)
+ *   is dropped from both lists (the transitions cancel out).
+ * - Same logic applies to edges (keyed by `from\0to\0label`).
+ * - For `propsChanged`, only the last entry per `(nodeId, key)` is kept.
+ *
+ * @param {PatchDiff} a
+ * @param {PatchDiff} b
+ * @returns {PatchDiff}
+ */
+export function mergeDiffs(a, b) {
+  const allAdded = a.nodesAdded.concat(b.nodesAdded);
+  const allRemoved = a.nodesRemoved.concat(b.nodesRemoved);
+  const removedSet = new Set(allRemoved);
+  const addedSet = new Set(allAdded);
+  const nodesAdded = allAdded.filter((id) => !removedSet.has(id));
+  const nodesRemoved = allRemoved.filter((id) => !addedSet.has(id));
+
+  /** @param {EdgeDiffEntry} e */
+  const edgeKey = (e) => `${e.from}\0${e.to}\0${e.label}`;
+  const allEdgesAdded = a.edgesAdded.concat(b.edgesAdded);
+  const allEdgesRemoved = a.edgesRemoved.concat(b.edgesRemoved);
+  const edgeRemovedSet = new Set(allEdgesRemoved.map(edgeKey));
+  const edgeAddedSet = new Set(allEdgesAdded.map(edgeKey));
+  const edgesAdded = allEdgesAdded.filter((e) => !edgeRemovedSet.has(edgeKey(e)));
+  const edgesRemoved = allEdgesRemoved.filter((e) => !edgeAddedSet.has(edgeKey(e)));
+
+  // For props, deduplicate by keeping the last entry per (nodeId, key).
+  const allProps = a.propsChanged.concat(b.propsChanged);
+  /** @type {Map<string, PropDiffEntry>} */
+  const propMap = new Map();
+  for (const entry of allProps) {
+    propMap.set(`${entry.nodeId}\0${entry.key}`, entry);
+  }
+  const propsChanged = [...propMap.values()];
+
+  return { nodesAdded, nodesRemoved, edgesAdded, edgesRemoved, propsChanged };
+}

package/src/domain/types/WarpTypesV2.js

@@ -50,7 +50,7 @@
  * @typedef {Object} OpV2NodeRemove
  * @property {'NodeRemove'} type - Operation type discriminator
  * @property {NodeId} node - Node ID to remove
- * @property {Dot[]} observedDots - Dots being removed (add events observed)
+ * @property {string[]} observedDots - Encoded dot strings being removed (add events observed)
  */
 
 /**
@@ -70,7 +70,7 @@
  * @property {NodeId} from - Source node ID
  * @property {NodeId} to - Target node ID
  * @property {string} label - Edge label/type
- * @property {Dot[]} observedDots - Dots being removed (add events observed)
+ * @property {string[]} observedDots - Encoded dot strings being removed (add events observed)
  */
 
 /**
@@ -121,7 +121,7 @@ export function createNodeAddV2(node, dot) {
 /**
  * Creates a NodeRemove operation with observed dots
  * @param {NodeId} node - Node ID to remove
- * @param {Dot[]} observedDots - Dots being removed
+ * @param {string[]} observedDots - Encoded dot strings being removed
  * @returns {OpV2NodeRemove} NodeRemove operation
  */
 export function createNodeRemoveV2(node, observedDots) {
@@ -145,7 +145,7 @@ export function createEdgeAddV2(from, to, label, dot) {
  * @param {NodeId} from - Source node ID
  * @param {NodeId} to - Target node ID
  * @param {string} label - Edge label
- * @param {Dot[]} observedDots - Dots being removed
+ * @param {string[]} observedDots - Encoded dot strings being removed
  * @returns {OpV2EdgeRemove} EdgeRemove operation
  */
 export function createEdgeRemoveV2(from, to, label, observedDots) {

package/src/domain/utils/MinHeap.js

@@ -8,10 +8,18 @@
 class MinHeap {
   /**
    * Creates an empty MinHeap.
+   *
+   * @param {Object} [options] - Configuration options
+   * @param {((a: T, b: T) => number)} [options.tieBreaker] - Comparator invoked when two
+   *   entries have equal priority. Negative return = a wins (comes out first).
+   *   When omitted, equal-priority extraction order is unspecified (heap-natural).
    */
-  constructor() {
+  constructor(options) {
+    const { tieBreaker } = options || {};
     /** @type {Array<{item: T, priority: number}>} */
-    this.heap = [];
+    this._heap = [];
+    /** @type {((a: T, b: T) => number) | undefined} */
+    this._tieBreaker = tieBreaker;
   }
 
   /**
@@ -22,8 +30,8 @@ class MinHeap {
    * @returns {void}
    */
   insert(item, priority) {
-    this.heap.push({ item, priority });
-    this._bubbleUp(this.heap.length - 1);
+    this._heap.push({ item, priority });
+    this._bubbleUp(this._heap.length - 1);
   }
 
   /**
@@ -32,11 +40,11 @@ class MinHeap {
    * @returns {T | undefined} The item with lowest priority, or undefined if empty
    */
   extractMin() {
-    if (this.heap.length === 0) { return undefined; }
-    if (this.heap.length === 1) { return /** @type {{item: T, priority: number}} */ (this.heap.pop()).item; }
+    if (this._heap.length === 0) { return undefined; }
+    if (this._heap.length === 1) { return /** @type {{item: T, priority: number}} */ (this._heap.pop()).item; }
 
-    const min = this.heap[0];
-    this.heap[0] = /** @type {{item: T, priority: number}} */ (this.heap.pop());
+    const min = this._heap[0];
+    this._heap[0] = /** @type {{item: T, priority: number}} */ (this._heap.pop());
     this._bubbleDown(0);
     return min.item;
   }
@@ -47,7 +55,7 @@ class MinHeap {
    * @returns {boolean} True if empty
    */
   isEmpty() {
-    return this.heap.length === 0;
+    return this._heap.length === 0;
   }
 
   /**
@@ -56,7 +64,7 @@ class MinHeap {
    * @returns {number} Number of items
    */
   size() {
-    return this.heap.length;
+    return this._heap.length;
   }
 
   /**
@@ -65,7 +73,27 @@ class MinHeap {
    * @returns {number} The minimum priority value, or Infinity if empty
    */
   peekPriority() {
-    return this.heap.length > 0 ? this.heap[0].priority : Infinity;
+    return this._heap.length > 0 ? this._heap[0].priority : Infinity;
+  }
+
+  /**
+   * Compares two heap entries. Returns negative if a should come before b.
+   *
+   * @private
+   * @param {number} idxA - Index of first entry
+   * @param {number} idxB - Index of second entry
+   * @returns {number} Negative if a < b, positive if a > b, zero if equal
+   */
+  _compare(idxA, idxB) {
+    const a = this._heap[idxA];
+    const b = this._heap[idxB];
+    if (a.priority !== b.priority) {
+      return a.priority - b.priority;
+    }
+    if (this._tieBreaker) {
+      return this._tieBreaker(a.item, b.item);
+    }
+    return 0;
   }
 
   /**
@@ -78,8 +106,8 @@ class MinHeap {
     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]];
+      if (this._compare(parentIndex, current) <= 0) { break; }
+      [this._heap[parentIndex], this._heap[current]] = [this._heap[current], this._heap[parentIndex]];
       current = parentIndex;
     }
   }
@@ -91,22 +119,22 @@ class MinHeap {
    * @param {number} pos - Starting index
    */
   _bubbleDown(pos) {
-    const {length} = this.heap;
+    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) {
+      if (leftChild < length && this._compare(leftChild, smallest) < 0) {
         smallest = leftChild;
       }
-      if (rightChild < length && this.heap[rightChild].priority < this.heap[smallest].priority) {
+      if (rightChild < length && this._compare(rightChild, smallest) < 0) {
         smallest = rightChild;
       }
       if (smallest === current) { break; }
 
-      [this.heap[current], this.heap[smallest]] = [this.heap[smallest], this.heap[current]];
+      [this._heap[current], this._heap[smallest]] = [this._heap[smallest], this._heap[current]];
       current = smallest;
     }
   }

package/src/domain/utils/canonicalCbor.js

@@ -0,0 +1,36 @@
+/**
+ * Canonical CBOR encoding/decoding.
+ *
+ * Delegates to defaultCodec which already sorts keys recursively
+ * and handles Maps, null-prototype objects, and arrays.
+ *
+ * Deterministic output relies on cbor-x's key-sorting behaviour,
+ * which approximates RFC 7049 Section 3.9 (Canonical CBOR) by sorting
+ * map keys in length-first lexicographic order. This is sufficient for
+ * content-addressed equality within the WARP system but should not be
+ * assumed to match other canonical CBOR implementations byte-for-byte.
+ *
+ * @module domain/utils/canonicalCbor
+ */
+
+import defaultCodec from './defaultCodec.js';
+
+/**
+ * Encodes a value to canonical CBOR bytes with sorted keys.
+ *
+ * @param {unknown} value - The value to encode
+ * @returns {Uint8Array} CBOR-encoded bytes
+ */
+export function encodeCanonicalCbor(value) {
+  return defaultCodec.encode(value);
+}
+
+/**
+ * Decodes CBOR bytes to a value.
+ *
+ * @param {Buffer|Uint8Array} buffer - CBOR bytes
+ * @returns {unknown} Decoded value
+ */
+export function decodeCanonicalCbor(buffer) {
+  return defaultCodec.decode(buffer);
+}

package/src/domain/utils/fnv1a.js

@@ -0,0 +1,20 @@
+/**
+ * FNV-1a 32-bit hash function.
+ *
+ * Used for shard key computation when the input is not a hex SHA.
+ * Uses Math.imul for correct 32-bit multiplication semantics.
+ *
+ * @note Callers with non-ASCII node IDs should normalize to NFC before
+ * hashing to ensure consistent shard placement.
+ *
+ * @param {string} str - Input string
+ * @returns {number} Unsigned 32-bit FNV-1a hash
+ */
+export default function fnv1a(str) {
+  let hash = 0x811c9dc5; // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime
+  }
+  return hash >>> 0; // Ensure unsigned
+}

package/src/domain/utils/roaring.js

@@ -50,6 +50,7 @@ const NOT_CHECKED = Symbol('NOT_CHECKED');
  * @typedef {Object} RoaringBitmapSubset
  * @property {number} size
  * @property {function(number): void} add
+ * @property {function(number): void} remove
  * @property {function(number): boolean} has
  * @property {function(Iterable<number>): void} orInPlace
  * @property {function(boolean): Uint8Array} serialize
@@ -63,6 +64,13 @@ const NOT_CHECKED = Symbol('NOT_CHECKED');
  */
 let roaringModule = null;
 
+/**
+ * Captures module initialization failure so callers can see the root cause.
+ * @type {unknown}
+ * @private
+ */
+let initError = null;
+
 /**
  * Cached result of native availability check.
  * `NOT_CHECKED` means not yet checked, `null` means indeterminate.
@@ -83,7 +91,8 @@ let nativeAvailability = NOT_CHECKED;
  */
 function loadRoaring() {
   if (!roaringModule) {
-    throw new Error('Roaring module not loaded. Call initRoaring() first or ensure top-level await import completed.');
+    const cause = initError instanceof Error ? ` Caused by: ${initError.message}` : '';
+    throw new Error(`Roaring module not loaded. Call initRoaring() first or ensure top-level await import completed.${cause}`);
   }
   return roaringModule;
 }
@@ -99,6 +108,7 @@ function loadRoaring() {
 export async function initRoaring(mod) {
   if (mod) {
     roaringModule = mod;
+    initError = null;
     return;
   }
   if (!roaringModule) {
@@ -113,8 +123,9 @@ export async function initRoaring(mod) {
 // Auto-initialize on module load (top-level await)
 try {
   await initRoaring();
-} catch {
-  // Roaring may not be installed; functions will throw on use
+} catch (err) {
+  // Roaring may not be installed; keep root cause for downstream diagnostics.
+  initError = err;
 }
 
 /**

package/src/domain/utils/shardKey.js

@@ -0,0 +1,40 @@
+const HEX_RE = /^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/;
+
+const encoder = new TextEncoder();
+
+/**
+ * FNV-1a 32-bit over raw bytes (Uint8Array).
+ *
+ * @param {Uint8Array} bytes
+ * @returns {number} Unsigned 32-bit hash
+ */
+function fnv1aBytes(bytes) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * Computes a 2-character hex shard key for a given ID.
+ *
+ * For hex SHAs (exactly 40 or 64 hex chars), uses the first two characters (lowercased).
+ * For all other strings, computes FNV-1a hash over UTF-8 bytes and takes the low byte.
+ *
+ * Returns '00' for null, undefined, or non-string inputs (graceful fallback).
+ *
+ * @param {string} id - Node ID or SHA
+ * @returns {string} 2-character lowercase hex shard key (e.g. 'ab', '0f')
+ */
+export default function computeShardKey(id) {
+  if (id === null || id === undefined || typeof id !== 'string') {
+    return '00';
+  }
+  if (HEX_RE.test(id)) {
+    return id.substring(0, 2).toLowerCase();
+  }
+  const hash = fnv1aBytes(encoder.encode(id));
+  return (hash & 0xff).toString(16).padStart(2, '0');
+}

package/src/domain/utils/toBytes.js

@@ -0,0 +1,17 @@
+/**
+ * Normalizes a decoded byte payload to a Uint8Array.
+ *
+ * CBOR decoders may yield Buffer, Uint8Array, or plain number[] depending
+ * on runtime and codec implementation (e.g. cbor-x on Node vs Deno).
+ * This helper ensures Roaring bitmap deserialization and other binary APIs
+ * always receive a Uint8Array.
+ *
+ * @param {Uint8Array|ArrayLike<number>} value
+ * @returns {Uint8Array}
+ */
+export default function toBytes(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  return Uint8Array.from(value);
+}

package/src/domain/utils/validateShardOid.js

@@ -0,0 +1,13 @@
+/**
+ * Validates a shard Object ID (hex string, 4-64 chars).
+ *
+ * The 4-character minimum accommodates abbreviated OIDs used in test
+ * fixtures and short internal IDs. Full Git SHA-1 OIDs are 40 chars;
+ * SHA-256 OIDs are 64 chars.
+ *
+ * @param {string} oid - The OID to validate
+ * @returns {boolean} True if oid is a valid hex string of 4-64 characters
+ */
+export function isValidShardOid(oid) {
+  return typeof oid === 'string' && /^[0-9a-fA-F]{4,64}$/.test(oid);
+}

package/src/domain/warp/_internal.js

@@ -10,17 +10,8 @@
 // ── Error constructors ──────────────────────────────────────────────────────
 export { default as QueryError } from '../errors/QueryError.js';
 export { default as ForkError } from '../errors/ForkError.js';
-export { default as SyncError } from '../errors/SyncError.js';
-export { default as OperationAbortedError } from '../errors/OperationAbortedError.js';
 
 // ── Shared constants ────────────────────────────────────────────────────────
 export const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
 export const E_NO_STATE_MSG = 'No materialized state. Call materialize() before querying, or use autoMaterialize: true (the default). See https://github.com/git-stunts/git-warp#materialization';
 export const E_STALE_STATE_MSG = 'State is stale (patches written since last materialize). Call materialize() to refresh. See https://github.com/git-stunts/git-warp#materialization';
-
-// ── Sync constants ──────────────────────────────────────────────────────────
-export const DEFAULT_SYNC_SERVER_MAX_BYTES = 4 * 1024 * 1024;
-export const DEFAULT_SYNC_WITH_RETRIES = 3;
-export const DEFAULT_SYNC_WITH_BASE_DELAY_MS = 250;
-export const DEFAULT_SYNC_WITH_MAX_DELAY_MS = 2000;
-export const DEFAULT_SYNC_WITH_TIMEOUT_MS = 10_000;