How OpenChronology was built

#106 · Expire old data on a schedule and delete a range at once

2026-10-12T15:33:53Z CE

• timeline-app
• pull request

Closes #91. Timelines that keep growing, log timelines especially, can now keep only their recent past and free the storage that history used. Anything in a stretch of time can also be deleted at once. Guide: `docs/retention.md`. ## Retention ("keep only the last …") - Owners set it in **Sharing & settings**, or with `PATCH /api/timelines/ /settings {"retention": "1 year"}` (`null` keeps everything). - Periods use the timeline's own difference units from #73: `1 year`, `90 days`, `2 weeks`. - It must be at least an hour and at most 1,000 years. - It needs a calendar (Gregorian) time display, so the server knows what time it is in the timeline. - About once an hour (`server/retention.mjs`, started with the platform), each server process runs the job under a Postgres advisory lock, so only one runs it at a time. For each timeline with retention it: 1. **prunes saved history** from before the period, keeping: - the head revision; - the patch chain newer revisions are stored against, back to the nearest snapshot (revisions are immutable, so a patch can't be rewritten as a snapshot); - anything forks, pull requests or other timelines refer to, with its ancestry. This is what frees storage. 2. **deletes moments** older than the period, and durations that ended before it, as one ordinary save by the owner. Durations that followed a deleted moment keep its time; relationships of deleted entities go. Live viewers and history see it like any other change. - The settings page shows when retention last ran and how much it deleted (`retention_applied_at`, `retention_removed`). ## Deleting everything in a view - **"Delete everything in this view…"** in the timeline's context menu. It's offered when the view shows something. - **Timelines kept in the browser:** it says how many moments and durations go, and **one Undo** restores them all, through a new grouped undo entry. - **Server timelines (writers):** it deletes on the server at once, as one revision. Save other changes first. - Desktop SQLite files aren't covered. - `POST /api/timelines/ /delete-range {revision, lower, upper}`, both ends included, for writers and write-scoped API keys: - it deletes up to 200,000 moments per call, plus the durations wholly inside the range; - a stale revision gets a 409; - it returns `removed`, and `more: true` when a call stops at that limit. ## Notes - **Pruning keeps patch chains.** A timeline saving small patches only stores a full snapshot every 1,000 saves, or once its patches outweigh it. History newer than the last such snapshot stays even when it's older than the retention period. The docs explain this. - **Range deletion is a save.** It creates one revision, so the version before it stays restorable until retention prunes it. ## Tests - `test/retention-postgres.mjs`, a new CI step, uses a "now" two years ahead: - expiry removes the old moments, the old duration and the relationship, and keeps the crossing duration at its old start time; - history is pruned, every remaining revision still reads, and the owner's storage goes down; - a second run does nothing; - range deletion: writers allowed, strangers refused, a bad range gets 400 and a stale revision 409; - retention parsing: units, the minimum, owner-only setting, clearing it, and refusing a non-calendar timeline. - `test/range-delete-browser.mjs`, in the browser suite: a view's moments and inner duration are deleted, a duration reaching outside stays, and one Undo and Redo work. - `test/next-postgres.mjs` renders the owner's settings page with the retention section. - Menu assertions in the selection and summaries tests now include the new item. - Locally: - `npm test` (233 tests) passes; - the Chromium suite passes; - the retention, versioning, incremental, HTTP and Next.js Postgres tests pass.

Open #106 · Expire old data on a schedule and delete a range at once in the timeline