@git-stunts/git-warp 11.5.1 → 12.0.0

package/src/domain/services/PropertyIndexBuilder.js

@@ -0,0 +1,64 @@
+/**
+ * Builds property index shards from node properties.
+ *
+ * Produces `props_XX.cbor` shards keyed by shard key, where each
+ * shard maps nodeId → { key: value, ... }.
+ *
+ * @module domain/services/PropertyIndexBuilder
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import computeShardKey from '../utils/shardKey.js';
+
+export default class PropertyIndexBuilder {
+  /**
+   * @param {Object} [options]
+   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   */
+  constructor({ codec } = {}) {
+    this._codec = codec || defaultCodec;
+    /** @type {Map<string, Map<string, Record<string, unknown>>>} shardKey → (nodeId → props) */
+    this._shards = new Map();
+  }
+
+  /**
+   * Adds a property for a node.
+   *
+   * @param {string} nodeId
+   * @param {string} key
+   * @param {unknown} value
+   */
+  addProperty(nodeId, key, value) {
+    const shardKey = computeShardKey(nodeId);
+    let shard = this._shards.get(shardKey);
+    if (!shard) {
+      shard = new Map();
+      this._shards.set(shardKey, shard);
+    }
+    let nodeProps = shard.get(nodeId);
+    if (!nodeProps) {
+      nodeProps = /** @type {Record<string, unknown>} */ (Object.create(null));
+      shard.set(nodeId, nodeProps);
+    }
+    /** @type {Record<string, unknown>} */ (nodeProps)[key] = value;
+  }
+
+  /**
+   * Serializes all property shards.
+   *
+   * @returns {Record<string, Uint8Array>}
+   */
+  serialize() {
+    /** @type {Record<string, Uint8Array>} */
+    const tree = {};
+    for (const [shardKey, shard] of this._shards) {
+      // Encode as array of [nodeId, props] pairs to avoid __proto__ key issues
+      // when CBOR decodes into plain objects. Sorted by nodeId for determinism.
+      const entries = [...shard.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([nodeId, props]) => [nodeId, props]);
+      tree[`props_${shardKey}.cbor`] = this._codec.encode(entries).slice();
+    }
+    return tree;
+  }
+}

package/src/domain/services/PropertyIndexReader.js

@@ -0,0 +1,111 @@
+/**
+ * Reads property index shards lazily with LRU caching.
+ *
+ * Loads `props_XX.cbor` shards on demand via IndexStoragePort.readBlob.
+ *
+ * @module domain/services/PropertyIndexReader
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import computeShardKey from '../utils/shardKey.js';
+import LRUCache from '../utils/LRUCache.js';
+
+export default class PropertyIndexReader {
+  /**
+   * @param {Object} [options]
+   * @param {import('../../ports/IndexStoragePort.js').default} [options.storage]
+   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {number} [options.maxCachedShards=64]
+   */
+  constructor({ storage, codec, maxCachedShards = 64 } = /** @type {{ storage?: import('../../ports/IndexStoragePort.js').default, codec?: import('../../ports/CodecPort.js').default, maxCachedShards?: number }} */ ({})) {
+    this._storage = storage;
+    this._codec = codec || defaultCodec;
+    /** @type {Map<string, string>} path → oid */
+    this._shardOids = new Map();
+    /** @type {LRUCache<string, Record<string, Record<string, unknown>>>} */
+    this._cache = new LRUCache(maxCachedShards);
+  }
+
+  /**
+   * Configures OID mappings for lazy loading.
+   *
+   * @param {Record<string, string>} shardOids - path → blob OID
+   */
+  setup(shardOids) {
+    this._shardOids = new Map(Object.entries(shardOids));
+    this._cache.clear();
+  }
+
+  /**
+   * Returns all properties for a node, or null if not found.
+   *
+   * @param {string} nodeId
+   * @returns {Promise<Record<string, unknown>|null>}
+   */
+  async getNodeProps(nodeId) {
+    const shard = await this._loadShard(nodeId);
+    if (!shard) {
+      return null;
+    }
+    return shard[nodeId] ?? null;
+  }
+
+  /**
+   * Returns a single property value, or undefined.
+   *
+   * @param {string} nodeId
+   * @param {string} key
+   * @returns {Promise<unknown|undefined>}
+   */
+  async getProperty(nodeId, key) {
+    const props = await this.getNodeProps(nodeId);
+    if (!props) {
+      return undefined;
+    }
+    return props[key];
+  }
+
+  /**
+   * @param {string} nodeId
+   * @returns {Promise<Record<string, Record<string, unknown>>|null>}
+   * @private
+   */
+  async _loadShard(nodeId) {
+    const shardKey = computeShardKey(nodeId);
+    const path = `props_${shardKey}.cbor`;
+
+    const cached = this._cache.get(path);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const oid = this._shardOids.get(path);
+    if (!oid) {
+      return null;
+    }
+
+    if (!this._storage) {
+      return null;
+    }
+
+    const buffer = await /** @type {{ readBlob(oid: string): Promise<Buffer|Uint8Array|undefined|null> }} */ (this._storage).readBlob(oid);
+    if (buffer === null || buffer === undefined) {
+      throw new Error(`PropertyIndexReader: missing blob for OID '${oid}' (${path})`);
+    }
+    const decoded = this._codec.decode(buffer);
+
+    // Shards are stored as array of [nodeId, props] pairs (proto-safe)
+    if (!Array.isArray(decoded)) {
+      const shape = decoded === null ? 'null' : typeof decoded;
+      throw new Error(`PropertyIndexReader: invalid shard format for '${path}' (expected array, got ${shape})`);
+    }
+
+    /** @type {Record<string, Record<string, unknown>>} */
+    const data = Object.create(null);
+    for (const [nid, props] of /** @type {Array<[string, Record<string, unknown>]>} */ (decoded)) {
+      data[nid] = props;
+    }
+    this._cache.set(path, data);
+    return data;
+  }
+}

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
+}