publication requires a reader; recording-decisions allows compaction

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) <noreply@anthropic.com>
This commit is contained in:
2026-09-07 16:02:24 -04:00
co-authored by Claude Opus 5
parent cc95488726
commit 6dcc06ab1c
3 changed files with 108 additions and 0 deletions
+63
View File
@@ -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.*