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

package/lib/types/invariant.js

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for dsh-data-table.
+ *
+ * Runtime invariant: the browser half can only render a sheet that the host
+ * tool admitted, because the renderer parses the durable tool-call arguments
+ * through {@link isSheetData} — the same shape the tool validated. A renderer
+ * reaching an unvalidated sheet is a build-level type violation, not a runtime
+ * state, so the companion registers the manifest name only.
+ * @module dsh-data-table/invariant
+ */
+export const manifest = 'dsh-data-table';
+export const invariant = {
+    manifest,
+    reason: 'renderer input is the host-validated tool-call arguments (isSheetData); no runtime event/data relation to check',
+};

package/lib/types/request-params.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Request vocabulary shared by both transports (docs/issue/0022 P3).
+ *
+ * The browser posts a JSON body and the Agent passes tool arguments, but both
+ * have to become the same `WorkbookOperationPayload`. These parsers are that
+ * translation, and they are validation-first: each one rejects what it cannot
+ * represent instead of coercing it.
+ *
+ * They live here rather than in `http/` because the Agent tools need exactly the
+ * same conversions, and a tool importing from the HTTP layer would make the two
+ * transports depend on each other.
+ */
+import { type WorkbookOperationPayload, type WorkbookOperationType, type WorkbookRange } from './types.ts';
+export declare function parseIndex(value: unknown, label: string): number;
+export declare function optionalRevision(value: unknown): number | undefined;
+export declare function isOperationType(value: unknown): value is WorkbookOperationType;
+export declare function asOperationPayload(value: unknown): WorkbookOperationPayload;
+export declare function parseRange(value: unknown): WorkbookRange;
+export declare function a1ColumnIndex(value: string): number;
+export declare function parseA1Range(value: string): WorkbookRange;
+export declare function normalizeValueMatrix(value: unknown): unknown[][];

package/lib/types/request-params.js

@@ -0,0 +1,76 @@
+import { validateRange } from "./contract/snapshots.js";
+export function parseIndex(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+        throw new Error(`${label} 必须是大于等于 0 的整数`);
+    return value;
+}
+export function optionalRevision(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return parseIndex(value, 'baseRevision');
+}
+export function isOperationType(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 asOperationPayload(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('operation payload 必须是对象');
+    return value;
+}
+export function parseRange(value) {
+    if (typeof value === 'string')
+        return parseA1Range(value);
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('range 必须是对象');
+    const raw = value;
+    const range = {
+        startRow: parseIndex(raw.startRow, 'range.startRow'),
+        startColumn: parseIndex(raw.startColumn, 'range.startColumn'),
+        endRow: parseIndex(raw.endRow, 'range.endRow'),
+        endColumn: parseIndex(raw.endColumn, 'range.endColumn'),
+    };
+    // One validator, not two opinions. This checked only the span, so a range far
+    // past the end of any sheet (`startRow: 9e8`) was accepted here and rejected
+    // later by whichever mutator happened to consult the absolute bound — with a
+    // different message. `parseA1Range` reaches this through the object branch, so
+    // both spellings of a range are now validated identically.
+    validateRange(range);
+    return range;
+}
+export function a1ColumnIndex(value) {
+    let result = 0;
+    for (const character of value.toUpperCase())
+        result = result * 26 + character.charCodeAt(0) - 64;
+    return result - 1;
+}
+export function parseA1Range(value) {
+    const match = /^\s*([A-Za-z]+)(\d+)(?::([A-Za-z]+)(\d+))?\s*$/.exec(value);
+    if (match === null)
+        throw new Error('range 必须是 0-based 对象，或类似 A1:D4 的范围字符串');
+    const startColumn = a1ColumnIndex(match[1]);
+    const startRow = Number(match[2]) - 1;
+    const endColumn = match[3] === undefined ? startColumn : a1ColumnIndex(match[3]);
+    const endRow = match[4] === undefined ? startRow : Number(match[4]) - 1;
+    return parseRange({ startRow, startColumn, endRow, endColumn });
+}
+export function normalizeValueMatrix(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error('values 必须是非空二维数组');
+    const rows = value.every(item => !Array.isArray(item)) ? [value] : value;
+    if (!rows.every(item => Array.isArray(item)))
+        throw new Error('values 必须是二维数组');
+    const width = Math.max(...rows.map(item => item.length));
+    if (width === 0)
+        throw new Error('values 不能包含空行');
+    // Ragged model-generated matrices are padded instead of rejected. This
+    // makes a four-row write safe when one row has a missing trailing field.
+    return rows.map(item => Array.from({ length: width }, (_value, index) => item[index] ?? null));
+}

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

@@ -0,0 +1,68 @@
+/** Resolve the DSH home, honoring $DSH_HOME (mirror of dsh-home-paths). */
+export declare function dshHome(): string;
+/**
+ * Repository root for this plugin.
+ *
+ * Two answers, and the difference is which project the call belongs to:
+ *
+ *  - **inside a Session** (an HTTP route or a tool call, which establish the
+ *    scope — see `./project.ts`): `<project>/storages/data-table`, so a
+ *    project directory is self-contained.
+ *  - **outside one** (a script, a test, an un-migrated caller): the pre-project
+ *    per-user location, unchanged. Answering that case with `process.cwd()`
+ *    would silently start a *new* store for a caller that was reading the old
+ *    one, which is worse than keeping it.
+ *
+ * `data-sheet` → `data-table` renamed that per-user root; resolving the root is
+ * the single choke point every read and write goes through, so the one-time
+ * migration runs here and is memoized afterwards.
+ */
+export declare function workbookRoot(): string;
+/**
+ * The pre-project, per-user storage root.
+ *
+ * Named rather than inlined because it is read by more than the fallback: the
+ * workbook list offers its contents as "from the old location" for a user who
+ * has workbooks there and none here yet.
+ */
+export declare function globalWorkbookRoot(): string;
+/** Storage root used before the data-sheet → data-table rename. */
+export declare function legacyWorkbookRoot(): string;
+/**
+ * Move `<dshHome>/storages/data-sheet` to `storages/data-table` exactly once.
+ *
+ * Idempotent and safe to call from every read/write path: the old root is only
+ * moved when the new root does not exist yet, so a second call is a no-op and
+ * two populated roots are never merged (the legacy files are left untouched
+ * rather than deleted).
+ * @returns the outcome of the first migration attempt.
+ */
+export declare function migrateLegacyWorkbookStorage(): WorkbookStorageMigration;
+/** Current root without triggering the migration (avoids recursion). */
+/**
+ * Where oversized tool results are spilled.
+ *
+ * Under the storage root, and here rather than in the module that writes them:
+ * what a spilled result *is* belongs to the tool presentation, but where plugin
+ * data lives is the store's business — and so is what to do when there is too
+ * much of it.
+ */
+export declare function toolOutputRoot(): string;
+export declare function workbookRootWithoutMigration(): string;
+/** Absolute snapshot path for one workbook. */
+export declare function workbookPath(id: string): string;
+/** Lightweight metadata path used by polling, workbook lists, and history. */
+export declare function workbookIndexPath(id: string): string;
+export declare function workbookSnapshotPath(id: string): string;
+export declare function workbookCheckpointsPath(id: string): string;
+/** Full operation log is kept out of the workbook metadata file. */
+export declare function workbookOperationsPath(id: string): string;
+/** Pending proposals (which may contain a full preview snapshot) are sidecar data. */
+export declare function workbookProposalsPath(id: string): string;
+export declare function workbookTransactionPath(id: string): string;
+/** Isolated review worktrees live below the workbook repository and never
+ * participate in the trunk workbook catalog. */
+export declare function workbookWorktreeDirectory(workbookId: string): string;
+export declare function workbookWorktreePath(workbookId: string, worktreeId: string): string;
+/** Outcome of {@link migrateLegacyWorkbookStorage}. */
+export type WorkbookStorageMigration = 'no-legacy' | 'migrated' | 'target-exists' | 'failed';

package/lib/types/store/paths.js

@@ -0,0 +1,148 @@
+/**
+ * Where a workbook's files live in the DSH home (docs/issue/0022 P1).
+ *
+ * The single choke point every read and write goes through, which is why the
+ * one-time `data-sheet` → `data-table` rename is performed here rather than at
+ * a call site. Nothing else in the plugin may build a storage path.
+ */
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { normalizeWorkbookId, normalizeWorktreeId } from "../contract/ids.js";
+import { currentProjectRoot, projectStoragesRoot } from "./project.js";
+/**
+ * The home the migration has already been attempted for, and what happened.
+ *
+ * Keyed by the resolved home rather than a bare boolean: `$DSH_HOME` is read on
+ * every call, and the previous process-wide flag meant a home that changed
+ * mid-process was never migrated at all — it returned the *other* home's
+ * outcome. The memo exists to avoid re-stat-ing on every operation, which keying
+ * by home still does.
+ */
+let storageMigrationHome = null;
+let storageMigrationOutcome = 'no-legacy';
+/** Resolve the DSH home, honoring $DSH_HOME (mirror of dsh-home-paths). */
+export function dshHome() {
+    const env = process.env.DSH_HOME;
+    const home = env !== undefined && env.trim().length > 0 ? env : join(homedir(), '.dsh');
+    return resolve(home);
+}
+/**
+ * Repository root for this plugin.
+ *
+ * Two answers, and the difference is which project the call belongs to:
+ *
+ *  - **inside a Session** (an HTTP route or a tool call, which establish the
+ *    scope — see `./project.ts`): `<project>/storages/data-table`, so a
+ *    project directory is self-contained.
+ *  - **outside one** (a script, a test, an un-migrated caller): the pre-project
+ *    per-user location, unchanged. Answering that case with `process.cwd()`
+ *    would silently start a *new* store for a caller that was reading the old
+ *    one, which is worse than keeping it.
+ *
+ * `data-sheet` → `data-table` renamed that per-user root; resolving the root is
+ * the single choke point every read and write goes through, so the one-time
+ * migration runs here and is memoized afterwards.
+ */
+export function workbookRoot() {
+    migrateLegacyWorkbookStorage();
+    const project = currentProjectRoot();
+    return project === undefined ? globalWorkbookRoot() : projectStoragesRoot(project);
+}
+/**
+ * The pre-project, per-user storage root.
+ *
+ * Named rather than inlined because it is read by more than the fallback: the
+ * workbook list offers its contents as "from the old location" for a user who
+ * has workbooks there and none here yet.
+ */
+export function globalWorkbookRoot() {
+    return join(dshHome(), 'storages', 'data-table');
+}
+/** Storage root used before the data-sheet → data-table rename. */
+export function legacyWorkbookRoot() {
+    return join(dshHome(), 'storages', 'data-sheet');
+}
+/**
+ * Move `<dshHome>/storages/data-sheet` to `storages/data-table` exactly once.
+ *
+ * Idempotent and safe to call from every read/write path: the old root is only
+ * moved when the new root does not exist yet, so a second call is a no-op and
+ * two populated roots are never merged (the legacy files are left untouched
+ * rather than deleted).
+ * @returns the outcome of the first migration attempt.
+ */
+export function migrateLegacyWorkbookStorage() {
+    const home = dshHome();
+    if (storageMigrationHome === home)
+        return storageMigrationOutcome;
+    storageMigrationHome = home;
+    const legacy = legacyWorkbookRoot();
+    const target = workbookRootWithoutMigration();
+    try {
+        if (legacy === target || !existsSync(legacy))
+            return (storageMigrationOutcome = 'no-legacy');
+        if (existsSync(target))
+            return (storageMigrationOutcome = 'target-exists');
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(legacy, target);
+        return (storageMigrationOutcome = 'migrated');
+    }
+    catch {
+        // A failed rename must never take the plugin down; the legacy root stays
+        // where it is and the next call retries.
+        storageMigrationHome = null;
+        return (storageMigrationOutcome = 'failed');
+    }
+}
+/** Current root without triggering the migration (avoids recursion). */
+/**
+ * Where oversized tool results are spilled.
+ *
+ * Under the storage root, and here rather than in the module that writes them:
+ * what a spilled result *is* belongs to the tool presentation, but where plugin
+ * data lives is the store's business — and so is what to do when there is too
+ * much of it.
+ */
+export function toolOutputRoot() {
+    return join(workbookRoot(), 'tool-output');
+}
+export function workbookRootWithoutMigration() {
+    return join(dshHome(), 'storages', 'data-table');
+}
+/** Absolute snapshot path for one workbook. */
+export function workbookPath(id) {
+    // Keep this boundary safe even for callers outside the tool/HTTP adapters.
+    // Those adapters already normalize ids, but this exported repository helper
+    // must not allow `../` segments to escape the Datasheet storage directory.
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.json`);
+}
+/** Lightweight metadata path used by polling, workbook lists, and history. */
+export function workbookIndexPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.index.json`);
+}
+export function workbookSnapshotPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.snapshot.json`);
+}
+export function workbookCheckpointsPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.checkpoints.json`);
+}
+/** Full operation log is kept out of the workbook metadata file. */
+export function workbookOperationsPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.operations.json`);
+}
+/** Pending proposals (which may contain a full preview snapshot) are sidecar data. */
+export function workbookProposalsPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.proposals.json`);
+}
+export function workbookTransactionPath(id) {
+    return join(workbookRoot(), `${normalizeWorkbookId(id)}.transaction.json`);
+}
+/** Isolated review worktrees live below the workbook repository and never
+ * participate in the trunk workbook catalog. */
+export function workbookWorktreeDirectory(workbookId) {
+    return join(workbookRoot(), '.worktrees', normalizeWorkbookId(workbookId));
+}
+export function workbookWorktreePath(workbookId, worktreeId) {
+    return join(workbookWorktreeDirectory(workbookId), `${normalizeWorktreeId(worktreeId)}.json`);
+}

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

@@ -0,0 +1,88 @@
+/** This plugin's directory inside a project's `storages/`. */
+export declare const PLUGIN_DIRECTORY = "data-table";
+/**
+ * Run one unit of work with a project root in scope.
+ *
+ * @param root - Absolute project directory.
+ * @param body - The work; may be async, and keeps the scope across its awaits.
+ * @returns whatever `body` returns.
+ */
+export declare function runInProject<T>(root: string, body: () => T): T;
+/**
+ * The project root in scope, when there is one.
+ *
+ * `undefined` means "no project": a script, a test, or a caller that has not been
+ * migrated. `workbookRoot()` answers that case with the pre-project location
+ * rather than inventing a project, so an un-migrated caller keeps reading and
+ * writing where it always did instead of quietly starting a new store.
+ */
+export declare function currentProjectRoot(): string | undefined;
+/**
+ * The bits of DSH's Session registry this module reads.
+ *
+ * Read structurally — it arrives from the Host, and a caller may run without it
+ * (a test harness, an embedding with no Host services).
+ */
+export interface SessionRegistry {
+    /** Look one Session up by id; `undefined` when no such Session is live. */
+    get?: (id: string) => {
+        readonly header?: {
+            readonly cwd?: unknown;
+        };
+    } | undefined;
+}
+/**
+ * The project directory one Session's store calls belong to, or `undefined` for
+ * "no project".
+ *
+ * The Session **header** is the only source, and it is read through the Host's
+ * registry (`ctx.sessions.get(id)`) rather than off the calling Agent's own
+ * Session object. That is the fix for a real bug (2026-10-02): the tools read
+ * `agent.session.cwd`, a field a Session does not have — a Session carries its
+ * directory at `session.header.cwd` — so every tool call answered "no project"
+ * and wrote to the per-user store while the browser panel wrote to
+ * `<project>/storages/data-table`. The Agent and the open Table were editing two
+ * different sets of workbooks, and neither could see the other's.
+ *
+ * Reading the registry also makes the two transports agree by construction: an
+ * HTTP request names a Session id, a tool call names the same id through its
+ * Agent, and both are answered by the same header. `data-excalidraw` resolves its
+ * scene directory the same way, for the same reason.
+ *
+ * The Host's sandbox policy is deliberately *not* consulted: a plugin context
+ * cannot read it (see `src/index.ts`), and the one attempt to use it as a
+ * fallback turned every workbook list into a bodyless 400.
+ *
+ * `undefined` is a real answer and not a failure: it means the caller named no
+ * Session, so nobody has said which project this is. The two ways to get it
+ * wrong are both worse than a missing project — `process.cwd()` would silently
+ * start a *new* per-project store for a caller that was reading the old per-user
+ * one (a test, a script, an older client), and a shared per-process default
+ * would mix two Sessions' writes. Callers therefore leave the scope unset, and
+ * `workbookRoot()` answers with the pre-project location it always used.
+ *
+ * @param sessions - DSH's Session registry, from the injected `sessions` service.
+ * @param sessionId - The Session naming the project; `undefined` or empty for a
+ *   caller that named none.
+ * @returns an absolute project directory, or `undefined` when nothing named one.
+ */
+export declare function projectScopeOf(sessions: SessionRegistry | undefined, sessionId: string | undefined): string | undefined;
+/**
+ * This plugin's storage inside one project.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages/data-table`, which may not exist yet.
+ */
+export declare function projectStoragesRoot(root: string): string;
+/**
+ * The project's storage container, shared by every plugin.
+ *
+ * The file chooser lists this directory rather than the project root: it is
+ * where a project's data lives, and it is what a copy of the project directory
+ * carries. A user who wants a file from elsewhere uses the "从项目外导入" path,
+ * which is deliberately unrestricted.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages`, which may not exist yet.
+ */
+export declare function projectStoragesDirectory(root: string): string;

package/lib/types/store/project.js

@@ -0,0 +1,120 @@
+/**
+ * Which project a store call belongs to (project-local storage, 2026-09-25).
+ *
+ * A workbook used to live in one per-user directory (`~/.dsh/storages/data-table`)
+ * shared by every Session. It now lives in the project it belongs to —
+ * `<project>/storages/data-table` — so copying a project directory copies its
+ * workbooks, and deleting one leaves nothing behind in the user's home.
+ *
+ * The store modules are called from three places that do **not** share a call
+ * shape: HTTP route handlers (which name a Session id), Agent tool executions
+ * (which carry the calling Agent), and plain scripts and tests (which have
+ * neither). Rather than thread a root parameter through every read and write —
+ * `workbookRoot()` is the single choke point they all pass through — the project
+ * travels in an async context for the duration of one request or tool call.
+ * `AsyncLocalStorage` rather than a module variable because one Host process
+ * serves several Sessions at once: a global would let two projects' writes
+ * interleave into the wrong directory, which is the one failure this must not
+ * have.
+ *
+ * The three callers converge on one question, asked in one place:
+ * {@link projectScopeOf} turns "this Session" into "this project directory" by
+ * looking the Session up in the Host's registry and reading its **header**. A
+ * tool and a browser request naming the same Session therefore mean the same
+ * directory by construction rather than by both computing it the same way.
+ *
+ * @module dsh-data-table/store/project
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { join } from 'node:path';
+import { STORAGES_DIRECTORY, isProjectDirectory } from '#contracts';
+/** This plugin's directory inside a project's `storages/`. */
+export const PLUGIN_DIRECTORY = 'data-table';
+const scope = new AsyncLocalStorage();
+/**
+ * Run one unit of work with a project root in scope.
+ *
+ * @param root - Absolute project directory.
+ * @param body - The work; may be async, and keeps the scope across its awaits.
+ * @returns whatever `body` returns.
+ */
+export function runInProject(root, body) {
+    return scope.run(root, body);
+}
+/**
+ * The project root in scope, when there is one.
+ *
+ * `undefined` means "no project": a script, a test, or a caller that has not been
+ * migrated. `workbookRoot()` answers that case with the pre-project location
+ * rather than inventing a project, so an un-migrated caller keeps reading and
+ * writing where it always did instead of quietly starting a new store.
+ */
+export function currentProjectRoot() {
+    return scope.getStore();
+}
+/**
+ * The project directory one Session's store calls belong to, or `undefined` for
+ * "no project".
+ *
+ * The Session **header** is the only source, and it is read through the Host's
+ * registry (`ctx.sessions.get(id)`) rather than off the calling Agent's own
+ * Session object. That is the fix for a real bug (2026-10-02): the tools read
+ * `agent.session.cwd`, a field a Session does not have — a Session carries its
+ * directory at `session.header.cwd` — so every tool call answered "no project"
+ * and wrote to the per-user store while the browser panel wrote to
+ * `<project>/storages/data-table`. The Agent and the open Table were editing two
+ * different sets of workbooks, and neither could see the other's.
+ *
+ * Reading the registry also makes the two transports agree by construction: an
+ * HTTP request names a Session id, a tool call names the same id through its
+ * Agent, and both are answered by the same header. `data-excalidraw` resolves its
+ * scene directory the same way, for the same reason.
+ *
+ * The Host's sandbox policy is deliberately *not* consulted: a plugin context
+ * cannot read it (see `src/index.ts`), and the one attempt to use it as a
+ * fallback turned every workbook list into a bodyless 400.
+ *
+ * `undefined` is a real answer and not a failure: it means the caller named no
+ * Session, so nobody has said which project this is. The two ways to get it
+ * wrong are both worse than a missing project — `process.cwd()` would silently
+ * start a *new* per-project store for a caller that was reading the old per-user
+ * one (a test, a script, an older client), and a shared per-process default
+ * would mix two Sessions' writes. Callers therefore leave the scope unset, and
+ * `workbookRoot()` answers with the pre-project location it always used.
+ *
+ * @param sessions - DSH's Session registry, from the injected `sessions` service.
+ * @param sessionId - The Session naming the project; `undefined` or empty for a
+ *   caller that named none.
+ * @returns an absolute project directory, or `undefined` when nothing named one.
+ */
+export function projectScopeOf(sessions, sessionId) {
+    if (sessionId === undefined || sessionId.length === 0)
+        return undefined;
+    const cwd = sessions?.get?.(sessionId)?.header?.cwd;
+    // A filesystem root counts as "not named": treating `/` as a project root
+    // meant creating `/storages/data-table`.
+    return isProjectDirectory(cwd) ? cwd : undefined;
+}
+/**
+ * This plugin's storage inside one project.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages/data-table`, which may not exist yet.
+ */
+export function projectStoragesRoot(root) {
+    return join(root, STORAGES_DIRECTORY, PLUGIN_DIRECTORY);
+}
+/**
+ * The project's storage container, shared by every plugin.
+ *
+ * The file chooser lists this directory rather than the project root: it is
+ * where a project's data lives, and it is what a copy of the project directory
+ * carries. A user who wants a file from elsewhere uses the "从项目外导入" path,
+ * which is deliberately unrestricted.
+ *
+ * @param root - Project directory.
+ * @returns `<root>/storages`, which may not exist yet.
+ */
+export function projectStoragesDirectory(root) {
+    return join(root, STORAGES_DIRECTORY);
+}

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

@@ -0,0 +1,110 @@
+import { type SheetSchema, type WorkbookChange, type WorkbookMeta, type WorkbookOperation, type WorkbookOperationType, type WorkbookProposal, type WorkbookSummary, type WorkbookWorktree, type WorkbookWorktreeStatus, type WorkbookWorktreeSummary } from '../types.ts';
+/** Whether a workbook file exists. */
+export declare function workbookExists(id: string): Promise<boolean>;
+/** Read only the sidecar index; a missing/invalid sidecar falls back safely. */
+export declare function readWorkbookIndex(id: string): Promise<WorkbookIndex | null>;
+/** Read one workbook meta. */
+export declare function readWorkbook(id: string, options?: {
+    includeCheckpoints?: boolean;
+}): Promise<WorkbookMeta | 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 declare function readWorkbookAtRevision(workbookId: string, targetRevision: number): Promise<{
+    snapshot: unknown;
+    revision: number;
+} | null>;
+/** List workbook ids (files in the repo root, sorted by name). */
+export declare function listWorkbooks(): Promise<string[]>;
+/** List workbook summaries for the browser picker and other read-only clients. */
+export declare function listWorkbookSummaries(): Promise<WorkbookSummary[]>;
+/** List worktrees belonging to a workbook, optionally scoped to one session. */
+export declare function listWorkbookWorktrees(workbookId: string, ownerSessionId?: string): Promise<WorkbookWorktreeSummary[]>;
+/** Read one isolated worktree, including its snapshot and operation tail. */
+export declare function readWorkbookWorktree(workbookId: string, worktreeId: string): Promise<WorkbookWorktree | null>;
+export declare function readJsonFile(path: string): Promise<unknown | null>;
+export declare function fileExists(path: string): Promise<boolean>;
+/** Derive a lightweight summary from a stored workbook. */
+export declare function summarize(meta: WorkbookMeta): WorkbookSummary;
+export declare function withWorkbookTransactionQueue<T>(id: string, task: () => Promise<T>): Promise<T>;
+/** Finish a prepared multi-file commit after a process interruption. */
+export declare function recoverWorkbookTransactionNow(id: string): Promise<void>;
+/**
+ * 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 declare function isStoredOperation(value: unknown): value is WorkbookOperation;
+export declare function isStoredIndexOperation(value: unknown): value is WorkbookIndexOperation;
+export declare function isKnownOperationType(value: unknown): value is WorkbookOperationType;
+export declare function isStoredSheetSummary(value: unknown): value is {
+    id: string;
+    name: string;
+    schema?: SheetSchema;
+};
+export declare function isStoredIndexProposal(value: unknown): value is WorkbookIndexProposal;
+export declare function isStoredProposal(value: unknown): value is WorkbookProposal;
+export declare function isStoredCheckpoint(value: unknown): value is {
+    revision: number;
+    actor: 'agent' | 'user';
+    timestamp: string;
+    snapshot: unknown;
+};
+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 declare const workbookCache: Map<string, {
+    meta: WorkbookMeta;
+    checkpointsLoaded: boolean;
+}>;
+/** Serialize transaction recovery and commits independently from mutations. */
+export declare const workbookTransactionQueues: Map<string, Promise<unknown>>;
+export declare function isWorktreeStatus(value: unknown): value is WorkbookWorktreeStatus;
+export declare function toWorktreeSummary(worktree: WorkbookWorktree): WorkbookWorktreeSummary;