@git-stunts/git-warp 11.2.1 → 11.3.3

package/src/domain/services/BitmapIndexReader.js

@@ -6,6 +6,7 @@ import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
 
 /** @typedef {import('../../ports/IndexStoragePort.js').default} IndexStoragePort */
+/** @typedef {import('../types/WarpPersistence.js').IndexStorage} IndexStorage */
 /** @typedef {import('../../ports/LoggerPort.js').default} LoggerPort */
 /** @typedef {import('../../ports/CryptoPort.js').default} CryptoPort */
 
@@ -89,11 +90,11 @@ export default class BitmapIndexReader {
    *   When exceeded, least recently used shards are evicted to free memory.
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
    */
-  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
-    this.storage = storage;
+    this.storage = /** @type {IndexStorage} */ (storage);
     this.strict = strict;
     this.logger = logger;
     this.maxCachedShards = maxCachedShards;
@@ -144,7 +145,8 @@ export default class BitmapIndexReader {
   async lookupId(sha) {
     const prefix = sha.substring(0, 2);
     const path = `meta_${prefix}.json`;
-    const idMap = await this._getOrLoadShard(path, 'json');
+    // Meta shards always map SHA→numeric ID (built by BitmapIndexBuilder)
+    const idMap = /** @type {Record<string, number>} */ (await this._getOrLoadShard(path, 'json'));
     return idMap[sha];
   }
 
@@ -176,7 +178,8 @@ export default class BitmapIndexReader {
   async _getEdges(sha, type) {
     const prefix = sha.substring(0, 2);
     const shardPath = `shards_${type}_${prefix}.json`;
-    const shard = await this._getOrLoadShard(shardPath, 'json');
+    // Bitmap shards always map SHA→base64-encoded bitmap data
+    const shard = /** @type {Record<string, string>} */ (await this._getOrLoadShard(shardPath, 'json'));
 
     const encoded = shard[sha];
     if (!encoded) {
@@ -195,7 +198,7 @@ export default class BitmapIndexReader {
         shardPath,
         oid: this.shardOids.get(shardPath),
         reason: 'bitmap_deserialize_error',
-        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
+        context: { originalError: err instanceof Error ? err.message : String(err) },
       });
       this._handleShardError(corruptionError, {
         path: shardPath,
@@ -224,7 +227,8 @@ export default class BitmapIndexReader {
 
     for (const [path] of this.shardOids) {
       if (path.startsWith('meta_') && path.endsWith('.json')) {
-        const shard = await this._getOrLoadShard(path, 'json');
+        // Meta shards always map SHA→numeric ID (built by BitmapIndexBuilder)
+        const shard = /** @type {Record<string, number>} */ (await this._getOrLoadShard(path, 'json'));
         for (const [sha, id] of Object.entries(shard)) {
           this._idToShaCache[id] = sha;
         }
@@ -247,10 +251,10 @@ export default class BitmapIndexReader {
   /**
    * Validates a shard envelope for version and checksum integrity.
    *
-   * @param {{ data?: any, version?: number, checksum?: string }} envelope - The shard envelope to validate
+   * @param {{ data?: Record<string, string | number>, version?: number, checksum?: string }} envelope - The shard envelope to validate
    * @param {string} path - Shard path (for error context)
    * @param {string} oid - Object ID (for error context)
-   * @returns {Promise<any>} The validated data from the envelope
+   * @returns {Promise<Record<string, string | number>>} The validated data from the envelope
    * @throws {ShardCorruptionError} If envelope format is invalid
    * @throws {ShardValidationError} If version or checksum validation fails
    * @private
@@ -299,7 +303,7 @@ export default class BitmapIndexReader {
    * @param {string} context.path - Shard path
    * @param {string} context.oid - Object ID
    * @param {string} context.format - 'json' or 'bitmap'
-   * @returns {any} Empty shard (non-strict mode only)
+   * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset} Empty shard (non-strict mode only)
    * @throws {ShardCorruptionError|ShardValidationError} In strict mode
    * @private
    */
@@ -307,17 +311,21 @@ export default class BitmapIndexReader {
     if (this.strict) {
       throw err;
     }
-    /** @type {any} */ // TODO(ts-cleanup): type lazy singleton
-    const errAny = err;
+    /** @type {string|undefined} */
+    const field = err instanceof ShardValidationError ? err.field : undefined;
+    /** @type {unknown} */
+    const expected = err instanceof ShardValidationError ? err.expected : undefined;
+    /** @type {unknown} */
+    const actual = err instanceof ShardValidationError ? err.actual : undefined;
     this.logger.warn('Shard validation warning', {
       operation: 'loadShard',
       shardPath: path,
       oid,
       error: err.message,
       code: err.code,
-      field: errAny.field,
-      expected: errAny.expected,
-      actual: errAny.actual,
+      field,
+      expected,
+      actual,
     });
     const emptyShard = format === 'json' ? {} : new (getRoaringBitmap32())();
     this.loadedShards.set(path, emptyShard);
@@ -329,7 +337,7 @@ export default class BitmapIndexReader {
    * @param {Buffer} buffer - Raw shard buffer
    * @param {string} path - Shard path (for error context)
    * @param {string} oid - Object ID (for error context)
-   * @returns {Promise<Object>} The validated data from the shard
+   * @returns {Promise<Record<string, string | number>>} The validated data from the shard
    * @throws {ShardCorruptionError} If parsing fails or format is invalid
    * @throws {ShardValidationError} If version or checksum validation fails
    * @private
@@ -349,7 +357,7 @@ export default class BitmapIndexReader {
    */
   async _loadShardBuffer(path, oid) {
     try {
-      return await /** @type {any} */ (this.storage).readBlob(oid); // TODO(ts-cleanup): narrow port type
+      return await this.storage.readBlob(oid);
     } catch (cause) {
       throw new ShardLoadError('Failed to load shard from storage', {
         shardPath: path,
@@ -382,15 +390,16 @@ export default class BitmapIndexReader {
   /**
    * Attempts to handle a shard error based on its type.
    * Returns handled result for validation/corruption errors, null otherwise.
-   * @param {any} err - The error to handle
+   * @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'
-   * @returns {any} Handled result or null if error should be re-thrown
+   * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset | null} Handled result or null if error should be re-thrown
    * @private
    */
   _tryHandleShardError(err, context) {
+    if (!(err instanceof Error)) { return null; }
     const wrappedErr = this._wrapParseError(err, context.path, context.oid);
     const isHandleable = wrappedErr instanceof ShardCorruptionError ||
                          wrappedErr instanceof ShardValidationError;
@@ -406,7 +415,7 @@ export default class BitmapIndexReader {
    *
    * @param {string} path - Shard path
    * @param {string} format - 'json' or 'bitmap'
-   * @returns {Promise<any>}
+   * @returns {Promise<Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset>}
    * @throws {ShardLoadError} When storage.readBlob fails
    * @throws {ShardCorruptionError} When shard format is invalid (strict mode only)
    * @throws {ShardValidationError} When version or checksum validation fails (strict mode only)

package/src/domain/services/BoundaryTransitionRecord.js

@@ -82,7 +82,7 @@ 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<unknown>} fields.P - Serialized provenance payload
  * @param {string} fields.t - ISO timestamp
  * @param {string|Uint8Array} key - HMAC key
  * @param {{ crypto: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} deps - Dependencies
@@ -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<unknown>} P - Serialized provenance payload
  * @property {string} t - ISO 8601 timestamp
  * @property {string} kappa - Authentication tag (hex HMAC-SHA256)
  */
@@ -189,7 +189,7 @@ const REQUIRED_FIELDS = ['version', 'h_in', 'h_out', 'U_0', 'P', 't', 'kappa'];
 /**
  * Validates BTR structure and returns failure reason if invalid.
  *
- * @param {*} btr - The BTR object to validate
+ * @param {unknown} btr - The BTR object to validate
  * @returns {string|null} Error message if invalid, null if valid
  * @private
  */
@@ -197,13 +197,14 @@ function validateBTRStructure(btr) {
   if (!btr || typeof btr !== 'object') {
     return 'BTR must be an object';
   }
+  const rec = /** @type {Record<string, unknown>} */ (btr);
   for (const field of REQUIRED_FIELDS) {
-    if (!(field in btr)) {
+    if (!(field in rec)) {
       return `Missing required field: ${field}`;
     }
   }
-  if (btr.version !== BTR_VERSION) {
-    return `Unsupported BTR version: ${btr.version} (expected ${BTR_VERSION})`;
+  if (rec.version !== BTR_VERSION) {
+    return `Unsupported BTR version: ${rec.version} (expected ${BTR_VERSION})`;
   }
   return null;
 }
@@ -250,7 +251,7 @@ async function verifyHmac(btr, key, { crypto, codec }) {
  * @returns {Promise<string|null>} Error message if replay mismatch, null if valid
  * @private
  */
-async function verifyReplayHash(btr, { crypto, codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+async function verifyReplayHash(btr, { crypto, codec } = {}) {
   try {
     const result = await replayBTR(btr, { crypto, codec });
     if (result.h_out !== btr.h_out) {
@@ -258,7 +259,7 @@ async function verifyReplayHash(btr, { crypto, codec } = /** @type {*} */ ({}))
     }
     return null;
   } catch (err) {
-    return `Replay failed: ${/** @type {any} */ (err).message}`; // TODO(ts-cleanup): type error
+    return `Replay failed: ${err instanceof Error ? err.message : String(err)}`;
   }
 }
 
@@ -280,7 +281,7 @@ async function verifyReplayHash(btr, { crypto, codec } = /** @type {*} */ ({}))
  * @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 = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function verifyBTR(btr, key, options = {}) {
   const { crypto, codec } = options;
 
   const structureError = validateBTRStructure(btr);
@@ -323,13 +324,13 @@ export async function verifyBTR(btr, key, options = /** @type {*} */ ({})) { //
  *   The final state and its hash
  * @throws {Error} If replay fails
  */
-export async function replayBTR(btr, { crypto, codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function replayBTR(btr, { crypto, codec } = {}) {
   // Deserialize initial state from U_0
   // Note: U_0 is the full serialized state (via serializeFullStateV5)
   const initialState = deserializeInitialState(btr.U_0, { codec });
 
   // Reconstruct payload
-  const payload = ProvenancePayload.fromJSON(btr.P);
+  const payload = ProvenancePayload.fromJSON(/** @type {import('./ProvenancePayload.js').PatchEntry[]} */ (btr.P));
 
   // Replay
   const finalState = payload.replay(initialState);
@@ -355,7 +356,7 @@ export async function replayBTR(btr, { crypto, codec } = /** @type {*} */ ({}))
  * @returns {import('./JoinReducer.js').WarpStateV5} The deserialized state
  * @private
  */
-function deserializeInitialState(U_0, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+function deserializeInitialState(U_0, { codec } = {}) {
   return deserializeFullStateV5(U_0, { codec });
 }
 
@@ -370,7 +371,7 @@ function deserializeInitialState(U_0, { codec } = /** @type {*} */ ({})) { // TO
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
  * @returns {Uint8Array} CBOR-encoded BTR
  */
-export function serializeBTR(btr, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function serializeBTR(btr, { codec } = {}) {
   const c = codec || defaultCodec;
   return c.encode({
     version: btr.version,
@@ -392,9 +393,9 @@ export function serializeBTR(btr, { codec } = /** @type {*} */ ({})) { // TODO(t
  * @returns {BTR} The deserialized BTR
  * @throws {Error} If the bytes are not valid CBOR or missing required fields
  */
-export function deserializeBTR(bytes, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function deserializeBTR(bytes, { codec } = {}) {
   const c = codec || defaultCodec;
-  const obj = /** @type {Record<string, *>} */ (c.decode(bytes));
+  const obj = /** @type {Record<string, unknown>} */ (c.decode(bytes));
 
   // Validate structure (reuse module-level constant for consistency with validateBTRStructure)
   for (const field of REQUIRED_FIELDS) {
@@ -403,7 +404,7 @@ export function deserializeBTR(bytes, { codec } = /** @type {*} */ ({})) { // TO
     }
   }
 
-  return {
+  return /** @type {BTR} */ ({
     version: obj.version,
     h_in: obj.h_in,
     h_out: obj.h_out,
@@ -411,7 +412,7 @@ export function deserializeBTR(bytes, { codec } = /** @type {*} */ ({})) { // TO
     P: obj.P,
     t: obj.t,
     kappa: obj.kappa,
-  };
+  });
 }
 
 /**

package/src/domain/services/CheckpointSerializerV5.js

@@ -39,7 +39,7 @@ import { createEmptyStateV5 } from './JoinReducer.js';
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
  * @returns {Buffer|Uint8Array} CBOR-encoded full state
  */
-export function serializeFullStateV5(state, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function serializeFullStateV5(state, { codec } = {}) {
   const c = codec || defaultCodec;
   // Serialize ORSets using existing serialization
   const nodeAliveObj = orsetSerialize(state.nodeAlive);
@@ -90,14 +90,14 @@ export function serializeFullStateV5(state, { codec } = /** @type {*} */ ({})) {
  * @returns {import('./JoinReducer.js').WarpStateV5}
  */
 // eslint-disable-next-line complexity
-export function deserializeFullStateV5(buffer, { codec: codecOpt } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function deserializeFullStateV5(buffer, { codec: codecOpt } = {}) {
   const codec = codecOpt || defaultCodec;
   // Handle null/undefined buffer before attempting decode
   if (buffer === null || buffer === undefined) {
     return createEmptyStateV5();
   }
 
-  const obj = /** @type {Record<string, *>} */ (codec.decode(buffer));
+  const obj = /** @type {Record<string, unknown>} */ (codec.decode(buffer));
 
   // Handle null/undefined decoded result: return empty state
   if (obj === null || obj === undefined) {
@@ -107,16 +107,17 @@ export function deserializeFullStateV5(buffer, { codec: codecOpt } = /** @type {
   // Handle version mismatch: throw with diagnostic info
   // Accept both 'full-v5' and missing version (for backward compatibility with pre-versioned data)
   if (obj.version !== undefined && obj.version !== 'full-v5') {
+    const ver = /** @type {string} */ (obj.version);
     throw new Error(
-      `Unsupported full state version: expected 'full-v5', got '${obj.version}'`
+      `Unsupported full state version: expected 'full-v5', got '${ver}'`
     );
   }
 
   return {
     nodeAlive: orsetDeserialize(obj.nodeAlive || {}),
     edgeAlive: orsetDeserialize(obj.edgeAlive || {}),
-    prop: deserializeProps(obj.prop),
-    observedFrontier: vvDeserialize(obj.observedFrontier || {}),
+    prop: deserializeProps(/** @type {[string, unknown][]} */ (obj.prop)),
+    observedFrontier: vvDeserialize(/** @type {{[x: string]: number}} */ (obj.observedFrontier || {})),
     edgeBirthEvent: /** @type {Map<string, import('../utils/EventId.js').EventId>} */ (deserializeEdgeBirthEvent(obj)),
   };
 }
@@ -172,7 +173,7 @@ export function computeAppliedVV(state) {
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
  * @returns {Buffer|Uint8Array} CBOR-encoded version vector
  */
-export function serializeAppliedVV(vv, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function serializeAppliedVV(vv, { codec } = {}) {
   const c = codec || defaultCodec;
   const obj = vvSerialize(vv);
   return c.encode(obj);
@@ -186,7 +187,7 @@ export function serializeAppliedVV(vv, { codec } = /** @type {*} */ ({})) { // T
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Map<string, number>} Version vector
  */
-export function deserializeAppliedVV(buffer, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export function deserializeAppliedVV(buffer, { codec } = {}) {
   const c = codec || defaultCodec;
   const obj = /** @type {{ [x: string]: number }} */ (c.decode(buffer));
   return vvDeserialize(obj);
@@ -198,14 +199,14 @@ export function deserializeAppliedVV(buffer, { codec } = /** @type {*} */ ({}))
 
 /**
  * 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<[string, unknown]>} propArray - Array of [key, registerObj] pairs
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>}
  */
 function deserializeProps(propArray) {
   const prop = new Map();
   if (propArray && Array.isArray(propArray)) {
     for (const [key, registerObj] of propArray) {
-      prop.set(key, deserializeLWWRegister(registerObj));
+      prop.set(key, deserializeLWWRegister(/** @type {{ eventId: { lamport: number, writerId: string, patchSha: string, opIndex: number }, value: unknown } | null} */ (registerObj)));
     }
   }
   return prop;
@@ -213,7 +214,7 @@ function deserializeProps(propArray) {
 
 /**
  * Deserializes edge birth event data, supporting both legacy and current formats.
- * @param {Record<string, *>} obj - The decoded checkpoint object
+ * @param {Record<string, unknown>} obj - The decoded checkpoint object
  * @returns {Map<string, import('../utils/EventId.js').EventId>}
  */
 function deserializeEdgeBirthEvent(obj) {
@@ -240,8 +241,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 {{ eventId: { lamport: number, opIndex: number, patchSha: string, writerId: string }, value: * } | null}
+ * @param {import('../crdt/LWW.js').LWWRegister<unknown>} register
+ * @returns {{ eventId: { lamport: number, opIndex: number, patchSha: string, writerId: string }, value: unknown } | null}
  */
 function serializeLWWRegister(register) {
   if (!register) {
@@ -262,8 +263,8 @@ function serializeLWWRegister(register) {
 /**
  * Deserializes an LWW register from CBOR.
  *
- * @param {{ eventId: { lamport: number, writerId: string, patchSha: string, opIndex: number }, value: * } | null} obj
- * @returns {import('../crdt/LWW.js').LWWRegister<*> | null}
+ * @param {{ eventId: { lamport: number, writerId: string, patchSha: string, opIndex: number }, value: unknown } | null} obj
+ * @returns {import('../crdt/LWW.js').LWWRegister<unknown> | null}
  */
 function deserializeLWWRegister(obj) {
   if (!obj) {

package/src/domain/services/CheckpointService.js

@@ -196,7 +196,7 @@ export async function createV5({
  * @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 } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function loadCheckpoint(persistence, checkpointSha, { codec } = {}) {
   // 1. Read commit message and decode
   const message = await persistence.showNode(checkpointSha);
   const decoded = /** @type {{ schema: number, stateHash: string, indexOid: string }} */ (decodeCheckpointMessage(message));
@@ -327,7 +327,7 @@ export async function materializeIncremental({
  * @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: *}>} visibleProjection.props - Visible properties
+ * @param {Array<{node: string, key: string, value: unknown}>} visibleProjection.props - Visible properties
  * @returns {import('./JoinReducer.js').WarpStateV5} Reconstructed WarpStateV5
  * @public
  */

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 } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ indexReader, logger = nullLogger }) {
     if (!indexReader) {
       throw new Error('CommitDagTraversalService requires an indexReader');
     }
@@ -56,7 +56,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Breadth-first traversal from a starting node.
-   * @param {*} options
+   * @param {Parameters<import('./DagTraversal.js').default['bfs']>[0]} options
    * @see DagTraversal#bfs
    */
   bfs(options) {
@@ -65,7 +65,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Depth-first pre-order traversal from a starting node.
-   * @param {*} options
+   * @param {Parameters<import('./DagTraversal.js').default['dfs']>[0]} options
    * @see DagTraversal#dfs
    */
   dfs(options) {
@@ -74,7 +74,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields all ancestors of a node.
-   * @param {*} options
+   * @param {Parameters<import('./DagTraversal.js').default['ancestors']>[0]} options
    * @see DagTraversal#ancestors
    */
   ancestors(options) {
@@ -83,7 +83,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields all descendants of a node.
-   * @param {*} options
+   * @param {Parameters<import('./DagTraversal.js').default['descendants']>[0]} options
    * @see DagTraversal#descendants
    */
   descendants(options) {
@@ -92,7 +92,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Checks if there is any path from one node to another.
-   * @param {*} options
+   * @param {Parameters<import('./DagTraversal.js').default['isReachable']>[0]} options
    * @see DagTraversal#isReachable
    */
   isReachable(options) {
@@ -103,7 +103,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds ANY path between two nodes using BFS.
-   * @param {*} options
+   * @param {Parameters<import('./DagPathFinding.js').default['findPath']>[0]} options
    * @see DagPathFinding#findPath
    */
   findPath(options) {
@@ -112,7 +112,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds the shortest path using bidirectional BFS.
-   * @param {*} options
+   * @param {Parameters<import('./DagPathFinding.js').default['shortestPath']>[0]} options
    * @see DagPathFinding#shortestPath
    */
   shortestPath(options) {
@@ -121,7 +121,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds shortest path using Dijkstra's algorithm.
-   * @param {*} options
+   * @param {Parameters<import('./DagPathFinding.js').default['weightedShortestPath']>[0]} options
    * @see DagPathFinding#weightedShortestPath
    */
   weightedShortestPath(options) {
@@ -130,7 +130,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds shortest path using A* with heuristic guidance.
-   * @param {*} options
+   * @param {Parameters<import('./DagPathFinding.js').default['aStarSearch']>[0]} options
    * @see DagPathFinding#aStarSearch
    */
   aStarSearch(options) {
@@ -139,7 +139,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Bi-directional A* search.
-   * @param {*} options
+   * @param {Parameters<import('./DagPathFinding.js').default['bidirectionalAStar']>[0]} options
    * @see DagPathFinding#bidirectionalAStar
    */
   bidirectionalAStar(options) {
@@ -150,7 +150,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Finds common ancestors of multiple nodes.
-   * @param {*} options
+   * @param {Parameters<import('./DagTopology.js').default['commonAncestors']>[0]} options
    * @see DagTopology#commonAncestors
    */
   commonAncestors(options) {
@@ -159,7 +159,7 @@ export default class CommitDagTraversalService {
 
   /**
    * Yields nodes in topological order using Kahn's algorithm.
-   * @param {*} options
+   * @param {Parameters<import('./DagTopology.js').default['topologicalSort']>[0]} 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(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {{ indexReader: import('./BitmapIndexReader.js').default }} */ ({})) {
     if (!indexReader) {
       throw new Error('DagPathFinding requires an indexReader');
     }
@@ -228,7 +228,7 @@ export default class DagPathFinding {
         checkAborted(signal, 'weightedShortestPath');
       }
 
-      const current = pq.extractMin();
+      const current = /** @type {string} */ (pq.extractMin());
 
       if (visited.has(current)) {
         continue;
@@ -314,7 +314,7 @@ export default class DagPathFinding {
         checkAborted(signal, 'aStarSearch');
       }
 
-      const current = pq.extractMin();
+      const current = /** @type {string} */ (pq.extractMin());
 
       if (visited.has(current)) {
         continue;
@@ -463,7 +463,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} state.fwdHeap
+   * @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
@@ -483,7 +483,7 @@ export default class DagPathFinding {
     weightProvider, forwardHeuristic, to,
     mu: inputMu, meetingPoint: inputMeeting,
   }) {
-    const current = fwdHeap.extractMin();
+    const current = /** @type {string} */ (fwdHeap.extractMin());
     let explored = 0;
     let bestMu = inputMu;
     let bestMeeting = inputMeeting;
@@ -536,7 +536,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} state.bwdHeap
+   * @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
@@ -556,7 +556,7 @@ export default class DagPathFinding {
     weightProvider, backwardHeuristic, from,
     mu: inputMu, meetingPoint: inputMeeting,
   }) {
-    const current = bwdHeap.extractMin();
+    const current = /** @type {string} */ (bwdHeap.extractMin());
     let explored = 0;
     let bestMu = inputMu;
     let bestMeeting = inputMeeting;

package/src/domain/services/DagTopology.js

@@ -37,7 +37,7 @@ export default class DagTopology {
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
    * @param {import('./DagTraversal.js').default} [options.traversal] - Traversal service for ancestor enumeration
    */
-  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default, traversal?: import('./DagTraversal.js').default }} */ { indexReader, logger = nullLogger, traversal } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  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 }} */ ({})) {
     if (!indexReader) {
       throw new Error('DagTopology requires an indexReader');
     }

package/src/domain/services/DagTraversal.js

@@ -43,7 +43,7 @@ export default class DagTraversal {
    * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
    */
-  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor(/** @type {{ indexReader: import('./BitmapIndexReader.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ { indexReader, logger = nullLogger } = /** @type {{ indexReader: import('./BitmapIndexReader.js').default }} */ ({})) {
     if (!indexReader) {
       throw new Error('DagTraversal requires an indexReader');
     }

package/src/domain/services/HealthCheckService.js

@@ -191,7 +191,7 @@ export default class HealthCheckService {
     } catch (err) {
       this._logger.warn('Repository ping failed', {
         operation: 'checkRepository',
-        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
+        error: err instanceof Error ? err.message : String(err),
       });
       return {
         status: /** @type {'healthy'|'unhealthy'} */ (HealthStatus.UNHEALTHY),

package/src/domain/services/HookInstaller.js

@@ -80,7 +80,7 @@ export class HookInstaller {
    * @param {string} deps.templateDir - Directory containing hook templates
    * @param {PathUtils} deps.path - Path utilities (join and resolve)
    */
-  constructor({ fs, execGitConfig, version, templateDir, path } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ fs, execGitConfig, version, templateDir, path }) {
     /** @type {FsAdapter} */
     this._fs = fs;
     /** @type {(repoPath: string, key: string) => string|null} */