From 6dcc06ab1ca051e1913476c33eb8d51308952cea Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Mon, 7 Sep 2026 16:02:24 -0400 Subject: [PATCH] publication requires a reader; recording-decisions allows compaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both from gap files loom-cli filed as the first real adopter of externals. publication.md: "publishing is not an act you can complete alone" existed only in a sibling document as an aside about a tool. It is a property of the act and now says so, along with the fact that publication has a visibility — which externals' confidentiality rule depends on entirely and this document never mentioned. recording-decisions.md: "never revised" and "must be readable" conflict far enough out. Adopts loom-cli's rule verbatim in substance — drop what the artifact could recover, never drop a decline, a measurement, a belief shown wrong, or a supersession — because compaction is safe in exactly the cases where the entry was redundant and unsafe in exactly the cases the log exists for. Entries 79-81. annotating's gaps are left standing on purpose; it is the most depended-on document and its revision is Jeff's call. Co-Authored-By: Claude Opus 5 (1M context) --- .loom/event-log.md | 63 ++++++++++++++++++++++++++ .loom/published/publication.md | 22 +++++++++ .loom/published/recording-decisions.md | 23 ++++++++++ 3 files changed, 108 insertions(+) diff --git a/.loom/event-log.md b/.loom/event-log.md index b64f6e5..45ef9a1 100644 --- a/.loom/event-log.md +++ b/.loom/event-log.md @@ -3613,3 +3613,66 @@ fetchable is.*** *And the command we nearly cut for being a third kind of thing — `reachable` — found all three on the day it would have shipped. **That is its validation and not a feature request.*** + +--- + +## 79 — publication says that a publication nobody can fetch is not one + +**Decided.** `publication.md` gains *"publishing is not an act you can complete +alone"* as a property of the act, and says that publication has a visibility and +that naming the readers is part of publishing. + +**Advances:** a repository can tell whether it has actually published. + +**Filed by** `loom-cli` in `publication.gaps.md`, from one round of real use. Their +claim: the sentence we needed already existed, but **in a sibling document, as an +aside about a tool**, rather than as a property of publication — and +`publication.md` never mentioned visibility although `externals`' confidentiality +rule depends on it entirely. + +**The belief that could turn out false:** that "the test is a fetch you did not +perform" is checkable often enough to be a practice and not just a slogan. *It was +measured three times in one afternoon and failed all three, which is evidence it +is worth stating and no evidence at all that anybody will do it.* + +## 80 — compaction is allowed, and four kinds of entry are exempt + +**Decided.** `recording-decisions.md` gains a compaction rule: an entry may be +dropped when a competent reader could recover it from the artifact, and may never +be dropped when it records a decline, a measurement, a belief shown wrong, or a +supersession. A compaction gets an entry. + +**Advances:** the log stays readable without losing the part that has no other +home. + +**Filed by** `loom-cli` in `recording-decisions.gaps.md` — that *"never revised"* +and *"somebody must be able to read it"* both hold and eventually conflict. **The +rule adopted here is theirs, including its formulation:** *compaction is safe in +exactly the cases where the entry was redundant with the artifact, and unsafe in +exactly the cases the log exists for.* + +**The belief that could turn out false:** that "recoverable from the artifact" is +a judgement two people make the same way. *If it is not, compaction becomes a +quiet way to lose entry 69.* + +## 81 — the four gap files are answered, and one was answered by repair + +**Decided.** Of the four gap files `loom-cli` filed against the four +conventions — the first genuine use of `externals` on a real dependency — three +are answered: entries 79 and 80 here, and `cart/v2`. + +**`annotating` is left standing**, deliberately. *Its gaps are real* — the source +hash that detects a violated freeze, **dissolve** as the definition of responding, +and what to do when a frozen file must change — *but `annotating` is the +most-depended-on document we have and the one whose revision costs every adopter +an afternoon.* **Jeff's call, not mine.** + +**The measurement worth keeping:** *the adopter found four defects in four +documents in three rounds, and the sharpest one was in the version I had written +that same day.* **`cart/v1` made the cart untracked and did not notice that this +turns conversion from lossy-in-the-tree into lossy-absolutely.** + +**Which is the case for `externals` as a whole**, stated better by the thing than +by the document: *the gap file is the only mechanism here where somebody who +cannot edit your document can still put a defect in front of you, and it caught +what review by the author did not.* diff --git a/.loom/published/publication.md b/.loom/published/publication.md index eb0cb63..385e26e 100644 --- a/.loom/published/publication.md +++ b/.loom/published/publication.md @@ -15,6 +15,28 @@ should be unmissable.* **`ls .loom/published/` is *what have we committed to?*** — and it is the question to ask before changing anything. +## Publishing is not an act you can complete alone + +**A file in `.loom/published/` that its intended readers cannot fetch is not +published.** *The move is the act, but the act is not finished until somebody who +is not you can perform the read.* + +> **The failure is invisible from the inside.** *Every check available to the +> publisher passes — the file is there, the commit landed, the path is right.* +> **Only a reader can detect it, and a reader who cannot fetch it does not know +> the document exists to ask about.** + +*The commonest form is a document that answers "why can you not see this?" and is +published **inside** the thing that cannot be seen.* + +**So publication has a visibility, and it is a property of the act rather than of +the file.** *"Others" is not "everyone".* **Naming who the readers are is part of +publishing**, because a repository that depends on this one has to know whether it +is inside that set — *and because a reader who copies a document out inherits the +copy without inheriting the visibility it was published under.* + +**The test is a fetch you did not perform.** + ## What is published is a document **Prose, in whatever form its readers need.** *If a repository organises its diff --git a/.loom/published/recording-decisions.md b/.loom/published/recording-decisions.md index 970d4b4..d190eea 100644 --- a/.loom/published/recording-decisions.md +++ b/.loom/published/recording-decisions.md @@ -24,6 +24,29 @@ reads.* you already rejected — because the rejection lived somewhere that did not survive.* +## Compaction, and the entries it may never touch + +**"Never revised" and "somebody must be able to read it" both hold, and far +enough out they conflict** — *a log nobody can get through has stopped being a +record.* + +**Compaction is allowed. Dropping an entry is not the same as revising one**, and +the uncompacted log is in git history, which is where a reader who needs it goes. + +> **An entry may be dropped when a competent reader could recover it by reading +> the artifact.** +> +> **An entry may never be dropped when it records a decline, a measurement, a +> belief that was shown wrong, or one entry superseding another.** + +*Which means **compaction is safe in exactly the cases where the entry was +redundant with the artifact, and unsafe in exactly the cases the log exists +for.*** **The four protected kinds are the ones with no other home:** *the code +shows what was built and can never show what was refused, what was measured, what +turned out false, or that somebody changed their mind.* + +**A compaction is itself a decision, and gets an entry.** + ## Where it lives `.loom/event-log.md`. **A stream, so a file.**