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

package/src/contract/mutations.ts

@@ -0,0 +1,791 @@
+/**
+ * The snapshot mutator: one DSH operation in, the rewritten snapshot out
+ * (docs/issue/0022 P0/P1).
+ *
+ * Pure and Univer-free — it is the model's own answer to "what does this
+ * operation mean", and `store/read.ts` replays operations through it when a
+ * workbook's snapshot is older than its revision. It lives in `contract/`
+ * rather than in `store/` precisely because it is not about the disk: moving
+ * the read path into the store without it would have made `store/` import
+ * *up* into `workbook-manager`, which the architecture guard forbids.
+ */
+import {
+  SHEET_MAX_COLUMNS,
+  SHEET_MAX_PHYSICAL_ROWS,
+  SHEET_MAX_ROWS,
+  type SheetColumn,
+  type SheetSchema,
+  type WorkbookCellDeleteShift,
+  type WorkbookCellUpdate,
+  type WorkbookCellValue,
+  type WorkbookOperation,
+  type WorkbookOperationPayload,
+  type WorkbookOperationType,
+  type WorkbookRange,
+} from '../types.ts'
+import { randomUUID } from 'node:crypto'
+import {
+  asWorkbookSnapshot,
+  cloneSnapshot,
+  findDuplicateRows,
+  isSheetSchema,
+  resolveSheet,
+  toCellValue,
+  validateIndex,
+  validateRange,
+  type StoredCell,
+  type WorkbookSheet,
+  type WorkbookSnapshot,
+  DEFAULT_SHEET_ROWS,
+  DEFAULT_SHEET_COLUMNS,
+  normalizeCellFormula,
+} from './snapshots.ts'
+import { APPEND_HEADER_MISMATCH } from './operations.ts'
+
+
+/** Apply one DSH operation to a Univer-compatible snapshot. */
+export function applyWorkbookOperation(snapshot: unknown, operation: WorkbookOperation): unknown {
+  if (operation.type === 'snapshot_replace') {
+    validateSnapshotBounds(operation.payload.snapshot)
+    // A copy, not the payload itself. The replay loop in `store/read.ts` keeps
+    // applying later operations to whatever this returns, so handing back the
+    // caller's object makes the *stored* operation payload accumulate every
+    // later revision — and `store/write.ts` persists `meta.operations` verbatim,
+    // so a rollback or step diff for this revision would show a later state.
+    // The neighbouring branches clone for the same reason; this one did not.
+    return cloneSnapshot(asWorkbookSnapshot(operation.payload.snapshot))
+  }
+  const root = asWorkbookSnapshot(snapshot)
+  const payload = operation.payload
+  switch (operation.type) {
+    case 'update_cells':
+      updateCells(root, payload.sheetId, payload.cells ?? [])
+      break
+    case 'clear_range':
+      clearRange(root, payload.sheetId, payload.range)
+      break
+    case 'delete_cells':
+      deleteCells(root, payload.sheetId, payload.range, payload.shift ?? 'clear')
+      break
+    case 'insert_rows':
+      insertRows(root, payload.sheetId, payload.range?.startRow ?? 0, payload.count ?? 1)
+      break
+    case 'delete_rows':
+      deleteRows(root, payload.sheetId, payload.range?.startRow ?? 0, payload.count ?? 1)
+      break
+    case 'insert_columns':
+      insertColumns(root, payload.sheetId, payload.range?.startColumn ?? 0, payload.count ?? 1)
+      break
+    case 'delete_columns':
+      deleteColumns(root, payload.sheetId, payload.range?.startColumn ?? 0, payload.count ?? 1)
+      break
+    case 'create_sheet':
+      createSheet(root, payload.sheetId ?? `sheet-${operation.opId.slice(0, 12)}`, payload.name)
+      break
+    case 'delete_sheet':
+      deleteSheet(root, payload.sheetId ?? payload.sheetName)
+      break
+    case 'rename_sheet':
+      renameSheet(root, payload.sheetId, payload.name)
+      break
+    case 'append_rows':
+      appendRows(root, payload.sheetId ?? payload.sheetName, payload.columns ?? [], payload.rows ?? [], payload.meta, payload.name, payload.headerRowIndex, payload.verifyHeader)
+      break
+    case 'format_cells':
+      formatCells(root, payload.sheetId ?? payload.sheetName, payload.range, payload.style)
+      break
+    case 'merge_cells':
+      mergeCells(root, payload.sheetId ?? payload.sheetName, payload.range ?? payload.merge)
+      break
+    case 'unmerge_cells':
+      unmergeCells(root, payload.sheetId ?? payload.sheetName, payload.range ?? payload.merge)
+      break
+    case 'freeze_panes':
+      freezePanes(root, payload.sheetId ?? payload.sheetName, payload.freeze)
+      break
+    case 'set_column_width':
+      setDimension(root, payload.sheetId ?? payload.sheetName, 'columnData', payload.range?.startColumn ?? 0, payload.size)
+      break
+    case 'set_row_height':
+      setDimension(root, payload.sheetId ?? payload.sheetName, 'rowData', payload.range?.startRow ?? 0, payload.size)
+      break
+    case 'sort_range':
+      sortRange(root, payload.sheetId ?? payload.sheetName, payload.range, payload.sort)
+      break
+    case 'set_hyperlink':
+      setHyperlink(root, payload.sheetId ?? payload.sheetName, payload.range, payload.url, payload.label)
+      break
+    case 'remove_hyperlink':
+      removeHyperlink(root, payload.sheetId ?? payload.sheetName, payload.range)
+      break
+    case 'remove_duplicates':
+      removeDuplicateRows(root, payload.sheetId ?? payload.sheetName, payload)
+      break
+    case 'batch':
+      for (const [index, child] of (payload.operations ?? []).entries()) {
+        applyWorkbookOperation(root, {
+          opId: `${operation.opId}:${index}`,
+          workbookId: operation.workbookId,
+          revision: operation.revision,
+          actor: operation.actor,
+          timestamp: operation.timestamp,
+          type: child.type,
+          payload: child.payload,
+        })
+      }
+      break
+    default:
+      assertNeverOperation(operation.type)
+  }
+  return root
+}
+
+/** Read a rectangular range as a compact 2D value matrix. */
+export function validateSnapshotBounds(value: unknown): void {
+  const serialized = JSON.stringify(value)
+  if (serialized === undefined || serialized.length > 25 * 1024 * 1024) throw new Error('工作簿快照过大（最大 25 MB）')
+  const root = asWorkbookSnapshot(value)
+  if (root.sheetOrder.length > 100 || Object.keys(root.sheets).length > 100) throw new Error('工作簿 sheet 数量超过上限（最多 100 个）')
+  const seenSheetIds = new Set<string>()
+  for (const sheetId of root.sheetOrder) {
+    if (seenSheetIds.has(sheetId) || root.sheets[sheetId] === undefined) throw new Error('工作簿 sheet 顺序无效')
+    seenSheetIds.add(sheetId)
+  }
+  for (const [sheetId, sheet] of Object.entries(root.sheets)) {
+    if (typeof sheet !== 'object' || sheet === null) throw new Error('工作簿 sheet 格式无效')
+    if (sheet.id !== sheetId || typeof sheet.name !== 'string' || sheet.name.trim().length === 0 || sheet.name.length > 64) throw new Error('工作簿 sheet 元数据无效')
+    if (typeof sheet.cellData !== 'object' || sheet.cellData === null || Array.isArray(sheet.cellData)) throw new Error('工作簿 cellData 格式无效')
+    const rowCount = Number(sheet.rowCount)
+    const columnCount = Number(sheet.columnCount)
+    if (!Number.isInteger(rowCount) || rowCount < 1 || rowCount > SHEET_MAX_PHYSICAL_ROWS) throw new Error('工作簿行数超过上限')
+    if (!Number.isInteger(columnCount) || columnCount < 1 || columnCount > SHEET_MAX_COLUMNS) throw new Error('工作簿列数超过上限')
+    for (const [rowKey, row] of Object.entries(sheet.cellData)) {
+      const rowIndex = Number(rowKey)
+      if (!Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= SHEET_MAX_PHYSICAL_ROWS) throw new Error('工作簿包含越界行')
+      if (typeof row !== 'object' || row === null || Array.isArray(row)) throw new Error('工作簿行数据格式无效')
+      for (const columnKey of Object.keys(row)) {
+        const columnIndex = Number(columnKey)
+        if (!Number.isInteger(columnIndex) || columnIndex < 0 || columnIndex >= SHEET_MAX_COLUMNS) throw new Error('工作簿包含越界列')
+      }
+    }
+  }
+}
+
+/** Guard operations whose full Excel semantics are not represented by the
+ * compact Host snapshot mutator. A snapshot fallback remains available for
+ * these workbooks through import/user edits. */
+function assertStructuralOperationSupported(root: WorkbookSnapshot, sheet: WorkbookSheet, operation: string): void {
+  const hasFormula = Object.values(root.sheets).some(candidate => Object.values(candidate.cellData ?? {}).some(row => Object.values(row).some(cell => typeof cell.f === 'string' && cell.f.length > 0)))
+  const hasAdvancedState = ['mergeData', 'rowData', 'columnData', 'freeze', 'conditionalFormatting', 'dataValidation', 'drawings', 'tables', 'comments'].some(key => {
+    const value = sheet[key]
+    if (value === undefined || value === null) return false
+    if (Array.isArray(value)) return value.length > 0
+    if (typeof value === 'object') return Object.keys(value as object).length > 0
+    return true
+  })
+  if (hasFormula || hasAdvancedState) {
+    throw new Error(`${operation} 在含公式或高级结构的 sheet 上被拒绝，以避免破坏引用和格式；写更多行请直接用 update_cells 或 import_file（越界会自动扩容 rowCount，不必先 insert_rows），整体替换请改用 snapshot`)
+  }
+}
+
+function maxCellIndex(cellData: Record<string, Record<string, StoredCell>>, dimension: 'row' | 'column'): number {
+  let max = -1
+  if (dimension === 'row') {
+    for (const key of Object.keys(cellData)) {
+      const value = Number(key)
+      if (Number.isInteger(value)) max = Math.max(max, value)
+    }
+    return max
+  }
+  for (const row of Object.values(cellData)) {
+    for (const key of Object.keys(row)) {
+      const value = Number(key)
+      if (Number.isInteger(value)) max = Math.max(max, value)
+    }
+  }
+  return max
+}
+
+function recomputeDataSheetStats(sheet: WorkbookSheet): void {
+  let maxDataRow = 0
+  let maxDataColumn = 0
+  for (const [rowKey, row] of Object.entries(sheet.cellData ?? {})) {
+    const rowIndex = Number(rowKey)
+    if (!Number.isInteger(rowIndex)) continue
+    if (rowIndex > 0 && Object.keys(row).length > 0) maxDataRow = Math.max(maxDataRow, rowIndex)
+    for (const columnKey of Object.keys(row)) {
+      const columnIndex = Number(columnKey)
+      if (Number.isInteger(columnIndex)) maxDataColumn = Math.max(maxDataColumn, columnIndex + 1)
+    }
+  }
+  // Recompute from the resulting cell map so clearing the last populated cell
+  // cannot leave a stale row/column count in the schema and tool output.
+  sheet.dataSheetStats = { rowCount: maxDataRow, columnCount: maxDataColumn }
+  const schema = isSheetSchema(sheet.dataSheetSchema) ? sheet.dataSheetSchema : undefined
+  if (schema !== undefined) {
+    sheet.dataSheetSchema = { ...schema, rowCount: maxDataRow, updatedAt: new Date().toISOString() }
+  }
+}
+
+function updateCells(root: WorkbookSnapshot, sheetRef: string | undefined, cells: WorkbookCellUpdate[]): void {
+  if (cells.length === 0) throw new Error('cells 不能为空')
+  if (cells.length > SHEET_MAX_ROWS * SHEET_MAX_COLUMNS) throw new Error('一次修改的单元格数量超过上限')
+  const sheet = resolveSheet(root, sheetRef)
+  for (const cell of cells) {
+    validateIndex(cell.row, 'cell.row')
+    validateIndex(cell.column, 'cell.column')
+    if (cell.row >= SHEET_MAX_PHYSICAL_ROWS) throw new Error(`cell.row 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+    if (cell.column >= SHEET_MAX_COLUMNS) throw new Error(`cell.column 超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+    const row = (sheet.cellData[String(cell.row)] ??= {})
+    const formula = normalizeCellFormula(cell.formula)
+    if (cell.value === null && formula === undefined) {
+      delete row[String(cell.column)]
+      if (Object.keys(row).length === 0) delete sheet.cellData[String(cell.row)]
+      continue
+    }
+    const current = row[String(cell.column)]
+    row[String(cell.column)] = formula === undefined
+      ? { ...(current ?? {}), v: cell.value, f: undefined }
+      : { ...(current ?? {}), v: cell.value, f: formula }
+    if (formula === undefined) delete row[String(cell.column)].f
+    sheet.rowCount = Math.max(sheet.rowCount, cell.row + 1)
+    sheet.columnCount = Math.max(sheet.columnCount, cell.column + 1)
+  }
+  recomputeDataSheetStats(sheet)
+}
+
+function clearRange(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined): void {
+  validateRange(range)
+  const sheet = resolveSheet(root, sheetRef)
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const cells = sheet.cellData[String(row)]
+    if (cells === undefined) continue
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) delete cells[String(column)]
+    if (Object.keys(cells).length === 0) delete sheet.cellData[String(row)]
+  }
+  recomputeDataSheetStats(sheet)
+}
+
+function deleteCells(
+  root: WorkbookSnapshot,
+  sheetRef: string | undefined,
+  range: WorkbookRange | undefined,
+  shift: WorkbookCellDeleteShift,
+): void {
+  validateRange(range)
+  if (shift !== 'clear' && shift !== 'left' && shift !== 'up') {
+    throw new Error(`不支持的单元格删除方式：${String(shift)}`)
+  }
+  if (shift === 'clear') {
+    clearRange(root, sheetRef, range)
+    return
+  }
+  const sheet = resolveSheet(root, sheetRef)
+  assertStructuralOperationSupported(root, sheet, `delete_cells:${shift}`)
+  const width = range.endColumn - range.startColumn + 1
+  const height = range.endRow - range.startRow + 1
+  const nextCellData: Record<string, Record<string, StoredCell>> = {}
+
+  for (const [rowKey, cells] of Object.entries(sheet.cellData)) {
+    const row = Number(rowKey)
+    if (!Number.isInteger(row)) continue
+    const nextCells: Record<string, StoredCell> = {}
+    for (const [columnKey, cell] of Object.entries(cells)) {
+      const column = Number(columnKey)
+      if (!Number.isInteger(column)) continue
+      if (shift === 'left' && row >= range.startRow && row <= range.endRow) {
+        if (column >= range.startColumn && column <= range.endColumn) continue
+        nextCells[String(column > range.endColumn ? column - width : column)] = cell
+        continue
+      }
+      if (shift === 'up' && column >= range.startColumn && column <= range.endColumn) {
+        if (row >= range.startRow && row <= range.endRow) continue
+        nextCellData[String(row > range.endRow ? row - height : row)] ??= {}
+        nextCellData[String(row > range.endRow ? row - height : row)][columnKey] = cell
+        continue
+      }
+      nextCells[columnKey] = cell
+    }
+    if (Object.keys(nextCells).length > 0) {
+      nextCellData[rowKey] ??= {}
+      Object.assign(nextCellData[rowKey], nextCells)
+    }
+  }
+  sheet.cellData = nextCellData
+  recomputeDataSheetStats(sheet)
+}
+
+function insertRows(root: WorkbookSnapshot, sheetRef: string | undefined, startRow: number, count: number): void {
+  validateIndex(startRow, 'startRow')
+  validateCount(count)
+  const sheet = resolveSheet(root, sheetRef)
+  if (sheet.rowCount + count > SHEET_MAX_PHYSICAL_ROWS) throw new Error(`插入后行数超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+  assertStructuralOperationSupported(root, sheet, 'insert_rows')
+  if (maxCellIndex(sheet.cellData, 'row') + count >= SHEET_MAX_PHYSICAL_ROWS) throw new Error('插入后单元格超出工作簿行上限')
+  const rows = Object.keys(sheet.cellData).map(Number).filter(Number.isInteger).sort((a, b) => b - a)
+  for (const row of rows) {
+    if (row < startRow) continue
+    sheet.cellData[String(row + count)] = sheet.cellData[String(row)]
+    delete sheet.cellData[String(row)]
+  }
+  sheet.rowCount += count
+  recomputeDataSheetStats(sheet)
+}
+
+function deleteRows(root: WorkbookSnapshot, sheetRef: string | undefined, startRow: number, count: number): void {
+  validateIndex(startRow, 'startRow')
+  validateCount(count)
+  if (startRow >= SHEET_MAX_PHYSICAL_ROWS) throw new Error(`startRow 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+  if (startRow + count > SHEET_MAX_PHYSICAL_ROWS) throw new Error(`删除范围超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+  const sheet = resolveSheet(root, sheetRef)
+  assertStructuralOperationSupported(root, sheet, 'delete_rows')
+  for (let row = startRow; row < startRow + count; row += 1) delete sheet.cellData[String(row)]
+  const rows = Object.keys(sheet.cellData).map(Number).filter(Number.isInteger).sort((a, b) => a - b)
+  for (const row of rows) {
+    if (row < startRow + count) continue
+    sheet.cellData[String(row - count)] = sheet.cellData[String(row)]
+    delete sheet.cellData[String(row)]
+  }
+  sheet.rowCount = Math.max(1, sheet.rowCount - count)
+  recomputeDataSheetStats(sheet)
+}
+
+function insertColumns(root: WorkbookSnapshot, sheetRef: string | undefined, startColumn: number, count: number): void {
+  validateIndex(startColumn, 'startColumn')
+  validateCount(count)
+  const sheet = resolveSheet(root, sheetRef)
+  if (sheet.columnCount + count > SHEET_MAX_COLUMNS) throw new Error(`插入后列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  assertStructuralOperationSupported(root, sheet, 'insert_columns')
+  if (maxCellIndex(sheet.cellData, 'column') + count >= SHEET_MAX_COLUMNS) throw new Error('插入后单元格超出工作簿列上限')
+  for (const cells of Object.values(sheet.cellData)) {
+    const nextCells: Record<string, StoredCell> = {}
+    for (const [columnKey, cell] of Object.entries(cells)) {
+      const column = Number(columnKey)
+      if (!Number.isInteger(column)) continue
+      nextCells[String(column >= startColumn ? column + count : column)] = cell
+    }
+    Object.keys(cells).forEach(column => { delete cells[column] })
+    Object.assign(cells, nextCells)
+  }
+  sheet.columnCount += count
+  recomputeDataSheetStats(sheet)
+}
+
+function deleteColumns(root: WorkbookSnapshot, sheetRef: string | undefined, startColumn: number, count: number): void {
+  validateIndex(startColumn, 'startColumn')
+  validateCount(count)
+  if (startColumn >= SHEET_MAX_COLUMNS || startColumn + count > SHEET_MAX_COLUMNS) {
+    throw new Error(`删除范围超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  }
+  const endColumn = startColumn + count
+  const sheet = resolveSheet(root, sheetRef)
+  assertStructuralOperationSupported(root, sheet, 'delete_columns')
+  for (const cells of Object.values(sheet.cellData)) {
+    const nextCells: Record<string, StoredCell> = {}
+    for (const [columnKey, cell] of Object.entries(cells)) {
+      const column = Number(columnKey)
+      if (!Number.isInteger(column) || (column >= startColumn && column < endColumn)) continue
+      nextCells[String(column >= endColumn ? column - count : column)] = cell
+    }
+    Object.keys(cells).forEach(column => { delete cells[column] })
+    Object.assign(cells, nextCells)
+  }
+  sheet.columnCount = Math.max(1, sheet.columnCount - count)
+  recomputeDataSheetStats(sheet)
+}
+
+function createSheet(root: WorkbookSnapshot, sheetId: string | undefined, name: string | undefined): void {
+  const sheetName = name?.trim()
+  if (sheetName === undefined || sheetName.length === 0) throw new Error('sheet 名称不能为空')
+  if (Object.values(root.sheets).some(sheet => sheet.name === sheetName)) throw new Error(`sheet 已存在：${sheetName}`)
+  const id = sheetId?.trim() || `sheet${Date.now().toString(36)}`
+  if (root.sheets[id] !== undefined) throw new Error(`sheet id 已存在：${id}`)
+  root.sheets[id] = { id, name: sheetName, rowCount: DEFAULT_SHEET_ROWS, columnCount: DEFAULT_SHEET_COLUMNS, cellData: {} }
+  root.sheetOrder.push(id)
+}
+
+function deleteSheet(root: WorkbookSnapshot, sheetRef: string | undefined): void {
+  if (root.sheetOrder.length <= 1) throw new Error('工作簿至少需要保留一个 sheet，不能删除最后一个 sheet')
+  const sheet = resolveSheet(root, sheetRef)
+  delete root.sheets[sheet.id]
+  root.sheetOrder = root.sheetOrder.filter(id => id !== sheet.id)
+}
+
+function renameSheet(root: WorkbookSnapshot, sheetRef: string | undefined, name: string | undefined): void {
+  const sheetName = name?.trim()
+  if (sheetName === undefined || sheetName.length === 0) throw new Error('sheet 名称不能为空')
+  const sheet = resolveSheet(root, sheetRef)
+  if (Object.values(root.sheets).some(candidate => candidate.name === sheetName && candidate.id !== sheet.id)) throw new Error(`sheet 已存在：${sheetName}`)
+  sheet.name = sheetName
+}
+
+/**
+ * Mirrored by the browser projection's `applyAppendRows`, which runs the same
+ * check against live Univer state. The hint names `headerRowIndex` because that
+ * is what unblocks a report sheet whose real header is not row 0.
+ */
+export 
+/**
+ * Appends schema-typed rows below the header row.
+ *
+ * `headerRowIndex` and `verifyHeader` exist for report sheets whose real header
+ * is not row 0 — previously those sheets could only be written through
+ * `update_cells`, which is what produced the "use update_cells" dead end. Both
+ * default to the old behaviour (header on row 0, labels verified), and the
+ * default path below is left structurally identical so no stored workbook or
+ * existing caller changes meaning.
+ */
+
+function formatCells(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined, style: WorkbookOperationPayload['style']): void {
+  validateRange(range)
+  if (style === undefined || typeof style !== 'object') throw new Error('format_cells 必须提供 style')
+  const sheet = resolveSheet(root, sheetRef)
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const cells = (sheet.cellData[String(row)] ??= {})
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+      const current = cells[String(column)] ?? { v: null }
+      cells[String(column)] = { ...current, s: { ...(current.s as object ?? {}), ...style } }
+    }
+  }
+}
+
+function mergeCells(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined): void {
+  validateRange(range)
+  const sheet = resolveSheet(root, sheetRef)
+  const merges = Array.isArray(sheet.mergeData) ? sheet.mergeData as WorkbookRange[] : []
+  if (!merges.some(item => JSON.stringify(item) === JSON.stringify(range))) merges.push(range)
+  sheet.mergeData = merges
+}
+
+function unmergeCells(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined): void {
+  validateRange(range)
+  const sheet = resolveSheet(root, sheetRef)
+  const merges = Array.isArray(sheet.mergeData) ? sheet.mergeData as WorkbookRange[] : []
+  sheet.mergeData = merges.filter(item => !rangesIntersect(item, range))
+}
+
+function rangesIntersect(left: WorkbookRange, right: WorkbookRange): boolean {
+  return left.startRow <= right.endRow && right.startRow <= left.endRow
+    && left.startColumn <= right.endColumn && right.startColumn <= left.endColumn
+}
+
+function freezePanes(root: WorkbookSnapshot, sheetRef: string | undefined, freeze: WorkbookOperationPayload['freeze']): void {
+  const sheet = resolveSheet(root, sheetRef)
+  if (freeze === undefined || (freeze.rows ?? 0) < 0 || (freeze.columns ?? 0) < 0) throw new Error('freeze_panes 参数无效')
+  sheet.freeze = { rows: Math.floor(freeze.rows ?? 0), columns: Math.floor(freeze.columns ?? 0) }
+}
+
+function setDimension(root: WorkbookSnapshot, sheetRef: string | undefined, key: 'columnData' | 'rowData', index: number, size: number | undefined): void {
+  validateIndex(index, `${key} index`)
+  if (key === 'columnData' && index >= SHEET_MAX_COLUMNS) throw new Error(`columnData index 超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  if (key === 'rowData' && index >= SHEET_MAX_PHYSICAL_ROWS) throw new Error(`rowData index 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+  if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0 || size > 1000) throw new Error('尺寸必须是 0 到 1000 之间的有限数字')
+  const sheet = resolveSheet(root, sheetRef)
+  const data = (sheet[key] as Record<string, unknown> | undefined) ?? {}
+  const current = typeof data[String(index)] === 'object' && data[String(index)] !== null ? data[String(index)] as Record<string, unknown> : {}
+  const dimension = key === 'columnData' ? 'width' : 'height'
+  const otherDimension = key === 'columnData' ? 'height' : 'width'
+  const next = { ...current, [dimension]: size }
+  delete next[otherDimension]
+  data[String(index)] = next
+  sheet[key] = data
+}
+
+function sortRange(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined, sort: WorkbookOperationPayload['sort']): void {
+  validateRange(range)
+  if (sort === undefined || !Number.isInteger(sort.column) || sort.column < range.startColumn || sort.column > range.endColumn) throw new Error('sort_range 的排序列必须位于 range 内')
+  const sheet = resolveSheet(root, sheetRef)
+  const rows: Array<{ index: number; cells: Record<string, StoredCell> }> = []
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const selected: Record<string, StoredCell> = {}
+    const source = sheet.cellData[String(row)] ?? {}
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+      if (source[String(column)] !== undefined) selected[String(column)] = source[String(column)]
+    }
+    rows.push({ index: row, cells: selected })
+  }
+  const valueOf = (item: { cells: Record<string, StoredCell> }): string | number => {
+    const value = toCellValue(item.cells[String(sort.column)])
+    return typeof value === 'number' ? value : String(value ?? '')
+  }
+  rows.sort((left, right) => {
+    const a = valueOf(left)
+    const b = valueOf(right)
+    const comparison = typeof a === 'number' && typeof b === 'number' ? a - b : String(a).localeCompare(String(b), 'zh-CN')
+    return sort.direction === 'desc' ? -comparison : comparison
+  })
+  rows.forEach((item, offset) => {
+    const target = range.startRow + offset
+    const current = sheet.cellData[String(target)] ?? {}
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) delete current[String(column)]
+    Object.assign(current, item.cells)
+    if (Object.keys(current).length > 0) sheet.cellData[String(target)] = current
+    else delete sheet.cellData[String(target)]
+  })
+}
+
+function setHyperlink(
+  root: WorkbookSnapshot,
+  sheetRef: string | undefined,
+  range: WorkbookRange | undefined,
+  url: string | undefined,
+  label: string | undefined,
+): void {
+  validateRange(range)
+  const targetUrl = url?.trim()
+  if (targetUrl === undefined || targetUrl.length === 0) throw new Error('set_hyperlink.url 不能为空')
+  if (!isSafeHyperlink(targetUrl)) throw new Error('set_hyperlink.url 只支持 http(s)、mailto、file 或 sheet 内部链接')
+  const sheet = resolveSheet(root, sheetRef)
+  const row = (sheet.cellData[String(range.startRow)] ??= {})
+  const current = row[String(range.startColumn)] ?? {}
+  const display = label === undefined || label.trim().length === 0 ? String(toCellValue(current) ?? targetUrl) : label
+  const document = isRecord(current.p) ? current.p : {}
+  const oldBody = isRecord(document.body) ? document.body : {}
+  const oldRanges = Array.isArray(oldBody.customRanges) ? oldBody.customRanges.filter(item => isRecord(item) && item.rangeType !== 0) : []
+  const linkId = `dsh-link-${randomUUID()}`
+  row[String(range.startColumn)] = {
+    ...current,
+    v: display,
+    t: 1,
+    p: {
+      ...document,
+      id: typeof document.id === 'string' ? document.id : `dsh-doc-${randomUUID()}`,
+      documentStyle: isRecord(document.documentStyle) ? document.documentStyle : {},
+      body: {
+        ...oldBody,
+        dataStream: `${display}\r\n`,
+        customRanges: [
+          ...oldRanges,
+          { startIndex: 0, endIndex: Math.max(0, display.length - 1), rangeId: linkId, rangeType: 0, properties: { url: targetUrl } },
+        ],
+      },
+    },
+  }
+  sheet.rowCount = Math.max(sheet.rowCount, range.startRow + 1)
+  sheet.columnCount = Math.max(sheet.columnCount, range.startColumn + 1)
+  recomputeDataSheetStats(sheet)
+}
+
+function removeHyperlink(root: WorkbookSnapshot, sheetRef: string | undefined, range: WorkbookRange | undefined): void {
+  validateRange(range)
+  const sheet = resolveSheet(root, sheetRef)
+  const row = sheet.cellData[String(range.startRow)]
+  const current = row?.[String(range.startColumn)]
+  if (!row || !isRecord(current) || !isRecord(current.p) || !isRecord(current.p.body)) return
+  const body = current.p.body
+  if (!Array.isArray(body.customRanges)) return
+  const customRanges = body.customRanges.filter(item => !(isRecord(item) && item.rangeType === 0))
+  if (customRanges.length === body.customRanges.length) return
+  current.p = { ...current.p, body: { ...body, customRanges } }
+  recomputeDataSheetStats(sheet)
+}
+
+function withResolvedDuplicateRows(snapshot: unknown, payload: WorkbookOperationPayload): WorkbookOperationPayload {
+  validateRange(payload.range)
+  const sheet = resolveSheet(asWorkbookSnapshot(snapshot), payload.sheetId ?? payload.sheetName)
+  const range = payload.range
+  const values = rangeValues(sheet, range)
+  const removedRows = findDuplicateRows(values, range, payload.dedupeColumns, payload.hasHeader ?? false, payload.keep ?? 'first')
+  return { ...payload, removedRows }
+}
+
+/** Resolve data-dependent children before an operation is persisted/replayed. */
+export function resolveOperationPayload(snapshot: unknown, type: WorkbookOperationType, payload: WorkbookOperationPayload): WorkbookOperationPayload {
+  if (type !== 'batch') {
+    if (type === 'snapshot_replace') validateSnapshotBounds(payload.snapshot)
+    return type === 'remove_duplicates' ? withResolvedDuplicateRows(snapshot, payload) : payload
+  }
+  if (!Array.isArray(payload.operations) || payload.operations.length === 0 || payload.operations.length > 200) {
+    throw new Error('batch.operations 必须包含 1 到 200 个操作')
+  }
+  // Normal Agent/browser batches contain already validated, replayable
+  // payloads. Only the legacy data-dependent dedupe operation needs a
+  // sequential resolution pass; skipping the clone here is significant for
+  // large append/update batches.
+  if (!payload.operations.some(operation => operationNeedsPayloadResolution(operation))) return payload
+  let workingSnapshot = cloneSnapshot(snapshot)
+  const operations = (payload.operations ?? []).map((child, index) => {
+    const childPayload = resolveOperationPayload(workingSnapshot, child.type, child.payload)
+    const childOperation: WorkbookOperation = {
+      opId: `resolve:${index}`,
+      workbookId: 'resolve',
+      revision: 0,
+      baseRevision: 0,
+      actor: 'agent',
+      timestamp: new Date(0).toISOString(),
+      type: child.type,
+      payload: childPayload,
+    }
+    workingSnapshot = applyWorkbookOperation(workingSnapshot, childOperation)
+    return { ...child, payload: childPayload }
+  })
+  return { ...payload, operations }
+}
+
+function operationNeedsPayloadResolution(operation: { type: WorkbookOperationType; payload: WorkbookOperationPayload }): boolean {
+  return operation.type === 'remove_duplicates'
+    || operation.type === 'batch' && (operation.payload.operations ?? []).some(operationNeedsPayloadResolution)
+}
+
+function removeDuplicateRows(root: WorkbookSnapshot, sheetRef: string | undefined, payload: WorkbookOperationPayload): void {
+  validateRange(payload.range)
+  const sheet = resolveSheet(root, sheetRef)
+  const rows = payload.removedRows === undefined
+    ? findDuplicateRows(rangeValues(sheet, payload.range), payload.range, payload.dedupeColumns, payload.hasHeader ?? false, payload.keep ?? 'first')
+    : payload.removedRows
+  if (rows.length === 0) return
+  for (const row of rows) validateIndex(row, 'removedRows')
+  // Delete from the bottom so indexes remain the original range indexes.
+  let end = rows[rows.length - 1] as number
+  let start = end
+  for (let index = rows.length - 2; index >= -1; index -= 1) {
+    const current = index >= 0 ? rows[index] as number : undefined
+    if (current !== undefined && current === start - 1) {
+      start = current
+      continue
+    }
+    deleteRows(root, sheetRef, start, end - start + 1)
+    if (current !== undefined) {
+      end = current
+      start = current
+    }
+  }
+  recomputeDataSheetStats(sheet)
+}
+
+function rangeValues(sheet: WorkbookSheet, range: WorkbookRange): Array<Array<WorkbookCellValue | null>> {
+  const values: Array<Array<WorkbookCellValue | null>> = []
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const source = sheet.cellData[String(row)] ?? {}
+    values.push(Array.from({ length: range.endColumn - range.startColumn + 1 }, (_value, offset) => toCellValue(source[String(range.startColumn + offset)])))
+  }
+  return values
+}
+
+function isSafeHyperlink(url: string): boolean {
+  return /^(?:https?:|mailto:|file:|#)/i.test(url)
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function validateCount(count: number): void {
+  if (!Number.isInteger(count) || count < 1 || count > SHEET_MAX_ROWS) throw new Error('count 必须是 1 到上限之间的整数')
+}
+
+function coerceCellValue(type: SheetColumn['type'], value: unknown): WorkbookCellValue {
+  if (type === 'number' || type === 'currency') {
+    const numeric = typeof value === 'number' ? value : Number(value)
+    return Number.isFinite(numeric) ? numeric : String(value)
+  }
+  if (type === 'boolean') return typeof value === 'boolean' ? value : String(value) === 'true'
+  if (type === 'date') return value instanceof Date ? value.toISOString().slice(0, 10) : String(value)
+  return String(value)
+}
+
+function sameSheetColumns(left: SheetColumn[], right: SheetColumn[]): boolean {
+  return left.length === right.length && left.every((column, index) => {
+    const other = right[index]
+    return other !== undefined && column.key === other.key && column.label === other.label && column.type === other.type
+  })
+}
+
+function assertNeverOperation(value: never): never {
+  throw new Error(`不支持的 workbook operation：${String(value)}`)
+}
+
+/**
+ * Appends schema-typed rows below the header row.
+ *
+ * `headerRowIndex` and `verifyHeader` exist for report sheets whose real header
+ * is not row 0 — previously those sheets could only be written through
+ * `update_cells`, which is what produced the "use update_cells" dead end. Both
+ * default to the old behaviour (header on row 0, labels verified), and the
+ * default path below is left structurally identical so no stored workbook or
+ * existing caller changes meaning.
+ */
+function appendRows(root: WorkbookSnapshot, sheetRef: string | undefined, columns: SheetColumn[], rows: Array<Record<string, unknown>>, meta?: WorkbookOperationPayload['meta'], sheetName?: string, rawHeaderRowIndex?: number, rawVerifyHeader?: boolean): void {
+  if (columns.length === 0 || columns.length > SHEET_MAX_COLUMNS) throw new Error(`列数必须是 1 到 ${SHEET_MAX_COLUMNS}`)
+  if (rows.length > SHEET_MAX_ROWS) throw new Error(`一次追加最多 ${SHEET_MAX_ROWS} 行`)
+  const headerRowIndex = rawHeaderRowIndex ?? 0
+  if (!Number.isInteger(headerRowIndex) || headerRowIndex < 0) throw new Error('headerRowIndex 必须是大于等于 0 的整数')
+  if (headerRowIndex >= SHEET_MAX_PHYSICAL_ROWS) throw new Error('headerRowIndex 超出上限（最后一个物理行是 ' + SHEET_MAX_ROWS + '）')
+  // Only an explicit false relaxes the label comparison; it remains the guard
+  // that catches a column reorder before rows are written.
+  const verifyHeader = rawVerifyHeader !== false
+  let sheet: WorkbookSheet
+  try {
+    sheet = resolveSheet(root, sheetRef)
+  } catch (error) {
+    if (sheetRef === undefined) throw error
+    // Use the caller's stable reference as the id when append_rows creates a
+    // sheet. This keeps the Node snapshot, browser projection, and subsequent
+    // commands in the same batch on the exact same sheet.
+    createSheet(root, sheetRef, sheetName ?? sheetRef)
+    sheet = resolveSheet(root, sheetRef)
+  }
+  const headerKey = String(headerRowIndex)
+  const header = sheet.cellData[headerKey]
+  const existingSchema = isSheetSchema(sheet.dataSheetSchema) ? sheet.dataSheetSchema : undefined
+  if (verifyHeader && existingSchema !== undefined && !sameSheetColumns(existingSchema.columns, columns)) {
+    throw new Error(APPEND_HEADER_MISMATCH)
+  }
+  const existingHeaderIndexes = Object.keys(header ?? {}).map(Number).filter(Number.isInteger)
+  const existingColumnCount = existingHeaderIndexes.length === 0 ? 0 : Math.max(...existingHeaderIndexes) + 1
+  const existingHeader = header === undefined ? [] : Array.from({ length: existingColumnCount }, (_value, index) => header[String(index)]?.v)
+  if (verifyHeader && existingColumnCount > 0 && (existingColumnCount !== columns.length
+    || columns.some((column, index) => String(existingHeader[index] ?? '') !== column.label))) {
+    throw new Error(APPEND_HEADER_MISMATCH)
+  }
+  if (header === undefined || Object.keys(header).length === 0) {
+    sheet.cellData[headerKey] = Object.fromEntries(columns.map((column, index) => [String(index), { v: column.label }]))
+  }
+  const storedStats = sheet.dataSheetStats as { rowCount?: unknown } | undefined
+  const storedDataRows = typeof storedStats?.rowCount === 'number' && Number.isInteger(storedStats.rowCount) && storedStats.rowCount >= 0
+    ? storedStats.rowCount
+    : -1
+  const floorRow = headerRowIndex + 1
+  let existingDataRows = -1
+  let nextRow = floorRow
+  if (headerRowIndex === 0 && storedDataRows >= 0) {
+    existingDataRows = storedDataRows
+    nextRow = Math.max(floorRow, existingDataRows + 1)
+  } else {
+    // A stored counter can only be read against a row-0 header, so a report
+    // sheet is positioned from its real last occupied row instead.
+    for (const key of Object.keys(sheet.cellData)) {
+      const row = Number(key)
+      if (Number.isInteger(row)) nextRow = Math.max(nextRow, row + 1)
+    }
+    existingDataRows = Math.max(0, nextRow - 1)
+  }
+  if (nextRow - 1 + rows.length > SHEET_MAX_ROWS) throw new Error(`写入后行数超过上限（最多 ${SHEET_MAX_ROWS} 行）`)
+  for (const [rowIndex, input] of rows.entries()) {
+    const line: Record<string, StoredCell> = {}
+    columns.forEach((column, columnIndex) => {
+      const value = input[column.key]
+      if (value === undefined || value === null) return
+      line[String(columnIndex)] = { v: coerceCellValue(column.type, value) }
+    })
+    sheet.cellData[String(nextRow + rowIndex)] = line
+  }
+  sheet.columnCount = Math.max(sheet.columnCount, columns.length)
+  sheet.rowCount = Math.max(sheet.rowCount, nextRow + rows.length)
+  sheet.dataSheetStats = {
+    rowCount: Math.max(existingDataRows, nextRow - 1 + rows.length),
+    columnCount: Math.max(
+      typeof (sheet.dataSheetStats as { columnCount?: unknown } | undefined)?.columnCount === 'number'
+        ? (sheet.dataSheetStats as { columnCount: number }).columnCount
+        : 0,
+      columns.length,
+    ),
+  }
+  if (meta !== undefined) sheet.dataSheetMeta = meta
+  sheet.dataSheetSchema = {
+    version: existingSchema?.version ?? 1,
+    columns,
+    rowCount: Math.max(existingDataRows, nextRow - 1 + rows.length),
+    updatedAt: new Date().toISOString(),
+  } satisfies SheetSchema
+}