Paper Versioning: Restore, Diff, and Collaborate Safely

We added versioning for Paper documents. Every save creates a small, encrypted snapshot so you can preview diffs, restore previous states, and track changes over time, without exposing your document text to our servers.

What versioning does

Each save captures only the blocks that changed, keeping versions small and fast to produce. You can open version history, preview a version locally, and restore it to become the current document. Versions appear as timestamps and optional notes; content remains encrypted until you fetch and decrypt it.

How it works (practical)

• Papers are lists of blocks. Each block is hashed with SHA-256 to detect changes.
• When you save, the client computes block hashes, encrypts any new or changed blocks, and uploads just those encrypted blobs plus a small version manifest.
• The version manifest lists blocks, their hashes, salts, and nonces. Only the manifest and blobs are stored by the server; everything is encrypted.
• Because unchanged blocks are reused by reference, storage stays efficient even with many versions.

Restore and preview

• Preview a past version in the UI without making it live. The preview decrypts locally.
• Restore replaces the current document with the selected version by reusing block references and fetching any missing blocks.
• Versions are created automatically and semantically. Manual saves, page close, document open, share actions, and other meaningful events create useful checkpoints. Block-level diffing is coming in a future release.

Privacy, integrity, and performance

• All version manifests and block blobs are encrypted client-side. The server stores ciphertext only.
• Block hashes (SHA-256) let clients verify integrity after download. If a hash mismatch appears, the client rejects the block.
• Because we only upload changed blocks, the zero-knowledge experience remains fast and responsive even with heavy crypto under the hood.

Under the hood: immutable block-based architecture

Paper versioning is built on a highly efficient immutable block-based model. Instead of saving a new full copy on every save, we treat a document as a collection of immutable blocks tied together by a Manifest.

1) The Manifest (the source of truth)

• Every Paper has a Manifest (stored with chunk_index = 0). The Manifest is a lightweight JSON map for the document.
• The Manifest contains encryption metadata (IV and salt), and a block map, an ordered list of chunk IDs (pointers) that make up the document.

Example manifest:

1
{
2
  "manifest_id": "man_01F...",
3
  "paper_id": "paper_01F...",
4
  "created_at": "2026-01-18T12:00:00Z",
5
  "iv": "BASE64_IV",
6
  "salt": "BASE64_SALT",
7
  "blocks": [
8
    { "id": "chunk_01F...", "hash": "HEX_SHA256" },
9
    { "id": "chunk_02F...", "hash": "HEX_SHA256" }
10
  ]
11
}

2) Immutable saves

• When you update a Paper, we never overwrite old data. New or edited blocks are uploaded as new objects (chunks) in storage.
• Every save produces a new Manifest stored at a unique path (for example: chunks/{paper-id}/{manifest-uuid}). The previous manifest remains archived.
• The previous manifest reference in the active index is set to NULL, but the data remains in storage for versioning and recovery.

3) Version pointers and efficiency (zero-copy)

• A version is simply a pointer to a specific Manifest. Manifests are immutable and can share blocks by reference.
• This structural sharing means many versions can coexist without duplicating unchanged blocks. Storage stays efficient even with hundreds of versions.
• Manual versions are permanent snapshots you create. Auto-versions are created by the system based on semantic events.

4) Smart throttling and retention

• To avoid excessive churn while you type, auto-versions are throttled to once every 10 minutes per Paper.
• Versions are retained per plan: Free 7 days, Plus 60 days, Pro 180 days, Unlimited 365 days. Old versions are auto-cleaned according to your plan.

5) Restoration process

• When you restore a version the system fetches that Manifest and re-indexes the chunks table so the chosen Manifest becomes active (chunk_index = 0).
• The editor reloads and the document is reverted instantly without copying large amounts of data.

In short: Paper uses immutable manifests and block-level structural sharing. Versioning is fast, storage-efficient, and keeps your data zero-knowledge private.

Quick usage

1. Open a Paper and choose Version history.
2. Click a timestamp to preview or select Restore to make a previous version current.
3. Block-level diffs are coming soon; for now preview any version locally before restoring.