@git-stunts/git-warp 10.1.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

@@ -8,6 +8,8 @@
  * - refs/warp/<graph>/writers/<writer_id>
  * - refs/warp/<graph>/checkpoints/head
  * - refs/warp/<graph>/coverage/head
+ * - refs/warp/<graph>/cursor/active
+ * - refs/warp/<graph>/cursor/saved/<name>
  *
  * @module domain/utils/RefLayout
  */
@@ -49,20 +51,22 @@ const PATH_TRAVERSAL_PATTERN = /\.\./;
  * Validates a graph name and throws if invalid.
  *
  * Graph names must not contain:
- * - Path traversal sequences (`../`)
+ * - Path traversal sequences (`..`)
  * - Semicolons (`;`)
  * - Spaces
  * - Null bytes (`\0`)
  * - Empty strings
  *
  * @param {string} name - The graph name to validate
- * @throws {Error} If the graph name is invalid
+ * @throws {Error} If the name is not a string, is empty, or contains
+ *   forbidden characters (`..`, `;`, space, `\0`)
  * @returns {void}
  *
  * @example
- * validateGraphName('events'); // OK
- * validateGraphName('../etc'); // throws
- * validateGraphName('my graph'); // throws
+ * validateGraphName('events');    // OK
+ * validateGraphName('team/proj'); // OK (slashes allowed)
+ * validateGraphName('../etc');    // throws — path traversal
+ * validateGraphName('my graph');  // throws — contains space
  */
 export function validateGraphName(name) {
   if (typeof name !== 'string') {
@@ -94,18 +98,20 @@ export function validateGraphName(name) {
  * Validates a writer ID and throws if invalid.
  *
  * Writer IDs must:
- * - Be ASCII ref-safe: only [A-Za-z0-9._-]
+ * - Be ASCII ref-safe: only `[A-Za-z0-9._-]`
  * - Be 1-64 characters long
  * - Not contain `/`, `..`, whitespace, or NUL
  *
  * @param {string} id - The writer ID to validate
- * @throws {Error} If the writer ID is invalid
+ * @throws {Error} If the ID is not a string, is empty, exceeds 64 characters,
+ *   or contains forbidden characters (`/`, `..`, whitespace, NUL, non-ASCII)
  * @returns {void}
  *
  * @example
- * validateWriterId('node-1'); // OK
- * validateWriterId('a/b'); // throws (contains /)
- * validateWriterId('x'.repeat(65)); // throws (too long)
+ * validateWriterId('node-1');        // OK
+ * validateWriterId('a/b');           // throws — contains forward slash
+ * validateWriterId('x'.repeat(65));  // throws — exceeds max length
+ * validateWriterId('has space');     // throws — contains whitespace
  */
 export function validateWriterId(id) {
   if (typeof id !== 'string') {
@@ -157,7 +163,7 @@ export function validateWriterId(id) {
  *
  * @param {string} graphName - The name of the graph
  * @param {string} writerId - The writer's unique identifier
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/writers/<writerId>`
  * @throws {Error} If graphName or writerId is invalid
  *
  * @example
@@ -174,7 +180,7 @@ export function buildWriterRef(graphName, writerId) {
  * Builds the checkpoint head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/checkpoints/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -190,7 +196,7 @@ export function buildCheckpointRef(graphName) {
  * Builds the coverage head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/coverage/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -204,10 +210,12 @@ export function buildCoverageRef(graphName) {
 
 /**
  * Builds the writers prefix path for the given graph.
- * Useful for listing all writer refs under a graph.
+ * Useful for listing all writer refs under a graph
+ * (e.g. via `git for-each-ref`).
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The writers prefix path
+ * @returns {string} The writers prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/writers/`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -219,6 +227,89 @@ export function buildWritersPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/writers/`;
 }
 
+/**
+ * Builds the active cursor ref path for the given graph.
+ *
+ * The active cursor is a single ref that stores the current time-travel
+ * position used by `git warp seek`. It points to a commit SHA representing
+ * the materialization frontier the user has seeked to.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/active`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorActiveRef('events');
+ * // => 'refs/warp/events/cursor/active'
+ */
+export function buildCursorActiveRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/cursor/active`;
+}
+
+/**
+ * Builds a saved (named) cursor ref path for the given graph and cursor name.
+ *
+ * Saved cursors are bookmarks created by `git warp seek --save <name>`.
+ * Each saved cursor persists a time-travel position that can be restored
+ * later without re-seeking.
+ *
+ * The cursor name is validated with the same rules as a writer ID
+ * (ASCII ref-safe: `[A-Za-z0-9._-]`, 1-64 characters).
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} name - The cursor bookmark name (validated like a writer ID)
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/saved/<name>`
+ * @throws {Error} If graphName or name is invalid
+ *
+ * @example
+ * buildCursorSavedRef('events', 'before-tui');
+ * // => 'refs/warp/events/cursor/saved/before-tui'
+ */
+export function buildCursorSavedRef(graphName, name) {
+  validateGraphName(graphName);
+  validateWriterId(name);
+  return `${REF_PREFIX}/${graphName}/cursor/saved/${name}`;
+}
+
+/**
+ * Builds the saved cursor prefix path for the given graph.
+ * Useful for listing all saved cursor bookmarks under a graph
+ * (e.g. via `git for-each-ref`).
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The saved cursor prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/cursor/saved/`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorSavedPrefix('events');
+ * // => 'refs/warp/events/cursor/saved/'
+ */
+export function buildCursorSavedPrefix(graphName) {
+  validateGraphName(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/parseCursorBlob.js

@@ -0,0 +1,51 @@
+/**
+ * Utilities for parsing seek-cursor blobs stored as Git refs.
+ *
+ * @module parseCursorBlob
+ */
+
+/**
+ * Parses and validates a cursor blob (Buffer) into a cursor object.
+ *
+ * The blob must contain UTF-8-encoded JSON representing a plain object with at
+ * minimum a finite numeric `tick` field.  Any additional fields (e.g. `mode`,
+ * `name`) are preserved in the returned object.
+ *
+ * @param {Buffer} buf - Raw blob contents (UTF-8 encoded JSON)
+ * @param {string} label - Human-readable label used in error messages
+ *   (e.g. `"active cursor"`, `"saved cursor 'foo'"`)
+ * @returns {{ tick: number, mode?: string, [key: string]: unknown }}
+ *   The validated cursor object.  `tick` is guaranteed to be a finite number.
+ * @throws {Error} If `buf` is not valid JSON
+ * @throws {Error} If the parsed value is not a plain JSON object (e.g. array,
+ *   null, or primitive)
+ * @throws {Error} If the `tick` field is missing, non-numeric, NaN, or
+ *   Infinity
+ *
+ * @example
+ * const buf = Buffer.from('{"tick":5,"mode":"lamport"}', 'utf8');
+ * const cursor = parseCursorBlob(buf, 'active cursor');
+ * // => { tick: 5, mode: 'lamport' }
+ *
+ * @example
+ * // Throws: "Corrupted active cursor: blob is not valid JSON"
+ * parseCursorBlob(Buffer.from('not json', 'utf8'), 'active cursor');
+ */
+export function parseCursorBlob(buf, label) {
+  let obj;
+  try {
+    obj = JSON.parse(new TextDecoder().decode(buf));
+  } catch {
+    throw new Error(`Corrupted ${label}: blob is not valid JSON`);
+  }
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`Corrupted ${label}: expected a JSON object`);
+  }
+
+  if (typeof obj.tick !== 'number' || !Number.isFinite(obj.tick)) {
+    throw new Error(`Corrupted ${label}: missing or invalid numeric tick`);
+  }
+
+  return obj;
+}

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() {