@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/services/Frontier.js

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

package/src/domain/services/GitLogParser.js

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

package/src/domain/services/GraphTraversal.js

@@ -92,11 +92,7 @@ const lexTieBreaker = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 /**
  * Distinguishes true topological cycles from maxNodes truncation.
  *
- * @param {Object} params
- * @param {number} params.sortedLength
- * @param {number} params.discoveredSize
- * @param {number} params.maxNodes
- * @param {boolean} params.readyRemaining
+ * @param {{ sortedLength: number, discoveredSize: number, maxNodes: number, readyRemaining: boolean }} params
  * @returns {boolean}
  */
 function computeTopoHasCycle({
@@ -110,10 +106,7 @@ function computeTopoHasCycle({
 
 export default class GraphTraversal {
   /**
-   * @param {Object} params
-   * @param {NeighborProviderPort} params.provider
-   * @param {import('../../ports/LoggerPort.js').default} [params.logger]
-   * @param {number} [params.neighborCacheSize]
+   * @param {{ provider: NeighborProviderPort, logger?: import('../../ports/LoggerPort.js').default, neighborCacheSize?: number }} params
    */
   constructor({ provider, logger = nullLogger, neighborCacheSize = 256 }) {
     this._provider = provider;
@@ -187,14 +180,7 @@ export default class GraphTraversal {
    *
    * Deterministic: nodes at equal depth are visited in lexicographic nodeId order.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {number} [params.maxDepth]
-   * @param {AbortSignal} [params.signal]
-   * @param {TraversalHooks} [params.hooks]
+   * @param {{ start: string, direction?: Direction, options?: NeighborOptions, maxNodes?: number, maxDepth?: number, signal?: AbortSignal, hooks?: TraversalHooks }} params
    * @returns {Promise<{nodes: string[], stats: TraversalStats}>}
    */
   async bfs({
@@ -254,14 +240,7 @@ export default class GraphTraversal {
    *
    * Deterministic: leftmost-first via reverse-push of sorted neighbors.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {number} [params.maxDepth]
-   * @param {AbortSignal} [params.signal]
-   * @param {TraversalHooks} [params.hooks]
+   * @param {{ start: string, direction?: Direction, options?: NeighborOptions, maxNodes?: number, maxDepth?: number, signal?: AbortSignal, hooks?: TraversalHooks }} params
    * @returns {Promise<{nodes: string[], stats: TraversalStats}>}
    */
   async dfs({
@@ -311,14 +290,7 @@ export default class GraphTraversal {
   /**
    * Unweighted shortest path (BFS-based).
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {number} [params.maxDepth]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, direction?: Direction, options?: NeighborOptions, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} params
    * @returns {Promise<{found: boolean, path: string[], length: number, stats: TraversalStats}>}
    */
   async shortestPath({
@@ -374,14 +346,7 @@ export default class GraphTraversal {
   /**
    * Reachability check — BFS with early termination.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {number} [params.maxDepth]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, direction?: Direction, options?: NeighborOptions, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} params
    * @returns {Promise<{reachable: boolean, stats: TraversalStats}>}
    */
   async isReachable({
@@ -432,15 +397,7 @@ export default class GraphTraversal {
    * Tie-breaking: equal-priority by lexicographic nodeId. Equal-cost
    * predecessor update: when altCost === bestCost && candidatePredecessor < currentPredecessor.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [params.weightFn]
-   * @param {(nodeId: string) => number | Promise<number>} [params.nodeWeightFn]
-   * @param {number} [params.maxNodes]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, direction?: Direction, options?: NeighborOptions, weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, maxNodes?: number, signal?: AbortSignal }} params
    * @returns {Promise<{path: string[], totalCost: number, stats: TraversalStats}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -501,16 +458,7 @@ export default class GraphTraversal {
   /**
    * A* search with heuristic guidance.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [params.weightFn]
-   * @param {(nodeId: string) => number | Promise<number>} [params.nodeWeightFn]
-   * @param {(nodeId: string, goalId: string) => number} [params.heuristicFn]
-   * @param {number} [params.maxNodes]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, direction?: Direction, options?: NeighborOptions, weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, heuristicFn?: (nodeId: string, goalId: string) => number, maxNodes?: number, signal?: AbortSignal }} params
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number, stats: TraversalStats}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -583,16 +531,7 @@ export default class GraphTraversal {
    * bidirectional algorithm — forward always means outgoing, backward always
    * means incoming.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {NeighborOptions} [params.options]
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [params.weightFn]
-   * @param {(nodeId: string) => number | Promise<number>} [params.nodeWeightFn]
-   * @param {(nodeId: string, goalId: string) => number} [params.forwardHeuristic]
-   * @param {(nodeId: string, goalId: string) => number} [params.backwardHeuristic]
-   * @param {number} [params.maxNodes]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, options?: NeighborOptions, weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, forwardHeuristic?: (nodeId: string, goalId: string) => number, backwardHeuristic?: (nodeId: string, goalId: string) => number, maxNodes?: number, signal?: AbortSignal }} params
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number, stats: TraversalStats}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -674,21 +613,7 @@ export default class GraphTraversal {
   /**
    * Expand one node in bidirectional A*.
    * @private
-   * @param {Object} p
-   * @param {MinHeap<string>} p.heap
-   * @param {Set<string>} p.visited
-   * @param {Map<string, number>} p.gScore
-   * @param {Map<string, string>} p.predMap
-   * @param {Set<string>} p.otherVisited
-   * @param {Map<string, number>} p.otherG
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} p.weightFn
-   * @param {(nodeId: string, goalId: string) => number} p.heuristicFn
-   * @param {string} p.target
-   * @param {Direction} p.directionForNeighbors
-   * @param {NeighborOptions} [p.options]
-   * @param {number} p.mu
-   * @param {string|null} p.meeting
-   * @param {RunStats} p.rs
+   * @param {{ heap: MinHeap<string>, visited: Set<string>, gScore: Map<string, number>, predMap: Map<string, string>, otherVisited: Set<string>, otherG: Map<string, number>, weightFn: (from: string, to: string, label: string) => number | Promise<number>, heuristicFn: (nodeId: string, goalId: string) => number, target: string, directionForNeighbors: Direction, options?: NeighborOptions, mu: number, meeting: string|null, rs: RunStats }} p
    * @returns {Promise<{explored: number, mu: number, meeting: string|null}>}
    */
   async _biAStarExpand({
@@ -749,12 +674,7 @@ export default class GraphTraversal {
   /**
    * Connected component — delegates to BFS with direction 'both'.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {number} [params.maxDepth]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, options?: NeighborOptions, maxNodes?: number, maxDepth?: number, signal?: AbortSignal }} params
    * @returns {Promise<{nodes: string[], stats: TraversalStats}>}
    */
   async connectedComponent({ start, options, maxNodes, maxDepth, signal }) {
@@ -766,14 +686,7 @@ export default class GraphTraversal {
    *
    * Deterministic: zero-indegree nodes dequeued in lexicographic nodeId order.
    *
-   * @param {Object} params
-   * @param {string | string[]} params.start - One or more start nodes
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxNodes]
-   * @param {boolean} [params.throwOnCycle]
-   * @param {AbortSignal} [params.signal]
-   * @param {boolean} [params._returnAdjList] - Private: return neighbor edge map alongside sorted (for internal reuse)
+   * @param {{ start: string | string[], direction?: Direction, options?: NeighborOptions, maxNodes?: number, throwOnCycle?: boolean, signal?: AbortSignal, _returnAdjList?: boolean }} params
    * @returns {Promise<{sorted: string[], hasCycle: boolean, stats: TraversalStats, _neighborEdgeMap?: Map<string, NeighborEdge[]>}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if throwOnCycle is true and cycle found
    */
@@ -914,12 +827,7 @@ export default class GraphTraversal {
    * `[A, B, C]`, then B and C may appear in the result because A's BFS
    * reaches them and their own BFS includes themselves at depth 0.
    *
-   * @param {Object} params
-   * @param {string[]} params.nodes - Nodes to find common ancestors of
-   * @param {NeighborOptions} [params.options]
-   * @param {number} [params.maxDepth]
-   * @param {number} [params.maxResults]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ nodes: string[], options?: NeighborOptions, maxDepth?: number, maxResults?: number, signal?: AbortSignal }} params
    * @returns {Promise<{ancestors: string[], stats: TraversalStats}>}
    */
   async commonAncestors({
@@ -981,15 +889,7 @@ export default class GraphTraversal {
    *
    * Only valid on DAGs. Throws ERR_GRAPH_HAS_CYCLES if graph has cycles.
    *
-   * @param {Object} params
-   * @param {string} params.start
-   * @param {string} params.goal
-   * @param {Direction} [params.direction]
-   * @param {NeighborOptions} [params.options]
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [params.weightFn]
-   * @param {(nodeId: string) => number | Promise<number>} [params.nodeWeightFn]
-   * @param {number} [params.maxNodes]
-   * @param {AbortSignal} [params.signal]
+   * @param {{ start: string, goal: string, direction?: Direction, options?: NeighborOptions, weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, maxNodes?: number, signal?: AbortSignal }} params
    * @returns {Promise<{path: string[], totalCost: number, stats: TraversalStats}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if graph has cycles
    * @throws {TraversalError} code 'NO_PATH' if unreachable

package/src/domain/services/HealthCheckService.js

@@ -45,11 +45,7 @@ export const HealthStatus = {
 export default class HealthCheckService {
   /**
    * Creates a HealthCheckService instance.
-   * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Persistence port for repository checks
-   * @param {import('../../ports/ClockPort.js').default} options.clock - Clock port for timing operations
-   * @param {number} [options.cacheTtlMs=5000] - How long to cache health results in milliseconds
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging
+   * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default, clock: import('../../ports/ClockPort.js').default, cacheTtlMs?: number, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ persistence, clock, cacheTtlMs = DEFAULT_CACHE_TTL_MS, logger = nullLogger }) {
     this._persistence = persistence;
@@ -116,9 +112,7 @@ export default class HealthCheckService {
    *
    * @typedef {Object} HealthResult
    * @property {'healthy'|'degraded'|'unhealthy'} status - Overall health status
-   * @property {Object} components - Component health breakdown
-   * @property {RepositoryHealth} components.repository - Repository health
-   * @property {IndexHealth} components.index - Index health
+   * @property {{ repository: RepositoryHealth, index: IndexHealth }} components - Component health breakdown
    * @property {string} [cachedAt] - ISO timestamp if result is cached
    *
    * @typedef {Object} RepositoryHealth
@@ -154,7 +148,7 @@ export default class HealthCheckService {
   /**
    * Computes health by checking all components.
    * This is called by CachedValue when the cache is stale.
-   * @returns {Promise<Object>}
+   * @returns {Promise<{status: 'healthy'|'degraded'|'unhealthy', components: {repository: RepositoryHealth, index: IndexHealth}}>}
    * @private
    */
   async _computeHealth() {

package/src/domain/services/HookInstaller.js

@@ -73,12 +73,7 @@ export class HookInstaller {
   /**
    * Creates a new HookInstaller.
    *
-   * @param {Object} deps - Injected dependencies
-   * @param {FsAdapter} deps.fs - Filesystem adapter with methods: readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync
-   * @param {(repoPath: string, key: string) => string|null} deps.execGitConfig - Function to read git config values
-   * @param {string} deps.version - Package version
-   * @param {string} deps.templateDir - Directory containing hook templates
-   * @param {PathUtils} deps.path - Path utilities (join and resolve)
+   * @param {{ fs: FsAdapter, execGitConfig: (repoPath: string, key: string) => string|null, version: string, templateDir: string, path: PathUtils }} deps - Injected dependencies
    */
   constructor({ fs, execGitConfig, version, templateDir, path }) {
     /** @type {FsAdapter} */
@@ -125,8 +120,7 @@ export class HookInstaller {
    * Installs the post-merge hook.
    *
    * @param {string} repoPath - Path to git repo
-   * @param {Object} opts - Install options
-   * @param {'install'|'upgrade'|'append'|'replace'} opts.strategy - Installation strategy
+   * @param {{ strategy: 'install'|'upgrade'|'append'|'replace' }} opts - Install options
    * @returns {{ action: string, hookPath: string, version: string, backupPath?: string }}
    * @throws {Error} If the strategy is unknown
    */

package/src/domain/services/HttpSyncServer.js

@@ -92,7 +92,7 @@ function canonicalStringify(value) {
  *
  * @param {number} status - HTTP status code
  * @param {string} message - Error message
- * @returns {{ status: number, headers: Object, body: string }}
+ * @returns {{ status: number, headers: Record<string, string>, body: string }}
  * @private
  */
 function errorResponse(status, message) {
@@ -107,7 +107,7 @@ function errorResponse(status, message) {
  * Builds a JSON success response with canonical key ordering.
  *
  * @param {unknown} data - Response payload
- * @returns {{ status: number, headers: Object, body: string }}
+ * @returns {{ status: number, headers: Record<string, string>, body: string }}
  * @private
  */
 function jsonResponse(data) {
@@ -125,7 +125,7 @@ function jsonResponse(data) {
  * content type is present but not application/json, otherwise null.
  *
  * @param {{ [x: string]: string }} headers - Request headers
- * @returns {{ status: number, headers: Object, body: string }|null}
+ * @returns {{ status: number, headers: Record<string, string>, body: string }|null}
  * @private
  */
 function checkContentType(headers) {
@@ -143,7 +143,7 @@ function checkContentType(headers) {
  * @param {{ method: string, url: string, headers: { [x: string]: string } }} request
  * @param {string} expectedPath
  * @param {string} defaultHost
- * @returns {{ status: number, headers: Object, body: string }|null}
+ * @returns {{ status: number, headers: Record<string, string>, body: string }|null}
  * @private
  */
 function validateRoute(request, expectedPath, defaultHost) {
@@ -168,9 +168,9 @@ function validateRoute(request, expectedPath, defaultHost) {
 /**
  * Checks if the request body exceeds the maximum allowed size.
  *
- * @param {Buffer|undefined} body
+ * @param {Buffer | Uint8Array | undefined} body
  * @param {number} maxBytes
- * @returns {{ status: number, headers: Object, body: string }|null} Error response or null if within limits
+ * @returns {{ status: number, headers: Record<string, string>, body: string }|null} Error response or null if within limits
  * @private
  */
 function checkBodySize(body, maxBytes) {
@@ -184,12 +184,12 @@ function checkBodySize(body, maxBytes) {
  * Parses and validates the request body as a sync request.
  * Uses Zod-based SyncPayloadSchema for shape + resource limit validation.
  *
- * @param {Buffer|undefined} body
- * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
+ * @param {Buffer | Uint8Array | undefined} body
+ * @returns {{ error: { status: number, headers: Record<string, string>, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
  * @private
  */
 function parseBody(body) {
-  const bodyStr = body ? body.toString('utf-8') : '';
+  const bodyStr = body ? new TextDecoder().decode(body) : '';
 
   let parsed;
   try {
@@ -223,14 +223,7 @@ function initAuth(auth, allowedWriters) {
 
 export default class HttpSyncServer {
   /**
-   * @param {Object} options
-   * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server port abstraction
-   * @param {{ processSyncRequest: Function }} options.graph - WarpGraph instance (must expose processSyncRequest)
-   * @param {string} [options.path='/sync'] - URL path to handle sync requests on
-   * @param {string} [options.host='127.0.0.1'] - Host to bind
-   * @param {number} [options.maxRequestBytes=4194304] - Maximum request body size in bytes
-   * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number }} [options.auth] - Auth configuration
-   * @param {string[]} [options.allowedWriters] - Optional whitelist of allowed writer IDs
+   * @param {{ httpPort: import('../../ports/HttpServerPort.js').default, graph: { processSyncRequest: (req: import('./SyncProtocol.js').SyncRequest) => Promise<unknown> }, path?: string, host?: string, maxRequestBytes?: number, auth?: { keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number }, allowedWriters?: string[] }} options
    */
   constructor(options) {
     /** @type {z.infer<typeof optionsSchema>} */
@@ -263,9 +256,9 @@ export default class HttpSyncServer {
    * In log-only mode both checks record metrics/logs but always return
    * null so the request proceeds.
    *
-   * @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request
+   * @param {{ method: string, url: string, headers: Record<string, string>, body: Buffer | Uint8Array | undefined }} request
    * @param {Record<string, unknown>} parsed - Parsed sync request body
-   * @returns {Promise<{ status: number, headers: Object, body: string }|null>}
+   * @returns {Promise<{ status: number, headers: Record<string, string>, body: string }|null>}
    * @private
    */
   async _authorize(request, parsed) {
@@ -299,9 +292,15 @@ export default class HttpSyncServer {
     return null;
   }
 
-  /** @param {{ method: string, url: string, headers: Object, body: Buffer|undefined }} request */
+  /**
+   * Handles an incoming HTTP request through the sync pipeline.
+   *
+   * @param {import('../../ports/HttpServerPort.js').HttpRequest} request
+   * @returns {Promise<import('../../ports/HttpServerPort.js').HttpResponse>}
+   * @private
+   */
   async _handleRequest(request) {
-    /** @type {{ method: string, url: string, headers: Record<string, string>, body: Buffer|undefined }} */
+    /** @type {{ method: string, url: string, headers: Record<string, string>, body: Buffer | Uint8Array | undefined }} */
     const req = { ...request, headers: /** @type {Record<string, string>} */ (request.headers) };
     const contentTypeError = checkContentType(req.headers);
     if (contentTypeError) {
@@ -348,14 +347,14 @@ export default class HttpSyncServer {
       throw new Error('listen() requires a numeric port');
     }
 
-    /** @type {{ listen: Function, close: Function, address: Function }} */
     const server = this._httpPort.createServer(
-      (/** @type {{ method: string, url: string, headers: Object, body: Buffer|undefined }} */ request) => this._handleRequest(request),
+      (/** @type {import('../../ports/HttpServerPort.js').HttpRequest} */ request) =>
+        this._handleRequest(request),
     );
     this._server = server;
 
     await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-      server.listen(port, this._host, (/** @type {Error|null} */ err) => {
+      server.listen(port, this._host, (err) => {
         if (err) {
           reject(err);
         } else {
@@ -372,7 +371,7 @@ export default class HttpSyncServer {
       url,
       close: () =>
         /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-          server.close((/** @type {Error|null} */ err) => {
+          server.close((err) => {
             if (err) {
               reject(err);
             } else {

package/src/domain/services/IncrementalIndexUpdater.js

@@ -42,8 +42,9 @@ const MAX_LOCAL_ID = 1 << 24;
 
 export default class IncrementalIndexUpdater {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * Create an incremental index updater.
+   *
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;
@@ -61,10 +62,7 @@ export default class IncrementalIndexUpdater {
   /**
    * Computes only the dirty shards from a PatchDiff.
    *
-   * @param {Object} params
-   * @param {import('../types/PatchDiff.js').PatchDiff} params.diff
-   * @param {import('./JoinReducer.js').WarpStateV5} params.state
-   * @param {(path: string) => Uint8Array|undefined} params.loadShard
+   * @param {{ diff: import('../types/PatchDiff.js').PatchDiff, state: import('./JoinReducer.js').WarpStateV5, loadShard: (path: string) => Uint8Array|undefined }} params
    * @returns {Record<string, Uint8Array>} dirty shard buffers (path -> Uint8Array)
    */
   computeDirtyShards({ diff, state, loadShard }) {

package/src/domain/services/IndexRebuildService.js

@@ -39,14 +39,7 @@ export default class IndexRebuildService {
   /**
    * Creates an IndexRebuildService instance.
    *
-   * @param {Object} options - Configuration options
-   * @param {{ iterateNodes: (opts: { ref: string, limit: number }) => AsyncIterable<{ sha: string, parents: string[] }> }} options.graphService - Graph service providing node iteration.
-   * @param {import('../../ports/IndexStoragePort.js').default} options.storage - Storage adapter
-   *   for persisting index blobs and trees. Typically GitGraphAdapter.
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for
-   *   structured logging. Defaults to null logger (no logging).
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - Crypto adapter for checksums
+   * @param {{ graphService: { iterateNodes: (opts: { ref: string, limit: number }) => AsyncIterable<{ sha: string, parents: string[] }> }, storage: import('../../ports/IndexStoragePort.js').default, logger?: import('../../ports/LoggerPort.js').default, codec?: import('../../ports/CodecPort.js').default, crypto?: import('../../ports/CryptoPort.js').default }} options - Configuration options
    * @throws {Error} If graphService is not provided
    * @throws {Error} If storage adapter is not provided
    */
@@ -87,19 +80,7 @@ export default class IndexRebuildService {
    * - `shards_rev_XX.json`: Reverse edge bitmaps (parent lookups)
    *
    * @param {string} ref - Git ref to start traversal from (e.g., 'HEAD', branch name, SHA)
-   * @param {Object} [options] - Rebuild options
-   * @param {number} [options.limit=10000000] - Maximum nodes to process (1 to 10,000,000)
-   * @param {number} [options.maxMemoryBytes] - Enable streaming mode with this memory threshold.
-   *   When bitmap memory exceeds this value, data is flushed to storage.
-   *   Recommended: 50-100MB for most systems. Minimum: 1MB.
-   * @param {Function} [options.onFlush] - Callback invoked on each flush (streaming mode only).
-   *   Receives { flushedBytes, totalFlushedBytes, flushCount }.
-   * @param {Function} [options.onProgress] - Callback invoked periodically during processing.
-   *   Receives { processedNodes, currentMemoryBytes }.
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation support.
-   *   When aborted, throws OperationAbortedError at the next loop boundary.
-   * @param {Map<string, string>} [options.frontier] - Frontier to persist alongside the rebuilt index.
-   *   Maps writer IDs to their tip SHAs; stored in the index tree for staleness detection.
+   * @param {{ limit?: number, maxMemoryBytes?: number, onFlush?: (stats: {flushedBytes: number, totalFlushedBytes: number, flushCount: number}) => void, onProgress?: (stats: {processedNodes: number, currentMemoryBytes: number | null}) => void, signal?: AbortSignal, frontier?: Map<string, string> }} [options] - Rebuild options
    * @returns {Promise<string>} OID of the created tree containing the index
    * @throws {Error} If maxMemoryBytes is specified but not positive
    * @throws {OperationAbortedError} If the signal is aborted during rebuild
@@ -174,13 +155,7 @@ export default class IndexRebuildService {
    * data structures, plus temporary overhead during serialization.
    *
    * @param {string} ref - Git ref to traverse from
-   * @param {Object} options - Options
-   * @param {number} options.limit - Maximum nodes to process
-   * @param {Function} [options.onProgress] - Progress callback invoked every 10,000 nodes.
-   *   Receives `{ processedNodes: number, currentMemoryBytes: null }`.
-   * @param {AbortSignal} [options.signal] - Abort signal for cancellation. Checked every
-   *   10,000 nodes to balance responsiveness with performance.
-   * @param {Map<string, string>} [options.frontier] - Frontier to persist with the index
+   * @param {{ limit: number, onProgress?: (stats: {processedNodes: number, currentMemoryBytes: number | null}) => void, signal?: AbortSignal, frontier?: Map<string, string> }} options - Options
    * @returns {Promise<string>} Tree OID of the persisted index
    * @throws {OperationAbortedError} If the signal is aborted during iteration
    * @throws {Error} If node iteration fails (e.g., invalid ref, Git error)
@@ -229,17 +204,7 @@ export default class IndexRebuildService {
    * - You can tolerate longer rebuild times for lower memory usage
    *
    * @param {string} ref - Git ref to traverse from
-   * @param {Object} options - Options
-   * @param {number} options.limit - Maximum nodes to process
-   * @param {number} options.maxMemoryBytes - Memory threshold in bytes. When estimated
-   *   bitmap memory exceeds this, a flush is triggered.
-   * @param {Function} [options.onFlush] - Flush callback invoked after each flush.
-   *   Receives `{ flushedBytes, totalFlushedBytes, flushCount }`.
-   * @param {Function} [options.onProgress] - Progress callback invoked every 10,000 nodes.
-   *   Receives `{ processedNodes, currentMemoryBytes }`.
-   * @param {AbortSignal} [options.signal] - Abort signal for cancellation. Checked every
-   *   10,000 nodes during iteration and at finalization.
-   * @param {Map<string, string>} [options.frontier] - Frontier to persist with the index
+   * @param {{ limit: number, maxMemoryBytes: number, onFlush?: (stats: {flushedBytes: number, totalFlushedBytes: number, flushCount: number}) => void, onProgress?: (stats: {processedNodes: number, currentMemoryBytes: number}) => void, signal?: AbortSignal, frontier?: Map<string, string> }} options - Options
    * @returns {Promise<string>} Tree OID of the persisted index
    * @throws {OperationAbortedError} If the signal is aborted during iteration or finalization
    * @throws {Error} If node iteration fails (e.g., invalid ref, Git error)
@@ -291,8 +256,7 @@ export default class IndexRebuildService {
    * - `100644 blob <oid>\tfrontier.json` (if frontier provided)
    *
    * @param {BitmapIndexBuilder} builder - The builder containing index data
-   * @param {Object} [options] - Persistence options
-   * @param {Map<string, string>} [options.frontier] - Frontier to include in the tree
+   * @param {{ frontier?: Map<string, string> }} [options] - Persistence options
    * @returns {Promise<string>} OID of the created tree
    * @throws {Error} If storage.writeBlob() fails for any shard
    * @throws {Error} If storage.writeTree() fails
@@ -329,17 +293,7 @@ export default class IndexRebuildService {
    * incomplete or incorrect query results.
    *
    * @param {string} treeOid - OID of the index tree (from rebuild() or a saved ref)
-   * @param {Object} [options] - Load options
-   * @param {boolean} [options.strict=true] - Enable strict integrity verification (fail-closed).
-   *   When true, throws on any shard validation or corruption errors.
-   *   When false, attempts graceful degradation.
-   * @param {Map<string, string>} [options.currentFrontier] - Frontier to compare for staleness.
-   *   Maps writer IDs to their current tip SHAs. When provided, triggers a staleness
-   *   check against the frontier stored in the index.
-   * @param {boolean} [options.autoRebuild=false] - Auto-rebuild when a stale index is detected.
-   *   Requires `rebuildRef` to be set.
-   * @param {string} [options.rebuildRef] - Git ref to rebuild from when `autoRebuild` is true.
-   *   Required if `autoRebuild` is true.
+   * @param {{ strict?: boolean, currentFrontier?: Map<string, string>, autoRebuild?: boolean, rebuildRef?: string }} [options] - Load options
    * @returns {Promise<BitmapIndexReader>} Configured reader ready for O(1) queries.
    *   The reader lazily loads shards on demand; initial load is O(1).
    * @throws {Error} If treeOid is invalid or tree cannot be read from storage

package/src/domain/services/IndexStalenessChecker.js

@@ -22,8 +22,7 @@ function validateEnvelope(envelope, label) {
  *
  * @param {Record<string, string>} shardOids - Map of path → blob OID from readTreeOids
  * @param {import('../../ports/IndexStoragePort.js').default & import('../../ports/BlobPort.js').default} storage - Storage adapter
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Promise<Map<string, string>|null>} Frontier map, or null if not present (legacy index)
  */
 export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
@@ -39,7 +38,7 @@ export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
   const jsonOid = shardOids['frontier.json'];
   if (jsonOid) {
     const buffer = await storage.readBlob(jsonOid);
-    const envelope = /** @type {{ frontier: Record<string, string> }} */ (JSON.parse(buffer.toString('utf-8')));
+    const envelope = /** @type {{ frontier: Record<string, string> }} */ (JSON.parse(new TextDecoder().decode(buffer)));
     validateEnvelope(envelope, 'frontier.json');
     return new Map(Object.entries(envelope.frontier));
   }