@git-stunts/git-warp 12.2.0 → 12.2.1

package/src/domain/warp/checkpoint.methods.js

@@ -167,8 +167,28 @@ export async function _loadLatestCheckpoint() {
 
   try {
     return await loadCheckpoint(this._persistence, checkpointSha, { codec: this._codec });
-  } catch {
-    return null;
+  } catch (err) {
+    // "Not found" conditions (missing tree entries, missing blobs) are expected
+    // when a checkpoint ref exists but the objects have been pruned or are
+    // unreachable. In that case, fall back to full replay by returning null.
+    // Decode/corruption errors (e.g., CBOR parse failure, schema mismatch)
+    // should propagate so callers see the real problem.
+    // These string-contains checks match specific error messages from the
+    // persistence layer and codec:
+    //   "missing"          — git cat-file on pruned/unreachable objects
+    //   "not found"        — readTree entry lookup failures
+    //   "ENOENT"           — filesystem-level missing path (bare repo edge case)
+    //   "non-empty string" — readRef/getNodeInfo called with empty/null SHA
+    const msg = err instanceof Error ? err.message : '';
+    if (
+      msg.includes('missing') ||
+      msg.includes('not found') ||
+      msg.includes('ENOENT') ||
+      msg.includes('non-empty string')
+    ) {
+      return null;
+    }
+    throw err;
   }
 }
 
@@ -188,9 +208,11 @@ export async function _loadPatchesSince(checkpoint) {
     const checkpointSha = checkpoint.frontier?.get(writerId) || null;
     const patches = await this._loadWriterPatches(writerId, checkpointSha);
 
-    // Validate each patch against checkpoint frontier
-    for (const { sha } of patches) {
-      await this._validatePatchAgainstCheckpoint(writerId, sha, checkpoint);
+    // Validate ancestry once at the writer tip; chain-order patches are then
+    // transitively valid between checkpointSha and tipSha.
+    if (patches.length > 0) {
+      const tipSha = patches[patches.length - 1].sha;
+      await this._validatePatchAgainstCheckpoint(writerId, tipSha, checkpoint);
     }
 
     for (const p of patches) {
@@ -228,10 +250,16 @@ export async function _validateMigrationBoundary() {
 }
 
 /**
- * Checks if there are any schema:1 patches in the graph.
+ * Checks whether any writer tip contains a schema:1 patch.
+ *
+ * **Heuristic only** — inspects the most recent patch per writer (the tip),
+ * not the full history chain. Older schema:1 patches buried deeper in a
+ * writer's chain will NOT be detected. This is acceptable because migration
+ * typically writes a new tip, so a schema:2+ tip implies the writer has
+ * been migrated.
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {Promise<boolean>} True if schema:1 patches exist
+ * @returns {Promise<boolean>} True if any writer tip is schema:1 (or omits `schema`, treated as legacy v1)
  * @private
  */
 export async function _hasSchema1Patches() {
@@ -312,6 +340,7 @@ export function _maybeRunGC(state) {
       if (preGcFingerprint !== postGcFingerprint) {
         // Frontier changed — discard compacted state, mark dirty
         this._stateDirty = true;
+        this._cachedViewHash = null;
         if (this._logger) {
           this._logger.warn(
             'Auto-GC discarded: frontier changed during compaction (concurrent write)',

package/src/domain/warp/materialize.methods.js

@@ -51,6 +51,30 @@ function scanPatchesForMaxLamport(graph, patches) {
   }
 }
 
+/**
+ * Creates a shallow-frozen public view of materialized state.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @returns {import('../services/JoinReducer.js').WarpStateV5}
+ */
+function freezePublicState(state) {
+  return Object.freeze({ ...state });
+}
+
+/**
+ * Creates a shallow-frozen public result for receipt-enabled materialization.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @param {import('../types/TickReceipt.js').TickReceipt[]} receipts
+ * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}}
+ */
+function freezePublicStateWithReceipts(state, receipts) {
+  return Object.freeze({
+    state: freezePublicState(state),
+    receipts,
+  });
+}
+
 
 /**
  * Materializes the current graph state.
@@ -90,7 +114,12 @@ export async function materialize(options) {
   try {
     // When ceiling is active, delegate to ceiling-aware path (with its own cache)
     if (ceiling !== null) {
-      return await this._materializeWithCeiling(ceiling, !!collectReceipts, t0);
+      const result = await this._materializeWithCeiling(ceiling, !!collectReceipts, t0);
+      if (collectReceipts) {
+        const withReceipts = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (result);
+        return freezePublicStateWithReceipts(withReceipts.state, withReceipts.receipts);
+      }
+      return freezePublicState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (result));
     }
 
     // Check for checkpoint
@@ -190,7 +219,7 @@ export async function materialize(options) {
       }
     }
 
-    await this._setMaterializedState(state, diff);
+    await this._setMaterializedState(state, { diff });
     this._provenanceDegraded = false;
     this._cachedCeiling = null;
     this._cachedFrontier = null;
@@ -225,9 +254,12 @@ export async function materialize(options) {
     this._logTiming('materialize', t0, { metrics: `${patchCount} patches` });
 
     if (collectReceipts) {
-      return { state, receipts: /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts) };
+      return freezePublicStateWithReceipts(
+        /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state),
+        /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts),
+      );
     }
-    return state;
+    return freezePublicState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state));
   } catch (err) {
     this._logTiming('materialize', t0, { error: /** @type {Error} */ (err) });
     throw err;
@@ -245,7 +277,14 @@ export async function _materializeGraph() {
   if (!this._stateDirty && this._materializedGraph) {
     return this._materializedGraph;
   }
-  const state = await this.materialize();
+  const materialized = await this.materialize();
+  const state = this._stateDirty
+    ? /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (materialized)
+    : (this._cachedState
+      || /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (materialized));
+  if (!state) {
+    return /** @type {object} */ (this._materializedGraph);
+  }
   if (!this._materializedGraph || this._materializedGraph.state !== state) {
     await this._setMaterializedState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state));
   }

package/src/domain/warp/materializeAdvanced.methods.js

@@ -22,15 +22,40 @@ import BitmapNeighborProvider from '../services/BitmapNeighborProvider.js';
 
 /** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 /** @typedef {import('../services/JoinReducer.js').WarpStateV5} WarpStateV5 */
+/** @typedef {import('../types/TickReceipt.js').TickReceipt} TickReceipt */
 
 /**
  * @typedef {{ outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>> }} AdjacencyMap
- * @typedef {{ state: WarpStateV5, stateHash: string, adjacency: AdjacencyMap }} MaterializedResult
+ * @typedef {{ state: WarpStateV5, stateHash: string|null, adjacency: AdjacencyMap }} MaterializedResult
  */
 
 import { buildWriterRef } from '../utils/RefLayout.js';
 import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
 
+/**
+ * Creates a shallow-frozen public view of materialized state.
+ *
+ * @param {WarpStateV5} state
+ * @returns {WarpStateV5}
+ */
+function freezePublicState(state) {
+  return Object.freeze({ ...state });
+}
+
+/**
+ * Creates a shallow-frozen public materialization result with receipts.
+ *
+ * @param {WarpStateV5} state
+ * @param {TickReceipt[]} receipts
+ * @returns {{state: WarpStateV5, receipts: TickReceipt[]}}
+ */
+function freezePublicStateWithReceipts(state, receipts) {
+  return Object.freeze({
+    state: freezePublicState(state),
+    receipts,
+  });
+}
+
 /**
  * Resolves the effective ceiling from options and instance state.
  *
@@ -107,11 +132,23 @@ export function _buildAdjacency(state) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
- * @param {import('../types/PatchDiff.js').PatchDiff} [diff] - Optional diff for incremental index
+ * @param {import('../types/PatchDiff.js').PatchDiff|{diff?: import('../types/PatchDiff.js').PatchDiff|null}} [optionsOrDiff]
+ *   Either a PatchDiff (legacy positional form) or options object.
  * @returns {Promise<MaterializedResult>}
  * @private
  */
-export async function _setMaterializedState(state, diff) {
+export async function _setMaterializedState(state, optionsOrDiff) {
+  /** @type {import('../types/PatchDiff.js').PatchDiff|undefined} */
+  let diff;
+  if (
+    optionsOrDiff &&
+    typeof optionsOrDiff === 'object' &&
+    Object.prototype.hasOwnProperty.call(optionsOrDiff, 'diff')
+  ) {
+    diff = /** @type {{diff?: import('../types/PatchDiff.js').PatchDiff|null}} */ (optionsOrDiff).diff ?? undefined;
+  } else {
+    diff = /** @type {import('../types/PatchDiff.js').PatchDiff|undefined} */ (optionsOrDiff ?? undefined);
+  }
   this._cachedState = state;
   this._stateDirty = false;
   this._versionVector = vvClone(state.observedFrontier);
@@ -222,7 +259,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
     cf.size === frontier.size &&
     [...frontier].every(([w, sha]) => cf.get(w) === sha)
   ) {
-    return this._cachedState;
+    return freezePublicState(this._cachedState);
   }
 
   const writerIds = [...frontier.keys()];
@@ -236,9 +273,9 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
     this._cachedFrontier = frontier;
     this._logTiming('materialize', t0, { metrics: '0 patches (ceiling)' });
     if (collectReceipts) {
-      return { state, receipts: [] };
+      return freezePublicStateWithReceipts(state, []);
     }
-    return state;
+    return freezePublicState(state);
   }
 
   // Persistent cache check — skip when collectReceipts is requested
@@ -259,7 +296,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
             await this._restoreIndexFromCache(cached.indexTreeOid);
           }
           this._logTiming('materialize', t0, { metrics: `cache hit (ceiling=${ceiling})` });
-          return state;
+          return freezePublicState(state);
         } catch {
           // Corrupted payload — self-heal by removing the bad entry
           try { await this._seekCache.delete(cacheKey); } catch { /* best-effort */ }
@@ -322,9 +359,12 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
   this._logTiming('materialize', t0, { metrics: `${allPatches.length} patches (ceiling=${ceiling})` });
 
   if (collectReceipts) {
-    return { state, receipts: /** @type {import('../types/TickReceipt.js').TickReceipt[]} */ (receipts) };
+    return freezePublicStateWithReceipts(
+      state,
+      /** @type {TickReceipt[]} */ (receipts),
+    );
   }
-  return state;
+  return freezePublicState(state);
 }
 
 /**
@@ -459,7 +499,7 @@ export async function materializeAt(checkpointSha) {
     codec: this._codec,
   });
   await this._setMaterializedState(state);
-  return state;
+  return freezePublicState(state);
 }
 
 /**

package/src/domain/warp/patch.methods.js

@@ -10,9 +10,9 @@
 
 import { QueryError, E_NO_STATE_MSG, E_STALE_STATE_MSG } from './_internal.js';
 import { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
-import { joinStates, join as joinPatch } from '../services/JoinReducer.js';
+import { joinStates, applyWithDiff, applyWithReceipt } from '../services/JoinReducer.js';
 import { orsetElements } from '../crdt/ORSet.js';
-import { vvIncrement } from '../crdt/VersionVector.js';
+import { vvIncrement, vvClone } from '../crdt/VersionVector.js';
 import { buildWriterRef, buildWritersPrefix, parseWriterIdFromRef } from '../utils/RefLayout.js';
 import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
 import { Writer } from './Writer.js';
@@ -220,15 +220,16 @@ export async function _onPatchCommitted(writerId, { patch: committed, sha } = {}
   // Only when the cache is clean — applying a patch to stale state would be incorrect
   if (this._cachedState && !this._stateDirty && committed && sha) {
     let tickReceipt = null;
+    /** @type {import('../types/PatchDiff.js').PatchDiff|null} */
+    let diff = null;
     if (this._auditService) {
-      const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (
-        joinPatch(this._cachedState, /** @type {Parameters<typeof joinPatch>[1]} */ (committed), sha, true)
-      );
+      const result = applyWithReceipt(this._cachedState, committed, sha);
       tickReceipt = result.receipt;
     } else {
-      joinPatch(this._cachedState, /** @type {Parameters<typeof joinPatch>[1]} */ (committed), sha);
+      const result = applyWithDiff(this._cachedState, committed, sha);
+      diff = result.diff;
     }
-    await this._setMaterializedState(this._cachedState);
+    await this._setMaterializedState(this._cachedState, { diff });
     // Update provenance index with new patch
     if (this._provenanceIndex) {
       this._provenanceIndex.addPatch(sha, /** @type {string[]|undefined} */ (committed.reads), /** @type {string[]|undefined} */ (committed.writes));
@@ -247,6 +248,7 @@ export async function _onPatchCommitted(writerId, { patch: committed, sha } = {}
     }
   } else {
     this._stateDirty = true;
+    this._cachedViewHash = null;
     if (this._auditService) {
       this._auditSkipCount++;
       this._logger?.warn('[warp:audit]', {
@@ -527,16 +529,22 @@ export function join(otherState) {
       !this._frontierEquals(this._cachedState.observedFrontier, mergedState.observedFrontier),
   };
 
-  // Update cached state
+  // Install merged state as canonical (B108 — cache coherence fix)
   this._cachedState = mergedState;
+  this._versionVector = vvClone(mergedState.observedFrontier);
 
-  // Invalidate derived caches (C1) — join changes underlying state
-  this._materializedGraph = null;
+  // Build adjacency synchronously (crypto hash deferred to next _buildView)
+  const adjacency = this._buildAdjacency(mergedState);
+  this._materializedGraph = { state: mergedState, stateHash: null, adjacency };
+
+  // Clear index caches — queries degrade to linear scan until next _buildView
   this._logicalIndex = null;
   this._propertyReader = null;
   this._cachedViewHash = null;
   this._cachedIndexTree = null;
-  this._stateDirty = true;
+
+  // State IS fresh — don't force rematerialization
+  this._stateDirty = false;
 
   return { state: mergedState, receipt };
 }

package/src/infrastructure/adapters/GitGraphAdapter.js

@@ -135,29 +135,6 @@ function isDanglingObjectError(err) {
   );
 }
 
-/**
- * Checks whether a Git ref exists without resolving it.
- * @param {function(Object): Promise<string>} execute - The git command executor function
- * @param {string} ref - The ref to check (e.g., 'refs/warp/events/writers/alice')
- * @returns {Promise<boolean>} True if the ref exists, false otherwise
- * @throws {Error} If the git command fails for reasons other than a missing ref
- */
-async function refExists(execute, ref) {
-  try {
-    await execute({ args: ['show-ref', '--verify', '--quiet', ref] });
-    return true;
-  } catch (err) {
-    const gitErr = /** @type {GitError} */ (err);
-    if (getExitCode(gitErr) === 1) {
-      return false;
-    }
-    if (isDanglingObjectError(gitErr)) {
-      return false;
-    }
-    throw err;
-  }
-}
-
 /**
  * Concrete implementation of {@link GraphPersistencePort} using Git plumbing commands.
  *
@@ -262,26 +239,37 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   }
 
   /**
-   * Creates a commit pointing to the empty tree.
-   * @param {Object} options
-   * @param {string} options.message - The commit message (typically CBOR-encoded patch data)
-   * @param {string[]} [options.parents=[]] - Parent commit SHAs
-   * @param {boolean} [options.sign=false] - Whether to GPG-sign the commit
-   * @returns {Promise<string>} The SHA of the created commit
-   * @throws {Error} If any parent OID is invalid
+   * Shared helper for commit creation. Validates parents, builds args, and
+   * executes `git commit-tree` with retry.
+   * @param {{ tree: string, parents: string[], message: string, sign: boolean }} opts
+   * @returns {Promise<string>} The created commit SHA
+   * @private
    */
-  async commitNode({ message, parents = [], sign = false }) {
+  async _createCommit({ tree, parents, message, sign }) {
     for (const p of parents) {
       this._validateOid(p);
     }
     const parentArgs = parents.flatMap(p => ['-p', p]);
     const signArgs = sign ? ['-S'] : [];
-    const args = ['commit-tree', this.emptyTree, ...parentArgs, ...signArgs, '-m', message];
+    const args = ['commit-tree', tree, ...parentArgs, ...signArgs, '-m', message];
 
     const oid = await this._executeWithRetry({ args });
     return oid.trim();
   }
 
+  /**
+   * Creates a commit pointing to the empty tree.
+   * @param {Object} options
+   * @param {string} options.message - The commit message (typically CBOR-encoded patch data)
+   * @param {string[]} [options.parents=[]] - Parent commit SHAs
+   * @param {boolean} [options.sign=false] - Whether to GPG-sign the commit
+   * @returns {Promise<string>} The SHA of the created commit
+   * @throws {Error} If any parent OID is invalid
+   */
+  async commitNode({ message, parents = [], sign = false }) {
+    return await this._createCommit({ tree: this.emptyTree, parents, message, sign });
+  }
+
   /**
    * Creates a commit pointing to a custom tree (not the empty tree).
    * Used for WARP patch commits that have attachment trees.
@@ -294,15 +282,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
    */
   async commitNodeWithTree({ treeOid, parents = [], message, sign = false }) {
     this._validateOid(treeOid);
-    for (const p of parents) {
-      this._validateOid(p);
-    }
-    const parentArgs = parents.flatMap(p => ['-p', p]);
-    const signArgs = sign ? ['-S'] : [];
-    const args = ['commit-tree', treeOid, ...parentArgs, ...signArgs, '-m', message];
-
-    const oid = await this._executeWithRetry({ args });
-    return oid.trim();
+    return await this._createCommit({ tree: treeOid, parents, message, sign });
   }
 
   /**
@@ -402,8 +382,13 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     // -z flag ensures NUL-terminated output and ignores i18n.logOutputEncoding config
     const args = ['log', '-z', `-${limit}`];
     if (format) {
-      // Strip NUL bytes from format - git -z flag handles NUL termination automatically
-      // Node.js child_process rejects args containing null bytes
+      // Strip NUL (\x00) bytes from the caller-supplied format string.
+      // Why: Git's -z flag uses NUL as the record terminator in its output.
+      // If a format string contains literal NUL bytes (e.g. from %x00 expansion
+      // or caller-constructed strings), they corrupt the NUL-delimited output
+      // stream, causing downstream parsers to split records at the wrong
+      // boundaries. Additionally, Node.js child_process rejects argv entries
+      // that contain null bytes, so passing them through would throw.
       // eslint-disable-next-line no-control-regex
       const cleanFormat = format.replace(/\x00/g, '');
       args.push(`--format=${cleanFormat}`);
@@ -415,6 +400,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Validates that a ref is safe to use in git commands.
    * Delegates to shared validation in adapterValidation.js.
+   *
+   * Instance method for port interface conformance and test mockability.
    * @param {string} ref - The ref to validate
    * @throws {Error} If ref contains invalid characters, is too long, or starts with -/--
    * @private
@@ -451,7 +438,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
 
   /**
    * Reads a tree and returns a map of path to content.
-   * Processes blobs sequentially to avoid spawning too many concurrent reads.
+   * Reads blobs in batches of 16 to balance concurrency against fd/process limits.
    * @param {string} treeOid - The tree OID to read
    * @returns {Promise<Record<string, Buffer>>} Map of file path to blob content
    */
@@ -459,9 +446,16 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     const oids = await this.readTreeOids(treeOid);
     /** @type {Record<string, Buffer>} */
     const files = {};
-    // Process sequentially to avoid spawning thousands of concurrent readBlob calls
-    for (const [path, oid] of Object.entries(oids)) {
-      files[path] = await this.readBlob(oid);
+    const entries = Object.entries(oids);
+    const BATCH_SIZE = 16;
+    for (let i = 0; i < entries.length; i += BATCH_SIZE) {
+      const batch = entries.slice(i, i + BATCH_SIZE);
+      const results = await Promise.all(
+        batch.map(([, oid]) => this.readBlob(oid))
+      );
+      for (let j = 0; j < batch.length; j++) {
+        files[batch[j][0]] = results[j];
+      }
     }
     return files;
   }
@@ -539,20 +533,21 @@ export default class GitGraphAdapter extends GraphPersistencePort {
    */
   async readRef(ref) {
     this._validateRef(ref);
-    const exists = await refExists(this._executeWithRetry.bind(this), ref);
-    if (!exists) {
-      return null;
-    }
     try {
+      // --verify ensures exactly one revision is resolved; --quiet suppresses
+      // error messages and makes exit code 1 (not 128) the indicator for
+      // "ref does not exist", simplifying downstream handling.
       const oid = await this._executeWithRetry({
-        args: ['rev-parse', ref]
+        args: ['rev-parse', '--verify', '--quiet', ref]
       });
       return oid.trim();
     } catch (err) {
       const gitErr = /** @type {GitError} */ (err);
+      // Exit code 1: ref does not exist (normal with --verify --quiet)
       if (getExitCode(gitErr) === 1) {
         return null;
       }
+      // Exit code 128 with dangling-object stderr: ref exists but target is missing
       if (isDanglingObjectError(gitErr)) {
         return null;
       }
@@ -602,6 +597,10 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Validates that an OID is safe to use in git commands.
    * Delegates to shared validation in adapterValidation.js.
+   *
+   * Exists as a method (rather than inlining the import) so tests can
+   * spy/stub validation independently and so future adapters sharing
+   * the same port interface can override validation rules.
    * @param {string} oid - The OID to validate
    * @throws {Error} If OID is invalid
    * @private
@@ -613,6 +612,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Validates that a limit is a safe positive integer.
    * Delegates to shared validation in adapterValidation.js.
+   *
+   * Instance method for port interface conformance and test mockability.
    * @param {number} limit - The limit to validate
    * @throws {Error} If limit is invalid
    * @private
@@ -759,6 +760,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Validates that a config key is safe to use in git commands.
    * Delegates to shared validation in adapterValidation.js.
+   *
+   * Instance method for port interface conformance and test mockability.
    * @param {string} key - The config key to validate
    * @throws {Error} If key is invalid
    * @private

package/src/infrastructure/codecs/CborCodec.js

@@ -96,6 +96,8 @@ function isPlainObject(value) {
 function sortPlainObject(obj) {
   /** @type {Record<string, unknown>} */
   const sorted = {};
+  // Key sort ensures deterministic CBOR encoding regardless of insertion order.
+  // Required for content-addressed storage where byte-identical encoding is critical.
   const keys = Object.keys(obj).sort();
   for (const key of keys) {
     sorted[key] = sortKeys(obj[key]);

package/src/domain/utils/fnv1a.js

@@ -1,20 +0,0 @@
-/**
- * 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
-}