How OpenChronology was built

#192 · Richer comments, the SQL first (#177)

2026-10-17T03:05:17Z CE

• timeline-app
• pull request

Closes #177. Comments only: about 6,000 lines across 80 files, focused on the SQL as asked. Eight agents wrote them in parallel, each on one area, to shared rules: say why, not just what; be accurate; correct stale comments; change no code. ## The SQL - **`server/schema.sql`:** - **Header:** how `migrate.mjs` runs the file and why every statement can be run again. - **Tables and columns:** what each of the 58 tables stores and which modules read and write it, plus its non-obvious columns. - **Indexes:** the query each one serves, and why partial ones are partial. - **Functions:** each has a header covering purpose, arguments, result, algorithm, locking and cost, with step comments inside its body. That includes the functions generated from others: the versioned triggers, the `_at` readers and the `_lineage` walks. - **Upgrades:** each idempotent upgrade statement says what changed and why it's safe to run again. - **Generated copies:** some functions are generated by rewriting other functions' text, so no comment inside those bodies contains a string the rewriting searches for. A note above `oc_rewrite` warns future editors. - **SQL in the server:** `store.mjs`, the versioned index and history (`history`, `index-versions`, `incremental`, `avl`, `merge`, `versioning`…), accounts and security, moderation, administration, collaboration, standing, retention, plugins, the log receivers, and the request router. - **Each non-trivial query** says what it reads or changes and why: locks (`FOR UPDATE`, `SKIP LOCKED`, advisory locks), isolation levels, CTEs and recursive CTEs, `ON CONFLICT`, `RETURNING`, keyset paging, and the indexes it relies on. - **Functions:** every function has JSDoc. - **`http.mjs`:** says, for each route group, who may call it and what's checked first. - **SQLite in the desktop app (`native-store`):** the file format, every table and index, and the save transactions and viewport queries. `src-tauri` documents each native command. ## Elsewhere The editor modules and website components with the fewest comments now have JSDoc for every function and component, and notes on their non-obvious logic. ## Corrections - **Wrong or stale comments fixed:** for example, history no longer "writes a full snapshot periodically"; `durationDefinitions` skips legacy rows rather than converting them; a moderation comment claimed at most one case per target; a plugin lock was said to enforce the quota. - **References updated:** comments naming functions that no longer exist now name the current ones. - **Comments moved to the right function:** in `store.mjs`, `workspace.rs` and `hover-preview.ts`. ## How it was checked - **Code unchanged:** a script compared every changed file with `main` token by token, ignoring comments (and `--` lines inside SQL strings). All 80 are unchanged apart from comments. - **Schema checked in a real database:** the schema was loaded into a brand-new database twice. Every function (203, generated ones included), table (58) and index (133) it creates was compared with `main`'s, and they are identical apart from comments. - **Tests pass:** - 289 unit tests, typecheck and Prettier; - `cargo fmt --check`, and both crates' tests; - the 45-test database suite, plus the main database tests on that fresh database; - the 11 browser suites; - the offline edition's test. ## Bugs the agents found I'm not fixing code in this PR. The five I've confirmed are fixed in a separate PR; the rest are filed as an issue.

Open #192 · Richer comments, the SQL first (#177) in the timeline