@git-stunts/git-warp 12.3.0 → 12.4.1

package/src/domain/services/JoinReducer.js

@@ -44,6 +44,28 @@ export { normalizeRawOp, lowerCanonicalOp } from './OpNormalizer.js';
  *   always produces an empty Map for them.
  */
 
+/**
+ * @typedef {Object} OpLike
+ * @property {string} type - Operation type discriminator
+ * @property {string} [node] - Node ID (for NodeAdd, NodeRemove, PropSet)
+ * @property {import('../crdt/Dot.js').Dot} [dot] - Dot identifier (for NodeAdd, EdgeAdd)
+ * @property {string[]} [observedDots] - Encoded dots to remove (for NodeRemove, EdgeRemove)
+ * @property {string} [from] - Source node ID (for EdgeAdd, EdgeRemove)
+ * @property {string} [to] - Target node ID (for EdgeAdd, EdgeRemove)
+ * @property {string} [label] - Edge label (for EdgeAdd, EdgeRemove)
+ * @property {string} [key] - Property key (for PropSet)
+ * @property {unknown} [value] - Property value (for PropSet)
+ * @property {string} [oid] - Blob object ID (for BlobValue)
+ */
+
+/**
+ * @typedef {Object} PatchLike
+ * @property {string} writer - Writer ID who created this patch
+ * @property {number} lamport - Lamport timestamp of this patch
+ * @property {OpLike[]} ops - Ordered array of operations
+ * @property {Map<string, number>|Record<string, number>} context - Version vector context
+ */
+
 /**
  * Creates an empty V5 state with all CRDT structures initialized.
  *
@@ -82,16 +104,7 @@ export function createEmptyStateV5() {
  * clone the state first using `cloneStateV5()`.
  *
  * @param {WarpStateV5} state - The state to mutate. Modified in place.
- * @param {Object} op - The operation to apply
- * @param {string} op.type - One of: 'NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove', 'PropSet', 'BlobValue'
- * @param {string} [op.node] - Node ID (for NodeAdd, NodeRemove, PropSet)
- * @param {import('../crdt/Dot.js').Dot} [op.dot] - Dot identifier (for NodeAdd, EdgeAdd)
- * @param {string[]} [op.observedDots] - Encoded dots to remove (for NodeRemove, EdgeRemove)
- * @param {string} [op.from] - Source node ID (for EdgeAdd, EdgeRemove)
- * @param {string} [op.to] - Target node ID (for EdgeAdd, EdgeRemove)
- * @param {string} [op.label] - Edge label (for EdgeAdd, EdgeRemove)
- * @param {string} [op.key] - Property key (for PropSet)
- * @param {unknown} [op.value] - Property value (for PropSet)
+ * @param {OpLike} op - The operation to apply
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
@@ -349,7 +362,7 @@ export function applyOpV2(state, op, eventId) {
  * - EdgeRemove -> EdgeTombstone (CRDT tombstone semantics)
  * - All others pass through unchanged
  *
- * @const {Object<string, string>}
+ * @const {Record<string, string>}
  */
 const RECEIPT_OP_TYPE = {
   NodeAdd: 'NodeAdd',
@@ -376,9 +389,7 @@ const VALID_RECEIPT_OPS = new Set(OP_TYPES);
  * this add operation is effective or redundant (idempotent re-delivery).
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The node OR-Set containing alive nodes
- * @param {Object} op - The NodeAdd operation
- * @param {string} op.node - The node ID being added
- * @param {import('../crdt/Dot.js').Dot} op.dot - The dot uniquely identifying this add event
+ * @param {{node: string, dot: import('../crdt/Dot.js').Dot}} op - The NodeAdd operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID as target
  */
 function nodeAddOutcome(orset, op) {
@@ -399,9 +410,7 @@ function nodeAddOutcome(orset, op) {
  * observed at the time the remove was issued.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The node OR-Set containing alive nodes
- * @param {Object} op - The NodeRemove operation
- * @param {string} [op.node] - The node ID being removed (may be absent for dot-only removes)
- * @param {string[]} op.observedDots - Array of encoded dots that were observed when the remove was issued
+ * @param {{node?: string, observedDots: string[] | Set<string>}} op - The NodeRemove operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID (or '*') as target
  */
 function nodeRemoveOutcome(orset, op) {
@@ -431,11 +440,7 @@ function nodeRemoveOutcome(orset, op) {
  * Unlike nodes, edges are keyed by the composite (from, to, label) tuple.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The edge OR-Set containing alive edges
- * @param {Object} op - The EdgeAdd operation
- * @param {string} op.from - Source node ID
- * @param {string} op.to - Target node ID
- * @param {string} op.label - Edge label
- * @param {import('../crdt/Dot.js').Dot} op.dot - The dot uniquely identifying this add event
+ * @param {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} op - The EdgeAdd operation
  * @param {string} edgeKey - Pre-encoded edge key (from\0to\0label format)
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key as target
  */
@@ -460,11 +465,7 @@ function edgeAddOutcome(orset, op, edgeKey) {
  * otherwise falls back to '*' for wildcard/unknown targets.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The edge OR-Set containing alive edges
- * @param {Object} op - The EdgeRemove operation
- * @param {string} [op.from] - Source node ID (optional for computing target)
- * @param {string} [op.to] - Target node ID (optional for computing target)
- * @param {string} [op.label] - Edge label (optional for computing target)
- * @param {string[]} op.observedDots - Array of encoded dots that were observed when the remove was issued
+ * @param {{from?: string, to?: string, label?: string, observedDots: string[] | Set<string>}} op - The EdgeRemove operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key (or '*') as target
  */
 function edgeRemoveOutcome(orset, op) {
@@ -535,9 +536,7 @@ function propOutcomeForKey(propMap, key, eventId) {
  * Determines the receipt outcome for a PropSet/NodePropSet operation.
  *
  * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap
- * @param {Object} op
- * @param {string} op.node - Node ID owning the property
- * @param {string} op.key - Property key/name
+ * @param {{node: string, key: string}} op - The PropSet or NodePropSet operation
  * @param {import('../utils/EventId.js').EventId} eventId
  * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
  */
@@ -549,11 +548,7 @@ function propSetOutcome(propMap, op, eventId) {
  * Determines the receipt outcome for an EdgePropSet operation.
  *
  * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap
- * @param {Object} op
- * @param {string} op.from
- * @param {string} op.to
- * @param {string} op.label
- * @param {string} op.key
+ * @param {{from: string, to: string, label: string, key: string}} op - The EdgePropSet operation
  * @param {import('../utils/EventId.js').EventId} eventId
  * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
  */
@@ -577,10 +572,7 @@ function foldPatchDot(frontier, writer, lamport) {
 /**
  * Merges a patch's context into state and folds the patch dot.
  * @param {WarpStateV5} state
- * @param {Object} patch
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {{writer: string, lamport: number, context: Map<string, number>|Record<string, number>}} patch
  */
 function updateFrontierFromPatch(state, patch) {
   const contextVV = patch.context instanceof Map
@@ -594,11 +586,7 @@ function updateFrontierFromPatch(state, patch) {
  * Applies a patch to state without receipt collection (zero overhead).
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {WarpStateV5} The mutated state
  */
@@ -819,11 +807,7 @@ function collectEdgeRemovals(diff, state, before) {
  * winner changes. Redundant ops produce no diff entries.
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<import('../types/WarpTypesV2.js').OpV2 | {type: string}>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {{state: WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}}
  */
@@ -847,11 +831,7 @@ export function applyWithDiff(state, patch, patchSha) {
  * Applies a patch to state with receipt collection for provenance tracking.
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
  */
@@ -883,10 +863,10 @@ export function applyWithReceipt(state, patch, patchSha) {
         break;
       case 'PropSet':
       case 'NodePropSet':
-        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: *}} */ (canonOp), eventId);
+        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: unknown}} */ (canonOp), eventId);
         break;
       case 'EdgePropSet':
-        outcome = edgePropSetOutcome(state.prop, /** @type {{from: string, to: string, label: string, key: string, value: *}} */ (canonOp), eventId);
+        outcome = edgePropSetOutcome(state.prop, /** @type {{from: string, to: string, label: string, key: string, value: unknown}} */ (canonOp), eventId);
         break;
       default: {
         // Unknown or BlobValue — always applied
@@ -940,11 +920,7 @@ export function applyWithReceipt(state, patch, patchSha) {
  * clone the state first using `cloneStateV5()`.
  *
  * @param {WarpStateV5} state - The state to mutate. Modified in place.
- * @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 {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, 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 {PatchLike} patch - The patch to apply
  * @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}}
@@ -1053,11 +1029,9 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @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?: unknown, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
+ * @param {Array<{patch: PatchLike, 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
- * @param {boolean} [options.trackDiff=false] - When true, collect and return PatchDiff
+ * @param {{receipts?: boolean, trackDiff?: boolean}} [options] - Optional configuration
  * @returns {WarpStateV5|{state: WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}|{state: WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}}
  *          Returns state directly when no options;
  *          returns {state, receipts} when receipts is true;

package/src/domain/services/LogicalBitmapIndexBuilder.js

@@ -24,8 +24,7 @@ const MAX_LOCAL_ID = 1 << 24;
 
 export default class LogicalBitmapIndexBuilder {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;

package/src/domain/services/LogicalIndexBuildService.js

@@ -17,9 +17,7 @@ import { nodeVisibleV5, edgeVisibleV5 } from './StateSerializerV5.js';
 
 export default class LogicalIndexBuildService {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} [options]
    */
   constructor({ codec, logger } = {}) {
     this._codec = codec || defaultCodec;
@@ -30,9 +28,7 @@ export default class LogicalIndexBuildService {
    * Builds a complete logical index from materialized state.
    *
    * @param {import('./JoinReducer.js').WarpStateV5} state
-   * @param {Object} [options]
-   * @param {Record<string, { nodeToGlobal: Record<string, number>, nextLocalId: number }>} [options.existingMeta] - Prior meta shards for ID stability
-   * @param {Record<string, number>|Array<[string, number]>} [options.existingLabels] - Prior label registry for append-only stability
+   * @param {{ existingMeta?: Record<string, { nodeToGlobal: Record<string, number>, nextLocalId: number }>, existingLabels?: Record<string, number>|Array<[string, number]> }} [options]
    * @returns {{ tree: Record<string, Uint8Array>, receipt: Record<string, unknown> }}
    */
   build(state, options = {}) {

package/src/domain/services/LogicalIndexReader.js

@@ -89,8 +89,7 @@ function classifyShards(items) {
 
 export default class LogicalIndexReader {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;

package/src/domain/services/LogicalTraversal.js

@@ -83,10 +83,7 @@ export default class LogicalTraversal {
    * multiple starts or no start at all (topologicalSort, commonAncestors).
    *
    * @private
-   * @param {Object} opts - The traversal options
-   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
-   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
-   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], maxDepth?: number }} opts - The traversal options
    * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
@@ -120,10 +117,7 @@ export default class LogicalTraversal {
    *
    * @private
    * @param {string} start - The starting node ID for traversal
-   * @param {Object} opts - The traversal options
-   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
-   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
-   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], maxDepth?: number }} opts - The traversal options
    * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
    * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
@@ -146,10 +140,7 @@ export default class LogicalTraversal {
    * Breadth-first traversal.
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
@@ -169,10 +160,7 @@ export default class LogicalTraversal {
    * Depth-first traversal (pre-order).
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
@@ -193,10 +181,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<{found: boolean, path: string[], length: number}>}
    *   When `found` is true, `path` contains the node IDs from `from` to `to` and
    *   `length` is the hop count. When `found` is false, `path` is empty and `length` is -1.
@@ -219,9 +204,7 @@ export default class LogicalTraversal {
    * Connected component (undirected by default).
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse (default: 1000)
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found
    */
@@ -236,11 +219,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[], signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{reachable: boolean}>}
    */
   async isReachable(from, to, options = {}) {
@@ -262,12 +241,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -292,13 +266,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {(nodeId: string, goalId: string) => number} [options.heuristicFn] - Heuristic function
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, heuristicFn?: (nodeId: string, goalId: string) => number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -326,13 +294,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {(nodeId: string, goalId: string) => number} [options.forwardHeuristic] - Forward heuristic
-   * @param {(nodeId: string, goalId: string) => number} [options.backwardHeuristic] - Backward heuristic
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, forwardHeuristic?: (nodeId: string, goalId: string) => number, backwardHeuristic?: (nodeId: string, goalId: string) => number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -365,11 +327,7 @@ export default class LogicalTraversal {
    * Topological sort (Kahn's algorithm).
    *
    * @param {string|string[]} start - One or more start nodes
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {boolean} [options.throwOnCycle] - Whether to throw on cycle detection
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], throwOnCycle?: boolean, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{sorted: string[], hasCycle: boolean}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if throwOnCycle and cycle found
    * @throws {TraversalError} code 'NODE_NOT_FOUND' if a start node does not exist
@@ -405,11 +363,7 @@ export default class LogicalTraversal {
    * Direction is fixed to 'in' (backward BFS).
    *
    * @param {string[]} nodes - Nodes to find common ancestors of
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {number} [options.maxResults] - Maximum number of results
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ maxDepth?: number, labelFilter?: string|string[], maxResults?: number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{ancestors: string[]}>}
    * @throws {TraversalError} code 'NODE_NOT_FOUND' if a node does not exist
    */
@@ -443,12 +397,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if graph has cycles
    * @throws {TraversalError} code 'NO_PATH' if unreachable

package/src/domain/services/MaterializedViewService.js

@@ -207,11 +207,7 @@ function canonicalizeNeighborSignatures(edges) {
 /**
  * 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
+ * @param {{ nodeId: string, direction: string, logicalIndex: LogicalIndex, truthMap: Map<string, Array<{neighborId: string, label: string}>> }} params
  * @returns {VerifyError|null}
  */
 function compareNodeDirection({ nodeId, direction, logicalIndex, truthMap }) {
@@ -232,9 +228,7 @@ function compareNodeDirection({ nodeId, direction, logicalIndex, truthMap }) {
 
 export default class MaterializedViewService {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} [options]
    */
   constructor({ codec, logger } = {}) {
     this._codec = codec || defaultCodec;
@@ -308,10 +302,7 @@ export default class MaterializedViewService {
   /**
    * 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
+   * @param {{ existingTree: Record<string, Uint8Array>, diff: import('../types/PatchDiff.js').PatchDiff, state: import('./JoinReducer.js').WarpStateV5 }} params
    * @returns {BuildResult}
    */
   applyDiff({ existingTree, diff, state }) {
@@ -345,12 +336,7 @@ export default class MaterializedViewService {
    * 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)
+   * @param {{ state: import('./JoinReducer.js').WarpStateV5, logicalIndex: LogicalIndex, options?: { seed?: number, sampleRate?: number } }} params
    * @returns {VerifyResult}
    */
   verifyIndex({ state, logicalIndex, options = {} }) {

package/src/domain/services/MigrationService.js

@@ -13,10 +13,7 @@ import { createVersionVector, vvIncrement } from '../crdt/VersionVector.js';
  * writer, rebuilds the ORSet structures, and copies only properties belonging
  * to visible nodes (dropping dangling props from deleted nodes).
  *
- * @param {Object} v4State - The V4 materialized state (visible projection)
- * @param {Map<string, {value: boolean}>} v4State.nodeAlive - V4 node alive map
- * @param {Map<string, {value: boolean}>} v4State.edgeAlive - V4 edge alive map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} v4State.prop - V4 property map
+ * @param {{ nodeAlive: Map<string, {value: boolean}>, edgeAlive: Map<string, {value: boolean}>, prop: Map<string, import('../crdt/LWW.js').LWWRegister<unknown>> }} v4State - The V4 materialized state (visible projection)
  * @param {string} migrationWriterId - Writer ID to use for synthetic dots
  * @returns {import('./JoinReducer.js').WarpStateV5} The migrated V5 state
  */

package/src/domain/services/ObserverView.js

@@ -156,13 +156,7 @@ export default class ObserverView {
   /**
    * Creates a new ObserverView.
    *
-   * @param {Object} options
-   * @param {string} options.name - Observer name
-   * @param {Object} options.config - Observer configuration
-   * @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
+   * @param {{ name: string, config: { match: string|string[], expose?: string[], redact?: string[] }, graph: import('../WarpGraph.js').default }} options
    */
   constructor({ name, config, graph }) {
     /** @type {string} */

package/src/domain/services/PatchBuilderV2.js

@@ -99,19 +99,7 @@ export class PatchBuilderV2 {
   /**
    * Creates a new PatchBuilderV2.
    *
-   * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
-   *   (uses CommitPort + RefPort + BlobPort + TreePort methods)
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - This writer's ID
-   * @param {number} options.lamport - Lamport timestamp for this patch
-   * @param {import('../crdt/VersionVector.js').VersionVector} options.versionVector - Current version vector
-   * @param {Function} options.getCurrentState - Function that returns the current materialized state
-   * @param {string|null} [options.expectedParentSha] - Expected parent SHA for race detection
-   * @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 {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for non-fatal warnings
+   * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default, graphName: string, writerId: string, lamport: number, versionVector: import('../crdt/VersionVector.js').VersionVector, getCurrentState: () => import('../services/JoinReducer.js').WarpStateV5 | null, expectedParentSha?: string|null, onCommitSuccess?: ((result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>)|null, onDeleteWithData?: 'reject'|'cascade'|'warn', codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   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} */
@@ -129,8 +117,8 @@ export class PatchBuilderV2 {
     /** @type {import('../crdt/VersionVector.js').VersionVector} */
     this._vv = vvClone(versionVector); // Clone to track local increments
 
-    /** @type {Function} */
-    this._getCurrentState = getCurrentState; // Function to get current materialized state
+    /** @type {() => import('../services/JoinReducer.js').WarpStateV5 | null} */
+    this._getCurrentState = getCurrentState;
 
     /**
      * Snapshot of state captured at construction time (C4).
@@ -540,7 +528,7 @@ export class PatchBuilderV2 {
    * only sets the `_content` property — it does not create the node.
    *
    * @param {string} nodeId - The node ID to attach content to
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachContent(nodeId, content) {
@@ -561,7 +549,7 @@ export class PatchBuilderV2 {
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
    * @param {string} label - Edge label
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachEdgeContent(from, to, label, content) {
@@ -732,7 +720,7 @@ export class PatchBuilderV2 {
 
       // 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));
+      const patchBlobOid = await this._persistence.writeBlob(patchCbor);
 
       // 7. Create tree with the patch blob + any content blobs (deduplicated)
       // Format for mktree: "mode type oid\tpath"

package/src/domain/services/PatchMessageCodec.js

@@ -25,12 +25,7 @@ import {
 /**
  * Encodes a patch commit message.
  *
- * @param {Object} options - The patch message options
- * @param {string} options.graph - The graph name
- * @param {string} options.writer - The writer ID
- * @param {number} options.lamport - The Lamport timestamp (must be a positive integer)
- * @param {string} options.patchOid - The OID of the patch blob
- * @param {number} [options.schema=2] - The schema version (defaults to 2 for new messages)
+ * @param {{ graph: string, writer: string, lamport: number, patchOid: string, schema?: number }} options - The patch message options
  * @returns {string} The encoded commit message
  * @throws {Error} If any validation fails
  *

package/src/domain/services/PropertyIndexBuilder.js

@@ -12,8 +12,7 @@ import computeShardKey from '../utils/shardKey.js';
 
 export default class PropertyIndexBuilder {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;

package/src/domain/services/PropertyIndexReader.js

@@ -12,10 +12,7 @@ import LRUCache from '../utils/LRUCache.js';
 
 export default class PropertyIndexReader {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/IndexStoragePort.js').default} [options.storage]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
-   * @param {number} [options.maxCachedShards=64]
+   * @param {{ storage?: import('../../ports/IndexStoragePort.js').default, codec?: import('../../ports/CodecPort.js').default, maxCachedShards?: number }} [options]
    */
   constructor({ storage, codec, maxCachedShards = 64 } = /** @type {{ storage?: import('../../ports/IndexStoragePort.js').default, codec?: import('../../ports/CodecPort.js').default, maxCachedShards?: number }} */ ({})) {
     this._storage = storage;

package/src/domain/services/ProvenanceIndex.js

@@ -242,9 +242,8 @@ class ProvenanceIndex {
    * The serialized format is a sorted array of [entityId, sortedShas[]] pairs
    * for deterministic output.
    *
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @returns {Buffer|Uint8Array} CBOR-encoded index
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
+   * @returns {Uint8Array} CBOR-encoded index
    */
   serialize({ codec } = {}) {
     const c = codec || defaultCodec;
@@ -268,9 +267,8 @@ class ProvenanceIndex {
   /**
    * Deserializes an index from CBOR format.
    *
-   * @param {Buffer} buffer - CBOR-encoded index
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+   * @param {Uint8Array} buffer - CBOR-encoded index
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    * @returns {ProvenanceIndex} The deserialized index
    * @throws {Error} If the buffer contains an unsupported version
    */
@@ -293,7 +291,7 @@ class ProvenanceIndex {
   /**
    * Returns a JSON-serializable representation of this index.
    *
-   * @returns {Object} Object with version and entries array
+   * @returns {{version: number, entries: Array<[string, string[]]>}} Object with version and entries array
    */
   toJSON() {
     return { version: 1, entries: this.#sortedEntries() };