@git-stunts/git-warp 12.3.0 → 12.4.1

package/src/domain/services/BoundaryTransitionRecord.js

@@ -77,13 +77,7 @@ const BTR_VERSION = 1;
  *
  * This ensures all fields are covered and the encoding is deterministic.
  *
- * @param {Object} fields - BTR fields to authenticate
- * @param {number} fields.version - BTR format version
- * @param {string} fields.h_in - Hash of input state
- * @param {string} fields.h_out - Hash of output state
- * @param {Uint8Array} fields.U_0 - Serialized initial state
- * @param {Array<unknown>} fields.P - Serialized provenance payload
- * @param {string} fields.t - ISO timestamp
+ * @param {{ version: number, h_in: string, h_out: string, U_0: Uint8Array, P: Array<unknown>, t: string }} fields - BTR fields to authenticate
  * @param {string|Uint8Array} key - HMAC key
  * @param {{ crypto: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} deps - Dependencies
  * @returns {Promise<string>} Hex-encoded HMAC tag
@@ -151,11 +145,7 @@ async function computeHmac(fields, key, { crypto, codec }) {
  *
  * @param {import('./JoinReducer.js').WarpStateV5} initialState - The input state U_0
  * @param {ProvenancePayload} payload - The provenance payload P
- * @param {Object} options - BTR creation options
- * @param {string|Uint8Array} options.key - HMAC key for authentication
- * @param {string} [options.timestamp] - ISO timestamp (defaults to now)
- * @param {import('../../ports/CryptoPort.js').default} options.crypto - CryptoPort instance
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @param {{ key: string|Uint8Array, timestamp?: string, crypto: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} options - BTR creation options
  * @returns {Promise<BTR>} The created BTR
  * @throws {TypeError} If payload is not a ProvenancePayload
  */
@@ -246,9 +236,7 @@ async function verifyHmac(btr, key, { crypto, codec }) {
  * Verifies replay produces expected h_out.
  *
  * @param {BTR} btr - The BTR to verify
- * @param {Object} [deps] - Dependencies
- * @param {import('../../ports/CryptoPort.js').default} [deps.crypto] - CryptoPort instance
- * @param {import('../../ports/CodecPort.js').default} [deps.codec] - Codec
+ * @param {{ crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} [deps] - Dependencies
  * @returns {Promise<string|null>} Error message if replay mismatch, null if valid
  * @private
  */
@@ -276,10 +264,7 @@ async function verifyReplayHash(btr, { crypto, codec } = {}) {
  *
  * @param {BTR} btr - The BTR to verify
  * @param {string|Uint8Array} key - HMAC key
- * @param {Object} [options] - Verification options
- * @param {boolean} [options.verifyReplay=false] - Also verify replay produces h_out
- * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @param {{ verifyReplay?: boolean, crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} [options] - Verification options
  * @returns {Promise<VerificationResult>} Verification result with valid flag and optional reason
  */
 export async function verifyBTR(btr, key, options = {}) {
@@ -368,8 +353,7 @@ function deserializeInitialState(U_0, { codec } = {}) {
  * enabling byte-for-byte comparison of BTRs.
  *
  * @param {BTR} btr - The BTR to serialize
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Uint8Array} CBOR-encoded BTR
  */
 export function serializeBTR(btr, { codec } = {}) {
@@ -389,8 +373,7 @@ export function serializeBTR(btr, { codec } = {}) {
  * Deserializes a BTR from CBOR bytes.
  *
  * @param {Uint8Array} bytes - CBOR-encoded BTR
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {BTR} The deserialized BTR
  * @throws {Error} If the bytes are not valid CBOR or missing required fields
  */

package/src/domain/services/CheckpointMessageCodec.js

@@ -30,12 +30,7 @@ import {
 /**
  * Encodes a checkpoint commit message.
  *
- * @param {Object} options - The checkpoint message options
- * @param {string} options.graph - The graph name
- * @param {string} options.stateHash - The SHA-256 hash of the materialized state
- * @param {string} options.frontierOid - The OID of the frontier blob
- * @param {string} options.indexOid - The OID of the index tree
- * @param {number} [options.schema=2] - The schema version (defaults to 2 for new messages)
+ * @param {{ graph: string, stateHash: string, frontierOid: string, indexOid: string, schema?: number }} options - The checkpoint message options
  * @returns {string} The encoded commit message
  * @throws {Error} If any validation fails
  *

package/src/domain/services/CheckpointSerializerV5.js

@@ -35,9 +35,8 @@ import { createEmptyStateV5 } from './JoinReducer.js';
  * }
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer|Uint8Array} CBOR-encoded full state
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
+ * @returns {Uint8Array} CBOR-encoded full state
  */
 export function serializeFullStateV5(state, { codec } = {}) {
   const c = codec || defaultCodec;
@@ -84,9 +83,8 @@ export function serializeFullStateV5(state, { codec } = {}) {
 /**
  * Deserializes full V5 state. Used for resume.
  *
- * @param {Buffer|Uint8Array} buffer - CBOR-encoded full state
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {Uint8Array} buffer - CBOR-encoded full state
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {import('./JoinReducer.js').WarpStateV5}
  */
 // eslint-disable-next-line complexity
@@ -169,9 +167,8 @@ export function computeAppliedVV(state) {
  * Serializes appliedVV to CBOR format.
  *
  * @param {Map<string, number>} vv - Version vector (Map<writerId, counter>)
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer|Uint8Array} CBOR-encoded version vector
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
+ * @returns {Uint8Array} CBOR-encoded version vector
  */
 export function serializeAppliedVV(vv, { codec } = {}) {
   const c = codec || defaultCodec;
@@ -182,9 +179,8 @@ export function serializeAppliedVV(vv, { codec } = {}) {
 /**
  * Deserializes appliedVV from CBOR format.
  *
- * @param {Buffer|Uint8Array} buffer - CBOR-encoded version vector
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {Uint8Array} buffer - CBOR-encoded version vector
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Map<string, number>} Version vector
  */
 export function deserializeAppliedVV(buffer, { codec } = {}) {

package/src/domain/services/CheckpointService.js

@@ -109,17 +109,7 @@ function partitionTreeOids(rawOids) {
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
  * ```
  *
- * @param {Object} options - Checkpoint creation options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Git persistence adapter
- * @param {string} options.graphName - Name of the graph
- * @param {import('./JoinReducer.js').WarpStateV5} options.state - The V5 state to checkpoint
- * @param {import('./Frontier.js').Frontier} options.frontier - Writer frontier map
- * @param {string[]} [options.parents=[]] - Parent commit SHAs (typically prior checkpoint or patch commits)
- * @param {boolean} [options.compact=true] - Whether to compact tombstoned dots before saving
- * @param {import('./ProvenanceIndex.js').ProvenanceIndex} [options.provenanceIndex] - Optional provenance index to persist
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization
- * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for state hash computation
- * @param {Record<string, Uint8Array>} [options.indexTree] - Optional materialized view index tree (triggers schema 4)
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default, graphName: string, state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, parents?: string[], compact?: boolean, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex, codec?: import('../../ports/CodecPort.js').default, crypto?: import('../../ports/CryptoPort.js').default, indexTree?: Record<string, Uint8Array> }} options - Checkpoint creation options
  * @returns {Promise<string>} The checkpoint commit SHA
  */
 export async function create({ persistence, graphName, state, frontier, parents = [], compact = true, provenanceIndex, codec, crypto, indexTree }) {
@@ -138,17 +128,7 @@ export async function create({ persistence, graphName, state, frontier, parents
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
  * ```
  *
- * @param {Object} options - Checkpoint creation options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Git persistence adapter
- * @param {string} options.graphName - Name of the graph
- * @param {import('./JoinReducer.js').WarpStateV5} options.state - The V5 state to checkpoint
- * @param {import('./Frontier.js').Frontier} options.frontier - Writer frontier map
- * @param {string[]} [options.parents=[]] - Parent commit SHAs
- * @param {boolean} [options.compact=true] - Whether to compact tombstoned dots before saving
- * @param {import('./ProvenanceIndex.js').ProvenanceIndex} [options.provenanceIndex] - Optional provenance index to persist
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization
- * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for state hash computation
- * @param {Record<string, Uint8Array>} [options.indexTree] - Optional materialized view index tree (triggers schema 4)
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default, graphName: string, state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, parents?: string[], compact?: boolean, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex, codec?: import('../../ports/CodecPort.js').default, crypto?: import('../../ports/CryptoPort.js').default, indexTree?: Record<string, Uint8Array> }} options - Checkpoint creation options
  * @returns {Promise<string>} The checkpoint commit SHA
  */
 export async function createV5({
@@ -187,15 +167,15 @@ export async function createV5({
   const appliedVVBuffer = serializeAppliedVV(appliedVV, { codec: /** @type {import('../../ports/CodecPort.js').default} */ (codec) });
 
   // 6. Write blobs to git
-  const stateBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (stateBuffer));
-  const frontierBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (frontierBuffer));
-  const appliedVVBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (appliedVVBuffer));
+  const stateBlobOid = await persistence.writeBlob(stateBuffer);
+  const frontierBlobOid = await persistence.writeBlob(frontierBuffer);
+  const appliedVVBlobOid = await persistence.writeBlob(appliedVVBuffer);
 
   // 6b. Optionally serialize and write provenance index
   let provenanceIndexBlobOid = null;
   if (provenanceIndex) {
     const provenanceIndexBuffer = provenanceIndex.serialize({ codec });
-    provenanceIndexBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (provenanceIndexBuffer));
+    provenanceIndexBlobOid = await persistence.writeBlob(provenanceIndexBuffer);
   }
 
   // 6c. Optionally write index subtree (schema 4)
@@ -293,8 +273,7 @@ export async function createV5({
  *
  * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default} persistence - Git persistence adapter
  * @param {string} checkpointSha - The checkpoint commit SHA to load
- * @param {Object} [options] - Load options
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR deserialization
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options] - Load options
  * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, stateHash: string, schema: number, appliedVV: Map<string, number>|null, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex, indexShardOids: Record<string, string>|null}>} The loaded checkpoint data
  * @throws {Error} If checkpoint is schema:1 (migration required)
  */
@@ -375,13 +354,7 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
  * Only supports schema:2 checkpoints. Schema:1 checkpoints will cause
  * loadCheckpoint to throw an error.
  *
- * @param {Object} options - Materialization options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Git persistence adapter
- * @param {string} options.graphName - Name of the graph
- * @param {string} options.checkpointSha - The schema:2 checkpoint commit SHA to start from
- * @param {import('./Frontier.js').Frontier} options.targetFrontier - The target frontier to materialize to
- * @param {Function} options.patchLoader - Async function to load patches: (writerId, fromSha, toSha) => Array<{patch, sha}>
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR deserialization
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default, graphName: string, checkpointSha: string, targetFrontier: import('./Frontier.js').Frontier, patchLoader: (writerId: string, fromSha: string|null, toSha: string) => Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>, codec?: import('../../ports/CodecPort.js').default }} options - Materialization options
  * @returns {Promise<import('./JoinReducer.js').WarpStateV5>} The materialized V5 state at targetFrontier
  * @throws {Error} If checkpoint is schema:1 (migration required)
  * @throws {Error} If checkpoint is missing required blobs (state.cbor, frontier.cbor)
@@ -430,10 +403,7 @@ export async function materializeIncremental({
  * Creates ORSet-based state with synthetic dots for all visible elements.
  * This is used when loading a v5 checkpoint for incremental materialization.
  *
- * @param {Object} visibleProjection - The checkpoint's visible projection
- * @param {string[]} visibleProjection.nodes - Visible node IDs
- * @param {Array<{from: string, to: string, label: string}>} visibleProjection.edges - Visible edges
- * @param {Array<{node: string, key: string, value: unknown}>} visibleProjection.props - Visible properties
+ * @param {{ nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}> }} visibleProjection - The checkpoint's visible projection
  * @returns {import('./JoinReducer.js').WarpStateV5} Reconstructed WarpStateV5
  * @public
  */

package/src/domain/services/CommitDagTraversalService.js

@@ -35,9 +35,7 @@ export default class CommitDagTraversalService {
   /**
    * Creates a new CommitDagTraversalService.
    *
-   * @param {Object} options
-   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
+   * @param {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ indexReader, logger = nullLogger }) {
     if (!indexReader) {

package/src/domain/services/DagPathFinding.js

@@ -37,11 +37,9 @@ export default class DagPathFinding {
   /**
    * Creates a new DagPathFinding service.
    *
-   * @param {Object} options
-   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
+   * @param {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
-  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {{ indexReader: import('./BitmapIndexReader.js').default }} */ ({})) {
+  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger }) {
     if (!indexReader) {
       throw new Error('DagPathFinding requires an indexReader');
     }
@@ -56,12 +54,7 @@ export default class DagPathFinding {
    * Returns the first path found, which is guaranteed to be a shortest path
    * (in terms of number of edges) due to BFS's level-order exploration.
    *
-   * @param {Object} options - Path finding options
-   * @param {string} options.from - Source node SHA
-   * @param {string} options.to - Target node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum nodes to visit
-   * @param {number} [options.maxDepth=1000] - Maximum path length
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} options - Path finding options
    * @returns {Promise<{found: boolean, path: string[], length: number}>} Path result
    */
   async findPath({
@@ -114,11 +107,7 @@ export default class DagPathFinding {
   /**
    * Finds the shortest path between two nodes using bidirectional BFS.
    *
-   * @param {Object} options - Path finding options
-   * @param {string} options.from - Source node SHA
-   * @param {string} options.to - Target node SHA
-   * @param {number} [options.maxDepth=1000] - Maximum search depth per direction
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, maxDepth?: number, signal?: AbortSignal }} options - Path finding options
    * @returns {Promise<{found: boolean, path: string[], length: number}>} Path result
    */
   async shortestPath({ from, to, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
@@ -197,12 +186,7 @@ export default class DagPathFinding {
   /**
    * Finds shortest path using Dijkstra's algorithm with custom edge weights.
    *
-   * @param {Object} options - Path finding options
-   * @param {string} options.from - Starting SHA
-   * @param {string} options.to - Target SHA
-   * @param {(from: string, to: string) => number|Promise<number>} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
-   * @param {string} [options.direction='children'] - Edge direction: 'children' or 'parents'
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, weightProvider?: (from: string, to: string) => number|Promise<number>, direction?: string, signal?: AbortSignal }} options - Path finding options
    * @returns {Promise<{path: string[], totalCost: number}>} Path and cost
    * @throws {TraversalError} With code 'NO_PATH' if no path exists
    */
@@ -274,13 +258,7 @@ export default class DagPathFinding {
   /**
    * Finds shortest path using A* algorithm with heuristic guidance.
    *
-   * @param {Object} options - Path finding options
-   * @param {string} options.from - Starting SHA
-   * @param {string} options.to - Target SHA
-   * @param {(from: string, to: string) => number|Promise<number>} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
-   * @param {(sha: string, target: string) => number} [options.heuristicProvider] - Callback `(sha, targetSha) => number`
-   * @param {string} [options.direction='children'] - Edge direction: 'children' or 'parents'
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, weightProvider?: (from: string, to: string) => number|Promise<number>, heuristicProvider?: (sha: string, target: string) => number, direction?: string, signal?: AbortSignal }} options - Path finding options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>} Path result
    * @throws {TraversalError} With code 'NO_PATH' if no path exists
    */
@@ -364,13 +342,7 @@ export default class DagPathFinding {
   /**
    * Bi-directional A* search - meets in the middle from both ends.
    *
-   * @param {Object} options - Path finding options
-   * @param {string} options.from - Starting SHA
-   * @param {string} options.to - Target SHA
-   * @param {(from: string, to: string) => number|Promise<number>} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
-   * @param {(sha: string, target: string) => number} [options.forwardHeuristic] - Callback for forward search
-   * @param {(sha: string, target: string) => number} [options.backwardHeuristic] - Callback for backward search
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, weightProvider?: (from: string, to: string) => number|Promise<number>, forwardHeuristic?: (sha: string, target: string) => number, backwardHeuristic?: (sha: string, target: string) => number, signal?: AbortSignal }} options - Path finding options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>} Path result
    * @throws {TraversalError} With code 'NO_PATH' if no path exists
    */
@@ -462,18 +434,7 @@ export default class DagPathFinding {
   /**
    * Expands the forward frontier by one node in bidirectional A*.
    *
-   * @param {Object} state - Forward expansion state
-   * @param {import('../utils/MinHeap.js').default<string>} state.fwdHeap
-   * @param {Set<string>} state.fwdVisited
-   * @param {Map<string, number>} state.fwdGScore
-   * @param {Map<string, string>} state.fwdPrevious
-   * @param {Set<string>} state.bwdVisited
-   * @param {Map<string, number>} state.bwdGScore
-   * @param {(from: string, to: string) => number|Promise<number>} state.weightProvider
-   * @param {(sha: string, target: string) => number} state.forwardHeuristic
-   * @param {string} state.to
-   * @param {number} state.mu
-   * @param {string|null} state.meetingPoint
+   * @param {{ fwdHeap: import('../utils/MinHeap.js').default<string>, fwdVisited: Set<string>, fwdGScore: Map<string, number>, fwdPrevious: Map<string, string>, bwdVisited: Set<string>, bwdGScore: Map<string, number>, weightProvider: (from: string, to: string) => number|Promise<number>, forwardHeuristic: (sha: string, target: string) => number, to: string, mu: number, meetingPoint: string|null }} state - Forward expansion state
    * @returns {Promise<{explored: number, mu: number, meetingPoint: string|null}>}
    * @private
    */
@@ -535,18 +496,7 @@ export default class DagPathFinding {
   /**
    * Expands the backward frontier by one node in bidirectional A*.
    *
-   * @param {Object} state - Backward expansion state
-   * @param {import('../utils/MinHeap.js').default<string>} state.bwdHeap
-   * @param {Set<string>} state.bwdVisited
-   * @param {Map<string, number>} state.bwdGScore
-   * @param {Map<string, string>} state.bwdNext
-   * @param {Set<string>} state.fwdVisited
-   * @param {Map<string, number>} state.fwdGScore
-   * @param {(from: string, to: string) => number|Promise<number>} state.weightProvider
-   * @param {(sha: string, target: string) => number} state.backwardHeuristic
-   * @param {string} state.from
-   * @param {number} state.mu
-   * @param {string|null} state.meetingPoint
+   * @param {{ bwdHeap: import('../utils/MinHeap.js').default<string>, bwdVisited: Set<string>, bwdGScore: Map<string, number>, bwdNext: Map<string, string>, fwdVisited: Set<string>, fwdGScore: Map<string, number>, weightProvider: (from: string, to: string) => number|Promise<number>, backwardHeuristic: (sha: string, target: string) => number, from: string, mu: number, meetingPoint: string|null }} state - Backward expansion state
    * @returns {Promise<{explored: number, mu: number, meetingPoint: string|null}>}
    * @private
    */

package/src/domain/services/DagTopology.js

@@ -32,12 +32,9 @@ export default class DagTopology {
   /**
    * Creates a new DagTopology service.
    *
-   * @param {Object} options
-   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
-   * @param {import('./DagTraversal.js').default} [options.traversal] - Traversal service for ancestor enumeration
+   * @param {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default, traversal?: import('./DagTraversal.js').default }} options
    */
-  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default, traversal?: import('./DagTraversal.js').default }} */ { indexReader, logger = nullLogger, traversal } = /** @type {{ indexReader: import('./BitmapIndexReader.js').default }} */ ({})) {
+  constructor({ indexReader, logger = nullLogger, traversal }) {
     if (!indexReader) {
       throw new Error('DagTopology requires an indexReader');
     }
@@ -67,11 +64,7 @@ export default class DagTopology {
    * An ancestor is "common" if it can be reached by following parent edges
    * from ALL of the input nodes.
    *
-   * @param {Object} options - Common ancestor options
-   * @param {string[]} options.shas - Array of node SHAs
-   * @param {number} [options.maxResults=100] - Maximum ancestors to return
-   * @param {number} [options.maxDepth=1000] - Maximum depth to search
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ shas: string[], maxResults?: number, maxDepth?: number, signal?: AbortSignal }} options - Common ancestor options
    * @returns {Promise<string[]>} Array of common ancestor SHAs
    */
   async commonAncestors({ shas, maxResults = 100, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
@@ -119,12 +112,7 @@ export default class DagTopology {
    * Topological order ensures that for every directed edge A -> B, node A
    * is yielded before node B.
    *
-   * @param {Object} options - Topological sort options
-   * @param {string} options.start - Starting node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum nodes to yield
-   * @param {TraversalDirection} [options.direction='forward'] - Direction
-   * @param {boolean} [options.throwOnCycle=false] - If true, throws on cycle detection
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ start: string, maxNodes?: number, direction?: TraversalDirection, throwOnCycle?: boolean, signal?: AbortSignal }} options - Topological sort options
    * @yields {{sha: string, depth: number, parent: null}} Nodes in topological order
    * @throws {TraversalError} With code 'CYCLE_DETECTED' if throwOnCycle is true
    */

package/src/domain/services/DagTraversal.js

@@ -39,11 +39,9 @@ export default class DagTraversal {
   /**
    * Creates a new DagTraversal service.
    *
-   * @param {Object} options
-   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
+   * @param {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
-  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {{ indexReader: import('./BitmapIndexReader.js').default }} */ ({})) {
+  constructor({ indexReader, logger = nullLogger }) {
     if (!indexReader) {
       throw new Error('DagTraversal requires an indexReader');
     }
@@ -73,12 +71,7 @@ export default class DagTraversal {
    * moving to depth N+1. This guarantees that nodes are yielded in order of
    * increasing distance from the start node.
    *
-   * @param {Object} options - Traversal options
-   * @param {string} options.start - Starting node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum nodes to visit
-   * @param {number} [options.maxDepth=1000] - Maximum depth to traverse
-   * @param {TraversalDirection} [options.direction='forward'] - Traversal direction
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ start: string, maxNodes?: number, maxDepth?: number, direction?: TraversalDirection, signal?: AbortSignal }} options - Traversal options
    * @yields {TraversalNode} Nodes in BFS order
    */
   async *bfs({
@@ -127,12 +120,7 @@ export default class DagTraversal {
    *
    * DFS explores as far as possible along each branch before backtracking.
    *
-   * @param {Object} options - Traversal options
-   * @param {string} options.start - Starting node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum nodes to visit
-   * @param {number} [options.maxDepth=1000] - Maximum depth to traverse
-   * @param {TraversalDirection} [options.direction='forward'] - Traversal direction
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ start: string, maxNodes?: number, maxDepth?: number, direction?: TraversalDirection, signal?: AbortSignal }} options - Traversal options
    * @yields {TraversalNode} Nodes in DFS pre-order
    */
   async *dfs({
@@ -180,11 +168,7 @@ export default class DagTraversal {
   /**
    * Yields all ancestors of a node (transitive closure going backwards).
    *
-   * @param {Object} options - Traversal options
-   * @param {string} options.sha - Starting node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum ancestor nodes to yield
-   * @param {number} [options.maxDepth=1000] - Maximum generations to traverse
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ sha: string, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} options - Traversal options
    * @yields {TraversalNode} Ancestor nodes in BFS order
    */
   async *ancestors({ sha, maxNodes = DEFAULT_MAX_NODES, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
@@ -194,11 +178,7 @@ export default class DagTraversal {
   /**
    * Yields all descendants of a node (transitive closure going forwards).
    *
-   * @param {Object} options - Traversal options
-   * @param {string} options.sha - Starting node SHA
-   * @param {number} [options.maxNodes=100000] - Maximum descendant nodes to yield
-   * @param {number} [options.maxDepth=1000] - Maximum generations to traverse
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ sha: string, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} options - Traversal options
    * @yields {TraversalNode} Descendant nodes in BFS order
    */
   async *descendants({ sha, maxNodes = DEFAULT_MAX_NODES, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
@@ -211,11 +191,7 @@ export default class DagTraversal {
    * Delegates to the path-finding service's findPath if one is set,
    * otherwise performs its own BFS-based reachability check.
    *
-   * @param {Object} options - Reachability options
-   * @param {string} options.from - Source node SHA
-   * @param {string} options.to - Target node SHA
-   * @param {number} [options.maxDepth=1000] - Maximum search depth
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @param {{ from: string, to: string, maxDepth?: number, signal?: AbortSignal }} options - Reachability options
    * @returns {Promise<boolean>} True if a path exists
    */
   async isReachable({ from, to, maxDepth = DEFAULT_MAX_DEPTH, signal }) {

package/src/domain/services/Frontier.js

@@ -49,9 +49,8 @@ export function getWriters(frontier) {
  * Serializes frontier to canonical CBOR bytes.
  * Keys are sorted for determinism.
  * @param {Frontier} frontier
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer|Uint8Array}
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
+ * @returns {Uint8Array}
  */
 export function serializeFrontier(frontier, { codec } = /** @type {{codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
   const c = codec || defaultCodec;
@@ -67,9 +66,8 @@ export function serializeFrontier(frontier, { codec } = /** @type {{codec?: impo
 
 /**
  * Deserializes frontier from CBOR bytes.
- * @param {Buffer} buffer
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {Uint8Array} buffer
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Frontier}
  */
 export function deserializeFrontier(buffer, { codec } = /** @type {{codec?: import('../../ports/CodecPort.js').default}} */ ({})) {

package/src/domain/services/GitLogParser.js

@@ -88,8 +88,7 @@ export default class GitLogParser {
    *
    * @param {AsyncIterable<Buffer|Uint8Array|string>} stream - The git log output stream.
    *   May yield Buffer, Uint8Array, or string chunks.
-   * @param {Object} [options] - Parse options
-   * @param {AbortSignal} [options.signal] - Optional abort signal for cancellation
+   * @param {{ signal?: AbortSignal }} [options] - Parse options
    * @yields {GraphNode} Parsed graph nodes. Invalid records are silently skipped.
    * @throws {OperationAbortedError} If signal is aborted during parsing
    *