@git-stunts/git-warp 11.2.1 → 11.5.0

package/src/domain/services/CheckpointService.js

@@ -25,7 +25,7 @@ import { createORSet, orsetAdd, orsetCompact } from '../crdt/ORSet.js';
 import { createDot } from '../crdt/Dot.js';
 import { createVersionVector } from '../crdt/VersionVector.js';
 import { cloneStateV5, reduceV5 } from './JoinReducer.js';
-import { encodeEdgeKey, encodePropKey } from './KeyCodec.js';
+import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
 // ============================================================================
@@ -132,6 +132,20 @@ export async function createV5({
     provenanceIndexBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (provenanceIndexBuffer));
   }
 
+  // 6c. Collect content blob OIDs from state properties for GC anchoring.
+  // If patch commits are ever pruned, content blobs remain reachable via
+  // the checkpoint tree. Without this, git gc would nuke content blobs
+  // whose only anchor was the (now-pruned) patch commit tree.
+  const contentOids = new Set();
+  for (const [propKey, register] of checkpointState.prop) {
+    const { propKey: decodedKey } = isEdgePropKey(propKey)
+      ? decodeEdgePropKey(propKey)
+      : decodePropKey(propKey);
+    if (decodedKey === CONTENT_PROPERTY_KEY && typeof register.value === 'string') {
+      contentOids.add(register.value);
+    }
+  }
+
   // 7. Create tree with sorted entries
   const treeEntries = [
     `100644 blob ${appliedVVBlobOid}\tappliedVV.cbor`,
@@ -145,6 +159,11 @@ export async function createV5({
     treeEntries.push(`100644 blob ${provenanceIndexBlobOid}\tprovenanceIndex.cbor`);
   }
 
+  // Add content blob anchors
+  for (const oid of contentOids) {
+    treeEntries.push(`100644 blob ${oid}\t_content_${oid}`);
+  }
+
   // Sort entries by filename for deterministic tree (git requires sorted entries by path)
   treeEntries.sort((a, b) => {
     const filenameA = a.split('\t')[1];
@@ -196,7 +215,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 +346,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} */

package/src/domain/services/HttpSyncServer.js

@@ -8,15 +8,56 @@
  * @module domain/services/HttpSyncServer
  */
 
+import { z } from 'zod';
 import SyncAuthService from './SyncAuthService.js';
 
 const DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
+const MAX_REQUEST_BYTES_CEILING = 128 * 1024 * 1024; // 134217728
+
+/**
+ * Zod schema for HttpSyncServer constructor options.
+ * @private
+ */
+const authSchema = z.object({
+  mode: z.enum(['enforce', 'log-only']).default('enforce'),
+  keys: z.record(z.string()).refine(
+    (obj) => Object.keys(obj).length > 0,
+    'auth.keys must not be empty',
+  ),
+  crypto: /** @type {z.ZodType<import('../../ports/CryptoPort.js').default>} */ (z.custom((v) => v === undefined || (typeof v === 'object' && v !== null))).optional(),
+  logger: /** @type {z.ZodType<import('../../ports/LoggerPort.js').default>} */ (z.custom((v) => v === undefined || (typeof v === 'object' && v !== null))).optional(),
+  wallClockMs: /** @type {z.ZodType<() => number>} */ (z.custom((v) => v === undefined || typeof v === 'function')).optional(),
+}).strict();
+
+const optionsSchema = z.object({
+  httpPort: /** @type {z.ZodType<import('../../ports/HttpServerPort.js').default>} */ (z.custom(
+    (v) => v !== null && v !== undefined && typeof v === 'object',
+    'httpPort must be a non-null object',
+  )),
+  graph: /** @type {z.ZodType<import('../WarpGraph.js').default>} */ (z.custom(
+    (v) => v !== null && v !== undefined && typeof v === 'object',
+    'graph must be a non-null object',
+  )),
+  maxRequestBytes: z.number().int().positive().max(MAX_REQUEST_BYTES_CEILING).default(DEFAULT_MAX_REQUEST_BYTES),
+  path: z.string().startsWith('/').default('/sync'),
+  host: z.string().min(1).default('127.0.0.1'),
+  auth: authSchema.optional(),
+  allowedWriters: z.array(z.string()).optional(),
+}).strict().superRefine((data, ctx) => {
+  if (data.allowedWriters && data.allowedWriters.length > 0 && !data.auth) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'allowedWriters requires auth.keys to be configured',
+      path: ['allowedWriters'],
+    });
+  }
+});
 
 /**
  * Recursively sorts object keys for deterministic JSON output.
  *
- * @param {*} value - Any JSON-serializable value
- * @returns {*} The canonicalized value with sorted object keys
+ * @param {unknown} value - Any JSON-serializable value
+ * @returns {unknown} The canonicalized value with sorted object keys
  * @private
  */
 function canonicalizeJson(value) {
@@ -24,10 +65,10 @@ function canonicalizeJson(value) {
     return value.map(canonicalizeJson);
   }
   if (value && typeof value === 'object') {
-    /** @type {{ [x: string]: * }} */
+    /** @type {{ [x: string]: unknown }} */
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
-      sorted[key] = canonicalizeJson(/** @type {{ [x: string]: * }} */ (value)[key]);
+      sorted[key] = canonicalizeJson(/** @type {{ [x: string]: unknown }} */ (value)[key]);
     }
     return sorted;
   }
@@ -37,7 +78,7 @@ function canonicalizeJson(value) {
 /**
  * Produces a canonical JSON string with sorted keys.
  *
- * @param {*} value - Any JSON-serializable value
+ * @param {unknown} value - Any JSON-serializable value
  * @returns {string} Canonical JSON string
  * @private
  */
@@ -64,7 +105,7 @@ function errorResponse(status, message) {
 /**
  * Builds a JSON success response with canonical key ordering.
  *
- * @param {*} data - Response payload
+ * @param {unknown} data - Response payload
  * @returns {{ status: number, headers: Object, body: string }}
  * @private
  */
@@ -79,7 +120,7 @@ function jsonResponse(data) {
 /**
  * Validates that a sync request object has the expected shape.
  *
- * @param {*} parsed - Parsed JSON body
+ * @param {unknown} parsed - Parsed JSON body
  * @returns {boolean} True if valid
  * @private
  */
@@ -87,10 +128,11 @@ function isValidSyncRequest(parsed) {
   if (!parsed || typeof parsed !== 'object') {
     return false;
   }
-  if (parsed.type !== 'sync-request') {
+  const rec = /** @type {Record<string, unknown>} */ (parsed);
+  if (rec.type !== 'sync-request') {
     return false;
   }
-  if (!parsed.frontier || typeof parsed.frontier !== 'object' || Array.isArray(parsed.frontier)) {
+  if (!rec.frontier || typeof rec.frontier !== 'object' || Array.isArray(rec.frontier)) {
     return false;
   }
   return true;
@@ -160,7 +202,7 @@ function checkBodySize(body, maxBytes) {
  * Parses and validates the request body as a sync request.
  *
  * @param {Buffer|undefined} body
- * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: Object }}
+ * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
  * @private
  */
 function parseBody(body) {
@@ -183,19 +225,14 @@ function parseBody(body) {
 /**
  * Initializes auth service from config if present.
  *
- * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: *, logger?: *, wallClockMs?: () => number }|undefined} auth
+ * @param {z.infer<typeof authSchema>} [auth]
  * @param {string[]} [allowedWriters]
  * @returns {{ auth: SyncAuthService|null, authMode: string|null }}
  * @private
  */
 function initAuth(auth, allowedWriters) {
-  if (auth && auth.keys) {
-    const VALID_MODES = new Set(['enforce', 'log-only']);
-    const mode = auth.mode || 'enforce';
-    if (!VALID_MODES.has(mode)) {
-      throw new Error(`Invalid auth.mode: '${mode}'. Must be 'enforce' or 'log-only'.`);
-    }
-    return { auth: new SyncAuthService({ ...auth, allowedWriters }), authMode: mode };
+  if (auth) {
+    return { auth: new SyncAuthService({ ...auth, allowedWriters }), authMode: auth.mode };
   }
   return { auth: null, authMode: null };
 }
@@ -204,26 +241,35 @@ export default class HttpSyncServer {
   /**
    * @param {Object} options
    * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server port abstraction
-   * @param {{ processSyncRequest: (request: *) => Promise<*> }} options.graph - WarpGraph instance (must expose processSyncRequest)
+   * @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
    */
-  constructor({ httpPort, graph, path = '/sync', host = '127.0.0.1', maxRequestBytes = DEFAULT_MAX_REQUEST_BYTES, auth, allowedWriters } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
-    this._httpPort = httpPort;
-    this._graph = graph;
-    this._path = path && path.startsWith('/') ? path : `/${path || 'sync'}`;
-    this._host = host;
-    this._maxRequestBytes = maxRequestBytes;
+  constructor(options) {
+    /** @type {z.infer<typeof optionsSchema>} */
+    let parsed;
+    try {
+      parsed = optionsSchema.parse(options);
+    } catch (err) {
+      if (err instanceof z.ZodError) {
+        const messages = err.issues.map((i) => i.message).join('; ');
+        throw new Error(`HttpSyncServer config: ${messages}`);
+      }
+      throw err;
+    }
+
+    this._httpPort = parsed.httpPort;
+    this._graph = parsed.graph;
+    this._path = parsed.path;
+    this._host = parsed.host;
+    this._maxRequestBytes = parsed.maxRequestBytes;
     this._server = null;
-    const authInit = initAuth(auth, allowedWriters);
+    const authInit = initAuth(parsed.auth, parsed.allowedWriters);
     this._auth = authInit.auth;
     this._authMode = authInit.authMode;
-    if (allowedWriters && !authInit.auth) {
-      throw new Error('allowedWriters requires auth.keys to be configured');
-    }
   }
 
   /**
@@ -234,7 +280,7 @@ export default class HttpSyncServer {
    * null so the request proceeds.
    *
    * @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request
-   * @param {*} parsed - Parsed sync request body
+   * @param {Record<string, unknown>} parsed - Parsed sync request body
    * @returns {Promise<{ status: number, headers: Object, body: string }|null>}
    * @private
    */
@@ -264,29 +310,31 @@ export default class HttpSyncServer {
     return null;
   }
 
-  /** @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request */
+  /** @param {{ method: string, url: string, headers: Object, body: Buffer|undefined }} request */
   async _handleRequest(request) {
-    const contentTypeError = checkContentType(request.headers);
+    /** @type {{ method: string, url: string, headers: Record<string, string>, body: Buffer|undefined }} */
+    const req = { ...request, headers: /** @type {Record<string, string>} */ (request.headers) };
+    const contentTypeError = checkContentType(req.headers);
     if (contentTypeError) {
       return contentTypeError;
     }
 
-    const routeError = validateRoute(request, this._path, this._host);
+    const routeError = validateRoute(req, this._path, this._host);
     if (routeError) {
       return routeError;
     }
 
-    const sizeError = checkBodySize(request.body, this._maxRequestBytes);
+    const sizeError = checkBodySize(req.body, this._maxRequestBytes);
     if (sizeError) {
       return sizeError;
     }
 
-    const { error, parsed } = parseBody(request.body);
+    const { error, parsed } = parseBody(req.body);
     if (error) {
       return error;
     }
 
-    const authError = await this._authorize(request, parsed);
+    const authError = await this._authorize(req, parsed);
     if (authError) {
       return authError;
     }
@@ -294,8 +342,8 @@ export default class HttpSyncServer {
     try {
       const response = await this._graph.processSyncRequest(parsed);
       return jsonResponse(response);
-    } catch (err) {
-      return errorResponse(500, /** @type {any} */ (err)?.message || 'Sync failed'); // TODO(ts-cleanup): type error
+    } catch (/** @type {unknown} */ err) {
+      return errorResponse(500, err instanceof Error ? err.message : 'Sync failed');
     }
   }
 
@@ -311,11 +359,14 @@ export default class HttpSyncServer {
       throw new Error('listen() requires a numeric port');
     }
 
-    const server = this._httpPort.createServer((/** @type {*} */ request) => this._handleRequest(request)); // TODO(ts-cleanup): type http callback
+    /** @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),
+    );
     this._server = server;
 
     await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-      server.listen(port, this._host, (/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
+      server.listen(port, this._host, (/** @type {Error|null} */ err) => {
         if (err) {
           reject(err);
         } else {
@@ -332,7 +383,7 @@ export default class HttpSyncServer {
       url,
       close: () =>
         /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-          server.close((/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
+          server.close((/** @type {Error|null} */ err) => {
             if (err) {
               reject(err);
             } else {

package/src/domain/services/IndexRebuildService.js

@@ -50,7 +50,7 @@ export default class IndexRebuildService {
    * @throws {Error} If graphService is not provided
    * @throws {Error} If storage adapter is not provided
    */
-  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {{ graphService: { iterateNodes: (opts: { ref: string, limit: number }) => AsyncIterable<{ sha: string, parents: string[] }> }, storage: import('../../ports/IndexStoragePort.js').default }} */ ({})) {
     if (!graphService) {
       throw new Error('IndexRebuildService requires a graphService');
     }
@@ -156,7 +156,7 @@ export default class IndexRebuildService {
         operation: 'rebuild',
         ref,
         mode,
-        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
+        error: err instanceof Error ? err.message : String(err),
         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(/** @type {*} */ ({ // TODO(ts-cleanup): narrow port type
+    const builder = new StreamingBitmapIndexBuilder({
       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 = /** @type {any} */ (builder).getMemoryStats(); // TODO(ts-cleanup): narrow port type
+          const stats = /** @type {{ estimatedBitmapBytes: number }} */ (builder.getMemoryStats());
           onProgress({
             processedNodes,
             currentMemoryBytes: stats.estimatedBitmapBytes,
@@ -275,7 +275,7 @@ export default class IndexRebuildService {
       }
     }
 
-    return await /** @type {any} */ (builder).finalize({ signal, frontier }); // TODO(ts-cleanup): narrow port type
+    return await builder.finalize({ signal, frontier });
   }
 
   /**
@@ -389,7 +389,7 @@ export default class IndexRebuildService {
 
     // Staleness check
     if (currentFrontier) {
-      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {*} */ (this.storage), { codec: this._codec }); // TODO(ts-cleanup): narrow port type
+      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {import('../../ports/IndexStoragePort.js').default & import('../../ports/BlobPort.js').default} */ (this.storage), { codec: this._codec });
       if (indexFrontier) {
         const result = checkStaleness(indexFrontier, currentFrontier);
         if (result.stale) {

package/src/domain/services/IndexStalenessChecker.js

@@ -6,12 +6,13 @@
 import defaultCodec from '../utils/defaultCodec.js';
 
 /**
- * @param {*} envelope
+ * @param {unknown} envelope
  * @param {string} label
  * @private
  */
 function validateEnvelope(envelope, label) {
-  if (!envelope || typeof envelope !== 'object' || !envelope.frontier || typeof envelope.frontier !== 'object') {
+  const rec = /** @type {Record<string, unknown>} */ (envelope);
+  if (!rec || typeof rec !== 'object' || !rec.frontier || typeof rec.frontier !== 'object') {
     throw new Error(`invalid frontier envelope for ${label}`);
   }
 }
@@ -25,7 +26,7 @@ function validateEnvelope(envelope, label) {
  * @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 } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
   const c = codec || defaultCodec;
   const cborOid = shardOids['frontier.cbor'];
   if (cborOid) {