OTO
concepts · from ARCHITECTURE.md at v0.6.1

The pending lane, the preview and watch mode

inboxwaiting
→
processingin a run
→
proposalsdrafted
→
candidateat the gates
→
livein the graph
The pending lane: every station a fact can be at, and a preview store that shows the graph as it would be.

Knowledge is visible the moment it is captured, labelled by where it stands, and never mixed with what is believed. curate/pending.py reads the stations on disk: files in inbox/, documents in processing/, every proposal under proposals/ merged the way curate add --dry-run would (on top of the open candidate, in file order, a refused proposal listed with its reason rather than dropped), and the candidate's changes against the live graph (new, changed, updated, retired).

The thirteenth tool, kg_pending, and oto query pending list it by station; the payload carries the same rows under pending, so the explorer draws a pending entity dotted with its station badge and a pending edge dotted, the reader lists them on the home page and on the page they would change, and a custom app projects them with $pending.

Three regimes decide when a served view moves. Live, the default: the view shows the believed graph and changes only when a candidate is applied and built (in repository mode, when the pull request merges and deploys); the lane shows what is coming. Preview, on command: oto preview composes the live graph, the candidate and every proposal and runs the compile stages over the result into build/preview/, a second store beside the live one, so derived facts and policy findings for pending knowledge appear; oto serve --http --preview serves it. Watch, on every change: oto serve --http --watch rebuilds the preview a moment after any authored file changes (preview.py) and the view refreshes through the change signal it already polls, which now carries a token that moves on a rebuild as well as on a build.

The live store, the candidate and the proposals are never written by any of this. Every payload and /api/status carry a mode block (regime, when the preview was built, how many facts differ, rebuild count), and both built-in apps say it in their header.