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

package/src/contract/operations.ts

@@ -0,0 +1,221 @@
+/**
+ * Operations: their shape, their expansion into Steps, and which Univer
+ * commands may become one (docs/issue/0022 P0).
+ *
+ * The mutation whitelist lives here rather than beside the engine because it is
+ * a policy about the *version model* — which canvas commands are durable
+ * content and which are derived UI state — not an engine detail. The engine
+ * asks; this module decides.
+ */
+import type { WorkbookOperation } from '../types.ts'
+
+/**
+ * Univer emits a small number of mutation commands for derived layout or UI
+ * state. They are useful inside the live canvas, but must not become DSH
+ * workbook revisions: they are either no-ops, recalculation markers, or state
+ * that is reconstructed when the workbook is mounted again. In particular,
+ * selection, focus, scrolling, and editor-panel commands are emitted while a
+ * user is merely navigating the canvas and must not dirty the workbook.
+ */
+const NON_PERSISTED_MUTATION_IDS = new Set([
+  'sheet.mutation.empty',
+  'sheet.mutation.mark-dirty-filter-change',
+  'sheet.mutation.re-calc-filter',
+  'sheet.mutation.set-worksheet-row-auto-height',
+  'sheet.mutation.toggle-note-popup',
+  'sheet.mutation.update-note-position',
+
+  // View-only operations emitted by clicks, keyboard navigation, and panels.
+  'sheet.operation.set-selections',
+  'sheet.operation.set-worksheet-active',
+  'sheet.operation.set-scroll',
+  'sheet.operation.scroll-to-cell',
+  'sheet.operation.scroll-to-range',
+  'sheet.operation.set-zoom-ratio',
+  'sheet.operation.set-activate-cell-edit',
+  'sheet.operation.set-cell-edit-visible',
+  'sheet.operation.set-cell-edit-visible-arrow',
+  'sheet.operation.set-cell-edit-visible-f2',
+  'sheet.operation.set-format-painter',
+  'sheet.operation.open.numfmt.panel',
+  'sheet.operation.close.numfmt.panel',
+  'sheet.command.apply-format-painter',
+  'sheet.command.set-infinite-format-painter',
+  'sheet.command.set-once-format-painter',
+  'sheet.command.move-selection',
+  'sheet.command.move-selection-enter-tab',
+  'sheet.command.expand-selection',
+  'sheet.command.select-range',
+  'sheet.command.select-all',
+  'sheet.command.set-selection-frozen',
+  'sheet.command.scroll-to-cell',
+  'sheet.command.scroll-view',
+  'sheet.command.scroll-view-reset',
+  'sheet.command.set-scroll-relative',
+  'sheet.command.change-zoom-ratio',
+  'sheet.command.set-zoom-ratio',
+  'sheet.command.set-worksheet-activate',
+])
+
+const NON_PERSISTED_MUTATION_PREFIXES = [
+  // Univer appends editor-specific suffixes to these UI operations.
+  'sheet.operation.editor-',
+]
+
+// Only these command ids are known to describe durable workbook state.  The
+// previous deny-list treated every new Univer command as a save candidate;
+// that made a navigation command capable of setting the dirty bit and caused
+// an unnecessary full snapshot request.  Unknown commands are deliberately
+// ignored until they have an explicit persistence contract and a parser.
+const PERSISTED_MUTATION_IDS = new Set([
+  'sheet.mutation.set-range-values',
+  'sheet.mutation.set-row-data',
+  'sheet.mutation.set-col-data',
+  'sheet.mutation.set-gridlines-color',
+  'sheet.mutation.set-worksheet-name',
+  'sheet.mutation.add-worksheet-merge',
+  'sheet.mutation.remove-worksheet-merge',
+  'sheet.mutation.set-style',
+  'sheet.mutation.set-number-format',
+  'sheet.command.clear-selection-content',
+  'sheet.command.set-bold',
+  'sheet.command.set-italic',
+  'sheet.command.set-underline',
+  'sheet.command.set-strikethrough',
+  'sheet.command.set-style',
+  'sheet.command.set-range-values',
+  'sheet.command.set-number-format',
+  'sheet.command.set-font-color',
+  'sheet.command.set-font-family',
+  'sheet.command.set-font-size',
+  'sheet.command.set-font-weight',
+  'sheet.command.set-font-style',
+  'sheet.command.set-horizontal-alignment',
+  'sheet.command.set-vertical-alignment',
+])
+
+/**
+ * The v3 tier of the Version these operations make up.
+ *
+ * Explicit when the log carries one. Operations written before v3 carry no
+ * `versionKind`, so the tier is derived from the facts that already separated a
+ * deliberate Version from editing-session churn — a summary, an Agent actor, a
+ * restore. Reading a missing tier as its schema default (`named`) instead is what
+ * once made every legacy Version unprunable.
+ *
+ * It is here because two layers need it and neither may import the other: the
+ * projection in `version/grouping.ts` and the retention policy in
+ * `store/retention.ts`, which the directory guard keeps below `version/`. Same
+ * reason `operationSummary` is here. It was written out twice, in different
+ * words that happened to agree.
+ */
+export function versionKindOfOperations(operations: WorkbookOperation[]): 'named' | 'auto' {
+  const explicit = operations.map(operation => operation.versionKind).find(kind => kind !== undefined)
+  if (explicit !== undefined) return explicit
+  const first = operations[0]
+  const last = operations.at(-1)
+  const deliberate = first?.versionSummary !== undefined || last?.versionSummary !== undefined
+    || first?.actor === 'agent'
+    || first?.restoredFromRevision !== undefined || last?.restoredFromRevision !== undefined
+  return deliberate ? 'named' : 'auto'
+}
+
+/**
+ * How many proposals a workbook keeps.
+ *
+ * One constant because the bound was applied in two layers — the manager when it
+ * created a proposal, and the store on every write — which is two policies for
+ * one array, and the layer that runs less often is the one that gets forgotten.
+ * The store owns it now, since it runs on every write.
+ */
+export const PROPOSAL_LOG_LIMIT = 20
+
+/**
+ * What `append_rows` says when its columns do not match the sheet's header.
+ *
+ * It lives here, not in `contract/mutations.ts` where the check is made, because
+ * the canvas applier raises the same error and `mutations.ts` imports
+ * `node:crypto` — the moment a browser-bundled module reached it, esbuild failed
+ * on a built-in Node module. This module is the one both halves already share.
+ */
+export const APPEND_HEADER_MISMATCH = '追加数据的列结构与现有表头不一致；若真实列头不在第 0 行，请用 headerRowIndex 指向它，或改用 workbook_edit 的 update_cells command'
+
+export type UniverMutationPersistence = 'ignore' | 'snapshot'
+
+/** Classify a Univer command before it is allowed to dirty a workbook. */
+export function classifyUniverMutation(commandId: string): UniverMutationPersistence {
+  // Three rules, in order, each written as its own statement.
+  //
+  // It used to be two, the second of which read
+  // `A || B && !PERSISTED.has(id)`. `&&` binds tighter than `||`, so that was
+  // `A || (B && !has)`, not `(A || B) && !has` — and since the last line is an
+  // allow-list, the `B && !has` half could never change an answer. It is still
+  // unreachable today (no `sheet.operation.*` id is in the allow-list), but it
+  // would have flipped the moment one was added, in a file whose whole purpose
+  // is to say which commands may dirty a workbook.
+  if (NON_PERSISTED_MUTATION_IDS.has(commandId)
+    || NON_PERSISTED_MUTATION_PREFIXES.some(prefix => commandId.startsWith(prefix))) return 'ignore'
+  // The `sheet.operation.*` namespace is view state — selections, scrolling,
+  // panel visibility. It is ignored *whatever* the allow-list later says, which
+  // is what the accidental `A ||` did and what is meant here.
+  if (commandId.startsWith('sheet.operation.')) return 'ignore'
+  // Everything else is durable only with an explicit contract. Unknown commands
+  // are ignored on purpose: treating a new Univer command as a save candidate is
+  // how a navigation keystroke marks a workbook dirty.
+  return PERSISTED_MUTATION_IDS.has(commandId) ? 'snapshot' : 'ignore'
+}
+
+/** Return whether a Univer mutation represents durable workbook state. */
+export function shouldPersistUniverMutation(commandId: string): boolean {
+  return classifyUniverMutation(commandId) !== 'ignore'
+}
+
+/** Expand a persisted operation into the ordered steps of one Version. A
+ * normal operation is one step; a batch keeps each child visible for history
+ * and replay without introducing a second persistence model. */
+export function workbookOperationSteps(operation: WorkbookOperation): WorkbookOperation[] {
+  if (operation.type !== 'batch') return [operation]
+  return (operation.payload.operations ?? []).map((child, index) => ({
+    opId: `${operation.opId}:${index + 1}`,
+    workbookId: operation.workbookId,
+    revision: operation.revision,
+    parentRevision: operation.parentRevision,
+    baseRevision: operation.baseRevision,
+    versionId: operation.versionId,
+    versionStatus: operation.versionStatus,
+    versionSummary: operation.versionSummary,
+    versionKind: operation.versionKind,
+    stepSummary: operation.stepSummary,
+    versionIntent: operation.versionIntent,
+    agentRunId: operation.agentRunId,
+    lineage: operation.lineage,
+    restoredFromRevision: operation.restoredFromRevision,
+    actor: operation.actor,
+    type: child.type,
+    timestamp: operation.timestamp,
+    payload: child.payload,
+  }))
+}
+
+export function operationSummary(operation: WorkbookOperation): string {
+  // A derived summary wins: the server knows what a generic operation changed
+  // (see `describeSnapshotReplace`). This used to exist twice — here and in
+  // `index.ts` — under a comment asking the two copies to stay in step.
+  if (operation.stepSummary !== undefined) return operation.stepSummary
+  const payload = operation.payload
+  switch (operation.type) {
+    case 'update_cells': return `更新 ${payload.cells?.length ?? 0} 个单元格`
+    case 'append_rows': return `追加 ${payload.rows?.length ?? 0} 行`
+    case 'set_hyperlink': return '设置超链接'
+    case 'remove_hyperlink': return '移除超链接'
+    case 'create_sheet': return `新增 sheet${payload.name === undefined ? '' : `：${payload.name}`}`
+    case 'delete_sheet': return '删除 sheet'
+    case 'rename_sheet': return `重命名 sheet${payload.name === undefined ? '' : `：${payload.name}`}`
+    case 'batch': return `批量操作（${payload.operations?.length ?? 0} 个 step）`
+    // Only pre-v3.1 records reach this: their payload was compacted away, so
+    // the change they made can no longer be derived. Say so, instead of a
+    // neutral label that reads like a normal save.
+    case 'snapshot_replace': return '保存整表内容（旧记录）'
+    default: return operation.type
+  }
+}

package/src/contract/snapshots.ts

@@ -0,0 +1,383 @@
+/**
+ * Snapshot vocabulary: the workbook snapshot shape, the matrix tools, and the
+ * one range reader (docs/issue/0022 P0).
+ *
+ * The readers here are pure functions of their arguments. The two **accessors**
+ * are not, and the distinction is worth stating because the module used to claim
+ * otherwise:
+ *
+ *   - `asWorkbookSnapshot` fills in a missing `sheetOrder` by writing it into the
+ *     object it was handed. That is how a caller's `payload.snapshot` could be
+ *     modified as a side effect of reading it, which is what made a stored
+ *     operation's payload accumulate later revisions. `applyWorkbookOperation`
+ *     now clones before returning, so the write lands on a copy — but this
+ *     function still writes to its argument, and a caller must not assume
+ *     otherwise.
+ *   - `resolveSheet` materializes `cellData` on the sheet it returns. That is
+ *     load-bearing, not incidental: writers mutate the returned sheet and expect
+ *     the change to land in the snapshot, so handing back a copy would silently
+ *     drop every edit.
+ *
+ * `cloneSnapshot` is the point of the move: it existed twice — once in the model
+ * layer and once again inside `client/SheetPanel.tsx` — which is exactly the
+ * drift a contract module exists to prevent.
+ */
+import {
+  SHEET_MAX_COLUMNS,
+  SHEET_MAX_PHYSICAL_ROWS,
+  SHEET_MAX_ROWS,
+  type SheetColumn,
+  type SheetSchema,
+  type WorkbookCellStyle,
+  type WorkbookCellValue,
+  type WorkbookRange,
+} from '../types.ts'
+
+/**
+ * The snapshot shape. It is declared here rather than in `types.ts` because it
+ * is the *input* of these functions and of nothing else on the wire; the
+ * tool-facing types stay in `types.ts`.
+ */
+/**
+ * The font family a blank sheet is created with.
+ *
+ * It lives in the contract because it is part of the stored snapshot's default
+ * style: the model, the xlsx reader and the engine all have to agree on it.
+ * Before the 0022 refactor it lived in the engine's font module, which made the
+ * model layer import *upward* into the engine (docs/issue/0022 §2).
+ */
+export const DEFAULT_SHEET_FONT_FAMILY = 'PingFang SC'
+
+/**
+ * The grid a new sheet starts with.
+ *
+ * One constant because *two* layers create sheets — the snapshot mutator and the
+ * Univer canvas — and a sheet's declared extent has to match the grid the user
+ * is looking at. It was written out as `1000` and `26` in seven places across
+ * five files, which is how the two drift apart without anyone editing either
+ * number. It is also a *starting* size, not a read limit: writes grow the sheet
+ * (`SHEET_MAX_ROWS` is the ceiling), and reads take the range they are given.
+ */
+export const DEFAULT_SHEET_ROWS = 1000
+export const DEFAULT_SHEET_COLUMNS = 26
+
+export interface WorkbookSnapshot {
+  sheetOrder: string[]
+  sheets: Record<string, WorkbookSheet>
+  [key: string]: unknown
+}
+
+export interface WorkbookSheet {
+  id: string
+  name: string
+  rowCount: number
+  columnCount: number
+  cellData: Record<string, Record<string, StoredCell>>
+  [key: string]: unknown
+}
+
+export interface StoredCell {
+  v?: unknown
+  f?: unknown
+  [key: string]: unknown
+}
+
+/**
+ * Deterministic JSON, so two equal values serialize identically.
+ *
+ * Object keys are sorted, which `JSON.stringify` does not do: it follows
+ * insertion order, so two snapshots holding the same content in a different
+ * order would compare unequal. Used for content hashes and for deciding whether
+ * a merge actually changed anything.
+ *
+ * It lived in the model layer *and* in the browser's merge code, byte for byte.
+ */
+export function stableJson(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`
+}
+
+/** Deep copy through JSON; snapshots are plain JSON by construction. */
+export function cloneSnapshot<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}
+
+/**
+ * Narrow `value` to a snapshot, defaulting `sheetOrder` from `sheets`.
+ *
+ * **Writes to its argument** when `sheetOrder` is absent (see the module note).
+ * Every caller here uses the return value, and `applyWorkbookOperation` clones,
+ * but a new caller should not read a snapshot *and* hand the same object
+ * somewhere else without knowing that.
+ */
+export function asWorkbookSnapshot(value: unknown): WorkbookSnapshot {
+  if (typeof value !== 'object' || value === null) throw new Error('工作簿快照格式无效')
+  const root = value as Partial<WorkbookSnapshot>
+  if (typeof root.sheets !== 'object' || root.sheets === null) throw new Error('工作簿缺少 sheets')
+  if (!Array.isArray(root.sheetOrder)) root.sheetOrder = Object.keys(root.sheets)
+  return root as WorkbookSnapshot
+}
+
+export function resolveSheet(root: WorkbookSnapshot, ref: string | undefined): WorkbookSheet {
+  const requested = ref?.trim()
+  const sheet = requested === undefined || requested.length === 0
+    ? root.sheets[root.sheetOrder[0] ?? '']
+    : root.sheets[requested] ?? Object.values(root.sheets).find(candidate => candidate.name === requested)
+  if (sheet === undefined) throw new Error(`sheet 不存在：${requested ?? '(第一个 sheet)'}`)
+  sheet.cellData ??= {}
+  return sheet
+}
+
+export function validateIndex(value: number, label: string): void {
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${label} 必须是大于等于 0 的整数`)
+}
+
+export function validateRange(range: WorkbookRange | undefined): asserts range is WorkbookRange {
+  if (range === undefined) throw new Error('必须提供 range')
+  validateIndex(range.startRow, 'range.startRow')
+  validateIndex(range.startColumn, 'range.startColumn')
+  validateIndex(range.endRow, 'range.endRow')
+  validateIndex(range.endColumn, 'range.endColumn')
+  if (range.endRow < range.startRow || range.endColumn < range.startColumn) throw new Error('range 结束位置不能小于开始位置')
+  if (range.endRow >= SHEET_MAX_PHYSICAL_ROWS) throw new Error(`range 行号超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`)
+  if (range.endColumn >= SHEET_MAX_COLUMNS) throw new Error(`range 列号超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  // No span check: `startRow`/`startColumn` are non-negative (above) and the end
+  // bounds are already inside the sheet, so the span cannot exceed it. Two
+  // checks that could never fire used to sit here, which is worse than noise —
+  // they read as a rule that something enforces.
+}
+
+/**
+ * A cell's formula in the one form this repository stores.
+ *
+ * `=SUM(A1:A2)` and `SUM(A1:A2)` are the same formula — the leading `=` is how a
+ * spreadsheet *displays* it, not part of it — and the whitespace around it is not
+ * part of it either. An input that reduces to nothing is not a formula at all.
+ *
+ * Four places wrote cells and each decided this for itself, so they disagreed:
+ * `update_cells` with `formula: '=SUM(A1:A2)'` stored `SUM(A1:A2)` in the
+ * snapshot and drew `=SUM(A1:A2)` on the canvas; `formula: ''` deleted the cell
+ * in the snapshot and left `{v:null,f:''}` on the canvas; `'='` was dropped by
+ * the snapshot and kept by the browser's merge. The snapshot and the canvas are
+ * two views of one workbook, so they cannot disagree about what is in it.
+ */
+export function normalizeCellFormula(formula: unknown): string | undefined {
+  if (typeof formula !== 'string') return undefined
+  const normalized = formula.trim().replace(/^=/, '')
+  return normalized.length === 0 ? undefined : normalized
+}
+
+export function toCellValue(cell: StoredCell | undefined): WorkbookCellValue | null {
+  if (cell === undefined) return null
+  if (typeof cell.e === 'string') return cell.e
+  if (cell.v === undefined || cell.v === null) return null
+  if (typeof cell.v === 'string' || typeof cell.v === 'number' || typeof cell.v === 'boolean') return cell.v
+  return String(cell.v)
+}
+
+export function cellType(value: WorkbookCellValue | null): string {
+  if (value === null) return 'blank'
+  if (typeof value === 'number') return 'number'
+  if (typeof value === 'boolean') return 'boolean'
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}(?:T|$)/.test(value)) return 'date'
+  return 'string'
+}
+
+/**
+ * The last row and column that actually carry something, or `-1` when the sheet
+ * is empty.
+ *
+ * A whole-sheet read needs this: the caller asking for "the sheet" must get the
+ * sheet, and the only way to know how big that is, is to look. A hard-coded
+ * window cannot know, and a window that is too small loses data silently.
+ *
+ * A cell that holds only a style is skipped — formatting an empty range writes
+ * style ids into every cell it covers, and those must not stretch a read.
+ */
+export function usedExtent(snapshot: unknown, sheetRef: string | undefined): { endRow: number; endColumn: number } {
+  const sheet = resolveSheet(asWorkbookSnapshot(snapshot), sheetRef)
+  let endRow = -1
+  let endColumn = -1
+  for (const [rowKey, line] of Object.entries(sheet.cellData ?? {})) {
+    const row = Number(rowKey)
+    if (!Number.isInteger(row) || row < 0) continue
+    let rowHasContent = false
+    for (const [columnKey, cell] of Object.entries(line ?? {})) {
+      const column = Number(columnKey)
+      if (!Number.isInteger(column) || column < 0) continue
+      const hasValue = toCellValue(cell) !== null
+      const hasFormula = typeof cell?.f === 'string' && cell.f !== ''
+      if (!hasValue && !hasFormula) continue
+      endColumn = Math.max(endColumn, column)
+      rowHasContent = true
+    }
+    if (rowHasContent) endRow = Math.max(endRow, row)
+  }
+  return { endRow, endColumn }
+}
+
+/**
+ * A style object out of a snapshot, narrowed to a plain record.
+ *
+ * Both storage shapes are real and both are read here: the browser's Univer
+ * residency keeps the object in the workbook's `styles` map and writes only its
+ * id onto the cell, while `format_cells` on the host writes the object inline.
+ * A resolver that knew one shape would silently drop the other's formatting.
+ */
+function styleRecord(value: unknown): WorkbookCellStyle {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {}
+  return { ...(value as WorkbookCellStyle) }
+}
+
+/**
+ * The style a cell actually paints with: the sheet's default under the cell's
+ * own, field by field.
+ *
+ * The sheet default is load-bearing, not decoration. `DEFAULT_SHEET_FONT_FAMILY`
+ * lives in every sheet's `defaultStyle` and is the **only** place a font family
+ * is recorded for a cell the user never formatted — a reader that skipped it
+ * would report "no font" for most of a sheet, which is how the Sheet Block
+ * preview could not show the font the workbook is actually set in.
+ *
+ * `null` means there is nothing to paint, so the wire carries a compact matrix
+ * instead of an object per empty cell.
+ */
+export function effectiveCellStyle(root: WorkbookSnapshot, sheet: WorkbookSheet, cell: StoredCell | undefined): WorkbookCellStyle | null {
+  const inline = cell === undefined ? {} : styleRecord(cell.s)
+  const named = typeof cell?.s === 'string' ? styleRecord((root.styles as Record<string, unknown> | undefined)?.[cell.s]) : {}
+  const merged = { ...styleRecord(sheet.defaultStyle), ...named, ...inline }
+  return Object.keys(merged).length === 0 ? null : merged
+}
+
+export function readWorkbookRange(snapshot: unknown, sheetRef: string, range: WorkbookRange, options: { styles?: boolean } = {}): {
+  sheetId: string
+  sheetName: string
+  range: WorkbookRange
+  values: Array<Array<WorkbookCellValue | null>>
+  formulas: Array<Array<string | null>>
+  cells: Array<Array<{ value: WorkbookCellValue | null; formula: string | null; type: string; calculation?: 'cached' | 'unavailable'; error?: string }>>
+  /**
+   * The effective style of every cell in `values`, when the caller asked for it.
+   *
+   * Opt-in, because the two readers of this range want different things: the SQL
+   * loader materializes values as a relation and would pay for a second matrix
+   * it never reads, while the Sheet Block preview exists to show the range the
+   * way the sheet draws it.
+   */
+  styles?: Array<Array<WorkbookCellStyle | null>>
+} {
+  const root = asWorkbookSnapshot(snapshot)
+  const sheet = resolveSheet(root, sheetRef)
+  validateRange(range)
+  const withStyles = options.styles === true
+  const values: Array<Array<WorkbookCellValue | null>> = []
+  const formulas: Array<Array<string | null>> = []
+  const cells: Array<Array<{ value: WorkbookCellValue | null; formula: string | null; type: string; calculation?: 'cached' | 'unavailable'; error?: string }>> = []
+  const styles: Array<Array<WorkbookCellStyle | null>> = []
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const line: Array<WorkbookCellValue | null> = []
+    const formulaLine: Array<string | null> = []
+    const cellLine: Array<{ value: WorkbookCellValue | null; formula: string | null; type: string; calculation?: 'cached' | 'unavailable'; error?: string }> = []
+    const styleLine: Array<WorkbookCellStyle | null> = []
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+      const cell = sheet.cellData[String(row)]?.[String(column)]
+      const value = toCellValue(cell)
+      const formula = typeof cell?.f === 'string' ? cell.f : null
+      line.push(value)
+      formulaLine.push(formula)
+      cellLine.push({
+        value,
+        formula,
+        type: formula !== null ? 'formula' : cellType(value),
+        ...(formula === null ? {} : { calculation: value === null ? 'unavailable' as const : 'cached' as const }),
+        ...(typeof value === 'string' && value.startsWith('#') ? { error: value } : {}),
+      })
+      if (withStyles) styleLine.push(effectiveCellStyle(root, sheet, cell))
+    }
+    values.push(line)
+    formulas.push(formulaLine)
+    cells.push(cellLine)
+    if (withStyles) styles.push(styleLine)
+  }
+  return {
+    sheetId: sheet.id,
+    sheetName: sheet.name,
+    range,
+    values,
+    formulas,
+    cells,
+    ...(withStyles ? { styles } : {}),
+  }
+}
+
+/**
+ * Return original sheet row indexes that are duplicates within a rectangular
+ * range. This follows Excel's default behavior: compare the selected columns,
+ * keep the first occurrence, and leave the header untouched when requested.
+ */
+export function findDuplicateRows(
+  values: ReadonlyArray<ReadonlyArray<unknown>>,
+  range: WorkbookRange,
+  columns?: readonly number[],
+  hasHeader = false,
+  keep: 'first' | 'last' = 'first',
+): number[] {
+  const selectedColumns = columns === undefined || columns.length === 0
+    ? Array.from({ length: range.endColumn - range.startColumn + 1 }, (_value, index) => range.startColumn + index)
+    : [...new Set(columns)]
+  for (const column of selectedColumns) {
+    if (!Number.isInteger(column) || column < range.startColumn || column > range.endColumn) {
+      throw new Error('remove_duplicates 的 columns 必须位于 range 内')
+    }
+  }
+  if (keep !== 'first' && keep !== 'last') throw new Error('remove_duplicates.keep 必须是 first 或 last')
+
+  const duplicateRows: number[] = []
+  const seen = new Set<string>()
+  const rowIndexes = Array.from({ length: values.length }, (_value, index) => index)
+  if (keep === 'last') rowIndexes.reverse()
+  for (const offset of rowIndexes) {
+    if (hasHeader && offset === 0) continue
+    const row = values[offset] ?? []
+    const key = JSON.stringify(selectedColumns.map(column => canonicalValue(row[column - range.startColumn])))
+    if (seen.has(key)) duplicateRows.push(range.startRow + offset)
+    else seen.add(key)
+  }
+  return duplicateRows.sort((left, right) => left - right)
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'number' && Number.isNaN(value)) return 'NaN'
+  if (typeof value === 'object') return JSON.stringify(value)
+  return value
+}
+
+export function isSheetSchema(value: unknown): value is SheetSchema {
+  if (typeof value !== 'object' || value === null) return false
+  const schema = value as Partial<SheetSchema>
+  if (!Number.isInteger(schema.version) || !Array.isArray(schema.columns) || schema.columns.length === 0 || schema.columns.length > SHEET_MAX_COLUMNS
+    || !Number.isInteger(schema.rowCount) || (schema.rowCount as number) < 0 || (schema.rowCount as number) > SHEET_MAX_ROWS
+    || typeof schema.updatedAt !== 'string') return false
+  const keys = new Set<string>()
+  return schema.columns.every(column => {
+    if (typeof column !== 'object' || column === null) return false
+    const candidate = column as Partial<SheetColumn>
+    if (typeof candidate.key !== 'string' || !/^[A-Za-z0-9_]+$/.test(candidate.key) || keys.has(candidate.key)
+      || typeof candidate.label !== 'string' || candidate.label.length === 0
+      || !['string', 'number', 'boolean', 'date', 'currency'].includes(candidate.type ?? '')) return false
+    keys.add(candidate.key)
+    return true
+  })
+}
+
+/** Force a snapshot's `name` field to the workbook's user-facing name.
+ * Both the read and the write path need it, which is why it is vocabulary
+ * rather than a store helper. */
+
+export function normalizeSnapshotName(snapshot: unknown, name: string): unknown {
+  if (typeof snapshot !== 'object' || snapshot === null) return snapshot
+  return { ...(snapshot as Record<string, unknown>), name }
+}