@git-stunts/git-warp 11.2.1 → 11.3.3

package/src/domain/crdt/ORSet.js

@@ -91,7 +91,7 @@ import { vvContains } from './VersionVector.js';
  * An element is present if it has at least one non-tombstoned dot.
  *
  * @typedef {Object} ORSet
- * @property {Map<*, Set<string>>} entries - element -> dots that added it
+ * @property {Map<string, Set<string>>} entries - element -> dots that added it
  * @property {Set<string>} tombstones - global tombstones
  */
 
@@ -112,7 +112,7 @@ export function createORSet() {
  * Mutates the set.
  *
  * @param {ORSet} set - The ORSet to mutate
- * @param {*} element - The element to add
+ * @param {string} element - The element to add
  * @param {import('./Dot.js').Dot} dot - The dot representing this add operation
  */
 export function orsetAdd(set, element, dot) {
@@ -145,7 +145,7 @@ export function orsetRemove(set, observedDots) {
  * An element is present if it has at least one non-tombstoned dot.
  *
  * @param {ORSet} set - The ORSet to check
- * @param {*} element - The element to check
+ * @param {string} element - The element to check
  * @returns {boolean}
  */
 export function orsetContains(set, element) {
@@ -168,7 +168,7 @@ export function orsetContains(set, element) {
  * Only returns elements that have at least one non-tombstoned dot.
  *
  * @param {ORSet} set - The ORSet
- * @returns {Array<*>} Array of present elements
+ * @returns {string[]} Array of present elements
  */
 export function orsetElements(set) {
   const result = [];
@@ -186,7 +186,7 @@ export function orsetElements(set) {
  * Returns the non-tombstoned dots for an element.
  *
  * @param {ORSet} set - The ORSet
- * @param {*} element - The element
+ * @param {string} element - The element
  * @returns {Set<string>} Set of encoded dots that are not tombstoned
  */
 export function orsetGetDots(set, element) {
@@ -311,11 +311,11 @@ export function orsetCompact(set, includedVV) {
  * Tombstones are sorted.
  *
  * @param {ORSet} set
- * @returns {{entries: Array<[*, string[]]>, tombstones: string[]}}
+ * @returns {{entries: Array<[string, string[]]>, tombstones: string[]}}
  */
 export function orsetSerialize(set) {
   // Serialize entries: convert Map to array of [element, sortedDots]
-  /** @type {Array<[any, string[]]>} */
+  /** @type {Array<[string, string[]]>} */
   const entriesArray = [];
   for (const [element, dots] of set.entries) {
     const sortedDots = [...dots].sort((a, b) => {
@@ -349,7 +349,7 @@ export function orsetSerialize(set) {
 /**
  * Deserializes a plain object back to an ORSet.
  *
- * @param {{entries?: Array<[*, string[]]>, tombstones?: string[]}} obj
+ * @param {{entries?: Array<[string, string[]]>, tombstones?: string[]}} obj
  * @returns {ORSet}
  */
 export function orsetDeserialize(obj) {

package/src/domain/errors/EmptyMessageError.js

@@ -12,7 +12,7 @@ import IndexError from './IndexError.js';
  * @property {string} name - The error name ('EmptyMessageError')
  * @property {string} code - Error code ('EMPTY_MESSAGE')
  * @property {string} operation - The operation that failed due to empty message
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (!message || message.trim() === '') {
@@ -27,7 +27,7 @@ export default class EmptyMessageError extends IndexError {
    * Creates a new EmptyMessageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ operation?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ operation?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ForkError.js

@@ -26,7 +26,7 @@ import WarpError from './WarpError.js';
 export default class ForkError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'FORK_ERROR', options);

package/src/domain/errors/IndexError.js

@@ -19,7 +19,7 @@ import WarpError from './WarpError.js';
 export default class IndexError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'INDEX_ERROR', options);

package/src/domain/errors/OperationAbortedError.js

@@ -15,7 +15,7 @@ import WarpError from './WarpError.js';
 export default class OperationAbortedError extends WarpError {
   /**
    * @param {string} operation
-   * @param {{ code?: string, context?: Object, reason?: string }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown>, reason?: string }} [options={}]
    */
   constructor(operation, options = {}) {
     const reason = options.reason || 'Operation was aborted';

package/src/domain/errors/QueryError.js

@@ -35,7 +35,7 @@ import WarpError from './WarpError.js';
 export default class QueryError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'QUERY_ERROR', options);

package/src/domain/errors/SchemaUnsupportedError.js

@@ -13,7 +13,7 @@ import WarpError from './WarpError.js';
 export default class SchemaUnsupportedError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'E_SCHEMA_UNSUPPORTED', options);

package/src/domain/errors/ShardCorruptionError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the corrupted shard file
  * @property {string} oid - Object ID associated with the shard
  * @property {string} reason - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (!validateChecksum(data)) {
@@ -30,7 +30,7 @@ export default class ShardCorruptionError extends IndexError {
    * Creates a new ShardCorruptionError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, oid?: string, reason?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, oid?: string, reason?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardLoadError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the shard file that failed to load
  * @property {string} oid - Object ID associated with the shard
  * @property {Error} cause - The original error that caused the load failure
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,7 +32,7 @@ export default class ShardLoadError extends IndexError {
    * Creates a new ShardLoadError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardValidationError.js

@@ -12,10 +12,10 @@ import IndexError from './IndexError.js';
  * @property {string} name - The error name ('ShardValidationError')
  * @property {string} code - Error code ('SHARD_VALIDATION_ERROR')
  * @property {string} shardPath - Path to the shard file that failed validation
- * @property {*} expected - The expected value for the field
- * @property {*} actual - The actual value found in the shard
+ * @property {unknown} expected - The expected value for the field
+ * @property {unknown} actual - The actual value found in the shard
  * @property {string} field - The field that failed validation (e.g., 'checksum', 'version')
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (shard.version !== EXPECTED_VERSION) {
@@ -32,7 +32,7 @@ export default class ShardValidationError extends IndexError {
    * Creates a new ShardValidationError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, expected?: *, actual?: *, field?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, expected?: unknown, actual?: unknown, field?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/StorageError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} operation - The operation that failed ('read' or 'write')
  * @property {string} oid - Object ID associated with the operation
  * @property {Error} cause - The original error that caused the failure
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,7 +32,7 @@ export default class StorageError extends IndexError {
    * Creates a new StorageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/SyncError.js

@@ -26,7 +26,7 @@ import WarpError from './WarpError.js';
 export default class SyncError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'SYNC_ERROR', options);

package/src/domain/errors/TraversalError.js

@@ -19,7 +19,7 @@ import WarpError from './WarpError.js';
 export default class TraversalError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'TRAVERSAL_ERROR', options);

package/src/domain/errors/TrustError.js

@@ -21,7 +21,7 @@ import WarpError from './WarpError.js';
 export default class TrustError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'TRUST_ERROR', options);

package/src/domain/errors/WarpError.js

@@ -10,13 +10,13 @@
  *
  * @property {string} name - Error name (set from constructor.name)
  * @property {string} code - Machine-readable error code
- * @property {Record<string, *>} context - Serializable context for debugging
+ * @property {Record<string, unknown>} context - Serializable context for debugging
  */
 export default class WarpError extends Error {
   /**
    * @param {string} message - Human-readable error message
    * @param {string} defaultCode - Default error code if not overridden by options
-   * @param {{ code?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, defaultCode, options = {}) {
     super(message);

package/src/domain/errors/WormholeError.js

@@ -24,7 +24,7 @@ import WarpError from './WarpError.js';
 export default class WormholeError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'WORMHOLE_ERROR', options);

package/src/domain/services/AuditReceiptService.js

@@ -290,12 +290,12 @@ export class AuditReceiptService {
 
     try {
       return await this._commitInner(tickReceipt);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._failed++;
       this._logger?.warn('[warp:audit]', {
         code: 'AUDIT_COMMIT_FAILED',
         writerId: this._writerId,
-        error: err?.message,
+        error: err instanceof Error ? err.message : String(err),
       });
       return null;
     }
@@ -366,11 +366,11 @@ export class AuditReceiptService {
     let blobOid;
     try {
       blobOid = await this._persistence.writeBlob(Buffer.from(cborBytes));
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._logger?.warn('[warp:audit]', {
         code: 'AUDIT_WRITE_BLOB_FAILED',
         writerId: this._writerId,
-        error: err?.message,
+        error: err instanceof Error ? err.message : String(err),
       });
       throw err;
     }
@@ -381,11 +381,11 @@ export class AuditReceiptService {
       treeOid = await this._persistence.writeTree([
         `100644 blob ${blobOid}\treceipt.cbor`,
       ]);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow catch type
+    } catch (err) {
       this._logger?.warn('[warp:audit]', {
         code: 'AUDIT_WRITE_TREE_FAILED',
         writerId: this._writerId,
-        error: err?.message,
+        error: err instanceof Error ? err.message : String(err),
       });
       throw err;
     }

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);
   }
 }