@git-stunts/git-warp 11.2.1 → 11.3.3

package/src/domain/utils/roaring.js

@@ -30,9 +30,35 @@
  */
 const NOT_CHECKED = Symbol('NOT_CHECKED');
 
+/**
+ * Shape of the lazily-loaded roaring module after ESM/CJS unwrapping.
+ * Uses Function instead of typeof import('roaring').RoaringBitmap32 to avoid
+ * duplicate import() references that crash Deno's JSR rewriter (deno_ast
+ * overlapping TextChange bug). The single import() reference lives on
+ * getRoaringBitmap32()'s @returns tag.
+ * @typedef {Object} RoaringModule
+ * @property {Function & { isNativelyInstalled?: () => boolean }} RoaringBitmap32
+ * @property {{ RoaringBitmap32: Function }} [default]
+ * @property {boolean} [isNativelyInstalled]
+ */
+
+/**
+ * Minimum structural contract of a RoaringBitmap32 as used by bitmap index code.
+ * Named "Subset" because it only covers methods actually called by index builders/readers.
+ * Using import('roaring').RoaringBitmap32 directly fails under checkJs + skipLibCheck
+ * because tsc doesn't fully resolve inherited methods from ReadonlyRoaringBitmap32.
+ * @typedef {Object} RoaringBitmapSubset
+ * @property {number} size
+ * @property {function(number): void} add
+ * @property {function(number): boolean} has
+ * @property {function(Iterable<number>): void} orInPlace
+ * @property {function(boolean): Uint8Array} serialize
+ * @property {function(): number[]} toArray
+ */
+
 /**
  * Cached reference to the loaded roaring module.
- * @type {any} // TODO(ts-cleanup): type lazy singleton
+ * @type {RoaringModule | null}
  * @private
  */
 let roaringModule = null;
@@ -51,7 +77,7 @@ let nativeAvailability = NOT_CHECKED;
  * Uses a top-level-await-friendly pattern with dynamic import.
  * The module is cached after first load.
  *
- * @returns {any} The roaring module exports
+ * @returns {RoaringModule} The roaring module exports
  * @throws {Error} If the roaring package is not installed or fails to load
  * @private
  */
@@ -67,7 +93,7 @@ function loadRoaring() {
  * This is called automatically via top-level await when the module is imported,
  * but can also be called manually with a pre-loaded module for testing.
  *
- * @param {Object} [mod] - Pre-loaded roaring module (for testing/DI)
+ * @param {RoaringModule} [mod] - Pre-loaded roaring module (for testing/DI)
  * @returns {Promise<void>}
  */
 export async function initRoaring(mod) {
@@ -76,7 +102,7 @@ export async function initRoaring(mod) {
     return;
   }
   if (!roaringModule) {
-    roaringModule = await import('roaring');
+    roaringModule = /** @type {RoaringModule} */ (await import('roaring'));
     // Handle both ESM default export and CJS module.exports
     if (roaringModule.default && roaringModule.default.RoaringBitmap32) {
       roaringModule = roaringModule.default;
@@ -116,7 +142,7 @@ try {
  * const intersection = RoaringBitmap32.and(a, b); // [2, 3]
  */
 export function getRoaringBitmap32() {
-  return loadRoaring().RoaringBitmap32;
+  return /** @type {typeof import('roaring').RoaringBitmap32} */ (loadRoaring().RoaringBitmap32);
 }
 
 /**

package/src/domain/warp/PatchSession.js

@@ -120,7 +120,7 @@ export class PatchSession {
    *
    * @param {string} nodeId - The node ID
    * @param {string} key - Property key
-   * @param {*} value - Property value (must be JSON-serializable)
+   * @param {unknown} value - Property value (must be JSON-serializable)
    * @returns {this} This session for chaining
    * @throws {Error} If this session has already been committed
    */
@@ -137,7 +137,7 @@ export class PatchSession {
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
    * @param {string} key - Property key
-   * @param {*} value - Property value (must be JSON-serializable)
+   * @param {unknown} value - Property value (must be JSON-serializable)
    * @returns {this} This session for chaining
    * @throws {Error} If this session has already been committed
    */
@@ -194,23 +194,14 @@ export class PatchSession {
       const sha = await this._builder.commit();
       this._committed = true;
       return sha;
-    } 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')) {
-        throw new WriterError(
-          'WRITER_REF_ADVANCED',
-          err.message,
-          err
-        );
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const cause = err instanceof Error ? err : undefined;
+      if (errMsg.includes('Concurrent commit detected') ||
+          errMsg.includes('has advanced')) {
+        throw new WriterError('WRITER_REF_ADVANCED', errMsg, cause);
       }
-
-      // Wrap other errors
-      throw new WriterError(
-        'PERSIST_WRITE_FAILED',
-        `Failed to persist patch: ${err.message}`,
-        err
-      );
+      throw new WriterError('PERSIST_WRITE_FAILED', `Failed to persist patch: ${errMsg}`, cause);
     }
   }
 

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

@@ -5,10 +5,153 @@
  * via wireWarpMethods(). This declaration file makes them visible to tsc.
  */
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
 import type { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
 import type { Writer } from './Writer.js';
+import type { WarpStateV5 } from '../services/JoinReducer.js';
+import type { PatchV2 } from '../types/WarpTypesV2.js';
+import type { StateDiffResult } from '../services/StateDiff.js';
+import type { TickReceipt } from '../types/TickReceipt.js';
+
+/**
+ * Observer configuration for view creation and translation cost.
+ */
+interface ObserverConfig {
+  match: string;
+  expose?: string[];
+  redact?: string[];
+}
+
+/**
+ * Translation cost result.
+ */
+interface TranslationCostResult {
+  cost: number;
+  breakdown: { nodeLoss: number; edgeLoss: number; propLoss: number };
+}
+
+/**
+ * Lightweight status snapshot.
+ */
+interface WarpGraphStatus {
+  cachedState: 'fresh' | 'stale' | 'none';
+  patchesSinceCheckpoint: number;
+  tombstoneRatio: number;
+  writers: number;
+  frontier: Record<string, string>;
+}
+
+/**
+ * Sync request message.
+ */
+interface SyncRequest {
+  type: 'sync-request';
+  frontier: Record<string, string>;
+}
+
+/**
+ * Sync response message.
+ */
+interface SyncResponse {
+  type: 'sync-response';
+  frontier: Record<string, string>;
+  patches: Array<{ writerId: string; sha: string; patch: unknown }>;
+}
+
+/**
+ * Result of applySyncResponse().
+ */
+interface ApplySyncResult {
+  state: WarpStateV5;
+  frontier: Map<string, number>;
+  applied: number;
+}
+
+/**
+ * Sync options for syncWith().
+ */
+interface SyncWithOptions {
+  path?: string;
+  retries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  onStatus?: (event: {
+    type: string;
+    attempt: number;
+    durationMs?: number;
+    status?: number;
+    error?: Error;
+  }) => void;
+  auth?: { secret: string; keyId?: string };
+  /** Auto-materialize after sync; when true, result includes `state` */
+  materialize?: boolean;
+}
+
+/**
+ * GC execution result.
+ */
+interface GCExecuteResult {
+  nodesCompacted: number;
+  edgesCompacted: number;
+  tombstonesRemoved: number;
+  durationMs: number;
+}
+
+/**
+ * GC metrics.
+ */
+interface GCMetrics {
+  nodeCount: number;
+  edgeCount: number;
+  tombstoneCount: number;
+  tombstoneRatio: number;
+  patchesSinceCompaction: number;
+  lastCompactionTime: number;
+}
+
+/**
+ * Result of maybeRunGC().
+ */
+interface MaybeGCResult {
+  ran: boolean;
+  result: GCExecuteResult | null;
+  reasons: string[];
+}
+
+/**
+ * Join receipt from CRDT merge.
+ */
+interface JoinReceipt {
+  nodesAdded: number;
+  nodesRemoved: number;
+  edgesAdded: number;
+  edgesRemoved: number;
+  propsChanged: number;
+  frontierMerged: boolean;
+}
+
+/**
+ * Wormhole edge.
+ */
+interface WormholeEdge {
+  fromSha: string;
+  toSha: string;
+  writerId: string;
+  payload: unknown;
+  patchCount: number;
+}
+
+/**
+ * Checkpoint data returned by _loadLatestCheckpoint.
+ */
+interface CheckpointData {
+  state: WarpStateV5;
+  frontier: Map<string, string>;
+  stateHash: string;
+  schema: number;
+  provenanceIndex?: unknown;
+}
 
 export {};
 
@@ -16,85 +159,96 @@ declare module '../WarpGraph.js' {
   export default interface WarpGraph {
     // ── query.methods.js ──────────────────────────────────────────────────
     hasNode(nodeId: string): Promise<boolean>;
-    getNodeProps(nodeId: string): Promise<Map<string, any> | null>;
-    getEdgeProps(from: string, to: string, label: string): Promise<Record<string, any> | null>;
+    getNodeProps(nodeId: string): Promise<Map<string, unknown> | null>;
+    getEdgeProps(from: string, to: string, label: string): Promise<Record<string, unknown> | null>;
     neighbors(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both', edgeLabel?: string): Promise<Array<{ nodeId: string; label: string; direction: 'outgoing' | 'incoming' }>>;
-    getStateSnapshot(): Promise<any>;
+    getStateSnapshot(): Promise<WarpStateV5 | null>;
     getNodes(): Promise<string[]>;
-    getEdges(): Promise<Array<{ from: string; to: string; label: string; props: Record<string, any> }>>;
+    getEdges(): Promise<Array<{ from: string; to: string; label: string; props: Record<string, unknown> }>>;
     getPropertyCount(): Promise<number>;
-    query(): any;
-    observer(name: string, config: any): Promise<any>;
-    translationCost(configA: any, configB: any): Promise<{ cost: number; breakdown: { nodeLoss: number; edgeLoss: number; propLoss: number } }>;
+    query(): import('../services/QueryBuilder.js').default;
+    observer(name: string, config: ObserverConfig): Promise<import('../services/ObserverView.js').default>;
+    translationCost(configA: ObserverConfig, configB: ObserverConfig): Promise<TranslationCostResult>;
 
     // ── subscribe.methods.js ──────────────────────────────────────────────
-    subscribe(options: { onChange: Function; onError?: Function; replay?: boolean }): { unsubscribe: () => void };
-    watch(pattern: string, options: { onChange: Function; onError?: Function; poll?: number }): { unsubscribe: () => void };
-    _notifySubscribers(diff: any, currentState: any): void;
+    subscribe(options: { onChange: (diff: StateDiffResult) => void; onError?: (error: Error) => void; replay?: boolean }): { unsubscribe: () => void };
+    watch(pattern: string, options: { onChange: (diff: StateDiffResult) => void; onError?: (error: Error) => void; poll?: number }): { unsubscribe: () => void };
+    _notifySubscribers(diff: StateDiffResult, currentState: WarpStateV5): void;
 
     // ── provenance.methods.js ─────────────────────────────────────────────
     patchesFor(entityId: string): Promise<string[]>;
-    materializeSlice(nodeId: string, options?: any): Promise<any>;
+    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<any>;
-    _loadPatchBySha(sha: string): Promise<any>;
-    _loadPatchesBySha(shas: string[]): Promise<Array<{ patch: any; sha: string }>>;
-    _sortPatchesCausally(patches: any[]): any[];
+    loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
+    _loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
+    _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 }>;
 
     // ── fork.methods.js ───────────────────────────────────────────────────
     fork(options: { from: string; at: string; forkName?: string; forkWriterId?: string }): Promise<WarpGraph>;
-    createWormhole(fromSha: string, toSha: string): Promise<{ fromSha: string; toSha: string; writerId: string; payload: any; patchCount: number }>;
+    createWormhole(fromSha: string, toSha: string): Promise<WormholeEdge>;
     _isAncestor(ancestorSha: string, descendantSha: string): Promise<boolean>;
     _relationToCheckpointHead(ckHead: string, incomingSha: string): Promise<string>;
-    _validatePatchAgainstCheckpoint(writerId: string, incomingSha: string, checkpoint: any): Promise<void>;
+    _validatePatchAgainstCheckpoint(writerId: string, incomingSha: string, checkpoint: unknown): Promise<void>;
 
     // ── sync.methods.js ───────────────────────────────────────────────────
     getFrontier(): Promise<Map<string, string>>;
     hasFrontierChanged(): Promise<boolean>;
-    status(): Promise<any>;
-    createSyncRequest(): Promise<any>;
-    processSyncRequest(request: any): Promise<any>;
-    applySyncResponse(response: any): any;
-    syncNeeded(remoteFrontier: any): Promise<boolean>;
-    syncWith(remote: any, options?: any): Promise<any>;
-    serve(options?: any): Promise<any>;
+    status(): Promise<WarpGraphStatus>;
+    createSyncRequest(): Promise<SyncRequest>;
+    processSyncRequest(request: SyncRequest): Promise<SyncResponse>;
+    applySyncResponse(response: SyncResponse): ApplySyncResult;
+    syncNeeded(remoteFrontier: Map<string, string>): Promise<boolean>;
+    syncWith(remote: string | WarpGraph, options?: SyncWithOptions): Promise<{ applied: number; attempts: number; state?: WarpStateV5 }>;
+    serve(options: {
+      port: number;
+      host?: string;
+      path?: string;
+      maxRequestBytes?: number;
+      httpPort: unknown;
+      auth?: unknown;
+      allowedWriters?: string[];
+    }): Promise<{ close(): Promise<void>; url: string }>;
 
     // ── checkpoint.methods.js ─────────────────────────────────────────────
     createCheckpoint(): Promise<string>;
     syncCoverage(): Promise<void>;
-    _loadLatestCheckpoint(): Promise<any>;
-    _loadPatchesSince(checkpoint: any): Promise<any[]>;
+    _loadLatestCheckpoint(): Promise<CheckpointData | null>;
+    _loadPatchesSince(checkpoint: CheckpointData): Promise<Array<{ patch: PatchV2; sha: string }>>;
     _validateMigrationBoundary(): Promise<void>;
     _hasSchema1Patches(): Promise<boolean>;
-    _maybeRunGC(state: any): any;
-    maybeRunGC(): any;
-    runGC(): any;
-    getGCMetrics(): any;
+    _maybeRunGC(state: WarpStateV5): void;
+    maybeRunGC(): MaybeGCResult;
+    runGC(): GCExecuteResult;
+    getGCMetrics(): GCMetrics | null;
 
     // ── patch.methods.js ──────────────────────────────────────────────────
     createPatch(): Promise<PatchBuilderV2>;
     patch(build: (p: PatchBuilderV2) => void | Promise<void>): Promise<string>;
     _nextLamport(): Promise<{ lamport: number; parentSha: string | null }>;
-    _loadWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: import('../types/WarpTypesV2.js').PatchV2; sha: string }>>;
-    getWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: import('../types/WarpTypesV2.js').PatchV2; sha: string }>>;
-    _onPatchCommitted(writerId: string, opts?: { patch?: any; sha?: string }): Promise<void>;
+    _loadWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: PatchV2; sha: string }>>;
+    getWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: PatchV2; sha: string }>>;
+    _onPatchCommitted(writerId: string, opts?: { patch?: PatchV2; sha?: string }): Promise<void>;
     writer(writerId?: string): Promise<Writer>;
-    createWriter(opts?: any): Promise<Writer>;
+    createWriter(opts?: { persist?: 'config' | 'none'; alias?: string }): Promise<Writer>;
     _ensureFreshState(): Promise<void>;
     discoverWriters(): Promise<string[]>;
     discoverTicks(): Promise<{ ticks: number[]; maxTick: number; perWriter: Map<string, { ticks: number[]; tipSha: string | null; tickShas: Record<number, string> }> }>;
-    join(otherState: any): any;
-    _frontierEquals(a: any, b: any): boolean;
+    join(otherState: WarpStateV5): { state: WarpStateV5; receipt: JoinReceipt };
+    _frontierEquals(a: Map<string, number>, b: Map<string, number>): boolean;
 
     // ── materialize.methods.js ────────────────────────────────────────────
-    materialize(options?: any): Promise<any>;
-    _materializeGraph(): Promise<any>;
+    materialize(options: { receipts: true; ceiling?: number | null }): Promise<{ state: WarpStateV5; receipts: TickReceipt[] }>;
+    materialize(options?: { receipts?: false; ceiling?: number | null }): Promise<WarpStateV5>;
+    _materializeGraph(): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
 
     // ── materializeAdvanced.methods.js ────────────────────────────────────
-    _resolveCeiling(options: any): any;
-    _buildAdjacency(state: any): any;
-    _setMaterializedState(state: any): Promise<{ state: any; stateHash: string; adjacency: any }>;
-    _materializeWithCeiling(ceiling: any, collectReceipts: boolean, t0: number): Promise<any>;
-    materializeAt(checkpointSha: string): Promise<any>;
+    _resolveCeiling(options?: { ceiling?: number | null }): number | null;
+    _buildAdjacency(state: WarpStateV5): { outgoing: Map<string, Array<{ neighborId: string; label: string }>>; incoming: Map<string, Array<{ neighborId: string; label: string }>> };
+    _setMaterializedState(state: WarpStateV5): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
+    _materializeWithCeiling(ceiling: number, collectReceipts: boolean, t0: number): Promise<WarpStateV5 | { state: WarpStateV5; receipts: TickReceipt[] }>;
+    materializeAt(checkpointSha: string): Promise<WarpStateV5>;
   }
 }

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

@@ -16,6 +16,8 @@ import { shouldRunGC, executeGC } from '../services/GCPolicy.js';
 import { collectGCMetrics } from '../services/GCMetrics.js';
 import { computeAppliedVV } from '../services/CheckpointSerializerV5.js';
 
+/** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
+
 /**
  * Creates a checkpoint of the current graph state.
  *
@@ -59,8 +61,10 @@ export async function createCheckpoint() {
     }
 
     // 4. Call CheckpointService.create() with provenance index if available
+    /** @type {CorePersistence} */
+    const persistence = this._persistence;
     const checkpointSha = await createCheckpointCommit({
-      persistence: /** @type {any} */ (this._persistence), // TODO(ts-cleanup): narrow port type
+      persistence,
       graphName: this._graphName,
       state,
       frontier,

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

@@ -201,13 +201,13 @@ export async function createWormhole(fromSha, toSha) {
   const t0 = this._clock.now();
 
   try {
-    const wormhole = await createWormholeImpl(/** @type {any} */ ({ // TODO(ts-cleanup): needs options type
+    const wormhole = await createWormholeImpl({
       persistence: this._persistence,
       graphName: this._graphName,
       fromSha,
       toSha,
       codec: this._codec,
-    }));
+    });
 
     this._logTiming('createWormhole', t0, {
       metrics: `${wormhole.patchCount} patches from=${fromSha.slice(0, 7)} to=${toSha.slice(0, 7)}`,

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

@@ -9,6 +9,47 @@
 import { reduceV5, createEmptyStateV5, cloneStateV5 } from '../services/JoinReducer.js';
 import { ProvenanceIndex } from '../services/ProvenanceIndex.js';
 import { diffStates, isEmptyDiff } from '../services/StateDiff.js';
+import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
+
+/**
+ * Scans the checkpoint frontier's tip commits for the maximum observed Lamport tick.
+ * Updates `graph._maxObservedLamport` in-place; best-effort (skips unreadable commits).
+ *
+ * @param {import('../WarpGraph.js').default} graph
+ * @param {Map<string, string>} frontier
+ * @returns {Promise<void>}
+ */
+async function scanFrontierForMaxLamport(graph, frontier) {
+  for (const tipSha of frontier.values()) {
+    try {
+      const msg = await graph._persistence.showNode(tipSha);
+      if (detectMessageKind(msg) === 'patch') {
+        const { lamport } = decodePatchMessage(msg);
+        if (lamport > graph._maxObservedLamport) {
+          graph._maxObservedLamport = lamport;
+        }
+      }
+    } catch {
+      // best-effort: skip unreadable frontier commits
+    }
+  }
+}
+
+/**
+ * Scans a list of patch entries for the maximum observed Lamport tick.
+ * Updates `graph._maxObservedLamport` in-place.
+ *
+ * @param {import('../WarpGraph.js').default} graph
+ * @param {Array<{patch: {lamport?: number}}>} patches
+ */
+function scanPatchesForMaxLamport(graph, patches) {
+  for (const { patch } of patches) {
+    const tick = patch.lamport ?? 0;
+    if (tick > graph._maxObservedLamport) {
+      graph._maxObservedLamport = tick;
+    }
+  }
+}
 
 /**
  * Materializes the current graph state.
@@ -63,17 +104,24 @@ export async function materialize(options) {
     // If checkpoint exists, use incremental materialization
     if (checkpoint?.schema === 2 || checkpoint?.schema === 3) {
       const patches = await this._loadPatchesSince(checkpoint);
+      // Update max observed Lamport so _nextLamport() issues globally-monotonic ticks.
+      // Read the checkpoint frontier's tip commit messages to capture the pre-checkpoint max,
+      // then scan the incremental patches for anything newer.
+      if (checkpoint.frontier instanceof Map) {
+        await scanFrontierForMaxLamport(this, checkpoint.frontier);
+      }
+      scanPatchesForMaxLamport(this, patches);
       if (collectReceipts) {
-        const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {any} */ (patches), /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (checkpoint.state), { receipts: true })); // TODO(ts-cleanup): type patch array
+        const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (patches), checkpoint.state, { receipts: true }));
         state = result.state;
         receipts = result.receipts;
       } else {
-        state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {any} */ (patches), /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (checkpoint.state))); // TODO(ts-cleanup): type patch array
+        state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (patches), checkpoint.state));
       }
       patchCount = patches.length;
 
       // Build provenance index: start from checkpoint index if present, then add new patches
-      const ckPI = /** @type {any} */ (checkpoint).provenanceIndex; // TODO(ts-cleanup): type checkpoint cast
+      const ckPI = /** @type {{provenanceIndex?: import('../services/ProvenanceIndex.js').ProvenanceIndex}} */ (checkpoint).provenanceIndex;
       this._provenanceIndex = ckPI
         ? ckPI.clone()
         : new ProvenanceIndex();
@@ -109,13 +157,15 @@ export async function materialize(options) {
             receipts = [];
           }
         } else {
+          // Update max observed Lamport from all loaded patches.
+          scanPatchesForMaxLamport(this, allPatches);
           // 5. Reduce all patches to state
           if (collectReceipts) {
-            const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {any} */ (allPatches), undefined, { receipts: true })); // TODO(ts-cleanup): type patch array
+            const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches), undefined, { receipts: true }));
             state = result.state;
             receipts = result.receipts;
           } else {
-            state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {any} */ (allPatches))); // TODO(ts-cleanup): type patch array
+            state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches)));
           }
           patchCount = allPatches.length;
 

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

@@ -18,6 +18,15 @@ import { serializeFullStateV5, deserializeFullStateV5 } from '../services/Checkp
 import { buildSeekCacheKey } from '../utils/seekCacheKey.js';
 import { materializeIncremental } from '../services/CheckpointService.js';
 import { createFrontier, updateFrontier } from '../services/Frontier.js';
+
+/** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
+/** @typedef {import('../services/JoinReducer.js').WarpStateV5} WarpStateV5 */
+
+/**
+ * @typedef {{ outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>> }} AdjacencyMap
+ * @typedef {{ state: WarpStateV5, stateHash: string, adjacency: AdjacencyMap }} MaterializedResult
+ */
+
 import { buildWriterRef } from '../utils/RefLayout.js';
 import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
 
@@ -97,7 +106,7 @@ export function _buildAdjacency(state) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
- * @returns {Promise<{state: any, stateHash: string, adjacency: any}>}
+ * @returns {Promise<MaterializedResult>}
  * @private
  */
 export async function _setMaterializedState(state) {
@@ -226,11 +235,11 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
       receipts = [];
     }
   } else if (collectReceipts) {
-    const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {any} */ (allPatches), undefined, { receipts: true })); // TODO(ts-cleanup): type patch array
+    const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches), undefined, { receipts: true }));
     state = result.state;
     receipts = result.receipts;
   } else {
-    state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {any} */ (allPatches))); // TODO(ts-cleanup): type patch array
+    state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches)));
   }
 
   this._provenanceIndex = new ProvenanceIndex();
@@ -326,8 +335,10 @@ export async function materializeAt(checkpointSha) {
   };
 
   // 4. Call materializeIncremental with the checkpoint and target frontier
+  /** @type {CorePersistence} */
+  const persistence = this._persistence;
   const state = await materializeIncremental({
-    persistence: /** @type {any} */ (this._persistence), // TODO(ts-cleanup): narrow port type
+    persistence,
     graphName: this._graphName,
     checkpointSha,
     targetFrontier,