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

package/lib/types/store/read.js

@@ -0,0 +1,404 @@
+/**
+ * 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.js";
+import { access, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { normalizeWorkbookId } from "../contract/ids.js";
+import { cloneSnapshot, isSheetSchema, normalizeSnapshotName } from "../contract/snapshots.js";
+import { applyWorkbookOperation } from "../contract/mutations.js";
+import { workbookCheckpointsPath, workbookIndexPath, workbookOperationsPath, workbookPath, workbookProposalsPath, workbookSnapshotPath, workbookTransactionPath, workbookRoot, workbookWorktreeDirectory, workbookWorktreePath, } from "./paths.js";
+/** Whether a workbook file exists. */
+export async function workbookExists(id) {
+    return fileExists(workbookPath(id));
+}
+/** Read only the sidecar index; a missing/invalid sidecar falls back safely. */
+export async function readWorkbookIndex(id) {
+    try {
+        await withWorkbookTransactionQueue(normalizeWorkbookId(id), () => recoverWorkbookTransactionNow(normalizeWorkbookId(id)));
+        const parsed = JSON.parse(await readFile(workbookIndexPath(id), 'utf8'));
+        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,
+            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, options = {}) {
+    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));
+                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);
+        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));
+            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))
+            : 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 = {
+            ...parsed,
+            snapshot: normalizeSnapshotName(snapshot, parsed.name),
+            revision: Number.isInteger(parsed.revision) && parsed.revision >= 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, targetRevision) {
+    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));
+    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() {
+    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() {
+    const summaries = [];
+    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, ownerSessionId) {
+    const normalizedWorkbookId = normalizeWorkbookId(workbookId);
+    try {
+        const entries = await readdir(workbookWorktreeDirectory(normalizedWorkbookId), { withFileTypes: true });
+        const result = [];
+        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, worktreeId) {
+    try {
+        const parsed = JSON.parse(await readFile(workbookWorktreePath(workbookId, worktreeId), 'utf8'));
+        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,
+            revision: parsed.revision,
+            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) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Derive a lightweight summary from a stored workbook. */
+export function summarize(meta) {
+    const snap = meta.snapshot;
+    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(id, task) {
+    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) {
+    const journalPath = workbookTransactionPath(id);
+    let transaction;
+    try {
+        transaction = JSON.parse(await readFile(journalPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.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.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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const operation = value;
+    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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const operation = value;
+    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) {
+    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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const sheet = value;
+    return typeof sheet.id === 'string' && typeof sheet.name === 'string'
+        && (sheet.schema === undefined || isSheetSchema(sheet.schema));
+}
+export function isStoredIndexProposal(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proposal = value;
+    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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proposal = value;
+    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) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const checkpoint = value;
+    return typeof checkpoint.revision === 'number'
+        && (checkpoint.actor === 'agent' || checkpoint.actor === 'user')
+        && typeof checkpoint.timestamp === 'string'
+        && 'snapshot' in checkpoint;
+}
+/** In-process cache: the DSH host is the single mutation authority. */
+export const workbookCache = new Map();
+/** Serialize transaction recovery and commits independently from mutations. */
+export const workbookTransactionQueues = new Map();
+export function isWorktreeStatus(value) {
+    return value === 'draft' || value === 'ready' || value === 'merged' || value === 'discarded';
+}
+export function toWorktreeSummary(worktree) {
+    const { snapshot: _snapshot, operations: _operations, ...summary } = worktree;
+    return summary;
+}

package/lib/types/store/retention.d.ts

@@ -0,0 +1,27 @@
+import type { WorkbookMeta } 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 declare function pruneAutoVersionOperations(meta: WorkbookMeta): number;
+/** Whether an operation is older than the shared Version merge window (§4.1). */
+export declare function isIdlePast(timestamp: string, nowMs?: number): boolean;
+export declare 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 declare const TOOL_OUTPUT_KEEP = 50;
+/** Delete all but the newest `keep` spilled results. Returns how many went. */
+export declare function pruneToolOutput(keep?: number): Promise<number>;

package/lib/types/store/retention.js

@@ -0,0 +1,111 @@
+/**
+ * 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.js";
+import { versionKindOfOperations } from "../contract/operations.js";
+/**
+ * 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) {
+    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) => operation.versionId ?? `revision:${operation.revision}`;
+    const byVersion = new Map();
+    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'),
+        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, nowMs = Date.now()) {
+    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) {
+    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;
+}

package/lib/types/store/write.d.ts

@@ -0,0 +1,22 @@
+import { type WorkbookMeta, type WorkbookWorktree } from '../types.ts';
+import { type WorkbookIndex, type WorkbookTransactionFile } from './read.ts';
+/** Write one workbook meta atomically (creates the repo root on demand). */
+export declare function writeWorkbook(meta: WorkbookMeta, options?: {
+    persistSnapshot?: boolean;
+    persistCheckpoints?: boolean;
+}): Promise<void>;
+export declare function writeJsonAtomically(path: string, value: unknown): Promise<void>;
+export declare function commitWorkbookTransaction(id: string, files: WorkbookTransactionFile[], revision: number): Promise<void>;
+export declare function writeWorktree(worktree: WorkbookWorktree): Promise<void>;
+export declare function buildWorkbookIndex(meta: WorkbookMeta): WorkbookIndex;
+/**
+ * Delete a workbook and all of its Datasheet sidecars. `main` is the stable
+ * default workbook and is intentionally protected from accidental deletion.
+ * The queue makes deletion serialize with an in-flight save for the same id.
+ */
+export declare function deleteWorkbook(id: string): Promise<void>;
+/** Rename the user-facing workbook label without changing its stable id or
+ * history. The snapshot name is kept in sync by `writeWorkbook`. */
+export declare function renameWorkbook(id: string, name: string): Promise<WorkbookMeta>;
+export declare function withWorkbookQueue<T>(id: string, task: () => Promise<T>): Promise<T>;
+export declare function withWorktreeQueue<T>(workbookId: string, worktreeId: string, task: () => Promise<T>): Promise<T>;