# Document Versioning (fact-closure snapshots) Give every leaflet a version history: **explicitly created, named versions**, a read-only viewer for any past version, and restore. A version is a **snapshot of the document's fact closure** — the same raw facts the editor already reads — stored in a side table. Automatic/periodic snapshots are deliberately **out of scope for now**. The design keeps the door open for them (see "Adding automatic cuts later"), but nothing in v1 observes the edit stream. ## Overview - A leaflet today is `permission_token → permission_token_rights → entity_set → entities → facts`, with `permission_tokens.root_entity` anchoring the recursive closure walk (`get_facts(root)`). All document content — blocks, ordering, images, theme, pages — is facts. - **Nothing is currently recoverable.** Facts are mutated in place and hard-deleted on retract; Replicache mutations are applied and discarded; every `Y.Doc` runs with GC on. Versioning must introduce its own storage — no history can be reconstructed retroactively. - A **version** = the serialized fact array returned by `get_facts(root)` at a point in time, stored as one row in `document_versions` as plain jsonb. `snapshot_path` is the escape hatch for offloading oversized snapshots to a Supabase storage bucket later. - Versions are cut by a **server action, on an explicit user action** — never from the push path. Push serializes on a per-token advisory lock (`pg_advisory_xact_lock` in `app/api/rpc/[command]/push.ts`) and flush is the hottest path in the app; with explicit-only cuts, versioning touches neither. Nothing is added to the write path at all. - **Viewing is nearly free**: `ReplicacheProvider` already supports `initialFactsOnly` + `disablePull`, which constructs no Replicache client, no realtime channel, and no yjs provider — every reader hook falls back to a static fact array. The version viewer reuses the editor's own component tree, not a parallel renderer. - **Blobs** get deferred deletion + a reference index, replacing today's synchronous `storage.remove()` in `removeBlock`/`removeGalleryImage`. - Storing **raw facts** (not the published-record format) is load-bearing: it's what makes both the viewer and restore possible. See "Why raw facts" below. ## Constraints discovered in the codebase These drove every decision here; each is a real finding, not an assumption. 1. **No server-side history of any kind exists.** Flush does `onConflictDoUpdate` on `facts` (`src/replicache/cachedServerMutationContext.ts:293-311`); retract issues real `DELETE`s, including of inbound reference facts pointing at a deleted entity (`:327-345`). No mutation log, no tombstones, no history tables. `facts.updated_at` and `facts.version` exist but are **vestigial** — no trigger and no writer touches them; the real row version used by CVR sync is Postgres `xmin`. 2. **The push path is latency-critical and serialized per permission token.** Everything added to flush lands inside `pg_advisory_xact_lock` on a 32-bit hash of `token.id` (`app/api/rpc/[command]/push.ts:96-100`) — the same `tokenHash` the AI routes reuse; any server-side write to a live leaflet should take the identical lock. Note it's per *token*, not per leaflet: two tokens over the same entity set don't serialize against each other. 3. **`block/text` facts hold full encoded ydoc state**, base64'd in jsonb, re-asserted on a 300ms debounce (`components/Blocks/TextBlock/useCollabText.tsx`). These dominate snapshot bytes. 4. **Yjs GC is on everywhere** — all 22 `new Y.Doc(` call sites use the default constructor. Deleted text content is *gone* from stored encodings; prior revisions are not reconstructible from a `block/text` value. 5. **You cannot restore text by writing an old `block/text` value back.** Yjs merge is monotone: the old encoding is a subset of the current one, so the flush-time `Y.mergeUpdates` (`cachedServerMutationContext.ts:269-291`) and every live client would merge it with newer state and the restore would silently no-op. A fresh ydoc doesn't fix this either — live clients apply pulled values into their *existing* in-memory doc via `Y.applyUpdate`, so an unrelated doc's content union-merges with (duplicates into) the current text. Restoring text means applying a **compensating update**: new ops on top of the *current* encoding that transform it into the old content, so the result is a superset of the current state and merges cleanly everywhere. `editYjsText` (`app/api/ai/lib.tsx:512-573`) already does exactly this shape server-side. See "Restore". 6. **The read path already has a no-Replicache branch, exercised in production.** `useEntity`, `useBlocks`, `useCanvasBlocksWithType`, `usePageFootnotes` and the theme hooks all compute a fallback from `initialFacts` via `scanIndexLocal` / `getBlocksWithTypeLocal` (`src/replicache/utils.ts`, `src/replicache/getBlocks.ts`), and `useSubscribe` no-ops on a null `rep`. `app/(app)/(identity)/(home-pages)/(writer)/home/LeafletList/LeafletCardReplicache.tsx` renders real blocks, canvases, and themes this way today. 7. **Read-only rendering is already a first-class mode.** `useEntitySetContext().permissions.write` (`components/EntitySetProvider.tsx`) gates ~40 editing affordances, and `components/Blocks/TextBlock/index.tsx:57-78` renders `RenderedTextBlock` (pure `useEntity` + `RenderYJSFragment`, no ProseMirror) when write permission is absent, the block is `preview`, or the client is schema-stale. 8. **Two existing primitives to reuse for restore:** `src/utils/copyLeafletContents.ts` (entity-id remapping + image storage copy — `actions/createNewLeafletFromTemplate.ts` is a thin wrapper over it) and `src/utils/createLeaflet.ts` (whole leaflet created in one CTE statement with pre-generated uuids and an optional caller-supplied `tailCte`). 9. **Image blobs are immutable but eagerly deleted.** `src/utils/addImage.ts` names each upload with a fresh v7 uuid and bakes the full public URL into the fact's `data.src` — replacing an image always writes a new file, never overwrites. But `removeBlock` (`src/replicache/mutations.ts:514`), `removeGalleryImage` (`:874`), and `app/api/ai/blocks/[blockId]/route.ts:70` call `storage.remove()` synchronously the moment a block is deleted. Meanwhile `actions/deleteLeaflet.ts` never touches storage, so whole-leaflet deletion already leaks blobs permanently. 10. **Query-plan rule applies to the versions list.** "Newest N versions for this leaflet" is exactly the `.order()` + `.limit()` + row-restricting embed shape that `npm run check-query-plans` flags. Filter on `document_versions`' own indexed columns or use a fenced SQL function. 11. **Scale.** Typical docs are tens to low-hundreds of facts; the perf stress fixture (3000 blocks, `perf/docs.json`) is ~9,000–12,000 facts. Snapshots of ordinary docs are tens–hundreds of KB, and successive versions are highly similar. 12. **`get_facts` returns bare fact rows, in nondeterministic order.** It's `RETURNS SETOF facts` — a recursive CTE with hash-deduped `UNION` and no `ORDER BY` — so sort by fact id before hashing the closure. It carries no `entities` rows, and `facts.entity → entities.id` is `ON DELETE CASCADE`: restoring a deleted block means re-creating its `entities` row first (its id is in the snapshot's facts; its `set` comes from `permission_token_rights.entity_set`, since every entity in a leaflet shares the one set). Entities with zero facts of their own (bare reference targets) never appear in the closure at all — `copyLeafletContents.ts:41-43` handles this same blind spot. Also, the generated `database.types.ts` types `get_facts` without `author_did` (the column postdates the types block), so a serializer typed off it silently drops authorship — hand-fix the types. ## Why raw facts, and not the alternatives **Snapshot raw facts, not `processBlocksToPages` output.** The published-record format (`src/utils/factsToPagesRecord.ts`) is lossy and has **no reverse path** — nothing in the codebase converts records back to facts. A record-based version could be viewed but never restored, and viewing it would go through the *published* renderer (`PostContent.tsx`), a parallel component tree that must be kept in sync with the editor by hand (the whole reason the `mirror-editor-block-styles` skill exists). Raw facts give a pixel-identical view for free and keep restore possible. Alternatives considered and rejected: | Approach | Why not | |---|---| | **Append-only fact history** (Datomic-style assert/retract rows, or Postgres temporal triggers) | Elegant fit for the EAV model, poor fit for the write path: doubles work *inside* the advisory lock on every fact write, and the 300ms text debounce fills history with near-duplicate multi-KB ydoc encodings unless text is special-cased — at which point you've built snapshots anyway for the attribute that holds all the bytes. Extra rows in `facts` would also bloat `facts_entity_idx` and the partial reference index the recursive closure walk depends on. Worth revisiting only if fine-grained per-fact attribution becomes a hard requirement. | | **Mutation log / event sourcing** | Worst fit. Replay requires mutator semantics frozen forever (ours evolve, and push already silently skips errored mutations). And since `assertFact` carries full fact values — including full ydoc states — the "log" degenerates into fact history with extra machinery. Google Docs makes this work because their ops are tiny OT deltas; ours aren't. | | **Yjs-native snapshots** (`Y.snapshot` + `gc: false`) | The only route to char-level attributed diffs, but requires `gc: false` for each doc's whole life (deleted content retained forever, unbounded growth), the y-prosemirror tooling is officially experimental with known binding bugs, and it covers *only text* — block structure, ordering, images, and theme live in facts. Industry survey found essentially nobody runs this at scale: Liveblocks, PartyKit, AFFiNE, and Evernote all store periodic full encodings instead. At most a future add-on for text diff views. | | **Content-addressed facts / structural sharing** (Dolt-style) | The right *upgrade path*, not the starting point. Store facts by content hash and let a version be a list of hashes, so unchanged facts are stored once across all versions. It retrofits cleanly onto this design without changing the read or restore paths — which is exactly why the version format should stay "an array of facts" rather than a derived rendering. Skip for v1; plain snapshots are cheap at our doc sizes. | ## Cut policy Versions are cut **only in response to a user action**. There is no timer, no edit-stream observer, and no background cutting job. - **Named**: the user saves a version, with a title. This is the whole feature in v1. - **Safety versions**, cut immediately before a **restore**. Restore is the one destructive operation here, and cutting first is what makes "restore = a new version on top, never rewind" true. Still user-triggered — it's part of the restore action, not a background policy. - Skip the cut if the closure hash is unchanged since the latest version, so repeated saves with no edits in between don't accumulate identical rows. Confluence is the closest precedent for explicit-only versioning: continuous autosave for durability, but a version is only cut on publish — specifically so a collaborative session doesn't produce hundreds of micro-versions. The broader industry pattern (Notion's 10-min/2-min-idle cadence, Figma's 30-min checkpoints, Tiptap's 30s-if-changed) all decouple user-visible versions from the durability layer, which is what we're doing too; we're just choosing the user as the trigger instead of a clock. **Consequences of explicit-only**, worth being clear-eyed about: - Users who never save a version get no history, and there is no recovery from an accidental deletion or a bad paste. Undo remains the only safety net for unsaved work, and it's client-side and in-memory (`src/undoManager.ts`) — lost on reload or any Replicache client rebuild. - Version volume is bounded by user behavior rather than by wall-clock, so **retention and thinning are not needed in v1**. Storage growth is self-limiting. - The blob-lifetime problem does not go away: an explicit version referencing a since-deleted image has exactly the same requirements as an automatic one. The blob work below is unchanged. ### Adding automatic cuts later If we do want them, the seam is small and this design doesn't foreclose it: flush marks the leaflet dirty, and a debounced Inngest job (keyed per leaflet, so an editing session coalesces into one cut) calls the same `cutVersion` with `kind: "auto"`. That would then bring retention/thinning with it. Everything else — schema, viewer, restore, blob GC — is already shaped to accept it. ## Expected behavior - A **Versions** entry in the editor's actions list opens a modal listing every saved version of the leaflet, newest first, each showing its name and the date it was saved. - From that modal the user can save a new version, giving it a name. Nothing is versioned unless they do. - A version can be **viewed** read-only at a stable URL, rendering exactly as the editor would have rendered it — same blocks, same canvas layout, same theme, same fonts — with all editing affordances absent. - While viewing a version, the header clearly says so — in the same place a publication draft is marked `DRAFT` — showing the version's name and date, plus a control to return to the current document. - A version can be **restored** in place (a safety version is cut first, as part of the restore) or **opened as a new leaflet** (a pure fork, zero risk to the original). - Restoring never truncates history: the pre-restore state remains viewable. - Images in old versions keep rendering as long as the version is retained, including images deleted from the live document. If a blob is genuinely gone, the block degrades to its thumbhash placeholder rather than a broken image. - Versions are immutable; the viewer page is indefinitely cacheable. ## Changes ### Schema - New `document_versions` table: `id uuid pk`, `token uuid → permission_tokens.id ON DELETE CASCADE`, `created_at timestamptz`, `kind text` (`named` | `pre_restore` — leave room for `auto`), `name text null`, `author_did text null`, `closure_hash text`, `snapshot jsonb null`, `snapshot_path text null` (future escape hatch: a Supabase storage object for oversized snapshots), `fact_count int`, `byte_size int`. Index on `(token, created_at desc)`. - Keying on `token` (not `root_entity`) is deliberate: the editor URL *is* the edit token, the modal is write-gated, and `deleteLeaflet` removes the `permission_tokens` row so versions cascade away with the doc. Accepted limitation: a doc's other tokens (e.g. view tokens over the same entity set) can't see versions cut via the edit token. - New `document_version_blob_refs`: `(version uuid → document_versions.id ON DELETE CASCADE, path text)`, indexed both ways. Populated at cut time from the closure's `image`-type facts. - New `blob_cleanup_queue`: `(path text pk, queued_at timestamptz)`. - Mirror all three in `drizzle/schema.ts` and hand-add the blocks to `supabase/database.types.ts` (wholesale regen breaks tsc — see the `generate-db-types` drift note). ### Cutting versions - `src/versioning/cutVersion.ts` (a plain lib, not a `"use server"` file — every exported async function in one of those is client-callable): `get_facts(root)` → **sort by fact id** (constraint 12: output order is planner-dependent) → hash → bail if unchanged → insert row → insert blob refs. Select `author_did` explicitly or fix the stale `get_facts` block in `database.types.ts` first, or the serializer drops it silently. - A thin server action in `actions/` wraps it, checks write permission on the token, resolves the session DID for `author_did`, and returns a `Result`. - **No changes to the push path, flush, or Inngest.** Versioning is entirely off the write path. - The client needs no Replicache mutation for this — versions aren't synced document state. A pending in-flight save can be reflected with local UI state; the versions list is fetched (SWR) rather than mirrored into Replicache. - One ordering caveat: the fact closure is read from Postgres, so a version saved mid-typing captures the last *pushed* state, not unflushed local edits (`block/text` persists on a 300ms debounce). Flush pending mutations client-side before invoking the action, or accept the small window. ### UI An entry in the editor's actions list opens a modal listing saved versions, with a control to save a new one. **The action entry.** The actions list is duplicated in two files and both need the entry: - Desktop: `LeafletSidebar` in `app/(app)/(editor)/[leaflet_id]/Sidebar.tsx` - Mobile: `LeafletFooter` in `app/(app)/(editor)/[leaflet_id]/Footer.tsx` Place it next to `` in both. Entries are not `MenuItem`s — each is a component rendering `ActionButton` (`components/ActionBar/ActionButton.tsx`, a `forwardRef` taking `icon` / `label` / `secondary` / `active`). Gate on `entity_set.permissions.write`, as both lists already do. ```jsx } label="Versions" />}> ``` Per CLAUDE.md, the trigger must be a real button component (never a raw `