@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/event-store-messages.adapter.test.ts

@@ -0,0 +1,365 @@
+import { describe, expect, test } from "bun:test"
+import type { QueuedChatMessage, TranscriptEntry } from "../shared/types"
+import type { StorageBackend } from "./storage/backend"
+import type { ToolRequest } from "../shared/permission-policy"
+import type { ChatRecord } from "./events"
+import {
+  getChatCount,
+  getMessages,
+  getMessagesPageBefore,
+  getQueuedMessage,
+  getQueuedMessages,
+  getRecentChatHistory,
+  getRecentMessagesPage,
+  getSeenMessageIds,
+  loadTranscriptFromDisk,
+  type CachedTranscriptRef,
+  type MessageReadDeps,
+} from "./event-store-messages.adapter"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeStorage(files: Map<string, string> = new Map()): StorageBackend {
+  return {
+    mkdir: async () => {},
+    exists: async (p) => files.has(p),
+    existsSync: (p) => files.has(p),
+    size: async (p) => files.get(p)?.length ?? 0,
+    readText: async (p) => files.get(p) ?? "",
+    readTextSync: (p) => files.get(p) ?? "",
+    writeText: async (p, v) => { files.set(p, v) },
+    appendText: async (p, v) => { files.set(p, (files.get(p) ?? "") + v) },
+    rename: async () => {},
+    remove: async () => {},
+  }
+}
+
+function makeTranscriptEntry(_chatId = "chat-1", kind: "user_prompt" | "assistant_text" = "user_prompt", extra: Partial<TranscriptEntry> = {}): TranscriptEntry {
+  const _id = `${kind}-${Math.random()}`
+  if (kind === "user_prompt") {
+    return { _id, createdAt: 1000, kind: "user_prompt", content: "hello", ...extra } as TranscriptEntry
+  }
+  return { _id, createdAt: 1001, kind: "assistant_text", text: "world", ...extra } as TranscriptEntry
+}
+
+function makeQueuedMessage(overrides: Partial<QueuedChatMessage> = {}): QueuedChatMessage {
+  return {
+    id: "qm-1",
+    content: "queued message",
+    attachments: [],
+    createdAt: 2000,
+    ...overrides,
+  }
+}
+
+function makeChatRecord(overrides: Partial<ChatRecord> = {}): ChatRecord {
+  return {
+    id: "chat-1",
+    projectId: "proj-1",
+    title: "Chat 1",
+    createdAt: 1000,
+    updatedAt: 1000,
+    unread: false,
+    provider: null,
+    planMode: false,
+    sessionTokensByProvider: {},
+    sourceHash: null,
+    lastTurnOutcome: null,
+    ...overrides,
+  }
+}
+
+function makeDeps(overrides: Partial<MessageReadDeps> = {}): MessageReadDeps {
+  return {
+    storage: makeStorage(),
+    transcriptsDir: "/data/transcripts",
+    cachedTranscriptRef: { value: null },
+    legacyMessagesByChatId: new Map(),
+    seenMessageIdsByChatId: new Map(),
+    queuedMessagesByChatId: new Map(),
+    chatsById: new Map(),
+    listPendingToolRequests: (_chatId) => [],
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// getSeenMessageIds
+// ---------------------------------------------------------------------------
+
+describe("getSeenMessageIds", () => {
+  test("creates an empty set for unknown chatId", () => {
+    const deps = makeDeps()
+    const set = getSeenMessageIds(deps, "chat-x")
+    expect(set.size).toBe(0)
+  })
+
+  test("returns the same set on repeated calls for the same chatId", () => {
+    const deps = makeDeps()
+    const s1 = getSeenMessageIds(deps, "chat-x")
+    s1.add("msg-1")
+    const s2 = getSeenMessageIds(deps, "chat-x")
+    expect(s2.has("msg-1")).toBe(true)
+    expect(s1).toBe(s2)
+  })
+
+  test("returns distinct sets for different chatIds", () => {
+    const deps = makeDeps()
+    const sa = getSeenMessageIds(deps, "chat-a")
+    const sb = getSeenMessageIds(deps, "chat-b")
+    expect(sa).not.toBe(sb)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// loadTranscriptFromDisk
+// ---------------------------------------------------------------------------
+
+describe("loadTranscriptFromDisk", () => {
+  test("returns empty array when file does not exist", () => {
+    const deps = makeDeps()
+    expect(loadTranscriptFromDisk(deps, "chat-1")).toEqual([])
+  })
+
+  test("returns empty array for empty file", () => {
+    const files = new Map([["/data/transcripts/chat-1.jsonl", ""]])
+    const deps = makeDeps({ storage: makeStorage(files) })
+    expect(loadTranscriptFromDisk(deps, "chat-1")).toEqual([])
+  })
+
+  test("parses entries from JSONL file", () => {
+    const e1 = makeTranscriptEntry("chat-1", "user_prompt")
+    const e2 = makeTranscriptEntry("chat-1", "assistant_text")
+    const content = `${JSON.stringify(e1)}\n${JSON.stringify(e2)}\n`
+    const files = new Map([["/data/transcripts/chat-1.jsonl", content]])
+    const deps = makeDeps({ storage: makeStorage(files) })
+
+    const result = loadTranscriptFromDisk(deps, "chat-1")
+    expect(result.length).toBe(2)
+    expect(result[0]!._id).toBe(e1._id)
+    expect(result[1]!._id).toBe(e2._id)
+  })
+
+  test("populates seenMessageIds set for entries with messageId", () => {
+    const e1: TranscriptEntry = { ...makeTranscriptEntry("chat-1"), messageId: "mid-1" } as TranscriptEntry & { messageId: string }
+    const content = `${JSON.stringify(e1)}\n`
+    const files = new Map([["/data/transcripts/chat-1.jsonl", content]])
+    const seenMessageIdsByChatId = new Map<string, Set<string>>()
+    const deps = makeDeps({ storage: makeStorage(files), seenMessageIdsByChatId })
+
+    loadTranscriptFromDisk(deps, "chat-1")
+
+    const seen = seenMessageIdsByChatId.get("chat-1")
+    expect(seen?.has("mid-1")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getMessages
+// ---------------------------------------------------------------------------
+
+describe("getMessages", () => {
+  test("returns from cache when chatId matches", () => {
+    const e1 = makeTranscriptEntry("chat-1")
+    const cachedTranscriptRef: CachedTranscriptRef = {
+      value: { chatId: "chat-1", entries: [e1] },
+    }
+    const deps = makeDeps({ cachedTranscriptRef })
+
+    const result = getMessages(deps, "chat-1")
+    expect(result[0]!._id).toBe(e1._id)
+  })
+
+  test("reads from legacy map and populates cache", () => {
+    const e1 = makeTranscriptEntry("chat-2")
+    const legacyMessagesByChatId = new Map([["chat-2", [e1]]])
+    const cachedTranscriptRef: CachedTranscriptRef = { value: null }
+    const deps = makeDeps({ legacyMessagesByChatId, cachedTranscriptRef })
+
+    const result = getMessages(deps, "chat-2")
+    expect(result[0]!._id).toBe(e1._id)
+    expect(cachedTranscriptRef.value?.chatId).toBe("chat-2")
+  })
+
+  test("loads from disk when no cache and no legacy data", () => {
+    const e1 = makeTranscriptEntry("chat-3")
+    const content = `${JSON.stringify(e1)}\n`
+    const files = new Map([["/data/transcripts/chat-3.jsonl", content]])
+    const cachedTranscriptRef: CachedTranscriptRef = { value: null }
+    const deps = makeDeps({ storage: makeStorage(files), cachedTranscriptRef })
+
+    const result = getMessages(deps, "chat-3")
+    expect(result[0]!._id).toBe(e1._id)
+    expect(cachedTranscriptRef.value?.chatId).toBe("chat-3")
+  })
+
+  test("returns a clone (not the cached reference)", () => {
+    const e1 = makeTranscriptEntry("chat-1")
+    const entries = [e1]
+    const cachedTranscriptRef: CachedTranscriptRef = {
+      value: { chatId: "chat-1", entries },
+    }
+    const deps = makeDeps({ cachedTranscriptRef })
+
+    const r1 = getMessages(deps, "chat-1")
+    const r2 = getMessages(deps, "chat-1")
+    expect(r1).not.toBe(r2)
+    expect(r1).not.toBe(entries)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getQueuedMessages
+// ---------------------------------------------------------------------------
+
+describe("getQueuedMessages", () => {
+  test("returns empty array for unknown chat", () => {
+    const deps = makeDeps()
+    expect(getQueuedMessages(deps, "chat-x")).toEqual([])
+  })
+
+  test("returns messages with cloned attachments", () => {
+    const msg = makeQueuedMessage({ id: "qm-1", attachments: [] })
+    const queuedMessagesByChatId = new Map([["chat-1", [msg]]])
+    const deps = makeDeps({ queuedMessagesByChatId })
+
+    const result = getQueuedMessages(deps, "chat-1")
+    expect(result[0]!.id).toBe("qm-1")
+    expect(result[0]!.attachments).not.toBe(msg.attachments)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getQueuedMessage
+// ---------------------------------------------------------------------------
+
+describe("getQueuedMessage", () => {
+  test("returns null for unknown queuedMessageId", () => {
+    const msg = makeQueuedMessage({ id: "qm-1" })
+    const queuedMessagesByChatId = new Map([["chat-1", [msg]]])
+    const deps = makeDeps({ queuedMessagesByChatId })
+    expect(getQueuedMessage(deps, "chat-1", "qm-99")).toBeNull()
+  })
+
+  test("returns the matching message", () => {
+    const msg1 = makeQueuedMessage({ id: "qm-1", content: "first" })
+    const msg2 = makeQueuedMessage({ id: "qm-2", content: "second" })
+    const queuedMessagesByChatId = new Map([["chat-1", [msg1, msg2]]])
+    const deps = makeDeps({ queuedMessagesByChatId })
+
+    const result = getQueuedMessage(deps, "chat-1", "qm-2")
+    expect(result?.content).toBe("second")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getRecentMessagesPage
+// ---------------------------------------------------------------------------
+
+describe("getRecentMessagesPage", () => {
+  test("returns empty page for limit 0", () => {
+    const deps = makeDeps()
+    const page = getRecentMessagesPage(deps, "chat-1", 0)
+    expect(page.messages).toEqual([])
+    expect(page.hasOlder).toBe(false)
+    expect(page.olderCursor).toBeNull()
+  })
+
+  test("returns up to limit messages", () => {
+    const entries = [1, 2, 3, 4, 5].map((i) => ({
+      _id: `e-${i}`,
+      createdAt: i * 100,
+      kind: "assistant_text" as const,
+      text: `msg ${i}`,
+    }))
+    const cachedTranscriptRef: CachedTranscriptRef = {
+      value: { chatId: "chat-1", entries },
+    }
+    const deps = makeDeps({ cachedTranscriptRef })
+    const page = getRecentMessagesPage(deps, "chat-1", 3)
+    expect(page.messages.length).toBe(3)
+  })
+
+  test("hasOlder is true when there are more messages than limit", () => {
+    const entries = [1, 2, 3, 4, 5].map((i) => ({
+      _id: `e-${i}`,
+      createdAt: i * 100,
+      kind: "assistant_text" as const,
+      text: `msg ${i}`,
+    }))
+    const cachedTranscriptRef: CachedTranscriptRef = {
+      value: { chatId: "chat-1", entries },
+    }
+    const deps = makeDeps({ cachedTranscriptRef })
+    const page = getRecentMessagesPage(deps, "chat-1", 3)
+    expect(page.hasOlder).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getMessagesPageBefore
+// ---------------------------------------------------------------------------
+
+describe("getMessagesPageBefore", () => {
+  test("returns empty page for limit 0", () => {
+    const deps = makeDeps()
+    const page = getMessagesPageBefore(deps, "chat-1", "cursor:0", 0)
+    expect(page.messages).toEqual([])
+    expect(page.hasOlder).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getRecentChatHistory
+// ---------------------------------------------------------------------------
+
+describe("getRecentChatHistory", () => {
+  test("includes pending tool request entries", () => {
+    const req = {
+      id: "req-1",
+      chatId: "chat-1",
+      toolName: "Bash",
+      arguments: { command: "ls" },
+      createdAt: 9000,
+    } as unknown as ToolRequest
+    const listPendingToolRequests = (_chatId: string) => [req]
+    const deps = makeDeps({ listPendingToolRequests })
+
+    const { messages } = getRecentChatHistory(deps, "chat-1", 50)
+    const pendingEntry = messages.find((m) => m.kind === "pending_tool_request")
+    expect(pendingEntry).toBeDefined()
+    expect(pendingEntry?.kind === "pending_tool_request" && pendingEntry.toolName).toBe("Bash")
+  })
+
+  test("returns history snapshot", () => {
+    const deps = makeDeps()
+    const result = getRecentChatHistory(deps, "chat-1", 50)
+    expect(result.history).toBeDefined()
+    expect(result.messages).toBeDefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getChatCount
+// ---------------------------------------------------------------------------
+
+describe("getChatCount", () => {
+  test("returns 0 for project with no chats", () => {
+    const deps = makeDeps()
+    expect(getChatCount(deps, "proj-1")).toBe(0)
+  })
+
+  test("counts only non-deleted, non-archived chats for the project", () => {
+    const chatsById = new Map([
+      ["c1", makeChatRecord({ id: "c1", projectId: "proj-1" })],
+      ["c2", makeChatRecord({ id: "c2", projectId: "proj-1", deletedAt: 1000 })],
+      ["c3", makeChatRecord({ id: "c3", projectId: "proj-1", archivedAt: 1000 })],
+      ["c4", makeChatRecord({ id: "c4", projectId: "proj-2" })],
+    ])
+    const deps = makeDeps({ chatsById })
+    expect(getChatCount(deps, "proj-1")).toBe(1)
+    expect(getChatCount(deps, "proj-2")).toBe(1)
+  })
+})

package/src/server/event-store-messages.adapter.ts

@@ -0,0 +1,213 @@
+/**
+ * Message and transcript read operations extracted from event-store.ts.
+ *
+ * `loadTranscriptFromDisk` performs synchronous disk IO, so this module is an
+ * adapter (`.adapter.ts`). All other functions in this file are pure in-memory
+ * reads — they are co-located here for cohesion because they share the same
+ * deps interface and depend on `loadTranscriptFromDisk`.
+ *
+ * This module must NOT import from event-store.ts (no circular deps).
+ */
+import path from "node:path"
+import type { ChatHistoryPage, QueuedChatMessage, TranscriptEntry } from "../shared/types"
+import type { StorageBackend } from "./storage/backend"
+import type { ToolRequest } from "../shared/permission-policy"
+import type { ChatRecord, StoreState } from "./events"
+import { cloneTranscriptEntries } from "./events"
+import {
+  coalesceContextWindowUpdates,
+  decodeCursor,
+  getHistorySnapshot,
+  getMessagesPageFromEntries,
+} from "./event-store-helpers"
+
+// ─── Mutable ref for the transcript cache ────────────────────────────────
+
+/** Wraps the mutable `cachedTranscript` field so extracted functions can read and replace it. */
+export interface CachedTranscriptRef {
+  value: { chatId: string; entries: TranscriptEntry[] } | null
+}
+
+// ─── Deps interface ────────────────────────────────────────────────────────
+
+export interface MessageReadDeps {
+  readonly storage: StorageBackend
+  readonly transcriptsDir: string
+  readonly cachedTranscriptRef: CachedTranscriptRef
+  readonly legacyMessagesByChatId: Map<string, TranscriptEntry[]>
+  readonly seenMessageIdsByChatId: Map<string, Set<string>>
+  readonly queuedMessagesByChatId: StoreState["queuedMessagesByChatId"]
+  readonly chatsById: Map<string, ChatRecord>
+  listPendingToolRequests: (chatId: string) => ToolRequest[]
+}
+
+// ─── Private helpers ───────────────────────────────────────────────────────
+
+function transcriptPath(deps: MessageReadDeps, chatId: string): string {
+  return path.join(deps.transcriptsDir, `${chatId}.jsonl`)
+}
+
+// ─── Exported functions ────────────────────────────────────────────────────
+
+/** Returns (or lazily creates) the seen-messageId dedup set for a chat. */
+export function getSeenMessageIds(deps: MessageReadDeps, chatId: string): Set<string> {
+  let set = deps.seenMessageIdsByChatId.get(chatId)
+  if (!set) {
+    set = new Set<string>()
+    deps.seenMessageIdsByChatId.set(chatId, set)
+  }
+  return set
+}
+
+/**
+ * Reads transcript entries from disk synchronously.
+ * Populates the seenMessageIds set as a side-effect.
+ */
+export function loadTranscriptFromDisk(
+  deps: MessageReadDeps,
+  chatId: string,
+): TranscriptEntry[] {
+  const tPath = transcriptPath(deps, chatId)
+  if (!deps.storage.existsSync(tPath)) {
+    return []
+  }
+
+  const text = deps.storage.readTextSync(tPath)
+  if (!text.trim()) return []
+
+  const entries: TranscriptEntry[] = []
+  const seen = getSeenMessageIds(deps, chatId)
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim()
+    if (!line) continue
+    const entry: TranscriptEntry & { messageId?: string } = JSON.parse(line)
+    entries.push(entry)
+    const mid = entry.messageId
+    if (typeof mid === "string" && mid.length > 0) {
+      seen.add(mid)
+    }
+  }
+  return entries
+}
+
+/**
+ * Returns cloned transcript entries for `chatId`, using the in-memory cache
+ * or loading from disk as needed.
+ */
+export function getMessages(deps: MessageReadDeps, chatId: string): TranscriptEntry[] {
+  if (deps.cachedTranscriptRef.value?.chatId === chatId) {
+    return cloneTranscriptEntries(deps.cachedTranscriptRef.value.entries)
+  }
+
+  const legacyEntries = deps.legacyMessagesByChatId.get(chatId)
+  if (legacyEntries) {
+    deps.cachedTranscriptRef.value = { chatId, entries: cloneTranscriptEntries(legacyEntries) }
+    return cloneTranscriptEntries(deps.cachedTranscriptRef.value.entries)
+  }
+
+  const entries = loadTranscriptFromDisk(deps, chatId)
+  deps.cachedTranscriptRef.value = { chatId, entries }
+  return cloneTranscriptEntries(entries)
+}
+
+/** Returns queued messages for a chat, with attachment arrays cloned. */
+export function getQueuedMessages(
+  deps: MessageReadDeps,
+  chatId: string,
+): QueuedChatMessage[] {
+  const entries = deps.queuedMessagesByChatId.get(chatId) ?? []
+  return entries.map((entry) => ({
+    ...entry,
+    attachments: [...entry.attachments],
+  }))
+}
+
+/** Returns a single queued message by id, or null. */
+export function getQueuedMessage(
+  deps: MessageReadDeps,
+  chatId: string,
+  queuedMessageId: string,
+): QueuedChatMessage | null {
+  return getQueuedMessages(deps, chatId).find((entry) => entry.id === queuedMessageId) ?? null
+}
+
+/** Returns the most recent page of transcript messages. */
+export function getRecentMessagesPage(
+  deps: MessageReadDeps,
+  chatId: string,
+  limit: number,
+): ChatHistoryPage {
+  if (limit <= 0) {
+    return { messages: [], hasOlder: false, olderCursor: null }
+  }
+
+  const entries = coalesceContextWindowUpdates(getMessages(deps, chatId))
+  const page = getMessagesPageFromEntries(entries, limit)
+
+  return {
+    messages: page.entries,
+    hasOlder: page.hasOlder,
+    olderCursor: page.olderCursor,
+  }
+}
+
+/** Returns a page of transcript messages before the given cursor. */
+export function getMessagesPageBefore(
+  deps: MessageReadDeps,
+  chatId: string,
+  beforeCursor: string,
+  limit: number,
+): ChatHistoryPage {
+  if (limit <= 0) {
+    return { messages: [], hasOlder: false, olderCursor: null }
+  }
+
+  // Coalesce identically to getRecentMessagesPage so cursors (which index the
+  // coalesced array) stay consistent across recent + load-older paging.
+  const beforeIndex = decodeCursor(beforeCursor)
+  const entries = coalesceContextWindowUpdates(getMessages(deps, chatId))
+  const page = getMessagesPageFromEntries(entries, limit, beforeIndex)
+
+  return {
+    messages: page.entries,
+    hasOlder: page.hasOlder,
+    olderCursor: page.olderCursor,
+  }
+}
+
+/** Returns merged transcript + pending tool request entries, plus a history snapshot. */
+export function getRecentChatHistory(
+  deps: MessageReadDeps,
+  chatId: string,
+  recentLimit: number,
+) {
+  const page = getRecentMessagesPage(deps, chatId, recentLimit)
+  const pending = deps.listPendingToolRequests(chatId)
+  const pendingEntries: TranscriptEntry[] = pending.map((req) => ({
+    _id: `pending-tool-request-${req.id}`,
+    createdAt: req.createdAt,
+    kind: "pending_tool_request",
+    toolRequestId: req.id,
+    toolName: req.toolName,
+    arguments: req.arguments,
+  }))
+  const merged = [...page.messages, ...pendingEntries]
+  return {
+    messages: merged,
+    history: getHistorySnapshot(
+      {
+        entries: merged,
+        hasOlder: page.hasOlder,
+        olderCursor: page.olderCursor,
+      },
+      recentLimit,
+    ),
+  }
+}
+
+/** Returns the count of active (non-deleted, non-archived) chats for a project. */
+export function getChatCount(deps: MessageReadDeps, projectId: string): number {
+  return [...deps.chatsById.values()].filter(
+    (chat) => chat.projectId === projectId && !chat.deletedAt && !chat.archivedAt,
+  ).length
+}

package/src/server/event-store-orch-subscription.ts

@@ -0,0 +1,124 @@
+/**
+ * Orchestration event write-path + subscription management extracted from
+ * event-store.ts.
+ *
+ * Wraps the pure read functions from event-store-orch.ts and adds:
+ * - `appendOrchestrationEvent` — sync apply + async disk enqueue
+ * - `subscribeOrchRuns` / `notifyOrchRunsChanged` — observer pattern
+ *
+ * All functions use injected deps so they carry no direct IO. EventStore
+ * is the sole owner of the underlying maps and write-chain.
+ *
+ * Must NOT import from event-store.ts (no circular deps).
+ */
+import { LOG_PREFIX } from "../shared/branding"
+import { log } from "../shared/log"
+import type { OrchRunSnapshot } from "../shared/orchestration-types"
+import type { OrchestrationEvent, OrchRunRecord } from "./events"
+import {
+  gatedOrchTasks as gatedOrchTasksFn,
+  getAllOrchRunSnapshots,
+  getOrchLastPhaseOutput as getOrchLastPhaseOutputFn,
+  getOrchRunEvents as getOrchRunEventsFn,
+  getOrchRunSnapshot,
+  getOrchTaskSpec as getOrchTaskSpecFn,
+  nonTerminalOrchTasks as nonTerminalOrchTasksFn,
+} from "./event-store-orch"
+
+// ─── Deps interface ────────────────────────────────────────────────────────
+
+export interface OrchSubscriptionDeps {
+  readonly orchRunsById: Map<string, OrchRunRecord>
+  readonly orchLogPath: string
+  readonly orchRunsSubscribers: Set<() => void>
+  applyEvent: (event: OrchestrationEvent) => void
+  enqueueDiskAppend: (filePath: string, payload: string) => void
+}
+
+// ─── Subscription state ───────────────────────────────────────────────────
+
+/** Create the mutable subscription state held by EventStore. */
+export function createOrchSubscriptionState(): { orchRunsSubscribers: Set<() => void> } {
+  return { orchRunsSubscribers: new Set() }
+}
+
+// ─── Write path ────────────────────────────────────────────────────────────
+
+/**
+ * Apply synchronously, then enqueue the disk append — the sync apply is what
+ * makes an orchestration claim atomic within one event-loop turn (same
+ * pattern as appendSubagentEvent).
+ */
+export function appendOrchestrationEvent(
+  deps: OrchSubscriptionDeps,
+  event: OrchestrationEvent,
+): Promise<void> {
+  deps.applyEvent(event)
+  deps.enqueueDiskAppend(deps.orchLogPath, `${JSON.stringify(event)}\n`)
+  notifyOrchRunsChanged(deps)
+  return Promise.resolve()
+}
+
+/**
+ * Observe orchestration read-model changes. The callback fires after each
+ * live orch event is applied (not during boot replay — no subscribers yet).
+ * Returns an unsubscribe fn.
+ */
+export function subscribeOrchRuns(deps: OrchSubscriptionDeps, cb: () => void): () => void {
+  deps.orchRunsSubscribers.add(cb)
+  return () => { deps.orchRunsSubscribers.delete(cb) }
+}
+
+function notifyOrchRunsChanged(deps: OrchSubscriptionDeps): void {
+  for (const cb of deps.orchRunsSubscribers) {
+    try { cb() } catch (err) { log.warn(`${LOG_PREFIX} orch-runs subscriber threw`, { err }) }
+  }
+}
+
+// ─── Read-model thin wrappers ──────────────────────────────────────────────
+
+export function getOrchRun(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+): OrchRunSnapshot | null {
+  return getOrchRunSnapshot(orchRunsById, runId)
+}
+
+export function getOrchRuns(orchRunsById: Map<string, OrchRunRecord>): OrchRunSnapshot[] {
+  return getAllOrchRunSnapshots(orchRunsById)
+}
+
+export function nonTerminalOrchTasks(
+  orchRunsById: Map<string, OrchRunRecord>,
+): Iterable<{ runId: string; taskId: string; state: "claimed" | "running" }> {
+  return nonTerminalOrchTasksFn(orchRunsById)
+}
+
+export function gatedOrchTasks(
+  orchRunsById: Map<string, OrchRunRecord>,
+): Iterable<{ runId: string; taskId: string; phaseIndex: number }> {
+  return gatedOrchTasksFn(orchRunsById)
+}
+
+export function getOrchTaskSpec(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+  taskId: string,
+): { prompt: string; scopePaths: string[] } | null {
+  return getOrchTaskSpecFn(orchRunsById, runId, taskId)
+}
+
+export function getOrchLastPhaseOutput(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+  taskId: string,
+): string | null {
+  return getOrchLastPhaseOutputFn(orchRunsById, runId, taskId)
+}
+
+export function getOrchRunEvents(
+  orchRunsById: Map<string, OrchRunRecord>,
+  runId: string,
+): OrchestrationEvent[] {
+  return getOrchRunEventsFn(orchRunsById, runId)
+}