Private workbook version history

Sheet exposes five private history Actions. list_versions pages with cursor and bounded limit; get_version returns a bounded read-only historical preview; create_named_version creates a labeled checkpoint; restore_version restores selected content in place; and copy_version creates a separate workbook from an old version. Historical data may include cells removed from the current workbook, so every version Action has allow_in_public: false.

Ordinary Agent mutations already create mandatory automatic checkpoints; do not create a named version for every write. Use create_named_version only when the user explicitly asks. It needs no confirmation and supports optional expectedHeadVersionId plus idempotencyKey. Its registry drift policy is Strict, so a changed head or changed arguments must be reloaded and reconciled rather than silently accepted.

restore_version is the only Sheet Action requiring UserConfirm. It requires workbookId, versionId, and expectedHeadVersionId, also uses Strict drift protection, and supports an idempotency key. Restore first saves the current state as a pre-restore checkpoint, then overwrites the current workbook in place with the selected historical content. It does not make the workbook’s integer version go backward: successful restore advances current state, so reread the workbook and use the newly returned/current version as the next mutation’s baseVersion.

Prefer copy_version when the user wants to inspect or recover historical content without replacing the live workbook. It requires workbookId and versionId, creates a new workbook with fresh history, needs no confirmation, and uses Strict drift handling. Restore remains appropriate only when the user explicitly wants the current workbook changed. Registry schemas, canRestore-style runtime results, permissions, confirmation, and typed history errors are authoritative.

Related actions

arinova.sheet.list_versions, arinova.sheet.get_version, arinova.sheet.create_named_version, arinova.sheet.restore_version, arinova.sheet.copy_version

Also known as

workbook history, sheet version, restore workbook, named version, expectedHeadVersionId, pre restore checkpoint, copy version, 版本歷史

---

Machine-readable Markdown · Knowledge index