@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/services/BitmapIndexReader.js

@@ -29,7 +29,7 @@ const DEFAULT_MAX_CACHED_SHARDS = 100;
  * Computes a SHA-256 checksum of the given data.
  * Used to verify shard integrity on load.
  *
- * @param {Object} data - The data object to checksum
+ * @param {Record<string, unknown>} data - The data object to checksum
  * @param {number} version - Shard version (1 uses JSON.stringify, 2+ uses canonicalStringify)
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
  * @returns {Promise<string>} Hex-encoded SHA-256 hash
@@ -82,16 +82,9 @@ const computeChecksum = async (data, version, crypto) => {
 export default class BitmapIndexReader {
   /**
    * Creates a BitmapIndexReader instance.
-   * @param {Object} options
-   * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
-   * @param {boolean} [options.strict=true] - If true, throw errors on validation failures; if false, log warnings and return empty shards
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
-   *   Defaults to NoOpLogger (no logging).
-   * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
-   *   When exceeded, least recently used shards are evicted to free memory.
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
+   * @param {{ storage: IndexStoragePort, strict?: boolean, logger?: import('../../ports/LoggerPort.js').default, maxCachedShards?: number, crypto?: import('../../ports/CryptoPort.js').default }} options
    */
-  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
+  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto }) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -321,10 +314,7 @@ export default class BitmapIndexReader {
   /**
    * Handles validation/corruption errors based on strict mode.
    * @param {ShardCorruptionError|ShardValidationError} err - The error to handle
-   * @param {Object} context - Error context
-   * @param {string} context.path - Shard path
-   * @param {string} context.oid - Object ID
-   * @param {string} context.format - 'json' or 'bitmap'
+   * @param {{ path: string, oid: string, format: string }} context - Error context
    * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset} Empty shard (non-strict mode only)
    * @throws {ShardCorruptionError|ShardValidationError} In strict mode
    * @private
@@ -356,7 +346,7 @@ export default class BitmapIndexReader {
 
   /**
    * Parses and validates a shard buffer.
-   * @param {Buffer} buffer - Raw shard buffer
+   * @param {Uint8Array} buffer - Raw shard buffer
    * @param {string} path - Shard path (for error context)
    * @param {string} oid - Object ID (for error context)
    * @returns {Promise<Record<string, string | number>>} The validated data from the shard
@@ -373,7 +363,7 @@ export default class BitmapIndexReader {
    * Loads raw buffer from storage.
    * @param {string} path - Shard path
    * @param {string} oid - Object ID
-   * @returns {Promise<Buffer>} Raw buffer
+   * @returns {Promise<Uint8Array>} Raw buffer
    * @throws {ShardLoadError} When storage.readBlob fails
    * @private
    */
@@ -413,10 +403,7 @@ export default class BitmapIndexReader {
    * Attempts to handle a shard error based on its type.
    * Returns handled result for validation/corruption errors, null otherwise.
    * @param {unknown} err - The error to handle
-   * @param {Object} context - Error context
-   * @param {string} context.path - Shard path
-   * @param {string} context.oid - Object ID
-   * @param {string} context.format - 'json' or 'bitmap'
+   * @param {{ path: string, oid: string, format: string }} context - Error context
    * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset | null} Handled result or null if error should be re-thrown
    * @private
    */

package/src/domain/services/BitmapNeighborProvider.js

@@ -59,9 +59,7 @@ function dedupSorted(edges) {
 
 export default class BitmapNeighborProvider extends NeighborProviderPort {
   /**
-   * @param {Object} params
-   * @param {BitmapIndexReader} [params.indexReader] - For commit DAG mode
-   * @param {LogicalIndex} [params.logicalIndex] - For logical graph mode
+   * @param {{ indexReader?: BitmapIndexReader, logicalIndex?: LogicalIndex }} params
    */
   constructor({ indexReader, logicalIndex }) {
     super();

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
  */
@@ -164,6 +154,7 @@ export async function createBTR(initialState, payload, options) {
     throw new TypeError('payload must be a ProvenancePayload');
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- wall-clock default for BTR timestamp
   const { key, timestamp = new Date().toISOString(), crypto, codec } = options;
 
   // Validate HMAC key is not empty/falsy
@@ -245,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
  */
@@ -275,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 = {}) {
@@ -367,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 } = {}) {
@@ -388,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

@@ -5,6 +5,11 @@
  * materialized graph state. See {@link module:domain/services/WarpMessageCodec}
  * for the facade that re-exports all codec functions.
  *
+ * **Schema namespace note:** Checkpoint schema versions (2, 3, 4) are
+ * distinct from patch schema versions (PATCH_SCHEMA_V2, PATCH_SCHEMA_V3).
+ * See {@link module:domain/services/CheckpointService} for named constants
+ * `CHECKPOINT_SCHEMA_STANDARD` and `CHECKPOINT_SCHEMA_INDEX_TREE`.
+ *
  * @module domain/services/CheckpointMessageCodec
  */
 
@@ -25,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

@@ -28,6 +28,24 @@ import { cloneStateV5, reduceV5 } from './JoinReducer.js';
 import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
+// ============================================================================
+// Checkpoint Schema Constants
+// ============================================================================
+
+/**
+ * Standard checkpoint schema — full V5 state without index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_STANDARD = 2;
+
+/**
+ * Index-tree checkpoint schema — full V5 state with bitmap index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_INDEX_TREE = 4;
+
 // ============================================================================
 // Internal Helpers
 // ============================================================================
@@ -91,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 }) {
@@ -120,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({
@@ -169,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)
@@ -244,7 +242,7 @@ export async function createV5({
     indexOid: treeOid,
     // Schema 3 was used for edge-property-aware patches but is never emitted
     // by checkpoint creation. Schema 4 indicates an index tree is present.
-    schema: indexTree ? 4 : 2,
+    schema: indexTree ? CHECKPOINT_SCHEMA_INDEX_TREE : CHECKPOINT_SCHEMA_STANDARD,
   });
 
   // 9. Create the checkpoint commit
@@ -275,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)
  */
@@ -357,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)
@@ -412,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 }) {