@git-stunts/git-warp 12.1.0 → 12.2.1

package/src/domain/services/PatchBuilderV2.js

@@ -46,9 +46,12 @@ function findAttachedData(state, nodeId) {
   const edges = [];
   const props = [];
 
+  // Edge keys are encoded as "from\0to\0label". Check prefix for source
+  // and interior substring for target — avoids split() on every key.
+  const srcPrefix = `${nodeId}\0`;
+  const tgtInfix = `\0${nodeId}\0`;
   for (const key of orsetElements(state.edgeAlive)) {
-    const parts = key.split('\0');
-    if (parts[0] === nodeId || parts[1] === nodeId) {
+    if (key.startsWith(srcPrefix) || key.includes(tgtInfix)) {
       edges.push(key);
     }
   }
@@ -103,6 +106,15 @@ export class PatchBuilderV2 {
     /** @type {Function} */
     this._getCurrentState = getCurrentState; // Function to get current materialized state
 
+    /**
+     * Snapshot of state captured at construction time (C4).
+     * Lazily populated on first call to _getSnapshotState().
+     * Prevents TOCTOU races where concurrent writes change state
+     * between remove operations in the same patch.
+     * @type {import('./JoinReducer.js').WarpStateV5|null}
+     */
+    this._snapshotState = /** @type {import('./JoinReducer.js').WarpStateV5|null} */ (/** @type {unknown} */ (undefined)); // undefined = not yet captured
+
     /** @type {string|null} */
     this._expectedParentSha = expectedParentSha;
 
@@ -132,17 +144,23 @@ export class PatchBuilderV2 {
     this._contentBlobs = [];
 
     /**
-     * Nodes/edges read by this patch (for provenance tracking).
+     * Observed operands — entities whose current state was consulted to build
+     * this patch.
+     *
+     * Semantic model per operation type:
+     * - removeNode(id): observes node `id` (reads its OR-Set dots for tombstoning)
+     * - removeEdge(from, to, label): observes the edge key
+     * - addEdge(from, to, label): observes both endpoint nodes `from` and `to`
+     * - setProperty(nodeId, key, value): observes node `nodeId`
+     * - setEdgeProperty(from, to, label, key, value): observes the edge key
+     * - cascade-generated EdgeRemove: observes the edge key
      *
-     * Design note: "reads" track observed-dot dependencies — entities whose
-     * state was consulted to build this patch. Remove operations read the
-     * entity to observe its dots (OR-Set semantics). "Writes" track new data
-     * creation (adds). This distinction enables finer-grained provenance
-     * queries like "which patches wrote to X?" vs "which patches depended on X?"
+     * The public getter `.reads` and the serialized patch field `reads` retain
+     * the historical name for backward compatibility.
      *
      * @type {Set<string>}
      */
-    this._reads = new Set();
+    this._observedOperands = new Set();
 
     /**
      * Nodes/edges written by this patch (for provenance tracking).
@@ -154,6 +172,42 @@ export class PatchBuilderV2 {
      * @type {Set<string>}
      */
     this._writes = new Set();
+
+    /** @type {boolean} Whether any edge-property ops have been added (schema 3 flag cache). */
+    this._hasEdgeProps = false;
+
+    /** @type {boolean} */
+    this._committed = false;
+
+    /** @type {boolean} */
+    this._committing = false;
+  }
+
+  /**
+   * Returns a snapshot of the current state, captured lazily on first call (C4).
+   *
+   * All remove operations within this patch observe dots from the same
+   * state snapshot, preventing TOCTOU races where concurrent writers
+   * change state between operations.
+   *
+   * @returns {import('./JoinReducer.js').WarpStateV5|null}
+   * @private
+   */
+  _getSnapshotState() {
+    if (this._snapshotState === undefined) {
+      this._snapshotState = this._getCurrentState() || null;
+    }
+    return this._snapshotState;
+  }
+
+  /**
+   * Throws if this builder is no longer open for mutation.
+   * @private
+   */
+  _assertNotCommitted() {
+    if (this._committed || this._committing) {
+      throw new Error('PatchBuilder already committed — create a new builder');
+    }
   }
 
   /**
@@ -178,6 +232,7 @@ export class PatchBuilderV2 {
    *   .addEdge('user:alice', 'user:bob', 'follows');
    */
   addNode(nodeId) {
+    this._assertNotCommitted();
     const dot = vvIncrement(this._vv, this._writerId);
     this._ops.push(createNodeAddV2(nodeId, dot));
     // Provenance: NodeAdd writes the node
@@ -212,8 +267,9 @@ export class PatchBuilderV2 {
    * builder.removeNode('user:alice'); // Also removes all connected edges
    */
   removeNode(nodeId) {
+    this._assertNotCommitted();
     // Get observed dots from current state (orsetGetDots returns already-encoded dot strings)
-    const state = this._getCurrentState();
+    const state = this._getSnapshotState();
 
     // Cascade mode: auto-generate EdgeRemove ops for all connected edges before NodeRemove.
     // Generated ops appear in the patch for auditability.
@@ -224,7 +280,7 @@ export class PatchBuilderV2 {
         const edgeDots = [...orsetGetDots(state.edgeAlive, edgeKey)];
         this._ops.push(createEdgeRemoveV2(from, to, label, edgeDots));
         // Provenance: cascade-generated EdgeRemove reads the edge key (to observe its dots)
-        this._reads.add(edgeKey);
+        this._observedOperands.add(edgeKey);
       }
     }
 
@@ -261,7 +317,7 @@ export class PatchBuilderV2 {
     const observedDots = state ? [...orsetGetDots(state.nodeAlive, nodeId)] : [];
     this._ops.push(createNodeRemoveV2(nodeId, observedDots));
     // Provenance: NodeRemove reads the node (to observe its dots)
-    this._reads.add(nodeId);
+    this._observedOperands.add(nodeId);
     return this;
   }
 
@@ -292,13 +348,14 @@ export class PatchBuilderV2 {
    *   .addEdge('user:alice', 'user:bob', 'collaborates_with');
    */
   addEdge(from, to, label) {
+    this._assertNotCommitted();
     const dot = vvIncrement(this._vv, this._writerId);
     this._ops.push(createEdgeAddV2(from, to, label, dot));
     const edgeKey = encodeEdgeKey(from, to, label);
     this._edgesAdded.add(edgeKey);
     // Provenance: EdgeAdd reads both endpoint nodes, writes the edge key
-    this._reads.add(from);
-    this._reads.add(to);
+    this._observedOperands.add(from);
+    this._observedOperands.add(to);
     this._writes.add(edgeKey);
     return this;
   }
@@ -329,13 +386,14 @@ export class PatchBuilderV2 {
    *   .removeNode('user:alice');
    */
   removeEdge(from, to, label) {
+    this._assertNotCommitted();
     // Get observed dots from current state (orsetGetDots returns already-encoded dot strings)
-    const state = this._getCurrentState();
+    const state = this._getSnapshotState();
     const edgeKey = encodeEdgeKey(from, to, label);
     const observedDots = state ? [...orsetGetDots(state.edgeAlive, edgeKey)] : [];
     this._ops.push(createEdgeRemoveV2(from, to, label, observedDots));
     // Provenance: EdgeRemove reads the edge key (to observe its dots)
-    this._reads.add(edgeKey);
+    this._observedOperands.add(edgeKey);
     return this;
   }
 
@@ -369,10 +427,11 @@ export class PatchBuilderV2 {
    *   .setProperty('user:alice', 'age', 30);
    */
   setProperty(nodeId, key, value) {
+    this._assertNotCommitted();
     // Props don't use dots - they use EventId from patch context
     this._ops.push(createPropSetV2(nodeId, key, value));
     // Provenance: PropSet reads the node (implicit existence check) and writes the node
-    this._reads.add(nodeId);
+    this._observedOperands.add(nodeId);
     this._writes.add(nodeId);
     return this;
   }
@@ -415,10 +474,11 @@ export class PatchBuilderV2 {
    *   .setEdgeProperty('user:alice', 'user:bob', 'follows', 'public', true);
    */
   setEdgeProperty(from, to, label, key, value) {
+    this._assertNotCommitted();
     // Validate edge exists in this patch or in current state
     const ek = encodeEdgeKey(from, to, label);
     if (!this._edgesAdded.has(ek)) {
-      const state = this._getCurrentState();
+      const state = this._getSnapshotState();
       if (!state || !orsetContains(state.edgeAlive, ek)) {
         throw new Error(`Cannot set property on unknown edge (${from} → ${to} [${label}]): add the edge first`);
       }
@@ -431,8 +491,9 @@ export class PatchBuilderV2 {
     //   = encodeEdgePropKey(from, to, label, key)
     const edgeNode = `${EDGE_PROP_PREFIX}${from}\0${to}\0${label}`;
     this._ops.push(createPropSetV2(edgeNode, key, value));
+    this._hasEdgeProps = true;
     // Provenance: setEdgeProperty reads the edge (implicit existence check) and writes the edge
-    this._reads.add(ek);
+    this._observedOperands.add(ek);
     this._writes.add(ek);
     return this;
   }
@@ -453,6 +514,7 @@ export class PatchBuilderV2 {
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachContent(nodeId, content) {
+    this._assertNotCommitted();
     const oid = await this._persistence.writeBlob(content);
     this.setProperty(nodeId, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -470,6 +532,7 @@ export class PatchBuilderV2 {
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachEdgeContent(from, to, label, content) {
+    this._assertNotCommitted();
     const oid = await this._persistence.writeBlob(content);
     this.setEdgeProperty(from, to, label, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -495,14 +558,14 @@ export class PatchBuilderV2 {
    *   - `ops`: Array of operations (NodeAdd, NodeRemove, EdgeAdd, EdgeRemove, PropSet)
    */
   build() {
-    const schema = this._ops.some(op => op.type === 'PropSet' && op.node.charCodeAt(0) === 1) ? 3 : 2;
+    const schema = this._hasEdgeProps ? 3 : 2;
     return createPatchV2({
       schema,
       writer: this._writerId,
       lamport: this._lamport,
       context: vvSerialize(this._vv),
       ops: this._ops,
-      reads: [...this._reads].sort(),
+      reads: [...this._observedOperands].sort(),
       writes: [...this._writes].sort(),
     });
   }
@@ -511,20 +574,24 @@ export class PatchBuilderV2 {
    * Commits the patch to the graph.
    *
    * This method performs the following steps atomically:
-   * 1. Validates the patch is non-empty
-   * 2. Checks for concurrent modifications (compare-and-swap on writer ref)
-   * 3. Calculates the next lamport timestamp from the parent commit
-   * 4. Builds the PatchV2 structure with the resolved lamport
-   * 5. Encodes the patch as CBOR and writes it as a Git blob
-   * 6. Creates a Git tree containing the patch blob
-   * 7. Creates a commit with proper trailers linking to the parent
-   * 8. Updates the writer ref to point to the new commit
-   * 9. Invokes the success callback if provided (for eager re-materialization)
+   * 1. Verifies this builder is still open (not committed and not in-flight)
+   * 2. Validates the patch is non-empty
+   * 3. Checks for concurrent modifications (compare-and-swap on writer ref)
+   * 4. Calculates the next lamport timestamp from the parent commit
+   * 5. Builds the PatchV2 structure with the resolved lamport
+   * 6. Encodes the patch as CBOR and writes it as a Git blob
+   * 7. Creates a Git tree containing the patch blob
+   * 8. Creates a commit with proper trailers linking to the parent
+   * 9. Updates the writer ref to point to the new commit
+   * 10. Invokes the success callback if provided (for eager re-materialization)
    *
    * The commit is written to the writer's patch chain at:
    * `refs/warp/<graphName>/writers/<writerId>`
    *
    * @returns {Promise<string>} The commit SHA of the new patch commit
+   * @throws {Error} If this builder has already been committed, or a commit
+   *   is currently in-flight on this builder.
+   *   Message: `"PatchBuilder already committed — create a new builder"`
    * @throws {Error} If the patch is empty (no operations were added).
    *   Message: `"Cannot commit empty patch: no operations added"`
    * @throws {WriterError} If a concurrent commit was detected (another process
@@ -552,115 +619,122 @@ export class PatchBuilderV2 {
    * }
    */
   async commit() {
-    // 1. Reject empty patches
-    if (this._ops.length === 0) {
-      throw new Error('Cannot commit empty patch: no operations added');
-    }
+    this._assertNotCommitted();
+    this._committing = true;
+    try {
+      // 2. Reject empty patches
+      if (this._ops.length === 0) {
+        throw new Error('Cannot commit empty patch: no operations added');
+      }
 
-    // 2. Race detection: check if writer ref has advanced since builder creation
-    const writerRef = buildWriterRef(this._graphName, this._writerId);
-    const currentRefSha = await this._persistence.readRef(writerRef);
-
-    if (currentRefSha !== this._expectedParentSha) {
-      const err = /** @type {WriterError & { expectedSha: string|null, actualSha: string|null }} */ (new WriterError(
-        'WRITER_CAS_CONFLICT',
-        'Commit failed: writer ref was updated by another process. Re-materialize and retry.'
-      ));
-      err.expectedSha = this._expectedParentSha;
-      err.actualSha = currentRefSha;
-      throw err;
-    }
+      // 3. Race detection: check if writer ref has advanced since builder creation
+      const writerRef = buildWriterRef(this._graphName, this._writerId);
+      const currentRefSha = await this._persistence.readRef(writerRef);
+
+      if (currentRefSha !== this._expectedParentSha) {
+        const err = /** @type {WriterError & { expectedSha: string|null, actualSha: string|null }} */ (new WriterError(
+          'WRITER_CAS_CONFLICT',
+          'Commit failed: writer ref was updated by another process. Re-materialize and retry.'
+        ));
+        err.expectedSha = this._expectedParentSha;
+        err.actualSha = currentRefSha;
+        throw err;
+      }
+
+      // 4. Calculate lamport and parent from current ref state.
+      // Start from this._lamport (set by _nextLamport() in createPatch()), which already
+      // incorporates the globally-observed max Lamport tick via _maxObservedLamport.
+      // This ensures a first-time writer whose own chain is empty still commits at a tick
+      // above any previously-observed writer, winning LWW tiebreakers correctly.
+      let lamport = this._lamport;
+      let parentCommit = null;
+
+      if (currentRefSha) {
+        parentCommit = currentRefSha;
+        // Read the current patch commit to get its lamport timestamp and take the max,
+        // so the chain stays monotonic even if the ref advanced since createPatch().
+        const commitMessage = await this._persistence.showNode(currentRefSha);
+        const kind = detectMessageKind(commitMessage);
+
+        if (kind === 'patch') {
+          let patchInfo;
+          try {
+            patchInfo = decodePatchMessage(commitMessage);
+          } catch (err) {
+            throw new Error(
+              `Failed to parse lamport from writer ref ${writerRef}: ` +
+              `commit ${currentRefSha} has invalid patch message format`,
+              { cause: err }
+            );
+          }
+          lamport = Math.max(this._lamport, patchInfo.lamport + 1);
+        }
+        // Non-patch ref (checkpoint, etc.): keep lamport from this._lamport
+        // (already incorporates _maxObservedLamport), matching _nextLamport() behavior.
+      }
 
-    // 3. Calculate lamport and parent from current ref state.
-    // Start from this._lamport (set by _nextLamport() in createPatch()), which already
-    // incorporates the globally-observed max Lamport tick via _maxObservedLamport.
-    // This ensures a first-time writer whose own chain is empty still commits at a tick
-    // above any previously-observed writer, winning LWW tiebreakers correctly.
-    let lamport = this._lamport;
-    let parentCommit = null;
-
-    if (currentRefSha) {
-      parentCommit = currentRefSha;
-      // Read the current patch commit to get its lamport timestamp and take the max,
-      // so the chain stays monotonic even if the ref advanced since createPatch().
-      const commitMessage = await this._persistence.showNode(currentRefSha);
-      const kind = detectMessageKind(commitMessage);
-
-      if (kind === 'patch') {
-        let patchInfo;
+      // 5. Build PatchV2 structure with correct lamport
+      // Note: Dots were assigned using constructor lamport, but commit lamport may differ.
+      // For now, we use the calculated lamport for the patch metadata.
+      // The dots themselves are independent of patch lamport (they use VV counters).
+      const schema = this._hasEdgeProps ? 3 : 2;
+      // Use createPatchV2 for consistent patch construction (DRY with build())
+      const patch = createPatchV2({
+        schema,
+        writer: this._writerId,
+        lamport,
+        context: vvSerialize(this._vv),
+        ops: this._ops,
+        reads: [...this._observedOperands].sort(),
+        writes: [...this._writes].sort(),
+      });
+
+      // 6. Encode patch as CBOR and write as a Git blob
+      const patchCbor = this._codec.encode(patch);
+      const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
+
+      // 7. Create tree with the patch blob + any content blobs (deduplicated)
+      // Format for mktree: "mode type oid\tpath"
+      const treeEntries = [`100644 blob ${patchBlobOid}\tpatch.cbor`];
+      const uniqueBlobs = [...new Set(this._contentBlobs)];
+      for (const blobOid of uniqueBlobs) {
+        treeEntries.push(`100644 blob ${blobOid}\t_content_${blobOid}`);
+      }
+      const treeOid = await this._persistence.writeTree(treeEntries);
+
+      // 8. Create commit with proper trailers linking to the parent
+      const commitMessage = encodePatchMessage({
+        graph: this._graphName,
+        writer: this._writerId,
+        lamport,
+        patchOid: patchBlobOid,
+        schema,
+      });
+      const parents = parentCommit ? [parentCommit] : [];
+      const newCommitSha = await this._persistence.commitNodeWithTree({
+        treeOid,
+        parents,
+        message: commitMessage,
+      });
+
+      // 9. Update writer ref to point to new commit
+      await this._persistence.updateRef(writerRef, newCommitSha);
+
+      // 10. Notify success callback (updates graph's version vector + eager re-materialize)
+      if (this._onCommitSuccess) {
         try {
-          patchInfo = decodePatchMessage(commitMessage);
+          await this._onCommitSuccess({ patch, sha: newCommitSha });
         } catch (err) {
-          throw new Error(
-            `Failed to parse lamport from writer ref ${writerRef}: ` +
-            `commit ${currentRefSha} has invalid patch message format`,
-            { cause: err }
-          );
+          // Commit is already persisted — log but don't fail the caller.
+          this._logger.warn(`[warp] onCommitSuccess callback failed (sha=${newCommitSha}):`, err);
         }
-        lamport = Math.max(this._lamport, patchInfo.lamport + 1);
       }
-      // Non-patch ref (checkpoint, etc.): keep lamport from this._lamport
-      // (already incorporates _maxObservedLamport), matching _nextLamport() behavior.
-    }
-
-    // 4. Build PatchV2 structure with correct lamport
-    // Note: Dots were assigned using constructor lamport, but commit lamport may differ.
-    // For now, we use the calculated lamport for the patch metadata.
-    // The dots themselves are independent of patch lamport (they use VV counters).
-    const schema = this._ops.some(op => op.type === 'PropSet' && op.node.charCodeAt(0) === 1) ? 3 : 2;
-    // Use createPatchV2 for consistent patch construction (DRY with build())
-    const patch = createPatchV2({
-      schema,
-      writer: this._writerId,
-      lamport,
-      context: vvSerialize(this._vv),
-      ops: this._ops,
-      reads: [...this._reads].sort(),
-      writes: [...this._writes].sort(),
-    });
-
-    // 5. Encode patch as CBOR and write as a Git blob
-    const patchCbor = this._codec.encode(patch);
-    const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
-
-    // 6. Create tree with the patch blob + any content blobs (deduplicated)
-    // Format for mktree: "mode type oid\tpath"
-    const treeEntries = [`100644 blob ${patchBlobOid}\tpatch.cbor`];
-    const uniqueBlobs = [...new Set(this._contentBlobs)];
-    for (const blobOid of uniqueBlobs) {
-      treeEntries.push(`100644 blob ${blobOid}\t_content_${blobOid}`);
-    }
-    const treeOid = await this._persistence.writeTree(treeEntries);
 
-    // 7. Create commit with proper trailers linking to the parent
-    const commitMessage = encodePatchMessage({
-      graph: this._graphName,
-      writer: this._writerId,
-      lamport,
-      patchOid: patchBlobOid,
-      schema,
-    });
-    const parents = parentCommit ? [parentCommit] : [];
-    const newCommitSha = await this._persistence.commitNodeWithTree({
-      treeOid,
-      parents,
-      message: commitMessage,
-    });
-
-    // 8. Update writer ref to point to new commit
-    await this._persistence.updateRef(writerRef, newCommitSha);
-
-    // 9. Notify success callback (updates graph's version vector + eager re-materialize)
-    if (this._onCommitSuccess) {
-      try {
-        await this._onCommitSuccess({ patch, sha: newCommitSha });
-      } catch (err) {
-        // Commit is already persisted — log but don't fail the caller.
-        this._logger.warn(`[warp] onCommitSuccess callback failed (sha=${newCommitSha}):`, err);
-      }
+      this._committed = true;
+      return newCommitSha;
+    } finally {
+      this._committing = false;
     }
-
-    return newCommitSha;
   }
 
   /**
@@ -697,22 +771,13 @@ export class PatchBuilderV2 {
   }
 
   /**
-   * Gets the set of node/edge IDs read by this patch.
-   *
-   * Returns a frozen copy of the reads tracked for provenance. This includes:
-   * - Nodes read via `removeNode` (to observe dots)
-   * - Endpoint nodes read via `addEdge` (implicit existence reference)
-   * - Edge keys read via `removeEdge` (to observe dots)
-   * - Nodes read via `setProperty` (implicit existence reference)
-   * - Edge keys read via `setEdgeProperty` (implicit existence reference)
-   *
-   * Note: Returns a defensive copy to prevent external mutation of internal state.
-   * The returned Set is a copy, so mutations to it do not affect the builder.
-   *
-   * @returns {ReadonlySet<string>} Copy of node IDs and encoded edge keys that were read
+   * Gets the set of observed operands (entities whose state was consulted).
+   * Retains the `reads` name for API/serialization compatibility.
+   * Internal field is `_observedOperands`.
+   * @returns {ReadonlySet<string>}
    */
   get reads() {
-    return new Set(this._reads);
+    return new Set(this._observedOperands);
   }
 
   /**