@git-stunts/git-warp 12.2.0 → 12.3.0

package/src/domain/services/PatchBuilderV2.js

@@ -20,10 +20,12 @@ import {
   createNodeRemoveV2,
   createEdgeAddV2,
   createEdgeRemoveV2,
-  createPropSetV2,
+  createNodePropSetV2,
+  createEdgePropSetV2,
   createPatchV2,
 } from '../types/WarpTypesV2.js';
-import { encodeEdgeKey, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
+import { encodeEdgeKey, FIELD_SEPARATOR, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
+import { lowerCanonicalOp } from './OpNormalizer.js';
 import { encodePatchMessage, decodePatchMessage, detectMessageKind } from './WarpMessageCodec.js';
 import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
@@ -46,9 +48,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);
     }
   }
@@ -63,6 +68,30 @@ function findAttachedData(state, nodeId) {
   return { edges, props, hasData: edges.length > 0 || props.length > 0 };
 }
 
+/**
+ * Validates that an identifier does not contain reserved bytes that would
+ * make the legacy edge-property encoding ambiguous.
+ *
+ * Rejects:
+ * - Identifiers containing \0 (field separator)
+ * - Identifiers starting with \x01 (edge property prefix)
+ *
+ * @param {string} value - Identifier to validate
+ * @param {string} label - Human-readable label for error messages
+ * @throws {Error} If the identifier contains reserved bytes
+ */
+function _assertNoReservedBytes(value, label) {
+  if (typeof value !== 'string') {
+    throw new Error(`${label} must be a string, got ${typeof value}`);
+  }
+  if (value.includes(FIELD_SEPARATOR)) {
+    throw new Error(`${label} must not contain null bytes (\\0): ${JSON.stringify(value)}`);
+  }
+  if (value.length > 0 && value[0] === EDGE_PROP_PREFIX) {
+    throw new Error(`${label} must not start with reserved prefix \\x01: ${JSON.stringify(value)}`);
+  }
+}
+
 /**
  * Fluent builder for creating WARP v5 patches with dots and observed-remove semantics.
  */
@@ -82,7 +111,7 @@ export class PatchBuilderV2 {
    * @param {Function|null} [options.onCommitSuccess] - Callback invoked after successful commit
    * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
    * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @param {{ warn: Function }} [options.logger] - Logger for non-fatal warnings
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for non-fatal warnings
    */
   constructor({ persistence, graphName, writerId, lamport, versionVector, getCurrentState, expectedParentSha = null, onCommitSuccess = null, onDeleteWithData = 'warn', codec, logger }) {
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */
@@ -130,7 +159,7 @@ export class PatchBuilderV2 {
     /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
 
-    /** @type {{ warn: Function }} */
+    /** @type {import('../../ports/LoggerPort.js').default} */
     this._logger = logger || nullLogger;
 
     /**
@@ -141,17 +170,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).
@@ -163,6 +198,15 @@ 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;
   }
 
   /**
@@ -182,6 +226,16 @@ export class PatchBuilderV2 {
     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');
+    }
+  }
+
   /**
    * Adds a node to the graph.
    *
@@ -204,6 +258,8 @@ export class PatchBuilderV2 {
    *   .addEdge('user:alice', 'user:bob', 'follows');
    */
   addNode(nodeId) {
+    this._assertNotCommitted();
+    _assertNoReservedBytes(nodeId, 'nodeId');
     const dot = vvIncrement(this._vv, this._writerId);
     this._ops.push(createNodeAddV2(nodeId, dot));
     // Provenance: NodeAdd writes the node
@@ -238,6 +294,7 @@ 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._getSnapshotState();
 
@@ -250,7 +307,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);
       }
     }
 
@@ -275,8 +332,7 @@ export class PatchBuilderV2 {
         }
 
         if (this._onDeleteWithData === 'warn') {
-          // eslint-disable-next-line no-console
-          console.warn(
+          this._logger.warn(
             `[warp] Deleting node '${nodeId}' which has attached data (${summary}). ` +
             `Orphaned data will remain in state.`
           );
@@ -287,7 +343,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;
   }
 
@@ -318,13 +374,17 @@ export class PatchBuilderV2 {
    *   .addEdge('user:alice', 'user:bob', 'collaborates_with');
    */
   addEdge(from, to, label) {
+    this._assertNotCommitted();
+    _assertNoReservedBytes(from, 'from node ID');
+    _assertNoReservedBytes(to, 'to node ID');
+    _assertNoReservedBytes(label, 'edge label');
     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;
   }
@@ -355,13 +415,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._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;
   }
 
@@ -395,10 +456,13 @@ export class PatchBuilderV2 {
    *   .setProperty('user:alice', 'age', 30);
    */
   setProperty(nodeId, key, value) {
-    // 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._assertNotCommitted();
+    _assertNoReservedBytes(nodeId, 'nodeId');
+    _assertNoReservedBytes(key, 'property key');
+    // Canonical NodePropSet — lowered to raw PropSet at commit time
+    this._ops.push(createNodePropSetV2(nodeId, key, value));
+    // Provenance: NodePropSet reads the node (implicit existence check) and writes the node
+    this._observedOperands.add(nodeId);
     this._writes.add(nodeId);
     return this;
   }
@@ -441,6 +505,11 @@ export class PatchBuilderV2 {
    *   .setEdgeProperty('user:alice', 'user:bob', 'follows', 'public', true);
    */
   setEdgeProperty(from, to, label, key, value) {
+    this._assertNotCommitted();
+    _assertNoReservedBytes(from, 'from node ID');
+    _assertNoReservedBytes(to, 'to node ID');
+    _assertNoReservedBytes(label, 'edge label');
+    _assertNoReservedBytes(key, 'property key');
     // Validate edge exists in this patch or in current state
     const ek = encodeEdgeKey(from, to, label);
     if (!this._edgesAdded.has(ek)) {
@@ -450,15 +519,11 @@ export class PatchBuilderV2 {
       }
     }
 
-    // Encode the edge identity as the "node" field with the \x01 prefix.
-    // When JoinReducer processes: encodePropKey(op.node, op.key)
-    //   = `\x01from\0to\0label` + `\0` + key
-    //   = `\x01from\0to\0label\0key`
-    //   = encodeEdgePropKey(from, to, label, key)
-    const edgeNode = `${EDGE_PROP_PREFIX}${from}\0${to}\0${label}`;
-    this._ops.push(createPropSetV2(edgeNode, key, value));
-    // Provenance: setEdgeProperty reads the edge (implicit existence check) and writes the edge
-    this._reads.add(ek);
+    // Canonical EdgePropSet — lowered to legacy raw PropSet at commit time
+    this._ops.push(createEdgePropSetV2(from, to, label, key, value));
+    this._hasEdgeProps = true;
+    // Provenance: EdgePropSet reads the edge (implicit existence check) and writes the edge
+    this._observedOperands.add(ek);
     this._writes.add(ek);
     return this;
   }
@@ -479,6 +544,10 @@ export class PatchBuilderV2 {
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachContent(nodeId, content) {
+    this._assertNotCommitted();
+    // Validate identifiers before writing blob to avoid orphaned blobs
+    _assertNoReservedBytes(nodeId, 'nodeId');
+    _assertNoReservedBytes(CONTENT_PROPERTY_KEY, 'key');
     const oid = await this._persistence.writeBlob(content);
     this.setProperty(nodeId, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -496,6 +565,12 @@ export class PatchBuilderV2 {
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachEdgeContent(from, to, label, content) {
+    this._assertNotCommitted();
+    // Validate identifiers before writing blob to avoid orphaned blobs
+    _assertNoReservedBytes(from, 'from');
+    _assertNoReservedBytes(to, 'to');
+    _assertNoReservedBytes(label, 'label');
+    _assertNoReservedBytes(CONTENT_PROPERTY_KEY, 'key');
     const oid = await this._persistence.writeBlob(content);
     this.setEdgeProperty(from, to, label, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -521,14 +596,16 @@ 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;
+    // Lower canonical ops to raw form for the persisted patch
+    const rawOps = /** @type {import('../types/WarpTypesV2.js').RawOpV2[]} */ (this._ops.map(lowerCanonicalOp));
     return createPatchV2({
       schema,
       writer: this._writerId,
       lamport: this._lamport,
       context: vvSerialize(this._vv),
-      ops: this._ops,
-      reads: [...this._reads].sort(),
+      ops: rawOps,
+      reads: [...this._observedOperands].sort(),
       writes: [...this._writes].sort(),
     });
   }
@@ -537,20 +614,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
@@ -578,115 +659,123 @@ 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;
+      // Lower canonical ops to raw form for the persisted patch
+      const rawOps = /** @type {import('../types/WarpTypesV2.js').RawOpV2[]} */ (this._ops.map(lowerCanonicalOp));
+      const patch = createPatchV2({
+        schema,
+        writer: this._writerId,
+        lamport,
+        context: vvSerialize(this._vv),
+        ops: rawOps,
+        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}):`, { error: 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;
   }
 
   /**
@@ -723,22 +812,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);
   }
 
   /**

package/src/domain/services/QueryBuilder.js

@@ -221,6 +221,10 @@ function deepFreeze(obj) {
 /**
  * Creates a deep clone of a value.
  *
+ * Results are deep-frozen to prevent accidental mutation of cached state.
+ * structuredClone is preferred; JSON round-trip is the fallback for
+ * environments without structuredClone support.
+ *
  * Attempts structuredClone first (Node 17+ / modern browsers), falls back
  * to JSON round-trip, and returns the original value if both fail (e.g.,
  * for values containing functions or circular references).

package/src/domain/services/SyncAuthService.js

@@ -68,6 +68,8 @@ export function buildCanonicalPayload({ keyId, method, path, timestamp, nonce, c
  */
 export async function signSyncRequest({ method, path, contentType, body, secret, keyId }, { crypto } = {}) {
   const c = crypto || defaultCrypto;
+  // Wall-clock timestamp required for HMAC replay protection (not a perf timer)
+  // eslint-disable-next-line no-restricted-syntax
   const timestamp = String(Date.now());
   const nonce = globalThis.crypto.randomUUID();
 
@@ -187,6 +189,7 @@ export default class SyncAuthService {
     this._mode = mode;
     this._crypto = crypto || defaultCrypto;
     this._logger = logger || nullLogger;
+    // eslint-disable-next-line no-restricted-syntax -- wall-clock fallback for HMAC verification
     this._wallClockMs = wallClockMs || (() => Date.now());
     this._maxClockSkewMs = typeof maxClockSkewMs === 'number' ? maxClockSkewMs : MAX_CLOCK_SKEW_MS;
     this._nonceCache = new LRUCache(nonceCapacity || DEFAULT_NONCE_CAPACITY);