@git-stunts/git-warp 11.2.1 → 11.5.0

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,

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

@@ -18,9 +18,19 @@ import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCo
 import { Writer } from './Writer.js';
 import { generateWriterId, resolveWriterId } from '../utils/WriterId.js';
 
+/** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
+
 /**
  * Creates a new PatchBuilderV2 for this graph.
  *
+ * In multi-writer scenarios, call `materialize()` (or a query method that
+ * auto-materializes) before creating a patch so that `_maxObservedLamport`
+ * reflects all known writers. Without this, `_nextLamport()` still produces
+ * locally-monotonic ticks (`Math.max(ownTick, _maxObservedLamport) + 1`),
+ * and `PatchBuilderV2.commit()` re-reads the writer's own ref at commit
+ * time, so correctness is preserved — but the tick may be lower than
+ * necessary, losing LWW tiebreakers against other writers.
+ *
  * @this {import('../WarpGraph.js').default}
  * @returns {Promise<PatchBuilderV2>} A new patch builder
  */
@@ -52,6 +62,9 @@ export async function createPatch() {
  * Not reentrant: calling `graph.patch()` inside a callback throws.
  * Use `createPatch()` directly for advanced multi-patch workflows.
  *
+ * **Multi-writer note:** call `materialize()` before `patch()` so that
+ * `_maxObservedLamport` is up-to-date. See `createPatch()` for details.
+ *
  * @this {import('../WarpGraph.js').default}
  * @param {(p: PatchBuilderV2) => void | Promise<void>} build - Callback that adds operations to the patch
  * @returns {Promise<string>} The commit SHA of the new patch
@@ -89,30 +102,35 @@ export async function _nextLamport() {
   const writerRef = buildWriterRef(this._graphName, this._writerId);
   const currentRefSha = await this._persistence.readRef(writerRef);
 
-  if (!currentRefSha) {
-    // First commit for this writer
-    return { lamport: 1, parentSha: null };
-  }
+  let ownTick = 0;
 
-  // Read the current patch commit to get its lamport timestamp
-  const commitMessage = await this._persistence.showNode(currentRefSha);
-  const kind = detectMessageKind(commitMessage);
+  if (currentRefSha) {
+    // Read the current patch commit to get its lamport timestamp
+    const commitMessage = await this._persistence.showNode(currentRefSha);
+    const kind = detectMessageKind(commitMessage);
 
-  if (kind !== 'patch') {
-    // Writer ref doesn't point to a patch commit - treat as first commit
-    return { lamport: 1, parentSha: currentRefSha };
+    if (kind === 'patch') {
+      try {
+        const patchInfo = decodePatchMessage(commitMessage);
+        ownTick = patchInfo.lamport;
+      } catch (err) {
+        throw new Error(
+          `Failed to parse lamport from writer ref ${writerRef}: ` +
+          `commit ${currentRefSha} has invalid patch message format`,
+          { cause: err }
+        );
+      }
+    }
+    // Non-patch ref: ownTick stays 0 (fresh start), falls through to standard return.
   }
 
-  try {
-    const patchInfo = decodePatchMessage(commitMessage);
-    return { lamport: patchInfo.lamport + 1, parentSha: currentRefSha };
-  } catch {
-    // Malformed message - error with actionable message
-    throw new Error(
-      `Failed to parse lamport from writer ref ${writerRef}: ` +
-      `commit ${currentRefSha} has invalid patch message format`
-    );
-  }
+  // Standard Lamport clock rule: next tick = max(own chain, globally observed max) + 1.
+  // _maxObservedLamport is updated during materialize() and after each commit, so this
+  // is O(1) — no additional git reads required at commit time.
+  return {
+    lamport: Math.max(ownTick, this._maxObservedLamport) + 1,
+    parentSha: currentRefSha ?? null,
+  };
 }
 
 /**
@@ -193,19 +211,22 @@ export async function getWriterPatches(writerId, stopAtSha = null) {
  */
 export async function _onPatchCommitted(writerId, { patch: committed, sha } = {}) {
   vvIncrement(this._versionVector, writerId);
+  // Keep _maxObservedLamport up to date so _nextLamport() issues globally-monotonic ticks.
+  if (committed?.lamport !== undefined && committed.lamport > this._maxObservedLamport) {
+    this._maxObservedLamport = committed.lamport;
+  }
   this._patchesSinceCheckpoint++;
   // Eager re-materialize: apply the just-committed patch to cached state
   // Only when the cache is clean — applying a patch to stale state would be incorrect
   if (this._cachedState && !this._stateDirty && committed && sha) {
     let tickReceipt = null;
     if (this._auditService) {
-      // TODO(ts-cleanup): narrow joinPatch return + patch type to PatchV2
       const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (
-        joinPatch(this._cachedState, /** @type {any} */ (committed), sha, true) // TODO(ts-cleanup): narrow patch type
+        joinPatch(this._cachedState, /** @type {Parameters<typeof joinPatch>[1]} */ (committed), sha, true)
       );
       tickReceipt = result.receipt;
     } else {
-      joinPatch(this._cachedState, /** @type {any} */ (committed), sha); // TODO(ts-cleanup): narrow patch type to PatchV2
+      joinPatch(this._cachedState, /** @type {Parameters<typeof joinPatch>[1]} */ (committed), sha);
     }
     await this._setMaterializedState(this._cachedState);
     // Update provenance index with new patch
@@ -257,14 +278,16 @@ export async function writer(writerId) {
     configSet,
   });
 
+  /** @type {CorePersistence} */
+  const persistence = this._persistence;
   return new Writer({
-    persistence: /** @type {any} */ (this._persistence), // TODO(ts-cleanup): narrow port type
+    persistence,
     graphName: this._graphName,
     writerId: resolvedWriterId,
     versionVector: this._versionVector,
-    getCurrentState: () => /** @type {any} */ (this._cachedState), // TODO(ts-cleanup): narrow port type
+    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: (/** @type {any} */ opts) => this._onPatchCommitted(resolvedWriterId, opts), // TODO(ts-cleanup): type sync protocol
+    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts))),
     codec: this._codec,
   });
 }
@@ -313,14 +336,16 @@ export async function createWriter(opts = {}) {
     await this._persistence.configSet(configKey, freshWriterId);
   }
 
+  /** @type {CorePersistence} */
+  const writerPersistence = this._persistence;
   return new Writer({
-    persistence: /** @type {any} */ (this._persistence), // TODO(ts-cleanup): narrow port type
+    persistence: writerPersistence,
     graphName: this._graphName,
     writerId: freshWriterId,
     versionVector: this._versionVector,
-    getCurrentState: () => /** @type {any} */ (this._cachedState), // TODO(ts-cleanup): narrow port type
+    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: (/** @type {any} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts), // TODO(ts-cleanup): type sync protocol
+    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts))),
     codec: this._codec,
   });
 }