@git-stunts/git-warp 10.1.2 → 10.4.2

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({ indexReader, logger = nullLogger, traversal } = {}) {
+  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
     if (!indexReader) {
       throw new Error('DagTopology requires an indexReader');
     }
@@ -76,9 +76,10 @@ export default class DagTopology {
    */
   async commonAncestors({ shas, maxResults = 100, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
     if (shas.length === 0) { return []; }
+    const traversal = /** @type {import('./DagTraversal.js').default} */ (this._traversal);
     if (shas.length === 1) {
       const ancestors = [];
-      for await (const node of this._traversal.ancestors({ sha: shas[0], maxNodes: maxResults, maxDepth, signal })) {
+      for await (const node of traversal.ancestors({ sha: shas[0], maxNodes: maxResults, maxDepth, signal })) {
         ancestors.push(node.sha);
       }
       return ancestors;
@@ -92,7 +93,7 @@ export default class DagTopology {
     for (const sha of shas) {
       checkAborted(signal, 'commonAncestors');
       const visited = new Set();
-      for await (const node of this._traversal.ancestors({ sha, maxDepth, signal })) {
+      for await (const node of traversal.ancestors({ sha, maxDepth, signal })) {
         if (!visited.has(node.sha)) {
           visited.add(node.sha);
           ancestorCounts.set(node.sha, (ancestorCounts.get(node.sha) || 0) + 1);
@@ -149,7 +150,7 @@ export default class DagTopology {
         checkAborted(signal, 'topologicalSort');
       }
 
-      const sha = queue.shift();
+      const sha = /** @type {string} */ (queue.shift());
       const neighbors = await this._getNeighbors(sha, direction);
       edges.set(sha, neighbors);
 
@@ -182,7 +183,7 @@ export default class DagTopology {
         checkAborted(signal, 'topologicalSort');
       }
 
-      const sha = ready.shift();
+      const sha = /** @type {string} */ (ready.shift());
       const depth = depthMap.get(sha) || 0;
 
       nodesYielded++;
@@ -190,7 +191,7 @@ export default class DagTopology {
 
       const neighbors = edges.get(sha) || [];
       for (const neighbor of neighbors) {
-        const newDegree = inDegree.get(neighbor) - 1;
+        const newDegree = /** @type {number} */ (inDegree.get(neighbor)) - 1;
         inDegree.set(neighbor, newDegree);
 
         if (!depthMap.has(neighbor)) {

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({ 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('DagTraversal requires an indexReader');
     }
@@ -89,6 +89,7 @@ export default class DagTraversal {
     signal,
   }) {
     const visited = new Set();
+    /** @type {TraversalNode[]} */
     const queue = [{ sha: start, depth: 0, parent: null }];
     let nodesYielded = 0;
 
@@ -99,7 +100,7 @@ export default class DagTraversal {
         checkAborted(signal, 'bfs');
       }
 
-      const current = queue.shift();
+      const current = /** @type {TraversalNode} */ (queue.shift());
 
       if (visited.has(current.sha)) { continue; }
       if (current.depth > maxDepth) { continue; }
@@ -142,6 +143,7 @@ export default class DagTraversal {
     signal,
   }) {
     const visited = new Set();
+    /** @type {TraversalNode[]} */
     const stack = [{ sha: start, depth: 0, parent: null }];
     let nodesYielded = 0;
 
@@ -152,7 +154,7 @@ export default class DagTraversal {
         checkAborted(signal, 'dfs');
       }
 
-      const current = stack.pop();
+      const current = /** @type {TraversalNode} */ (stack.pop());
 
       if (visited.has(current.sha)) { continue; }
       if (current.depth > maxDepth) { continue; }

package/src/domain/services/Frontier.js

@@ -50,12 +50,13 @@ export function getWriters(frontier) {
  * Keys are sorted for determinism.
  * @param {Frontier} frontier
  * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} options.codec - Codec for serialization
- * @returns {Buffer}
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @returns {Buffer|Uint8Array}
  */
-export function serializeFrontier(frontier, { codec } = {}) {
+export function serializeFrontier(frontier, { codec } = /** @type {{codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
   const c = codec || defaultCodec;
   // Convert Map to sorted object for deterministic encoding
+  /** @type {Record<string, string|undefined>} */
   const obj = {};
   const sortedKeys = Array.from(frontier.keys()).sort();
   for (const key of sortedKeys) {
@@ -68,12 +69,12 @@ export function serializeFrontier(frontier, { codec } = {}) {
  * Deserializes frontier from CBOR bytes.
  * @param {Buffer} buffer
  * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} options.codec - Codec for deserialization
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Frontier}
  */
-export function deserializeFrontier(buffer, { codec } = {}) {
+export function deserializeFrontier(buffer, { codec } = /** @type {{codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
   const c = codec || defaultCodec;
-  const obj = c.decode(buffer);
+  const obj = /** @type {Record<string, string>} */ (c.decode(buffer));
   const frontier = new Map();
   for (const [writerId, patchSha] of Object.entries(obj)) {
     frontier.set(writerId, patchSha);

package/src/domain/services/HealthCheckService.js

@@ -46,7 +46,7 @@ export default class HealthCheckService {
   /**
    * Creates a HealthCheckService instance.
    * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Persistence port for repository checks
+   * @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
@@ -132,22 +132,23 @@ export default class HealthCheckService {
    */
   async getHealth() {
     const { value, cachedAt, fromCache } = await this._healthCache.getWithMetadata();
+    const result = /** @type {HealthResult} */ (value);
 
     if (cachedAt) {
-      return { ...value, cachedAt };
+      return { ...result, cachedAt };
     }
 
     // Log only for fresh computations
     if (!fromCache) {
       this._logger.debug('Health check completed', {
         operation: 'getHealth',
-        status: value.status,
-        repositoryStatus: value.components.repository.status,
-        indexStatus: value.components.index.status,
+        status: result.status,
+        repositoryStatus: result.components.repository.status,
+        indexStatus: result.components.index.status,
       });
     }
 
-    return value;
+    return result;
   }
 
   /**
@@ -184,16 +185,16 @@ export default class HealthCheckService {
     try {
       const pingResult = await this._persistence.ping();
       return {
-        status: pingResult.ok ? HealthStatus.HEALTHY : HealthStatus.UNHEALTHY,
+        status: /** @type {'healthy'|'unhealthy'} */ (pingResult.ok ? HealthStatus.HEALTHY : HealthStatus.UNHEALTHY),
         latencyMs: Math.round(pingResult.latencyMs * 100) / 100, // Round to 2 decimal places
       };
     } catch (err) {
       this._logger.warn('Repository ping failed', {
         operation: 'checkRepository',
-        error: err.message,
+        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
       });
       return {
-        status: HealthStatus.UNHEALTHY,
+        status: /** @type {'healthy'|'unhealthy'} */ (HealthStatus.UNHEALTHY),
         latencyMs: 0,
       };
     }
@@ -207,7 +208,7 @@ export default class HealthCheckService {
   _checkIndex() {
     if (!this._indexReader) {
       return {
-        status: HealthStatus.DEGRADED,
+        status: /** @type {'healthy'|'degraded'|'unhealthy'} */ (HealthStatus.DEGRADED),
         loaded: false,
       };
     }
@@ -216,7 +217,7 @@ export default class HealthCheckService {
     const shardCount = this._indexReader.shardOids?.size ?? 0;
 
     return {
-      status: HealthStatus.HEALTHY,
+      status: /** @type {'healthy'|'degraded'|'unhealthy'} */ (HealthStatus.HEALTHY),
       loaded: true,
       shardCount,
     };
@@ -232,15 +233,15 @@ export default class HealthCheckService {
   _computeOverallStatus(repositoryHealth, indexHealth) {
     // If repository is unhealthy, overall is unhealthy
     if (repositoryHealth.status === HealthStatus.UNHEALTHY) {
-      return HealthStatus.UNHEALTHY;
+      return /** @type {'healthy'|'degraded'|'unhealthy'} */ (HealthStatus.UNHEALTHY);
     }
 
     // If index is degraded (not loaded), overall is degraded
     if (indexHealth.status === HealthStatus.DEGRADED) {
-      return HealthStatus.DEGRADED;
+      return /** @type {'healthy'|'degraded'|'unhealthy'} */ (HealthStatus.DEGRADED);
     }
 
     // All components healthy
-    return HealthStatus.HEALTHY;
+    return /** @type {'healthy'|'degraded'|'unhealthy'} */ (HealthStatus.HEALTHY);
   }
 }

package/src/domain/services/HookInstaller.js

@@ -7,6 +7,21 @@
  * @module domain/services/HookInstaller
  */
 
+/**
+ * @typedef {Object} FsAdapter
+ * @property {(path: string, content: string | Buffer, options?: Object) => void} writeFileSync
+ * @property {(path: string, mode: number) => void} chmodSync
+ * @property {(path: string, encoding?: string) => string} readFileSync
+ * @property {(path: string) => boolean} existsSync
+ * @property {(path: string, options?: Object) => void} mkdirSync
+ */
+
+/**
+ * @typedef {Object} PathUtils
+ * @property {(...segments: string[]) => string} join
+ * @property {(...segments: string[]) => string} resolve
+ */
+
 const DELIMITER_START_PREFIX = '# --- @git-stunts/git-warp post-merge hook';
 const DELIMITER_END = '# --- end @git-stunts/git-warp ---';
 const VERSION_MARKER_PREFIX = '# warp-hook-version:';
@@ -59,17 +74,22 @@ export class HookInstaller {
    * Creates a new HookInstaller.
    *
    * @param {Object} deps - Injected dependencies
-   * @param {Object} deps.fs - Filesystem adapter with methods: readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, copyFileSync
+   * @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 {{ join: (...segments: string[]) => string, resolve: (...segments: string[]) => string }} deps.path - Path utilities (join and resolve)
+   * @param {PathUtils} deps.path - Path utilities (join and resolve)
    */
-  constructor({ fs, execGitConfig, version, templateDir, path } = {}) {
+  constructor({ fs, execGitConfig, version, templateDir, path } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+    /** @type {FsAdapter} */
     this._fs = fs;
+    /** @type {(repoPath: string, key: string) => string|null} */
     this._execGitConfig = execGitConfig;
+    /** @type {string} */
     this._templateDir = templateDir;
+    /** @type {string} */
     this._version = version;
+    /** @type {PathUtils} */
     this._path = path;
   }
 
@@ -134,7 +154,11 @@ export class HookInstaller {
     throw new Error(`Unknown install strategy: ${strategy}`);
   }
 
-  /** @private */
+  /**
+   * @param {string} hookPath
+   * @param {string} content
+   * @private
+   */
   _freshInstall(hookPath, content) {
     this._fs.writeFileSync(hookPath, content, { mode: 0o755 });
     this._fs.chmodSync(hookPath, 0o755);
@@ -145,13 +169,17 @@ export class HookInstaller {
     };
   }
 
-  /** @private */
+  /**
+   * @param {string} hookPath
+   * @param {string} stamped
+   * @private
+   */
   _upgradeInstall(hookPath, stamped) {
     const existing = this._readFile(hookPath);
     const classification = classifyExistingHook(existing);
 
     if (classification.appended) {
-      const updated = replaceDelimitedSection(existing, stamped);
+      const updated = replaceDelimitedSection(/** @type {string} */ (existing), stamped);
       // If delimiters were corrupted, replaceDelimitedSection returns unchanged content — fall back to overwrite
       if (updated === existing) {
         this._fs.writeFileSync(hookPath, stamped, { mode: 0o755 });
@@ -170,7 +198,11 @@ export class HookInstaller {
     };
   }
 
-  /** @private */
+  /**
+   * @param {string} hookPath
+   * @param {string} stamped
+   * @private
+   */
   _appendInstall(hookPath, stamped) {
     const existing = this._readFile(hookPath) || '';
     const body = stripShebang(stamped);
@@ -184,7 +216,11 @@ export class HookInstaller {
     };
   }
 
-  /** @private */
+  /**
+   * @param {string} hookPath
+   * @param {string} stamped
+   * @private
+   */
   _replaceInstall(hookPath, stamped) {
     const existing = this._readFile(hookPath);
     let backupPath;
@@ -210,12 +246,18 @@ export class HookInstaller {
     return this._fs.readFileSync(templatePath, 'utf8');
   }
 
-  /** @private */
+  /**
+   * @param {string} template
+   * @private
+   */
   _stampVersion(template) {
     return template.replaceAll(VERSION_PLACEHOLDER, this._version);
   }
 
-  /** @private */
+  /**
+   * @param {string} repoPath
+   * @private
+   */
   _resolveHooksDir(repoPath) {
     const customPath = this._execGitConfig(repoPath, 'core.hooksPath');
     if (customPath) {
@@ -230,12 +272,18 @@ export class HookInstaller {
     return this._path.join(repoPath, '.git', 'hooks');
   }
 
-  /** @private */
+  /**
+   * @param {string} repoPath
+   * @private
+   */
   _resolveHookPath(repoPath) {
     return this._path.join(this._resolveHooksDir(repoPath), 'post-merge');
   }
 
-  /** @private */
+  /**
+   * @param {string} filePath
+   * @private
+   */
   _readFile(filePath) {
     try {
       return this._fs.readFileSync(filePath, 'utf8');
@@ -244,7 +292,10 @@ export class HookInstaller {
     }
   }
 
-  /** @private */
+  /**
+   * @param {string} dirPath
+   * @private
+   */
   _ensureDir(dirPath) {
     if (!this._fs.existsSync(dirPath)) {
       this._fs.mkdirSync(dirPath, { recursive: true });

package/src/domain/services/HttpSyncServer.js

@@ -22,9 +22,10 @@ function canonicalizeJson(value) {
     return value.map(canonicalizeJson);
   }
   if (value && typeof value === 'object') {
+    /** @type {{ [x: string]: * }} */
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
-      sorted[key] = canonicalizeJson(value[key]);
+      sorted[key] = canonicalizeJson(/** @type {{ [x: string]: * }} */ (value)[key]);
     }
     return sorted;
   }
@@ -97,7 +98,7 @@ function isValidSyncRequest(parsed) {
  * Checks the content-type header. Returns an error response if the
  * content type is present but not application/json, otherwise null.
  *
- * @param {Object} headers - Request headers
+ * @param {{ [x: string]: string }} headers - Request headers
  * @returns {{ status: number, headers: Object, body: string }|null}
  * @private
  */
@@ -113,7 +114,7 @@ function checkContentType(headers) {
  * Parses the request URL and validates the path and method.
  * Returns an error response on failure, or null if valid.
  *
- * @param {{ method: string, url: string, headers: Object }} request
+ * @param {{ method: string, url: string, headers: { [x: string]: string } }} request
  * @param {string} expectedPath
  * @param {string} defaultHost
  * @returns {{ status: number, headers: Object, body: string }|null}
@@ -171,12 +172,12 @@ export default class HttpSyncServer {
   /**
    * @param {Object} options
    * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server port abstraction
-   * @param {Object} options.graph - WarpGraph instance (must expose processSyncRequest)
+   * @param {{ processSyncRequest: (request: *) => Promise<*> }} 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
    */
-  constructor({ httpPort, graph, path = '/sync', host = '127.0.0.1', maxRequestBytes = DEFAULT_MAX_REQUEST_BYTES } = {}) {
+  constructor({ httpPort, graph, path = '/sync', host = '127.0.0.1', maxRequestBytes = DEFAULT_MAX_REQUEST_BYTES } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     this._httpPort = httpPort;
     this._graph = graph;
     this._path = path && path.startsWith('/') ? path : `/${path || 'sync'}`;
@@ -188,7 +189,7 @@ export default class HttpSyncServer {
   /**
    * Handles an incoming HTTP request through the port abstraction.
    *
-   * @param {{ method: string, url: string, headers: Object, body: Buffer|undefined }} request
+   * @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request
    * @returns {Promise<{ status: number, headers: Object, body: string }>}
    * @private
    */
@@ -212,7 +213,7 @@ export default class HttpSyncServer {
       const response = await this._graph.processSyncRequest(parsed);
       return jsonResponse(response);
     } catch (err) {
-      return errorResponse(500, err?.message || 'Sync failed');
+      return errorResponse(500, /** @type {any} */ (err)?.message || 'Sync failed'); // TODO(ts-cleanup): type error
     }
   }
 
@@ -228,18 +229,18 @@ export default class HttpSyncServer {
       throw new Error('listen() requires a numeric port');
     }
 
-    const server = this._httpPort.createServer((request) => this._handleRequest(request));
+    const server = this._httpPort.createServer((/** @type {*} */ request) => this._handleRequest(request)); // TODO(ts-cleanup): type http callback
     this._server = server;
 
-    await new Promise((resolve, reject) => {
-      server.listen(port, this._host, (err) => {
+    await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+      server.listen(port, this._host, (/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
         if (err) {
           reject(err);
         } else {
           resolve();
         }
       });
-    });
+    }));
 
     const address = server.address();
     const actualPort = typeof address === 'object' && address ? address.port : port;
@@ -248,15 +249,15 @@ export default class HttpSyncServer {
     return {
       url,
       close: () =>
-        new Promise((resolve, reject) => {
-          server.close((err) => {
+        /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+          server.close((/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
             if (err) {
               reject(err);
             } else {
               resolve();
             }
           });
-        }),
+        })),
     };
   }
 }

package/src/domain/services/IndexRebuildService.js

@@ -40,17 +40,17 @@ export default class IndexRebuildService {
    * Creates an IndexRebuildService instance.
    *
    * @param {Object} options - Configuration options
-   * @param {Object} options.graphService - Graph service providing node iteration.
-   *   Must implement `iterateNodes({ ref, limit }) => AsyncGenerator<GraphNode>`.
+   * @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
    * @throws {Error} If graphService is not provided
    * @throws {Error} If storage adapter is not provided
    */
-  constructor({ graphService, storage, logger = nullLogger, codec, crypto }) {
+  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     if (!graphService) {
       throw new Error('IndexRebuildService requires a graphService');
     }
@@ -156,7 +156,7 @@ export default class IndexRebuildService {
         operation: 'rebuild',
         ref,
         mode,
-        error: err.message,
+        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
         durationMs,
       });
       throw err;
@@ -247,12 +247,12 @@ export default class IndexRebuildService {
    * @private
    */
   async _rebuildStreaming(ref, { limit, maxMemoryBytes, onFlush, onProgress, signal, frontier }) {
-    const builder = new StreamingBitmapIndexBuilder({
+    const builder = new StreamingBitmapIndexBuilder(/** @type {*} */ ({ // TODO(ts-cleanup): narrow port type
       storage: this.storage,
       maxMemoryBytes,
       onFlush,
       crypto: this._crypto,
-    });
+    }));
 
     let processedNodes = 0;
 
@@ -266,7 +266,7 @@ export default class IndexRebuildService {
       if (processedNodes % 10000 === 0) {
         checkAborted(signal, 'rebuild');
         if (onProgress) {
-          const stats = builder.getMemoryStats();
+          const stats = /** @type {any} */ (builder).getMemoryStats(); // TODO(ts-cleanup): narrow port type
           onProgress({
             processedNodes,
             currentMemoryBytes: stats.estimatedBitmapBytes,
@@ -275,7 +275,7 @@ export default class IndexRebuildService {
       }
     }
 
-    return await builder.finalize({ signal, frontier });
+    return await /** @type {any} */ (builder).finalize({ signal, frontier }); // TODO(ts-cleanup): narrow port type
   }
 
   /**
@@ -302,10 +302,10 @@ export default class IndexRebuildService {
     const treeStructure = await builder.serialize({ frontier });
     const flatEntries = [];
     for (const [path, buffer] of Object.entries(treeStructure)) {
-      const oid = await this.storage.writeBlob(buffer);
+      const oid = await /** @type {import('../../ports/BlobPort.js').default} */ (/** @type {unknown} */ (this.storage)).writeBlob(buffer);
       flatEntries.push(`100644 blob ${oid}\t${path}`);
     }
-    return await this.storage.writeTree(flatEntries);
+    return await /** @type {import('../../ports/TreePort.js').default} */ (/** @type {unknown} */ (this.storage)).writeTree(flatEntries);
   }
 
   /**
@@ -384,12 +384,12 @@ export default class IndexRebuildService {
     }
 
     const startTime = performance.now();
-    const shardOids = await this.storage.readTreeOids(treeOid);
+    const shardOids = await /** @type {import('../../ports/TreePort.js').default} */ (/** @type {unknown} */ (this.storage)).readTreeOids(treeOid);
     const shardCount = Object.keys(shardOids).length;
 
     // Staleness check
     if (currentFrontier) {
-      const indexFrontier = await loadIndexFrontier(shardOids, this.storage, { codec: this._codec });
+      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {*} */ (this.storage), { codec: this._codec }); // TODO(ts-cleanup): narrow port type
       if (indexFrontier) {
         const result = checkStaleness(indexFrontier, currentFrontier);
         if (result.stale) {

package/src/domain/services/IndexStalenessChecker.js

@@ -5,7 +5,11 @@
 
 import defaultCodec from '../utils/defaultCodec.js';
 
-/** @private */
+/**
+ * @param {*} envelope
+ * @param {string} label
+ * @private
+ */
 function validateEnvelope(envelope, label) {
   if (!envelope || typeof envelope !== 'object' || !envelope.frontier || typeof envelope.frontier !== 'object') {
     throw new Error(`invalid frontier envelope for ${label}`);
@@ -16,17 +20,17 @@ function validateEnvelope(envelope, label) {
  * Loads the frontier from an index tree's shard OIDs.
  *
  * @param {Record<string, string>} shardOids - Map of path → blob OID from readTreeOids
- * @param {import('../../ports/IndexStoragePort.js').default} storage - Storage adapter
+ * @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
  * @returns {Promise<Map<string, string>|null>} Frontier map, or null if not present (legacy index)
  */
-export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
+export async function loadIndexFrontier(shardOids, storage, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
   const cborOid = shardOids['frontier.cbor'];
   if (cborOid) {
     const buffer = await storage.readBlob(cborOid);
-    const envelope = c.decode(buffer);
+    const envelope = /** @type {{ frontier: Record<string, string> }} */ (c.decode(buffer));
     validateEnvelope(envelope, 'frontier.cbor');
     return new Map(Object.entries(envelope.frontier));
   }
@@ -34,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 = JSON.parse(buffer.toString('utf-8'));
+    const envelope = /** @type {{ frontier: Record<string, string> }} */ (JSON.parse(buffer.toString('utf-8')));
     validateEnvelope(envelope, 'frontier.json');
     return new Map(Object.entries(envelope.frontier));
   }
@@ -51,7 +55,10 @@ export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
  * @property {string[]} removedWriters - Writers in index but not current
  */
 
-/** @private */
+/**
+ * @param {{ stale: boolean, advancedWriters: string[], newWriters: string[], removedWriters: string[] }} opts
+ * @private
+ */
 function buildReason({ stale, advancedWriters, newWriters, removedWriters }) {
   if (!stale) {
     return 'index is current';