@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/domain/services/BoundaryTransitionRecord.js

@@ -82,10 +82,10 @@ const BTR_VERSION = 1;
  * @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} fields.P - Serialized provenance payload
+ * @param {Array<*>} fields.P - Serialized provenance payload
  * @param {string} fields.t - ISO timestamp
  * @param {string|Uint8Array} key - HMAC key
- * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
+ * @param {{ crypto: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} deps - Dependencies
  * @returns {Promise<string>} Hex-encoded HMAC tag
  * @private
  */
@@ -111,7 +111,7 @@ async function computeHmac(fields, key, { crypto, codec }) {
  * @property {string} h_in - Hash of input state (hex SHA-256)
  * @property {string} h_out - Hash of output state (hex SHA-256)
  * @property {Uint8Array} U_0 - Serialized initial state (CBOR)
- * @property {Array} P - Serialized provenance payload
+ * @property {Array<*>} P - Serialized provenance payload
  * @property {string} t - ISO 8601 timestamp
  * @property {string} kappa - Authentication tag (hex HMAC-SHA256)
  */
@@ -155,6 +155,7 @@ async function computeHmac(fields, key, { crypto, codec }) {
  * @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
  * @returns {Promise<BTR>} The created BTR
  * @throws {TypeError} If payload is not a ProvenancePayload
  */
@@ -212,7 +213,7 @@ function validateBTRStructure(btr) {
  *
  * @param {BTR} btr - The BTR to verify
  * @param {string|Uint8Array} key - HMAC key
- * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
+ * @param {{ crypto: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} deps - Dependencies
  * @returns {Promise<boolean>} True if the HMAC tag matches
  * @private
  */
@@ -243,10 +244,13 @@ 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
  * @returns {Promise<string|null>} Error message if replay mismatch, null if valid
  * @private
  */
-async function verifyReplayHash(btr, { crypto, codec } = {}) {
+async function verifyReplayHash(btr, { crypto, codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   try {
     const result = await replayBTR(btr, { crypto, codec });
     if (result.h_out !== btr.h_out) {
@@ -254,7 +258,7 @@ async function verifyReplayHash(btr, { crypto, codec } = {}) {
     }
     return null;
   } catch (err) {
-    return `Replay failed: ${err.message}`;
+    return `Replay failed: ${/** @type {any} */ (err).message}`; // TODO(ts-cleanup): type error
   }
 }
 
@@ -272,10 +276,11 @@ async function verifyReplayHash(btr, { crypto, codec } = {}) {
  * @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/CryptoPort.js').default} [options.crypto] - CryptoPort instance
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
  * @returns {Promise<VerificationResult>} Verification result with valid flag and optional reason
  */
-export async function verifyBTR(btr, key, options = {}) {
+export async function verifyBTR(btr, key, options = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const { crypto, codec } = options;
 
   const structureError = validateBTRStructure(btr);
@@ -285,7 +290,7 @@ export async function verifyBTR(btr, key, options = {}) {
 
   let hmacValid;
   try {
-    hmacValid = await verifyHmac(btr, key, { crypto, codec });
+    hmacValid = await verifyHmac(btr, key, { crypto: /** @type {import('../../ports/CryptoPort.js').default} */ (crypto), codec });
   } catch (err) {
     if (err instanceof RangeError) {
       return { valid: false, reason: `Invalid hex in authentication tag: ${err.message}` };
@@ -313,11 +318,12 @@ export async function verifyBTR(btr, key, options = {}) {
  * encoding (U_0, P), replay uniquely determines the interior worldline.
  *
  * @param {BTR} btr - The BTR to replay
+ * @param {{ crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} deps - Dependencies
  * @returns {Promise<{ state: import('./JoinReducer.js').WarpStateV5, h_out: string }>}
  *   The final state and its hash
  * @throws {Error} If replay fails
  */
-export async function replayBTR(btr, { crypto, codec } = {}) {
+export async function replayBTR(btr, { crypto, codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   // Deserialize initial state from U_0
   // Note: U_0 is the full serialized state (via serializeFullStateV5)
   const initialState = deserializeInitialState(btr.U_0, { codec });
@@ -329,7 +335,7 @@ export async function replayBTR(btr, { crypto, codec } = {}) {
   const finalState = payload.replay(initialState);
 
   // Compute h_out
-  const h_out = await computeStateHashV5(finalState, { crypto, codec });
+  const h_out = await computeStateHashV5(finalState, { crypto: /** @type {import('../../ports/CryptoPort.js').default} */ (crypto), codec });
 
   return { state: finalState, h_out };
 }
@@ -345,10 +351,11 @@ export async function replayBTR(btr, { crypto, codec } = {}) {
  * the correct h_out hash.
  *
  * @param {Uint8Array} U_0 - Serialized full state
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} options
  * @returns {import('./JoinReducer.js').WarpStateV5} The deserialized state
  * @private
  */
-function deserializeInitialState(U_0, { codec } = {}) {
+function deserializeInitialState(U_0, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   return deserializeFullStateV5(U_0, { codec });
 }
 
@@ -363,7 +370,7 @@ function deserializeInitialState(U_0, { codec } = {}) {
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
  * @returns {Uint8Array} CBOR-encoded BTR
  */
-export function serializeBTR(btr, { codec } = {}) {
+export function serializeBTR(btr, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
   return c.encode({
     version: btr.version,
@@ -385,9 +392,9 @@ export function serializeBTR(btr, { codec } = {}) {
  * @returns {BTR} The deserialized BTR
  * @throws {Error} If the bytes are not valid CBOR or missing required fields
  */
-export function deserializeBTR(bytes, { codec } = {}) {
+export function deserializeBTR(bytes, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
-  const obj = c.decode(bytes);
+  const obj = /** @type {Record<string, *>} */ (c.decode(bytes));
 
   // Validate structure (reuse module-level constant for consistency with validateBTRStructure)
   for (const field of REQUIRED_FIELDS) {

package/src/domain/services/CheckpointMessageCodec.js

@@ -79,13 +79,7 @@ export function encodeCheckpointMessage({ graph, stateHash, frontierOid, indexOi
  * Decodes a checkpoint commit message.
  *
  * @param {string} message - The raw commit message
- * @returns {Object} The decoded checkpoint message
- * @returns {string} return.kind - Always 'checkpoint'
- * @returns {string} return.graph - The graph name
- * @returns {string} return.stateHash - The SHA-256 state hash
- * @returns {string} return.frontierOid - The frontier blob OID
- * @returns {string} return.indexOid - The index tree OID
- * @returns {number} return.schema - The schema version
+ * @returns {{ kind: 'checkpoint', graph: string, stateHash: string, frontierOid: string, indexOid: string, schema: number, checkpointVersion: string|null }} The decoded checkpoint message
  * @throws {Error} If the message is not a valid checkpoint message
  *
  * @example

package/src/domain/services/CheckpointSerializerV5.js

@@ -37,9 +37,9 @@ 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} CBOR-encoded full state
+ * @returns {Buffer|Uint8Array} CBOR-encoded full state
  */
-export function serializeFullStateV5(state, { codec } = {}) {
+export function serializeFullStateV5(state, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
   // Serialize ORSets using existing serialization
   const nodeAliveObj = orsetSerialize(state.nodeAlive);
@@ -84,20 +84,20 @@ export function serializeFullStateV5(state, { codec } = {}) {
 /**
  * Deserializes full V5 state. Used for resume.
  *
- * @param {Buffer} buffer - CBOR-encoded full state
+ * @param {Buffer|Uint8Array} buffer - CBOR-encoded full state
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {import('./JoinReducer.js').WarpStateV5}
  */
 // eslint-disable-next-line complexity
-export function deserializeFullStateV5(buffer, { codec: codecOpt } = {}) {
+export function deserializeFullStateV5(buffer, { codec: codecOpt } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const codec = codecOpt || defaultCodec;
   // Handle null/undefined buffer before attempting decode
   if (buffer === null || buffer === undefined) {
     return createEmptyStateV5();
   }
 
-  const obj = codec.decode(buffer);
+  const obj = /** @type {Record<string, *>} */ (codec.decode(buffer));
 
   // Handle null/undefined decoded result: return empty state
   if (obj === null || obj === undefined) {
@@ -117,7 +117,7 @@ export function deserializeFullStateV5(buffer, { codec: codecOpt } = {}) {
     edgeAlive: orsetDeserialize(obj.edgeAlive || {}),
     prop: deserializeProps(obj.prop),
     observedFrontier: vvDeserialize(obj.observedFrontier || {}),
-    edgeBirthEvent: deserializeEdgeBirthEvent(obj),
+    edgeBirthEvent: /** @type {Map<string, import('../utils/EventId.js').EventId>} */ (deserializeEdgeBirthEvent(obj)),
   };
 }
 
@@ -170,9 +170,9 @@ export function computeAppliedVV(state) {
  * @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} CBOR-encoded version vector
+ * @returns {Buffer|Uint8Array} CBOR-encoded version vector
  */
-export function serializeAppliedVV(vv, { codec } = {}) {
+export function serializeAppliedVV(vv, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
   const obj = vvSerialize(vv);
   return c.encode(obj);
@@ -181,14 +181,14 @@ export function serializeAppliedVV(vv, { codec } = {}) {
 /**
  * Deserializes appliedVV from CBOR format.
  *
- * @param {Buffer} buffer - CBOR-encoded version vector
+ * @param {Buffer|Uint8Array} buffer - CBOR-encoded version vector
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Map<string, number>} Version vector
  */
-export function deserializeAppliedVV(buffer, { codec } = {}) {
+export function deserializeAppliedVV(buffer, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
-  const obj = c.decode(buffer);
+  const obj = /** @type {{ [x: string]: number }} */ (c.decode(buffer));
   return vvDeserialize(obj);
 }
 
@@ -198,8 +198,8 @@ export function deserializeAppliedVV(buffer, { codec } = {}) {
 
 /**
  * Deserializes the props array from checkpoint format.
- * @param {Array} propArray - Array of [key, registerObj] pairs
- * @returns {Map<string, import('../crdt/LWW.js').LWWRegister>}
+ * @param {Array<*>} propArray - Array of [key, registerObj] pairs
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<*>>}
  */
 function deserializeProps(propArray) {
   const prop = new Map();
@@ -213,10 +213,11 @@ function deserializeProps(propArray) {
 
 /**
  * Deserializes edge birth event data, supporting both legacy and current formats.
- * @param {Object} obj - The decoded checkpoint object
- * @returns {Map<string, Object>}
+ * @param {Record<string, *>} obj - The decoded checkpoint object
+ * @returns {Map<string, import('../utils/EventId.js').EventId>}
  */
 function deserializeEdgeBirthEvent(obj) {
+  /** @type {Map<string, import('../utils/EventId.js').EventId>} */
   const edgeBirthEvent = new Map();
   const birthData = obj.edgeBirthEvent || obj.edgeBirthLamport;
   if (birthData && Array.isArray(birthData)) {
@@ -239,8 +240,8 @@ function deserializeEdgeBirthEvent(obj) {
  * Serializes an LWW register for CBOR encoding.
  * EventId is serialized as a plain object with sorted keys.
  *
- * @param {import('../crdt/LWW.js').LWWRegister} register
- * @returns {Object}
+ * @param {import('../crdt/LWW.js').LWWRegister<*>} register
+ * @returns {{ eventId: { lamport: number, opIndex: number, patchSha: string, writerId: string }, value: * } | null}
  */
 function serializeLWWRegister(register) {
   if (!register) {
@@ -261,8 +262,8 @@ function serializeLWWRegister(register) {
 /**
  * Deserializes an LWW register from CBOR.
  *
- * @param {Object} obj
- * @returns {import('../crdt/LWW.js').LWWRegister}
+ * @param {{ eventId: { lamport: number, writerId: string, patchSha: string, opIndex: number }, value: * } | null} obj
+ * @returns {import('../crdt/LWW.js').LWWRegister<*> | null}
  */
 function deserializeLWWRegister(obj) {
   if (!obj) {

package/src/domain/services/CheckpointService.js

@@ -46,7 +46,7 @@ import { ProvenanceIndex } from './ProvenanceIndex.js';
  * ```
  *
  * @param {Object} options - Checkpoint creation options
- * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @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
@@ -75,7 +75,7 @@ export async function create({ persistence, graphName, state, frontier, parents
  * ```
  *
  * @param {Object} options - Checkpoint creation options
- * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @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
@@ -113,23 +113,23 @@ export async function createV5({
 
   // 4. Serialize visible projection (CACHE)
   const visibleBuffer = serializeStateV5(checkpointState, { codec });
-  const stateHash = await computeStateHashV5(checkpointState, { codec, crypto });
+  const stateHash = await computeStateHashV5(checkpointState, { codec, crypto: /** @type {import('../../ports/CryptoPort.js').default} */ (crypto) });
 
   // 5. Serialize frontier and appliedVV
-  const frontierBuffer = serializeFrontier(frontier, { codec });
-  const appliedVVBuffer = serializeAppliedVV(appliedVV, { codec });
+  const frontierBuffer = serializeFrontier(frontier, { codec: /** @type {import('../../ports/CodecPort.js').default} */ (codec) });
+  const appliedVVBuffer = serializeAppliedVV(appliedVV, { codec: /** @type {import('../../ports/CodecPort.js').default} */ (codec) });
 
   // 6. Write blobs to git
-  const stateBlobOid = await persistence.writeBlob(stateBuffer);
-  const visibleBlobOid = await persistence.writeBlob(visibleBuffer);
-  const frontierBlobOid = await persistence.writeBlob(frontierBuffer);
-  const appliedVVBlobOid = await persistence.writeBlob(appliedVVBuffer);
+  const stateBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (stateBuffer));
+  const visibleBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (visibleBuffer));
+  const frontierBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (frontierBuffer));
+  const appliedVVBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (appliedVVBuffer));
 
   // 6b. Optionally serialize and write provenance index
   let provenanceIndexBlobOid = null;
   if (provenanceIndex) {
     const provenanceIndexBuffer = provenanceIndex.serialize({ codec });
-    provenanceIndexBlobOid = await persistence.writeBlob(provenanceIndexBuffer);
+    provenanceIndexBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (provenanceIndexBuffer));
   }
 
   // 7. Create tree with sorted entries
@@ -189,17 +189,17 @@ export async function createV5({
  * Schema:1 checkpoints are not supported and will throw an error.
  * Use MigrationService to upgrade schema:1 checkpoints first.
  *
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence adapter
+ * @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
- * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, stateHash: string, schema: number, appliedVV?: Map<string, number>, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex}>} The loaded checkpoint data
+ * @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}>} The loaded checkpoint data
  * @throws {Error} If checkpoint is schema:1 (migration required)
  */
-export async function loadCheckpoint(persistence, checkpointSha, { codec } = {}) {
+export async function loadCheckpoint(persistence, checkpointSha, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   // 1. Read commit message and decode
   const message = await persistence.showNode(checkpointSha);
-  const decoded = decodeCheckpointMessage(message);
+  const decoded = /** @type {{ schema: number, stateHash: string, indexOid: string }} */ (decodeCheckpointMessage(message));
 
   // 2. Reject schema:1 checkpoints - migration required
   if (decoded.schema !== 2 && decoded.schema !== 3) {
@@ -218,7 +218,7 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
     throw new Error(`Checkpoint ${checkpointSha} missing frontier.cbor in tree`);
   }
   const frontierBuffer = await persistence.readBlob(frontierOid);
-  const frontier = deserializeFrontier(frontierBuffer, { codec });
+  const frontier = deserializeFrontier(frontierBuffer, { codec: /** @type {import('../../ports/CodecPort.js').default} */ (codec) });
 
   // 5. Read state.cbor blob and deserialize as V5 full state
   const stateOid = treeOids['state.cbor'];
@@ -252,7 +252,7 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
     stateHash: decoded.stateHash,
     schema: decoded.schema,
     appliedVV,
-    provenanceIndex,
+    provenanceIndex: provenanceIndex || undefined,
   };
 }
 
@@ -270,7 +270,7 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
  * loadCheckpoint to throw an error.
  *
  * @param {Object} options - Materialization options
- * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @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
@@ -313,7 +313,7 @@ export async function materializeIncremental({
   }
 
   // 5. Apply new patches using V5 reducer with checkpoint state as initial
-  const finalState = reduceV5(allPatches, initialState);
+  const finalState = /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(allPatches, initialState));
 
   return finalState;
 }

package/src/domain/services/CommitDagTraversalService.js

@@ -39,7 +39,7 @@ export default class CommitDagTraversalService {
    * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
    */
-  constructor({ indexReader, logger = nullLogger } = {}) {
+  constructor({ indexReader, logger = nullLogger } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     if (!indexReader) {
       throw new Error('CommitDagTraversalService requires an indexReader');
     }
@@ -56,6 +56,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Breadth-first traversal from a starting node.
+   * @param {*} options
    * @see DagTraversal#bfs
    */
   bfs(options) {
@@ -64,6 +65,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Depth-first pre-order traversal from a starting node.
+   * @param {*} options
    * @see DagTraversal#dfs
    */
   dfs(options) {
@@ -72,6 +74,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields all ancestors of a node.
+   * @param {*} options
    * @see DagTraversal#ancestors
    */
   ancestors(options) {
@@ -80,6 +83,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields all descendants of a node.
+   * @param {*} options
    * @see DagTraversal#descendants
    */
   descendants(options) {
@@ -88,6 +92,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Checks if there is any path from one node to another.
+   * @param {*} options
    * @see DagTraversal#isReachable
    */
   isReachable(options) {
@@ -98,6 +103,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds ANY path between two nodes using BFS.
+   * @param {*} options
    * @see DagPathFinding#findPath
    */
   findPath(options) {
@@ -106,6 +112,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds the shortest path using bidirectional BFS.
+   * @param {*} options
    * @see DagPathFinding#shortestPath
    */
   shortestPath(options) {
@@ -114,6 +121,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds shortest path using Dijkstra's algorithm.
+   * @param {*} options
    * @see DagPathFinding#weightedShortestPath
    */
   weightedShortestPath(options) {
@@ -122,6 +130,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds shortest path using A* with heuristic guidance.
+   * @param {*} options
    * @see DagPathFinding#aStarSearch
    */
   aStarSearch(options) {
@@ -130,6 +139,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Bi-directional A* search.
+   * @param {*} options
    * @see DagPathFinding#bidirectionalAStar
    */
   bidirectionalAStar(options) {
@@ -140,6 +150,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds common ancestors of multiple nodes.
+   * @param {*} options
    * @see DagTopology#commonAncestors
    */
   commonAncestors(options) {
@@ -148,6 +159,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields nodes in topological order using Kahn's algorithm.
+   * @param {*} options
    * @see DagTopology#topologicalSort
    */
   topologicalSort(options) {

package/src/domain/services/DagPathFinding.js

@@ -41,7 +41,7 @@ export default class DagPathFinding {
    * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
    */
-  constructor({ indexReader, logger = nullLogger } = {}) {
+  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     if (!indexReader) {
       throw new Error('DagPathFinding requires an indexReader');
     }
@@ -85,7 +85,7 @@ export default class DagPathFinding {
         checkAborted(signal, 'findPath');
       }
 
-      const current = queue.shift();
+      const current = /** @type {{sha: string, depth: number}} */ (queue.shift());
 
       if (current.depth > maxDepth) { continue; }
       if (visited.has(current.sha)) { continue; }
@@ -200,7 +200,7 @@ export default class DagPathFinding {
    * @param {Object} options - Path finding options
    * @param {string} options.from - Starting SHA
    * @param {string} options.to - Target SHA
-   * @param {Function} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
+   * @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
    * @returns {Promise<{path: string[], totalCost: number}>} Path and cost
@@ -277,8 +277,8 @@ export default class DagPathFinding {
    * @param {Object} options - Path finding options
    * @param {string} options.from - Starting SHA
    * @param {string} options.to - Target SHA
-   * @param {Function} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
-   * @param {Function} [options.heuristicProvider] - Callback `(sha, targetSha) => number`
+   * @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
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>} Path result
@@ -367,9 +367,9 @@ export default class DagPathFinding {
    * @param {Object} options - Path finding options
    * @param {string} options.from - Starting SHA
    * @param {string} options.to - Target SHA
-   * @param {Function} [options.weightProvider] - Async callback `(fromSha, toSha) => number`
-   * @param {Function} [options.forwardHeuristic] - Callback for forward search
-   * @param {Function} [options.backwardHeuristic] - Callback for backward search
+   * @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
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>} Path result
    * @throws {TraversalError} With code 'NO_PATH' if no path exists
@@ -463,6 +463,17 @@ 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} 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
    * @returns {Promise<{explored: number, mu: number, meetingPoint: string|null}>}
    * @private
    */
@@ -484,7 +495,7 @@ export default class DagPathFinding {
     explored = 1;
 
     if (bwdVisited.has(current)) {
-      const totalCost = fwdGScore.get(current) + bwdGScore.get(current);
+      const totalCost = /** @type {number} */ (fwdGScore.get(current)) + /** @type {number} */ (bwdGScore.get(current));
       if (totalCost < bestMu) {
         bestMu = totalCost;
         bestMeeting = current;
@@ -498,8 +509,8 @@ export default class DagPathFinding {
       }
 
       const edgeWeight = await weightProvider(current, child);
-      const tentativeG = fwdGScore.get(current) + edgeWeight;
-      const currentG = fwdGScore.has(child) ? fwdGScore.get(child) : Infinity;
+      const tentativeG = /** @type {number} */ (fwdGScore.get(current)) + edgeWeight;
+      const currentG = fwdGScore.has(child) ? /** @type {number} */ (fwdGScore.get(child)) : Infinity;
 
       if (tentativeG < currentG) {
         fwdPrevious.set(child, current);
@@ -509,7 +520,7 @@ export default class DagPathFinding {
         fwdHeap.insert(child, f);
 
         if (bwdGScore.has(child)) {
-          const totalCost = tentativeG + bwdGScore.get(child);
+          const totalCost = tentativeG + /** @type {number} */ (bwdGScore.get(child));
           if (totalCost < bestMu) {
             bestMu = totalCost;
             bestMeeting = child;
@@ -525,6 +536,17 @@ 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} 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
    * @returns {Promise<{explored: number, mu: number, meetingPoint: string|null}>}
    * @private
    */
@@ -546,7 +568,7 @@ export default class DagPathFinding {
     explored = 1;
 
     if (fwdVisited.has(current)) {
-      const totalCost = fwdGScore.get(current) + bwdGScore.get(current);
+      const totalCost = /** @type {number} */ (fwdGScore.get(current)) + /** @type {number} */ (bwdGScore.get(current));
       if (totalCost < bestMu) {
         bestMu = totalCost;
         bestMeeting = current;
@@ -560,8 +582,8 @@ export default class DagPathFinding {
       }
 
       const edgeWeight = await weightProvider(parent, current);
-      const tentativeG = bwdGScore.get(current) + edgeWeight;
-      const currentG = bwdGScore.has(parent) ? bwdGScore.get(parent) : Infinity;
+      const tentativeG = /** @type {number} */ (bwdGScore.get(current)) + edgeWeight;
+      const currentG = bwdGScore.has(parent) ? /** @type {number} */ (bwdGScore.get(parent)) : Infinity;
 
       if (tentativeG < currentG) {
         bwdNext.set(parent, current);
@@ -571,7 +593,7 @@ export default class DagPathFinding {
         bwdHeap.insert(parent, f);
 
         if (fwdGScore.has(parent)) {
-          const totalCost = fwdGScore.get(parent) + tentativeG;
+          const totalCost = /** @type {number} */ (fwdGScore.get(parent)) + tentativeG;
           if (totalCost < bestMu) {
             bestMu = totalCost;
             bestMeeting = parent;
@@ -691,7 +713,7 @@ export default class DagPathFinding {
     const forwardPath = [meeting];
     let current = meeting;
     while (fwdParent.has(current) && fwdParent.get(current) !== undefined) {
-      current = fwdParent.get(current);
+      current = /** @type {string} */ (fwdParent.get(current));
       forwardPath.unshift(current);
     }
     if (forwardPath[0] !== from) {
@@ -700,7 +722,7 @@ export default class DagPathFinding {
 
     current = meeting;
     while (bwdParent.has(current) && bwdParent.get(current) !== undefined) {
-      current = bwdParent.get(current);
+      current = /** @type {string} */ (bwdParent.get(current));
       forwardPath.push(current);
     }
     if (forwardPath[forwardPath.length - 1] !== to) {