@git-stunts/git-warp 11.2.1 → 11.3.3

package/bin/presenters/text.js

@@ -7,6 +7,28 @@
 
 import { formatStructuralDiff } from '../../src/visualization/renderers/ascii/seek.js';
 
+// ── Payload typedefs ────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ installed: boolean, foreign?: boolean, current?: boolean, version?: string }} HookStatus
+ * @typedef {{ repo: string, graphs: Array<{ name: string, writers?: { count: number } | null, checkpoint?: { sha: string } | null, coverage?: { sha: string } | null, cursor?: { active: boolean, tick: number, mode: string } | null }> }} InfoPayload
+ * @typedef {{ graph: string, stateHash?: string, nodes: Array<{ id?: string, props?: Record<string, unknown>, edges?: NodeEdges }>, _renderedAscii?: string, _renderedSvg?: string }} QueryPayload
+ * @typedef {{ outgoing?: Array<{ label: string, to: string }>, incoming?: Array<{ label: string, from: string }> }} NodeEdges
+ * @typedef {{ graph: string, from: string, to: string, found: boolean, length?: number, path?: string[] }} PathPayload
+ * @typedef {{ graph: string, health: { status: string }, checkpoint?: { sha: string, ageSeconds: number | null } | null, writers: { count: number, heads: Array<{ writerId: string, sha: string }> }, coverage?: { sha: string, missingWriters: string[] } | null, gc?: { totalTombstones: number, tombstoneRatio: number } | null, hook?: HookStatus | null, status?: { cachedState: string, patchesSinceCheckpoint: number, tombstoneRatio: number, writers: number } | null }} CheckPayload
+ * @typedef {{ graph: string, writer: string, nodeFilter?: string | null, entries: Array<{ sha: string, lamport: number, opCount: number }> }} HistoryPayload
+ * @typedef {{ error: { message: string } }} ErrorPayload
+ * @typedef {{ graphs: Array<{ graph: string, nodes?: number, edges?: number, checkpoint?: string, error?: string }> }} MaterializePayload
+ * @typedef {{ action: string, hookPath?: string, version?: string, backupPath?: string, name?: string }} InstallHooksPayload
+ * @typedef {{ graph?: string, action: string, tick?: number, maxTick?: number, ticks?: number[], nodes?: number, edges?: number, patchCount?: number, perWriter?: Record<string, unknown>, diff?: { nodes?: number, edges?: number } | null, tickReceipt?: Record<string, unknown>, structuralDiff?: import('../../src/domain/services/StateDiff.js').StateDiffResult | null, cursor?: { active: boolean, tick?: number }, message?: string, cursors?: Array<{ name: string, tick: number }>, activeTick?: number | null, name?: string, diffBaseline?: string, baselineTick?: number | null, truncated?: boolean, totalChanges?: number, shownChanges?: number }} SeekPayload
+ * @typedef {{ graph: string, health: string, checkedAt: string, summary: { checksRun: number, findingsTotal: number, ok: number, warn: number, fail: number, priorityActions: string[] }, findings: Array<{ status: string, id: string, message: string, fix?: string }> }} DoctorPayload
+ * @typedef {{ graph: string, verifiedAt: string, summary: { total: number, valid: number, partial: number, invalid: number }, chains: Array<{ writerId: string, status: string, receiptsVerified: number, since?: string, errors: Array<{ code: string, message: string }>, warnings: Array<{ code: string, message: string }> }>, trustWarning?: { message: string } }} VerifyAuditPayload
+ * @typedef {{ graph: string, trustVerdict: string, mode: string, trust: { source: string, evidenceSummary: { activeKeys: number, revokedKeys: number, activeBindings: number }, explanations: Array<{ trusted: boolean, writerId: string, reasonCode: string, reason: string }>, untrustedWriters: string[] } }} TrustPayload
+ * @typedef {{ type: string, node?: string, from?: string, to?: string, label?: string, key?: string, value?: unknown }} PatchOp
+ * @typedef {{ graph: string, sha: string, writer: string, lamport: number, schema?: number, ops: PatchOp[] }} PatchShowPayload
+ * @typedef {{ graph: string, total: number, showing: number, writerFilter?: string | null, entries: Array<{ sha: string, writer: string, lamport: number, opCount: number, nodeIds: string[] }> }} PatchListPayload
+ */
+
 // ── ANSI helpers ─────────────────────────────────────────────────────────────
 
 const ANSI_GREEN = '\x1b[32m';
@@ -26,7 +48,7 @@ function colorCachedState(state) {
   return `${ANSI_RED}${ANSI_DIM}${state}${ANSI_RESET}`;
 }
 
-/** @param {*} hook */
+/** @param {HookStatus} hook */
 function formatHookStatusLine(hook) {
   if (!hook.installed && hook.foreign) {
     return "Hook: foreign hook present — run 'git warp install-hooks'";
@@ -42,7 +64,7 @@ function formatHookStatusLine(hook) {
 
 // ── Simple renderers ─────────────────────────────────────────────────────────
 
-/** @param {*} payload */
+/** @param {InfoPayload} payload */
 export function renderInfo(payload) {
   const lines = [`Repo: ${payload.repo}`];
   lines.push(`Graphs: ${payload.graphs.length}`);
@@ -62,7 +84,25 @@ export function renderInfo(payload) {
   return `${lines.join('\n')}\n`;
 }
 
-/** @param {*} payload */
+/**
+ * Appends edge lines for a single node to the output array.
+ * @param {string[]} lines
+ * @param {NodeEdges} edges
+ */
+function appendNodeEdges(lines, edges) {
+  if (edges.outgoing && edges.outgoing.length > 0) {
+    for (const e of edges.outgoing) {
+      lines.push(`  -> ${e.label} -> ${e.to}`);
+    }
+  }
+  if (edges.incoming && edges.incoming.length > 0) {
+    for (const e of edges.incoming) {
+      lines.push(`  <- ${e.label} <- ${e.from}`);
+    }
+  }
+}
+
+/** @param {QueryPayload} payload */
 export function renderQuery(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -76,21 +116,27 @@ export function renderQuery(payload) {
     if (node.props && Object.keys(node.props).length > 0) {
       lines.push(`  props: ${JSON.stringify(node.props)}`);
     }
+    if (node.edges) {
+      appendNodeEdges(lines, node.edges);
+    }
   }
 
   return `${lines.join('\n')}\n`;
 }
 
-/** @param {*} payload */
+/** @param {PathPayload} payload */
 export function renderPath(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
     `From: ${payload.from}`,
     `To: ${payload.to}`,
     `Found: ${payload.found ? 'yes' : 'no'}`,
-    `Length: ${payload.length}`,
   ];
 
+  if (payload.found) {
+    lines.push(`Length: ${payload.length}`);
+  }
+
   if (payload.path && payload.path.length > 0) {
     lines.push(`Path: ${payload.path.join(' -> ')}`);
   }
@@ -101,7 +147,7 @@ export function renderPath(payload) {
 /**
  * Appends checkpoint and writer lines to check output.
  * @param {string[]} lines
- * @param {*} payload
+ * @param {CheckPayload} payload
  */
 function appendCheckpointAndWriters(lines, payload) {
   if (payload.checkpoint?.sha) {
@@ -124,7 +170,7 @@ function appendCheckpointAndWriters(lines, payload) {
 /**
  * Appends coverage, gc, and hook lines to check output.
  * @param {string[]} lines
- * @param {*} payload
+ * @param {CheckPayload} payload
  */
 function appendCoverageAndExtras(lines, payload) {
   if (payload.coverage?.sha) {
@@ -146,7 +192,7 @@ function appendCoverageAndExtras(lines, payload) {
   }
 }
 
-/** @param {*} payload */
+/** @param {CheckPayload} payload */
 export function renderCheck(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -165,7 +211,7 @@ export function renderCheck(payload) {
   return `${lines.join('\n')}\n`;
 }
 
-/** @param {*} payload */
+/** @param {HistoryPayload} payload */
 export function renderHistory(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -184,12 +230,12 @@ export function renderHistory(payload) {
   return `${lines.join('\n')}\n`;
 }
 
-/** @param {*} payload */
+/** @param {ErrorPayload} payload */
 export function renderError(payload) {
   return `Error: ${payload.error.message}\n`;
 }
 
-/** @param {*} payload */
+/** @param {MaterializePayload} payload */
 export function renderMaterialize(payload) {
   if (payload.graphs.length === 0) {
     return 'No graphs found in repo.\n';
@@ -206,7 +252,7 @@ export function renderMaterialize(payload) {
   return `${lines.join('\n')}\n`;
 }
 
-/** @param {*} payload */
+/** @param {InstallHooksPayload} payload */
 export function renderInstallHooks(payload) {
   if (payload.action === 'up-to-date') {
     return `Hook: already up to date (v${payload.version}) at ${payload.hookPath}\n`;
@@ -225,10 +271,10 @@ export function renderInstallHooks(payload) {
 
 /**
  * Formats a numeric delta as " (+N)" or " (-N)", or empty string for zero/non-finite.
- * @param {*} n
+ * @param {unknown} n
  * @returns {string}
  */
-function formatDelta(n) { // TODO(ts-cleanup): type CLI payload
+function formatDelta(n) {
   if (typeof n !== 'number' || !Number.isFinite(n) || n === 0) {
     return '';
   }
@@ -238,10 +284,10 @@ function formatDelta(n) { // TODO(ts-cleanup): type CLI payload
 
 /**
  * Formats an operation summary object as a compact plain-text string.
- * @param {*} summary
+ * @param {Record<string, number> | null | undefined} summary
  * @returns {string}
  */
-function formatOpSummaryPlain(summary) { // TODO(ts-cleanup): type CLI payload
+function formatOpSummaryPlain(summary) {
   const order = [
     ['NodeAdd', '+', 'node'],
     ['EdgeAdd', '+', 'edge'],
@@ -264,7 +310,7 @@ function formatOpSummaryPlain(summary) { // TODO(ts-cleanup): type CLI payload
 /**
  * Appends a per-writer tick receipt summary below a base line.
  * @param {string} baseLine
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @returns {string}
  */
 function appendReceiptSummary(baseLine, payload) {
@@ -284,8 +330,12 @@ function appendReceiptSummary(baseLine, payload) {
   const maxWriterLen = Math.max(5, ...entries.map(([writerId]) => writerId.length));
   const receiptLines = [`  Tick ${payload.tick}:`];
   for (const [writerId, entry] of entries) {
-    const sha = typeof entry.sha === 'string' ? entry.sha.slice(0, 7) : '';
-    const opSummary = entry.opSummary && typeof entry.opSummary === 'object' ? entry.opSummary : entry;
+    /** @type {Record<string, unknown>} */
+    const rec = /** @type {Record<string, unknown>} */ (entry);
+    const sha = typeof rec.sha === 'string' ? rec.sha.slice(0, 7) : '';
+    const opSummary = rec.opSummary && typeof rec.opSummary === 'object'
+      ? /** @type {Record<string, number>} */ (rec.opSummary)
+      : /** @type {Record<string, number>} */ (rec);
     receiptLines.push(`    ${writerId.padEnd(maxWriterLen)}  ${sha.padEnd(7)}  ${formatOpSummaryPlain(opSummary)}`);
   }
 
@@ -294,7 +344,7 @@ function appendReceiptSummary(baseLine, payload) {
 
 /**
  * Builds human-readable state count strings from a seek payload.
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @returns {{nodesStr: string, edgesStr: string, patchesStr: string}}
  */
 function buildStateStrings(payload) {
@@ -310,20 +360,20 @@ function buildStateStrings(payload) {
 
 /**
  * Renders the "tick" / "latest" / "load" seek action with receipt + structural diff.
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @param {string} headerLine
  * @returns {string}
  */
 function renderSeekWithDiff(payload, headerLine) {
   const base = appendReceiptSummary(headerLine, payload);
-  return base + formatStructuralDiff(payload);
+  return base + formatStructuralDiff(/** @type {import('../../src/visualization/renderers/ascii/seek.js').SeekPayload} */ (payload));
 }
 
 // ── Seek simple-action renderers ─────────────────────────────────────────────
 
 /**
  * Renders seek actions that don't involve state counts: clear-cache, list, drop, save.
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @returns {string|null} Rendered string, or null if action is not simple
  */
 function renderSeekSimple(payload) {
@@ -344,11 +394,11 @@ function renderSeekSimple(payload) {
 
 /**
  * Renders the cursor list action.
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @returns {string}
  */
 function renderSeekList(payload) {
-  if (payload.cursors.length === 0) {
+  if (!payload.cursors || payload.cursors.length === 0) {
     return 'No saved cursors.\n';
   }
   const lines = [];
@@ -363,7 +413,7 @@ function renderSeekList(payload) {
 
 /**
  * Renders seek actions that show state: latest, load, tick, status.
- * @param {*} payload
+ * @param {SeekPayload} payload
  * @returns {string}
  */
 function renderSeekState(payload) {
@@ -396,19 +446,19 @@ function renderSeekState(payload) {
       payload,
     );
   }
-  return `${payload.graph}: no cursor active, ${payload.ticks.length} ticks available\n`;
+  return `${payload.graph}: no cursor active, ${(payload.ticks ?? []).length} ticks available\n`;
 }
 
 // ── Seek main renderer ──────────────────────────────────────────────────────
 
-/** @param {*} payload */
+/** @param {SeekPayload} payload */
 export function renderSeek(payload) {
   return renderSeekSimple(payload) ?? renderSeekState(payload);
 }
 
 // ── Doctor renderer ──────────────────────────────────────────────────────────
 
-/** @param {'ok'|'warn'|'fail'} status */
+/** @param {string} status */
 function findingIcon(status) {
   if (status === 'ok') {
     return `${ANSI_GREEN}\u2713${ANSI_RESET}`;
@@ -419,7 +469,7 @@ function findingIcon(status) {
   return `${ANSI_RED}\u2717${ANSI_RESET}`;
 }
 
-/** @param {'ok'|'degraded'|'failed'} health */
+/** @param {string} health */
 function colorHealth(health) {
   if (health === 'ok') {
     return `${ANSI_GREEN}${health}${ANSI_RESET}`;
@@ -430,7 +480,7 @@ function colorHealth(health) {
   return `${ANSI_RED}${health}${ANSI_RESET}`;
 }
 
-/** @param {*} payload */
+/** @param {DoctorPayload} payload */
 export function renderDoctor(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -468,7 +518,7 @@ function colorStatus(status) {
   return `${ANSI_RED}${status}${ANSI_RESET}`;
 }
 
-/** @param {*} payload */
+/** @param {VerifyAuditPayload} payload */
 export function renderVerifyAudit(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -513,7 +563,7 @@ function colorVerdict(verdict) {
   return `${ANSI_RED}${verdict}${ANSI_RESET}`;
 }
 
-/** @param {*} payload */
+/** @param {TrustPayload} payload */
 export function renderTrust(payload) {
   const lines = [
     `Graph: ${payload.graph}`,
@@ -541,3 +591,75 @@ export function renderTrust(payload) {
 
   return `${lines.join('\n')}\n`;
 }
+
+// ── Patch renderers ──────────────────────────────────────────────────────────
+
+/**
+ * Formats a single operation line for patch show output.
+ * @param {PatchOp} op
+ * @returns {string|null}
+ */
+function formatPatchOp(op) {
+  if (op.type === 'NodeAdd') {
+    return `  + node ${op.node}`;
+  }
+  if (op.type === 'NodeTombstone') {
+    return `  - node ${op.node}`;
+  }
+  if (op.type === 'EdgeAdd') {
+    return `  + edge ${op.from} -[${op.label}]-> ${op.to}`;
+  }
+  if (op.type === 'EdgeTombstone') {
+    return `  - edge ${op.from} -[${op.label}]-> ${op.to}`;
+  }
+  if (op.type === 'PropSet') {
+    return `  ~ ${op.node}.${op.key} = ${JSON.stringify(op.value)}`;
+  }
+  if (op.type === 'BlobValue') {
+    return `  + blob ${op.node}`;
+  }
+  return null;
+}
+
+/** @param {PatchShowPayload} payload */
+export function renderPatchShow(payload) {
+  const lines = [
+    `Graph: ${payload.graph}`,
+    `SHA: ${payload.sha}`,
+    `Writer: ${payload.writer}`,
+    `Lamport: ${payload.lamport}`,
+    `Schema: ${payload.schema}`,
+    `Operations: ${payload.ops.length}`,
+    '',
+  ];
+
+  for (const op of payload.ops) {
+    const line = formatPatchOp(op);
+    if (line) {
+      lines.push(line);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/** @param {PatchListPayload} payload */
+export function renderPatchList(payload) {
+  const lines = [
+    `Graph: ${payload.graph}`,
+    `Patches: ${payload.showing}/${payload.total}`,
+  ];
+
+  if (payload.writerFilter) {
+    lines.push(`Writer: ${payload.writerFilter}`);
+  }
+
+  lines.push('');
+
+  for (const entry of payload.entries) {
+    const nodes = entry.nodeIds.length > 0 ? ` [${entry.nodeIds.join(', ')}]` : '';
+    lines.push(`  ${entry.sha}  L${String(entry.lamport).padStart(3)}  ${entry.writer.padEnd(20)}  ${entry.opCount} ops${nodes}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/index.d.ts

@@ -566,6 +566,15 @@ export interface GitPlumbing {
  */
 export class InMemoryGraphAdapter extends GraphPersistencePort {
   constructor();
+
+  get emptyTree(): string;
+  commitNode(options: CreateNodeOptions): Promise<string>;
+  showNode(sha: string): Promise<string>;
+  getNodeInfo(sha: string): Promise<NodeInfo>;
+  logNodesStream(options: ListNodesOptions & { format: string }): Promise<AsyncIterable<Uint8Array | string>>;
+  logNodes(options: ListNodesOptions & { format: string }): Promise<string>;
+  ping(): Promise<PingResult>;
+  countNodes(ref: string): Promise<number>;
 }
 
 /**
@@ -1032,7 +1041,7 @@ export class SyncError extends Error {
  * Base error class for bitmap index operations.
  */
 export class IndexError extends Error {
-  readonly name: 'IndexError';
+  readonly name: string;
   readonly code: string;
   readonly context: Record<string, unknown>;
 
@@ -1293,12 +1302,65 @@ export interface TemporalQuery {
   ): Promise<boolean>;
 }
 
+// ============================================================================
+// PatchV2 & PatchBuilderV2
+// ============================================================================
+
+/**
+ * WARP V5 patch object (schema 2 or 3).
+ */
+export interface PatchV2 {
+  /** Schema version (2 for node/edge ops, 3 if edge properties present) */
+  schema: 2 | 3;
+  /** Writer ID */
+  writer: string;
+  /** Lamport timestamp for ordering */
+  lamport: number;
+  /** Writer's observed frontier (version vector) */
+  context: Record<string, number>;
+  /** Ordered array of operations */
+  ops: unknown[];
+  /** Node/edge IDs read by this patch (provenance tracking) */
+  reads?: string[];
+  /** Node/edge IDs written by this patch (provenance tracking) */
+  writes?: string[];
+}
+
+/**
+ * Fluent builder for creating WARP v5 patches with OR-Set semantics.
+ *
+ * Returned by WarpGraph.createPatch(). Chain mutation methods then call
+ * commit() to persist the patch atomically.
+ */
+export class PatchBuilderV2 {
+  /** Adds a node to the graph. */
+  addNode(nodeId: string): PatchBuilderV2;
+  /** Removes a node from the graph. */
+  removeNode(nodeId: string): PatchBuilderV2;
+  /** Adds an edge between two nodes. */
+  addEdge(from: string, to: string, label: string): PatchBuilderV2;
+  /** Removes an edge between two nodes. */
+  removeEdge(from: string, to: string, label: string): PatchBuilderV2;
+  /** Sets a property on a node. */
+  setProperty(nodeId: string, key: string, value: unknown): PatchBuilderV2;
+  /** Sets a property on an edge. */
+  setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): PatchBuilderV2;
+  /** Builds the PatchV2 object without committing. */
+  build(): PatchV2;
+  /** Commits the patch to the graph and returns the commit SHA. */
+  commit(): Promise<string>;
+  /** Number of operations in this patch. */
+  readonly opCount: number;
+}
+
 // ============================================================================
 // Writer & PatchSession
 // ============================================================================
 
 /**
  * Fluent patch session for building and committing graph mutations.
+ *
+ * Created by Writer.beginPatch(). Wraps a PatchBuilderV2 with CAS protection.
  */
 export class PatchSession {
   /** Adds a node to the graph. */
@@ -1313,8 +1375,8 @@ export class PatchSession {
   setProperty(nodeId: string, key: string, value: unknown): this;
   /** Sets a property on an edge. */
   setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): this;
-  /** Builds the patch object without committing. */
-  build(): unknown;
+  /** Builds the PatchV2 object without committing. */
+  build(): PatchV2;
   /** Commits the patch with CAS protection. */
   commit(): Promise<string>;
   /** Number of operations in this patch. */
@@ -1527,21 +1589,21 @@ export default class WarpGraph {
   setSeekCache(cache: SeekCachePort | null): void;
 
   /**
-   * Creates a new patch for adding operations.
+   * Creates a new PatchBuilderV2 for adding operations.
    */
-  createPatch(): Promise<PatchSession>;
+  createPatch(): Promise<PatchBuilderV2>;
 
   /**
    * Convenience wrapper: creates a patch, runs the callback, and commits.
    *
-   * The callback receives a patch builder and may be synchronous or
+   * The callback receives a PatchBuilderV2 and may be synchronous or
    * asynchronous. The commit happens only after the callback resolves.
    * If the callback throws or rejects, no commit is attempted.
    *
    * Not reentrant: calling `graph.patch()` inside a callback throws.
    * Use `createPatch()` directly for nested or concurrent patches.
    */
-  patch(build: (patch: PatchSession) => void | Promise<void>): Promise<string>;
+  patch(build: (patch: PatchBuilderV2) => void | Promise<void>): Promise<string>;
 
   /**
    * Returns patches from a writer's ref chain.
@@ -1549,7 +1611,7 @@ export default class WarpGraph {
   getWriterPatches(
     writerId: string,
     stopAtSha?: string | null
-  ): Promise<Array<{ patch: unknown; sha: string }>>;
+  ): Promise<Array<{ patch: PatchV2; sha: string }>>;
 
   /**
    * Gets all visible nodes in the materialized state.
@@ -1621,7 +1683,7 @@ export default class WarpGraph {
   /**
    * Materializes graph state from a checkpoint, applying incremental patches.
    */
-  materializeAt(checkpointSha: string): Promise<unknown>;
+  materializeAt(checkpointSha: string): Promise<WarpStateV5>;
 
   /**
    * Logical graph traversal helpers.
@@ -1654,8 +1716,12 @@ export default class WarpGraph {
 
   /**
    * Materializes the current graph state from all patches.
+   *
+   * When `options.receipts` is true, returns `{ state, receipts }`.
+   * Otherwise returns the WarpStateV5 directly.
    */
-  materialize(): Promise<unknown>;
+  materialize(options: { receipts: true; ceiling?: number | null }): Promise<{ state: WarpStateV5; receipts: TickReceipt[] }>;
+  materialize(options?: { receipts?: false; ceiling?: number | null }): Promise<WarpStateV5>;
 
   /**
    * Starts a built-in sync server for this graph.
@@ -1672,6 +1738,8 @@ export default class WarpGraph {
 
   /**
    * Syncs with a remote peer (HTTP URL or another WarpGraph instance).
+   *
+   * When `options.materialize` is true, the returned object also contains a `state` property.
    */
   syncWith(remote: string | WarpGraph, options?: {
     path?: string;
@@ -1688,7 +1756,9 @@ export default class WarpGraph {
       error?: Error;
     }) => void;
     auth?: SyncAuthClientOptions;
-  }): Promise<{ applied: number; attempts: number }>;
+    /** Auto-materialize after sync; when true, result includes `state` */
+    materialize?: boolean;
+  }): Promise<{ applied: number; attempts: number; state?: WarpStateV5 }>;
 
   /**
    * Creates a fork of this graph at a specific point in a writer's history.
@@ -2113,17 +2183,7 @@ export function migrateV4toV5(v4State: {
  */
 export interface PatchEntry {
   /** The decoded patch object */
-  patch: {
-    schema: 2 | 3;
-    writer: string;
-    lamport: number;
-    context: Record<string, number> | Map<string, number>;
-    ops: unknown[];
-    /** Node/edge IDs read by this patch (V2 provenance) */
-    reads?: string[];
-    /** Node/edge IDs written by this patch (V2 provenance) */
-    writes?: string[];
-  };
+  patch: PatchV2;
   /** The Git SHA of the patch commit */
   sha: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "11.2.1",
+  "version": "11.3.3",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -78,7 +78,7 @@
     "demo:down": "cd examples && docker compose down -v",
     "setup:hooks": "node scripts/setup-hooks.js",
     "prepare": "patch-package && node scripts/setup-hooks.js",
-    "prepack": "npm run lint && npm run test:local",
+    "prepack": "npm run lint && npm run test:local && npm run typecheck:consumer",
     "install:git-warp": "bash scripts/install-git-warp.sh",
     "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh",
     "test:node20": "docker compose -f docker-compose.test.yml --profile node20 run --build --rm test-node20",
@@ -89,6 +89,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:src": "tsc --noEmit -p tsconfig.src.json",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "typecheck:consumer": "tsc --noEmit -p test/type-check/tsconfig.json",
     "typecheck:policy": "node scripts/ts-policy-check.js"
   },
   "dependencies": {

package/src/domain/WarpGraph.js

@@ -95,6 +95,9 @@ export default class WarpGraph {
     /** @type {number} */
     this._patchesSinceCheckpoint = 0;
 
+    /** @type {number} */
+    this._maxObservedLamport = 0;
+
     /** @type {{every: number}|null} */
     this._checkpointPolicy = checkpointPolicy || null;
 
@@ -285,7 +288,7 @@ export default class WarpGraph {
     // Initialize audit service if enabled
     if (graph._audit) {
       graph._auditService = new AuditReceiptService({
-        persistence: /** @type {any} */ (persistence), // TODO(ts-cleanup): persistence implements full port union
+        persistence: /** @type {import('./types/WarpPersistence.js').CorePersistence} */ (persistence),
         graphName,
         writerId,
         codec: graph._codec,