@git-stunts/git-warp 11.2.1 → 11.3.3

package/bin/cli/commands/check.js

@@ -11,7 +11,7 @@ import { openGraph, applyCursorCeiling, emitCursorWarning, readCheckpointDate, c
 /** @param {Persistence} persistence */
 async function getHealth(persistence) {
   const clock = ClockAdapter.global();
-  const healthService = new HealthCheckService({ persistence: /** @type {*} */ (persistence), clock }); // TODO(ts-cleanup): narrow port type
+  const healthService = new HealthCheckService({ persistence: /** @type {import('../../../src/domain/types/WarpPersistence.js').CorePersistence} */ (/** @type {unknown} */ (persistence)), clock });
   return await healthService.getHealth();
 }
 
@@ -137,7 +137,7 @@ function getHookStatusForCheck(repoPath) {
 /**
  * Handles the `check` command: reports graph health, GC, and hook status.
  * @param {{options: CliOptions}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleCheck({ options }) {
   const { graph, graphName, persistence } = await openGraph(options);

package/bin/cli/commands/doctor/checks.js

@@ -24,7 +24,7 @@ import { CODES } from './codes.js';
 
 /**
  * @param {string} id
- * @param {*} err TODO(ts-cleanup): narrow error type
+ * @param {unknown} err
  * @returns {DoctorFinding}
  */
 function internalError(id, err) {
@@ -33,7 +33,7 @@ function internalError(id, err) {
     status: 'fail',
     code: CODES.CHECK_INTERNAL_ERROR,
     impact: 'data_integrity',
-    message: `Internal error: ${err?.message || String(err)}`,
+    message: `Internal error: ${err instanceof Error ? err.message : String(err)}`,
   };
 }
 
@@ -43,7 +43,7 @@ function internalError(id, err) {
 export async function checkRepoAccessible(ctx) {
   try {
     const clock = ClockAdapter.global();
-    const svc = new HealthCheckService({ persistence: /** @type {*} TODO(ts-cleanup): narrow port type */ (ctx.persistence), clock });
+    const svc = new HealthCheckService({ persistence: /** @type {import('../../../../src/domain/types/WarpPersistence.js').CorePersistence} */ (/** @type {unknown} */ (ctx.persistence)), clock });
     const health = await svc.getHealth();
     if (health.components.repository.status === 'unhealthy') {
       return {
@@ -56,7 +56,7 @@ export async function checkRepoAccessible(ctx) {
       id: 'repo-accessible', status: 'ok', code: CODES.REPO_OK,
       impact: 'operability', message: 'Repository is accessible',
     };
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return internalError('repo-accessible', err);
   }
 }
@@ -104,7 +104,7 @@ export async function checkRefsConsistent(ctx) {
       });
     }
     return findings;
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return [internalError('refs-consistent', err)];
   }
 }
@@ -151,7 +151,7 @@ export async function checkCoverageComplete(ctx) {
       id: 'coverage-complete', status: 'ok', code: CODES.COVERAGE_OK,
       impact: 'operability', message: 'Coverage anchor includes all writers',
     };
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return internalError('coverage-complete', err);
   }
 }
@@ -192,7 +192,7 @@ export async function checkCheckpointFresh(ctx) {
 
     const { date, ageHours } = await getCheckpointAge(ctx.persistence, sha);
     return buildCheckpointFinding({ sha, date, ageHours, maxAge: ctx.policy.checkpointMaxAgeHours });
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return internalError('checkpoint-fresh', err);
   }
 }
@@ -290,7 +290,7 @@ export async function checkAuditConsistent(ctx) {
       });
     }
     return findings;
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return [internalError('audit-consistent', err)];
   }
 }
@@ -350,7 +350,7 @@ export async function checkClockSkew(ctx) {
       message: `Clock skew is within threshold (${Math.round(spreadMs / 1000)}s)`,
       evidence: { spreadMs },
     };
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return internalError('clock-skew', err);
   }
 }
@@ -367,13 +367,13 @@ export async function checkHooksInstalled(ctx) {
     const installer = createHookInstaller();
     const s = installer.getHookStatus(ctx.repoPath);
     return buildHookFinding(s);
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): narrow error type
+  } catch (err) {
     return internalError('hooks-installed', err);
   }
 }
 
 /**
- * @param {*} s TODO(ts-cleanup): narrow hook status type
+ * @param {{ installed: boolean, version?: string, current?: boolean, foreign?: boolean, hookPath: string }} s
  * @returns {DoctorFinding}
  */
 function buildHookFinding(s) {
@@ -396,7 +396,7 @@ function buildHookFinding(s) {
       id: 'hooks-installed', status: 'warn', code: CODES.HOOKS_OUTDATED,
       impact: 'hygiene', message: `Hook is outdated (v${s.version})`,
       fix: 'Run `git warp install-hooks` to upgrade',
-      evidence: { version: s.version },
+      evidence: { version: s.version ?? null },
     };
   }
   return {

package/bin/cli/commands/doctor/index.js

@@ -160,7 +160,7 @@ async function runChecks(ctx, startMs) {
         f.durationMs = checkDuration;
         findings.push(f);
       }
-    } catch (/** @type {*} TODO(ts-cleanup): narrow error type */ err) {
+    } catch (err) {
       checkDuration = checkDuration ?? 0;
       checksRun++;
       findings.push({
@@ -168,7 +168,7 @@ async function runChecks(ctx, startMs) {
         status: 'fail',
         code: CODES.CHECK_INTERNAL_ERROR,
         impact: 'data_integrity',
-        message: `Internal error in ${check.id}: ${err?.message || String(err)}`,
+        message: `Internal error in ${check.id}: ${err instanceof Error ? err.message : String(err)}`,
         durationMs: checkDuration,
       });
     }

package/bin/cli/commands/doctor/types.js

@@ -6,7 +6,7 @@
 
 // ── JSON-safe recursive value type ──────────────────────────────────────────
 
-/** @typedef {null | boolean | number | string | Array<*> | {[k:string]: *}} JsonValue */ // TODO(ts-cleanup): recursive type
+/** @typedef {null | boolean | number | string | Array<unknown> | {[k:string]: unknown}} JsonValue */
 
 /** @typedef {{[k:string]: JsonValue}} FindingEvidence */
 

package/bin/cli/commands/history.js

@@ -4,6 +4,7 @@ import { historySchema } from '../schemas.js';
 import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
 
 /** @typedef {import('../types.js').CliOptions} CliOptions */
+/** @typedef {{patch: {schema?: number, lamport: number, ops?: Array<{type: string, node?: string, from?: string, to?: string}>}, sha: string}} PatchEntry */
 
 const HISTORY_OPTIONS = {
   node: { type: 'string' },
@@ -16,7 +17,7 @@ function parseHistoryArgs(args) {
 }
 
 /**
- * @param {*} patch
+ * @param {{ops?: Array<{node?: string, from?: string, to?: string}>}} patch
  * @param {string} nodeId
  */
 function patchTouchesNode(patch, nodeId) {
@@ -35,7 +36,7 @@ function patchTouchesNode(patch, nodeId) {
 /**
  * Handles the `history` command: shows patch history for a writer.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleHistory({ options, args }) {
   const historyOptions = parseHistoryArgs(args);
@@ -46,15 +47,21 @@ export default async function handleHistory({ options, args }) {
   const writerId = options.writer;
   let patches = await graph.getWriterPatches(writerId);
   if (cursorInfo.active) {
-    patches = patches.filter((/** @type {*} */ { patch }) => patch.lamport <= /** @type {number} */ (cursorInfo.tick)); // TODO(ts-cleanup): type CLI payload
+    patches = patches.filter((/** @type {PatchEntry} */ { patch }) => patch.lamport <= /** @type {number} */ (cursorInfo.tick));
   }
   if (patches.length === 0) {
+    const knownWriters = await graph.discoverWriters();
+    if (knownWriters.length > 0) {
+      throw notFoundError(
+        `No patches found for writer: ${writerId}\nKnown writers: ${knownWriters.join(', ')}\nUse: warp-graph history --writer <id>`
+      );
+    }
     throw notFoundError(`No patches found for writer: ${writerId}`);
   }
 
   const entries = patches
-    .filter((/** @type {*} */ { patch }) => !historyOptions.node || patchTouchesNode(patch, historyOptions.node)) // TODO(ts-cleanup): type CLI payload
-    .map((/** @type {*} */ { patch, sha }) => ({ // TODO(ts-cleanup): type CLI payload
+    .filter((/** @type {PatchEntry} */ { patch }) => !historyOptions.node || patchTouchesNode(patch, historyOptions.node))
+    .map((/** @type {PatchEntry} */ { patch, sha }) => ({
       sha,
       schema: patch.schema,
       lamport: patch.lamport,

package/bin/cli/commands/install-hooks.js

@@ -18,7 +18,7 @@ function parseInstallHooksArgs(args) {
 }
 
 /**
- * @param {*} classification
+ * @param {{kind: string, version?: string, appended?: boolean}} classification
  * @param {{force: boolean}} hookOptions
  */
 async function resolveStrategy(classification, hookOptions) {
@@ -37,7 +37,7 @@ async function resolveStrategy(classification, hookOptions) {
   return await promptForForeignStrategy();
 }
 
-/** @param {*} classification */
+/** @param {{kind: string, version?: string, appended?: boolean}} classification */
 async function promptForOursStrategy(classification) {
   const installer = createHookInstaller();
   if (classification.version === installer._version) {
@@ -81,8 +81,8 @@ async function promptForForeignStrategy() {
 function readHookContent(hookPath) {
   try {
     return fs.readFileSync(hookPath, 'utf8');
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type fs error
-    if (err.code === 'ENOENT') {
+  } catch (err) {
+    if (err instanceof Error && /** @type {{code?: string}} */ (err).code === 'ENOENT') {
       return null;
     }
     throw err;
@@ -92,7 +92,7 @@ function readHookContent(hookPath) {
 /**
  * Handles the `install-hooks` command.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleInstallHooks({ options, args }) {
   const hookOptions = parseInstallHooksArgs(args);

package/bin/cli/commands/materialize.js

@@ -45,7 +45,7 @@ async function materializeOneGraph({ persistence, graphName, writerId, ceiling }
 /**
  * Handles the `materialize` command: materializes and checkpoints all graphs.
  * @param {{options: CliOptions}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleMaterialize({ options }) {
   const { persistence } = await createPersistence(options.repo);
@@ -91,7 +91,7 @@ export default async function handleMaterialize({ options }) {
     }
   }
 
-  const allFailed = results.every((r) => /** @type {*} */ (r).error); // TODO(ts-cleanup): type CLI payload
+  const allFailed = results.every((r) => 'error' in r);
   return {
     payload: { graphs: results },
     exitCode: allFailed ? EXIT_CODES.INTERNAL : EXIT_CODES.OK,

package/bin/cli/commands/patch.js

@@ -0,0 +1,142 @@
+import { EXIT_CODES, usageError, notFoundError, parseCommandArgs } from '../infrastructure.js';
+import { openGraph } from '../shared.js';
+import { z } from 'zod';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const PATCH_OPTIONS = {
+  writer: { type: 'string' },
+  limit: { type: 'string' },
+};
+
+const patchSchema = z.object({
+  writer: z.string().optional(),
+  limit: z.coerce.number().int().positive().optional(),
+}).strict();
+
+/**
+ * Collects all patches across all writers (or a single writer).
+ * @param {import('../types.js').WarpGraphInstance} graph
+ * @param {string|null} writerFilter
+ * @returns {Promise<Array<{sha: string, writer: string, patch: {schema?: number, lamport: number, ops?: Array<Record<string, unknown>>, context?: Record<string, unknown>}}>>}
+ */
+async function collectPatches(graph, writerFilter) {
+  const writers = writerFilter ? [writerFilter] : await graph.discoverWriters();
+  const all = [];
+  for (const writerId of writers) {
+    const patches = await graph.getWriterPatches(writerId);
+    for (const { patch, sha } of patches) {
+      all.push({ sha, writer: writerId, patch });
+    }
+  }
+  // Sort by lamport ascending
+  all.sort((a, b) => (a.patch.lamport ?? 0) - (b.patch.lamport ?? 0));
+  return all;
+}
+
+/**
+ * Handles the `patch` command: show or list decoded patches.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+export default async function handlePatch({ options, args }) {
+  // First positional is the subaction: show or list
+  const subaction = args[0];
+  const rest = args.slice(1);
+
+  if (subaction === 'show') {
+    return await handlePatchShow({ options, args: rest });
+  }
+  if (subaction === 'list') {
+    return await handlePatchList({ options, args: rest });
+  }
+  if (!subaction) {
+    throw usageError('Usage: warp-graph patch <show|list> [options]\n  show <sha>   Decode and display a single patch\n  list         List all patches');
+  }
+  throw usageError(`Unknown patch subaction: ${subaction}. Use: show, list`);
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+async function handlePatchShow({ options, args }) {
+  if (!args[0]) {
+    throw usageError('Usage: warp-graph patch show <sha>');
+  }
+  const targetSha = args[0];
+  const { graph, graphName } = await openGraph(options);
+  const allPatches = await collectPatches(graph, null);
+
+  const match = allPatches.find((p) => p.sha === targetSha || p.sha.startsWith(targetSha));
+  if (!match) {
+    throw notFoundError(`Patch not found: ${targetSha}`);
+  }
+
+  const payload = {
+    graph: graphName,
+    sha: match.sha,
+    writer: match.writer,
+    lamport: match.patch.lamport,
+    schema: match.patch.schema,
+    ops: match.patch.ops,
+    context: match.patch.context,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+async function handlePatchList({ options, args }) {
+  const { values } = parseCommandArgs(args, PATCH_OPTIONS, patchSchema);
+  const { graph, graphName } = await openGraph(options);
+  const writerFilter = values.writer || null;
+  const allPatches = await collectPatches(graph, writerFilter);
+
+  const limit = values.limit ?? allPatches.length;
+  const entries = allPatches.slice(0, limit).map((p) => ({
+    sha: p.sha.slice(0, 7),
+    fullSha: p.sha,
+    writer: p.writer,
+    lamport: p.patch.lamport,
+    opCount: Array.isArray(p.patch.ops) ? p.patch.ops.length : 0,
+    nodeIds: extractNodeIds(p.patch.ops || []),
+  }));
+
+  const payload = {
+    graph: graphName,
+    total: allPatches.length,
+    showing: entries.length,
+    writerFilter,
+    entries,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}
+
+/**
+ * Extracts unique node IDs touched by a patch's operations.
+ * @param {Array<Record<string, unknown>>} ops
+ * @returns {string[]}
+ */
+function extractNodeIds(ops) {
+  if (!Array.isArray(ops)) {
+    return [];
+  }
+  const ids = new Set();
+  for (const op of ops) {
+    if (op.node) {
+      ids.add(op.node);
+    }
+    if (op.from) {
+      ids.add(op.from);
+    }
+    if (op.to) {
+      ids.add(op.to);
+    }
+  }
+  return [...ids].sort();
+}

package/bin/cli/commands/path.js

@@ -43,7 +43,7 @@ function parsePathArgs(args) {
 /**
  * Handles the `path` command: finds a shortest path between two nodes.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handlePath({ options, args }) {
   const pathOptions = parsePathArgs(args);
@@ -77,10 +77,10 @@ export default async function handlePath({ options, args }) {
 
     return {
       payload,
-      exitCode: result.found ? EXIT_CODES.OK : EXIT_CODES.NOT_FOUND,
+      exitCode: result.found ? EXIT_CODES.OK : EXIT_CODES.NO_MATCH,
     };
-  } catch (/** @type {*} */ error) { // TODO(ts-cleanup): type error
-    if (error && error.code === 'NODE_NOT_FOUND') {
+  } catch (error) {
+    if (error instanceof Error && /** @type {{code?: string}} */ (error).code === 'NODE_NOT_FOUND') {
       throw notFoundError(error.message);
     }
     throw error;

package/bin/cli/commands/query.js

@@ -6,6 +6,7 @@ import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
 import { querySchema } from '../schemas.js';
 
 /** @typedef {import('../types.js').CliOptions} CliOptions */
+/** @typedef {import('../types.js').QueryBuilderLike} QueryBuilderLike */
 
 const QUERY_OPTIONS = {
   match: { type: 'string' },
@@ -85,7 +86,7 @@ function parseQueryArgs(args) {
 }
 
 /**
- * @param {*} builder
+ * @param {QueryBuilderLike} builder
  * @param {Array<{type: string, label?: string, key?: string, value?: string}>} steps
  */
 function applyQuerySteps(builder, steps) {
@@ -97,7 +98,7 @@ function applyQuerySteps(builder, steps) {
 }
 
 /**
- * @param {*} builder
+ * @param {QueryBuilderLike} builder
  * @param {{type: string, label?: string, key?: string, value?: string}} step
  */
 function applyQueryStep(builder, step) {
@@ -108,13 +109,13 @@ function applyQueryStep(builder, step) {
     return builder.incoming(step.label);
   }
   if (step.type === 'where-prop') {
-    return builder.where((/** @type {*} */ node) => matchesPropFilter(node, /** @type {string} */ (step.key), /** @type {string} */ (step.value))); // TODO(ts-cleanup): type CLI payload
+    return builder.where((/** @type {{props?: Record<string, unknown>}} */ node) => matchesPropFilter(node, /** @type {string} */ (step.key), /** @type {string} */ (step.value)));
   }
   return builder;
 }
 
 /**
- * @param {*} node
+ * @param {{props?: Record<string, unknown>}} node
  * @param {string} key
  * @param {string} value
  */
@@ -126,22 +127,62 @@ function matchesPropFilter(node, key, value) {
   return String(props[key]) === value;
 }
 
+/**
+ * Builds a map of nodeId -> {outgoing: [], incoming: []} from edges.
+ * @param {Array<{from: string, to: string, label?: string}>} edges
+ * @returns {Map<string, {outgoing: Array<{label: string, to: string}>, incoming: Array<{label: string, from: string}>}>}
+ */
+function buildEdgeMap(edges) {
+  /** @type {Map<string, {outgoing: Array<{label: string, to: string}>, incoming: Array<{label: string, from: string}>}>} */
+  const edgeMap = new Map();
+  for (const edge of edges) {
+    if (!edgeMap.has(edge.from)) {
+      edgeMap.set(edge.from, { outgoing: [], incoming: [] });
+    }
+    if (!edgeMap.has(edge.to)) {
+      edgeMap.set(edge.to, { outgoing: [], incoming: [] });
+    }
+    const fromEntry = edgeMap.get(edge.from);
+    const toEntry = edgeMap.get(edge.to);
+    if (fromEntry) {
+      fromEntry.outgoing.push({ label: edge.label || '', to: edge.to });
+    }
+    if (toEntry) {
+      toEntry.incoming.push({ label: edge.label || '', from: edge.from });
+    }
+  }
+  return edgeMap;
+}
+
 /**
  * @param {string} graphName
- * @param {*} result
- * @returns {{graph: string, stateHash: *, nodes: *, _renderedSvg?: string, _renderedAscii?: string}}
+ * @param {{nodes: Array<{id: string, props?: Record<string, unknown>}>, stateHash?: string}} result
+ * @param {Array<{from: string, to: string, label?: string}>} edges
+ * @returns {{graph: string, stateHash: string|undefined, nodes: Array<{id: string, props?: Record<string, unknown>} & Record<string, unknown>>, [k: string]: unknown}}
  */
-function buildQueryPayload(graphName, result) {
+function buildQueryPayload(graphName, result, edges) {
+  const edgeMap = buildEdgeMap(edges);
+
+  const nodes = result.nodes.map((/** @type {{id: string, props?: Record<string, unknown>}} */ node) => {
+    /** @type {{id: string, props?: Record<string, unknown>} & Record<string, unknown>} */
+    const entry = { ...node };
+    const nodeEdges = edgeMap.get(node.id);
+    if (nodeEdges) {
+      entry.edges = nodeEdges;
+    }
+    return entry;
+  });
+
   return {
     graph: graphName,
     stateHash: result.stateHash,
-    nodes: result.nodes,
+    nodes,
   };
 }
 
-/** @param {*} error */
+/** @param {unknown} error */
 function mapQueryError(error) {
-  if (error && error.code && String(error.code).startsWith('E_QUERY')) {
+  if (error instanceof Error && /** @type {{code?: string}} */ (error).code?.startsWith('E_QUERY')) {
     throw usageError(error.message);
   }
   throw error;
@@ -150,7 +191,7 @@ function mapQueryError(error) {
 /**
  * Handles the `query` command: runs a logical graph query.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleQuery({ options, args }) {
   const querySpec = parseQueryArgs(args);
@@ -171,10 +212,10 @@ export default async function handleQuery({ options, args }) {
 
   try {
     const result = await builder.run();
-    const payload = buildQueryPayload(graphName, result);
+    const edges = await graph.getEdges();
+    const payload = buildQueryPayload(graphName, result, edges);
 
     if (options.view) {
-      const edges = await graph.getEdges();
       const graphData = queryResultToGraphData(payload, edges);
       const positioned = await layoutGraph(graphData, { type: 'query' });
       if (typeof options.view === 'string' && (options.view.startsWith('svg:') || options.view.startsWith('html:'))) {

package/bin/cli/commands/registry.js

@@ -10,6 +10,8 @@ import handleVerifyAudit from './verify-audit.js';
 import handleView from './view.js';
 import handleInstallHooks from './install-hooks.js';
 import handleTrust from './trust.js';
+import handlePatch from './patch.js';
+import handleTree from './tree.js';
 
 /** @type {Map<string, Function>} */
 export const COMMANDS = new Map(/** @type {[string, Function][]} */ ([
@@ -23,6 +25,8 @@ export const COMMANDS = new Map(/** @type {[string, Function][]} */ ([
   ['seek', handleSeek],
   ['verify-audit', handleVerifyAudit],
   ['trust', handleTrust],
+  ['patch', handlePatch],
+  ['tree', handleTree],
   ['view', handleView],
   ['install-hooks', handleInstallHooks],
 ]));

package/bin/cli/commands/seek.js

@@ -17,6 +17,7 @@ import { openGraph, readActiveCursor, writeActiveCursor, wireSeekCache } from '.
 /** @typedef {import('../types.js').WriterTickInfo} WriterTickInfo */
 /** @typedef {import('../types.js').CursorBlob} CursorBlob */
 /** @typedef {import('../types.js').SeekSpec} SeekSpec */
+/** @typedef {import('../../../src/domain/services/StateDiff.js').StateDiffResult} StateDiffResult */
 
 // ============================================================================
 // Cursor I/O Helpers (seek-only)
@@ -257,18 +258,19 @@ function computeSeekStateDiff(prevCursor, next, frontierHash) {
 
 /**
  * @param {{tick: number, perWriter: Map<string, WriterTickInfo>, graph: WarpGraphInstance}} params
- * @returns {Promise<Record<string, {sha: string, opSummary: *}>|null>}
+ * @returns {Promise<Record<string, {sha: string, opSummary: unknown}>|null>}
  */
 async function buildTickReceipt({ tick, perWriter, graph }) {
   if (!Number.isInteger(tick) || tick <= 0) {
     return null;
   }
 
-  /** @type {Record<string, {sha: string, opSummary: *}>} */
+  /** @type {Record<string, {sha: string, opSummary: unknown}>} */
   const receipt = {};
 
   for (const [writerId, info] of perWriter) {
-    const sha = /** @type {*} */ (info?.tickShas)?.[tick]; // TODO(ts-cleanup): type CLI payload
+    const tickShas = /** @type {Record<number, string> | undefined} */ (info?.tickShas);
+    const sha = tickShas?.[tick];
     if (!sha) {
       continue;
     }
@@ -283,7 +285,7 @@ async function buildTickReceipt({ tick, perWriter, graph }) {
 
 /**
  * @param {{graph: WarpGraphInstance, prevTick: number|null, currentTick: number, diffLimit: number}} params
- * @returns {Promise<{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}>}
+ * @returns {Promise<{structuralDiff: unknown, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}>}
  */
 async function computeStructuralDiff({ graph, prevTick, currentTick, diffLimit }) {
   let beforeState = null;
@@ -303,18 +305,22 @@ async function computeStructuralDiff({ graph, prevTick, currentTick, diffLimit }
   }
 
   await graph.materialize({ ceiling: currentTick });
-  const afterState = /** @type {*} */ (await graph.getStateSnapshot()); // TODO(ts-cleanup): narrow WarpStateV5
+  const afterState = await graph.getStateSnapshot();
+  if (!afterState) {
+    const empty = { nodes: { added: [], removed: [] }, edges: { added: [], removed: [] }, props: { set: [], removed: [] } };
+    return applyDiffLimit(empty, diffBaseline, baselineTick, diffLimit);
+  }
   const diff = diffStates(beforeState, afterState);
 
   return applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit);
 }
 
 /**
- * @param {*} diff
+ * @param {StateDiffResult} diff
  * @param {string} diffBaseline
  * @param {number|null} baselineTick
  * @param {number} diffLimit
- * @returns {{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}}
+ * @returns {{structuralDiff: StateDiffResult, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}}
  */
 function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   const totalChanges =
@@ -327,7 +333,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   }
 
   let remaining = diffLimit;
-  const cap = (/** @type {any[]} */ arr) => {
+  const cap = (/** @type {unknown[]} */ arr) => {
     const take = Math.min(arr.length, remaining);
     remaining -= take;
     return arr.slice(0, take);
@@ -340,7 +346,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   };
 
   const shownChanges = diffLimit - remaining;
-  return { structuralDiff: capped, diffBaseline, baselineTick, truncated: true, totalChanges, shownChanges };
+  return { structuralDiff: /** @type {StateDiffResult} */ (capped), diffBaseline, baselineTick, truncated: true, totalChanges, shownChanges };
 }
 
 // ============================================================================
@@ -349,7 +355,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
 
 /**
  * @param {{graph: WarpGraphInstance, graphName: string, persistence: Persistence, activeCursor: CursorBlob|null, ticks: number[], maxTick: number, perWriter: Map<string, WriterTickInfo>, frontierHash: string}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 async function handleSeekStatus({ graph, graphName, persistence, activeCursor, ticks, maxTick, perWriter, frontierHash }) {
   if (activeCursor) {
@@ -411,7 +417,7 @@ async function handleSeekStatus({ graph, graphName, persistence, activeCursor, t
 /**
  * Handles the `git warp seek` command across all sub-actions.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleSeek({ options, args }) {
   const seekSpec = parseSeekArgs(args);