@git-stunts/git-warp 11.5.1 → 12.1.0

package/src/domain/services/MaterializedViewService.js

@@ -0,0 +1,379 @@
+/**
+ * Orchestrates building, persisting, and loading a MaterializedView
+ * composed of a LogicalIndex + PropertyIndexReader.
+ *
+ * Five entry points:
+ * - `build(state)` — from a WarpStateV5 (in-memory)
+ * - `persistIndexTree(tree, persistence)` — write shards to Git storage
+ * - `loadFromOids(shardOids, storage)` — hydrate from blob OIDs
+ * - `applyDiff(existingTree, diff, state)` — incremental update from PatchDiff
+ * - `verifyIndex({ state, logicalIndex, options })` — cross-provider verification
+ *
+ * @module domain/services/MaterializedViewService
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import nullLogger from '../utils/nullLogger.js';
+import LogicalIndexBuildService from './LogicalIndexBuildService.js';
+import LogicalIndexReader from './LogicalIndexReader.js';
+import PropertyIndexReader from './PropertyIndexReader.js';
+import IncrementalIndexUpdater from './IncrementalIndexUpdater.js';
+import { orsetElements, orsetContains } from '../crdt/ORSet.js';
+import { decodeEdgeKey } from './KeyCodec.js';
+
+/**
+ * @typedef {import('./BitmapNeighborProvider.js').LogicalIndex} LogicalIndex
+ */
+
+/**
+ * @typedef {Object} BuildResult
+ * @property {Record<string, Uint8Array>} tree
+ * @property {LogicalIndex} logicalIndex
+ * @property {PropertyIndexReader} propertyReader
+ * @property {Record<string, unknown>} receipt
+ */
+
+/**
+ * @typedef {Object} LoadResult
+ * @property {LogicalIndex} logicalIndex
+ * @property {PropertyIndexReader} propertyReader
+ */
+
+/**
+ * @typedef {Object} VerifyError
+ * @property {string} nodeId
+ * @property {string} direction
+ * @property {string[]} expected
+ * @property {string[]} actual
+ */
+
+/**
+ * @typedef {Object} VerifyResult
+ * @property {number} passed
+ * @property {number} failed
+ * @property {VerifyError[]} errors
+ * @property {number} seed
+ */
+
+/**
+ * Creates a PropertyIndexReader backed by an in-memory tree map.
+ *
+ * @param {Record<string, Uint8Array>} tree
+ * @param {import('../../ports/CodecPort.js').default} codec
+ * @returns {PropertyIndexReader}
+ */
+function buildInMemoryPropertyReader(tree, codec) {
+  /** @type {Record<string, string>} */
+  const propShardOids = {};
+  for (const path of Object.keys(tree)) {
+    if (path.startsWith('props_')) {
+      propShardOids[path] = path;
+    }
+  }
+
+  const storage = /** @type {{ readBlob(oid: string): Promise<Uint8Array> }} */ ({
+    readBlob: (oid) => Promise.resolve(tree[oid]),
+  });
+
+  const reader = new PropertyIndexReader({ storage, codec });
+  reader.setup(propShardOids);
+  return reader;
+}
+
+/**
+ * Partitions shard OID entries into index vs property buckets.
+ *
+ * @param {Record<string, string>} shardOids
+ * @returns {{ indexOids: Record<string, string>, propOids: Record<string, string> }}
+ */
+function partitionShardOids(shardOids) {
+  /** @type {Record<string, string>} */
+  const indexOids = {};
+  /** @type {Record<string, string>} */
+  const propOids = {};
+
+  for (const [path, oid] of Object.entries(shardOids)) {
+    if (path.startsWith('props_')) {
+      propOids[path] = oid;
+    } else {
+      indexOids[path] = oid;
+    }
+  }
+  return { indexOids, propOids };
+}
+
+/**
+ * Mulberry32 PRNG — deterministic 32-bit generator from a seed.
+ *
+ * @param {number} seed
+ * @returns {() => number} Returns values in [0, 1)
+ */
+function mulberry32(seed) {
+  let t = (seed | 0) + 0x6D2B79F5;
+  return () => {
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Selects a deterministic sample of nodes using a seeded PRNG.
+ *
+ * @param {string[]} allNodes
+ * @param {number} sampleRate - Fraction of nodes to select (>0 and <=1)
+ * @param {number} seed
+ * @returns {string[]}
+ */
+function sampleNodes(allNodes, sampleRate, seed) {
+  if (sampleRate >= 1) {
+    return allNodes;
+  }
+  if (sampleRate <= 0 || allNodes.length === 0) {
+    return [];
+  }
+  const rng = mulberry32(seed);
+  const sampled = allNodes.filter(() => rng() < sampleRate);
+  if (sampled.length === 0) {
+    sampled.push(allNodes[Math.floor(rng() * allNodes.length)]);
+  }
+  return sampled;
+}
+
+/**
+ * Builds adjacency maps from state for ground-truth verification.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @returns {{ outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>> }}
+ */
+function buildGroundTruthAdjacency(state) {
+  const outgoing = new Map();
+  const incoming = new Map();
+
+  for (const edgeKey of orsetElements(state.edgeAlive)) {
+    const { from, to, label } = decodeEdgeKey(edgeKey);
+    if (!orsetContains(state.nodeAlive, from) || !orsetContains(state.nodeAlive, to)) {
+      continue;
+    }
+    if (!outgoing.has(from)) {
+      outgoing.set(from, []);
+    }
+    outgoing.get(from).push({ neighborId: to, label });
+    if (!incoming.has(to)) {
+      incoming.set(to, []);
+    }
+    incoming.get(to).push({ neighborId: from, label });
+  }
+
+  return { outgoing, incoming };
+}
+
+/**
+ * Canonicalizes neighbor edges into deterministic, label-aware signatures.
+ *
+ * @param {Array<{neighborId: string, label: string}>} edges
+ * @returns {string[]}
+ */
+function canonicalizeNeighborSignatures(edges) {
+  /** @type {Map<string, string[]>} */
+  const byNeighbor = new Map();
+  for (const { neighborId, label } of edges) {
+    let labels = byNeighbor.get(neighborId);
+    if (!labels) {
+      labels = [];
+      byNeighbor.set(neighborId, labels);
+    }
+    labels.push(label);
+  }
+  const signatures = [];
+  for (const [neighborId, labels] of byNeighbor) {
+    signatures.push(JSON.stringify([neighborId, labels.slice().sort()]));
+  }
+  signatures.sort();
+  return signatures;
+}
+
+/**
+ * Compares bitmap index neighbors against ground-truth adjacency for one node.
+ *
+ * @param {Object} params
+ * @param {string} params.nodeId
+ * @param {string} params.direction
+ * @param {LogicalIndex} params.logicalIndex
+ * @param {Map<string, Array<{neighborId: string, label: string}>>} params.truthMap
+ * @returns {VerifyError|null}
+ */
+function compareNodeDirection({ nodeId, direction, logicalIndex, truthMap }) {
+  const bitmapEdges = logicalIndex.getEdges(nodeId, direction);
+  const actual = canonicalizeNeighborSignatures(bitmapEdges);
+  const expected = canonicalizeNeighborSignatures(truthMap.get(nodeId) || []);
+
+  if (actual.length !== expected.length) {
+    return { nodeId, direction, expected, actual };
+  }
+  for (let i = 0; i < actual.length; i++) {
+    if (actual[i] !== expected[i]) {
+      return { nodeId, direction, expected, actual };
+    }
+  }
+  return null;
+}
+
+export default class MaterializedViewService {
+  /**
+   * @param {Object} [options]
+   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   */
+  constructor({ codec, logger } = {}) {
+    this._codec = codec || defaultCodec;
+    this._logger = logger || nullLogger;
+  }
+
+  /**
+   * Builds a complete MaterializedView from WarpStateV5.
+   *
+   * @param {import('./JoinReducer.js').WarpStateV5} state
+   * @returns {BuildResult}
+   */
+  build(state) {
+    const svc = new LogicalIndexBuildService({
+      codec: this._codec,
+      logger: this._logger,
+    });
+    const { tree, receipt } = svc.build(state);
+
+    const logicalIndex = new LogicalIndexReader({ codec: this._codec })
+      .loadFromTree(tree)
+      .toLogicalIndex();
+
+    const propertyReader = buildInMemoryPropertyReader(tree, this._codec);
+
+    return { tree, logicalIndex, propertyReader, receipt };
+  }
+
+  /**
+   * Writes each shard as a blob and creates a Git tree object.
+   *
+   * @param {Record<string, Uint8Array>} tree
+   * @param {{ writeBlob(buf: Uint8Array): Promise<string>, writeTree(entries: string[]): Promise<string> }} persistence
+   * @returns {Promise<string>} tree OID
+   */
+  async persistIndexTree(tree, persistence) {
+    const paths = Object.keys(tree).sort();
+    const oids = await Promise.all(
+      paths.map((p) => persistence.writeBlob(tree[p]))
+    );
+
+    const entries = paths.map(
+      (path, i) => `100644 blob ${oids[i]}\t${path}`
+    );
+    return await persistence.writeTree(entries);
+  }
+
+  /**
+   * Hydrates a LogicalIndex + PropertyIndexReader from blob OIDs.
+   *
+   * @param {Record<string, string>} shardOids - path to blob OID
+   * @param {{ readBlob(oid: string): Promise<Uint8Array> }} storage
+   * @returns {Promise<LoadResult>}
+   */
+  async loadFromOids(shardOids, storage) {
+    const { indexOids, propOids } = partitionShardOids(shardOids);
+
+    const reader = new LogicalIndexReader({ codec: this._codec });
+    await reader.loadFromOids(indexOids, storage);
+    const logicalIndex = reader.toLogicalIndex();
+
+    const propertyReader = new PropertyIndexReader({
+      storage: /** @type {import('../../ports/IndexStoragePort.js').default} */ (storage),
+      codec: this._codec,
+    });
+    propertyReader.setup(propOids);
+
+    return { logicalIndex, propertyReader };
+  }
+
+  /**
+   * Applies a PatchDiff incrementally to an existing index tree.
+   *
+   * @param {Object} params
+   * @param {Record<string, Uint8Array>} params.existingTree
+   * @param {import('../types/PatchDiff.js').PatchDiff} params.diff
+   * @param {import('./JoinReducer.js').WarpStateV5} params.state
+   * @returns {BuildResult}
+   */
+  applyDiff({ existingTree, diff, state }) {
+    const updater = new IncrementalIndexUpdater({ codec: this._codec });
+    const loadShard = (/** @type {string} */ path) => existingTree[path];
+    const dirtyShards = updater.computeDirtyShards({ diff, state, loadShard });
+    const tree = { ...existingTree, ...dirtyShards };
+
+    const logicalIndex = new LogicalIndexReader({ codec: this._codec })
+      .loadFromTree(tree)
+      .toLogicalIndex();
+    const propertyReader = buildInMemoryPropertyReader(tree, this._codec);
+
+    // Note: receipt.cbor is written only by the full build (LogicalIndexBuildService).
+    // IncrementalIndexUpdater never writes a receipt, so the receipt returned here
+    // reflects the state at the time of the original full build, not the current
+    // incremental update. Consumers should not rely on it for incremental accuracy.
+    const receipt = tree['receipt.cbor']
+      ? this._codec.decode(tree['receipt.cbor'])
+      : {};
+
+    return {
+      tree,
+      logicalIndex,
+      propertyReader,
+      receipt: /** @type {Record<string, unknown>} */ (receipt),
+    };
+  }
+
+  /**
+   * Verifies index integrity by sampling alive nodes and comparing
+   * bitmap neighbor queries against adjacency-based ground truth.
+   *
+   * @param {Object} params
+   * @param {import('./JoinReducer.js').WarpStateV5} params.state
+   * @param {LogicalIndex} params.logicalIndex
+   * @param {Object} [params.options]
+   * @param {number} [params.options.seed] - PRNG seed for reproducible sampling
+   * @param {number} [params.options.sampleRate] - Fraction of nodes to check (>0 and <=1, default 0.1)
+   * @returns {VerifyResult}
+   */
+  verifyIndex({ state, logicalIndex, options = {} }) {
+    const seed = options.seed ?? (Date.now() & 0x7FFFFFFF);
+    const sampleRate = options.sampleRate ?? 0.1;
+    const allNodes = [...orsetElements(state.nodeAlive)].sort();
+    const sampled = sampleNodes(allNodes, sampleRate, seed);
+    const truth = buildGroundTruthAdjacency(state);
+
+    /** @type {VerifyError[]} */
+    const errors = [];
+    let passed = 0;
+
+    for (const nodeId of sampled) {
+      if (!logicalIndex.isAlive(nodeId)) {
+        errors.push({
+          nodeId,
+          direction: 'alive',
+          expected: ['true'],
+          actual: ['false'],
+        });
+        continue;
+      }
+      for (const direction of ['out', 'in']) {
+        const map = direction === 'out' ? truth.outgoing : truth.incoming;
+        const err = compareNodeDirection({ nodeId, direction, logicalIndex, truthMap: map });
+        if (err) {
+          errors.push(err);
+        } else {
+          passed++;
+        }
+      }
+    }
+
+    return { passed, failed: errors.length, errors, seed };
+  }
+}

package/src/domain/services/ObserverView.js

@@ -13,28 +13,7 @@ import QueryBuilder from './QueryBuilder.js';
 import LogicalTraversal from './LogicalTraversal.js';
 import { orsetContains, orsetElements } from '../crdt/ORSet.js';
 import { decodeEdgeKey } from './KeyCodec.js';
-
-/**
- * Tests whether a string matches a glob-style pattern.
- *
- * Supports `*` as a wildcard matching zero or more characters.
- * A lone `*` matches everything.
- *
- * @param {string} pattern - Glob pattern (e.g. 'user:*', '*:admin', '*')
- * @param {string} str - The string to test
- * @returns {boolean} True if the string matches the pattern
- */
-function matchGlob(pattern, str) {
-  if (pattern === '*') {
-    return true;
-  }
-  if (!pattern.includes('*')) {
-    return pattern === str;
-  }
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-  const regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
-  return regex.test(str);
-}
+import { matchGlob } from '../utils/matchGlob.js';
 
 /**
  * Filters a properties Map based on expose and redact lists.
@@ -67,6 +46,106 @@ function filterProps(propsMap, expose, redact) {
   return filtered;
 }
 
+/** @typedef {{ neighborId: string, label: string }} NeighborEntry */
+
+/**
+ * Sorts a neighbor list by (neighborId, label) using strict codepoint comparison.
+ *
+ * @param {NeighborEntry[]} list
+ */
+function sortNeighbors(list) {
+  list.sort((a, b) => {
+    if (a.neighborId !== b.neighborId) {
+      return a.neighborId < b.neighborId ? -1 : 1;
+    }
+    return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+  });
+}
+
+/**
+ * Builds filtered adjacency maps by scanning all edges in the OR-Set.
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state
+ * @param {string|string[]} pattern
+ * @returns {{ outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]> }}
+ */
+function buildAdjacencyFromEdges(state, pattern) {
+  const outgoing = /** @type {Map<string, NeighborEntry[]>} */ (new Map());
+  const incoming = /** @type {Map<string, NeighborEntry[]>} */ (new Map());
+
+  for (const edgeKey of orsetElements(state.edgeAlive)) {
+    const { from, to, label } = decodeEdgeKey(edgeKey);
+
+    if (!orsetContains(state.nodeAlive, from) || !orsetContains(state.nodeAlive, to)) {
+      continue;
+    }
+    if (!matchGlob(pattern, from) || !matchGlob(pattern, to)) {
+      continue;
+    }
+
+    if (!outgoing.has(from)) { outgoing.set(from, []); }
+    if (!incoming.has(to)) { incoming.set(to, []); }
+
+    /** @type {NeighborEntry[]} */ (outgoing.get(from)).push({ neighborId: to, label });
+    /** @type {NeighborEntry[]} */ (incoming.get(to)).push({ neighborId: from, label });
+  }
+
+  for (const list of outgoing.values()) { sortNeighbors(list); }
+  for (const list of incoming.values()) { sortNeighbors(list); }
+  return { outgoing, incoming };
+}
+
+/**
+ * Processes a single node's edges into the outgoing/incoming adjacency maps.
+ *
+ * @param {string} id
+ * @param {NeighborEntry[]} edges
+ * @param {{ visibleSet: Set<string>, outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]> }} ctx
+ */
+function collectNodeEdges(id, edges, ctx) {
+  const filtered = edges.filter((e) => ctx.visibleSet.has(e.neighborId));
+  if (filtered.length > 0) {
+    ctx.outgoing.set(id, filtered);
+  }
+  for (const { neighborId, label } of filtered) {
+    if (!ctx.incoming.has(neighborId)) { ctx.incoming.set(neighborId, []); }
+    /** @type {NeighborEntry[]} */ (ctx.incoming.get(neighborId)).push({ neighborId: id, label });
+  }
+}
+
+/**
+ * Builds filtered adjacency maps using a BitmapNeighborProvider.
+ *
+ * For each visible node, queries the provider for outgoing neighbors,
+ * then post-filters by glob match. Incoming maps are derived from
+ * the outgoing results to avoid duplicate provider calls.
+ *
+ * @param {import('./BitmapNeighborProvider.js').default} provider
+ * @param {string[]} visibleNodes
+ * @returns {Promise<{ outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]> }>}
+ */
+async function buildAdjacencyViaProvider(provider, visibleNodes) {
+  const visibleSet = new Set(visibleNodes);
+  const outgoing = /** @type {Map<string, NeighborEntry[]>} */ (new Map());
+  const incoming = /** @type {Map<string, NeighborEntry[]>} */ (new Map());
+  const ctx = { visibleSet, outgoing, incoming };
+
+  const BATCH = 64;
+  for (let i = 0; i < visibleNodes.length; i += BATCH) {
+    const chunk = visibleNodes.slice(i, i + BATCH);
+    const results = await Promise.all(
+      chunk.map(id => provider.getNeighbors(id, 'out').then(edges => ({ id, edges })))
+    );
+    for (const { id, edges } of results) {
+      collectNodeEdges(id, edges, ctx);
+    }
+  }
+
+  // Provider returns pre-sorted outgoing; incoming needs sorting
+  for (const list of incoming.values()) { sortNeighbors(list); }
+  return { outgoing, incoming };
+}
+
 /**
  * Read-only observer view of a materialized WarpGraph state.
  *
@@ -80,7 +159,7 @@ export default class ObserverView {
    * @param {Object} options
    * @param {string} options.name - Observer name
    * @param {Object} options.config - Observer configuration
-   * @param {string} options.config.match - Glob pattern for visible nodes
+   * @param {string|string[]} options.config.match - Glob pattern(s) for visible nodes
    * @param {string[]} [options.config.expose] - Property keys to include
    * @param {string[]} [options.config.redact] - Property keys to exclude (takes precedence over expose)
    * @param {import('../WarpGraph.js').default} options.graph - The source WarpGraph instance
@@ -89,7 +168,7 @@ export default class ObserverView {
     /** @type {string} */
     this._name = name;
 
-    /** @type {string} */
+    /** @type {string|string[]} */
     this._matchPattern = config.match;
 
     /** @type {string[]|undefined} */
@@ -101,6 +180,13 @@ export default class ObserverView {
     /** @type {import('../WarpGraph.js').default} */
     this._graph = graph;
 
+    /**
+     * Cast safety: LogicalTraversal requires the following methods from the
+     * graph-like object it wraps:
+     *   - hasNode(nodeId): Promise<boolean>          (line ~96 in LogicalTraversal)
+     *   - _materializeGraph(): Promise<{adjacency}>  (line ~94 in LogicalTraversal)
+     * ObserverView implements both: hasNode() at line ~242, _materializeGraph() at line ~214.
+     */
     /** @type {LogicalTraversal} */
     this.traverse = new LogicalTraversal(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
@@ -122,60 +208,28 @@ export default class ObserverView {
    * QueryBuilder and LogicalTraversal.
    *
    * Builds a filtered adjacency structure that only includes edges
-   * where both endpoints pass the match filter.
+   * where both endpoints pass the match filter. Uses the parent graph's
+   * BitmapNeighborProvider when available for O(1) lookups with post-filter.
    *
-   * @returns {Promise<{state: unknown, stateHash: string, adjacency: {outgoing: Map<string, unknown[]>, incoming: Map<string, unknown[]>}}>}
+   * @returns {Promise<{state: unknown, stateHash: string, adjacency: {outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]>}}>}
    * @private
    */
   async _materializeGraph() {
-    const materialized = await /** @type {{ _materializeGraph: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, stateHash: string, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, stateHash: string, provider?: import('./BitmapNeighborProvider.js').default, adjacency: {outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]>}}> }} */ (this._graph)._materializeGraph();
     const { state, stateHash } = materialized;
 
-    // Build filtered adjacency: only edges where both endpoints match
-    const outgoing = new Map();
-    const incoming = new Map();
-
-    for (const edgeKey of orsetElements(state.edgeAlive)) {
-      const { from, to, label } = decodeEdgeKey(edgeKey);
-
-      // Both endpoints must be alive
-      if (!orsetContains(state.nodeAlive, from) || !orsetContains(state.nodeAlive, to)) {
-        continue;
-      }
+    /** @type {{ outgoing: Map<string, NeighborEntry[]>, incoming: Map<string, NeighborEntry[]> }} */
+    let adjacency;
 
-      // Both endpoints must match the observer pattern
-      if (!matchGlob(this._matchPattern, from) || !matchGlob(this._matchPattern, to)) {
-        continue;
-      }
-
-      if (!outgoing.has(from)) {
-        outgoing.set(from, []);
-      }
-      if (!incoming.has(to)) {
-        incoming.set(to, []);
-      }
-
-      outgoing.get(from).push({ neighborId: to, label });
-      incoming.get(to).push({ neighborId: from, label });
-    }
-
-    const sortNeighbors = (/** @type {{ neighborId: string, label: string }[]} */ list) => {
-      list.sort((/** @type {{ neighborId: string, label: string }} */ a, /** @type {{ neighborId: string, label: string }} */ b) => {
-        if (a.neighborId !== b.neighborId) {
-          return a.neighborId < b.neighborId ? -1 : 1;
-        }
-        return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
-      });
-    };
-
-    for (const list of outgoing.values()) {
-      sortNeighbors(list);
-    }
-    for (const list of incoming.values()) {
-      sortNeighbors(list);
+    if (materialized.provider) {
+      const visibleNodes = orsetElements(state.nodeAlive)
+        .filter((id) => matchGlob(this._matchPattern, id));
+      adjacency = await buildAdjacencyViaProvider(materialized.provider, visibleNodes);
+    } else {
+      adjacency = buildAdjacencyFromEdges(state, this._matchPattern);
     }
 
-    return { state, stateHash, adjacency: { outgoing, incoming } };
+    return { state, stateHash, adjacency };
   }
 
   // ===========================================================================
@@ -260,6 +314,15 @@ export default class ObserverView {
    * @returns {QueryBuilder} A query builder scoped to this observer
    */
   query() {
+    /**
+     * Cast safety: QueryBuilder requires the following methods from the
+     * graph-like object it wraps:
+     *   - getNodes(): Promise<string[]>                  (line ~680 in QueryBuilder)
+     *   - getNodeProps(nodeId): Promise<Map|null>         (lines ~691, ~757, ~806 in QueryBuilder)
+     *   - _materializeGraph(): Promise<{adjacency, stateHash}>  (line ~678 in QueryBuilder)
+     * ObserverView implements all three: getNodes() at line ~254, getNodeProps() at line ~268,
+     * _materializeGraph() at line ~214.
+     */
     return new QueryBuilder(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
 }

package/src/domain/services/PatchBuilderV2.js

@@ -221,7 +221,7 @@ export class PatchBuilderV2 {
       const { edges } = findAttachedData(state, nodeId);
       for (const edgeKey of edges) {
         const [from, to, label] = edgeKey.split('\0');
-        const edgeDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ ([...orsetGetDots(state.edgeAlive, edgeKey)]));
+        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);
@@ -258,7 +258,7 @@ export class PatchBuilderV2 {
       }
     }
 
-    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (state ? [...orsetGetDots(state.nodeAlive, nodeId)] : []));
+    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);
@@ -332,7 +332,7 @@ export class PatchBuilderV2 {
     // Get observed dots from current state (orsetGetDots returns already-encoded dot strings)
     const state = this._getCurrentState();
     const edgeKey = encodeEdgeKey(from, to, label);
-    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (state ? [...orsetGetDots(state.edgeAlive, edgeKey)] : []));
+    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);