@git-stunts/git-warp 10.3.2 → 10.4.2

package/src/domain/types/WarpTypesV2.js

@@ -25,9 +25,7 @@
 
 /**
  * Dot - causal identifier for an add operation
- * @typedef {Object} Dot
- * @property {string} writer - Writer ID that created this dot
- * @property {number} seq - Sequence number for this writer
+ * @typedef {import('../crdt/Dot.js').Dot} Dot
  */
 
 /**
@@ -182,6 +180,7 @@ export function createPropSetV2(node, key, value) {
  * @returns {PatchV2} PatchV2 object
  */
 export function createPatchV2({ schema = 2, writer, lamport, context, ops, reads, writes }) {
+  /** @type {PatchV2} */
   const patch = {
     schema,
     writer,

package/src/domain/utils/CachedValue.js

@@ -68,7 +68,7 @@ class CachedValue {
    */
   async get() {
     if (this._isValid()) {
-      return this._value;
+      return /** @type {T} */ (this._value);
     }
 
     const value = await this._compute();

package/src/domain/utils/LRUCache.js

@@ -35,7 +35,7 @@ class LRUCache {
       return undefined;
     }
     // Move to end (most recently used) by deleting and re-inserting
-    const value = this._cache.get(key);
+    const value = /** @type {V} */ (this._cache.get(key));
     this._cache.delete(key);
     this._cache.set(key, value);
     return value;
@@ -48,7 +48,7 @@ class LRUCache {
    *
    * @param {K} key - The key to set
    * @param {V} value - The value to cache
-   * @returns {LRUCache} The cache instance for chaining
+   * @returns {LRUCache<K, V>} The cache instance for chaining
    */
   set(key, value) {
     // If key exists, delete it first so it moves to the end
@@ -61,7 +61,7 @@ class LRUCache {
 
     // Evict oldest entry if over capacity
     if (this._cache.size > this.maxSize) {
-      const oldestKey = this._cache.keys().next().value;
+      const oldestKey = /** @type {K} */ (this._cache.keys().next().value);
       this._cache.delete(oldestKey);
     }
 

package/src/domain/utils/MinHeap.js

@@ -32,10 +32,10 @@ class MinHeap {
    */
   extractMin() {
     if (this.heap.length === 0) { return undefined; }
-    if (this.heap.length === 1) { return this.heap.pop().item; }
+    if (this.heap.length === 1) { return /** @type {{item: *, priority: number}} */ (this.heap.pop()).item; }
 
     const min = this.heap[0];
-    this.heap[0] = this.heap.pop();
+    this.heap[0] = /** @type {{item: *, priority: number}} */ (this.heap.pop());
     this._bubbleDown(0);
     return min.item;
   }

package/src/domain/utils/RefLayout.js

@@ -291,6 +291,25 @@ export function buildCursorSavedPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/cursor/saved/`;
 }
 
+/**
+ * Builds the seek cache ref path for the given graph.
+ *
+ * The seek cache ref points to a blob containing a JSON index of
+ * cached materialization states, keyed by (ceiling, frontier) tuples.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/seek-cache`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildSeekCacheRef('events');
+ * // => 'refs/warp/events/seek-cache'
+ */
+export function buildSeekCacheRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/seek-cache`;
+}
+
 // -----------------------------------------------------------------------------
 // Parsers
 // -----------------------------------------------------------------------------

package/src/domain/utils/WriterId.js

@@ -178,7 +178,7 @@ export async function resolveWriterId({ graphName, explicitWriterId, configGet,
   try {
     existing = await configGet(key);
   } catch (e) {
-    throw new WriterIdError('CONFIG_READ_FAILED', `Failed to read git config key ${key}`, e);
+    throw new WriterIdError('CONFIG_READ_FAILED', `Failed to read git config key ${key}`, /** @type {Error|undefined} */ (e));
   }
 
   if (existing) {
@@ -198,7 +198,7 @@ export async function resolveWriterId({ graphName, explicitWriterId, configGet,
   try {
     await configSet(key, fresh);
   } catch (e) {
-    throw new WriterIdError('CONFIG_WRITE_FAILED', `Failed to persist writerId to git config key ${key}`, e);
+    throw new WriterIdError('CONFIG_WRITE_FAILED', `Failed to persist writerId to git config key ${key}`, /** @type {Error|undefined} */ (e));
   }
 
   return fresh;

package/src/domain/utils/defaultCodec.js

@@ -18,20 +18,27 @@ const encoder = new Encoder({
   mapsAsObjects: true,
 });
 
+/**
+ * Recursively sorts object keys for deterministic CBOR encoding.
+ * @param {unknown} value - The value to sort keys of
+ * @returns {unknown} The value with sorted keys
+ */
 function sortKeys(value) {
   if (value === null || value === undefined) { return value; }
   if (Array.isArray(value)) { return value.map(sortKeys); }
   if (value instanceof Map) {
+    /** @type {Record<string, unknown>} */
     const sorted = {};
     for (const key of Array.from(value.keys()).sort()) {
       sorted[key] = sortKeys(value.get(key));
     }
     return sorted;
   }
-  if (typeof value === 'object' && (value.constructor === Object || value.constructor === undefined)) {
+  if (typeof value === 'object' && (/** @type {Object} */ (value).constructor === Object || /** @type {Object} */ (value).constructor === undefined)) {
+    /** @type {Record<string, unknown>} */
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
-      sorted[key] = sortKeys(value[key]);
+      sorted[key] = sortKeys(/** @type {Record<string, unknown>} */ (value)[key]);
     }
     return sorted;
   }

package/src/domain/utils/defaultCrypto.js

@@ -0,0 +1,36 @@
+/**
+ * Default crypto implementation for domain services.
+ *
+ * Provides SHA hashing, HMAC, and timing-safe comparison using
+ * node:crypto directly, avoiding concrete adapter imports from
+ * the infrastructure layer. This follows the same pattern as
+ * defaultCodec.js and defaultClock.js.
+ *
+ * Since git-warp requires Git (and therefore Node 22+, Deno, or Bun),
+ * node:crypto is always available.
+ *
+ * @module domain/utils/defaultCrypto
+ */
+
+import {
+  createHash,
+  createHmac,
+  timingSafeEqual as nodeTimingSafeEqual,
+} from 'node:crypto';
+
+/** @type {import('../../ports/CryptoPort.js').default} */
+const defaultCrypto = {
+  // eslint-disable-next-line @typescript-eslint/require-await -- async matches CryptoPort contract
+  async hash(algorithm, data) {
+    return createHash(algorithm).update(data).digest('hex');
+  },
+  // eslint-disable-next-line @typescript-eslint/require-await -- async matches CryptoPort contract
+  async hmac(algorithm, key, data) {
+    return createHmac(algorithm, key).update(data).digest();
+  },
+  timingSafeEqual(a, b) {
+    return nodeTimingSafeEqual(a, b);
+  },
+};
+
+export default defaultCrypto;

package/src/domain/utils/roaring.js

@@ -32,7 +32,7 @@ const NOT_CHECKED = Symbol('NOT_CHECKED');
 
 /**
  * Cached reference to the loaded roaring module.
- * @type {Object|null}
+ * @type {any} // TODO(ts-cleanup): type lazy singleton
  * @private
  */
 let roaringModule = null;
@@ -51,7 +51,7 @@ let nativeAvailability = NOT_CHECKED;
  * Uses a top-level-await-friendly pattern with dynamic import.
  * The module is cached after first load.
  *
- * @returns {Object} The roaring module exports
+ * @returns {any} The roaring module exports
  * @throws {Error} If the roaring package is not installed or fails to load
  * @private
  */
@@ -151,7 +151,7 @@ export function getRoaringBitmap32() {
  */
 export function getNativeRoaringAvailable() {
   if (nativeAvailability !== NOT_CHECKED) {
-    return nativeAvailability;
+    return /** @type {boolean|null} */ (nativeAvailability);
   }
 
   try {
@@ -161,13 +161,13 @@ export function getNativeRoaringAvailable() {
     // Try the method-based API first (roaring >= 2.x)
     if (typeof RoaringBitmap32.isNativelyInstalled === 'function') {
       nativeAvailability = RoaringBitmap32.isNativelyInstalled();
-      return nativeAvailability;
+      return /** @type {boolean|null} */ (nativeAvailability);
     }
 
     // Fall back to property-based API (roaring 1.x)
     if (roaring.isNativelyInstalled !== undefined) {
       nativeAvailability = roaring.isNativelyInstalled;
-      return nativeAvailability;
+      return /** @type {boolean|null} */ (nativeAvailability);
     }
 
     // Could not determine - leave as null (indeterminate)

package/src/domain/utils/seekCacheKey.js

@@ -0,0 +1,32 @@
+/**
+ * Deterministic cache key for seek materialization cache.
+ *
+ * Key format: `v1:t<ceiling>-<frontierHash>`
+ * where frontierHash = hex SHA-256 of sorted writerId:tipSha pairs.
+ *
+ * The `v1` prefix ensures future schema/codec changes produce distinct keys
+ * without needing to flush existing caches.
+ *
+ * @module domain/utils/seekCacheKey
+ */
+
+import { createHash } from 'node:crypto';
+
+const KEY_VERSION = 'v1';
+
+/**
+ * Builds a deterministic, collision-resistant cache key from a ceiling tick
+ * and writer frontier snapshot.
+ *
+ * @param {number} ceiling - Lamport ceiling tick
+ * @param {Map<string, string>} frontier - Map of writerId → tip SHA
+ * @returns {string} Cache key, e.g. `v1:t42-a1b2c3d4...` (32+ hex chars in hash)
+ */
+export function buildSeekCacheKey(ceiling, frontier) {
+  const sorted = [...frontier.entries()].sort((a, b) =>
+    a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0
+  );
+  const payload = sorted.map(([w, sha]) => `${w}:${sha}`).join('\n');
+  const hash = createHash('sha256').update(payload).digest('hex');
+  return `${KEY_VERSION}:t${ceiling}-${hash}`;
+}

package/src/domain/warp/PatchSession.js

@@ -21,7 +21,7 @@ export class PatchSession {
    *
    * @param {Object} options
    * @param {import('../services/PatchBuilderV2.js').PatchBuilderV2} options.builder - Internal builder
-   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
+   * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default} options.persistence - Git adapter
    * @param {string} options.graphName - Graph namespace
    * @param {string} options.writerId - Writer ID
    * @param {string|null} options.expectedOldHead - Expected parent SHA for CAS
@@ -30,7 +30,7 @@ export class PatchSession {
     /** @type {import('../services/PatchBuilderV2.js').PatchBuilderV2} */
     this._builder = builder;
 
-    /** @type {import('../../ports/GraphPersistencePort.js').default} */
+    /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default} */
     this._persistence = persistence;
 
     /** @type {string} */
@@ -176,7 +176,7 @@ export class PatchSession {
       const sha = await this._builder.commit();
       this._committed = true;
       return sha;
-    } catch (err) {
+    } catch (/** @type {any} */ err) { // TODO(ts-cleanup): type error
       // Check if it's a concurrent commit error from PatchBuilderV2
       if (err.message?.includes('Concurrent commit detected') ||
           err.message?.includes('has advanced')) {

package/src/domain/warp/Writer.js

@@ -36,7 +36,7 @@ export class Writer {
    * Creates a new Writer instance.
    *
    * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
+   * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Git adapter
    * @param {string} options.graphName - Graph namespace
    * @param {string} options.writerId - This writer's ID
    * @param {import('../crdt/VersionVector.js').VersionVector} options.versionVector - Current version vector
@@ -48,7 +48,7 @@ export class Writer {
   constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec }) {
     validateWriterId(writerId);
 
-    /** @type {import('../../ports/GraphPersistencePort.js').default} */
+    /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} */
     this._persistence = persistence;
 
     /** @type {string} */

package/src/infrastructure/adapters/BunHttpAdapter.js

@@ -50,9 +50,10 @@ async function readStreamBody(bodyStream) {
  * HttpServerPort request handlers.
  *
  * @param {Request} request - Bun fetch Request
- * @returns {Promise<{ method: string, url: string, headers: Object, body: Buffer|undefined }>}
+ * @returns {Promise<{ method: string, url: string, headers: Record<string, string>, body: Uint8Array|undefined }>}
  */
 async function toPortRequest(request) {
+  /** @type {Record<string, string>} */
   const headers = {};
   request.headers.forEach((value, key) => {
     headers[key] = value;
@@ -81,11 +82,11 @@ async function toPortRequest(request) {
 /**
  * Converts a plain-object port response into a Bun Response.
  *
- * @param {{ status?: number, headers?: Object, body?: string|Uint8Array }} portResponse
+ * @param {{ status?: number, headers?: Record<string, string>, body?: string|Uint8Array|null }} portResponse
  * @returns {Response}
  */
 function toResponse(portResponse) {
-  return new Response(portResponse.body ?? null, {
+  return new Response(/** @type {BodyInit | null} */ (portResponse.body ?? null), {
     status: portResponse.status || 200,
     headers: portResponse.headers || {},
   });
@@ -105,7 +106,7 @@ function createFetchHandler(requestHandler, logger) {
       const portReq = await toPortRequest(request);
       const portRes = await requestHandler(portReq);
       return toResponse(portRes);
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (err.status === 413) {
         return new Response(PAYLOAD_TOO_LARGE, {
           status: 413,
@@ -131,11 +132,12 @@ function createFetchHandler(requestHandler, logger) {
  * Note: Bun.serve() is synchronous, so cb fires on the same tick
  * (unlike Node's server.listen which defers via the event loop).
  *
- * @param {{ port: number, hostname?: string, fetch: Function }} serveOptions
+ * @param {*} serveOptions
  * @param {Function|undefined} cb - Node-style callback
- * @returns {Object} The Bun server instance
+ * @returns {*} The Bun server instance
  */
 function startServer(serveOptions, cb) {
+  // @ts-expect-error — Bun global is only available in Bun runtime
   const server = globalThis.Bun.serve(serveOptions);
   if (cb) {
     cb(null);
@@ -146,7 +148,7 @@ function startServer(serveOptions, cb) {
 /**
  * Safely stops a Bun server, forwarding errors to the callback.
  *
- * @param {{ server: Object|null }} state - Shared mutable state
+ * @param {{ server: * }} state - Shared mutable state
  * @param {Function} [callback]
  */
 function stopServer(state, callback) {
@@ -184,15 +186,25 @@ export default class BunHttpAdapter extends HttpServerPort {
     this._logger = logger || noopLogger;
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Function} requestHandler
+   * @returns {{ listen: Function, close: Function, address: Function }}
+   */
   createServer(requestHandler) {
     const fetchHandler = createFetchHandler(requestHandler, this._logger);
+    /** @type {{ server: * }} */
     const state = { server: null };
 
     return {
+      /**
+       * @param {number} port
+       * @param {string|Function} [host]
+       * @param {Function} [callback]
+       */
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
         const bindHost = typeof host === 'string' ? host : undefined;
+        /** @type {*} */ // TODO(ts-cleanup): type Bun.serve options
         const serveOptions = { port, fetch: fetchHandler };
 
         if (bindHost !== undefined) {
@@ -208,6 +220,7 @@ export default class BunHttpAdapter extends HttpServerPort {
         }
       },
 
+      /** @param {Function} [callback] */
       close: (callback) => stopServer(state, callback),
 
       address() {