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

package/src/workbook-manager.ts

@@ -0,0 +1,1111 @@
+/**
+ * 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 { join } from 'node:path'
+import {
+  type WorkbookMeta,
+  type WorkbookOperation,
+  type WorkbookOperationPayload,
+  type WorkbookOperationType,
+  type WorkbookVersionStatus,
+  type WorkbookChange,
+  type WorkbookProposal,
+  type WorkbookWorktree,
+  type WorkbookWorktreeStatus,
+} from './types.ts'
+import { conflictPayload, type ConflictEntry, type ConflictPayload, type VersionKind } from '#contracts'
+import type { LineageContext } from '#contracts'
+
+import { DataSheetError } from './errors.ts'
+import { publishWorkbookCollaboration } from './collaboration-hub.ts'
+import { newWorktreeId, nextContinuationVersionId, normalizeWorkbookId, normalizeWorktreeId } from './contract/ids.ts'
+import { operationSummary, workbookOperationSteps } from './contract/operations.ts'
+import {
+  dshHome,
+  workbookCheckpointsPath,
+} from './store/paths.ts'
+import {
+  readWorkbook,
+  readWorkbookAtRevision,
+  readWorkbookWorktree,
+  readJsonFile,
+  isStoredCheckpoint,
+} from './store/read.ts'
+import {
+  withWorkbookQueue,
+  withWorktreeQueue,
+  writeWorkbook,
+  writeWorktree,
+} from './store/write.ts'
+import {
+  pruneAutoVersionOperations,
+  isIdlePast,
+  CHECKPOINT_INTERVAL,
+} from './store/retention.ts'
+// 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, 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'
+import { applyWorkbookOperation, resolveOperationPayload, validateSnapshotBounds } from './contract/mutations.ts'
+import { PROPOSAL_LOG_LIMIT } from './contract/operations.ts'
+import { DIFF_CHANGE_LIMIT, collectDiffScopes, diffWorkbookSnapshots } from './version/diff.ts'
+import { describeSnapshotReplace } from './version/summary.ts'
+import {
+  finalizeOpenUserVersions,
+  finalizeVersion,
+  isOpenVersionStatus,
+  normalizeVersionKind,
+  normalizeVersionStatus,
+  optionalVersionText,
+  settleIdleUserVersions,
+  VERSION_STEP_LIMIT,
+} from './version/session.ts'
+import {
+  DEFAULT_SHEET_FONT_FAMILY,
+  asWorkbookSnapshot,
+  cloneSnapshot,
+  findDuplicateRows,
+  readWorkbookRange,
+  DEFAULT_SHEET_ROWS,
+  DEFAULT_SHEET_COLUMNS,
+  stableJson,
+} from './contract/snapshots.ts'
+
+// 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.ts'
+export { workbookOperationSteps } from './contract/operations.ts'
+export { findDuplicateRows, readWorkbookRange } from './contract/snapshots.ts'
+export { applyWorkbookOperation } from './contract/mutations.ts'
+
+// 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.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 async function createWorkbookWorktree(args: {
+  workbookId: string
+  ownerSessionId: string
+  name?: string
+  worktreeId?: string
+}): Promise<WorkbookWorktree> {
+  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: WorkbookWorktree = {
+      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: {
+  workbookId: string
+  worktreeId: string
+  ownerSessionId: string
+  actor: 'agent' | 'user'
+  type: WorkbookOperationType
+  payload: WorkbookOperationPayload
+  expectedRevision?: number
+  opId?: string
+  lineage?: LineageContext
+}): Promise<{ worktree: WorkbookWorktree; operation: WorkbookOperation }> {
+  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: WorkbookOperation = {
+      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: {
+  workbookId: string
+  worktreeId: string
+  ownerSessionId: string
+  status: 'ready' | 'reopen' | 'discarded'
+}): Promise<WorkbookWorktree> {
+  const workbookId = normalizeWorkbookId(args.workbookId)
+  return withWorktreeQueue(workbookId, args.worktreeId, async () => {
+    const worktree = await readWorkbookWorktree(workbookId, args.worktreeId)
+    assertWorktreeOwner(worktree, args.ownerSessionId)
+    const nextStatus: WorkbookWorktreeStatus = 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: {
+  workbookId: string
+  worktreeId: string
+  ownerSessionId: string
+  actor?: 'agent' | 'user'
+  expectedRevision?: number
+}): Promise<{ worktree: WorkbookWorktree; mutation: WorkbookMutationResult }> {
+  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: string): string | null {
+  const id = value.trim()
+  return id.length > 0 && id.length <= 256 ? id : null
+}
+
+function assertWorktreeOwner(worktree: WorkbookWorktree | null, ownerSessionId: string): asserts worktree is WorkbookWorktree {
+  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: string): unknown {
+  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 {
+  /** Unified cross-plugin 409 body (PRD §5.1). */
+  readonly payload: ConflictPayload
+
+  constructor(
+    readonly expected: number,
+    readonly actual: number,
+    message?: string,
+    readonly conflictSet: ConflictEntry[] = [],
+    readonly workbookId = '',
+  ) {
+    const text = message ?? `工作簿版本已变化：请求基于 revision ${expected}，当前是 ${actual}；请先重新读取工作簿`
+    super(text)
+    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: WorkbookOperation[]): ConflictEntry[] {
+  return operations.slice(-20).map(operation => ({
+    kind: 'content' as const,
+    target: `r${operation.revision}`,
+    description: operationSummary(operation),
+    remote: operation.type,
+  }))
+}
+
+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
+}
+
+/** 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: {
+  actor: 'agent' | 'user'
+  type: WorkbookOperationType
+  payload: WorkbookOperationPayload
+  versionId?: string
+  // Keep the caller's wire value in the fingerprint. That lets an old browser
+  // safely retry a previously accepted `temporary` request while the durable
+  // record itself is normalized to `open`.
+  versionStatus?: WorkbookVersionStatus
+  versionSummary?: string
+  versionKind?: VersionKind
+  versionIntent?: string
+  agentRunId?: string
+  lineage?: LineageContext
+}): string {
+  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: WorkbookOperation): string {
+  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: {
+  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> {
+  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) as WorkbookMeta
+    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: WorkbookVersionStatus = 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: WorkbookOperation[] | undefined
+    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: WorkbookOperation = {
+      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)) as { checkpoints?: unknown } | null
+      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: WorkbookMeta, actor: 'agent' | 'user', step: WorkbookMutationPlanStep): string {
+  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: {
+  workbookId: string
+  actor: 'agent'
+  steps: WorkbookMutationPlanStep[]
+  expectedRevision?: number
+  dryRun?: boolean
+}): Promise<WorkbookMutationPlanResult> {
+  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 is string => 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: WorkbookOperation[] | undefined
+    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) as WorkbookMeta
+    finalizeOpenUserVersions(meta)
+    let revision = currentRevision
+    const committed: WorkbookOperation[] = []
+    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: WorkbookOperation = {
+        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: WorkbookOperation[], baseRevision: number, currentRevision: number): WorkbookOperation[] | null {
+  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: WorkbookMeta, currentRevision: number): void {
+  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: WorkbookOperationType, payload: WorkbookOperationPayload, target: Set<string>): boolean {
+  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: WorkbookOperationType, payload: WorkbookOperationPayload, intervening: WorkbookOperation[]): boolean {
+  const incoming = new Set<string>()
+  if (!collectCellKeys(type, payload, incoming)) return false
+  for (const operation of intervening) {
+    const interveningCells = new Set<string>()
+    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: WorkbookMutationPlanStep[], intervening: WorkbookOperation[]): boolean {
+  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: {
+  workbookId: string
+  actor: 'agent' | 'user'
+  operations: Array<{ type: WorkbookOperationType; payload: WorkbookOperationPayload }>
+  expectedRevision?: number
+  proposalId?: string
+  summary?: string
+}): Promise<WorkbookProposalResult> {
+  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) as WorkbookMeta
+    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: WorkbookProposal = {
+      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: {
+  workbookId: string
+  proposalId: string
+  actor: 'agent' | 'user'
+  expectedRevision?: number
+}): Promise<WorkbookMutationResult> {
+  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) as WorkbookMeta
+    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: WorkbookOperation = {
+      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: string, proposalId: string): Promise<WorkbookMeta> {
+  const normalizedId = normalizeWorkbookId(workbookId)
+  return withWorkbookQueue(normalizedId, async () => {
+    let meta = await readWorkbook(normalizedId)
+    if (meta === null) throw new Error(`工作簿不存在：${workbookId}`)
+    meta = cloneSnapshot(meta) as WorkbookMeta
+    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: {
+  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> {
+  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) as WorkbookMeta
+    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: WorkbookOperation = {
+      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: string, targetRevision: number, stepIndex: number): Promise<WorkbookChange[] | null> {
+  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: string, targetRevision: number, stepIndex: number): Promise<{ snapshot: unknown; revision: number; step: number; stepCount: number; baseRevision?: number } | null> {
+  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: string | undefined): void {
+  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: WorkbookCheckpointLike[]): WorkbookCheckpointLike[] {
+  const unique = new Map<number, WorkbookCheckpointLike>()
+  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)
+}
+
+type WorkbookCheckpointLike = { revision: number; actor: 'agent' | 'user'; timestamp: string; snapshot: unknown }