@git-stunts/git-warp 11.2.1 → 11.5.0

package/src/domain/services/AuditVerifierService.js

@@ -16,6 +16,19 @@
  * @see docs/specs/AUDIT_RECEIPT.md Section 8
  */
 
+/**
+ * @typedef {Object} AuditReceipt
+ * @property {number} version
+ * @property {string} graphName
+ * @property {string} writerId
+ * @property {string} dataCommit
+ * @property {string} opsDigest
+ * @property {string} prevAuditCommit
+ * @property {number} tickStart
+ * @property {number} tickEnd
+ * @property {number} timestamp
+ */
+
 import { buildAuditPrefix, buildAuditRef } from '../utils/RefLayout.js';
 import { decodeAuditMessage } from './AuditMessageCodec.js';
 import { TrustRecordService } from '../trust/TrustRecordService.js';
@@ -67,14 +80,15 @@ function validateOidFormat(value) {
 
 /**
  * Checks whether a receipt object has the expected 9 fields with correct types.
- * @param {*} receipt
+ * @param {unknown} receipt
  * @returns {string|null} Error message or null if valid
  */
 function validateReceiptSchema(receipt) {
   if (!receipt || typeof receipt !== 'object') {
     return 'receipt is not an object';
   }
-  const keys = Object.keys(receipt);
+  const rec = /** @type {Record<string, unknown>} */ (receipt);
+  const keys = Object.keys(rec);
   if (keys.length !== 9) {
     return `expected 9 fields, got ${keys.length}`;
   }
@@ -83,46 +97,46 @@ function validateReceiptSchema(receipt) {
     'tickEnd', 'tickStart', 'timestamp', 'version', 'writerId',
   ];
   for (const k of required) {
-    if (!(k in receipt)) {
+    if (!(k in rec)) {
       return `missing field: ${k}`;
     }
   }
-  if (receipt.version !== 1) {
-    return `unsupported version: ${receipt.version}`;
+  if (rec.version !== 1) {
+    return `unsupported version: ${rec.version}`;
   }
-  if (typeof receipt.graphName !== 'string' || receipt.graphName.length === 0) {
+  if (typeof rec.graphName !== 'string' || rec.graphName.length === 0) {
     return 'graphName must be a non-empty string';
   }
-  if (typeof receipt.writerId !== 'string' || receipt.writerId.length === 0) {
+  if (typeof rec.writerId !== 'string' || rec.writerId.length === 0) {
     return 'writerId must be a non-empty string';
   }
-  if (typeof receipt.dataCommit !== 'string') {
+  if (typeof rec.dataCommit !== 'string') {
     return 'dataCommit must be a string';
   }
-  if (typeof receipt.opsDigest !== 'string') {
+  if (typeof rec.opsDigest !== 'string') {
     return 'opsDigest must be a string';
   }
-  if (typeof receipt.prevAuditCommit !== 'string') {
+  if (typeof rec.prevAuditCommit !== 'string') {
     return 'prevAuditCommit must be a string';
   }
-  if (!Number.isInteger(receipt.tickStart) || receipt.tickStart < 1) {
-    return `tickStart must be integer >= 1, got ${receipt.tickStart}`;
+  if (!Number.isInteger(rec.tickStart) || /** @type {number} */ (rec.tickStart) < 1) {
+    return `tickStart must be integer >= 1, got ${rec.tickStart}`;
   }
-  if (!Number.isInteger(receipt.tickEnd) || receipt.tickEnd < receipt.tickStart) {
-    return `tickEnd must be integer >= tickStart, got ${receipt.tickEnd}`;
+  if (!Number.isInteger(rec.tickEnd) || /** @type {number} */ (rec.tickEnd) < /** @type {number} */ (rec.tickStart)) {
+    return `tickEnd must be integer >= tickStart, got ${rec.tickEnd}`;
   }
-  if (receipt.version === 1 && receipt.tickStart !== receipt.tickEnd) {
-    return `v1 requires tickStart === tickEnd, got ${receipt.tickStart} !== ${receipt.tickEnd}`;
+  if (rec.version === 1 && rec.tickStart !== rec.tickEnd) {
+    return `v1 requires tickStart === tickEnd, got ${rec.tickStart} !== ${rec.tickEnd}`;
   }
-  if (!Number.isInteger(receipt.timestamp) || receipt.timestamp < 0) {
-    return `timestamp must be non-negative integer, got ${receipt.timestamp}`;
+  if (!Number.isInteger(rec.timestamp) || /** @type {number} */ (rec.timestamp) < 0) {
+    return `timestamp must be non-negative integer, got ${rec.timestamp}`;
   }
   return null;
 }
 
 /**
  * Validates trailers against the CBOR receipt fields.
- * @param {*} receipt
+ * @param {AuditReceipt} receipt
  * @param {{ graph: string, writer: string, dataCommit: string, opsDigest: string, schema: number }} decoded
  * @returns {string|null} Error message or null if consistent
  */
@@ -312,7 +326,7 @@ export class AuditVerifierService {
    */
   async _walkChain(graphName, writerId, tip, since, result) {
     let current = tip;
-    /** @type {Record<string, *>|null} */ let prevReceipt = null;
+    /** @type {AuditReceipt|null} */ let prevReceipt = null;
     /** @type {number|null} */ let chainOidLen = null;
 
     while (current) {
@@ -322,8 +336,8 @@ export class AuditVerifierService {
       let commitInfo;
       try {
         commitInfo = await this._persistence.getNodeInfo(current);
-      } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
-        this._addError(result, 'MISSING_RECEIPT_BLOB', `Cannot read commit ${current}: ${err?.message}`, current);
+      } catch (err) {
+        this._addError(result, 'MISSING_RECEIPT_BLOB', `Cannot read commit ${current}: ${err instanceof Error ? err.message : String(err)}`, current);
         return;
       }
 
@@ -456,7 +470,7 @@ export class AuditVerifierService {
    * @param {string} commitSha
    * @param {{ message: string }} commitInfo
    * @param {ChainResult} result
-   * @returns {Promise<{ receipt: *, decodedTrailers: * }|null>}
+   * @returns {Promise<{ receipt: AuditReceipt, decodedTrailers: { graph: string, writer: string, dataCommit: string, opsDigest: string, schema: number } }|null>}
    * @private
    */
   async _readReceipt(commitSha, commitInfo, result) {
@@ -464,9 +478,9 @@ export class AuditVerifierService {
     let treeOid;
     try {
       treeOid = await this._persistence.getCommitTree(commitSha);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._addError(result, 'MISSING_RECEIPT_BLOB',
-        `Cannot read tree for ${commitSha}: ${err?.message}`, commitSha);
+        `Cannot read tree for ${commitSha}: ${err instanceof Error ? err.message : String(err)}`, commitSha);
       return null;
     }
 
@@ -474,9 +488,9 @@ export class AuditVerifierService {
     let treeEntries;
     try {
       treeEntries = await this._persistence.readTreeOids(treeOid);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._addError(result, 'RECEIPT_TREE_INVALID',
-        `Cannot read tree ${treeOid}: ${err?.message}`, commitSha);
+        `Cannot read tree ${treeOid}: ${err instanceof Error ? err.message : String(err)}`, commitSha);
       return null;
     }
 
@@ -493,19 +507,19 @@ export class AuditVerifierService {
     let blobContent;
     try {
       blobContent = await this._persistence.readBlob(blobOid);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._addError(result, 'MISSING_RECEIPT_BLOB',
-        `Cannot read receipt blob ${blobOid}: ${err?.message}`, commitSha);
+        `Cannot read receipt blob ${blobOid}: ${err instanceof Error ? err.message : String(err)}`, commitSha);
       return null;
     }
 
     // Decode CBOR
     let receipt;
     try {
-      receipt = this._codec.decode(blobContent);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+      receipt = /** @type {AuditReceipt} */ (this._codec.decode(blobContent));
+    } catch (err) {
       this._addError(result, 'CBOR_DECODE_FAILED',
-        `CBOR decode failed: ${err?.message}`, commitSha);
+        `CBOR decode failed: ${err instanceof Error ? err.message : String(err)}`, commitSha);
       result.status = STATUS_ERROR;
       return null;
     }
@@ -514,9 +528,9 @@ export class AuditVerifierService {
     let decodedTrailers;
     try {
       decodedTrailers = decodeAuditMessage(commitInfo.message);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._addError(result, 'TRAILER_MISMATCH',
-        `Trailer decode failed: ${err?.message}`, commitSha);
+        `Trailer decode failed: ${err instanceof Error ? err.message : String(err)}`, commitSha);
       result.status = STATUS_DATA_MISMATCH;
       return null;
     }
@@ -526,7 +540,7 @@ export class AuditVerifierService {
 
   /**
    * Validates OID format for dataCommit, prevAuditCommit, and opsDigest.
-   * @param {*} receipt
+   * @param {AuditReceipt} receipt
    * @param {ChainResult} result
    * @param {string} commitSha
    * @returns {boolean} true if valid
@@ -556,8 +570,8 @@ export class AuditVerifierService {
 
   /**
    * Validates chain linking between current and previous (newer) receipt.
-   * @param {*} currentReceipt - The older receipt being validated
-   * @param {*} prevReceipt - The newer receipt (closer to tip)
+   * @param {AuditReceipt} currentReceipt - The older receipt being validated
+   * @param {AuditReceipt} prevReceipt - The newer receipt (closer to tip)
    * @param {string} commitSha
    * @param {ChainResult} result
    * @returns {boolean} true if valid
@@ -645,7 +659,7 @@ export class AuditVerifierService {
    * @param {Object} [options]
    * @param {string} [options.pin] - Pinned trust chain commit SHA
    * @param {string} [options.mode] - Policy mode ('warn' or 'enforce')
-   * @returns {Promise<Record<string, *>>}
+   * @returns {Promise<import('../trust/TrustEvaluator.js').TrustAssessment>}
    */
   async evaluateTrust(graphName, options = {}) {
     const recordService = new TrustRecordService({

package/src/domain/services/BitmapIndexBuilder.js

@@ -103,7 +103,7 @@ export default class BitmapIndexBuilder {
     this.shaToId = new Map();
     /** @type {string[]} */
     this.idToSha = [];
-    /** @type {Map<string, any>} */
+    /** @type {Map<string, import('../utils/roaring.js').RoaringBitmapSubset>} */
     this.bitmaps = new Map();
   }
 
@@ -178,7 +178,7 @@ export default class BitmapIndexBuilder {
         bitmapShards[type][prefix] = {};
       }
       // Encode bitmap as base64 for JSON storage
-      bitmapShards[type][prefix][sha] = bitmap.serialize(true).toString('base64');
+      bitmapShards[type][prefix][sha] = Buffer.from(bitmap.serialize(true)).toString('base64');
     }
 
     for (const type of ['fwd', 'rev']) {
@@ -224,6 +224,6 @@ export default class BitmapIndexBuilder {
       const RoaringBitmap32 = ensureRoaringBitmap32();
       this.bitmaps.set(key, new RoaringBitmap32());
     }
-    this.bitmaps.get(key).add(id);
+    /** @type {import('../utils/roaring.js').RoaringBitmapSubset} */ (this.bitmaps.get(key)).add(id);
   }
 }

package/src/domain/services/BitmapIndexReader.js

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

package/src/domain/services/BoundaryTransitionRecord.js

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

package/src/domain/services/CheckpointSerializerV5.js

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