@git-stunts/git-warp 11.2.1 → 11.3.3

package/src/domain/services/HttpSyncServer.js

@@ -8,15 +8,56 @@
  * @module domain/services/HttpSyncServer
  */
 
+import { z } from 'zod';
 import SyncAuthService from './SyncAuthService.js';
 
 const DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
+const MAX_REQUEST_BYTES_CEILING = 128 * 1024 * 1024; // 134217728
+
+/**
+ * Zod schema for HttpSyncServer constructor options.
+ * @private
+ */
+const authSchema = z.object({
+  mode: z.enum(['enforce', 'log-only']).default('enforce'),
+  keys: z.record(z.string()).refine(
+    (obj) => Object.keys(obj).length > 0,
+    'auth.keys must not be empty',
+  ),
+  crypto: /** @type {z.ZodType<import('../../ports/CryptoPort.js').default>} */ (z.custom((v) => v === undefined || (typeof v === 'object' && v !== null))).optional(),
+  logger: /** @type {z.ZodType<import('../../ports/LoggerPort.js').default>} */ (z.custom((v) => v === undefined || (typeof v === 'object' && v !== null))).optional(),
+  wallClockMs: /** @type {z.ZodType<() => number>} */ (z.custom((v) => v === undefined || typeof v === 'function')).optional(),
+}).strict();
+
+const optionsSchema = z.object({
+  httpPort: /** @type {z.ZodType<import('../../ports/HttpServerPort.js').default>} */ (z.custom(
+    (v) => v !== null && v !== undefined && typeof v === 'object',
+    'httpPort must be a non-null object',
+  )),
+  graph: /** @type {z.ZodType<import('../WarpGraph.js').default>} */ (z.custom(
+    (v) => v !== null && v !== undefined && typeof v === 'object',
+    'graph must be a non-null object',
+  )),
+  maxRequestBytes: z.number().int().positive().max(MAX_REQUEST_BYTES_CEILING).default(DEFAULT_MAX_REQUEST_BYTES),
+  path: z.string().startsWith('/').default('/sync'),
+  host: z.string().min(1).default('127.0.0.1'),
+  auth: authSchema.optional(),
+  allowedWriters: z.array(z.string()).optional(),
+}).strict().superRefine((data, ctx) => {
+  if (data.allowedWriters && data.allowedWriters.length > 0 && !data.auth) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'allowedWriters requires auth.keys to be configured',
+      path: ['allowedWriters'],
+    });
+  }
+});
 
 /**
  * Recursively sorts object keys for deterministic JSON output.
  *
- * @param {*} value - Any JSON-serializable value
- * @returns {*} The canonicalized value with sorted object keys
+ * @param {unknown} value - Any JSON-serializable value
+ * @returns {unknown} The canonicalized value with sorted object keys
  * @private
  */
 function canonicalizeJson(value) {
@@ -24,10 +65,10 @@ function canonicalizeJson(value) {
     return value.map(canonicalizeJson);
   }
   if (value && typeof value === 'object') {
-    /** @type {{ [x: string]: * }} */
+    /** @type {{ [x: string]: unknown }} */
     const sorted = {};
     for (const key of Object.keys(value).sort()) {
-      sorted[key] = canonicalizeJson(/** @type {{ [x: string]: * }} */ (value)[key]);
+      sorted[key] = canonicalizeJson(/** @type {{ [x: string]: unknown }} */ (value)[key]);
     }
     return sorted;
   }
@@ -37,7 +78,7 @@ function canonicalizeJson(value) {
 /**
  * Produces a canonical JSON string with sorted keys.
  *
- * @param {*} value - Any JSON-serializable value
+ * @param {unknown} value - Any JSON-serializable value
  * @returns {string} Canonical JSON string
  * @private
  */
@@ -64,7 +105,7 @@ function errorResponse(status, message) {
 /**
  * Builds a JSON success response with canonical key ordering.
  *
- * @param {*} data - Response payload
+ * @param {unknown} data - Response payload
  * @returns {{ status: number, headers: Object, body: string }}
  * @private
  */
@@ -79,7 +120,7 @@ function jsonResponse(data) {
 /**
  * Validates that a sync request object has the expected shape.
  *
- * @param {*} parsed - Parsed JSON body
+ * @param {unknown} parsed - Parsed JSON body
  * @returns {boolean} True if valid
  * @private
  */
@@ -87,10 +128,11 @@ function isValidSyncRequest(parsed) {
   if (!parsed || typeof parsed !== 'object') {
     return false;
   }
-  if (parsed.type !== 'sync-request') {
+  const rec = /** @type {Record<string, unknown>} */ (parsed);
+  if (rec.type !== 'sync-request') {
     return false;
   }
-  if (!parsed.frontier || typeof parsed.frontier !== 'object' || Array.isArray(parsed.frontier)) {
+  if (!rec.frontier || typeof rec.frontier !== 'object' || Array.isArray(rec.frontier)) {
     return false;
   }
   return true;
@@ -160,7 +202,7 @@ function checkBodySize(body, maxBytes) {
  * Parses and validates the request body as a sync request.
  *
  * @param {Buffer|undefined} body
- * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: Object }}
+ * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
  * @private
  */
 function parseBody(body) {
@@ -183,19 +225,14 @@ function parseBody(body) {
 /**
  * Initializes auth service from config if present.
  *
- * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: *, logger?: *, wallClockMs?: () => number }|undefined} auth
+ * @param {z.infer<typeof authSchema>} [auth]
  * @param {string[]} [allowedWriters]
  * @returns {{ auth: SyncAuthService|null, authMode: string|null }}
  * @private
  */
 function initAuth(auth, allowedWriters) {
-  if (auth && auth.keys) {
-    const VALID_MODES = new Set(['enforce', 'log-only']);
-    const mode = auth.mode || 'enforce';
-    if (!VALID_MODES.has(mode)) {
-      throw new Error(`Invalid auth.mode: '${mode}'. Must be 'enforce' or 'log-only'.`);
-    }
-    return { auth: new SyncAuthService({ ...auth, allowedWriters }), authMode: mode };
+  if (auth) {
+    return { auth: new SyncAuthService({ ...auth, allowedWriters }), authMode: auth.mode };
   }
   return { auth: null, authMode: null };
 }
@@ -204,26 +241,35 @@ export default class HttpSyncServer {
   /**
    * @param {Object} options
    * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server port abstraction
-   * @param {{ processSyncRequest: (request: *) => Promise<*> }} options.graph - WarpGraph instance (must expose processSyncRequest)
+   * @param {{ processSyncRequest: Function }} options.graph - WarpGraph instance (must expose processSyncRequest)
    * @param {string} [options.path='/sync'] - URL path to handle sync requests on
    * @param {string} [options.host='127.0.0.1'] - Host to bind
    * @param {number} [options.maxRequestBytes=4194304] - Maximum request body size in bytes
    * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number }} [options.auth] - Auth configuration
    * @param {string[]} [options.allowedWriters] - Optional whitelist of allowed writer IDs
    */
-  constructor({ httpPort, graph, path = '/sync', host = '127.0.0.1', maxRequestBytes = DEFAULT_MAX_REQUEST_BYTES, auth, allowedWriters } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
-    this._httpPort = httpPort;
-    this._graph = graph;
-    this._path = path && path.startsWith('/') ? path : `/${path || 'sync'}`;
-    this._host = host;
-    this._maxRequestBytes = maxRequestBytes;
+  constructor(options) {
+    /** @type {z.infer<typeof optionsSchema>} */
+    let parsed;
+    try {
+      parsed = optionsSchema.parse(options);
+    } catch (err) {
+      if (err instanceof z.ZodError) {
+        const messages = err.issues.map((i) => i.message).join('; ');
+        throw new Error(`HttpSyncServer config: ${messages}`);
+      }
+      throw err;
+    }
+
+    this._httpPort = parsed.httpPort;
+    this._graph = parsed.graph;
+    this._path = parsed.path;
+    this._host = parsed.host;
+    this._maxRequestBytes = parsed.maxRequestBytes;
     this._server = null;
-    const authInit = initAuth(auth, allowedWriters);
+    const authInit = initAuth(parsed.auth, parsed.allowedWriters);
     this._auth = authInit.auth;
     this._authMode = authInit.authMode;
-    if (allowedWriters && !authInit.auth) {
-      throw new Error('allowedWriters requires auth.keys to be configured');
-    }
   }
 
   /**
@@ -234,7 +280,7 @@ export default class HttpSyncServer {
    * null so the request proceeds.
    *
    * @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request
-   * @param {*} parsed - Parsed sync request body
+   * @param {Record<string, unknown>} parsed - Parsed sync request body
    * @returns {Promise<{ status: number, headers: Object, body: string }|null>}
    * @private
    */
@@ -264,29 +310,31 @@ export default class HttpSyncServer {
     return null;
   }
 
-  /** @param {{ method: string, url: string, headers: { [x: string]: string }, body: Buffer|undefined }} request */
+  /** @param {{ method: string, url: string, headers: Object, body: Buffer|undefined }} request */
   async _handleRequest(request) {
-    const contentTypeError = checkContentType(request.headers);
+    /** @type {{ method: string, url: string, headers: Record<string, string>, body: Buffer|undefined }} */
+    const req = { ...request, headers: /** @type {Record<string, string>} */ (request.headers) };
+    const contentTypeError = checkContentType(req.headers);
     if (contentTypeError) {
       return contentTypeError;
     }
 
-    const routeError = validateRoute(request, this._path, this._host);
+    const routeError = validateRoute(req, this._path, this._host);
     if (routeError) {
       return routeError;
     }
 
-    const sizeError = checkBodySize(request.body, this._maxRequestBytes);
+    const sizeError = checkBodySize(req.body, this._maxRequestBytes);
     if (sizeError) {
       return sizeError;
     }
 
-    const { error, parsed } = parseBody(request.body);
+    const { error, parsed } = parseBody(req.body);
     if (error) {
       return error;
     }
 
-    const authError = await this._authorize(request, parsed);
+    const authError = await this._authorize(req, parsed);
     if (authError) {
       return authError;
     }
@@ -294,8 +342,8 @@ export default class HttpSyncServer {
     try {
       const response = await this._graph.processSyncRequest(parsed);
       return jsonResponse(response);
-    } catch (err) {
-      return errorResponse(500, /** @type {any} */ (err)?.message || 'Sync failed'); // TODO(ts-cleanup): type error
+    } catch (/** @type {unknown} */ err) {
+      return errorResponse(500, err instanceof Error ? err.message : 'Sync failed');
     }
   }
 
@@ -311,11 +359,14 @@ export default class HttpSyncServer {
       throw new Error('listen() requires a numeric port');
     }
 
-    const server = this._httpPort.createServer((/** @type {*} */ request) => this._handleRequest(request)); // TODO(ts-cleanup): type http callback
+    /** @type {{ listen: Function, close: Function, address: Function }} */
+    const server = this._httpPort.createServer(
+      (/** @type {{ method: string, url: string, headers: Object, body: Buffer|undefined }} */ request) => this._handleRequest(request),
+    );
     this._server = server;
 
     await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-      server.listen(port, this._host, (/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
+      server.listen(port, this._host, (/** @type {Error|null} */ err) => {
         if (err) {
           reject(err);
         } else {
@@ -332,7 +383,7 @@ export default class HttpSyncServer {
       url,
       close: () =>
         /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
-          server.close((/** @type {*} */ err) => { // TODO(ts-cleanup): type http callback
+          server.close((/** @type {Error|null} */ err) => {
             if (err) {
               reject(err);
             } else {

package/src/domain/services/IndexRebuildService.js

@@ -50,7 +50,7 @@ export default class IndexRebuildService {
    * @throws {Error} If graphService is not provided
    * @throws {Error} If storage adapter is not provided
    */
-  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {{ graphService: { iterateNodes: (opts: { ref: string, limit: number }) => AsyncIterable<{ sha: string, parents: string[] }> }, storage: import('../../ports/IndexStoragePort.js').default }} */ ({})) {
     if (!graphService) {
       throw new Error('IndexRebuildService requires a graphService');
     }
@@ -156,7 +156,7 @@ export default class IndexRebuildService {
         operation: 'rebuild',
         ref,
         mode,
-        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
+        error: err instanceof Error ? err.message : String(err),
         durationMs,
       });
       throw err;
@@ -247,12 +247,12 @@ export default class IndexRebuildService {
    * @private
    */
   async _rebuildStreaming(ref, { limit, maxMemoryBytes, onFlush, onProgress, signal, frontier }) {
-    const builder = new StreamingBitmapIndexBuilder(/** @type {*} */ ({ // TODO(ts-cleanup): narrow port type
+    const builder = new StreamingBitmapIndexBuilder({
       storage: this.storage,
       maxMemoryBytes,
       onFlush,
       crypto: this._crypto,
-    }));
+    });
 
     let processedNodes = 0;
 
@@ -266,7 +266,7 @@ export default class IndexRebuildService {
       if (processedNodes % 10000 === 0) {
         checkAborted(signal, 'rebuild');
         if (onProgress) {
-          const stats = /** @type {any} */ (builder).getMemoryStats(); // TODO(ts-cleanup): narrow port type
+          const stats = /** @type {{ estimatedBitmapBytes: number }} */ (builder.getMemoryStats());
           onProgress({
             processedNodes,
             currentMemoryBytes: stats.estimatedBitmapBytes,
@@ -275,7 +275,7 @@ export default class IndexRebuildService {
       }
     }
 
-    return await /** @type {any} */ (builder).finalize({ signal, frontier }); // TODO(ts-cleanup): narrow port type
+    return await builder.finalize({ signal, frontier });
   }
 
   /**
@@ -389,7 +389,7 @@ export default class IndexRebuildService {
 
     // Staleness check
     if (currentFrontier) {
-      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {*} */ (this.storage), { codec: this._codec }); // TODO(ts-cleanup): narrow port type
+      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {import('../../ports/IndexStoragePort.js').default & import('../../ports/BlobPort.js').default} */ (this.storage), { codec: this._codec });
       if (indexFrontier) {
         const result = checkStaleness(indexFrontier, currentFrontier);
         if (result.stale) {

package/src/domain/services/IndexStalenessChecker.js

@@ -6,12 +6,13 @@
 import defaultCodec from '../utils/defaultCodec.js';
 
 /**
- * @param {*} envelope
+ * @param {unknown} envelope
  * @param {string} label
  * @private
  */
 function validateEnvelope(envelope, label) {
-  if (!envelope || typeof envelope !== 'object' || !envelope.frontier || typeof envelope.frontier !== 'object') {
+  const rec = /** @type {Record<string, unknown>} */ (envelope);
+  if (!rec || typeof rec !== 'object' || !rec.frontier || typeof rec.frontier !== 'object') {
     throw new Error(`invalid frontier envelope for ${label}`);
   }
 }
@@ -25,7 +26,7 @@ function validateEnvelope(envelope, label) {
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Promise<Map<string, string>|null>} Frontier map, or null if not present (legacy index)
  */
-export async function loadIndexFrontier(shardOids, storage, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
   const c = codec || defaultCodec;
   const cborOid = shardOids['frontier.cbor'];
   if (cborOid) {

package/src/domain/services/JoinReducer.js

@@ -29,7 +29,7 @@ export {
  * @typedef {Object} WarpStateV5
  * @property {import('../crdt/ORSet.js').ORSet} nodeAlive - ORSet of alive nodes
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
- * @property {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} prop - Properties with LWW
+ * @property {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
  * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
  */
@@ -81,7 +81,7 @@ export function createEmptyStateV5() {
  * @param {string} [op.to] - Target node ID (for EdgeAdd, EdgeRemove)
  * @param {string} [op.label] - Edge label (for EdgeAdd, EdgeRemove)
  * @param {string} [op.key] - Property key (for PropSet)
- * @param {*} [op.value] - Property value (for PropSet)
+ * @param {unknown} [op.value] - Property value (for PropSet)
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
@@ -114,7 +114,7 @@ export function applyOpV2(state, op, eventId) {
       // Uses EventId-based LWW, same as v4
       const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
       const current = state.prop.get(key);
-      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(current, lwwSet(eventId, op.value))));
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(current, lwwSet(eventId, op.value))));
       break;
     }
     default:
@@ -290,11 +290,11 @@ function edgeRemoveOutcome(orset, op) {
  * - `superseded`: An existing value with higher EventId wins
  * - `redundant`: Exact same write (identical EventId)
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} propMap - The properties map keyed by encoded prop keys
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap - The properties map keyed by encoded prop keys
  * @param {Object} op - The PropSet operation
  * @param {string} op.node - Node ID owning the property
  * @param {string} op.key - Property key/name
- * @param {*} op.value - Property value to set
+ * @param {unknown} op.value - Property value to set
  * @param {import('../utils/EventId.js').EventId} eventId - The event ID for this operation, used for LWW comparison
  * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
  *          Outcome with encoded prop key as target; includes reason when superseded
@@ -347,7 +347,7 @@ function propSetOutcome(propMap, op, eventId) {
  * @param {Object} patch - The patch to apply
  * @param {string} patch.writer - Writer ID who created this patch
  * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
  * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
  * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
  * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
@@ -470,16 +470,16 @@ export function joinStates(a, b) {
  *
  * This is a pure function that does not mutate its inputs.
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} a - First property map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} b - Second property map
- * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} New map containing merged properties
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} a - First property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} b - Second property map
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} New map containing merged properties
  */
 function mergeProps(a, b) {
   const result = new Map(a);
 
   for (const [key, regB] of b) {
     const regA = result.get(key);
-    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(regA, regB)));
+    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(regA, regB)));
   }
 
   return result;
@@ -530,7 +530,7 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
+ * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
  * @param {WarpStateV5} [initialState] - Optional starting state (for incremental materialization from checkpoint)
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.receipts=false] - When true, collect and return TickReceipts

package/src/domain/services/LogicalTraversal.js

@@ -152,7 +152,7 @@ export default class LogicalTraversal {
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
    */
   async _prepare(start, { dir, labelFilter, maxDepth }) {
-    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
 
     if (!(await this._graph.hasNode(start))) {
       throw new TraversalError(`Start node not found: ${start}`, {

package/src/domain/services/MessageCodecInternal.js

@@ -66,7 +66,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 // -----------------------------------------------------------------------------
 
 // Lazy singleton codec instance
-/** @type {*} */ // TODO(ts-cleanup): type lazy singleton
+/** @type {TrailerCodec|null} */
 let _codec = null;
 
 /**

package/src/domain/services/MigrationService.js

@@ -16,7 +16,7 @@ import { createVersionVector, vvIncrement } from '../crdt/VersionVector.js';
  * @param {Object} v4State - The V4 materialized state (visible projection)
  * @param {Map<string, {value: boolean}>} v4State.nodeAlive - V4 node alive map
  * @param {Map<string, {value: boolean}>} v4State.edgeAlive - V4 edge alive map
- * @param {Map<string, *>} v4State.prop - V4 property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} v4State.prop - V4 property map
  * @param {string} migrationWriterId - Writer ID to use for synthetic dots
  * @returns {import('./JoinReducer.js').WarpStateV5} The migrated V5 state
  */

package/src/domain/services/ObserverView.js

@@ -43,10 +43,10 @@ function matchGlob(pattern, str) {
  * - If `expose` is provided and non-empty, only keys in `expose` are included.
  * - If `expose` is absent/empty, all non-redacted keys are included.
  *
- * @param {Map<string, *>} propsMap - The full properties Map
+ * @param {Map<string, unknown>} propsMap - The full properties Map
  * @param {string[]|undefined} expose - Whitelist of property keys to include
  * @param {string[]|undefined} redact - Blacklist of property keys to exclude
- * @returns {Map<string, *>} Filtered properties Map
+ * @returns {Map<string, unknown>} Filtered properties Map
  */
 function filterProps(propsMap, expose, redact) {
   const redactSet = redact && redact.length > 0 ? new Set(redact) : null;
@@ -102,7 +102,7 @@ export default class ObserverView {
     this._graph = graph;
 
     /** @type {LogicalTraversal} */
-    this.traverse = new LogicalTraversal(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
+    this.traverse = new LogicalTraversal(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
 
   /**
@@ -124,11 +124,11 @@ export default class ObserverView {
    * Builds a filtered adjacency structure that only includes edges
    * where both endpoints pass the match filter.
    *
-   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map<string, *[]>, incoming: Map<string, *[]>}}>}
+   * @returns {Promise<{state: unknown, stateHash: string, adjacency: {outgoing: Map<string, unknown[]>, incoming: Map<string, unknown[]>}}>}
    * @private
    */
   async _materializeGraph() {
-    const materialized = await /** @type {*} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, stateHash: string, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
     const { state, stateHash } = materialized;
 
     // Build filtered adjacency: only edges where both endpoints match
@@ -212,7 +212,7 @@ export default class ObserverView {
    * the observer pattern.
    *
    * @param {string} nodeId - The node ID to get properties for
-   * @returns {Promise<Map<string, *>|null>} Filtered properties Map, or null
+   * @returns {Promise<Map<string, unknown>|null>} Filtered properties Map, or null
    */
   async getNodeProps(nodeId) {
     if (!matchGlob(this._matchPattern, nodeId)) {
@@ -234,7 +234,7 @@ export default class ObserverView {
    *
    * An edge is visible only when both endpoints match the observer pattern.
    *
-   * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, *>}>>}
+   * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, unknown>}>>}
    */
   async getEdges() {
     const allEdges = await this._graph.getEdges();
@@ -260,6 +260,6 @@ export default class ObserverView {
    * @returns {QueryBuilder} A query builder scoped to this observer
    */
   query() {
-    return new QueryBuilder(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
+    return new QueryBuilder(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
 }