@git-stunts/git-warp 12.2.0 → 12.3.0

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]', {
@@ -289,6 +291,7 @@ export async function writer(writerId) {
     onDeleteWithData: this._onDeleteWithData,
     onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts))),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }
 
@@ -347,6 +350,7 @@ export async function createWriter(opts = {}) {
     onDeleteWithData: this._onDeleteWithData,
     onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts))),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }
 
@@ -527,16 +531,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
-}