How OpenChronology was built

#396 · Docs match the code in a dozen places (#392)

2026-10-31T02:39:16Z CE

• timeline-app
• pull request

Fixes #392 Each item re-checked against current `main`; the docs now follow the code. **architecture.md** - Saving: the stale "full index rebuild; incremental writes are future work" sentence now points to incremental saves and saved history. - Rebuild threshold: a patch is rebuilt only past `max(64, n / 2)` changes (under 200,000 moments). - `oc_overview_v2` is named (with `oc_overview` as its wrapper). - `rasterize`: applied by `navigate` (gestures, fit duration, search result, shared view link), zoom destinations and every animation frame, and follow-latest; Fit all, the opening view and typed bounds stay exact. - Rebuild-save history comparison pages 20,000 keys at a time. - Copies are prepared later at 20,000 *rows* (source's own moment rows plus duration-tree rows, hidden included), also in administration.md. - Upgrading: `npm run migrate` starts history as rows (`startHistory`); a save starts it for any timeline still without it. - Viewport cache: levels are powers of two except when clamped to the 1.5·span/1024 minimum (very wide views); the last-drawn window stays while it overlaps the view. **PostgreSQL 10,001 candidates — docs fixed, code kept.** The walk is a recursive CTE, which PostgreSQL evaluates a tree level at a time; `LIMIT 10001` is what lets it stop early. An `ORDER BY` before the limit would read and sort every match in the window, defeating the cap (there's no index giving overlapping intervals in start order, and forks read through lineage). Start order of the candidates isn't something callers rely on: past the cap the count already reads "10,000+", the 256 kept are approximate either way, and they're returned in start order regardless. durations.md, the OpenAPI text, the store comment and the Rust comment now say SQLite's walk is in start order and PostgreSQL's isn't. **Other docs** - time-presentation.md: one label per tick, the heaviest text drawn with the combined weight (#241). - plugins.md: 64/16 MiB old/young generation, 16 MiB code range, 4 MiB stack; the last 1,000 results remembered, recompiled after a stopped worker. - log-import.md / administration.md: importer batches cap at 4,999. **Code-only leftovers** - Removed the unused `durationLanes` (and its test; `arrangeDurations` tests already check that overlapping bands never share a row). - Removed `'size'` from the marker kind type, since validation refuses it and nothing reads it. Also added `outline`, which validation accepts, to the OpenAPI marker enum. - `src/custom-time.ts`: the comment now says the server compiles plugin scripts in sandboxed workers but never runs them. **Disclosures**: each "Note on the documentation" now uses the past tense and records the fix in #392; `durationLanes` is noted as removed. No SQL changed (only comments), so no PostgreSQL tests were needed. `npm test`, typecheck, prettier and rustfmt pass. collaboration code and docs/collaboration.md are untouched (#395).

Open #396 · Docs match the code in a dozen places (#392) in the timeline