Checkpoint writer: stop discarding edit history #38

New issue

Closed

opened 2026-09-21 18:02:32 +01:00 by cruelacid · 1 comment

cruelacid commented

2026-09-21 18:02:32 +01:00

Owner

Part of #37.

What Relay does

Edit history is the single item on Relay's Planned list (roadmap, read 21 Sep
2026) — committed but unshipped. Their closest shipped substitute is
relay-git-sync, a Premium-tier Docker service that writes timestamped Git
commits.

What we do today

We retain nothing. packages/server/src/doc-store.ts:190, inside
putSnapshot:

DELETE FROM doc_updates WHERE doc_name = ? AND seq <= ?

and doc_snapshots keeps exactly one row per document
(ON CONFLICT(doc_name) DO UPDATE). Compaction fires at
COMPACT_AFTER_UPDATES = 500 (ws-server.ts:926), so once a document passes
that threshold its history is gone irreversibly.

Why this is urgent rather than merely wanted

The plugin is live in the community store and accumulating downloads. Every
day it runs without this, real users' edit history is discarded and cannot be
recovered later. CLAUDE.md's central principle — a user's writing is the only
thing here that cannot be reconstructed — makes this closer to a defect than a
feature gap.

Ship this first, and alone if anything slips.

What changes

Client-written checkpoints into a new doc_checkpoints table that compaction
never touches. MessageType 19 is the next free number
(packages/shared/src/index.ts; 18 is highest in use, and 2 is retired with a
comment explaining that numbers are never reused).

Checkpoints rather than retaining every update: storage is bounded, and "restore
this note to how it was yesterday" is what people actually want. Retaining
everything grows with edit volume, which is exactly what quotas meter, and would
need a terms clause.

Split deliberately: this issue is the writer only. The version browser is a
separate issue in Phase 19 — a checkpoint not written today cannot be browsed in
June, which is the whole argument for doing the writer now and the UI later.

Risk

risk:additive. A new table and a new message type; older clients neither send
nor read them. No wire-format break.

Verification

A document taken past 500 updates still has recoverable earlier states.
Mutation-check both directions (CLAUDE.md): invert the retention rule and
confirm the test fails.
Storage growth is measured against quota accounting, not assumed bounded.

Part of #37. ## What Relay does Edit history is the single item on Relay's **Planned** list (roadmap, read 21 Sep 2026) — committed but unshipped. Their closest shipped substitute is `relay-git-sync`, a Premium-tier Docker service that writes timestamped Git commits. ## What we do today **We retain nothing.** `packages/server/src/doc-store.ts:190`, inside `putSnapshot`: ```sql DELETE FROM doc_updates WHERE doc_name = ? AND seq <= ? ``` and `doc_snapshots` keeps exactly one row per document (`ON CONFLICT(doc_name) DO UPDATE`). Compaction fires at `COMPACT_AFTER_UPDATES = 500` (`ws-server.ts:926`), so once a document passes that threshold its history is gone irreversibly. ## Why this is urgent rather than merely wanted The plugin is **live in the community store and accumulating downloads**. Every day it runs without this, real users' edit history is discarded and cannot be recovered later. `CLAUDE.md`'s central principle — a user's writing is the only thing here that cannot be reconstructed — makes this closer to a defect than a feature gap. **Ship this first, and alone if anything slips.** ## What changes Client-written checkpoints into a new `doc_checkpoints` table that compaction never touches. `MessageType` 19 is the next free number (`packages/shared/src/index.ts`; 18 is highest in use, and 2 is retired with a comment explaining that numbers are never reused). Checkpoints rather than retaining every update: storage is bounded, and "restore this note to how it was yesterday" is what people actually want. Retaining everything grows with edit volume, which is exactly what quotas meter, and would need a terms clause. **Split deliberately:** this issue is the *writer* only. The version browser is a separate issue in Phase 19 — a checkpoint not written today cannot be browsed in June, which is the whole argument for doing the writer now and the UI later. ## Risk `risk:additive`. A new table and a new message type; older clients neither send nor read them. No wire-format break. ## Verification - A document taken past 500 updates still has recoverable earlier states. - **Mutation-check both directions** (`CLAUDE.md`): invert the retention rule and confirm the test fails. - Storage growth is measured against quota accounting, not assumed bounded.

cruelacid added this to the Phase 15 - Retention and enrolment milestone

2026-09-21 18:02:32 +01:00

cruelacid added the

labels

2026-09-21 18:02:32 +01:00

cruelacid referenced this issue

2026-09-21 18:05:10 +01:00

Version browser over retained checkpoints #58