@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/store/read.ts

@@ -0,0 +1,454 @@
+/**
+ * Reading a workbook, its sidecar index, and its catalog (docs/issue/0022 P1).
+ *
+ * The in-process cache lives here because the DSH host is the single mutation
+ * authority: a reader either sees a workbook's committed state or misses, and
+ * `store/write.ts` is the only thing that invalidates it.
+ *
+ * The write-ahead journal's *lock* and *recovery* are here too: `readWorkbook`
+ * must finish an interrupted commit before it reads, and `store/write.ts`
+ * takes the same lock to commit, so the two cannot race. The direction is
+ * one-way — `read` never imports `write`.
+ */
+import { DataSheetError } from '../errors.ts'
+import { access, readFile, readdir, rename, unlink } from 'node:fs/promises'
+import {
+  type SheetSchema,
+  type WorkbookChange,
+  type WorkbookMeta,
+  type WorkbookOperation,
+  type WorkbookOperationType,
+  type WorkbookProposal,
+  type WorkbookSummary,
+  type WorkbookWorktree,
+  type WorkbookWorktreeStatus,
+  type WorkbookWorktreeSummary,
+} from '../types.ts'
+import { normalizeWorkbookId } from '../contract/ids.ts'
+import { cloneSnapshot, isSheetSchema, normalizeSnapshotName } from '../contract/snapshots.ts'
+import { applyWorkbookOperation } from '../contract/mutations.ts'
+import {
+  workbookCheckpointsPath,
+  workbookIndexPath,
+  workbookOperationsPath,
+  workbookPath,
+  workbookProposalsPath,
+  workbookSnapshotPath,
+  workbookTransactionPath,
+  workbookRoot,
+  workbookWorktreeDirectory,
+  workbookWorktreePath,
+} from './paths.ts'
+
+/** Whether a workbook file exists. */
+export async function workbookExists(id: string): Promise<boolean> {
+  return fileExists(workbookPath(id))
+}
+
+/** Read only the sidecar index; a missing/invalid sidecar falls back safely. */
+export async function readWorkbookIndex(id: string): Promise<WorkbookIndex | null> {
+  try {
+    await withWorkbookTransactionQueue(normalizeWorkbookId(id), () => recoverWorkbookTransactionNow(normalizeWorkbookId(id)))
+    const parsed = JSON.parse(await readFile(workbookIndexPath(id), 'utf8')) as Partial<WorkbookIndex>
+    if (typeof parsed.id !== 'string' || typeof parsed.name !== 'string' || !Number.isInteger(parsed.revision)
+      || !Array.isArray(parsed.sheets) || !Array.isArray(parsed.operations) || !Array.isArray(parsed.proposals)) return null
+    return {
+      id: parsed.id,
+      name: parsed.name,
+      sheetOrder: Array.isArray(parsed.sheetOrder) ? parsed.sheetOrder.filter(item => typeof item === 'string') : parsed.sheets.map(sheet => sheet.id),
+      sheets: parsed.sheets.filter(isStoredSheetSummary),
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+      revision: parsed.revision as number,
+      operations: parsed.operations.filter(operation => isStoredIndexOperation(operation)),
+      proposals: parsed.proposals.filter(isStoredIndexProposal),
+    }
+  } catch (error) {
+    // A missing or malformed sidecar is not an error: the caller learns "no
+    // workbook here" and moves on. A *corrupt transaction journal* is, and it
+    // used to be swallowed by this same catch — so a workbook that still had
+    // every one of its files simply disappeared from the catalog and
+    // `workbook_read` answered 「工作簿不存在」, three hand-written error messages
+    // away from the reader.
+    if (error instanceof DataSheetError) throw error
+    return null
+  }
+}
+
+/** Read one workbook meta. */
+export async function readWorkbook(id: string, options: { includeCheckpoints?: boolean } = {}): Promise<WorkbookMeta | null> {
+  try {
+    await withWorkbookTransactionQueue(normalizeWorkbookId(id), () => recoverWorkbookTransactionNow(normalizeWorkbookId(id)))
+    const cached = workbookCache.get(normalizeWorkbookId(id))
+    if (cached !== undefined) {
+      if (options.includeCheckpoints === true && !cached.checkpointsLoaded) {
+        const stored = await readJsonFile(workbookCheckpointsPath(id)) as { checkpoints?: unknown } | null
+        cached.meta.checkpoints = Array.isArray(stored?.checkpoints)
+          ? stored.checkpoints.filter(checkpoint => isStoredCheckpoint(checkpoint))
+          : []
+        cached.checkpointsLoaded = true
+      }
+      return cached.meta
+    }
+    const raw = await readFile(workbookPath(id), 'utf8')
+    const parsed = JSON.parse(raw) as WorkbookMeta
+    if (typeof parsed.id !== 'string' || typeof parsed.name !== 'string') return null
+    let snapshot = parsed.snapshot
+    let snapshotRevision = 0
+    if (snapshot === undefined) {
+      const stored = await readJsonFile(workbookSnapshotPath(id)) as { revision?: unknown; snapshot?: unknown } | null
+      if (stored === null || !Object.prototype.hasOwnProperty.call(stored, 'snapshot')) return null
+      snapshot = stored.snapshot
+      snapshotRevision = typeof stored.revision === 'number' && Number.isInteger(stored.revision) ? stored.revision : 0
+    }
+    const storedCheckpoints = options.includeCheckpoints === true
+      ? await readJsonFile(workbookCheckpointsPath(id)) as { checkpoints?: unknown } | null
+      : null
+    const rawCheckpoints = Array.isArray(parsed.checkpoints)
+      ? parsed.checkpoints
+      : Array.isArray(storedCheckpoints?.checkpoints) ? storedCheckpoints.checkpoints : []
+    const storedOperations = Array.isArray(parsed.operations)
+      ? parsed.operations
+      : await readJsonFile(workbookOperationsPath(id))
+    const operations = Array.isArray(storedOperations)
+      ? storedOperations.filter(operation => isStoredOperation(operation))
+      : []
+    const storedProposals = Array.isArray(parsed.proposals)
+      ? parsed.proposals
+      : await readJsonFile(workbookProposalsPath(id))
+    if (parsed.snapshot === undefined && snapshotRevision < (parsed.revision ?? 0)) {
+      for (const operation of operations) {
+        if (operation.revision <= snapshotRevision) continue
+        snapshot = applyWorkbookOperation(snapshot, operation)
+      }
+    }
+    const result: WorkbookMeta = {
+      ...parsed,
+      snapshot: normalizeSnapshotName(snapshot, parsed.name),
+      revision: Number.isInteger(parsed.revision) && (parsed.revision as number) >= 0 ? parsed.revision : 0,
+      snapshotRevision: parsed.snapshot === undefined ? snapshotRevision : (typeof parsed.snapshotRevision === 'number' ? parsed.snapshotRevision : parsed.revision ?? 0),
+      operations,
+      proposals: Array.isArray(storedProposals)
+        ? storedProposals.filter(proposal => isStoredProposal(proposal))
+        : [],
+      checkpoints: rawCheckpoints.filter(checkpoint => isStoredCheckpoint(checkpoint)),
+    }
+    workbookCache.set(normalizeWorkbookId(id), { meta: result, checkpointsLoaded: Array.isArray(parsed.checkpoints) || options.includeCheckpoints === true })
+    return result
+  } catch (error) {
+    // See `readWorkbookIndex`: only the deliberate persistence failures escape.
+    if (error instanceof DataSheetError) throw error
+    return null
+  }
+}
+
+/**
+ * Reconstruct a historical workbook revision from the nearest checkpoint and
+ * the retained operation tail. A null result means the requested revision has
+ * been compacted or contains an opaque snapshot replacement.
+ */
+export async function readWorkbookAtRevision(workbookId: string, targetRevision: number): Promise<{ snapshot: unknown; revision: number } | null> {
+  const meta = await readWorkbook(workbookId, { includeCheckpoints: true })
+  if (meta === null) return null
+  const currentRevision = meta.revision ?? 0
+  if (!Number.isInteger(targetRevision) || targetRevision < 0 || targetRevision > currentRevision) return null
+  if (targetRevision === currentRevision) return { snapshot: cloneSnapshot(meta.snapshot), revision: currentRevision }
+
+  // The snapshot sidecar is itself a durable checkpoint. Older workbooks may
+  // have been written before the in-memory checkpoint index existed, so use it
+  // directly when the requested revision is exactly the sidecar revision.
+  const sidecar = await readJsonFile(workbookSnapshotPath(workbookId)) as { revision?: unknown; snapshot?: unknown } | null
+  if (sidecar !== null && sidecar.snapshot !== undefined && sidecar.revision === targetRevision) {
+    return { snapshot: cloneSnapshot(sidecar.snapshot), revision: targetRevision }
+  }
+
+  const checkpoint = [...(meta.checkpoints ?? [])]
+    .filter(item => item.revision <= targetRevision)
+    .sort((left, right) => right.revision - left.revision)[0]
+  if (checkpoint === undefined) return null
+  let snapshot = cloneSnapshot(checkpoint.snapshot)
+  const operations = (meta.operations ?? [])
+    .filter(operation => operation.revision > checkpoint.revision && operation.revision <= targetRevision)
+    .sort((left, right) => left.revision - right.revision)
+  if (operations.length !== targetRevision - checkpoint.revision) return null
+  for (const operation of operations) {
+    if (operation.type === 'snapshot_replace' && operation.payload.snapshot === undefined) return null
+    snapshot = applyWorkbookOperation(snapshot, operation)
+  }
+  return { snapshot, revision: targetRevision }
+}
+
+/** List workbook ids (files in the repo root, sorted by name). */
+export async function listWorkbooks(): Promise<string[]> {
+  try {
+    const entries = await readdir(workbookRoot(), { withFileTypes: true })
+    return entries
+      .filter(entry => entry.isFile() && entry.name.endsWith('.json')
+        && !entry.name.endsWith('.index.json') && !entry.name.endsWith('.snapshot.json')
+        && !entry.name.endsWith('.checkpoints.json') && !entry.name.endsWith('.operations.json')
+        && !entry.name.endsWith('.proposals.json') && !entry.name.endsWith('.transaction.json'))
+      .map(entry => entry.name.slice(0, -'.json'.length))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/** List workbook summaries for the browser picker and other read-only clients. */
+export async function listWorkbookSummaries(): Promise<WorkbookSummary[]> {
+  const summaries: WorkbookSummary[] = []
+  for (const id of await listWorkbooks()) {
+    const index = await readWorkbookIndex(id)
+    if (index !== null) summaries.push({ id: index.id, name: index.name, sheets: index.sheets, updatedAt: index.updatedAt, revision: index.revision })
+    else {
+      const meta = await readWorkbook(id)
+      if (meta !== null) summaries.push(summarize(meta))
+    }
+  }
+  return summaries
+}
+
+/** List worktrees belonging to a workbook, optionally scoped to one session. */
+export async function listWorkbookWorktrees(workbookId: string, ownerSessionId?: string): Promise<WorkbookWorktreeSummary[]> {
+  const normalizedWorkbookId = normalizeWorkbookId(workbookId)
+  try {
+    const entries = await readdir(workbookWorktreeDirectory(normalizedWorkbookId), { withFileTypes: true })
+    const result: WorkbookWorktreeSummary[] = []
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue
+      const worktree = await readWorkbookWorktree(normalizedWorkbookId, entry.name.slice(0, -'.json'.length))
+      if (worktree === null || ownerSessionId !== undefined && worktree.ownerSessionId !== ownerSessionId) continue
+      result.push(toWorktreeSummary(worktree))
+    }
+    return result.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+  } catch {
+    return []
+  }
+}
+
+/** Read one isolated worktree, including its snapshot and operation tail. */
+export async function readWorkbookWorktree(workbookId: string, worktreeId: string): Promise<WorkbookWorktree | null> {
+  try {
+    const parsed = JSON.parse(await readFile(workbookWorktreePath(workbookId, worktreeId), 'utf8')) as Partial<WorkbookWorktree>
+    if (typeof parsed.id !== 'string' || typeof parsed.workbookId !== 'string'
+      || typeof parsed.ownerSessionId !== 'string' || typeof parsed.name !== 'string'
+      || !Number.isInteger(parsed.baseRevision) || !Number.isInteger(parsed.revision)
+      || !isWorktreeStatus(parsed.status) || typeof parsed.createdAt !== 'string'
+      || typeof parsed.updatedAt !== 'string' || parsed.snapshot === undefined) return null
+    return {
+      id: parsed.id,
+      workbookId: normalizeWorkbookId(parsed.workbookId),
+      ownerSessionId: parsed.ownerSessionId,
+      name: parsed.name,
+      baseRevision: parsed.baseRevision as number,
+      revision: parsed.revision as number,
+      status: parsed.status,
+      createdAt: parsed.createdAt,
+      updatedAt: parsed.updatedAt,
+      snapshot: parsed.snapshot,
+      operations: Array.isArray(parsed.operations) ? parsed.operations.filter(isStoredOperation) : [],
+    }
+  } catch {
+    return null
+  }
+}
+
+export async function readJsonFile(path: string): Promise<unknown | null> {
+  try { return JSON.parse(await readFile(path, 'utf8')) as unknown } catch { return null }
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try { await access(path); return true } catch { return false }
+}
+
+/** Derive a lightweight summary from a stored workbook. */
+export function summarize(meta: WorkbookMeta): WorkbookSummary {
+  const snap = meta.snapshot as {
+    sheetOrder?: readonly string[]
+    sheets?: Record<string, { id?: string; name?: string; dataSheetSchema?: unknown }>
+  } | null
+  const order = snap?.sheetOrder ?? Object.keys(snap?.sheets ?? {})
+  const sheets = order.map(id => ({
+    id,
+    name: snap?.sheets?.[id]?.name ?? id,
+    ...(isSheetSchema(snap?.sheets?.[id]?.dataSheetSchema) ? { schema: snap?.sheets?.[id]?.dataSheetSchema } : {}),
+  }))
+  return {
+    id: meta.id,
+    name: meta.name,
+    sheets,
+    updatedAt: meta.updatedAt,
+    revision: meta.revision ?? 0,
+  }
+}
+
+export async function withWorkbookTransactionQueue<T>(id: string, task: () => Promise<T>): Promise<T> {
+  const previous = workbookTransactionQueues.get(id) ?? Promise.resolve()
+  const current = previous.catch(() => undefined).then(task)
+  workbookTransactionQueues.set(id, current)
+  try { return await current } finally {
+    if (workbookTransactionQueues.get(id) === current) workbookTransactionQueues.delete(id)
+  }
+}
+
+/** Finish a prepared multi-file commit after a process interruption. */
+export async function recoverWorkbookTransactionNow(id: string): Promise<void> {
+  const journalPath = workbookTransactionPath(id)
+  let transaction: StoredWorkbookTransaction
+  try {
+    transaction = JSON.parse(await readFile(journalPath, 'utf8')) as StoredWorkbookTransaction
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+    throw new DataSheetError('PERSISTENCE_FAILED', `工作簿事务日志损坏：${id}`, 500)
+  }
+  if (!Number.isInteger(transaction.revision) || !Array.isArray(transaction.files) || transaction.files.some(file => typeof file?.target !== 'string' || typeof file?.temp !== 'string')) {
+    throw new DataSheetError('PERSISTENCE_FAILED', `工作簿事务日志无效：${id}`, 500)
+  }
+  for (const file of transaction.files) {
+    if (await fileExists(file.temp)) await rename(file.temp, file.target)
+    else if (!(await fileExists(file.target))) throw new DataSheetError('PERSISTENCE_FAILED', `工作簿事务缺少文件：${file.target}`, 500)
+  }
+  await unlink(journalPath).catch(error => {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  })
+  workbookCache.delete(normalizeWorkbookId(id))
+}
+
+/**
+ * Mirrored by the browser projection's `applyAppendRows`, which runs the same
+ * check against live Univer state. The hint names `headerRowIndex` because that
+ * is what unblocks a report sheet whose real header is not row 0.
+ */
+
+export function isStoredOperation(value: unknown): value is WorkbookOperation {
+  if (typeof value !== 'object' || value === null) return false
+  const operation = value as Partial<WorkbookOperation>
+  return typeof operation.opId === 'string'
+    && typeof operation.workbookId === 'string'
+    && typeof operation.revision === 'number'
+    && (operation.actor === 'agent' || operation.actor === 'user')
+    && isKnownOperationType(operation.type)
+    && typeof operation.timestamp === 'string'
+    && typeof operation.payload === 'object'
+    && operation.payload !== null
+}
+
+export function isStoredIndexOperation(value: unknown): value is WorkbookIndexOperation {
+  if (typeof value !== 'object' || value === null) return false
+  const operation = value as Partial<WorkbookIndexOperation>
+  return typeof operation.opId === 'string'
+    && typeof operation.workbookId === 'string'
+    && typeof operation.revision === 'number'
+    && (operation.actor === 'agent' || operation.actor === 'user')
+    && isKnownOperationType(operation.type)
+    && typeof operation.timestamp === 'string'
+    && typeof operation.summary === 'string'
+}
+
+export function isKnownOperationType(value: unknown): value is WorkbookOperationType {
+  return value === 'update_cells' || value === 'clear_range' || value === 'delete_cells'
+    || value === 'insert_rows' || value === 'delete_rows' || value === 'insert_columns'
+    || value === 'delete_columns' || value === 'create_sheet' || value === 'delete_sheet'
+    || value === 'rename_sheet' || value === 'append_rows' || value === 'format_cells'
+    || value === 'merge_cells' || value === 'unmerge_cells' || value === 'freeze_panes'
+    || value === 'set_column_width' || value === 'set_row_height' || value === 'sort_range'
+    || value === 'set_hyperlink' || value === 'remove_hyperlink' || value === 'remove_duplicates'
+    || value === 'batch' || value === 'snapshot_replace'
+}
+
+export function isStoredSheetSummary(value: unknown): value is { id: string; name: string; schema?: SheetSchema } {
+  if (typeof value !== 'object' || value === null) return false
+  const sheet = value as { id?: unknown; name?: unknown; schema?: unknown }
+  return typeof sheet.id === 'string' && typeof sheet.name === 'string'
+    && (sheet.schema === undefined || isSheetSchema(sheet.schema))
+}
+
+export function isStoredIndexProposal(value: unknown): value is WorkbookIndexProposal {
+  if (typeof value !== 'object' || value === null) return false
+  const proposal = value as Partial<WorkbookIndexProposal>
+  return typeof proposal.id === 'string' && typeof proposal.workbookId === 'string'
+    && (proposal.actor === 'agent' || proposal.actor === 'user')
+    && typeof proposal.baseRevision === 'number' && typeof proposal.createdAt === 'string'
+    && typeof proposal.updatedAt === 'string'
+    && (proposal.status === 'pending' || proposal.status === 'committed' || proposal.status === 'rejected' || proposal.status === 'expired')
+    && typeof proposal.summary === 'string' && Array.isArray(proposal.changes)
+}
+
+export function isStoredProposal(value: unknown): value is WorkbookProposal {
+  if (typeof value !== 'object' || value === null) return false
+  const proposal = value as Partial<WorkbookProposal>
+  return typeof proposal.id === 'string' && typeof proposal.workbookId === 'string'
+    && (proposal.actor === 'agent' || proposal.actor === 'user')
+    && typeof proposal.baseRevision === 'number' && typeof proposal.createdAt === 'string'
+    && typeof proposal.updatedAt === 'string'
+    && (proposal.status === 'pending' || proposal.status === 'committed' || proposal.status === 'rejected' || proposal.status === 'expired')
+    && Array.isArray(proposal.changes) && 'snapshot' in proposal
+}
+
+export function isStoredCheckpoint(value: unknown): value is { revision: number; actor: 'agent' | 'user'; timestamp: string; snapshot: unknown } {
+  if (typeof value !== 'object' || value === null) return false
+  const checkpoint = value as { revision?: unknown; actor?: unknown; timestamp?: unknown; snapshot?: unknown }
+  return typeof checkpoint.revision === 'number'
+    && (checkpoint.actor === 'agent' || checkpoint.actor === 'user')
+    && typeof checkpoint.timestamp === 'string'
+    && 'snapshot' in checkpoint
+}
+
+export interface WorkbookIndex {
+  id: string
+  name: string
+  sheetOrder: string[]
+  sheets: Array<{ id: string; name: string; schema?: SheetSchema }>
+  updatedAt: string
+  revision: number
+  operations: WorkbookIndexOperation[]
+  proposals: WorkbookIndexProposal[]
+}
+
+/** Payload-free operation summary used by catalog/history bootstrap. */
+export interface WorkbookIndexOperation {
+  opId: string
+  workbookId: string
+  revision: number
+  actor: 'agent' | 'user'
+  type: WorkbookOperationType
+  timestamp: string
+  summary: string
+}
+
+export interface WorkbookIndexProposal {
+  id: string
+  workbookId: string
+  actor: 'agent' | 'user'
+  baseRevision: number
+  createdAt: string
+  updatedAt: string
+  status: 'pending' | 'committed' | 'rejected' | 'expired'
+  summary: string
+  changes: WorkbookChange[]
+  committedRevision?: number
+}
+
+export interface WorkbookTransactionFile {
+  target: string
+  value: unknown
+}
+
+export interface StoredWorkbookTransaction {
+  revision: number
+  files: Array<{ target: string; temp: string }>
+}
+
+/** In-process cache: the DSH host is the single mutation authority. */
+export const workbookCache = new Map<string, { meta: WorkbookMeta; checkpointsLoaded: boolean }>()
+
+/** Serialize transaction recovery and commits independently from mutations. */
+export const workbookTransactionQueues = new Map<string, Promise<unknown>>()
+
+export function isWorktreeStatus(value: unknown): value is WorkbookWorktreeStatus {
+  return value === 'draft' || value === 'ready' || value === 'merged' || value === 'discarded'
+}
+
+export function toWorktreeSummary(worktree: WorkbookWorktree): WorkbookWorktreeSummary {
+  const { snapshot: _snapshot, operations: _operations, ...summary } = worktree
+  return summary
+}

package/src/store/retention.ts

@@ -0,0 +1,106 @@
+/**
+ * How long history is kept (docs/issue/0022 P1).
+ *
+ * Two rules, both policy rather than mechanism: how often a rebuildable
+ * checkpoint is taken, and how old a Version's last Step must be before the
+ * session that produced it is considered over. Both are read by the write path
+ * and by the version session, so they live below both.
+ */
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { AUTO_CHECKPOINT_KEEP, VERSION_IDLE_CLOSE_MS, selectAutoCheckpointsToPrune } from '#contracts'
+import { toolOutputRoot } from './paths.ts'
+import { versionKindOfOperations } from '../contract/operations.ts'
+import type { WorkbookMeta, WorkbookOperation } from '../types.ts'
+
+/**
+ * Drop the operations of auto checkpoints outside the retention window
+ * (PRD v3.1 §6.2, D3: newest 100 + the last one of every older day).
+ *
+ * Only history a checkpoint can rebuild from is removed: nothing at or above
+ * `newestCheckpoint - CHECKPOINT_INTERVAL` is touched, so every recent Version
+ * still previews and restores exactly as before. Older auto Versions disappear
+ * from the list instead of lingering as rows that can no longer be replayed;
+ * named Versions and anything a survivor references are always kept.
+ */
+export function pruneAutoVersionOperations(meta: WorkbookMeta): number {
+  const operations = meta.operations ?? []
+  // A conservative early exit, and `AUTO_CHECKPOINT_KEEP` rather than a literal
+  // 100: the policy always keeps the newest N *Versions*, and a Version is one or
+  // more operations, so fewer operations than N means fewer Versions than N and
+  // nothing can be prunable. The count is of operations, the bound is a Version
+  // count, and that is only sound for this direction — which is why the constant
+  // is the right thing to name here and a bare `100` was not.
+  if (operations.length < AUTO_CHECKPOINT_KEEP) return 0
+  const checkpoints = (meta.checkpoints ?? []).map(checkpoint => checkpoint.revision).sort((left, right) => left - right)
+  const newest = checkpoints.at(-1)
+  if (newest === undefined) return 0
+  const cutoff = newest - CHECKPOINT_INTERVAL
+  if (cutoff <= 0) return 0
+  const versionIdOf = (operation: WorkbookOperation): string => operation.versionId ?? `revision:${operation.revision}`
+  const byVersion = new Map<string, WorkbookOperation[]>()
+  for (const operation of operations) {
+    const id = versionIdOf(operation)
+    const group = byVersion.get(id)
+    if (group === undefined) byVersion.set(id, [operation])
+    else group.push(operation)
+  }
+  const versions = [...byVersion.entries()].map(([versionId, group], index) => ({
+    versionId,
+    number: index + 1,
+    status: (group.at(-1)?.versionStatus === 'final' ? 'committed' : 'open') as 'open' | 'committed',
+    kind: versionKindOfOperations(group),
+    createdAt: group[0]?.timestamp,
+  }))
+  const prunable = new Set(selectAutoCheckpointsToPrune(versions).map(version => version.versionId))
+  if (prunable.size === 0) return 0
+  const kept = operations.filter(operation => {
+    const id = versionIdOf(operation)
+    if (!prunable.has(id)) return true
+    // Only drop what a checkpoint can rebuild from.
+    return operation.revision > cutoff
+  })
+  if (kept.length === operations.length) return 0
+  meta.operations = kept
+  return operations.length - kept.length
+}
+
+/** Whether an operation is older than the shared Version merge window (§4.1). */
+export function isIdlePast(timestamp: string, nowMs = Date.now()): boolean {
+  const at = Date.parse(timestamp)
+  return Number.isFinite(at) && nowMs - at >= VERSION_IDLE_CLOSE_MS
+}
+
+export const CHECKPOINT_INTERVAL = 20
+
+/**
+ * How many spilled tool results to keep.
+ *
+ * They exist so the model can page through a result that was too large to inline
+ * — a debugging and continuity aid, not data. Nothing pruned them: every
+ * oversized `workbook_read` wrote a file under the storage root that stayed
+ * forever, which is disk growth with no ceiling and no way for a user to know
+ * why their storage directory kept getting bigger.
+ */
+export const TOOL_OUTPUT_KEEP = 50
+
+/** Delete all but the newest `keep` spilled results. Returns how many went. */
+export async function pruneToolOutput(keep = TOOL_OUTPUT_KEEP): Promise<number> {
+  const directory = toolOutputRoot()
+  const names = await readdir(directory).catch(() => [])
+  const files = []
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+    const full = join(directory, name)
+    const info = await stat(full).catch(() => null)
+    if (info !== null && info.isFile()) files.push({ full, at: info.mtimeMs })
+  }
+  if (files.length <= keep) return 0
+  files.sort((left, right) => right.at - left.at)
+  let removed = 0
+  for (const file of files.slice(keep)) {
+    await rm(file.full, { force: true }).catch(() => undefined)
+    removed += 1
+  }
+  return removed
+}