@git-stunts/git-warp 10.1.2 → 10.4.2

package/src/domain/services/JoinReducer.js

@@ -29,7 +29,7 @@ export {
  * @typedef {Object} WarpStateV5
  * @property {import('../crdt/ORSet.js').ORSet} nodeAlive - ORSet of alive nodes
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
- * @property {Map<string, import('../crdt/LWW.js').LWWRegister>} prop - Properties with LWW
+ * @property {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
  * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
  */
@@ -88,14 +88,14 @@ export function createEmptyStateV5() {
 export function applyOpV2(state, op, eventId) {
   switch (op.type) {
     case 'NodeAdd':
-      orsetAdd(state.nodeAlive, op.node, op.dot);
+      orsetAdd(state.nodeAlive, /** @type {string} */ (op.node), /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
       break;
     case 'NodeRemove':
-      orsetRemove(state.nodeAlive, op.observedDots);
+      orsetRemove(state.nodeAlive, /** @type {Set<string>} */ (/** @type {unknown} */ (op.observedDots)));
       break;
     case 'EdgeAdd': {
-      const edgeKey = encodeEdgeKey(op.from, op.to, op.label);
-      orsetAdd(state.edgeAlive, edgeKey, op.dot);
+      const edgeKey = encodeEdgeKey(/** @type {string} */ (op.from), /** @type {string} */ (op.to), /** @type {string} */ (op.label));
+      orsetAdd(state.edgeAlive, edgeKey, /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
       // Track the EventId at which this edge incarnation was born.
       // On re-add after remove, the greater EventId replaces the old one,
       // allowing the query layer to filter out stale properties.
@@ -108,13 +108,13 @@ export function applyOpV2(state, op, eventId) {
       break;
     }
     case 'EdgeRemove':
-      orsetRemove(state.edgeAlive, op.observedDots);
+      orsetRemove(state.edgeAlive, /** @type {Set<string>} */ (/** @type {unknown} */ (op.observedDots)));
       break;
     case 'PropSet': {
       // Uses EventId-based LWW, same as v4
-      const key = encodePropKey(op.node, op.key);
+      const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
       const current = state.prop.get(key);
-      state.prop.set(key, lwwMax(current, lwwSet(eventId, op.value)));
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(current, lwwSet(eventId, op.value))));
       break;
     }
     default:
@@ -290,7 +290,7 @@ function edgeRemoveOutcome(orset, op) {
  * - `superseded`: An existing value with higher EventId wins
  * - `redundant`: Exact same write (identical EventId)
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} propMap - The properties map keyed by encoded prop keys
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} propMap - The properties map keyed by encoded prop keys
  * @param {Object} op - The PropSet operation
  * @param {string} op.node - Node ID owning the property
  * @param {string} op.key - Property key/name
@@ -347,8 +347,8 @@ function propSetOutcome(propMap, op, eventId) {
  * @param {Object} patch - The patch to apply
  * @param {string} patch.writer - Writer ID who created this patch
  * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Object[]} patch.ops - Array of operations to apply
- * @param {Map|Object} patch.context - Version vector context (Map or serialized form)
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
  * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
  * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
  * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
@@ -370,30 +370,32 @@ export function join(state, patch, patchSha, collectReceipts) {
   }
 
   // Receipt-enabled path
+  /** @type {import('../types/TickReceipt.js').OpOutcome[]} */
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
 
     // Determine outcome BEFORE applying the op (state is pre-op)
+    /** @type {{target: string, result: string, reason?: string}} */
     let outcome;
     switch (op.type) {
       case 'NodeAdd':
-        outcome = nodeAddOutcome(state.nodeAlive, op);
+        outcome = nodeAddOutcome(state.nodeAlive, /** @type {{node: string, dot: import('../crdt/Dot.js').Dot}} */ (op));
         break;
       case 'NodeRemove':
-        outcome = nodeRemoveOutcome(state.nodeAlive, op);
+        outcome = nodeRemoveOutcome(state.nodeAlive, /** @type {{node?: string, observedDots: string[]}} */ (op));
         break;
       case 'EdgeAdd': {
-        const edgeKey = encodeEdgeKey(op.from, op.to, op.label);
-        outcome = edgeAddOutcome(state.edgeAlive, op, edgeKey);
+        const edgeKey = encodeEdgeKey(/** @type {string} */ (op.from), /** @type {string} */ (op.to), /** @type {string} */ (op.label));
+        outcome = edgeAddOutcome(state.edgeAlive, /** @type {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} */ (op), edgeKey);
         break;
       }
       case 'EdgeRemove':
-        outcome = edgeRemoveOutcome(state.edgeAlive, op);
+        outcome = edgeRemoveOutcome(state.edgeAlive, /** @type {{from?: string, to?: string, label?: string, observedDots: string[]}} */ (op));
         break;
       case 'PropSet':
-        outcome = propSetOutcome(state.prop, op, eventId);
+        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: *}} */ (op), eventId);
         break;
       default:
         // Unknown or BlobValue — always applied
@@ -404,12 +406,13 @@ export function join(state, patch, patchSha, collectReceipts) {
     // Apply the op (mutates state)
     applyOpV2(state, op, eventId);
 
-    const receiptOp = RECEIPT_OP_TYPE[op.type] || op.type;
+    const receiptOp = /** @type {Record<string, string>} */ (RECEIPT_OP_TYPE)[op.type] || op.type;
     // Skip unknown/forward-compatible op types that aren't valid receipt ops
     if (!VALID_RECEIPT_OPS.has(receiptOp)) {
       continue;
     }
-    const entry = { op: receiptOp, target: outcome.target, result: outcome.result };
+    /** @type {import('../types/TickReceipt.js').OpOutcome} */
+    const entry = { op: receiptOp, target: outcome.target, result: /** @type {'applied'|'superseded'|'redundant'} */ (outcome.result) };
     if (outcome.reason) {
       entry.reason = outcome.reason;
     }
@@ -467,16 +470,16 @@ export function joinStates(a, b) {
  *
  * This is a pure function that does not mutate its inputs.
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} a - First property map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} b - Second property map
- * @returns {Map<string, import('../crdt/LWW.js').LWWRegister>} New map containing merged properties
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} a - First property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} b - Second property map
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} New map containing merged properties
  */
 function mergeProps(a, b) {
   const result = new Map(a);
 
   for (const [key, regB] of b) {
     const regA = result.get(key);
-    result.set(key, lwwMax(regA, regB));
+    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(regA, regB)));
   }
 
   return result;
@@ -527,9 +530,7 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @param {Array<{patch: Object, sha: string}>} patches - Array of patch objects with their Git SHAs
- * @param {Object} patches[].patch - The decoded patch object (writer, lamport, ops, context)
- * @param {string} patches[].sha - The Git SHA of the patch commit
+ * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
  * @param {WarpStateV5} [initialState] - Optional starting state (for incremental materialization from checkpoint)
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.receipts=false] - When true, collect and return TickReceipts
@@ -544,7 +545,7 @@ export function reduceV5(patches, initialState, options) {
   if (options && options.receipts) {
     const receipts = [];
     for (const { patch, sha } of patches) {
-      const result = join(state, patch, sha, true);
+      const result = /** @type {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (join(state, patch, sha, true));
       receipts.push(result.receipt);
     }
     return { state, receipts };

package/src/domain/services/LogicalTraversal.js

@@ -145,14 +145,14 @@ export default class LogicalTraversal {
    * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
    * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
    * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: Object, depthLimit: number}>}
+   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}, depthLimit: number}>}
    *   The normalized traversal parameters
    * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
    */
   async _prepare(start, { dir, labelFilter, maxDepth }) {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
 
     if (!(await this._graph.hasNode(start))) {
       throw new TraversalError(`Start node not found: ${start}`, {
@@ -187,7 +187,7 @@ export default class LogicalTraversal {
     const result = [];
 
     while (queue.length > 0) {
-      const current = queue.shift();
+      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
       if (visited.has(current.nodeId)) {
         continue;
       }
@@ -237,7 +237,7 @@ export default class LogicalTraversal {
     const result = [];
 
     while (stack.length > 0) {
-      const current = stack.pop();
+      const current = /** @type {{nodeId: string, depth: number}} */ (stack.pop());
       if (visited.has(current.nodeId)) {
         continue;
       }
@@ -298,7 +298,7 @@ export default class LogicalTraversal {
     visited.add(from);
 
     while (queue.length > 0) {
-      const current = queue.shift();
+      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
       if (current.depth >= depthLimit) {
         continue;
       }
@@ -319,10 +319,11 @@ export default class LogicalTraversal {
 
         if (edge.neighborId === to) {
           const path = [to];
+          /** @type {string|undefined} */
           let cursor = current.nodeId;
           while (cursor) {
             path.push(cursor);
-            cursor = parent.get(cursor) || null;
+            cursor = parent.get(cursor);
           }
           path.reverse();
           return { found: true, path, length: path.length - 1 };

package/src/domain/services/MessageCodecInternal.js

@@ -12,6 +12,7 @@
  * @private
  */
 
+// @ts-expect-error -- no declaration file for @git-stunts/trailer-codec
 import { TrailerCodec, TrailerCodecService } from '@git-stunts/trailer-codec';
 
 // -----------------------------------------------------------------------------
@@ -62,6 +63,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 // -----------------------------------------------------------------------------
 
 // Lazy singleton codec instance
+/** @type {*} */ // TODO(ts-cleanup): type lazy singleton
 let _codec = null;
 
 /**

package/src/domain/services/ObserverView.js

@@ -102,7 +102,7 @@ export default class ObserverView {
     this._graph = graph;
 
     /** @type {LogicalTraversal} */
-    this.traverse = new LogicalTraversal(this);
+    this.traverse = new LogicalTraversal(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
   }
 
   /**
@@ -124,11 +124,11 @@ export default class ObserverView {
    * Builds a filtered adjacency structure that only includes edges
    * where both endpoints pass the match filter.
    *
-   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map, incoming: Map}}>}
+   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map<string, *[]>, incoming: Map<string, *[]>}}>}
    * @private
    */
   async _materializeGraph() {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {*} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
     const { state, stateHash } = materialized;
 
     // Build filtered adjacency: only edges where both endpoints match
@@ -159,8 +159,8 @@ export default class ObserverView {
       incoming.get(to).push({ neighborId: from, label });
     }
 
-    const sortNeighbors = (list) => {
-      list.sort((a, b) => {
+    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;
         }
@@ -260,6 +260,6 @@ export default class ObserverView {
    * @returns {QueryBuilder} A query builder scoped to this observer
    */
   query() {
-    return new QueryBuilder(this);
+    return new QueryBuilder(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
   }
 }

package/src/domain/services/PatchBuilderV2.js

@@ -85,8 +85,8 @@ export class PatchBuilderV2 {
    * @param {{ warn: Function }} [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} */
-    this._persistence = persistence;
+    /** @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} */
+    this._persistence = /** @type {*} */ (persistence); // TODO(ts-cleanup): narrow port type
 
     /** @type {string} */
     this._graphName = graphName;
@@ -214,7 +214,7 @@ export class PatchBuilderV2 {
       const { edges } = findAttachedData(state, nodeId);
       for (const edgeKey of edges) {
         const [from, to, label] = edgeKey.split('\0');
-        const edgeDots = [...orsetGetDots(state.edgeAlive, edgeKey)];
+        const edgeDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ ([...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);
@@ -251,7 +251,7 @@ export class PatchBuilderV2 {
       }
     }
 
-    const observedDots = state ? [...orsetGetDots(state.nodeAlive, nodeId)] : [];
+    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (state ? [...orsetGetDots(state.nodeAlive, nodeId)] : []));
     this._ops.push(createNodeRemoveV2(nodeId, observedDots));
     // Provenance: NodeRemove reads the node (to observe its dots)
     this._reads.add(nodeId);
@@ -325,7 +325,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 = state ? [...orsetGetDots(state.edgeAlive, edgeKey)] : [];
+    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (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);
@@ -454,7 +454,7 @@ export class PatchBuilderV2 {
       schema,
       writer: this._writerId,
       lamport: this._lamport,
-      context: this._vv,
+      context: /** @type {*} */ (this._vv), // TODO(ts-cleanup): narrow port type
       ops: this._ops,
       reads: [...this._reads].sort(),
       writes: [...this._writes].sort(),
@@ -515,10 +515,10 @@ export class PatchBuilderV2 {
     const currentRefSha = await this._persistence.readRef(writerRef);
 
     if (currentRefSha !== this._expectedParentSha) {
-      const err = new WriterError(
+      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;
@@ -556,7 +556,7 @@ export class PatchBuilderV2 {
     const patchCbor = this._codec.encode(patch);
 
     // 5. Write patch.cbor blob
-    const patchBlobOid = await this._persistence.writeBlob(patchCbor);
+    const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
 
     // 6. Create tree with the blob
     // Format for mktree: "mode type oid\tpath"

package/src/domain/services/PatchMessageCodec.js

@@ -72,13 +72,7 @@ export function encodePatchMessage({ graph, writer, lamport, patchOid, schema =
  * Decodes a patch commit message.
  *
  * @param {string} message - The raw commit message
- * @returns {Object} The decoded patch message
- * @returns {string} return.kind - Always 'patch'
- * @returns {string} return.graph - The graph name
- * @returns {string} return.writer - The writer ID
- * @returns {number} return.lamport - The Lamport timestamp
- * @returns {string} return.patchOid - The patch blob OID
- * @returns {number} return.schema - The schema version
+ * @returns {{ kind: 'patch', graph: string, writer: string, lamport: number, patchOid: string, schema: number }} The decoded patch message
  * @throws {Error} If the message is not a valid patch message
  *
  * @example

package/src/domain/services/ProvenanceIndex.js

@@ -52,7 +52,6 @@ class ProvenanceIndex {
   /**
    * Internal index mapping nodeId/edgeKey to Set of patch SHAs.
    * @type {Map<string, Set<string>>}
-   * @private
    */
   #index;
 
@@ -120,7 +119,6 @@ class ProvenanceIndex {
    *
    * @param {string} entityId - The node ID or edge key
    * @param {string} patchSha - The patch SHA
-   * @private
    */
   #addEntry(entityId, patchSha) {
     let shas = this.#index.get(entityId);
@@ -227,12 +225,12 @@ class ProvenanceIndex {
    * Returns sorted entries for deterministic output.
    *
    * @returns {Array<[string, string[]]>} Sorted array of [entityId, sortedShas[]] pairs
-   * @private
    */
   #sortedEntries() {
+    /** @type {Array<[string, string[]]>} */
     const entries = [];
     for (const [entityId, shas] of this.#index) {
-      entries.push([entityId, [...shas].sort()]);
+      entries.push(/** @type {[string, string[]]} */ ([entityId, [...shas].sort()]));
     }
     entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
     return entries;
@@ -246,7 +244,7 @@ class ProvenanceIndex {
    *
    * @param {Object} [options]
    * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @returns {Buffer} CBOR-encoded index
+   * @returns {Buffer|Uint8Array} CBOR-encoded index
    */
   serialize({ codec } = {}) {
     const c = codec || defaultCodec;
@@ -258,7 +256,6 @@ class ProvenanceIndex {
    *
    * @param {Array<[string, string[]]>} entries - Array of [entityId, shas[]] pairs
    * @returns {Map<string, Set<string>>} The built index
-   * @private
    */
   static #buildIndex(entries) {
     const index = new Map();
@@ -279,7 +276,8 @@ class ProvenanceIndex {
    */
   static deserialize(buffer, { codec } = {}) {
     const c = codec || defaultCodec;
-    const obj = c.decode(buffer);
+    /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */
+    const obj = /** @type {any} */ (c.decode(buffer)); // TODO(ts-cleanup): narrow port type
 
     if (obj.version !== 1) {
       throw new Error(`Unsupported ProvenanceIndex version: ${obj.version}`);
@@ -304,7 +302,7 @@ class ProvenanceIndex {
   /**
    * Creates a ProvenanceIndex from a JSON representation.
    *
-   * @param {Object} json - Object with version and entries array
+   * @param {{ version?: number, entries?: Array<[string, string[]]> }} json - Object with version and entries array
    * @returns {ProvenanceIndex} The deserialized index
    * @throws {Error} If the JSON contains an unsupported version
    */

package/src/domain/services/ProvenancePayload.js

@@ -68,7 +68,6 @@ class ProvenancePayload {
   /**
    * The internal array of patch entries. Frozen after construction.
    * @type {ReadonlyArray<PatchEntry>}
-   * @private
    */
   #patches;
 
@@ -173,7 +172,7 @@ class ProvenancePayload {
     // Use JoinReducer's reduceV5 for deterministic materialization.
     // Note: reduceV5 returns { state, receipts } when options.receipts is truthy,
     // but returns bare WarpStateV5 when no options passed (as here).
-    return reduceV5(this.#patches, initialState);
+    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {*} */ (this.#patches), initialState)); // TODO(ts-cleanup): type patch array
   }
 
   /**

package/src/domain/services/QueryBuilder.js

@@ -12,8 +12,8 @@ const DEFAULT_PATTERN = '*';
  * @typedef {Object} QueryNodeSnapshot
  * @property {string} id - The unique identifier of the node
  * @property {Record<string, unknown>} props - Frozen snapshot of node properties
- * @property {Array<{label: string, to: string}>} edgesOut - Outgoing edges sorted by label then target
- * @property {Array<{label: string, from: string}>} edgesIn - Incoming edges sorted by label then source
+ * @property {ReadonlyArray<{label: string, to?: string, from?: string}>} edgesOut - Outgoing edges sorted by label then target
+ * @property {ReadonlyArray<{label: string, to?: string, from?: string}>} edgesIn - Incoming edges sorted by label then source
  */
 
 /**
@@ -271,6 +271,7 @@ function cloneValue(value) {
  * @private
  */
 function buildPropsSnapshot(propsMap) {
+  /** @type {Record<string, unknown>} */
   const props = {};
   const keys = [...propsMap.keys()].sort();
   for (const key of keys) {
@@ -299,8 +300,8 @@ function buildEdgesSnapshot(edges, directionKey) {
     if (a.label !== b.label) {
       return a.label < b.label ? -1 : 1;
     }
-    const aPeer = a[directionKey];
-    const bPeer = b[directionKey];
+    const aPeer = /** @type {string} */ (a[directionKey]);
+    const bPeer = /** @type {string} */ (b[directionKey]);
     return aPeer < bPeer ? -1 : aPeer > bPeer ? 1 : 0;
   });
   return deepFreeze(list);
@@ -493,9 +494,13 @@ export default class QueryBuilder {
    */
   constructor(graph) {
     this._graph = graph;
+    /** @type {string|null} */
     this._pattern = null;
+    /** @type {Array<{type: string, fn?: (node: QueryNodeSnapshot) => boolean, label?: string, depth?: [number, number]}>} */
     this._operations = [];
+    /** @type {string[]|null} */
     this._select = null;
+    /** @type {AggregateSpec|null} */
     this._aggregate = null;
   }
 
@@ -531,7 +536,7 @@ export default class QueryBuilder {
    */
   where(fn) {
     assertPredicate(fn);
-    const predicate = isPlainObject(fn) ? objectToPredicate(fn) : fn;
+    const predicate = isPlainObject(fn) ? objectToPredicate(/** @type {Record<string, unknown>} */ (fn)) : /** @type {(node: QueryNodeSnapshot) => boolean} */ (fn);
     this._operations.push({ type: 'where', fn: predicate });
     return this;
   }
@@ -628,11 +633,6 @@ export default class QueryBuilder {
    * The "props." prefix is optional and will be stripped automatically.
    *
    * @param {AggregateSpec} spec - Aggregation specification
-   * @param {boolean} [spec.count] - If true, include count of matched nodes
-   * @param {string} [spec.sum] - Property path to sum
-   * @param {string} [spec.avg] - Property path to average
-   * @param {string} [spec.min] - Property path to find minimum
-   * @param {string} [spec.max] - Property path to find maximum
    * @returns {QueryBuilder} This builder for chaining
    * @throws {QueryError} If spec is not a plain object (code: E_QUERY_AGGREGATE_TYPE)
    * @throws {QueryError} If numeric aggregation keys are not strings (code: E_QUERY_AGGREGATE_TYPE)
@@ -646,11 +646,12 @@ export default class QueryBuilder {
       });
     }
     const numericKeys = ['sum', 'avg', 'min', 'max'];
+    const specAny = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (spec));
     for (const key of numericKeys) {
-      if (spec[key] !== undefined && typeof spec[key] !== 'string') {
+      if (specAny[key] !== undefined && typeof specAny[key] !== 'string') {
         throw new QueryError(`aggregate() expects ${key} to be a string path`, {
           code: 'E_QUERY_AGGREGATE_TYPE',
-          context: { key, receivedType: typeof spec[key] },
+          context: { key, receivedType: typeof specAny[key] },
         });
       }
     }
@@ -674,7 +675,7 @@ export default class QueryBuilder {
    * @throws {QueryError} If an unknown select field is specified (code: E_QUERY_SELECT_FIELD)
    */
   async run() {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
     const { adjacency, stateHash } = materialized;
     const allNodes = sortIds(await this._graph.getNodes());
 
@@ -696,15 +697,16 @@ export default class QueryBuilder {
             };
           })
         );
+        const predicate = /** @type {(node: QueryNodeSnapshot) => boolean} */ (op.fn);
         const filtered = snapshots
-          .filter(({ snapshot }) => op.fn(snapshot))
+          .filter(({ snapshot }) => predicate(snapshot))
           .map(({ nodeId }) => nodeId);
         workingSet = sortIds(filtered);
         continue;
       }
 
       if (op.type === 'outgoing' || op.type === 'incoming') {
-        const [minD, maxD] = op.depth;
+        const [minD, maxD] = /** @type {[number, number]} */ (op.depth);
         if (minD === 1 && maxD === 1) {
           workingSet = applyHop({
             direction: op.type,
@@ -718,7 +720,7 @@ export default class QueryBuilder {
             label: op.label,
             workingSet,
             adjacency,
-            depth: op.depth,
+            depth: /** @type {[number, number]} */ (op.depth),
           });
         }
       }
@@ -778,21 +780,24 @@ export default class QueryBuilder {
    * @private
    */
   async _runAggregate(workingSet, stateHash) {
-    const spec = this._aggregate;
+    const spec = /** @type {AggregateSpec} */ (this._aggregate);
+    /** @type {AggregateResult} */
     const result = { stateHash };
+    const specRec = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (spec));
 
     if (spec.count) {
       result.count = workingSet.length;
     }
 
     const numericAggs = ['sum', 'avg', 'min', 'max'];
-    const activeAggs = numericAggs.filter((key) => spec[key]);
+    const activeAggs = numericAggs.filter((key) => specRec[key]);
 
     if (activeAggs.length > 0) {
+      /** @type {Map<string, {segments: string[], values: number[]}>} */
       const propsByAgg = new Map();
       for (const key of activeAggs) {
         propsByAgg.set(key, {
-          segments: spec[key].replace(/^props\./, '').split('.'),
+          segments: /** @type {string} */ (specRec[key]).replace(/^props\./, '').split('.'),
           values: [],
         });
       }
@@ -800,6 +805,7 @@ export default class QueryBuilder {
       for (const nodeId of workingSet) {
         const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
         for (const { segments, values } of propsByAgg.values()) {
+          /** @type {*} */ // TODO(ts-cleanup): type deep property traversal
           let value = propsMap.get(segments[0]);
           for (let i = 1; i < segments.length; i++) {
             if (value && typeof value === 'object') {
@@ -817,15 +823,15 @@ export default class QueryBuilder {
 
       for (const [key, { values }] of propsByAgg) {
         if (key === 'sum') {
-          result.sum = values.length > 0 ? values.reduce((a, b) => a + b, 0) : 0;
+          result.sum = values.length > 0 ? values.reduce((/** @type {number} */ a, /** @type {number} */ b) => a + b, 0) : 0;
         } else if (key === 'avg') {
-          result.avg = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+          result.avg = values.length > 0 ? values.reduce((/** @type {number} */ a, /** @type {number} */ b) => a + b, 0) / values.length : 0;
         } else if (key === 'min') {
           result.min =
-            values.length > 0 ? values.reduce((m, v) => (v < m ? v : m), Infinity) : 0;
+            values.length > 0 ? values.reduce((/** @type {number} */ m, /** @type {number} */ v) => (v < m ? v : m), Infinity) : 0;
         } else if (key === 'max') {
           result.max =
-            values.length > 0 ? values.reduce((m, v) => (v > m ? v : m), -Infinity) : 0;
+            values.length > 0 ? values.reduce((/** @type {number} */ m, /** @type {number} */ v) => (v > m ? v : m), -Infinity) : 0;
         }
       }
     }

package/src/domain/services/StateDiff.js

@@ -86,8 +86,8 @@ function compareProps(a, b) {
 
 /**
  * Checks if two arrays are deeply equal.
- * @param {Array} a
- * @param {Array} b
+ * @param {Array<*>} a
+ * @param {Array<*>} b
  * @returns {boolean}
  */
 function arraysEqual(a, b) {
@@ -104,8 +104,8 @@ function arraysEqual(a, b) {
 
 /**
  * Checks if two objects are deeply equal.
- * @param {Object} a
- * @param {Object} b
+ * @param {Record<string, *>} a
+ * @param {Record<string, *>} b
  * @returns {boolean}
  */
 function objectsEqual(a, b) {
@@ -155,9 +155,9 @@ function deepEqual(a, b) {
 
 /**
  * Computes set difference: elements in `after` not in `before`.
- * @param {Set} before
- * @param {Set} after
- * @returns {Array}
+ * @param {Set<string>} before
+ * @param {Set<string>} after
+ * @returns {Array<string>}
  */
 function setAdded(before, after) {
   const result = [];