@git-stunts/git-warp 12.1.0 → 12.2.1

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);
@@ -167,6 +204,7 @@ export function _buildView(state, stateHash, diff) {
     this._propertyReader = result.propertyReader;
     this._cachedViewHash = stateHash;
     this._cachedIndexTree = result.tree;
+    this._indexDegraded = false;
 
     const provider = new BitmapNeighborProvider({ logicalIndex: result.logicalIndex });
     if (this._materializedGraph) {
@@ -176,6 +214,7 @@ export function _buildView(state, stateHash, diff) {
     this._logger?.warn('[warp] index build failed, falling back to linear scan', {
       error: /** @type {Error} */ (err).message,
     });
+    this._indexDegraded = true;
     this._logicalIndex = null;
     this._propertyReader = null;
     this._cachedIndexTree = null;
@@ -220,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()];
@@ -234,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
@@ -257,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 */ }
@@ -320,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);
 }
 
 /**
@@ -457,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,8 +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);
+
+  // 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;
+
+  // State IS fresh — don't force rematerialization
+  this._stateDirty = false;
 
   return { state: mergedState, receipt };
 }

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

@@ -319,9 +319,9 @@ export function query() {
  */
 export async function observer(name, config) {
   /** @param {unknown} m */
-  const isValidMatch = (m) => typeof m === 'string' || (Array.isArray(m) && m.every(/** @param {unknown} i */ i => typeof i === 'string'));
+  const isValidMatch = (m) => typeof m === 'string' || (Array.isArray(m) && m.length > 0 && m.every(/** @param {unknown} i */ i => typeof i === 'string'));
   if (!config || !isValidMatch(config.match)) {
-    throw new Error('observer config.match must be a string or array of strings');
+    throw new Error('observer config.match must be a non-empty string or non-empty array of strings');
   }
   await this._ensureFreshState();
   return new ObserverView({ name, config, graph: this });
@@ -332,11 +332,11 @@ export async function observer(name, config) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {Object} configA - Observer configuration for A
- * @param {string} configA.match - Glob pattern for visible nodes
+ * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
  * @param {string[]} [configA.expose] - Property keys to include
  * @param {string[]} [configA.redact] - Property keys to exclude
  * @param {Object} configB - Observer configuration for B
- * @param {string} configB.match - Glob pattern for visible nodes
+ * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
  * @param {string[]} [configB.expose] - Property keys to include
  * @param {string[]} [configB.redact] - Property keys to exclude
  * @returns {Promise<{cost: number, breakdown: {nodeLoss: number, edgeLoss: number, propLoss: number}}>}

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

@@ -6,6 +6,7 @@
  */
 
 import { diffStates, isEmptyDiff } from '../services/StateDiff.js';
+import { matchGlob } from '../utils/matchGlob.js';
 
 /**
  * Subscribes to graph changes.
@@ -101,13 +102,13 @@ export function subscribe({ onChange, onError, replay = false }) {
  * be at least 1000ms.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {string} pattern - Glob pattern (e.g., 'user:*', 'order:123', '*')
+ * @param {string|string[]} pattern - Glob pattern(s) (e.g., 'user:*', 'order:123', '*')
  * @param {Object} options - Watch options
  * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with filtered diff when matching changes occur
  * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
  * @param {number} [options.poll] - Poll interval in ms (min 1000); checks frontier and auto-materializes
  * @returns {{unsubscribe: () => void}} Subscription handle
- * @throws {Error} If pattern is not a string
+ * @throws {Error} If pattern is not a string or array of strings
  * @throws {Error} If onChange is not a function
  * @throws {Error} If poll is provided but less than 1000
  *
@@ -130,31 +131,22 @@ export function subscribe({ onChange, onError, replay = false }) {
  * unsubscribe();
  */
 export function watch(pattern, { onChange, onError, poll }) {
-  if (typeof pattern !== 'string') {
-    throw new Error('pattern must be a string');
+  const isValidPattern = (/** @type {string|string[]} */ p) => typeof p === 'string' || (Array.isArray(p) && p.length > 0 && p.every(i => typeof i === 'string'));
+  if (!isValidPattern(pattern)) {
+    throw new Error('pattern must be a non-empty string or non-empty array of strings');
   }
   if (typeof onChange !== 'function') {
     throw new Error('onChange must be a function');
   }
   if (poll !== undefined) {
-    if (typeof poll !== 'number' || poll < 1000) {
-      throw new Error('poll must be a number >= 1000');
+    if (typeof poll !== 'number' || !Number.isFinite(poll) || poll < 1000) {
+      throw new Error('poll must be a finite number >= 1000');
     }
   }
 
-  // Pattern matching: same logic as QueryBuilder.match()
-  // Pre-compile pattern matcher once for performance
+  // Pattern matching logic
   /** @type {(nodeId: string) => boolean} */
-  let matchesPattern;
-  if (pattern === '*') {
-    matchesPattern = () => true;
-  } else if (pattern.includes('*')) {
-    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
-    matchesPattern = (/** @type {string} */ nodeId) => regex.test(nodeId);
-  } else {
-    matchesPattern = (/** @type {string} */ nodeId) => nodeId === pattern;
-  }
+  const matchesPattern = (nodeId) => matchGlob(pattern, nodeId);
 
   // Filtered onChange that only passes matching changes
   const filteredOnChange = (/** @type {import('../services/StateDiff.js').StateDiffResult} */ diff) => {
@@ -194,7 +186,7 @@ export function watch(pattern, { onChange, onError, poll }) {
   /** @type {ReturnType<typeof setInterval>|null} */
   let pollIntervalId = null;
   let pollInFlight = false;
-  if (poll) {
+  if (poll !== undefined) {
     pollIntervalId = setInterval(() => {
       if (pollInFlight) {
         return;

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;
       }
@@ -575,8 +570,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   async compareAndSwapRef(ref, newOid, expectedOid) {
     this._validateRef(ref);
     this._validateOid(newOid);
-    // null means "ref must not exist" → use zero OID
-    const oldArg = expectedOid || '0'.repeat(newOid.length);
+    // null means "ref must not exist" → use zero OID (always 40 chars for SHA-1)
+    const oldArg = expectedOid || '0'.repeat(40);
     if (expectedOid) {
       this._validateOid(expectedOid);
     }
@@ -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
-}