A record that was wrong is never edited. A new document points back at it, and the engine shows the correction on the record itself, so old citations keep showing what they cited and every reader of the record sees what changed.
The argument runs in four steps: which documents may not be edited, what happens when one is overwritten anyway, the three ways folio points back instead, and why pointing back is worth the extra document.
supersedes field, sends every reader on. The ids are made up for the example.Step one
Which documents are never edited
A genre says how its documents change over time. Most are revised in place. A permanent record, such as a journal entry or a result, is never edited once committed. A frozen document, such as a locked protocol or a published report, is edited freely until it reaches its frozen state, and then never again except its status. The gate checks both against git history.
Permanent
a journal entry, a result
- first commit
- never edited
The gate compares the file with its first commit. It writes no status: its status is derived from what points back.
Frozen
a protocol, a report
- draft
- locked
- abandoned
Edited freely until it reaches a frozen state. After that only its status moves, forward to one of its card's exits, in a commit that changes nothing else.
Revised
concepts, entries, maps, projects
- live
- live
- live
Edited in place and always current. Corrections to these are ordinary edits, and git keeps the history.
A protocol was locked yesterday and has a typo in its hypothesis. Can the agent fix it in place?
amends, or a correction entry about it says what was meant.Step two
Overwrite against supersede, replayed
Take one result that three pages cite. The measurement is redone and comes out different. Step through what each lane does, and what a reader who follows an old citation sees at the end.
- Cited. The result is committed, and an entry, a report and a project page cite it by id.
- Redone. Someone edits the result's number to the new value. The old value is gone from the page, and the gate fails the edit, because the file no longer matches its first commit.
- Followed. Had the edit got through, a reader who quoted the old value would follow the citation and find a different number, with nothing to say it changed or why. The three citing pages now point at a document that says something else.
- Cited. The result is committed, and an entry, a report and a project page cite it by id.
- Redone. A new result is committed with
supersedesnaming the old one. Nothing else is written: the engine derives the old result's status assuperseded. - Followed. The reader lands on the old result exactly as it was cited, with a banner linking the new one. With the lab pack on, the gate warns on each revised page that still cites the old result, so the agent updates them.
Both lanes start from the same file. Only the supersede lane leaves the library able to answer what was believed, when, and what replaced it.
Step three
Three ways to point back
When a measurement is redone, the new result names the old one: supersedes: R-12. When nothing replaces a record, a journal entry does the pointing. Each row below is one instrument, and none of them edits the original.
| Instrument | Written as | Status of the original | What the reader sees |
|---|---|---|---|
| Supersede | a newer record of the same genre, with supersedes | superseded, derived | a banner linking the newer record; the old one keeps its id and address |
| Retract | a journal entry of kind retraction, naming it in about | retracted, derived | the record stays readable, marked retracted, with a banner linking the entry that says why |
| Correct | a journal entry of kind correction, naming it in about | unchanged | a banner on the document with the entry's text, saying what is true instead |
A frozen document keeps the status it was frozen with, and shows its corrections the same way.
Where does a retracted result's status come from, since the result writes no status?
about names the result.Step four
Why not just edit
An edit erases the evidence that something was wrong. Anyone who read the old value has no way to learn it changed, and a page that quoted it now cites a document that says something else.
A correction that points back keeps both, and the banner tells every later reader. The cost is one more document, and the gate makes sure nobody skips it.
It is the same idea as one fact, one home, applied over time: the fact keeps one home, and its history is a chain of documents that point back.