@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/state/schema.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 export const STATE_APPLICATION_ID = 0x50495746;
 export const STATE_SCHEMA_NAME = "pi-workflows-state";
 export const STATE_SCHEMA_VERSION = 1;
-export const STATE_APP_VERSION = "0.13.3";
+export const STATE_APP_VERSION = "0.14.0";
 
 export const STATE_SCHEMA_SQL = String.raw`
 CREATE TABLE schema_meta (
@@ -22,6 +22,28 @@ CREATE TABLE projects (
   created_at INTEGER NOT NULL
 ) STRICT;
 
+CREATE TABLE workflow_host_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  epoch INTEGER NOT NULL DEFAULT 0 CHECK (epoch >= 0),
+  host_id TEXT,
+  token_hash BLOB CHECK (token_hash IS NULL OR length(token_hash) = 32),
+  pid INTEGER CHECK (pid IS NULL OR pid > 0),
+  process_start_identity TEXT,
+  started_at INTEGER,
+  heartbeat_at INTEGER,
+  expires_at INTEGER,
+  CHECK (
+    (host_id IS NULL AND token_hash IS NULL AND pid IS NULL AND process_start_identity IS NULL
+      AND started_at IS NULL AND heartbeat_at IS NULL AND expires_at IS NULL)
+    OR
+    (host_id IS NOT NULL AND token_hash IS NOT NULL AND pid IS NOT NULL
+      AND process_start_identity IS NOT NULL AND started_at IS NOT NULL
+      AND heartbeat_at IS NOT NULL AND expires_at IS NOT NULL)
+  )
+) STRICT;
+
+INSERT INTO workflow_host_state(id, epoch) VALUES (1, 0);
+
 CREATE TABLE blobs (
   blob_hash BLOB PRIMARY KEY CHECK (length(blob_hash) = 32),
   media_type TEXT NOT NULL,
@@ -115,6 +137,39 @@ CREATE INDEX runs_project_idx ON runs(project_id, created_at DESC);
 CREATE INDEX runs_status_idx ON runs(status, updated_at DESC);
 CREATE INDEX runs_parent_idx ON runs(parent_run_id);
 
+CREATE TABLE viewer_runs (
+  run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
+  presentation_revision INTEGER NOT NULL CHECK (presentation_revision >= 1),
+  retained_from_revision INTEGER NOT NULL CHECK (
+    retained_from_revision >= 1 AND retained_from_revision <= presentation_revision
+  ),
+  updated_at INTEGER NOT NULL
+) STRICT;
+
+CREATE TABLE viewer_deltas (
+  run_id TEXT NOT NULL REFERENCES viewer_runs(run_id) ON DELETE CASCADE,
+  presentation_revision INTEGER NOT NULL CHECK (presentation_revision >= 1),
+  delta_index INTEGER NOT NULL CHECK (delta_index >= 0),
+  target_type TEXT NOT NULL CHECK (target_type IN (
+    'summary', 'graph', 'replay', 'timeline', 'conversation', 'inspector'
+  )),
+  target_key TEXT NOT NULL,
+  patch_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  recorded_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, presentation_revision, delta_index)
+) STRICT;
+
+CREATE INDEX viewer_deltas_resume_idx
+  ON viewer_deltas(run_id, presentation_revision, delta_index);
+
+CREATE TABLE viewer_session_checkpoints (
+  run_id TEXT NOT NULL REFERENCES viewer_runs(run_id) ON DELETE CASCADE,
+  event_seq INTEGER NOT NULL CHECK (event_seq > 0),
+  state_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  recorded_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, event_seq)
+) STRICT;
+
 CREATE TABLE run_sources (
   run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
   mount_path TEXT NOT NULL,
@@ -240,6 +295,70 @@ CREATE INDEX run_queue_claim_idx ON run_queue(status, available_at, created_at);
 CREATE UNIQUE INDEX run_queue_active_session_idx ON run_queue(origin_session_id)
 WHERE status IN ('queued', 'starting', 'running');
 
+CREATE TABLE host_commands (
+  request_id TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  operation TEXT NOT NULL CHECK (operation IN (
+    'run.start', 'run.pause', 'run.resume', 'run.cancel', 'run.status', 'run.list',
+    'checkpoint.answer', 'decision.answer', 'interaction.submit', 'interaction.update',
+    'notification.claim', 'notification.deliver', 'turn.claim', 'turn.resolve',
+    'controller.list', 'controller.get', 'controller.apply', 'controller.reconcile', 'controller.delete',
+    'host.status', 'host.stop'
+  )),
+  idempotency_key TEXT NOT NULL,
+  request_fingerprint BLOB NOT NULL CHECK (length(request_fingerprint) = 32),
+  run_id TEXT REFERENCES runs(run_id) ON DELETE SET NULL,
+  accepted_revision INTEGER CHECK (accepted_revision IS NULL OR accepted_revision >= 0),
+  outcome TEXT NOT NULL CHECK (outcome IN (
+    'accepted', 'adopted', 'rejected', 'conflict', 'notFound', 'claimLost', 'unavailable'
+  )),
+  receipt_hash BLOB REFERENCES blobs(blob_hash),
+  error_hash BLOB REFERENCES blobs(blob_hash),
+  host_epoch INTEGER NOT NULL CHECK (host_epoch > 0),
+  created_at INTEGER NOT NULL,
+  completed_at INTEGER NOT NULL,
+  UNIQUE (client_id, idempotency_key)
+) STRICT;
+
+CREATE INDEX host_commands_run_idx ON host_commands(run_id, created_at);
+
+CREATE TABLE run_workers (
+  worker_epoch TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  generation INTEGER NOT NULL CHECK (generation > 0),
+  host_epoch INTEGER NOT NULL CHECK (host_epoch > 0),
+  launch_envelope_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  pid INTEGER,
+  process_start_identity TEXT,
+  status TEXT NOT NULL CHECK (status IN (
+    'starting', 'ready', 'running', 'exited', 'cancelled', 'timedOut',
+    'crashed', 'claimLost', 'orphaned'
+  )),
+  started_at INTEGER NOT NULL,
+  ready_at INTEGER,
+  finished_at INTEGER,
+  exit_code INTEGER,
+  signal TEXT,
+  diagnostic_hash BLOB REFERENCES blobs(blob_hash),
+  CHECK ((pid IS NULL) = (process_start_identity IS NULL))
+) STRICT;
+
+CREATE UNIQUE INDEX run_workers_active_idx ON run_workers(run_id)
+WHERE status IN ('starting', 'ready', 'running');
+CREATE INDEX run_workers_generation_idx ON run_workers(run_id, generation, started_at);
+
+CREATE TABLE worker_messages (
+  worker_epoch TEXT NOT NULL REFERENCES run_workers(worker_epoch) ON DELETE CASCADE,
+  message_id TEXT NOT NULL,
+  request_fingerprint BLOB NOT NULL CHECK (length(request_fingerprint) = 32),
+  outcome TEXT NOT NULL CHECK (outcome IN ('accepted', 'adopted', 'rejected', 'claimLost')),
+  accepted_revision INTEGER CHECK (accepted_revision IS NULL OR accepted_revision >= 0),
+  result_hash BLOB REFERENCES blobs(blob_hash),
+  error_hash BLOB REFERENCES blobs(blob_hash),
+  completed_at INTEGER NOT NULL,
+  PRIMARY KEY (worker_epoch, message_id)
+) STRICT;
+
 CREATE TABLE node_attempts (
   attempt_id TEXT PRIMARY KEY,
   run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
@@ -268,6 +387,7 @@ CREATE TABLE node_attempts (
 CREATE UNIQUE INDEX node_attempts_active_idx ON node_attempts(run_id)
 WHERE status IN ('pending', 'running', 'waiting');
 CREATE INDEX node_attempts_run_idx ON node_attempts(run_id, created_at);
+CREATE INDEX node_attempts_deadline_idx ON node_attempts(deadline_at) WHERE deadline_at IS NOT NULL;
 
 CREATE TABLE run_steps (
   run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
@@ -314,14 +434,19 @@ CREATE INDEX session_segments_run_idx ON session_segments(run_id, created_at);
 
 CREATE TABLE session_entries (
   segment_id TEXT NOT NULL REFERENCES session_segments(segment_id) ON DELETE CASCADE,
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
   entry_seq INTEGER NOT NULL CHECK (entry_seq > 0),
+  run_seq INTEGER NOT NULL CHECK (run_seq > 0),
   entry_id TEXT NOT NULL,
   entry_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   recorded_at INTEGER NOT NULL,
   PRIMARY KEY (segment_id, entry_seq),
-  UNIQUE (segment_id, entry_id)
+  UNIQUE (segment_id, entry_id),
+  UNIQUE (run_id, run_seq)
 ) STRICT;
 
+CREATE INDEX session_entries_run_idx ON session_entries(run_id, run_seq);
+
 CREATE TABLE attempt_entries (
   attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
   role TEXT NOT NULL CHECK (role IN ('prompt', 'response', 'first', 'last')),
@@ -336,7 +461,9 @@ CREATE INDEX attempt_entries_entry_idx ON attempt_entries(segment_id, entry_id);
 
 CREATE TABLE session_events (
   segment_id TEXT NOT NULL REFERENCES session_segments(segment_id) ON DELETE CASCADE,
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
   event_seq INTEGER NOT NULL CHECK (event_seq > 0),
+  run_seq INTEGER NOT NULL CHECK (run_seq > 0),
   event_type TEXT NOT NULL,
   node_id TEXT,
   attempt_id TEXT,
@@ -345,9 +472,12 @@ CREATE TABLE session_events (
   tool_call_id TEXT,
   payload_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   recorded_at INTEGER NOT NULL,
-  PRIMARY KEY (segment_id, event_seq)
+  PRIMARY KEY (segment_id, event_seq),
+  UNIQUE (run_id, run_seq)
 ) STRICT;
 
+CREATE INDEX session_events_run_idx ON session_events(run_id, run_seq);
+
 CREATE TABLE human_decisions (
   decision_id TEXT PRIMARY KEY,
   resource_id TEXT NOT NULL UNIQUE REFERENCES resources(resource_id),
@@ -369,6 +499,44 @@ CREATE TABLE human_decisions (
 CREATE INDEX human_decisions_run_idx ON human_decisions(run_id, created_at);
 CREATE INDEX human_decisions_deadline_idx ON human_decisions(deadline_at) WHERE deadline_at IS NOT NULL;
 
+CREATE TABLE interactive_requests (
+  request_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  attempt_id TEXT NOT NULL UNIQUE REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
+  target_session_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('agent', 'assistant', 'decision')),
+  contract_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
+  status TEXT NOT NULL CHECK (status IN ('pending', 'presenting', 'settled', 'cancelled')),
+  presenter_id TEXT,
+  presentation_claim_expires_at INTEGER,
+  presentation_session_entry_id TEXT,
+  accepted_submission_id TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  settled_at INTEGER,
+  consumed_at INTEGER,
+  CHECK ((status = 'settled') = (accepted_submission_id IS NOT NULL AND settled_at IS NOT NULL)),
+  CHECK ((presenter_id IS NULL) = (presentation_claim_expires_at IS NULL)),
+  CHECK (presenter_id IS NULL OR status = 'presenting'),
+  CHECK (consumed_at IS NULL OR status = 'settled')
+) STRICT;
+
+CREATE INDEX interactive_requests_session_idx
+  ON interactive_requests(target_session_id, status, created_at);
+
+CREATE TABLE interactive_submissions (
+  submission_id TEXT PRIMARY KEY,
+  request_id TEXT NOT NULL REFERENCES interactive_requests(request_id) ON DELETE CASCADE,
+  idempotency_key TEXT NOT NULL,
+  request_revision INTEGER NOT NULL CHECK (request_revision > 0),
+  payload_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  outcome TEXT NOT NULL CHECK (outcome IN ('validating', 'accepted', 'rejected', 'adopted')),
+  receipt_hash BLOB REFERENCES blobs(blob_hash),
+  submitted_at INTEGER NOT NULL,
+  UNIQUE (request_id, idempotency_key)
+) STRICT;
+
 CREATE TABLE human_decision_resolutions (
   decision_id TEXT PRIMARY KEY REFERENCES human_decisions(decision_id) ON DELETE CASCADE,
   outcome TEXT NOT NULL CHECK (outcome IN ('accepted', 'cancelled')),

package/src/state/viewer.ts

@@ -0,0 +1,356 @@
+import { StateDatabase } from "./database.js";
+import { canonicalJson, parseJson, type JsonValue } from "./json.js";
+
+export const VIEWER_DELTA_RETENTION = 256;
+export const VIEWER_PAGE_SIZE = 256;
+
+export type ViewerTargetType =
+  | "summary"
+  | "graph"
+  | "replay"
+  | "timeline"
+  | "conversation"
+  | "inspector";
+
+export type ViewerPatchOperation =
+  | { op: "add" | "replace"; path: string; value: JsonValue }
+  | { op: "remove"; path: string }
+  | { op: "append"; path: string; value: JsonValue[] };
+
+export type ViewerDeltaDraft = {
+  targetType: ViewerTargetType;
+  targetKey?: string;
+  patch?: ViewerPatchOperation[];
+};
+
+export type ViewerTailItem = JsonValue;
+
+export type ViewerDeltaRecord = {
+  runId: string;
+  presentationRevision: number;
+  deltaIndex: number;
+  targetType: ViewerTargetType;
+  targetKey: string;
+  patch: ViewerPatchOperation[];
+  recordedAt: number;
+};
+
+export type ViewerCursorResult =
+  | {
+      kind: "deltas";
+      currentRevision: number;
+      retainedFromRevision: number;
+      deltas: ViewerDeltaRecord[];
+    }
+  | {
+      kind: "snapshot_required";
+      currentRevision: number;
+      retainedFromRevision: number;
+    };
+
+type ViewerRunRow = {
+  presentationRevision: number;
+  retainedFromRevision: number;
+};
+
+type ViewerDeltaRow = {
+  runId: string;
+  presentationRevision: number;
+  deltaIndex: number;
+  targetType: string;
+  targetKey: string;
+  patchHash: Buffer;
+  recordedAt: number;
+};
+
+export function initializeViewerRun(state: StateDatabase, runId: string, now: number): number {
+  state.connection
+    .prepare(
+      `INSERT INTO viewer_runs(
+         run_id, presentation_revision, retained_from_revision, updated_at
+       ) VALUES (?, 1, 1, ?)
+       ON CONFLICT(run_id) DO NOTHING`,
+    )
+    .run(runId, now);
+  const row = state.connection
+    .prepare(
+      `SELECT presentation_revision AS presentationRevision,
+              retained_from_revision AS retainedFromRevision
+       FROM viewer_runs WHERE run_id = ?`,
+    )
+    .get(runId);
+  if (!isViewerRunRow(row)) {
+    throw new Error(`Viewer projection could not be initialized for workflow run: ${runId}`);
+  }
+  return row.presentationRevision;
+}
+
+export function recordViewerDeltas(
+  state: StateDatabase,
+  runId: string,
+  drafts: readonly ViewerDeltaDraft[],
+  now: number = Date.now(),
+): number {
+  if (!state.connection.inTransaction) {
+    throw new Error("Viewer changes must be recorded inside the durable state transaction");
+  }
+  if (drafts.length === 0) {
+    throw new Error("Viewer change must name at least one bounded target");
+  }
+  const row = state.connection
+    .prepare(
+      `SELECT presentation_revision AS presentationRevision,
+              retained_from_revision AS retainedFromRevision
+       FROM viewer_runs WHERE run_id = ?`,
+    )
+    .get(runId);
+  if (!isViewerRunRow(row)) {
+    throw new Error(`Viewer projection does not exist for workflow run: ${runId}`);
+  }
+  const revision = row.presentationRevision + 1;
+  for (const [index, draft] of drafts.entries()) {
+    const patch: ViewerPatchOperation[] = [
+      {
+        op: "replace",
+        path: "/presentationRevision",
+        value: revision,
+      },
+      ...(draft.targetType === "graph"
+        ? [
+            {
+              op: "replace" as const,
+              path: "/graphRevision",
+              value: revision,
+            },
+          ]
+        : []),
+      ...(draft.patch ?? []),
+    ];
+    const patchHash = state.putJson(patch, now);
+    state.connection
+      .prepare(
+        `INSERT INTO viewer_deltas(
+           run_id, presentation_revision, delta_index, target_type,
+           target_key, patch_hash, recorded_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(runId, revision, index, draft.targetType, draft.targetKey ?? "", patchHash, now);
+  }
+  const retainedFromRevision = Math.max(1, revision - VIEWER_DELTA_RETENTION + 1);
+  const update = state.connection
+    .prepare(
+      `UPDATE viewer_runs
+       SET presentation_revision = ?, retained_from_revision = ?, updated_at = ?
+       WHERE run_id = ? AND presentation_revision = ?`,
+    )
+    .run(revision, retainedFromRevision, now, runId, row.presentationRevision);
+  if (update.changes !== 1) {
+    throw new Error(`Viewer projection revision conflict for workflow run: ${runId}`);
+  }
+  const stalePatchHashes = state.connection
+    .prepare(
+      `SELECT DISTINCT patch_hash AS patchHash FROM viewer_deltas
+       WHERE run_id = ? AND presentation_revision < ?`,
+    )
+    .all(runId, retainedFromRevision)
+    .filter(isPatchHashRow)
+    .map((value) => value.patchHash);
+  state.connection
+    .prepare(
+      `DELETE FROM viewer_deltas
+       WHERE run_id = ? AND presentation_revision < ?`,
+    )
+    .run(runId, retainedFromRevision);
+  const deleteBlob = state.connection.prepare(
+    `DELETE FROM blobs WHERE blob_hash = ?
+     AND NOT EXISTS (SELECT 1 FROM viewer_deltas WHERE patch_hash = blobs.blob_hash)`,
+  );
+  for (const hash of stalePatchHashes) {
+    try {
+      deleteBlob.run(hash);
+    } catch (error) {
+      if (
+        typeof error !== "object" ||
+        error === null ||
+        !("code" in error) ||
+        error.code !== "SQLITE_CONSTRAINT_FOREIGNKEY"
+      ) {
+        throw error;
+      }
+    }
+  }
+  return revision;
+}
+
+export function viewerTailPatch(
+  oldTotal: number,
+  items: readonly ViewerTailItem[],
+): ViewerPatchOperation[] {
+  if (!Number.isInteger(oldTotal) || oldTotal < 0) {
+    throw new Error("Viewer page total must be a non-negative integer");
+  }
+  if (items.length === 0) return [];
+  const nextTotal = oldTotal + items.length;
+  const previousStart = Math.max(0, oldTotal - VIEWER_PAGE_SIZE);
+  const nextStart = Math.max(0, nextTotal - VIEWER_PAGE_SIZE);
+  const patch: ViewerPatchOperation[] = [];
+  if (items.length >= VIEWER_PAGE_SIZE) {
+    patch.push({
+      op: "replace",
+      path: "/items",
+      value: items.slice(-VIEWER_PAGE_SIZE),
+    });
+  } else {
+    const retainedBefore = oldTotal - previousStart;
+    const removed = Math.min(nextStart - previousStart, retainedBefore);
+    for (let index = 0; index < removed; index += 1) {
+      patch.push({ op: "remove", path: "/items/0" });
+    }
+    patch.push({ op: "append", path: "/items", value: [...items] });
+  }
+  if (nextStart !== previousStart) {
+    patch.push({ op: "replace", path: "/start", value: nextStart });
+  }
+  patch.push({ op: "replace", path: "/total", value: nextTotal });
+  return patch;
+}
+
+export function readViewerDeltas(
+  state: StateDatabase,
+  runId: string,
+  afterRevision: number,
+): ViewerCursorResult {
+  if (!Number.isInteger(afterRevision) || afterRevision < 0) {
+    throw new Error("Viewer cursor must be a non-negative integer");
+  }
+  const row = state.connection
+    .prepare(
+      `SELECT presentation_revision AS presentationRevision,
+              retained_from_revision AS retainedFromRevision
+       FROM viewer_runs WHERE run_id = ?`,
+    )
+    .get(runId);
+  if (!isViewerRunRow(row)) {
+    throw new Error(`Viewer projection does not exist for workflow run: ${runId}`);
+  }
+  if (
+    afterRevision === 0 ||
+    afterRevision > row.presentationRevision ||
+    afterRevision < row.retainedFromRevision - 1
+  ) {
+    return {
+      kind: "snapshot_required",
+      currentRevision: row.presentationRevision,
+      retainedFromRevision: row.retainedFromRevision,
+    };
+  }
+  const rows = state.connection
+    .prepare(
+      `SELECT run_id AS runId, presentation_revision AS presentationRevision,
+              delta_index AS deltaIndex, target_type AS targetType,
+              target_key AS targetKey, patch_hash AS patchHash,
+              recorded_at AS recordedAt
+       FROM viewer_deltas
+       WHERE run_id = ? AND presentation_revision > ?
+       ORDER BY presentation_revision, delta_index`,
+    )
+    .all(runId, afterRevision);
+  const deltas: ViewerDeltaRecord[] = [];
+  for (const value of rows) {
+    if (!isViewerDeltaRow(value) || !isViewerTargetType(value.targetType)) {
+      throw new Error("Viewer delta row is invalid");
+    }
+    deltas.push({
+      runId: value.runId,
+      presentationRevision: value.presentationRevision,
+      deltaIndex: value.deltaIndex,
+      targetType: value.targetType,
+      targetKey: value.targetKey,
+      patch: parsePatch(state.readJson(value.patchHash)),
+      recordedAt: value.recordedAt,
+    });
+  }
+  const revisions = [...new Set(deltas.map((delta) => delta.presentationRevision))];
+  const expectedCount = row.presentationRevision - afterRevision;
+  if (
+    revisions.length !== expectedCount ||
+    revisions.some((revision, index) => revision !== afterRevision + index + 1)
+  ) {
+    return {
+      kind: "snapshot_required",
+      currentRevision: row.presentationRevision,
+      retainedFromRevision: row.retainedFromRevision,
+    };
+  }
+  return {
+    kind: "deltas",
+    currentRevision: row.presentationRevision,
+    retainedFromRevision: row.retainedFromRevision,
+    deltas,
+  };
+}
+
+function parsePatch(value: JsonValue): ViewerPatchOperation[] {
+  if (!Array.isArray(value)) throw new Error("Viewer delta patch is not an array");
+  const operations: ViewerPatchOperation[] = [];
+  for (const item of value) {
+    if (!isRecord(item) || typeof item.op !== "string" || typeof item.path !== "string") {
+      throw new Error("Viewer delta patch operation is invalid");
+    }
+    if (item.op === "remove") {
+      operations.push({ op: "remove", path: item.path });
+      continue;
+    }
+    if ((item.op === "add" || item.op === "replace") && "value" in item) {
+      operations.push({
+        op: item.op,
+        path: item.path,
+        value: parseJson(canonicalJson(item.value)),
+      });
+      continue;
+    }
+    if (item.op === "append" && Array.isArray(item.value)) {
+      operations.push({
+        op: "append",
+        path: item.path,
+        value: item.value.map((entry) => parseJson(canonicalJson(entry))),
+      });
+      continue;
+    }
+    throw new Error("Viewer delta patch operation is unsupported");
+  }
+  return operations;
+}
+
+function isPatchHashRow(value: unknown): value is { patchHash: Buffer } {
+  return isRecord(value) && Buffer.isBuffer(value.patchHash);
+}
+
+function isViewerRunRow(value: unknown): value is ViewerRunRow {
+  return (
+    isRecord(value) &&
+    typeof value.presentationRevision === "number" &&
+    typeof value.retainedFromRevision === "number"
+  );
+}
+
+function isViewerDeltaRow(value: unknown): value is ViewerDeltaRow {
+  return (
+    isRecord(value) &&
+    typeof value.runId === "string" &&
+    typeof value.presentationRevision === "number" &&
+    typeof value.deltaIndex === "number" &&
+    typeof value.targetType === "string" &&
+    typeof value.targetKey === "string" &&
+    Buffer.isBuffer(value.patchHash) &&
+    typeof value.recordedAt === "number"
+  );
+}
+
+function isViewerTargetType(value: string): value is ViewerTargetType {
+  return ["summary", "graph", "replay", "timeline", "conversation", "inspector"].includes(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}