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

package/lib/types/version/records.js

@@ -0,0 +1,102 @@
+/**
+ * A Version as the wire presents it (docs/issue/0022 P2/P3).
+ *
+ * The history endpoint and the Agent's history tool answer the same question,
+ * so they must produce the same record shape — including the content hash that
+ * lets a client prove it has the right Version without materializing a snapshot.
+ * That is why this is not part of either transport.
+ *
+ * `node:crypto` is deliberate and is pure computation: the hash is of the
+ * Version's *inputs* (its checkpoint plus its ordered Step ids), not of a file.
+ */
+import { createHash } from 'node:crypto';
+/** Follow logical parents from the current head. Versions skipped by a
+ * rollback remain in history but are no longer part of the active main line. */
+export function activeHistoryRevisions(currentRevision, operations) {
+    const active = new Set();
+    let cursor = currentRevision;
+    const visited = new Set();
+    while (cursor > 0 && !visited.has(cursor)) {
+        visited.add(cursor);
+        const operation = operations.get(cursor);
+        if (operation === undefined)
+            break;
+        active.add(cursor);
+        cursor = operation.parentRevision ?? Math.max(0, cursor - 1);
+    }
+    return active;
+}
+export function canReplayHistoryRevision(targetRevision, currentRevision, checkpoints, operations) {
+    if (targetRevision === currentRevision)
+        return true;
+    const checkpoint = checkpoints.filter(revision => revision <= targetRevision).at(-1);
+    if (checkpoint === undefined)
+        return false;
+    for (let revision = checkpoint + 1; revision <= targetRevision; revision += 1) {
+        const operation = operations.get(revision);
+        if (operation === undefined || (operation.type === 'snapshot_replace' && operation.payload.snapshot === undefined))
+            return false;
+    }
+    return true;
+}
+/**
+ * Stable content hash for a Version (PRD §3.2): the checkpoint the Version
+ * starts from, plus the ordered opIds applied on top of it. It is a pure
+ * function of the Version's inputs, so the history list never has to
+ * materialise or copy a workbook snapshot into the browser (PRD §11).
+ */
+export function versionContentHash(version, checkpointHash) {
+    const chain = version.steps.map(step => step.opId).join(',');
+    return createHash('sha256').update(`${checkpointHash(version.revision)}#${version.startRevision}#${chain}`).digest('hex');
+}
+/** Map the Data Sheet history shape onto the shared Version record (PRD §7.1). */
+export function toVersionRecords(versions, workbookId, checkpointHash) {
+    return versions.map(version => {
+        const status = version.status === 'final'
+            ? 'committed'
+            : version.status === 'temporary'
+                ? 'open'
+                : version.status;
+        return {
+            versionId: version.versionId,
+            artifactKind: 'workbook',
+            artifactId: workbookId,
+            number: version.number,
+            startRevision: version.startRevision,
+            endRevision: version.revision,
+            // The unified record points at the reinstated Version, like other versioned artifacts
+            // record does; `r48` only survives on the legacy history shape.
+            ...(version.restoredFromRevision === undefined
+                ? {}
+                : { restoredFromVersionId: versions.find(candidate => candidate.revision === version.restoredFromRevision)?.versionId ?? `r${version.restoredFromRevision}` }),
+            status,
+            kind: version.kind,
+            actor: version.actor === 'agent' ? 'agent' : 'user',
+            summary: version.summary,
+            ...(version.intent === undefined ? {} : { intent: version.intent }),
+            stepCount: version.stepCount,
+            contentHash: versionContentHash(version, checkpointHash),
+            createdAt: version.timestamp,
+            ...(status === 'committed' || status === 'restored' ? { committedAt: version.timestamp } : {}),
+            ...(version.lineage === undefined ? {} : { lineage: version.lineage }),
+            replayable: version.canPreview,
+        };
+    });
+}
+/** Memoized checkpoint hash lookup: hashes each snapshot at most once. */
+export function checkpointHasher(checkpoints) {
+    const ascending = checkpoints.slice().sort((left, right) => left.revision - right.revision);
+    const cache = new Map();
+    const genesis = createHash('sha256').update('genesis').digest('hex');
+    return (revision) => {
+        const cached = cache.get(revision);
+        if (cached !== undefined)
+            return cached;
+        const base = ascending.filter(checkpoint => checkpoint.revision <= revision).at(-1);
+        const hash = base === undefined
+            ? genesis
+            : createHash('sha256').update(JSON.stringify(base.snapshot)).digest('hex');
+        cache.set(revision, hash);
+        return hash;
+    };
+}

package/lib/types/version/session.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The editing session: when a Version opens, what closes it, and the shape of
+ * the version fields on the wire (docs/issue/0022 P2).
+ *
+ * Two boundaries close a session (PRD v3.5 D21) — the idle window and the Step
+ * cap — and nothing else does. `settleIdleUserVersions` exists because the write
+ * path can only fork a session when the *next* write arrives: an abandoned tab
+ * left a Version `open` forever, so settling is evaluated lazily at the moment
+ * the user can observe the outcome (reading the version list).
+ */
+import { type VersionKind } from '#contracts';
+import type { WorkbookMeta, WorkbookVersionStatus } from '../types.ts';
+export declare const VERSION_STEP_LIMIT = 20;
+/** Old logs use `temporary`; expose it as the clearer `open` lifecycle state. */
+export declare function normalizeVersionStatus(status: WorkbookVersionStatus | undefined): WorkbookVersionStatus | undefined;
+/** v3 tier on the wire; unknown values are dropped rather than guessed. */
+export declare function normalizeVersionKind(kind: VersionKind | undefined): VersionKind | undefined;
+export declare function isOpenVersionStatus(status: WorkbookVersionStatus | undefined): boolean;
+export declare function optionalVersionText(value: string | undefined, name: string, maxLength: number): string | undefined;
+export declare function finalizeOpenUserVersions(meta: WorkbookMeta): void;
+/**
+ * Close every user Version whose last Step is older than the idle window
+ * (PRD v3.3 D21).
+ *
+ * The write path already forks a session when the *next* write arrives after a
+ * pause, but nothing settled a session that was simply abandoned — leaving the
+ * tab open, or closing it, left the Version `open` forever, so "停手 10 分钟"
+ * never actually produced a saved Version. Settling is evaluated lazily when
+ * the version list is read, which is the moment a user can observe the outcome.
+ *
+ * Idempotent: a second call finds nothing open past the window and writes
+ * nothing.
+ */
+export declare function settleIdleUserVersions(workbookId: string, nowMs?: number): Promise<number>;
+/** Finalize exactly one open Version, leaving other Versions untouched. */
+export declare function finalizeVersion(meta: WorkbookMeta, versionId: string): void;

package/lib/types/version/session.js

@@ -0,0 +1,89 @@
+/**
+ * The editing session: when a Version opens, what closes it, and the shape of
+ * the version fields on the wire (docs/issue/0022 P2).
+ *
+ * Two boundaries close a session (PRD v3.5 D21) — the idle window and the Step
+ * cap — and nothing else does. `settleIdleUserVersions` exists because the write
+ * path can only fork a session when the *next* write arrives: an abandoned tab
+ * left a Version `open` forever, so settling is evaluated lazily at the moment
+ * the user can observe the outcome (reading the version list).
+ */
+import { VERSION_MAX_STEPS } from '#contracts';
+import { cloneSnapshot } from "../contract/snapshots.js";
+import { isIdlePast } from "../store/retention.js";
+import { readWorkbook } from "../store/read.js";
+import { writeWorkbook } from "../store/write.js";
+// Safety cap only: idle and semantic boundaries are the primary Version
+// boundary now (PRD §4.1). Shared through data-contracts.
+export const VERSION_STEP_LIMIT = VERSION_MAX_STEPS;
+/** Old logs use `temporary`; expose it as the clearer `open` lifecycle state. */
+export function normalizeVersionStatus(status) {
+    return status === 'temporary' ? 'open' : status;
+}
+/** v3 tier on the wire; unknown values are dropped rather than guessed. */
+export function normalizeVersionKind(kind) {
+    return kind === 'named' || kind === 'auto' ? kind : undefined;
+}
+export function isOpenVersionStatus(status) {
+    return status === 'open' || status === 'temporary';
+}
+export function optionalVersionText(value, name, maxLength) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > maxLength)
+        throw new Error(`${name} 必须是 1 到 ${maxLength} 字符的字符串`);
+    return normalized;
+}
+export function finalizeOpenUserVersions(meta) {
+    const openVersionIds = new Set((meta.operations ?? [])
+        .filter(operation => operation.actor === 'user' && isOpenVersionStatus(operation.versionStatus) && operation.versionId !== undefined)
+        .map(operation => operation.versionId));
+    if (openVersionIds.size === 0)
+        return;
+    meta.operations = (meta.operations ?? []).map(operation => openVersionIds.has(operation.versionId ?? '')
+        ? { ...operation, versionStatus: 'final' }
+        : operation);
+}
+/**
+ * Close every user Version whose last Step is older than the idle window
+ * (PRD v3.3 D21).
+ *
+ * The write path already forks a session when the *next* write arrives after a
+ * pause, but nothing settled a session that was simply abandoned — leaving the
+ * tab open, or closing it, left the Version `open` forever, so "停手 10 分钟"
+ * never actually produced a saved Version. Settling is evaluated lazily when
+ * the version list is read, which is the moment a user can observe the outcome.
+ *
+ * Idempotent: a second call finds nothing open past the window and writes
+ * nothing.
+ */
+export async function settleIdleUserVersions(workbookId, nowMs = Date.now()) {
+    const meta = await readWorkbook(workbookId);
+    if (meta === null)
+        return 0;
+    const open = (meta.operations ?? []).filter(operation => operation.actor === 'user' && isOpenVersionStatus(operation.versionStatus));
+    if (open.length === 0)
+        return 0;
+    const lastAt = new Map();
+    for (const operation of open) {
+        const id = operation.versionId ?? `revision:${operation.revision}`;
+        const previous = lastAt.get(id);
+        if (previous === undefined || operation.timestamp > previous)
+            lastAt.set(id, operation.timestamp);
+    }
+    const idle = [...lastAt.entries()].filter(([, timestamp]) => isIdlePast(timestamp, nowMs)).map(([id]) => id);
+    if (idle.length === 0)
+        return 0;
+    const next = cloneSnapshot(meta);
+    for (const id of idle)
+        finalizeVersion(next, id);
+    await writeWorkbook(next, { persistSnapshot: false, persistCheckpoints: false });
+    return idle.length;
+}
+/** Finalize exactly one open Version, leaving other Versions untouched. */
+export function finalizeVersion(meta, versionId) {
+    meta.operations = (meta.operations ?? []).map(operation => operation.versionId === versionId && isOpenVersionStatus(operation.versionStatus)
+        ? { ...operation, versionStatus: 'final' }
+        : operation);
+}

package/lib/types/version/summary.d.ts

@@ -0,0 +1,24 @@
+import type { WorkbookOperation } from '../types.ts';
+/**
+ * Describe a whole-snapshot save by what it actually changed (PRD v3.1 §7).
+ * The browser persists most edits this way, and 「替换 workbook 快照」 told the
+ * user nothing; the diff is already computed for Version comparison, so a Step
+ * can say `修改 1 个单元格：Sheet1!C3` — an address the user can paste straight
+ * into the formula bar, unlike the former `Sheet1!R3C2`.
+ */
+export declare function describeSnapshotReplace(before: unknown, after: unknown): string;
+/**
+ * Describe an editing session that was never given a name (PRD v3.3 D21, D22).
+ *
+ * It used to read `编辑会话 · 5 个 Step`, which stated the same count twice: the
+ * row's meta line immediately above it already says `用户 · 5 个 Step`, and the
+ * two lines are read together. A session has no single operation to quote, and
+ * diffing its two ends would mean two snapshot reads plus a diff per Version on
+ * every list request — but the *kinds* of its Steps are already in hand, and
+ * 「改了什么」 is the question the summary line is there to answer; the size of
+ * the session is what the meta line is for.
+ *
+ * An unknown Step type is counted rather than dropped: a summary that silently
+ * omits a kind of change is worse than one that admits it does not know it.
+ */
+export declare function describeSessionSteps(steps: readonly WorkbookOperation[]): string;

package/lib/types/version/summary.js

@@ -0,0 +1,111 @@
+/**
+ * How a Version and its Steps are described in words (docs/issue/0022 P2).
+ *
+ * This is the copy the user reads in the version list, so it is deliberately a
+ * module of its own: PRD 0002 changed it four times, and each of those changes
+ * is a change to *one* file rather than to the repository layer.
+ *
+ * A one-line summary of an *operation* (before it is diffed) lives in
+ * `contract/operations.ts` instead — `store/write.ts` embeds it in the sidecar
+ * index, and a store module may not import upward into `version/`.
+ */
+import { cellAddress, formatCellReference } from '#contracts';
+import { DIFF_CHANGE_LIMIT, diffReachedLimit, diffWorkbookSnapshots } from "./diff.js";
+/**
+ * Describe a whole-snapshot save by what it actually changed (PRD v3.1 §7).
+ * The browser persists most edits this way, and 「替换 workbook 快照」 told the
+ * user nothing; the diff is already computed for Version comparison, so a Step
+ * can say `修改 1 个单元格：Sheet1!C3` — an address the user can paste straight
+ * into the formula bar, unlike the former `Sheet1!R3C2`.
+ */
+export function describeSnapshotReplace(before, after) {
+    const changes = diffWorkbookSnapshots(before, after);
+    if (changes.length === 0)
+        return '保存内容（无变化）';
+    // Content edits are 修改; everything else is 样式. Splitting them is what
+    // makes the sentence true: a cell that only had its formatting touched is not
+    // a modification of anything the reader can see in the grid.
+    const cells = changes.filter(change => change.kind === 'cell' && change.styleOnly !== true);
+    const styled = changes.filter(change => change.kind !== 'cell' || change.styleOnly === true);
+    const sheetOf = (change) => change.sheetName ?? change.sheetId ?? 'sheet';
+    // One sheet is named once: `发版日志!B27、B28、B29` reads like a spreadsheet
+    // selection, while `发版日志!B27、发版日志!B28` repeats the same word per cell.
+    const head = changes.slice(0, 3);
+    const sheets = new Set(head.map(change => (change.kind === 'cell' ? sheetOf(change) : '')));
+    const labels = head.map(change => change.kind === 'cell'
+        ? (sheets.size === 1
+            ? cellAddress(change.row ?? 0, change.column ?? 0)
+            : formatCellReference({ sheet: sheetOf(change), row: change.row ?? 0, column: change.column ?? 0 }))
+        : (change.description === undefined ? sheetOf(change) : `${sheetOf(change)}·${change.description}`));
+    const scope = sheets.size === 1 && [...sheets][0] !== '' ? `${[...sheets][0]}!` : '';
+    // Three structural changes in one sheet used to print `Sheet1、Sheet1、Sheet1`.
+    const distinct = [...new Set(labels)];
+    // A sheet being merged or frozen — or a cell that only had its formatting
+    // touched — is not a 修改 of anything: nothing about the *content* changed.
+    // The old headline said `修改 4 处结构变化`, which read as though the count
+    // were the verb's object, and it once reported `修改 496 个单元格` when 473 of
+    // those were styled-but-empty cells. Each bucket now carries its own verb.
+    // 结构 / 改变 → 样式 is the user's wording (GUI feedback 2026-09-19): it is
+    // the word they read cell-formatting adjustments as, and it covers the
+    // sheet-level ones too.
+    // `capped` is not the same as `truncated` below: that one is about the *sample*
+    // list being cut short, this one about the counts themselves being a floor.
+    const capped = diffReachedLimit(changes);
+    const headline = [
+        cells.length > 0 ? `修改 ${cells.length}${capped ? '+' : ''} 个单元格` : '',
+        styled.length > 0 ? `样式 ${styled.length}${capped ? '+' : ''} 处` : '',
+    ].filter(part => part !== '').join('、');
+    const truncated = changes.length > 3 || distinct.length < labels.length;
+    const limitNote = capped ? `（差异已达 ${DIFF_CHANGE_LIMIT} 条上限，计数为下限）` : '';
+    return `${headline}：${scope}${distinct.join('、')}${truncated ? ' 等' : ''}${limitNote}`;
+}
+/** One Step's kind → the bucket a session summary counts it in. */
+const SESSION_STEP_BUCKET = {
+    update_cells: '修改单元格',
+    append_rows: '追加行',
+    set_hyperlink: '设置超链接',
+    remove_hyperlink: '移除超链接',
+    snapshot_replace: '保存内容',
+    create_sheet: '新增 sheet',
+    delete_sheet: '删除 sheet',
+    rename_sheet: '重命名 sheet',
+};
+/**
+ * Fixed bucket order: what was edited first, then what the workbook is made of,
+ * then the presentation of a sheet. Map insertion order would have made the
+ * same session read differently depending on which Step happened to come first.
+ */
+const SESSION_BUCKET_ORDER = [
+    '修改单元格', '追加行', '设置超链接', '移除超链接', '保存内容',
+    '新增 sheet', '删除 sheet', '重命名 sheet',
+];
+/**
+ * Describe an editing session that was never given a name (PRD v3.3 D21, D22).
+ *
+ * It used to read `编辑会话 · 5 个 Step`, which stated the same count twice: the
+ * row's meta line immediately above it already says `用户 · 5 个 Step`, and the
+ * two lines are read together. A session has no single operation to quote, and
+ * diffing its two ends would mean two snapshot reads plus a diff per Version on
+ * every list request — but the *kinds* of its Steps are already in hand, and
+ * 「改了什么」 is the question the summary line is there to answer; the size of
+ * the session is what the meta line is for.
+ *
+ * An unknown Step type is counted rather than dropped: a summary that silently
+ * omits a kind of change is worse than one that admits it does not know it.
+ */
+export function describeSessionSteps(steps) {
+    const counts = new Map();
+    for (const step of steps) {
+        const bucket = SESSION_STEP_BUCKET[step.type] ?? '其他改动';
+        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+    }
+    const buckets = [...counts.keys()].sort((left, right) => bucketRank(left) - bucketRank(right));
+    if (buckets.length === 0)
+        return '编辑会话';
+    return `编辑会话：${buckets.map(bucket => `${bucket} ${counts.get(bucket) ?? 0} 次`).join('、')}`;
+}
+/** Position in {@link SESSION_BUCKET_ORDER}; anything unlisted sorts last. */
+function bucketRank(bucket) {
+    const at = SESSION_BUCKET_ORDER.indexOf(bucket);
+    return at === -1 ? SESSION_BUCKET_ORDER.length : at;
+}

package/lib/types/workbook-manager.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Node-side workbook repository for dsh-data-table.
+ *
+ * One named workbook = one Univer snapshot JSON file under the DSH home
+ * storage root (`<dshHome>/storages/data-table/<id>.json`; the pre-rename
+ * `storages/data-sheet` root is migrated once on first access). The agent tools
+ * address workbooks by id across sessions; the browser mounts a residency
+ * instance from the current snapshot and saves back in Version-sized batches.
+ * @module dsh-data-table/workbook-manager
+ */
+import { type WorkbookMeta, type WorkbookOperation, type WorkbookOperationPayload, type WorkbookOperationType, type WorkbookVersionStatus, type WorkbookChange, type WorkbookProposal, type WorkbookWorktree } from './types.ts';
+import { type ConflictEntry, type ConflictPayload, type VersionKind } from '#contracts';
+import type { LineageContext } from '#contracts';
+export { workbookRoot, legacyWorkbookRoot, WorkbookStorageMigration, migrateLegacyWorkbookStorage, workbookPath, workbookIndexPath } from './store/paths.ts';
+export { WorkbookIndex, WorkbookIndexOperation, WorkbookIndexProposal, readWorkbookIndex, readWorkbook, readWorkbookAtRevision, workbookExists, listWorkbooks, listWorkbookSummaries, listWorkbookWorktrees, readWorkbookWorktree, summarize } from './store/read.ts';
+export { writeWorkbook, deleteWorkbook, renameWorkbook } from './store/write.ts';
+export { newWorktreeId, normalizeWorkbookId, normalizeWorktreeId } from './contract/ids.ts';
+export { workbookOperationSteps } from './contract/operations.ts';
+export { findDuplicateRows, readWorkbookRange } from './contract/snapshots.ts';
+export { applyWorkbookOperation } from './contract/mutations.ts';
+export { describeSnapshotReplace } from './version/summary.ts';
+export { settleIdleUserVersions } from './version/session.ts';
+export { diffWorkbookSnapshots, type WorkbookDiffScope } from './version/diff.ts';
+/** Expand a persisted operation into the ordered steps represented by one
+ * version. A normal operation is one step; a batch keeps each child visible
+ * for history and replay without introducing a second persistence model. */
+/** Create a worktree from the current trunk snapshot without mutating trunk. */
+export declare function createWorkbookWorktree(args: {
+    workbookId: string;
+    ownerSessionId: string;
+    name?: string;
+    worktreeId?: string;
+}): Promise<WorkbookWorktree>;
+/** Apply an operation inside a worktree; trunk remains unchanged. */
+export declare function mutateWorkbookWorktree(args: {
+    workbookId: string;
+    worktreeId: string;
+    ownerSessionId: string;
+    actor: 'agent' | 'user';
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+    expectedRevision?: number;
+    opId?: string;
+    lineage?: LineageContext;
+}): Promise<{
+    worktree: WorkbookWorktree;
+    operation: WorkbookOperation;
+}>;
+/** Move a worktree between review states without changing trunk data. */
+export declare function setWorkbookWorktreeStatus(args: {
+    workbookId: string;
+    worktreeId: string;
+    ownerSessionId: string;
+    status: 'ready' | 'reopen' | 'discarded';
+}): Promise<WorkbookWorktree>;
+/** Merge a ready worktree into trunk as one atomic snapshot replacement. */
+export declare function mergeWorkbookWorktree(args: {
+    workbookId: string;
+    worktreeId: string;
+    ownerSessionId: string;
+    actor?: 'agent' | 'user';
+    expectedRevision?: number;
+}): Promise<{
+    worktree: WorkbookWorktree;
+    mutation: WorkbookMutationResult;
+}>;
+/** Create an empty workbook snapshot (one blank default sheet). */
+export declare function blankSnapshot(name: string): unknown;
+/** A failed optimistic-concurrency check, surfaced as a model-facing error. */
+export declare class WorkbookRevisionConflictError extends Error {
+    readonly expected: number;
+    readonly actual: number;
+    readonly conflictSet: ConflictEntry[];
+    readonly workbookId: string;
+    /** Unified cross-plugin 409 body (PRD §5.1). */
+    readonly payload: ConflictPayload;
+    constructor(expected: number, actual: number, message?: string, conflictSet?: ConflictEntry[], workbookId?: string);
+}
+export interface WorkbookMutationResult {
+    meta: WorkbookMeta;
+    operation: WorkbookOperation;
+    /** Operations observed after the caller's base revision when it was rebased. */
+    rebasedOperations?: WorkbookOperation[];
+    /** True when the server accepted a safe concurrent cell edit. */
+    transformed?: boolean;
+}
+export interface WorkbookMutationPlanStep {
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+    opId?: string;
+    versionId?: string;
+    versionSummary?: string;
+    versionKind?: VersionKind;
+    versionIntent?: string;
+    agentRunId?: string;
+    lineage?: LineageContext;
+}
+export interface WorkbookMutationPlanResult {
+    meta: WorkbookMeta;
+    operations: WorkbookOperation[];
+    /** True when every step was already committed and the request was replayed. */
+    replayed?: boolean;
+    /** True when the plan was validated in memory only and nothing was persisted. */
+    dryRun?: boolean;
+    /** Operations observed after the caller's base revision when the plan was rebased. */
+    rebasedOperations?: WorkbookOperation[];
+    /** True when the plan was accepted on top of a newer revision instead of 409ing. */
+    transformed?: boolean;
+}
+export interface WorkbookProposalResult {
+    meta: WorkbookMeta;
+    proposal: WorkbookProposal;
+}
+export declare function mutateWorkbook(args: {
+    workbookId: string;
+    actor: 'agent' | 'user';
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+    expectedRevision?: number;
+    opId?: string;
+    createIfMissing?: boolean;
+    /** Join an existing open logical Version (browser user saves). */
+    versionId?: string;
+    versionStatus?: WorkbookVersionStatus;
+    /** Host-owned audit metadata for a semantic Agent Version. */
+    versionSummary?: string;
+    /** v3 tier; omitted by browser user edits, which are auto checkpoints. */
+    versionKind?: VersionKind;
+    versionIntent?: string;
+    agentRunId?: string;
+    lineage?: LineageContext;
+}): Promise<WorkbookMutationResult>;
+export declare function mutateWorkbookPlan(args: {
+    workbookId: string;
+    actor: 'agent';
+    steps: WorkbookMutationPlanStep[];
+    expectedRevision?: number;
+    dryRun?: boolean;
+}): Promise<WorkbookMutationPlanResult>;
+/** Build and persist a durable proposal without changing the workbook revision. */
+export declare function previewWorkbookChanges(args: {
+    workbookId: string;
+    actor: 'agent' | 'user';
+    operations: Array<{
+        type: WorkbookOperationType;
+        payload: WorkbookOperationPayload;
+    }>;
+    expectedRevision?: number;
+    proposalId?: string;
+    summary?: string;
+}): Promise<WorkbookProposalResult>;
+/** Commit a proposal atomically after checking the revision it was previewed on. */
+export declare function commitWorkbookProposal(args: {
+    workbookId: string;
+    proposalId: string;
+    actor: 'agent' | 'user';
+    expectedRevision?: number;
+}): Promise<WorkbookMutationResult>;
+/** Reject a pending proposal without changing workbook data or revision. */
+export declare function rejectWorkbookProposal(workbookId: string, proposalId: string): Promise<WorkbookMeta>;
+/** Restore any replayable previous version as a new revision. */
+export declare function rollbackWorkbook(args: {
+    workbookId: string;
+    targetRevision: number;
+    expectedRevision?: number;
+    actor?: 'agent' | 'user';
+    opId?: string;
+    /** User-facing summary for the restored Version, e.g. `恢复到 V3`. */
+    summary?: string;
+    lineage?: LineageContext;
+}): Promise<WorkbookMutationResult>;
+/**
+ * What one Step changed: the diff between the state before it and the state
+ * after it (PRD v3.3 §7.2).
+ *
+ * Step replay used to hand the browser a snapshot and nothing else, so the
+ * viewport stayed wherever the previous state happened to leave it and the user
+ * had to hunt for the cell that moved. This answers "which cells, and where" in
+ * the same request as the snapshot, so the canvas can scroll to and tint them.
+ */
+export declare function readStepChanges(workbookId: string, targetRevision: number, stepIndex: number): Promise<WorkbookChange[] | null>;
+/** Reconstruct the state after one step inside a Version. This starts from
+ * the revision before the Version's first physical operation, then applies
+ * only the requested ordered children so the UI can replay it step by step. */
+export declare function readWorkbookAtStep(workbookId: string, targetRevision: number, stepIndex: number): Promise<{
+    snapshot: unknown;
+    revision: number;
+    step: number;
+    stepCount: number;
+    baseRevision?: number;
+} | null>;