From d2001431d4e5ab5d8f42df75b79c4fefdd13a9c8 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:27:18 +0200 Subject: [PATCH] Leave a record's moved reading as the command that produced it (#269) 0103 pastes a command and three file names under a paragraph arguing that a refusal with a worked case behind it is quotable. The command returns five files today. Nobody edited that paragraph: two records were added that name #103, and the paste went stale where it stood. 0269 decides that where a landed record pastes a command and the output no longer reproduces, the output is deleted and the command is left standing alone, with nothing pasted in its place. 0001 receives a second `Narrowed-by:` line for it, naming the clause narrowed - the prohibition on editing a record in place, which does not reach a pasted output removed so that only its command is left. The failure it prevents is a reader who runs the command, finds two files the record does not account for, and cannot tell whether the record is wrong or they are. That is the defect class this repository's rules lead with, standing in the record whose subject is what may be admitted at all. A fresh output pasted in place of the stale one repairs the sentence and not the class, and the evidence for that is the instance itself: the count moved from three to five without anybody opening the paragraph, so a second paste is a second thing that goes stale at the next record naming #103. The command alone cannot fail in that direction - it either runs or it visibly does not. What is lost is stated in the record rather than softened. The historical reading leaves the file and the history is where it is found afterwards, which is a real cost and the one argument against this decision. One thing near the paste is untouched and the record says so, to stop it being raised again: the sentence above the command counts three refusals with a worked case behind them, that is a count of refusals rather than of files, and the two were never the same number. Nothing refuses a stale paste, before or after this. No check here re-runs a command a record wrote down, and none could without executing arbitrary commands out of tracked text, which this gate deliberately does not do. The record says so of itself rather than implying a mechanism arrived. Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- docs/decisions/0001-decision-records.md | 2 + ...admits-a-dependency-and-what-is-refused.md | 3 - ...-reading-a-record-pasted-that-has-moved.md | 160 ++++++++++++++++++ docs/decisions/README.md | 1 + 4 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 docs/decisions/0269-a-reading-a-record-pasted-that-has-moved.md diff --git a/docs/decisions/0001-decision-records.md b/docs/decisions/0001-decision-records.md index acd99ca..7e04719 100644 --- a/docs/decisions/0001-decision-records.md +++ b/docs/decisions/0001-decision-records.md @@ -6,6 +6,8 @@ Status: accepted. Supersedes nothing. Superseded by nothing. Narrowed-by: 0267, on the third permitted edit, the pointer to a later record, which takes a fixed form and becomes a pair of fields where the later record narrows a clause +Narrowed-by: 0269, on the rule that a record is never edited in place, which does not reach a pasted output deleted so that only the command that produced it is left + Issue: #2 ## The decision diff --git a/docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md b/docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md index 34d8bc8..0114946 100644 --- a/docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md +++ b/docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md @@ -137,9 +137,6 @@ tracing library, and 0112 refuses a cross-platform media framework on size on every target: git grep -l '#103' -- docs/decisions - docs/decisions/0041-how-a-cache-key-is-built.md - docs/decisions/0061-the-span-facility.md - docs/decisions/0112-where-the-platform-decoder-begins.md ## A dependency a record already standing requires diff --git a/docs/decisions/0269-a-reading-a-record-pasted-that-has-moved.md b/docs/decisions/0269-a-reading-a-record-pasted-that-has-moved.md new file mode 100644 index 0000000..07acea5 --- /dev/null +++ b/docs/decisions/0269-a-reading-a-record-pasted-that-has-moved.md @@ -0,0 +1,160 @@ +# 0269. A reading a record pasted, after the tree has moved + +Date: 2026-09-02 + +Status: accepted. Supersedes nothing. Superseded by nothing. + +Narrows: 0001, on the rule that a record is never edited in place, which does not reach a pasted output deleted so that only the command that produced it is left + +Issue: #269 + +## The decision + +Where a landed record pastes a command and the output that command produced, and +the output no longer reproduces, the output is deleted and the command is left +standing alone; nothing is pasted in its place, and this is a fourth edit that is +not a supersession. + +## The instance, read rather than recalled + +[0103](0103-what-admits-a-dependency-and-what-is-refused.md) pastes a command and +three file names under a paragraph arguing that a refusal with a worked case +behind it is quotable: + + git show origin/main:docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md | sed -n '137,140p' + +The same command run against the reference a reader has: + + git grep -l '#103' origin/main -- docs/decisions + +returns five paths rather than three. Two of them the paste does not carry: the +record itself, which matches on its own `Issue:` line and always did, and +[0011](0011-the-language-the-toolchain-and-the-binding-layer.md), which wrote this +collision down as its own reversal condition before there was a graph to measure. + +Nobody edited that paragraph. The count moved because records were added, which is +what makes this a class rather than a mistake somebody made. + +One thing near it is untouched and is worth separating, so that a reader does not +raise it a second time. The sentence above the command counts three refusals with +a worked case behind them. That is a count of refusals and not of files, the +command returns files, and the two were never the same number - 0103 itself and +0011 are among the five and neither is a refusal with a worked case. The sentence +is the record's argument, it is unchanged, and this decision reaches the output +under it and nothing else. + +## Why the output goes and the command stays + +A reader who runs the command finds two files the record does not account for and +cannot tell whether the record is wrong or whether they are. That is the defect +class this repository's rules lead with, standing in the record whose subject is +what may be admitted at all. + +Pasting a fresh output repairs the sentence and not the class. The reading was +correct on the day it was written and went stale without being touched; a second +paste is a second thing that will go stale, and the next record naming #103 moves +it again. + +The command alone cannot fail in that direction. It either still runs or it does +not, and a command that no longer runs is visible the moment somebody tries it, +where a stale output is invisible to everyone who does not. + +The tree already hands a reader a command rather than its output in the two places +that meet this most often. `README.md` says of the dependency graph that what is +there and what it reaches is read rather than written there. `docs/gate-parity.md` +does it twice: once as a sentence telling a reader to re-run rather than read the +paste, and once by declining to write a count into a table cell and handing over +the command instead. This record takes the second of those shapes for a landed +decision record, where the first is not available because it is an edit that adds +prose. + +## Why this is a narrowing of 0001 and not a supersession of anything + +[0001](0001-decision-records.md) says a record is added or superseded and never +edited in place, and gives the reason: the value of a record is the reasoning that +was available at the time, including the parts that turned out to be wrong, and a +record quietly corrected reads afterwards as a decision that was always right. + +A pasted output is not reasoning. It is a reading of a tree at a moment, standing +as evidence for a sentence that is itself unchanged. +[0103](0103-what-admits-a-dependency-and-what-is-refused.md)'s paragraph argues +that the refusals are quotable; the command is the quotation, and the three lines +under it are what the quotation returned once. Delete them and the record decides +what it decided, argues what it argued, and reverses under the same condition. + +So the clause narrowed is the prohibition itself rather than any of the three +edits already carved out of it, and the field +[0001](0001-decision-records.md) receives says so. 0267 is the record that decided +what such a field looks like, one day before this one used it. + +## What is lost, stated rather than softened + +The historical reading goes out of the file. A reader who wants to know what the +command returned on 2026-08-24 has to go to the history for it: + + git log -p --follow -- docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md + +That is a real cost and it is the one argument against this decision. It is +accepted because the alternative keeps a wrong reading in front of every reader in +order to serve one who is looking for a superseded one, and because the history is +where this repository keeps superseded things everywhere else. + +Nothing refuses a stale paste. No check here re-runs a command a record wrote +down, and none could without running arbitrary commands out of tracked text, which +is a thing this gate deliberately does not do. So this rule is carried by the +record and by whoever notices, exactly as it was before, and what changed is that +noticing now has a route that does not require superseding a record whole. #269 is +where that gap was named and this record does not close it. + +## Why this is written down before the code + +Without it the only route 0001 offers for a stale reading is a supersession of the +whole record. Superseding +[0103](0103-what-admits-a-dependency-and-what-is-refused.md) to correct one pasted +grep discards a licence set, a worth test, five grounds and a clause for a +standing requirement that nobody has argued with, and it does that every time any +record's reading moves. The cost is high enough that the honest route is the +expensive one, and a rule whose honest route is the expensive one selects for the +quiet one - which here is leaving the wrong output standing. + +The specific failure has already happened and it is the one above. It will happen +again on a schedule nobody controls, because every pasted reading in every record +goes stale when the tree moves rather than when somebody edits the paragraph. + +## Alternatives, and what each cost + +A supersession of the whole record. It costs the six things above, discarded to +correct three lines, and it gets worse each time: a record superseded for a stale +reading has a successor that carries its own pasted readings and its own future +supersession. + +A fresh output pasted in place of the stale one. Cheapest to write and it is the +option that looks like a fix. It costs nothing today and reproduces the defect on +the day the next record names #103, which is measured rather than supposed: the +count moved from three to five without anybody opening the paragraph. + +A sentence beside the paste saying the output moves, which is what +`docs/gate-parity.md` does. It costs more than what it replaces: it is an edit +that adds prose to a landed record, so it needs the same permission this record is +about, and it leaves the wrong output standing as the first thing a reader meets. + +Leaving it. The state this record ends. A reader who runs the command gets an +answer the record contradicts, in the record that says a claim carries the command +that produced it. + +## What would reverse this + +A deleted output turns out to have been the argument rather than evidence for one, +twice. One is a paragraph that was written badly. Two is a shape where the output +carried the reasoning, and the answer is a supersession rather than a wider +deletion rule. + +The history stops reaching a deleted reading. This decision rests on the history +holding what the file no longer does, so a rewrite of it, or a move that breaks +`--follow`, takes the ground out from under this record rather than merely +inconveniencing a reader. + +A check arrives that re-derives a record's pasted readings and refuses one that no +longer reproduces. Then the deletion is no longer the repair, because the paste +can be kept and held true, and this record is superseded by one describing what +that check reads. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 181243d..67705eb 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -65,4 +65,5 @@ allocated, and why a record is superseded rather than edited are in - [0243. The means a certificate is validated with, and what it costs](0243-the-means-a-certificate-is-validated-with.md) - [0267. A record that narrows one clause of another](0267-a-record-that-narrows-one-clause-of-another.md) - [0268. A conjunctive licence expression, and the term the set does not name](0268-a-conjunctive-licence-expression.md) +- [0269. A reading a record pasted, after the tree has moved](0269-a-reading-a-record-pasted-that-has-moved.md) - [0272. The route next up is read from](0272-the-route-next-up-is-read-from.md)