@git-stunts/git-warp 12.1.0 → 12.2.0

package/README.md

@@ -8,10 +8,12 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.1.0
+## What's New in v12.2.0
 
-- **Multi-pattern glob support** — `graph.observer()`, `query().match()`, and `translationCost()` now accept an array of glob patterns (e.g. `['campaign:*', 'milestone:*']`). Nodes matching *any* pattern in the array are included (OR semantics).
-- **Release preflight** — `npm run release:preflight` runs a 10-check local gate (version agreement, CHANGELOG, README, lint, types, tests, pack dry-runs) before tagging.
+- **O(N log N) topological sort** — `topologicalSort()` now uses a MinHeap ready queue instead of sorted-array merging, eliminating the O(N²) hot path for large DAGs.
+- **QueryBuilder batching + memoization** — property fetches are now bounded (chunks of 100) and cached per-run, reducing redundant I/O across where-clauses, result building, and aggregation.
+- **Fast materialization guard** — `_materializeGraph()` skips full materialization when cached state is clean, improving query/traversal latency.
+- **Checkpoint `visible.cbor` removed** — checkpoints no longer write the unused visible-projection blob, saving one serialize + blob write per checkpoint.
 
 See the [full changelog](CHANGELOG.md) for details.
 

package/bin/warp-graph.js

@@ -9,6 +9,10 @@ import { COMMANDS } from './cli/commands/registry.js';
 
 const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query', 'seek'];
 
+// C8: Capture output format early so the error handler can use it
+const hasJsonFlag = process.argv.includes('--json');
+const hasNdjsonFlag = process.argv.includes('--ndjson');
+
 /**
  * CLI entry point. Parses arguments, dispatches to the appropriate command handler,
  * and emits the result to stdout (JSON or human-readable).
@@ -78,8 +82,8 @@ main().catch((error) => {
     payload.error.cause = error.cause instanceof Error ? error.cause.message : error.cause;
   }
 
-  if (process.argv.includes('--json') || process.argv.includes('--ndjson')) {
-    const stringify = process.argv.includes('--ndjson') ? compactStringify : stableStringify;
+  if (hasJsonFlag || hasNdjsonFlag) {
+    const stringify = hasNdjsonFlag ? compactStringify : stableStringify;
     process.stdout.write(`${stringify(payload)}\n`);
   } else {
     process.stderr.write(renderError(payload));

package/index.d.ts

@@ -1915,7 +1915,7 @@ export default class WarpGraph {
 
   /** Filtered watcher that only fires for changes matching a glob pattern. */
   watch(
-    pattern: string,
+    pattern: string | string[],
     options: {
       onChange: (diff: StateDiffResult) => void;
       onError?: (error: Error) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",

package/src/domain/WarpGraph.js

@@ -195,6 +195,9 @@ export default class WarpGraph {
 
     /** @type {Record<string, Uint8Array>|null} */
     this._cachedIndexTree = null;
+
+    /** @type {boolean} */
+    this._indexDegraded = false;
   }
 
   /**

package/src/domain/crdt/ORSet.js

@@ -290,19 +290,48 @@ export function orsetJoin(a, b) {
  *   All replicas are known to have observed at least this causal context.
  */
 export function orsetCompact(set, includedVV) {
+  // Collect deletions in temp arrays to avoid mutation-during-iteration (J8)
+  /** @type {Array<{element: string, dot: string}>} */
+  const toDelete = [];
+
   for (const [element, dots] of set.entries) {
     for (const encodedDot of dots) {
       const dot = decodeDot(encodedDot);
       // Only compact if: (1) dot is tombstoned AND (2) dot <= includedVV
       if (set.tombstones.has(encodedDot) && vvContains(includedVV, dot)) {
-        dots.delete(encodedDot);
-        set.tombstones.delete(encodedDot);
+        toDelete.push({ element, dot: encodedDot });
       }
     }
-    if (dots.size === 0) {
-      set.entries.delete(element);
+  }
+
+  // Apply deletions
+  for (const { element, dot: encodedDot } of toDelete) {
+    const dots = set.entries.get(element);
+    if (dots) {
+      dots.delete(encodedDot);
+      if (dots.size === 0) {
+        set.entries.delete(element);
+      }
     }
+    set.tombstones.delete(encodedDot);
+  }
+}
+
+/**
+ * Creates a deep clone of an ORSet.
+ *
+ * @param {ORSet} set - The ORSet to clone
+ * @returns {ORSet} A new ORSet with independent data structures
+ */
+export function orsetClone(set) {
+  const result = createORSet();
+  for (const [element, dots] of set.entries) {
+    result.entries.set(element, new Set(dots));
+  }
+  for (const dot of set.tombstones) {
+    result.tombstones.add(dot);
   }
+  return result;
 }
 
 /**

package/src/domain/errors/SyncError.js

@@ -14,6 +14,7 @@ import WarpError from './WarpError.js';
  * | `E_SYNC_TIMEOUT` | Sync request exceeded timeout |
  * | `E_SYNC_REMOTE` | Remote server returned a 5xx error |
  * | `E_SYNC_PROTOCOL` | Protocol violation: 4xx, invalid JSON, or malformed response |
+ * | `E_SYNC_PAYLOAD_INVALID` | Sync payload failed shape/resource-limit validation (B64) |
  * | `SYNC_ERROR` | Generic/default sync error |
  *
  * @class SyncError

package/src/domain/errors/TrustError.js

@@ -9,6 +9,8 @@ import WarpError from './WarpError.js';
  * |------|-------------|
  * | `E_TRUST_UNSUPPORTED_ALGORITHM` | Algorithm is not `ed25519` |
  * | `E_TRUST_INVALID_KEY` | Public key is malformed (wrong length or bad base64) |
+ * | `E_TRUST_CAS_CONFLICT` | Concurrent append advanced the trust chain; caller must rebuild + re-sign |
+ * | `E_TRUST_CAS_EXHAUSTED` | CAS retry budget exhausted (transient failures) |
  * | `TRUST_ERROR` | Generic/default trust error |
  *
  * @class TrustError

package/src/domain/services/CheckpointService.js

@@ -11,7 +11,7 @@
  * @see WARP Spec Section 10
  */
 
-import { serializeStateV5, computeStateHashV5 } from './StateSerializerV5.js';
+import { computeStateHashV5 } from './StateSerializerV5.js';
 import {
   serializeFullStateV5,
   deserializeFullStateV5,
@@ -86,7 +86,6 @@ function partitionTreeOids(rawOids) {
  * ```
  * <checkpoint_commit_tree>/
  * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
- * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
  * ├── frontier.cbor        # Writer frontiers
  * ├── appliedVV.cbor       # Version vector of dots in state
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
@@ -116,7 +115,6 @@ export async function create({ persistence, graphName, state, frontier, parents
  * ```
  * <checkpoint_tree>/
  * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
- * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
  * ├── frontier.cbor        # Writer frontiers
  * ├── appliedVV.cbor       # Version vector of dots in state
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
@@ -161,8 +159,7 @@ export async function createV5({
   // 3. Serialize full state (AUTHORITATIVE)
   const stateBuffer = serializeFullStateV5(checkpointState, { codec });
 
-  // 4. Serialize visible projection (CACHE)
-  const visibleBuffer = serializeStateV5(checkpointState, { codec });
+  // 4. Compute state hash
   const stateHash = await computeStateHashV5(checkpointState, { codec, crypto: /** @type {import('../../ports/CryptoPort.js').default} */ (crypto) });
 
   // 5. Serialize frontier and appliedVV
@@ -171,7 +168,6 @@ export async function createV5({
 
   // 6. Write blobs to git
   const stateBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (stateBuffer));
-  const visibleBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (visibleBuffer));
   const frontierBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (frontierBuffer));
   const appliedVVBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (appliedVVBuffer));
 
@@ -207,7 +203,6 @@ export async function createV5({
     `100644 blob ${appliedVVBlobOid}\tappliedVV.cbor`,
     `100644 blob ${frontierBlobOid}\tfrontier.cbor`,
     `100644 blob ${stateBlobOid}\tstate.cbor`,
-    `100644 blob ${visibleBlobOid}\tvisible.cbor`,
   ];
 
   // Add provenance index if present

package/src/domain/services/Frontier.js

@@ -91,6 +91,24 @@ export function cloneFrontier(frontier) {
   return new Map(frontier);
 }
 
+/**
+ * Produces a stable, deterministic fingerprint of a frontier.
+ *
+ * Sorts entries by writer ID and JSON-stringifies the sorted pairs.
+ * Two frontiers produce the same fingerprint iff they have identical
+ * writer→SHA mappings. Used for snapshot isolation checks (B63)
+ * and diagnostic logging.
+ *
+ * @param {Frontier} frontier
+ * @returns {string} Deterministic JSON string of sorted entries
+ */
+export function frontierFingerprint(frontier) {
+  const sorted = [...frontier.entries()].sort(
+    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return JSON.stringify(sorted);
+}
+
 /**
  * Merges two frontiers, taking the "later" entry for each writer.
  * Note: This is a simple merge that takes entries from both.

package/src/domain/services/GraphTraversal.js

@@ -830,52 +830,38 @@ export default class GraphTraversal {
       }
     }
 
-    // Phase 2: Kahn's — collect zero-indegree nodes, sort them lex, yield in order
-    /** @type {string[]} */
-    const ready = [];
+    // Phase 2: Kahn's — MinHeap for O(N log N) zero-indegree processing
+    const ready = new MinHeap({ tieBreaker: lexTieBreaker });
     for (const nodeId of discovered) {
       if ((inDegree.get(nodeId) || 0) === 0) {
-        ready.push(nodeId);
+        ready.insert(nodeId, 0);
       }
     }
-    ready.sort(lexTieBreaker);
 
+    /** @type {string[]} */
     const sorted = [];
-    let rHead = 0;
-    while (rHead < ready.length && sorted.length < maxNodes) {
+    while (!ready.isEmpty() && sorted.length < maxNodes) {
       if (sorted.length % 1000 === 0) {
         checkAborted(signal, 'topologicalSort');
       }
-      const nodeId = /** @type {string} */ (ready[rHead++]);
+      const nodeId = /** @type {string} */ (ready.extractMin());
       sorted.push(nodeId);
 
       const neighbors = adjList.get(nodeId) || [];
-      /** @type {string[]} */
-      const newlyReady = [];
       for (const neighborId of neighbors) {
         const deg = /** @type {number} */ (inDegree.get(neighborId)) - 1;
         inDegree.set(neighborId, deg);
         if (deg === 0) {
-          newlyReady.push(neighborId);
+          ready.insert(neighborId, 0);
         }
       }
-      // Insert newly ready nodes in sorted position
-      if (newlyReady.length > 0) {
-        newlyReady.sort(lexTieBreaker);
-        // Compact consumed prefix before merge to keep rHead at 0
-        if (rHead > 0) {
-          ready.splice(0, rHead);
-          rHead = 0;
-        }
-        this._insertSorted(ready, newlyReady);
-      }
     }
 
     const hasCycle = computeTopoHasCycle({
       sortedLength: sorted.length,
       discoveredSize: discovered.size,
       maxNodes,
-      readyRemaining: rHead < ready.length,
+      readyRemaining: !ready.isEmpty(),
     });
     if (hasCycle && throwOnCycle) {
       // Find a back-edge as witness
@@ -1209,31 +1195,4 @@ export default class GraphTraversal {
     return candidatePred < current;
   }
 
-  /**
-   * Inserts sorted items into a sorted array maintaining order.
-   * Both input arrays must be sorted by lexTieBreaker.
-   *
-   * @param {string[]} target - Sorted array to insert into (mutated in place)
-   * @param {string[]} items - Sorted items to insert
-   * @private
-   */
-  _insertSorted(target, items) {
-    // O(n+k) merge: build merged array from two sorted inputs
-    const merged = [];
-    let ti = 0;
-    let ii = 0;
-    while (ti < target.length && ii < items.length) {
-      if (target[ti] <= items[ii]) {
-        merged.push(target[ti++]);
-      } else {
-        merged.push(items[ii++]);
-      }
-    }
-    while (ti < target.length) { merged.push(target[ti++]); }
-    while (ii < items.length) { merged.push(items[ii++]); }
-    target.length = 0;
-    for (let i = 0; i < merged.length; i++) {
-      target.push(merged[i]);
-    }
-  }
 }

package/src/domain/services/HttpSyncServer.js

@@ -10,6 +10,7 @@
 
 import { z } from 'zod';
 import SyncAuthService from './SyncAuthService.js';
+import { validateSyncRequest } from './SyncPayloadSchema.js';
 
 const DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
 const MAX_REQUEST_BYTES_CEILING = 128 * 1024 * 1024; // 134217728
@@ -117,26 +118,7 @@ function jsonResponse(data) {
   };
 }
 
-/**
- * Validates that a sync request object has the expected shape.
- *
- * @param {unknown} parsed - Parsed JSON body
- * @returns {boolean} True if valid
- * @private
- */
-function isValidSyncRequest(parsed) {
-  if (!parsed || typeof parsed !== 'object') {
-    return false;
-  }
-  const rec = /** @type {Record<string, unknown>} */ (parsed);
-  if (rec.type !== 'sync-request') {
-    return false;
-  }
-  if (!rec.frontier || typeof rec.frontier !== 'object' || Array.isArray(rec.frontier)) {
-    return false;
-  }
-  return true;
-}
+// isValidSyncRequest replaced by SyncPayloadSchema.validateSyncRequest (B64)
 
 /**
  * Checks the content-type header. Returns an error response if the
@@ -200,6 +182,7 @@ function checkBodySize(body, maxBytes) {
 
 /**
  * Parses and validates the request body as a sync request.
+ * Uses Zod-based SyncPayloadSchema for shape + resource limit validation.
  *
  * @param {Buffer|undefined} body
  * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
@@ -215,11 +198,12 @@ function parseBody(body) {
     return { error: errorResponse(400, 'Invalid JSON'), parsed: null };
   }
 
-  if (!isValidSyncRequest(parsed)) {
-    return { error: errorResponse(400, 'Invalid sync request'), parsed: null };
+  const validation = validateSyncRequest(parsed);
+  if (!validation.ok) {
+    return { error: errorResponse(400, `Invalid sync request: ${validation.error}`), parsed: null };
   }
 
-  return { error: null, parsed };
+  return { error: null, parsed: /** @type {import('./SyncProtocol.js').SyncRequest} */ (validation.value) };
 }
 
 /**
@@ -298,12 +282,17 @@ export default class HttpSyncServer {
       this._auth.recordLogOnlyPassthrough();
     }
 
-    // Writer whitelist (uses parsed body for writer IDs)
-    if (parsed.patches && typeof parsed.patches === 'object') {
-      const writerIds = Object.keys(parsed.patches);
-      const writerResult = this._auth.enforceWriters(writerIds);
-      if (!writerResult.ok) {
-        return errorResponse(writerResult.status, writerResult.reason);
+    // Writer whitelist: for sync-requests, extract writer IDs from frontier
+    // keys (the writers the peer claims to have). Sync-requests don't carry
+    // patches — the server generates the response. For sync-responses with
+    // patches, trust-gate should be on patch authors (handled client-side).
+    if (parsed.frontier && typeof parsed.frontier === 'object') {
+      const writerIds = Object.keys(/** @type {Record<string, string>} */ (parsed.frontier));
+      if (writerIds.length > 0) {
+        const writerResult = this._auth.enforceWriters(writerIds);
+        if (!writerResult.ok) {
+          return errorResponse(writerResult.status, writerResult.reason);
+        }
       }
     }
 

package/src/domain/services/JoinReducer.js

@@ -86,6 +86,29 @@ export function createEmptyStateV5() {
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
+/**
+ * Known V2 operation types. Used for forward-compatibility validation.
+ * @type {ReadonlySet<string>}
+ */
+const KNOWN_OPS = new Set(['NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove', 'PropSet', 'BlobValue']);
+
+/**
+ * Validates that an operation has a known type.
+ *
+ * @param {{ type: string }} op
+ * @returns {boolean} True if the op type is in KNOWN_OPS
+ */
+export function isKnownOp(op) {
+  return op && typeof op.type === 'string' && KNOWN_OPS.has(op.type);
+}
+
+/**
+ * Applies a single V2 operation to the given CRDT state.
+ *
+ * @param {WarpStateV5} state - The mutable CRDT state to update
+ * @param {{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}} op - The operation to apply
+ * @param {import('../utils/EventId.js').EventId} eventId - The event ID for LWW ordering
+ */
 export function applyOpV2(state, op, eventId) {
   switch (op.type) {
     case 'NodeAdd':

package/src/domain/services/PatchBuilderV2.js

@@ -103,6 +103,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;
 
@@ -156,6 +165,23 @@ export class PatchBuilderV2 {
     this._writes = new Set();
   }
 
+  /**
+   * 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;
+  }
+
   /**
    * Adds a node to the graph.
    *
@@ -213,7 +239,7 @@ export class PatchBuilderV2 {
    */
   removeNode(nodeId) {
     // 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.
@@ -330,7 +356,7 @@ export class PatchBuilderV2 {
    */
   removeEdge(from, to, label) {
     // 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));
@@ -418,7 +444,7 @@ export class PatchBuilderV2 {
     // 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`);
       }

package/src/domain/services/QueryBuilder.js

@@ -9,6 +9,27 @@ import { matchGlob } from '../utils/matchGlob.js';
 
 const DEFAULT_PATTERN = '*';
 
+/**
+ * Processes items in batches with bounded concurrency.
+ *
+ * @template T, R
+ * @param {T[]} items - Items to process
+ * @param {(item: T) => Promise<R>} fn - Async function to apply to each item
+ * @param {number} [limit=100] - Maximum concurrent operations per batch
+ * @returns {Promise<R[]>} Results in input order
+ */
+async function batchMap(items, fn, limit = 100) {
+  const results = [];
+  for (let i = 0; i < items.length; i += limit) {
+    const batch = items.slice(i, i + limit);
+    const batchResults = await Promise.all(batch.map(fn));
+    for (const r of batchResults) {
+      results.push(r);
+    }
+  }
+  return results;
+}
+
 /**
  * @typedef {Object} QueryNodeSnapshot
  * @property {string} id - The unique identifier of the node
@@ -652,22 +673,33 @@ export default class QueryBuilder {
 
     const pattern = this._pattern ?? DEFAULT_PATTERN;
 
+    // Per-run props memo to avoid redundant getNodeProps calls
+    /** @type {Map<string, Map<string, unknown>>} */
+    const propsMemo = new Map();
+    const getProps = async (/** @type {string} */ nodeId) => {
+      const cached = propsMemo.get(nodeId);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
+      propsMemo.set(nodeId, propsMap);
+      return propsMap;
+    };
+
     let workingSet;
     workingSet = allNodes.filter((nodeId) => matchGlob(pattern, nodeId));
 
     for (const op of this._operations) {
       if (op.type === 'where') {
-        const snapshots = await Promise.all(
-          workingSet.map(async (nodeId) => {
-            const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
-            const edgesOut = adjacency.outgoing.get(nodeId) || [];
-            const edgesIn = adjacency.incoming.get(nodeId) || [];
-            return {
-              nodeId,
-              snapshot: createNodeSnapshot({ id: nodeId, propsMap, edgesOut, edgesIn }),
-            };
-          })
-        );
+        const snapshots = await batchMap(workingSet, async (nodeId) => {
+          const propsMap = await getProps(nodeId);
+          const edgesOut = adjacency.outgoing.get(nodeId) || [];
+          const edgesIn = adjacency.incoming.get(nodeId) || [];
+          return {
+            nodeId,
+            snapshot: createNodeSnapshot({ id: nodeId, propsMap, edgesOut, edgesIn }),
+          };
+        });
         const predicate = /** @type {(node: QueryNodeSnapshot) => boolean} */ (op.fn);
         const filtered = snapshots
           .filter(({ snapshot }) => predicate(snapshot))
@@ -698,7 +730,7 @@ export default class QueryBuilder {
     }
 
     if (this._aggregate) {
-      return await this._runAggregate(workingSet, stateHash);
+      return await this._runAggregate(workingSet, stateHash, getProps);
     }
 
     const selected = this._select;
@@ -718,22 +750,20 @@ export default class QueryBuilder {
     const includeId = !selectFields || selectFields.includes('id');
     const includeProps = !selectFields || selectFields.includes('props');
 
-    const nodes = await Promise.all(
-      workingSet.map(async (nodeId) => {
-        const entry = {};
-        if (includeId) {
-          entry.id = nodeId;
-        }
-        if (includeProps) {
-          const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
-          const props = buildPropsSnapshot(propsMap);
-          if (selectFields || Object.keys(props).length > 0) {
-            entry.props = props;
-          }
+    const nodes = await batchMap(workingSet, async (nodeId) => {
+      const entry = {};
+      if (includeId) {
+        entry.id = nodeId;
+      }
+      if (includeProps) {
+        const propsMap = await getProps(nodeId);
+        const props = buildPropsSnapshot(propsMap);
+        if (selectFields || Object.keys(props).length > 0) {
+          entry.props = props;
         }
-        return entry;
-      })
-    );
+      }
+      return entry;
+    });
 
     return { stateHash, nodes };
   }
@@ -747,10 +777,11 @@ export default class QueryBuilder {
    *
    * @param {string[]} workingSet - Array of matched node IDs
    * @param {string} stateHash - Hash of the materialized state
+   * @param {(nodeId: string) => Promise<Map<string, unknown>>} getProps - Memoized props fetcher
    * @returns {Promise<AggregateResult>} Object containing stateHash and requested aggregation values
    * @private
    */
-  async _runAggregate(workingSet, stateHash) {
+  async _runAggregate(workingSet, stateHash, getProps) {
     const spec = /** @type {AggregateSpec} */ (this._aggregate);
     /** @type {AggregateResult} */
     const result = { stateHash };
@@ -773,8 +804,10 @@ export default class QueryBuilder {
         });
       }
 
-      for (const nodeId of workingSet) {
-        const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
+      // Pre-fetch all props with bounded concurrency
+      const propsList = await batchMap(workingSet, getProps);
+
+      for (const propsMap of propsList) {
         for (const { segments, values } of propsByAgg.values()) {
           /** @type {unknown} */
           let value = propsMap.get(segments[0]);