@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/utils/parseCursorBlob.js

@@ -5,13 +5,13 @@
  */
 
 /**
- * Parses and validates a cursor blob (Buffer) into a cursor object.
+ * Parses and validates a cursor blob (Uint8Array) 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 {Uint8Array} 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 }}
@@ -23,13 +23,13 @@
  *   Infinity
  *
  * @example
- * const buf = Buffer.from('{"tick":5,"mode":"lamport"}', 'utf8');
+ * const buf = new TextEncoder().encode('{"tick":5,"mode":"lamport"}');
  * 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');
+ * parseCursorBlob(new TextEncoder().encode('not json'), 'active cursor');
  */
 export function parseCursorBlob(buf, label) {
   let obj;

package/src/domain/warp/PatchSession.js

@@ -19,12 +19,7 @@ export class PatchSession {
   /**
    * Creates a new PatchSession.
    *
-   * @param {Object} options
-   * @param {import('../services/PatchBuilderV2.js').PatchBuilderV2} options.builder - Internal builder
-   * @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
+   * @param {{ builder: import('../services/PatchBuilderV2.js').PatchBuilderV2, persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default, graphName: string, writerId: string, expectedOldHead: string|null }} options
    */
   constructor({ builder, persistence, graphName, writerId, expectedOldHead }) {
     /** @type {import('../services/PatchBuilderV2.js').PatchBuilderV2} */
@@ -152,7 +147,7 @@ export class PatchSession {
    * Attaches content to a node.
    *
    * @param {string} nodeId - The node ID to attach content to
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
    * @throws {WriterError} SESSION_COMMITTED if already committed
    */
@@ -168,7 +163,7 @@ export class PatchSession {
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
    * @throws {WriterError} SESSION_COMMITTED if already committed
    */

package/src/domain/warp/Writer.js

@@ -15,6 +15,7 @@
  */
 
 import defaultCodec from '../utils/defaultCodec.js';
+import nullLogger from '../utils/nullLogger.js';
 import { validateWriterId, buildWriterRef } from '../utils/RefLayout.js';
 import { PatchSession } from './PatchSession.js';
 import { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
@@ -35,17 +36,9 @@ export class Writer {
   /**
    * Creates a new Writer instance.
    *
-   * @param {Object} options
-   * @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
-   * @param {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} options.getCurrentState - Async function returning the current materialized V5 state
-   * @param {(result: {patch: Object, sha: string}) => void | Promise<void>} [options.onCommitSuccess] - Callback invoked after successful commit with { patch, sha }
-   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
+   * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default, graphName: string, writerId: string, versionVector: import('../crdt/VersionVector.js').VersionVector, getCurrentState: () => import('../services/JoinReducer.js').WarpStateV5 | null, onCommitSuccess?: (result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>, onDeleteWithData?: 'reject'|'cascade'|'warn', codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
-  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec }) {
+  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec, logger }) {
     validateWriterId(writerId);
 
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} */
@@ -60,10 +53,10 @@ export class Writer {
     /** @type {import('../crdt/VersionVector.js').VersionVector} */
     this._versionVector = versionVector;
 
-    /** @type {Function} */
+    /** @type {() => import('../services/JoinReducer.js').WarpStateV5 | null} */
     this._getCurrentState = getCurrentState;
 
-    /** @type {Function|undefined} */
+    /** @type {((result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>)|undefined} */
     this._onCommitSuccess = onCommitSuccess;
 
     /** @type {'reject'|'cascade'|'warn'} */
@@ -72,6 +65,9 @@ export class Writer {
     /** @type {import('../../ports/CodecPort.js').default|undefined} */
     this._codec = codec || defaultCodec;
 
+    /** @type {import('../../ports/LoggerPort.js').default} */
+    this._logger = logger || nullLogger;
+
     /** @type {boolean} */
     this._commitInProgress = false;
   }
@@ -151,6 +147,7 @@ export class Writer {
       onCommitSuccess: this._onCommitSuccess,
       onDeleteWithData: this._onDeleteWithData,
       codec: this._codec,
+      logger: this._logger,
     });
 
     // Return PatchSession wrapping the builder

package/src/domain/warp/_wire.js

@@ -14,8 +14,8 @@
  * become method names on the prototype. Duplicates across modules are
  * detected eagerly and throw at import time (not at call time).
  *
- * @param {Function} Class - The class constructor whose prototype to extend
- * @param {Array<Record<string, Function>>} methodModules - Array of method module namespace objects
+ * @param {{ prototype: object, name: string }} Class - The class constructor whose prototype to extend
+ * @param {Array<Record<string, unknown>>} methodModules - Array of method module namespace objects
  * @throws {Error} If a method name appears in more than one module
  */
 export function wireWarpMethods(Class, methodModules) {

package/src/domain/warp/_wiredMethods.d.ts

@@ -179,13 +179,11 @@ declare module '../WarpGraph.js' {
     // ── provenance.methods.js ─────────────────────────────────────────────
     patchesFor(entityId: string): Promise<string[]>;
     materializeSlice(nodeId: string, options?: { receipts?: boolean }): Promise<{ state: WarpStateV5; patchCount: number; receipts?: TickReceipt[] }>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- internal method; `any` avoids breaking provenance.methods.js callers
-    _computeBackwardCone(nodeId: string): Promise<Map<string, any>>;
-    loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
-    _loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
+    _computeBackwardCone(nodeId: string): Promise<Map<string, PatchV2>>;
+    loadPatchBySha(sha: string): Promise<PatchV2>;
+    _loadPatchBySha(sha: string): Promise<PatchV2>;
     _loadPatchesBySha(shas: string[]): Promise<Array<{ patch: PatchV2; sha: string }>>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- internal method; `any` avoids breaking provenance.methods.js callers
-    _sortPatchesCausally(patches: Array<{ patch: any; sha: string }>): Array<{ patch: any; sha: string }>;
+    _sortPatchesCausally(patches: Array<{ patch: PatchV2; sha: string }>): Array<{ patch: PatchV2; sha: string }>;
 
     // ── fork.methods.js ───────────────────────────────────────────────────
     fork(options: { from: string; at: string; forkName?: string; forkWriterId?: string }): Promise<WarpGraph>;
@@ -251,7 +249,7 @@ declare module '../WarpGraph.js' {
     _buildView(state: WarpStateV5, stateHash: string, diff?: import('../types/PatchDiff.js').PatchDiff): void;
     _setMaterializedState(state: WarpStateV5, optionsOrDiff?: import('../types/PatchDiff.js').PatchDiff | { diff?: import('../types/PatchDiff.js').PatchDiff | null }): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
     _materializeWithCeiling(ceiling: number, collectReceipts: boolean, t0: number): Promise<WarpStateV5 | { state: WarpStateV5; receipts: TickReceipt[] }>;
-    _persistSeekCacheEntry(cacheKey: string, buf: Buffer, state: WarpStateV5): Promise<void>;
+    _persistSeekCacheEntry(cacheKey: string, buf: Uint8Array, state: WarpStateV5): Promise<void>;
     _restoreIndexFromCache(indexTreeOid: string): Promise<void>;
     materializeAt(checkpointSha: string): Promise<WarpStateV5>;
     verifyIndex(options?: { seed?: number; sampleRate?: number }): { passed: number; failed: number; errors: Array<{ nodeId: string; direction: string; expected: string[]; actual: string[] }> };

package/src/domain/warp/checkpoint.methods.js

@@ -375,7 +375,7 @@ export function _maybeRunGC(state) {
  * **Requires a cached state.**
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {{ran: boolean, result: Object|null, reasons: string[]}} GC result
+ * @returns {{ran: boolean, result: import('../services/GCPolicy.js').GCExecuteResult|null, reasons: string[]}} GC result
  *
  * @example
  * await graph.materialize();

package/src/domain/warp/fork.methods.js

@@ -31,11 +31,7 @@ import { createWormhole as createWormholeImpl } from '../services/WormholeServic
  * - History up to the fork point is shared (content-addressed dedup)
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} options - Fork configuration
- * @param {string} options.from - Writer ID whose chain to fork from
- * @param {string} options.at - Patch SHA to fork at (must be in the writer's chain)
- * @param {string} [options.forkName] - Name for the forked graph. Defaults to `<graphName>-fork-<timestamp>`
- * @param {string} [options.forkWriterId] - Writer ID for the fork. Defaults to a new canonical ID.
+ * @param {{ from: string, at: string, forkName?: string, forkWriterId?: string }} options - Fork configuration
  * @returns {Promise<import('../WarpGraph.js').default>} A new WarpGraph instance for the fork
  * @throws {ForkError} If `from` writer does not exist (code: `E_FORK_WRITER_NOT_FOUND`)
  * @throws {ForkError} If `at` SHA does not exist (code: `E_FORK_PATCH_NOT_FOUND`)
@@ -104,7 +100,7 @@ export async function fork({ from, at, forkName, forkWriterId }) {
 
     // 4. Generate or validate fork name (add random suffix to prevent collisions)
     const resolvedForkName =
-      forkName ?? `${this._graphName}-fork-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+      forkName ?? `${this._graphName}-fork-${Math.random().toString(36).slice(2, 10).padEnd(8, '0')}`;
     try {
       validateGraphName(resolvedForkName);
     } catch (err) {

package/src/domain/warp/materializeAdvanced.methods.js

@@ -351,7 +351,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
       cacheKey = buildSeekCacheKey(ceiling, frontier);
     }
     const buf = serializeFullStateV5(state, { codec: this._codec });
-    this._persistSeekCacheEntry(cacheKey, /** @type {Buffer} */ (buf), state)
+    this._persistSeekCacheEntry(cacheKey, buf, state)
       .catch(() => {});
   }
 
@@ -377,7 +377,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} cacheKey - Seek cache key
- * @param {Buffer} buf - Serialized WarpStateV5 buffer
+ * @param {Uint8Array} buf - Serialized WarpStateV5 buffer
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
  * @returns {Promise<void>}
  * @private
@@ -473,7 +473,7 @@ export async function materializeAt(checkpointSha) {
 
       const patchMeta = decodePatchMessage(message);
       const patchBuffer = await this._persistence.readBlob(patchMeta.patchOid);
-      const patch = this._codec.decode(patchBuffer);
+      const patch = /** @type {import('../types/WarpTypesV2.js').PatchV2} */ (this._codec.decode(patchBuffer));
 
       patches.push({ patch, sha: currentSha });
 

package/src/domain/warp/patch.methods.js

@@ -287,10 +287,11 @@ export async function writer(writerId) {
     graphName: this._graphName,
     writerId: resolvedWriterId,
     versionVector: this._versionVector,
-    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
+    getCurrentState: () => this._cachedState,
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts))),
+    onCommitSuccess: /** @type {(result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts)),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }
 
@@ -303,9 +304,7 @@ export async function writer(writerId) {
  *
  * @deprecated Use `writer()` to resolve a stable ID from git config, or `writer(id)` with an explicit ID.
  * @this {import('../WarpGraph.js').default}
- * @param {Object} [opts]
- * @param {'config'|'none'} [opts.persist='none'] - Whether to persist the new ID to git config
- * @param {string} [opts.alias] - Optional alias for config key (used with persist:'config')
+ * @param {{ persist?: 'config'|'none', alias?: string }} [opts]
  * @returns {Promise<Writer>} A Writer instance with new canonical ID
  * @throws {Error} If config operations fail (when persist:'config')
  *
@@ -345,10 +344,11 @@ export async function createWriter(opts = {}) {
     graphName: this._graphName,
     writerId: freshWriterId,
     versionVector: this._versionVector,
-    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
+    getCurrentState: () => this._cachedState,
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts))),
+    onCommitSuccess: /** @type {(result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts)),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }
 
@@ -482,7 +482,7 @@ export async function discoverTicks() {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} otherState - The state to merge in
- * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: Object}} Merged state and receipt
+ * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: {nodesAdded: number, nodesRemoved: number, edgesAdded: number, edgesRemoved: number, propsChanged: number, frontierMerged: boolean}}} Merged state and receipt
  * @throws {QueryError} If no cached state exists (code: `E_NO_STATE`)
  * @throws {Error} If otherState is invalid
  */

package/src/domain/warp/provenance.methods.js

@@ -152,7 +152,7 @@ export async function materializeSlice(nodeId, options) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} nodeId - The target node ID
- * @returns {Promise<Map<string, Object>>} Map of patch SHA to loaded patch object
+ * @returns {Promise<Map<string, import('../types/WarpTypesV2.js').PatchV2>>} Map of patch SHA to loaded patch object
  */
 export async function _computeBackwardCone(nodeId) {
   if (!this._provenanceIndex) {
@@ -209,7 +209,7 @@ export async function _computeBackwardCone(nodeId) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} sha - The patch commit SHA
- * @returns {Promise<Object>} The decoded patch object
+ * @returns {Promise<import('../types/WarpTypesV2.js').PatchV2>} The decoded patch object
  * @throws {Error} If the commit is not a patch or loading fails
  */
 export async function loadPatchBySha(sha) {
@@ -221,7 +221,7 @@ export async function loadPatchBySha(sha) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} sha - The patch commit SHA
- * @returns {Promise<Object>} The decoded patch object
+ * @returns {Promise<import('../types/WarpTypesV2.js').PatchV2>} The decoded patch object
  * @throws {Error} If the commit is not a patch or loading fails
  */
 export async function _loadPatchBySha(sha) {
@@ -234,7 +234,7 @@ export async function _loadPatchBySha(sha) {
 
   const patchMeta = decodePatchMessage(nodeInfo.message);
   const patchBuffer = await this._persistence.readBlob(patchMeta.patchOid);
-  return /** @type {Object} */ (this._codec.decode(patchBuffer));
+  return /** @type {import('../types/WarpTypesV2.js').PatchV2} */ (this._codec.decode(patchBuffer));
 }
 
 /**
@@ -242,7 +242,7 @@ export async function _loadPatchBySha(sha) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string[]} shas - Array of patch commit SHAs
- * @returns {Promise<Array<{patch: Object, sha: string}>>} Array of patch entries
+ * @returns {Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>} Array of patch entries
  * @throws {Error} If any SHA is not a patch or loading fails
  */
 export async function _loadPatchesBySha(shas) {

package/src/domain/warp/query.methods.js

@@ -311,10 +311,7 @@ export function query() {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} name - Observer name
- * @param {Object} config - Observer configuration
- * @param {string|string[]} config.match - Glob pattern(s) for visible nodes
- * @param {string[]} [config.expose] - Property keys to include
- * @param {string[]} [config.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} config - Observer configuration
  * @returns {Promise<import('../services/ObserverView.js').default>} A read-only observer view
  */
 export async function observer(name, config) {
@@ -331,14 +328,8 @@ export async function observer(name, config) {
  * Computes the directed MDL translation cost from observer A to observer B.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} configA - Observer configuration for A
- * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configA.expose] - Property keys to include
- * @param {string[]} [configA.redact] - Property keys to exclude
- * @param {Object} configB - Observer configuration for B
- * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configB.expose] - Property keys to include
- * @param {string[]} [configB.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configA - Observer configuration for A
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configB - Observer configuration for B
  * @returns {Promise<{cost: number, breakdown: {nodeLoss: number, edgeLoss: number, propLoss: number}}>}
  */
 export async function translationCost(configA, configB) {
@@ -368,12 +359,12 @@ export async function getContentOid(nodeId) {
 /**
  * Gets the content blob for a node, or null if none is attached.
  *
- * Returns the raw Buffer from `readBlob()`. Consumers wanting text
- * should call `.toString('utf8')` on the result.
+ * Returns the raw bytes from `readBlob()`. Consumers wanting text
+ * should decode the result with `new TextDecoder().decode(buf)`.
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} nodeId - The node ID to get content for
- * @returns {Promise<Buffer|null>} Content buffer or null
+ * @returns {Promise<Uint8Array|null>} Content bytes or null
  * @throws {Error} If the referenced blob OID is not in the object store
  *   (e.g., garbage-collected despite anchoring). Callers should handle this
  *   if operating on repos with aggressive GC or partial clones.
@@ -409,14 +400,14 @@ export async function getEdgeContentOid(from, to, label) {
 /**
  * Gets the content blob for an edge, or null if none is attached.
  *
- * Returns the raw Buffer from `readBlob()`. Consumers wanting text
- * should call `.toString('utf8')` on the result.
+ * Returns the raw bytes from `readBlob()`. Consumers wanting text
+ * should decode the result with `new TextDecoder().decode(buf)`.
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} from - Source node ID
  * @param {string} to - Target node ID
  * @param {string} label - Edge label
- * @returns {Promise<Buffer|null>} Content buffer or null
+ * @returns {Promise<Uint8Array|null>} Content bytes or null
  * @throws {Error} If the referenced blob OID is not in the object store
  *   (e.g., garbage-collected despite anchoring). Callers should handle this
  *   if operating on repos with aggressive GC or partial clones.

package/src/domain/warp/subscribe.methods.js

@@ -22,10 +22,7 @@ import { matchGlob } from '../utils/matchGlob.js';
  * One handler's error does not prevent other handlers from being called.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} options - Subscription options
- * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with diff when graph changes
- * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
- * @param {boolean} [options.replay=false] - If true, immediately fires onChange with initial state diff
+ * @param {{ onChange: (diff: import('../services/StateDiff.js').StateDiffResult) => void, onError?: (error: unknown) => void, replay?: boolean }} options - Subscription options
  * @returns {{unsubscribe: () => void}} Subscription handle
  * @throws {Error} If onChange is not a function
  *
@@ -103,10 +100,7 @@ export function subscribe({ onChange, onError, replay = false }) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string|string[]} pattern - Glob pattern(s) (e.g., 'user:*', 'order:123', '*')
- * @param {Object} options - Watch options
- * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with filtered diff when matching changes occur
- * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
- * @param {number} [options.poll] - Poll interval in ms (min 1000); checks frontier and auto-materializes
+ * @param {{ onChange: (diff: import('../services/StateDiff.js').StateDiffResult) => void, onError?: (error: unknown) => void, poll?: number }} options - Watch options
  * @returns {{unsubscribe: () => void}} Subscription handle
  * @throws {Error} If pattern is not a string or array of strings
  * @throws {Error} If onChange is not a function

package/src/globals.d.ts

@@ -62,3 +62,10 @@ interface BunServeOptions {
 declare namespace Bun {
   function serve(options: BunServeOptions): BunServer;
 }
+
+/* ------------------------------------------------------------------ */
+/*  globalThis augmentation                                           */
+/* ------------------------------------------------------------------ */
+
+declare var Bun: typeof Bun | undefined;
+declare var Deno: typeof Deno | undefined;

package/src/infrastructure/adapters/BunHttpAdapter.js

@@ -96,8 +96,8 @@ function toResponse(portResponse) {
  * Creates the Bun fetch handler that bridges between Request/Response
  * and the HttpServerPort plain-object contract.
  *
- * @param {Function} requestHandler - Port-style async handler
- * @param {{ error: Function }} logger
+ * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler - Port-style async handler
+ * @param {{ error: (...args: unknown[]) => void }} logger
  * @returns {(request: Request) => Promise<Response>}
  */
 function createFetchHandler(requestHandler, logger) {
@@ -125,10 +125,6 @@ function createFetchHandler(requestHandler, logger) {
   };
 }
 
-/**
- * @typedef {{ hostname: string, port: number, stop: (closeActiveConnections?: boolean) => Promise<void> }} BunServer
- */
-
 /**
  * Starts a Bun server and invokes the callback with (null) on success
  * or (err) on failure.
@@ -137,7 +133,7 @@ function createFetchHandler(requestHandler, logger) {
  * (unlike Node's server.listen which defers via the event loop).
  *
  * @param {BunServeOptions} serveOptions
- * @param {Function|undefined} cb - Node-style callback
+ * @param {((err: Error | null) => void) | undefined} cb - Node-style callback
  * @returns {BunServer} The Bun server instance
  */
 function startServer(serveOptions, cb) {
@@ -152,7 +148,7 @@ function startServer(serveOptions, cb) {
  * Safely stops a Bun server, forwarding errors to the callback.
  *
  * @param {{ server: BunServer | null }} state - Shared mutable state
- * @param {Function} [callback]
+ * @param {(err?: Error) => void} [callback]
  */
 function stopServer(state, callback) {
   try {
@@ -165,9 +161,9 @@ function stopServer(state, callback) {
     if (callback) {
       callback();
     }
-  } catch (err) {
+  } catch (/** @type {unknown} */ err) {
     if (callback) {
-      callback(err);
+      callback(err instanceof Error ? err : new Error(String(err)));
     }
   }
 }
@@ -184,7 +180,7 @@ const noopLogger = { error() {} };
  */
 export default class BunHttpAdapter extends HttpServerPort {
   /**
-   * @param {{ logger?: { error: Function } }} [options]
+   * @param {{ logger?: { error: (...args: unknown[]) => void } }} [options]
    */
   constructor({ logger } = {}) {
     super();
@@ -192,8 +188,8 @@ export default class BunHttpAdapter extends HttpServerPort {
   }
 
   /**
-   * @param {Function} requestHandler
-   * @returns {{ listen: Function, close: Function, address: Function }}
+   * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+   * @returns {import('../../ports/HttpServerPort.js').HttpServerHandle}
    */
   createServer(requestHandler) {
     const fetchHandler = createFetchHandler(requestHandler, this._logger);
@@ -203,8 +199,8 @@ export default class BunHttpAdapter extends HttpServerPort {
     return {
       /**
        * @param {number} port
-       * @param {string|Function} [host]
-       * @param {Function} [callback]
+       * @param {string|((err?: Error | null) => void)} [host]
+       * @param {(err?: Error | null) => void} [callback]
        */
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
@@ -218,14 +214,14 @@ export default class BunHttpAdapter extends HttpServerPort {
 
         try {
           state.server = startServer(serveOptions, cb);
-        } catch (err) {
+        } catch (/** @type {unknown} */ err) {
           if (cb) {
-            cb(err);
+            cb(err instanceof Error ? err : new Error(String(err)));
           }
         }
       },
 
-      /** @param {Function} [callback] */
+      /** @param {(err?: Error) => void} [callback] */
       close: (callback) => stopServer(state, callback),
 
       address() {

package/src/infrastructure/adapters/ConsoleLogger.js

@@ -46,10 +46,7 @@ const LEVEL_NAMES = Object.freeze({
 export default class ConsoleLogger extends LoggerPort {
   /**
    * Creates a new ConsoleLogger instance.
-   * @param {Object} [options] - Logger options
-   * @param {number} [options.level=LogLevel.INFO] - Minimum log level to output
-   * @param {Record<string, unknown>} [options.context={}] - Base context for all log entries
-   * @param {function(): string} [options.timestampFn] - Custom timestamp function (defaults to ISO string)
+   * @param {{ level?: number | string, context?: Record<string, unknown>, timestampFn?: function(): string }} [options] - Logger options
    */
   constructor({ level = LogLevel.INFO, context = {}, timestampFn } = {}) {
     super();
@@ -114,11 +111,7 @@ export default class ConsoleLogger extends LoggerPort {
 
   /**
    * Internal logging implementation.
-   * @param {Object} opts - Log options
-   * @param {number} opts.level - Numeric log level
-   * @param {string} opts.levelName - String representation of level
-   * @param {string} opts.message - Log message
-   * @param {Record<string, unknown>} [opts.context] - Additional context
+   * @param {{ level: number, levelName: string, message: string, context?: Record<string, unknown> }} opts - Log options
    * @private
    */
   _log({ level, levelName, message, context }) {

package/src/infrastructure/adapters/DenoHttpAdapter.js

@@ -90,8 +90,8 @@ function toDenoResponse(plain) {
  * Creates a Deno.serve-compatible handler that bridges to the
  * HttpServerPort request handler contract.
  *
- * @param {Function} requestHandler
- * @param {{ error: Function }} logger
+ * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+ * @param {{ error: (...args: unknown[]) => void }} logger
  * @returns {(request: Request) => Promise<Response>}
  */
 function createHandler(requestHandler, logger) {
@@ -123,8 +123,8 @@ function createHandler(requestHandler, logger) {
 /**
  * Gracefully shuts down the Deno HTTP server.
  *
- * @param {{ server: *}} state - Shared mutable state `{ server }`
- * @param {Function} [callback]
+ * @param {{ server: { shutdown: () => Promise<void> } | null }} state - Shared mutable state `{ server }`
+ * @param {(err?: Error) => void} [callback]
  */
 function closeImpl(state, callback) {
   if (!state.server) {
@@ -143,7 +143,7 @@ function closeImpl(state, callback) {
     /** @param {unknown} err */ (err) => {
       state.server = null;
       if (callback) {
-        callback(err);
+        callback(err instanceof Error ? err : new Error(String(err)));
       }
     }
   );
@@ -152,7 +152,7 @@ function closeImpl(state, callback) {
 /**
  * Returns the server's bound address info.
  *
- * @param {{ server: * }} state - Shared mutable state `{ server }`
+ * @param {{ server: { addr: { transport: string, hostname: string, port: number } } | null }} state - Shared mutable state `{ server }`
  * @returns {{ address: string, port: number, family: string }|null}
  */
 function addressImpl(state) {
@@ -183,7 +183,7 @@ const noopLogger = { error() {} };
  */
 export default class DenoHttpAdapter extends HttpServerPort {
   /**
-   * @param {{ logger?: { error: Function } }} [options]
+   * @param {{ logger?: { error: (...args: unknown[]) => void } }} [options]
    */
   constructor({ logger } = {}) {
     super();
@@ -191,19 +191,19 @@ export default class DenoHttpAdapter extends HttpServerPort {
   }
 
   /**
-   * @param {Function} requestHandler
-   * @returns {{ listen: Function, close: Function, address: Function }}
+   * @param {(request: import('../../ports/HttpServerPort.js').HttpRequest) => Promise<import('../../ports/HttpServerPort.js').HttpResponse>} requestHandler
+   * @returns {import('../../ports/HttpServerPort.js').HttpServerHandle}
    */
   createServer(requestHandler) {
     const handler = createHandler(requestHandler, this._logger);
-    /** @type {{ server: * }} */
+    /** @type {{ server: { shutdown: () => Promise<void>, addr: { transport: string, hostname: string, port: number } } | null }} */
     const state = { server: null };
 
     return {
       /**
        * @param {number} port
-       * @param {string|Function} [host]
-       * @param {Function} [callback]
+       * @param {string|((err?: Error | null) => void)} [host]
+       * @param {(err?: Error | null) => void} [callback]
        */
       listen: (port, host, callback) => {
         const cb = typeof host === 'function' ? host : callback;
@@ -224,15 +224,15 @@ export default class DenoHttpAdapter extends HttpServerPort {
           }
 
           state.server = globalThis.Deno.serve(serveOptions, handler);
-        } catch (err) {
+        } catch (/** @type {unknown} */ err) {
           if (cb) {
-            cb(err);
+            cb(err instanceof Error ? err : new Error(String(err)));
           } else {
             throw err;
           }
         }
       },
-      /** @param {Function} [callback] */
+      /** @param {(err?: Error) => void} [callback] */
       close: (callback) => {
         closeImpl(state, callback);
       },