@nickmeriano/task 0.11.0 → 0.12.0

package/src/board/source.test.ts

@@ -0,0 +1,203 @@
+/**
+ * The hosted board and an exported board's live proxy serve the same SPA as
+ * `task serve`, so their payloads have to be the same payloads — not
+ * "compatible", the same. This diffs them against the CLI's own `FileStore`.
+ *
+ * That is the test that actually protects the design: if someone adds a field
+ * to the CLI's `toTask` and not here, the hosted board silently loses it, and
+ * the only symptom is a piece of the UI that renders blank for one deployment
+ * and not the other.
+ */
+
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { fileURLToPath } from "node:url"
+import { join } from "node:path"
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import type { Store } from "../store.ts"
+import { FileStore, initProject } from "../file-store.ts"
+import { findBoardDirs, readTicketsBoard, type BoardData } from "./source.ts"
+
+const REPO_ROOT = fileURLToPath(new URL("../../../../..", import.meta.url))
+
+/** Every board this repo actually commits, as `findBoards` would order them. */
+const BOARDS = [".", "projects/inspo", "projects/phone/web", "projects/portal", "projects/task/cli"]
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "board-source-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+/** A board's `.task/` read off disk into the path→bytes map the worker sees. */
+function ticketFiles(taskDir: string): Map<string, Uint8Array> {
+  const files = new Map<string, Uint8Array>()
+  for (const dir of ["goals", "goals/archive"]) {
+    const goalsDir = join(taskDir, dir)
+    if (!existsSync(goalsDir)) continue
+    for (const entry of readdirSync(goalsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue
+      files.set(`${dir}/${entry.name}`, new Uint8Array(readFileSync(join(goalsDir, entry.name))))
+    }
+  }
+  const ticketsDir = join(taskDir, "tickets")
+  if (!existsSync(ticketsDir)) return files
+  for (const number of readdirSync(ticketsDir)) {
+    const ticket = join(ticketsDir, number, "ticket.md")
+    if (existsSync(ticket)) {
+      files.set(`tickets/${number}/ticket.md`, new Uint8Array(readFileSync(ticket)))
+    }
+    for (const kind of ["comments", "asks"]) {
+      const dir = join(ticketsDir, number, kind)
+      if (!existsSync(dir)) continue
+      for (const entry of readdirSync(dir)) {
+        files.set(
+          `tickets/${number}/${kind}/${entry}`,
+          new Uint8Array(readFileSync(join(dir, entry))),
+        )
+      }
+    }
+  }
+  return files
+}
+
+function loadTicketsBoard(id: string, root: string): BoardData {
+  const taskDir = join(root, ".task")
+  return readTicketsBoard(
+    id,
+    new Uint8Array(readFileSync(join(taskDir, "config.json"))),
+    ticketFiles(taskDir),
+  )
+}
+
+/** `GET /api/tasks` + per-task comments, straight from the CLI store. */
+function expectedPayloads(store: Store) {
+  const counts = store.commentCounts()
+  const tasks = store.list().map((task) => ({
+    ...task,
+    commentCount: counts.get(task.key) ?? 0,
+  }))
+  return { tasks, comments: new Map(tasks.map((t) => [t.key, store.comments(t.key)])) }
+}
+
+function assertSamePayloads(id: string, hosted: BoardData, store: Store): void {
+  assert.equal(hosted.info.name, store.config.name, `${id}: project name`)
+  assert.equal(hosted.info.prefix, store.config.prefix, `${id}: prefix`)
+  const expected = expectedPayloads(store)
+  assert.equal(hosted.tasks.length, expected.tasks.length, `${id}: task count`)
+  for (let i = 0; i < expected.tasks.length; i++) {
+    assert.deepEqual(hosted.tasks[i], expected.tasks[i], `${id}: task ${expected.tasks[i].id}`)
+  }
+  for (const task of expected.tasks) {
+    assert.deepEqual(
+      hosted.comments.get(task.key) ?? [],
+      expected.comments.get(task.key),
+      `${id}: comments on ${task.id}`,
+    )
+  }
+  assert.deepEqual(
+    hosted.goals,
+    [...store.goals(), ...store.goals(true)],
+    `${id}: goals`,
+  )
+}
+
+test("finds the same boards the CLI would, in the same order", () => {
+  // The shape a recursive git-tree listing arrives in, plus the noise it
+  // really contains: nested boards, unrelated files, and a `.task` path that
+  // is a file rather than a board.
+  const paths = [
+    "README.md",
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "projects/phone/web/.task/config.json",
+    "projects/task/cli/.task/config.json",
+    "docs/.taskrc",
+    "vendor/thing/.task/config.json.bak",
+    // A directory that merely *ends* in `.task` is not a board directory.
+    "lib/x.task/config.json",
+  ]
+  assert.deepEqual(findBoardDirs(paths), [".", "projects/phone/web", "projects/task/cli"])
+})
+
+test("ignores boards nested deeper than the CLI would walk", () => {
+  const deep = "a/b/c/d/e/f/g/.task/config.json"
+  assert.deepEqual(findBoardDirs([deep]), [])
+  assert.deepEqual(findBoardDirs(["a/b/c/.task/config.json"]), ["a/b/c"])
+})
+
+test("text boards produce the same payloads the CLI's FileStore does", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "fixture board", prefix: "FIX" })
+  store.createGoal({ title: "Launch", description: "the shared why" })
+  const one = store.create({
+    title: "Every field exercised",
+    description: "A *body* with\n\n# an inner heading\n\nand `code`.",
+    tags: ["api", "infra"],
+    goal: "launch",
+    prs: ["https://github.com/x/y/pull/3"],
+  })
+  store.addAsk(one.key, "Approve the launch window", "claude")
+  const two = store.create({ title: "Mover", status: "backlog" })
+  store.create({ title: "Plain" })
+  store.update(two.key, { status: "in_progress" }) // lands on top → negative position
+  store.link(two.key, "blocked_by", one.key)
+  store.addComment(one.key, "first, with **markdown**", "nick")
+  store.addComment(one.key, "second", "claude")
+
+  assertSamePayloads("fixture", loadTicketsBoard("fixture", root), store)
+})
+
+test("this repo's committed boards read as text, same as the CLI reads them", () => {
+  for (const id of BOARDS) {
+    const root = id === "." ? REPO_ROOT : join(REPO_ROOT, id)
+    assertSamePayloads(id, loadTicketsBoard(id, root), new FileStore(root))
+  }
+})
+
+test("every committed board is non-empty and self-consistent", () => {
+  // A smoke check that the fixtures above are actually exercising something —
+  // boards that all happened to be empty would make the diff vacuous.
+  const loaded = BOARDS.map((id) =>
+    loadTicketsBoard(id, id === "." ? REPO_ROOT : join(REPO_ROOT, id)),
+  )
+  const total = loaded.reduce((sum, board) => sum + board.tasks.length, 0)
+  assert.ok(total > 10, `expected the repo's boards to hold real tasks, found ${total}`)
+
+  for (const board of loaded) {
+    for (const task of board.tasks) {
+      assert.match(task.id, /^[A-Z0-9]+-[a-z0-9]+$/, `${board.info.id}: display id`)
+      assert.ok(Array.isArray(task.tags), `${board.info.id}: tags parsed`)
+      assert.equal(typeof task.needsHuman, "boolean", `${board.info.id}: needsHuman`)
+    }
+  }
+})
+
+test("a broken ticket degrades instead of breaking the board", () => {
+  const config = new TextEncoder().encode(
+    JSON.stringify({ name: "rough", prefix: "RGH", version: 2 }),
+  )
+  const encode = (s: string) => new TextEncoder().encode(s)
+  const board = readTicketsBoard(
+    "rough",
+    config,
+    new Map([
+      ["tickets/bad2c/ticket.md", encode("---\nstatus: todoo\nposition: not-a-number\n---\n\nno heading")],
+      ["tickets/gone3/ticket.md", encode("not even frontmatter")],
+      ["tickets/fine4/ticket.md", encode("---\nstatus: todo\nposition: 1\ncreated: c\nupdated: u\n---\n\n# Fine\n")],
+      // A comment on a ticket that didn't parse must not surface anywhere.
+      ["tickets/gone3/comments/2026-08-15T120000-x.md", encode("---\nauthor: \"x\"\ncreated: c\n---\n\nhi")],
+      // A pre-TAS-42 numeric directory is not a ticket to this reader at all.
+      ["tickets/42/ticket.md", encode("---\nstatus: todo\nposition: 1\ncreated: c\nupdated: u\n---\n\n# Old format\n")],
+    ]),
+  )
+  assert.deepEqual(
+    board.tasks.map((t) => [t.key, t.status, t.title]),
+    [
+      ["bad2c", "backlog", ""],
+      ["fine4", "todo", "Fine"],
+    ],
+  )
+  assert.equal(board.comments.size, 0)
+})

package/src/board/source.ts

@@ -0,0 +1,422 @@
+/**
+ * A repository, read as boards.
+ *
+ * This is `findBoards` + `FileStore`, re-expressed against a git tree instead
+ * of a filesystem, and producing byte-identical API payloads. That
+ * equivalence is the whole point: the hosted board and an exported board's
+ * live proxy run the *same* SPA as `task serve`, so anything that differs
+ * here shows up as a broken screen rather than a type error. The shapes below
+ * are pinned to `server.ts` — change one and change both — and the ticket
+ * format itself is not restated: parsing comes from `ticket-doc.ts`, the one
+ * definition every server shares, in its lenient mode (a hand-edited file
+ * that no longer parses becomes a degraded ticket or a skipped comment, never
+ * a broken board).
+ *
+ * Read-only by construction. There is no code here that could write, which is
+ * how "the board can't edit your repo" stays true no matter what the routing
+ * layer does.
+ *
+ * Cache-free on purpose. A snapshot is immutable per commit, so *where* to
+ * keep one is a deployment question — the hosted worker layers isolate memory
+ * and KV over `snapshotAt`, the live proxy keeps a bounded `SnapshotMemory` —
+ * and this module answers only "what is at this commit".
+ */
+
+import {
+  parseAskLenient,
+  parseCommentLenient,
+  parseGoalLenient,
+  parseTicketLenient,
+  type TicketDoc,
+} from "../ticket-doc.ts"
+import { isTicketKey } from "../id.ts"
+import type { Ask, Comment, Goal, Task as StoredTask } from "../types.ts"
+import { fetchRepoArchive, headCommit, type CommitInfo } from "./github.ts"
+
+export { STATUSES, type Status } from "../types.ts"
+export type { Ask, Comment, Goal }
+
+const TASK_DIR = ".task"
+const CONFIG_FILE = "config.json"
+const TICKETS_DIR = "tickets"
+const TICKET_FILE = "ticket.md"
+const COMMENTS_DIR = "comments"
+const ASKS_DIR = "asks"
+const GOALS_DIR = "goals"
+
+/** Same ceiling as the CLI's `findBoards`, for the same reason. */
+const MAX_DEPTH = 6
+
+export interface BoardInfo {
+  id: string
+  name: string
+  prefix: string
+}
+
+/** A stored task plus the count `GET /tasks` sends — exactly what `task serve` lists. */
+export interface Task extends StoredTask {
+  commentCount: number
+}
+
+export interface BoardData {
+  info: BoardInfo
+  tasks: Task[]
+  /** Keyed by task key. */
+  comments: Map<string, Comment[]>
+  /** Live goals first, archived flagged — the shape `GET /goals` serves. */
+  goals: Goal[]
+}
+
+export interface Snapshot {
+  commit: CommitInfo
+  boards: BoardInfo[]
+  data: Map<string, BoardData>
+  /**
+   * Historically "the tree listing hit GitHub's cap". The tarball read is
+   * always complete, so this is now always false — kept because the SPA's
+   * payloads carry it.
+   */
+  truncated: boolean
+}
+
+export class BoardSourceError extends Error {
+  readonly status: number
+  /**
+   * Machine-readable cause, sent beside the message so the SPA can choose a
+   * screen rather than infer one from a status code. Optional: most of these
+   * are one of a kind and the message is the whole story.
+   */
+  readonly reason: string | null
+  constructor(status: number, message: string, reason: string | null = null) {
+    super(message)
+    this.name = "BoardSourceError"
+    this.status = status
+    this.reason = reason
+  }
+}
+
+function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback
+}
+
+function num(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback
+}
+
+interface ParsedConfig {
+  name: string
+  prefix: string
+  version: number
+}
+
+/** `.task/config.json`, defensively — it's a file anyone can hand-edit. */
+function parseConfig(bytes: Uint8Array, fallbackName: string): ParsedConfig {
+  try {
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes))
+    if (parsed && typeof parsed === "object") {
+      const config = parsed as Record<string, unknown>
+      return {
+        name: str(config.name, fallbackName),
+        prefix: str(config.prefix, "TASK").toUpperCase(),
+        version: num(config.version, 1),
+      }
+    }
+  } catch {
+    // fall through
+  }
+  return { name: fallbackName, prefix: "TASK", version: 1 }
+}
+
+/**
+ * Board directories, from a flat list of repo paths.
+ *
+ * The CLI finds a board by the presence of `.task/config.json`; so does this.
+ * Depth is capped the same way, and the ordering — "." first, then
+ * lexicographic — is copied so the default board is the same one you'd get
+ * locally.
+ */
+export function findBoardDirs(paths: string[]): string[] {
+  const marker = `${TASK_DIR}/${CONFIG_FILE}`
+  const dirs: string[] = []
+  for (const path of paths) {
+    // The directory has to be `.task` itself, not merely end in it — a bare
+    // suffix match would read `x.task/config.json` as a board at `x`.
+    if (path !== marker && !path.endsWith(`/${marker}`)) continue
+    const dir = path.slice(0, -(TASK_DIR.length + CONFIG_FILE.length + 2))
+    const id = dir === "" ? "." : dir.replace(/\/$/, "")
+    if (id !== "." && id.split("/").length > MAX_DEPTH) continue
+    dirs.push(id)
+  }
+  dirs.sort((a, b) => (a === "." ? -1 : b === "." ? 1 : a < b ? -1 : 1))
+  return dirs
+}
+
+/** `projects/phone/web` → "phone web"-ish fallback name, matching `task init`. */
+function nameFromDir(id: string): string {
+  if (id === ".") return "tasks"
+  return id.split("/").pop() ?? "tasks"
+}
+
+/**
+ * One board from its ticket files. `files` is keyed by path relative to the
+ * board's `.task/` — `tickets/12/ticket.md`, `tickets/12/comments/<stem>.md` —
+ * which is how `snapshotAt` fetches them and how the test feeds them from
+ * disk.
+ */
+export function readTicketsBoard(
+  id: string,
+  configBytes: Uint8Array,
+  files: Map<string, Uint8Array>,
+): BoardData {
+  const config = parseConfig(configBytes, nameFromDir(id))
+  const decoder = new TextDecoder()
+
+  const docs = new Map<string, TicketDoc>()
+  const comments = new Map<string, Comment[]>()
+  const asks = new Map<string, Ask[]>()
+  const goals: Goal[] = []
+  for (const [path, bytes] of files) {
+    // Goals: one file per goal, archived ones one level down. Old branches
+    // simply have no goals/ — the list stays empty and every reader tolerates
+    // a ticket's goal ref not resolving.
+    const goalMatch = new RegExp(`^${GOALS_DIR}/(archive/)?([^/]+)\\.md$`).exec(path)
+    if (goalMatch) {
+      if (goalMatch[2].startsWith(".")) continue
+      const doc = parseGoalLenient(decoder.decode(bytes))
+      if (doc) {
+        goals.push({
+          slug: goalMatch[2],
+          title: doc.title,
+          description: doc.description,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          ...(goalMatch[1] ? { archived: true } : {}),
+        })
+      }
+      continue
+    }
+    const ticketMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${TICKET_FILE}$`).exec(path)
+    if (ticketMatch && isTicketKey(ticketMatch[1])) {
+      const doc = parseTicketLenient(decoder.decode(bytes))
+      if (doc) docs.set(ticketMatch[1], doc)
+      continue
+    }
+    const commentMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${COMMENTS_DIR}/([^/]+)\\.md$`).exec(
+      path,
+    )
+    if (commentMatch && isTicketKey(commentMatch[1]) && !commentMatch[2].startsWith(".")) {
+      const doc = parseCommentLenient(decoder.decode(bytes))
+      if (!doc) continue
+      const taskKey = commentMatch[1]
+      const list = comments.get(taskKey) ?? []
+      list.push({
+        id: commentMatch[2],
+        taskId: `${config.prefix}-${taskKey}`,
+        author: doc.author,
+        body: doc.body,
+        createdAt: doc.createdAt,
+      })
+      comments.set(taskKey, list)
+      continue
+    }
+    const askMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${ASKS_DIR}/([^/]+)\\.md$`).exec(path)
+    if (askMatch && isTicketKey(askMatch[1]) && !askMatch[2].startsWith(".")) {
+      const doc = parseAskLenient(decoder.decode(bytes))
+      if (!doc) continue
+      const taskKey = askMatch[1]
+      const list = asks.get(taskKey) ?? []
+      // Ordinal assigned after the sort below — 0 is a placeholder.
+      list.push({
+        id: askMatch[2],
+        taskId: `${config.prefix}-${taskKey}`,
+        ordinal: 0,
+        text: doc.body,
+        author: doc.author,
+        createdAt: doc.createdAt,
+        resolvedAt: doc.resolvedAt,
+        resolvedBy: doc.resolvedBy,
+      })
+      asks.set(taskKey, list)
+    }
+  }
+  // Comments whose ticket file is missing or unreadable would count against a
+  // ticket that isn't drawn — drop them, and order the rest the CLI's way.
+  for (const taskKey of comments.keys()) {
+    if (!docs.has(taskKey)) comments.delete(taskKey)
+  }
+  for (const list of comments.values()) {
+    list.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+  }
+  // Asks: same orphan rule, and ordinals are creation-order positions — the
+  // exact numbering the CLI's `asks()` derives.
+  for (const taskKey of asks.keys()) {
+    if (!docs.has(taskKey)) asks.delete(taskKey)
+  }
+  for (const list of asks.values()) {
+    list.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    list.forEach((ask, index) => (ask.ordinal = index + 1))
+  }
+
+  // `blocks` is derived from the other tickets' stored `blocked_by` — the
+  // relation lives on one side only, so the two views can't disagree.
+  const blocks = new Map<string, string[]>()
+  for (const [key, doc] of docs) {
+    for (const blocker of doc.blockedBy) {
+      blocks.set(blocker, [...(blocks.get(blocker) ?? []), key])
+    }
+  }
+  for (const list of blocks.values()) list.sort((a, b) => a.localeCompare(b))
+
+  const tasks: Task[] = [...docs.entries()]
+    .map(([key, doc]) => ({
+      id: `${config.prefix}-${key}`,
+      key,
+      title: doc.title,
+      description: doc.description,
+      status: doc.status,
+      tags: doc.tags,
+      goal: doc.goal,
+      needsHuman: (asks.get(key) ?? []).some((a) => !a.resolvedAt),
+      asks: asks.get(key) ?? [],
+      blocks: blocks.get(key) ?? [],
+      blockedBy: doc.blockedBy,
+      prs: doc.prs,
+      position: doc.position,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      commentCount: comments.get(key)?.length ?? 0,
+    }))
+    .sort(
+      (a, b) =>
+        a.position - b.position ||
+        a.createdAt.localeCompare(b.createdAt) ||
+        a.key.localeCompare(b.key),
+    )
+
+  goals.sort(
+    (a, b) => Number(a.archived === true) - Number(b.archived === true) || a.slug.localeCompare(b.slug),
+  )
+  return { info: { id, name: config.name, prefix: config.prefix }, tasks, comments, goals }
+}
+
+/**
+ * Every board in a repository at a known commit, ready to serve.
+ *
+ * One request for the whole repository: every path, plus bytes for anything
+ * under a .task/ directory. (Earlier shapes — a tree listing plus per-file or
+ * batched blob reads — scaled subrequests with board size and tripped
+ * Workers' 50-subrequest ceiling; a tarball is one request regardless.)
+ *
+ * `ref` is only for the error message: told a branch, "this repository has
+ * no .task directory" is both wrong and confusing — the repository plainly
+ * has one, you were just looking at it — and `task init` is not the fix for
+ * previewing a branch that forked before the boards existed.
+ */
+export async function snapshotAt(
+  token: string,
+  owner: string,
+  repo: string,
+  commit: CommitInfo,
+  ref = "HEAD",
+): Promise<Snapshot> {
+  const { paths, files } = await fetchRepoArchive(token, owner, repo, commit.sha, (path) =>
+    path.startsWith(`${TASK_DIR}/`) || path.includes(`/${TASK_DIR}/`),
+  )
+  const dirs = findBoardDirs(paths)
+  if (dirs.length === 0) {
+    throw new BoardSourceError(
+      404,
+      ref === "HEAD"
+        ? "no .task directory in this repository — run `task init` and commit it"
+        : `no .task directory on ${ref}`,
+      "no-boards",
+    )
+  }
+
+  const data = new Map<string, BoardData>()
+  for (const id of dirs) {
+    const base = id === "." ? TASK_DIR : `${id}/${TASK_DIR}`
+    const configBytes = files.get(`${base}/${CONFIG_FILE}`)
+    if (!configBytes) continue
+
+    const prefix = `${base}/`
+    const ticketPaths = paths.filter(
+      (path) =>
+        (path.startsWith(`${prefix}${TICKETS_DIR}/`) || path.startsWith(`${prefix}${GOALS_DIR}/`)) &&
+        path.endsWith(".md"),
+    )
+    // A config with no committed tickets can be two very different things: a
+    // real (empty) text board, or a pre-0.6 board whose state is a SQLite
+    // database this app no longer reads. The config's version says which —
+    // skip the legacy one rather than render an empty board that lies.
+    if (ticketPaths.length === 0 && parseConfig(configBytes, "").version < 2) continue
+
+    const tickets = new Map<string, Uint8Array>()
+    for (const path of ticketPaths) {
+      const bytes = files.get(path)
+      if (bytes) tickets.set(path.slice(prefix.length), bytes)
+    }
+    const board = readTicketsBoard(id, configBytes, tickets)
+    data.set(board.info.id, board)
+  }
+  if (data.size === 0) {
+    throw new BoardSourceError(
+      404,
+      "found .task/config.json but no committed tickets — are .task/tickets/ gitignored, or is this a pre-0.6 SQLite board that still needs `task migrate` (@nickmeriano/task@0.6)?",
+    )
+  }
+
+  return {
+    commit,
+    boards: [...data.values()].map((board) => board.info),
+    data,
+    truncated: false,
+  }
+}
+
+/**
+ * Every board at `ref`, cache-free: "what is HEAD" plus one tarball. Callers
+ * that serve more than one view put a cache between the two — see
+ * `SnapshotMemory` — because the second request is the expensive one and a
+ * commit never changes.
+ */
+export async function loadSnapshot(
+  token: string,
+  owner: string,
+  repo: string,
+  ref: string,
+): Promise<Snapshot> {
+  const commit = await headCommit(token, owner, repo, ref)
+  return snapshotAt(token, owner, repo, commit, ref)
+}
+
+/**
+ * Parsed snapshots, keyed by `owner/repo@sha`, bounded.
+ *
+ * A commit is immutable, so this never serves anything stale: the only lookup
+ * that goes to GitHub on a warm instance is "what is HEAD right now", and a
+ * new commit is a new key. Bounded because an isolate's memory is not ours to
+ * fill; `Map` iterates in insertion order, so the first key is the oldest.
+ */
+export class SnapshotMemory {
+  private readonly snapshots = new Map<string, Snapshot>()
+  private readonly max: number
+
+  constructor(max = 24) {
+    this.max = max
+  }
+
+  get(key: string): Snapshot | undefined {
+    return this.snapshots.get(key)
+  }
+
+  remember(key: string, snapshot: Snapshot): Snapshot {
+    this.snapshots.set(key, snapshot)
+    while (this.snapshots.size > this.max) {
+      const oldest = this.snapshots.keys().next().value
+      if (oldest === undefined) break
+      this.snapshots.delete(oldest)
+    }
+    return snapshot
+  }
+}