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

package/lib/types/workbook-manager.js

@@ -0,0 +1,935 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+import { conflictPayload } from '#contracts';
+import { DataSheetError } from "./errors.js";
+import { publishWorkbookCollaboration } from "./collaboration-hub.js";
+import { newWorktreeId, nextContinuationVersionId, normalizeWorkbookId, normalizeWorktreeId } from "./contract/ids.js";
+import { operationSummary, workbookOperationSteps } from "./contract/operations.js";
+import { workbookCheckpointsPath, } from "./store/paths.js";
+import { readWorkbook, readWorkbookAtRevision, readWorkbookWorktree, readJsonFile, isStoredCheckpoint, } from "./store/read.js";
+import { withWorkbookQueue, withWorktreeQueue, writeWorkbook, writeWorktree, } from "./store/write.js";
+import { pruneAutoVersionOperations, isIdlePast, CHECKPOINT_INTERVAL, } from "./store/retention.js";
+// Re-exported façade (docs/issue/0022 §4): the store is now the home of this
+// vocabulary; callers move to `store/` as their own phase lands.
+export { workbookRoot, legacyWorkbookRoot, migrateLegacyWorkbookStorage, workbookPath, workbookIndexPath } from "./store/paths.js";
+export { readWorkbookIndex, readWorkbook, readWorkbookAtRevision, workbookExists, listWorkbooks, listWorkbookSummaries, listWorkbookWorktrees, readWorkbookWorktree, summarize } from "./store/read.js";
+export { writeWorkbook, deleteWorkbook, renameWorkbook } from "./store/write.js";
+import { applyWorkbookOperation, resolveOperationPayload, validateSnapshotBounds } from "./contract/mutations.js";
+import { DIFF_CHANGE_LIMIT, collectDiffScopes, diffWorkbookSnapshots } from "./version/diff.js";
+import { describeSnapshotReplace } from "./version/summary.js";
+import { finalizeOpenUserVersions, finalizeVersion, isOpenVersionStatus, normalizeVersionKind, normalizeVersionStatus, optionalVersionText, VERSION_STEP_LIMIT, } from "./version/session.js";
+import { DEFAULT_SHEET_FONT_FAMILY, asWorkbookSnapshot, cloneSnapshot, DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, stableJson, } from "./contract/snapshots.js";
+// Re-exported façade (docs/issue/0022 §4): callers move to `contract/` as their own
+// phase lands, so this module can be split without touching them.
+export { newWorktreeId, normalizeWorkbookId, normalizeWorktreeId } from "./contract/ids.js";
+export { workbookOperationSteps } from "./contract/operations.js";
+export { findDuplicateRows, readWorkbookRange } from "./contract/snapshots.js";
+export { applyWorkbookOperation } from "./contract/mutations.js";
+// Re-exported façade (docs/issue/0022 §4): the version vocabulary now lives in
+// `version/`; callers move there as their own phase lands.
+export { describeSnapshotReplace } from "./version/summary.js";
+export { settleIdleUserVersions } from "./version/session.js";
+export { diffWorkbookSnapshots } from "./version/diff.js";
+/** 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 async function createWorkbookWorktree(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    const ownerSessionId = normalizeSessionId(args.ownerSessionId);
+    if (ownerSessionId === null)
+        throw new DataSheetError('VALIDATION_ERROR', 'ownerSessionId 必须是非空字符串');
+    return withWorktreeQueue(workbookId, args.worktreeId ?? 'new', async () => {
+        const meta = await readWorkbook(workbookId);
+        if (meta === null)
+            throw new DataSheetError('WORKBOOK_NOT_FOUND', `工作簿不存在：${workbookId}`, 404);
+        const id = normalizeWorktreeId(args.worktreeId ?? newWorktreeId());
+        const existing = await readWorkbookWorktree(workbookId, id);
+        if (existing !== null)
+            throw new DataSheetError('VALIDATION_ERROR', `worktree 已存在：${id}`, 409);
+        const timestamp = new Date().toISOString();
+        const worktree = {
+            id,
+            workbookId,
+            ownerSessionId,
+            name: args.name?.trim() || `${meta.name} 草稿`,
+            baseRevision: meta.revision ?? 0,
+            revision: 0,
+            status: 'draft',
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            snapshot: cloneSnapshot(meta.snapshot),
+            operations: [],
+        };
+        await writeWorktree(worktree);
+        return worktree;
+    });
+}
+/** Apply an operation inside a worktree; trunk remains unchanged. */
+export async function mutateWorkbookWorktree(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorktreeQueue(workbookId, args.worktreeId, async () => {
+        const worktree = await readWorkbookWorktree(workbookId, args.worktreeId);
+        assertWorktreeOwner(worktree, args.ownerSessionId);
+        if (worktree.status !== 'draft')
+            throw new DataSheetError('WORKTREE_STATE_INVALID', `worktree 当前状态为 ${worktree.status}，不能修改`);
+        const revision = worktree.revision;
+        if (args.expectedRevision !== undefined && args.expectedRevision !== revision) {
+            throw new WorkbookRevisionConflictError(args.expectedRevision, revision, undefined, [], workbookId);
+        }
+        const operation = {
+            opId: args.opId ?? `worktree:${worktree.id}:${randomUUID()}`,
+            workbookId,
+            revision: revision + 1,
+            parentRevision: revision,
+            baseRevision: args.expectedRevision ?? revision,
+            actor: args.actor,
+            type: args.type,
+            timestamp: new Date().toISOString(),
+            lineage: args.lineage,
+            payload: resolveOperationPayload(worktree.snapshot, args.type, args.payload),
+        };
+        worktree.snapshot = applyWorkbookOperation(worktree.snapshot, operation);
+        worktree.revision = operation.revision;
+        worktree.updatedAt = operation.timestamp;
+        worktree.operations = [...worktree.operations, operation].slice(-200);
+        await writeWorktree(worktree);
+        return { worktree, operation };
+    });
+}
+/** Move a worktree between review states without changing trunk data. */
+export async function setWorkbookWorktreeStatus(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorktreeQueue(workbookId, args.worktreeId, async () => {
+        const worktree = await readWorkbookWorktree(workbookId, args.worktreeId);
+        assertWorktreeOwner(worktree, args.ownerSessionId);
+        const nextStatus = args.status === 'reopen' ? 'draft' : args.status;
+        if (worktree.status === 'merged' || worktree.status === 'discarded')
+            throw new DataSheetError('WORKTREE_STATE_INVALID', `worktree 当前状态为 ${worktree.status}，不能再次操作`);
+        if (nextStatus === 'ready' && worktree.status !== 'draft')
+            throw new DataSheetError('WORKTREE_STATE_INVALID', `worktree 当前状态为 ${worktree.status}，不能进入 ready`);
+        if (nextStatus === 'ready' && worktree.revision === 0)
+            throw new DataSheetError('WORKTREE_STATE_INVALID', '空 worktree 不能进入 ready 状态');
+        if (nextStatus === 'draft' && worktree.status !== 'ready')
+            throw new DataSheetError('WORKTREE_STATE_INVALID', `worktree 当前状态为 ${worktree.status}，不能重新打开`);
+        worktree.status = nextStatus;
+        worktree.updatedAt = new Date().toISOString();
+        await writeWorktree(worktree);
+        return worktree;
+    });
+}
+/** Merge a ready worktree into trunk as one atomic snapshot replacement. */
+export async function mergeWorkbookWorktree(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorktreeQueue(workbookId, args.worktreeId, async () => {
+        const worktree = await readWorkbookWorktree(workbookId, args.worktreeId);
+        assertWorktreeOwner(worktree, args.ownerSessionId);
+        if (worktree.status !== 'ready')
+            throw new DataSheetError('WORKTREE_STATE_INVALID', `worktree 当前状态为 ${worktree.status}，只有 ready 可以合并`);
+        const mutation = await mutateWorkbook({
+            workbookId,
+            actor: args.actor ?? 'user',
+            type: 'snapshot_replace',
+            payload: { snapshot: worktree.snapshot },
+            expectedRevision: args.expectedRevision ?? worktree.baseRevision,
+            opId: `worktree-merge:${worktree.id}:${worktree.revision}`,
+        });
+        const latest = await readWorkbookWorktree(workbookId, worktree.id);
+        assertWorktreeOwner(latest, args.ownerSessionId);
+        latest.status = 'merged';
+        latest.updatedAt = new Date().toISOString();
+        await writeWorktree(latest);
+        return { worktree: latest, mutation };
+    });
+}
+function normalizeSessionId(value) {
+    const id = value.trim();
+    return id.length > 0 && id.length <= 256 ? id : null;
+}
+function assertWorktreeOwner(worktree, ownerSessionId) {
+    if (worktree === null)
+        throw new DataSheetError('WORKTREE_NOT_FOUND', 'worktree 不存在', 404);
+    if (normalizeSessionId(ownerSessionId) !== worktree.ownerSessionId) {
+        throw new DataSheetError('SESSION_SCOPE_DENIED', '当前 session 无权访问该 worktree', 403);
+    }
+}
+/** Create an empty workbook snapshot (one blank default sheet). */
+export function blankSnapshot(name) {
+    return {
+        id: 'default',
+        name,
+        sheetOrder: ['sheet1'],
+        sheets: {
+            sheet1: {
+                id: 'sheet1',
+                name: 'sheet1',
+                rowCount: DEFAULT_SHEET_ROWS,
+                columnCount: DEFAULT_SHEET_COLUMNS,
+                defaultStyle: { ff: DEFAULT_SHEET_FONT_FAMILY },
+                cellData: {},
+            },
+        },
+    };
+}
+/** A failed optimistic-concurrency check, surfaced as a model-facing error. */
+export class WorkbookRevisionConflictError extends Error {
+    expected;
+    actual;
+    conflictSet;
+    workbookId;
+    /** Unified cross-plugin 409 body (PRD §5.1). */
+    payload;
+    constructor(expected, actual, message, conflictSet = [], workbookId = '') {
+        const text = message ?? `工作簿版本已变化：请求基于 revision ${expected}，当前是 ${actual}；请先重新读取工作簿`;
+        super(text);
+        this.expected = expected;
+        this.actual = actual;
+        this.conflictSet = conflictSet;
+        this.workbookId = workbookId;
+        this.name = 'WorkbookRevisionConflictError';
+        this.payload = conflictPayload({
+            artifactKind: 'workbook',
+            artifactId: workbookId,
+            baseRevision: expected,
+            currentRevision: actual,
+            conflictSet,
+            message: text,
+            nextAction: '重新读取工作簿后重试；需要保留本地修改时先查看差异或提交合并提案',
+        });
+    }
+}
+/** Describe the operations a caller missed as conflict-set entries. */
+function conflictingOperations(operations) {
+    return operations.slice(-20).map(operation => ({
+        kind: 'content',
+        target: `r${operation.revision}`,
+        description: operationSummary(operation),
+        remote: operation.type,
+    }));
+}
+/** Apply and persist one operation, incrementing the workbook revision. */
+/**
+ * Fingerprint of one mutation request. The single-operation path and the plan
+ * path both compare it, so reusing an `opId` with different content is rejected
+ * instead of silently replaying the earlier write.
+ */
+function requestFingerprint(fields) {
+    return stableJson({
+        actor: fields.actor,
+        type: fields.type,
+        payload: fields.payload,
+        // Keep these two base fields present even when undefined so request hashes
+        // stay compatible with operation logs written before semantic Version
+        // metadata existed.
+        versionId: fields.versionId,
+        versionStatus: fields.versionStatus,
+        ...(fields.versionSummary === undefined ? {} : { versionSummary: fields.versionSummary }),
+        // Added in v3; omitted when absent so pre-v3 retries keep their hash.
+        ...(fields.versionKind === undefined ? {} : { versionKind: fields.versionKind }),
+        ...(fields.versionIntent === undefined ? {} : { versionIntent: fields.versionIntent }),
+        ...(fields.agentRunId === undefined ? {} : { agentRunId: fields.agentRunId }),
+        ...(fields.lineage === undefined ? {} : { lineage: fields.lineage }),
+    });
+}
+/** Fingerprint of an already committed operation, including logs written before
+ * `requestHash` was persisted. */
+function storedRequestFingerprint(operation) {
+    return operation.requestHash ?? requestFingerprint({
+        actor: operation.actor,
+        type: operation.type,
+        payload: operation.payload,
+        versionId: operation.versionId,
+        versionStatus: operation.versionStatus,
+        versionSummary: operation.versionSummary,
+        versionKind: operation.versionKind,
+        versionIntent: operation.versionIntent,
+        agentRunId: operation.agentRunId,
+        lineage: operation.lineage,
+    });
+}
+export async function mutateWorkbook(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorkbookQueue(workbookId, async () => {
+        let meta = await readWorkbook(args.workbookId);
+        if (meta === null) {
+            if (!args.createIfMissing)
+                throw new Error(`工作簿不存在：${args.workbookId}`);
+            meta = {
+                id: workbookId,
+                name: workbookId,
+                sheetOrder: ['sheet1'],
+                updatedAt: new Date().toISOString(),
+                revision: 0,
+                operations: [],
+                snapshot: blankSnapshot(workbookId),
+            };
+        }
+        // Never mutate the cache object before all files are durably committed.
+        meta = cloneSnapshot(meta);
+        const revision = meta.revision ?? 0;
+        validateOpId(args.opId);
+        const versionId = args.versionId === undefined ? undefined : args.versionId.trim();
+        if (versionId !== undefined && versionId.length === 0)
+            throw new Error('versionId 必须是非空字符串');
+        if (versionId !== undefined && versionId.length > 240)
+            throw new Error('versionId 最多 240 个字符');
+        const versionSummary = optionalVersionText(args.versionSummary, 'versionSummary', 280);
+        const versionKind = normalizeVersionKind(args.versionKind);
+        const versionIntent = optionalVersionText(args.versionIntent, 'versionIntent', 1000);
+        const agentRunId = optionalVersionText(args.agentRunId, 'agentRunId', 160);
+        const lineage = args.lineage;
+        const requestedVersionStatus = normalizeVersionStatus(args.versionStatus);
+        const payload = resolveOperationPayload(meta.snapshot, args.type, args.payload);
+        const requestHash = requestFingerprint({
+            actor: args.actor,
+            type: args.type,
+            payload,
+            versionId,
+            versionStatus: args.versionStatus,
+            versionSummary,
+            versionKind,
+            versionIntent,
+            agentRunId,
+            lineage,
+        });
+        // Idempotency is checked before the revision gate. A retried request may
+        // legitimately carry an old base revision after its first attempt was
+        // committed but its response was lost.
+        const existing = args.opId === undefined
+            ? undefined
+            : meta.operations?.find(operation => operation.opId === args.opId);
+        if (existing !== undefined) {
+            const existingHash = storedRequestFingerprint(existing);
+            if (existingHash !== requestHash) {
+                throw new Error(`opId 已被其他请求使用：${args.opId}`);
+            }
+            return { meta, operation: existing };
+        }
+        expireStaleProposals(meta, revision);
+        // An open user Version stays open until it reaches ten steps. A
+        // later user save joins the same logical Version; an Agent write closes
+        // any open user Version first. A semantic Agent Version supplies its own
+        // Host-owned id and persists all of its child commands as one batch.
+        let logicalVersionId = versionId;
+        let logicalVersionStatus = requestedVersionStatus ?? 'final';
+        if (args.actor === 'agent') {
+            finalizeOpenUserVersions(meta);
+            logicalVersionStatus = 'final';
+        }
+        else if (args.type === 'snapshot_replace' && (requestedVersionStatus === 'final' || versionSummary !== undefined)) {
+            // A named save or an import is a deliberate, self-contained Version: it
+            // captures the whole workbook and closes whatever session was open.
+            finalizeOpenUserVersions(meta);
+            logicalVersionId = undefined;
+            logicalVersionStatus = 'final';
+        }
+        else if (args.actor === 'user') {
+            // Every other user save — including a whole-snapshot save, which is how
+            // the browser persists most edits — is one Step of the editing session
+            // (PRD v3.1 §4). It used to finalize the Version and start a new one on
+            // every save, which is what produced 220 Versions of 「替换 workbook 快照」.
+            if (logicalVersionId === undefined) {
+                const open = (meta.operations ?? [])
+                    .slice()
+                    .reverse()
+                    .find(operation => isOpenVersionStatus(operation.versionStatus) && operation.actor === 'user');
+                logicalVersionId = open?.versionId;
+            }
+            if (logicalVersionId === undefined) {
+                logicalVersionId = nextContinuationVersionId(workbookId, `session:${randomUUID()}`);
+            }
+            logicalVersionStatus = 'open';
+        }
+        if (args.actor === 'user' && logicalVersionId !== undefined) {
+            const sameVersion = (meta.operations ?? []).filter(operation => operation.versionId === logicalVersionId);
+            const latest = sameVersion.at(-1);
+            // A pause longer than the merge window closes the open Version, so a new
+            // burst of typing becomes its own user-visible version (PRD §4.1).
+            if (latest !== undefined && isOpenVersionStatus(latest.versionStatus) && isIdlePast(latest.timestamp)) {
+                finalizeVersion(meta, logicalVersionId);
+                logicalVersionId = nextContinuationVersionId(workbookId, logicalVersionId);
+            }
+            else if (latest !== undefined && !isOpenVersionStatus(latest.versionStatus)) {
+                // An Agent (or a full snapshot save) may have finalized the Version
+                // while this browser still had local steps in flight. Do not turn
+                // that benign race into a save failure; fork the unsent steps into a
+                // fresh logical Version and return its id so the client can continue
+                // joining it on the next save.
+                logicalVersionId = nextContinuationVersionId(workbookId, logicalVersionId);
+            }
+            const existingStepCount = logicalVersionId === versionId
+                ? sameVersion.reduce((total, operation) => total + workbookOperationSteps(operation).length, 0)
+                : 0;
+            const incomingStepCount = args.type === 'batch' ? Math.max(1, payload.operations?.length ?? 0) : 1;
+            if (existingStepCount + incomingStepCount > VERSION_STEP_LIMIT) {
+                throw new Error(`Version ${logicalVersionId} 最多 ${VERSION_STEP_LIMIT} 个 step，请拆分后再提交`);
+            }
+            logicalVersionStatus = existingStepCount + incomingStepCount >= VERSION_STEP_LIMIT ? 'final' : 'open';
+        }
+        let rebasedOperations;
+        let transformed = false;
+        if (args.expectedRevision !== undefined && args.expectedRevision !== revision) {
+            const intervening = operationsSinceRevision(meta.operations ?? [], args.expectedRevision, revision);
+            if (intervening === null || !canTransformCellEdit(args.type, args.payload, intervening)) {
+                throw new WorkbookRevisionConflictError(args.expectedRevision, revision, '工作簿存在无法自动转换的并发修改；请重新读取后重试或提交合并提案', conflictingOperations(intervening ?? operationsSinceRevision(meta.operations ?? [], args.expectedRevision, revision) ?? []), workbookId);
+            }
+            rebasedOperations = intervening;
+            transformed = true;
+        }
+        // Resolve the rows once at the mutation authority. The original row
+        // indexes are retained in the operation so every browser projection and
+        // replay removes exactly the same rows, even if duplicate values change
+        // later in the workbook.
+        const nextRevision = revision + 1;
+        const operation = {
+            opId: args.opId ?? randomUUID(),
+            workbookId,
+            revision: nextRevision,
+            parentRevision: revision,
+            baseRevision: args.expectedRevision ?? revision,
+            versionId: logicalVersionId,
+            versionStatus: logicalVersionStatus,
+            versionSummary,
+            versionKind,
+            versionIntent,
+            agentRunId,
+            lineage,
+            actor: args.actor,
+            type: args.type,
+            timestamp: new Date().toISOString(),
+            payload,
+            ...(args.type === 'snapshot_replace' && payload.snapshot !== undefined
+                ? { stepSummary: describeSnapshotReplace(meta.snapshot, payload.snapshot) }
+                : {}),
+            requestHash,
+        };
+        // `applyWorkbookOperation` mutates normal snapshots in place. Clone only
+        // at a checkpoint boundary, otherwise the old implementation stored the
+        // already-mutated object as the checkpoint and serialized it repeatedly.
+        const shouldCheckpoint = revision === 0 || nextRevision % CHECKPOINT_INTERVAL === 0 || operation.type === 'snapshot_replace';
+        if (shouldCheckpoint && (meta.checkpoints ?? []).length === 0) {
+            const stored = await readJsonFile(workbookCheckpointsPath(workbookId));
+            if (Array.isArray(stored?.checkpoints))
+                meta.checkpoints = stored.checkpoints.filter(checkpoint => isStoredCheckpoint(checkpoint));
+        }
+        const previousSnapshot = shouldCheckpoint ? cloneSnapshot(meta.snapshot) : null;
+        meta.snapshot = applyWorkbookOperation(meta.snapshot, operation);
+        // Keep the metadata index aligned with structural sheet operations. The
+        // snapshot is authoritative, but callers also read this lightweight list.
+        meta.sheetOrder = asWorkbookSnapshot(meta.snapshot).sheetOrder.slice();
+        meta.revision = nextRevision;
+        meta.updatedAt = operation.timestamp;
+        expireStaleProposals(meta, nextRevision);
+        // Keep the complete operation payload so every Version remains replayable.
+        // Snapshot replacements are less frequent but are still first-class steps
+        // in the simple version model.
+        const logOperation = operation;
+        meta.operations = [...(meta.operations ?? []), logOperation];
+        meta.checkpoints = compactCheckpoints(previousSnapshot === null
+            ? (meta.checkpoints ?? [])
+            : [...(meta.checkpoints ?? []), { revision, actor: args.actor, timestamp: operation.timestamp, snapshot: previousSnapshot }]);
+        pruneAutoVersionOperations(meta);
+        await writeWorkbook(meta, { persistSnapshot: shouldCheckpoint, persistCheckpoints: shouldCheckpoint });
+        publishWorkbookCollaboration(logOperation);
+        return { meta, operation: logOperation, rebasedOperations, transformed };
+    });
+}
+/**
+ * Commit a prepared Agent edit plan as one durable multi-file transaction.
+ *
+ * `workbook_edit` can contain several semantic Versions. The old implementation
+ * committed each Version independently, so a disk error or process exit could
+ * leave a partially applied request. This path applies all prepared Versions
+ * to one cloned metadata object and publishes them only after the single
+ * workbook transaction is durable.
+ *
+ * `dryRun` runs the exact same validation pipeline — opId checks, payload
+ * resolution, `applyWorkbookOperation` and revision accounting — and returns
+ * before the durable write. Sharing one path is what keeps a passing preview
+ * from failing on commit.
+ */
+/**
+ * Fingerprint of one plan step exactly as the caller submitted it. The payload
+ * is resolved the same way the commit path resolves it, so the comparison sees
+ * the bytes that were stored.
+ */
+function planStepFingerprint(meta, actor, step) {
+    return requestFingerprint({
+        actor,
+        type: step.type,
+        payload: resolveOperationPayload(meta.snapshot, step.type, step.payload),
+        versionId: step.versionId?.trim(),
+        versionStatus: 'final',
+        versionSummary: optionalVersionText(step.versionSummary, 'versionSummary', 280),
+        versionKind: normalizeVersionKind(step.versionKind),
+        versionIntent: optionalVersionText(step.versionIntent, 'versionIntent', 1000),
+        agentRunId: optionalVersionText(step.agentRunId, 'agentRunId', 160),
+        lineage: step.lineage,
+    });
+}
+export async function mutateWorkbookPlan(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorkbookQueue(workbookId, async () => {
+        if (args.steps.length === 0 || args.steps.length > 20)
+            throw new Error('mutation plan 必须是 1 到 20 个 Version');
+        const current = await readWorkbook(workbookId);
+        if (current === null)
+            throw new Error(`工作簿不存在：${args.workbookId}`);
+        const currentRevision = current.revision ?? 0;
+        // A retry after a lost response is valid only when the complete plan was
+        // committed. A partially present plan is intentionally rejected instead
+        // of guessing which steps may be safe to replay.
+        const requestedIds = args.steps.map(step => step.opId).filter((opId) => opId !== undefined);
+        const existingById = new Map((current.operations ?? []).filter(operation => requestedIds.includes(operation.opId)).map(operation => [operation.opId, operation]));
+        if (existingById.size > 0 && existingById.size !== requestedIds.length)
+            throw new Error('mutation plan 已部分提交；请先读取 workbook_history 再决定是否继续');
+        if (requestedIds.length === args.steps.length && existingById.size === requestedIds.length) {
+            // A replayed opId is only valid for the same request. Without this check
+            // a retry that changed its content would silently no-op and still report
+            // success — and a file import would even return a receipt describing a
+            // file that was never written.
+            for (const step of args.steps) {
+                const existing = existingById.get(step.opId);
+                if (storedRequestFingerprint(existing) !== planStepFingerprint(current, args.actor, step)) {
+                    throw new Error(`opId 已被其他请求使用：${step.opId}`);
+                }
+            }
+            return { meta: current, operations: args.steps.map(step => existingById.get(step.opId)), replayed: true };
+        }
+        // The plan path used to reject any revision drift outright, which made an
+        // Agent plan fail with a bare 409 whenever a browser save landed between
+        // `workbook_read` and `workbook_edit`. It now accepts the same narrow
+        // transform as the single-operation path: when the caller only missed cell
+        // writes and every step is itself a cell write, the declarative plan (which
+        // is still entirely unwritten) is applied on top of the current revision.
+        // Structural steps keep failing, because their coordinates cannot be
+        // transformed here.
+        let rebasedOperations;
+        let transformed = false;
+        if (args.expectedRevision !== undefined && args.expectedRevision !== currentRevision) {
+            const intervening = operationsSinceRevision(current.operations ?? [], args.expectedRevision, currentRevision);
+            if (intervening === null || !canTransformPlanCellEdits(args.steps, intervening)) {
+                throw new WorkbookRevisionConflictError(args.expectedRevision, currentRevision, '工作簿存在并发修改；请重新读取后重试整个编辑计划', conflictingOperations(intervening ?? operationsSinceRevision(current.operations ?? [], args.expectedRevision, currentRevision) ?? []), args.workbookId);
+            }
+            rebasedOperations = intervening;
+            transformed = true;
+        }
+        const meta = cloneSnapshot(current);
+        finalizeOpenUserVersions(meta);
+        let revision = currentRevision;
+        const committed = [];
+        for (const step of args.steps) {
+            validateOpId(step.opId);
+            const versionId = step.versionId?.trim();
+            if (versionId !== undefined && (versionId.length === 0 || versionId.length > 240))
+                throw new Error('versionId 必须是 1 到 240 个字符');
+            const versionSummary = optionalVersionText(step.versionSummary, 'versionSummary', 280);
+            const versionKind = normalizeVersionKind(step.versionKind);
+            const versionIntent = optionalVersionText(step.versionIntent, 'versionIntent', 1000);
+            const agentRunId = optionalVersionText(step.agentRunId, 'agentRunId', 160);
+            const lineage = step.lineage;
+            const payload = resolveOperationPayload(meta.snapshot, step.type, step.payload);
+            const requestHash = requestFingerprint({
+                actor: args.actor,
+                type: step.type,
+                payload,
+                versionId,
+                versionStatus: 'final',
+                versionSummary,
+                versionKind,
+                versionIntent,
+                agentRunId,
+                lineage,
+            });
+            const operation = {
+                opId: step.opId ?? randomUUID(),
+                workbookId,
+                revision: revision + 1,
+                parentRevision: revision,
+                baseRevision: revision,
+                versionId,
+                versionStatus: 'final',
+                versionSummary,
+                versionKind,
+                versionIntent,
+                agentRunId,
+                lineage,
+                actor: args.actor,
+                type: step.type,
+                timestamp: new Date().toISOString(),
+                payload,
+                requestHash,
+            };
+            const shouldCheckpoint = revision === 0 || operation.revision % CHECKPOINT_INTERVAL === 0 || operation.type === 'snapshot_replace';
+            const previousSnapshot = shouldCheckpoint ? cloneSnapshot(meta.snapshot) : null;
+            meta.snapshot = applyWorkbookOperation(meta.snapshot, operation);
+            revision = operation.revision;
+            meta.sheetOrder = asWorkbookSnapshot(meta.snapshot).sheetOrder.slice();
+            meta.revision = revision;
+            meta.updatedAt = operation.timestamp;
+            expireStaleProposals(meta, revision);
+            meta.operations = [...(meta.operations ?? []), operation];
+            meta.checkpoints = compactCheckpoints(previousSnapshot === null ? (meta.checkpoints ?? []) : [...(meta.checkpoints ?? []), { revision: revision - 1, actor: args.actor, timestamp: operation.timestamp, snapshot: previousSnapshot }]);
+            committed.push(operation);
+        }
+        if (args.dryRun === true)
+            return { meta, operations: committed, dryRun: true, ...(rebasedOperations === undefined ? {} : { rebasedOperations, transformed }) };
+        pruneAutoVersionOperations(meta);
+        await writeWorkbook(meta, { persistSnapshot: true, persistCheckpoints: true });
+        for (const operation of committed)
+            publishWorkbookCollaboration(operation);
+        return { meta, operations: committed, ...(rebasedOperations === undefined ? {} : { rebasedOperations, transformed }) };
+    });
+}
+/**
+ * Return the durable operation window needed to rebase a request. `null`
+ * means the tail has already been compacted, so accepting the request would
+ * be unsafe because the server can no longer prove what changed in between.
+ */
+function operationsSinceRevision(operations, baseRevision, currentRevision) {
+    if (baseRevision >= currentRevision)
+        return [];
+    const ordered = operations.filter(operation => operation.revision > baseRevision && operation.revision <= currentRevision).sort((left, right) => left.revision - right.revision);
+    if (ordered.length === 0 || ordered[0]?.revision !== baseRevision + 1 || ordered[ordered.length - 1]?.revision !== currentRevision)
+        return null;
+    for (let index = 1; index < ordered.length; index += 1) {
+        if (ordered[index]?.revision !== (ordered[index - 1]?.revision ?? 0) + 1)
+            return null;
+    }
+    return ordered;
+}
+/** Mark proposals based on an older revision as stale instead of leaving them
+ * visible forever and guaranteed to fail on commit. */
+function expireStaleProposals(meta, currentRevision) {
+    const timestamp = new Date().toISOString();
+    meta.proposals = (meta.proposals ?? []).map(proposal => proposal.status === 'pending' && proposal.baseRevision < currentRevision
+        ? { ...proposal, status: 'expired', updatedAt: timestamp }
+        : proposal);
+}
+/** Collect cell coordinates for the intentionally narrow safe transform. */
+function collectCellKeys(type, payload, target) {
+    if (type === 'update_cells') {
+        const sheetId = payload.sheetId ?? payload.sheetName;
+        if (sheetId === undefined)
+            return false;
+        for (const cell of payload.cells ?? [])
+            target.add(`${sheetId}:${cell.row}:${cell.column}`);
+        return (payload.cells ?? []).length > 0;
+    }
+    if (type === 'batch') {
+        const operations = payload.operations ?? [];
+        return operations.length > 0 && operations.every(operation => collectCellKeys(operation.type, operation.payload, target));
+    }
+    return false;
+}
+/**
+ * A small OT-like transform for cell writes. The Host is the single mutation
+ * authority and replays the accepted operation against the latest snapshot,
+ * so the revision order is the conflict rule: the later committed cell write
+ * wins, including when both writers touched the same coordinate. Structural
+ * edits, formatting and snapshot replacements remain strict conflicts because
+ * their coordinates or workbook shape cannot be safely transformed here.
+ */
+function canTransformCellEdit(type, payload, intervening) {
+    const incoming = new Set();
+    if (!collectCellKeys(type, payload, incoming))
+        return false;
+    for (const operation of intervening) {
+        const interveningCells = new Set();
+        if (!collectCellKeys(operation.type, operation.payload, interveningCells))
+            return false;
+    }
+    return true;
+}
+/**
+ * Plan-level counterpart of `canTransformCellEdit`: every step in the plan must
+ * be a pure cell write before the whole plan may ride on a newer revision. One
+ * structural or formatting step is enough to keep the strict conflict, because
+ * the surrounding row/column coordinates would have moved underneath it.
+ */
+function canTransformPlanCellEdits(steps, intervening) {
+    if (steps.length === 0)
+        return false;
+    return steps.every(step => canTransformCellEdit(step.type, step.payload, intervening));
+}
+/** Build and persist a durable proposal without changing the workbook revision. */
+export async function previewWorkbookChanges(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorkbookQueue(workbookId, async () => {
+        let meta = await readWorkbook(workbookId);
+        if (meta === null)
+            throw new Error(`工作簿不存在：${args.workbookId}`);
+        meta = cloneSnapshot(meta);
+        const baseRevision = meta.revision ?? 0;
+        expireStaleProposals(meta, baseRevision);
+        if (args.expectedRevision !== undefined && args.expectedRevision !== baseRevision) {
+            throw new WorkbookRevisionConflictError(args.expectedRevision, baseRevision, undefined, [], workbookId);
+        }
+        const proposalId = args.proposalId ?? randomUUID();
+        const existing = (meta.proposals ?? []).find(proposal => proposal.id === proposalId);
+        if (existing !== undefined)
+            return { meta, proposal: existing };
+        let nextSnapshot = cloneSnapshot(meta.snapshot);
+        for (const [index, operation] of args.operations.entries()) {
+            nextSnapshot = applyWorkbookOperation(nextSnapshot, {
+                opId: `${proposalId}:${index}`,
+                workbookId,
+                revision: baseRevision + 1,
+                actor: args.actor,
+                timestamp: new Date().toISOString(),
+                type: operation.type,
+                payload: operation.payload,
+            });
+        }
+        const changes = diffWorkbookSnapshots(meta.snapshot, nextSnapshot, collectDiffScopes(args.operations));
+        if (changes.length === 0)
+            throw new Error('提案没有产生任何变化');
+        validateSnapshotBounds(nextSnapshot);
+        const timestamp = new Date().toISOString();
+        const proposal = {
+            id: proposalId,
+            workbookId,
+            actor: args.actor,
+            baseRevision,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            status: 'pending',
+            summary: args.summary?.trim() || `待确认修改（${changes.length} 项）`,
+            changes: changes.slice(0, DIFF_CHANGE_LIMIT),
+            snapshot: nextSnapshot,
+        };
+        // Non-pending records are kept, not filtered away. This used to drop every
+        // proposal that was not `pending`, which deleted the very record
+        // `commitWorkbookProposal` needs to answer a retry after a lost response —
+        // so a retry answered `提案不存在` instead of returning the operation it had
+        // already committed. Trimming is the store's job.
+        meta.proposals = [...(meta.proposals ?? []), proposal];
+        await writeWorkbook(meta);
+        return { meta, proposal };
+    });
+}
+/** Commit a proposal atomically after checking the revision it was previewed on. */
+export async function commitWorkbookProposal(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorkbookQueue(workbookId, async () => {
+        let meta = await readWorkbook(workbookId, { includeCheckpoints: true });
+        if (meta === null)
+            throw new Error(`工作簿不存在：${args.workbookId}`);
+        meta = cloneSnapshot(meta);
+        const proposal = (meta.proposals ?? []).find(item => item.id === args.proposalId);
+        if (proposal === undefined)
+            throw new Error(`提案不存在：${args.proposalId}`);
+        if (proposal.status === 'committed') {
+            const existing = (meta.operations ?? []).find(item => item.opId === `proposal:${proposal.id}`);
+            if (existing !== undefined)
+                return { meta, operation: existing };
+        }
+        if (proposal.status !== 'pending')
+            throw new Error(`提案当前状态为 ${proposal.status}，不能提交`);
+        const revision = meta.revision ?? 0;
+        const expected = args.expectedRevision ?? proposal.baseRevision;
+        if (expected !== revision || proposal.baseRevision !== revision) {
+            throw new WorkbookRevisionConflictError(expected, revision, undefined, [], args.workbookId);
+        }
+        finalizeOpenUserVersions(meta);
+        const previousSnapshot = cloneSnapshot(meta.snapshot);
+        const timestamp = new Date().toISOString();
+        const operation = {
+            opId: `proposal:${proposal.id}`,
+            workbookId,
+            revision: revision + 1,
+            parentRevision: revision,
+            baseRevision: revision,
+            actor: args.actor,
+            type: 'snapshot_replace',
+            timestamp,
+            payload: { snapshot: proposal.snapshot },
+            requestHash: stableJson({ actor: args.actor, type: 'snapshot_replace', payload: { snapshot: proposal.snapshot } }),
+        };
+        meta.snapshot = applyWorkbookOperation(meta.snapshot, operation);
+        meta.sheetOrder = asWorkbookSnapshot(meta.snapshot).sheetOrder.slice();
+        meta.revision = operation.revision;
+        meta.updatedAt = timestamp;
+        expireStaleProposals(meta, operation.revision);
+        const logOperation = operation;
+        meta.operations = [...(meta.operations ?? []), logOperation];
+        meta.checkpoints = compactCheckpoints([...(meta.checkpoints ?? []), { revision, actor: args.actor, timestamp, snapshot: previousSnapshot }]);
+        meta.proposals = (meta.proposals ?? []).map(item => item.id === proposal.id
+            ? { ...item, status: 'committed', updatedAt: timestamp, committedRevision: operation.revision }
+            : item);
+        await writeWorkbook(meta, { persistSnapshot: true, persistCheckpoints: true });
+        publishWorkbookCollaboration(logOperation);
+        return { meta, operation: logOperation };
+    });
+}
+/** Reject a pending proposal without changing workbook data or revision. */
+export async function rejectWorkbookProposal(workbookId, proposalId) {
+    const normalizedId = normalizeWorkbookId(workbookId);
+    return withWorkbookQueue(normalizedId, async () => {
+        let meta = await readWorkbook(normalizedId);
+        if (meta === null)
+            throw new Error(`工作簿不存在：${workbookId}`);
+        meta = cloneSnapshot(meta);
+        const proposal = (meta.proposals ?? []).find(item => item.id === proposalId);
+        if (proposal === undefined)
+            throw new Error(`提案不存在：${proposalId}`);
+        const timestamp = new Date().toISOString();
+        meta.proposals = (meta.proposals ?? []).map(item => item.id === proposalId ? { ...item, status: 'rejected', updatedAt: timestamp } : item);
+        await writeWorkbook(meta);
+        return meta;
+    });
+}
+/** Restore any replayable previous version as a new revision. */
+export async function rollbackWorkbook(args) {
+    const workbookId = normalizeWorkbookId(args.workbookId);
+    return withWorkbookQueue(workbookId, async () => {
+        let meta = await readWorkbook(workbookId, { includeCheckpoints: true });
+        if (meta === null)
+            throw new Error(`工作簿不存在：${args.workbookId}`);
+        meta = cloneSnapshot(meta);
+        const revision = meta.revision ?? 0;
+        validateOpId(args.opId);
+        const existing = args.opId === undefined
+            ? undefined
+            : (meta.operations ?? []).find(operation => operation.opId === args.opId);
+        if (existing !== undefined) {
+            if (existing.type !== 'snapshot_replace' || existing.parentRevision !== args.targetRevision) {
+                throw new Error(`opId 已被其他请求使用：${args.opId}`);
+            }
+            return { meta, operation: existing };
+        }
+        if (args.expectedRevision !== undefined && args.expectedRevision !== revision) {
+            throw new WorkbookRevisionConflictError(args.expectedRevision, revision, undefined, [], workbookId);
+        }
+        if (args.targetRevision === revision)
+            throw new Error(`已经位于 revision ${args.targetRevision}`);
+        const target = await readWorkbookAtRevision(workbookId, args.targetRevision);
+        if (target === null)
+            throw new Error(`找不到可重放的 revision ${args.targetRevision}`);
+        finalizeOpenUserVersions(meta);
+        const operation = {
+            opId: args.opId ?? `rollback:${args.targetRevision}:${randomUUID()}`,
+            workbookId,
+            revision: revision + 1,
+            parentRevision: args.targetRevision,
+            baseRevision: revision,
+            versionId: `restore:${workbookId}:${randomUUID().slice(0, 12)}`,
+            versionStatus: 'restored',
+            versionKind: 'named',
+            versionSummary: optionalVersionText(args.summary, 'summary', 280) ?? `恢复到 revision ${args.targetRevision}`,
+            restoredFromRevision: args.targetRevision,
+            actor: args.actor ?? 'agent',
+            type: 'snapshot_replace',
+            timestamp: new Date().toISOString(),
+            lineage: args.lineage,
+            payload: { snapshot: target.snapshot },
+        };
+        const previousSnapshot = cloneSnapshot(meta.snapshot);
+        meta.snapshot = applyWorkbookOperation(meta.snapshot, operation);
+        meta.sheetOrder = asWorkbookSnapshot(meta.snapshot).sheetOrder.slice();
+        meta.revision = operation.revision;
+        meta.updatedAt = operation.timestamp;
+        expireStaleProposals(meta, operation.revision);
+        // Rollback is a normal new version whose logical parent is the target
+        // version. Keep the snapshot payload so this version can be replayed.
+        const logOperation = operation;
+        meta.operations = [...(meta.operations ?? []), logOperation];
+        meta.checkpoints = compactCheckpoints([...(meta.checkpoints ?? []), { revision, actor: operation.actor, timestamp: operation.timestamp, snapshot: previousSnapshot }]);
+        await writeWorkbook(meta, { persistSnapshot: true, persistCheckpoints: true });
+        publishWorkbookCollaboration(logOperation);
+        return { meta, operation: logOperation };
+    });
+}
+/**
+ * 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 async function readStepChanges(workbookId, targetRevision, stepIndex) {
+    const after = await readWorkbookAtStep(workbookId, targetRevision, stepIndex);
+    if (after === null)
+        return null;
+    const before = stepIndex === 0
+        ? await readWorkbookAtRevision(workbookId, (after.baseRevision ?? 0))
+        : await readWorkbookAtStep(workbookId, targetRevision, stepIndex - 1);
+    if (before === null)
+        return null;
+    return diffWorkbookSnapshots(before.snapshot, after.snapshot);
+}
+/** 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 async function readWorkbookAtStep(workbookId, targetRevision, stepIndex) {
+    if (!Number.isInteger(stepIndex) || stepIndex < 0)
+        return null;
+    const meta = await readWorkbook(workbookId, { includeCheckpoints: true });
+    if (meta === null || !Number.isInteger(targetRevision) || targetRevision <= 0 || targetRevision > (meta.revision ?? 0))
+        return null;
+    const operation = (meta.operations ?? []).find(item => item.revision === targetRevision);
+    if (operation === undefined)
+        return null;
+    const versionId = operation.versionId ?? `revision:${operation.revision}`;
+    const versionOperations = (meta.operations ?? [])
+        .filter(item => (item.versionId ?? `revision:${item.revision}`) === versionId && item.revision <= targetRevision)
+        .sort((left, right) => left.revision - right.revision);
+    const firstOperation = versionOperations[0] ?? operation;
+    const steps = versionOperations.flatMap(item => workbookOperationSteps(item));
+    if (stepIndex >= steps.length)
+        return null;
+    // Legacy snapshot_replace records may have lost their payload during the
+    // old 200-operation compaction pass. If a checkpoint was written exactly at
+    // that revision, it is still a valid historical state even though the
+    // opaque operation itself cannot be reapplied from the previous revision.
+    if (versionOperations.length === 1 && firstOperation.revision === targetRevision
+        && firstOperation.type === 'snapshot_replace' && firstOperation.payload.snapshot === undefined) {
+        const checkpointState = await readWorkbookAtRevision(workbookId, targetRevision);
+        // The start state is unrecoverable here, so report the step as its own
+        // baseline: a diff against it is empty, which is the honest answer.
+        if (checkpointState !== null)
+            return { ...checkpointState, step: 0, stepCount: 1, baseRevision: targetRevision };
+    }
+    const previous = await readWorkbookAtRevision(workbookId, Math.max(0, firstOperation.revision - 1));
+    if (previous === null)
+        return null;
+    let snapshot = cloneSnapshot(previous.snapshot);
+    for (let index = 0; index <= stepIndex; index += 1) {
+        const step = steps[index];
+        if (step === undefined)
+            return null;
+        snapshot = applyWorkbookOperation(snapshot, step);
+    }
+    return { snapshot, revision: targetRevision, step: stepIndex, stepCount: steps.length, baseRevision: Math.max(0, firstOperation.revision - 1) };
+}
+function validateOpId(opId) {
+    if (opId !== undefined && (opId.trim().length === 0 || opId.length > 256)) {
+        throw new Error('opId 必须是 1 到 256 个字符');
+    }
+}
+/** Deterministic JSON used for idempotency request fingerprints. */
+function compactCheckpoints(checkpoints) {
+    const unique = new Map();
+    for (const checkpoint of checkpoints)
+        unique.set(checkpoint.revision, checkpoint);
+    const ordered = [...unique.values()].sort((left, right) => left.revision - right.revision);
+    const latestRevision = ordered.at(-1)?.revision;
+    // Migrate legacy "every mutation" checkpoints lazily. A checkpoint at
+    // revision N represents the state before N+1, so interval boundaries are
+    // N+1 = 20, 40, ...; keep revision 0 and the latest legacy point as well.
+    return ordered
+        .filter(checkpoint => checkpoint.revision === 0
+        || (checkpoint.revision + 1) % CHECKPOINT_INTERVAL === 0
+        || checkpoint.revision === latestRevision);
+}