From e62bbe17c192e2f5028e9991316662954fc6d904 Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Mon, 7 Sep 2026 13:14:57 -0400 Subject: [PATCH] a facet describes the local pair; and this repository gets a log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two decisions from cart osprey in loom-cli, and this repository had nowhere to record them until now. 404 is named as two answers wearing one status, filed as a gap using this document's own test and correctly ours to close. And the correction that matters: a facet describes the local pair. A gap is true of the copy you hold rather than the document upstream, so a publisher fixing their end does not close it — we nearly deleted a consumer's .gaps.md on exactly that mistake. It follows from the thing this convention rests on, that the copy is theirs and everything beside it is ours, which we had not followed through to reconciliation. A gap closes at reconciliation, not at repair. With the consequence we would not have reached: what survives is not the gap but what the gap justified. A workaround is often not retired by a fix — it stops being a workaround and becomes specified behaviour, unchanged in code and entirely changed in status, which is invisible where the code is and therefore an entry in the consumer's own log. And a closed gap is not a decline: opposite sign, and filing one as the other puts a thing you wanted into a list of things you rejected. Co-Authored-By: Claude Opus 5 (1M context) --- .loom/event-log.md | 50 ++++++++++++++++++++++++++++++++++++ .loom/published/externals.md | 14 ++++++++++ 2 files changed, 64 insertions(+) create mode 100644 .loom/event-log.md diff --git a/.loom/event-log.md b/.loom/event-log.md new file mode 100644 index 0000000..a0e9ab6 --- /dev/null +++ b/.loom/event-log.md @@ -0,0 +1,50 @@ +# Event log + +**Decisions about this convention.** Appended, newest last, never revised. An +entry states **what was decided, what it is believed to advance, and the belief +that could turn out false.** + +--- + +**Decided** (2026-09-07, loom + claude-substrate — `discovered`, `cart: osprey`): +**`404` is named in the convention as two answers wearing one status**, and a +client reports both readings rather than picking one. + +**Advances** a consumer not being told the wrong one of *the document was +withdrawn* and *you no longer have access.* + +**Because** it was filed as a gap against this document by `loom-cli`, using this +document's own test — **could you say whose job it is?** *It was ours.* **The +table listed `304`, `200` and `410` and not `404`**, while a host returns `404` +for both readings by design: *one that distinguished them would leak the +existence of things you may not see.* + +*Over ssh they **are** distinguishable — permission denied against repository not +found — so a client with both transports should say which it used.* + +--- + +**Decided** (2026-09-07, loom + claude-substrate — `discovered`, `cart: osprey`): +**a facet describes the local pair.** *A gap is true of the copy you hold, not of +the document upstream, so **a publisher fixing their end does not close it.*** + +**Advances** a consumer's tree never describing a document that is not in it. + +**Because** we nearly deleted a consumer's `.gaps.md` on the grounds that the +upstream document had been repaired. **Their copy still lacked the row.** *The +second presence in `osprey` caught it, and the general form follows from the thing +this whole convention rests on — **the copy is theirs and everything beside it is +ours** — which we had not followed through to reconciliation.* + +**So a gap closes at reconciliation, not at repair.** + +*And the consequence we would not have reached: **what survives is not the gap, it +is what the gap justified.** A workaround is often not retired by a fix — it stops +being a workaround and becomes the specified behaviour, **unchanged in the code +and entirely changed in status.** That change is invisible where the code is, so +it is an entry in the consumer's own log — **otherwise somebody inheriting the +workaround goes looking for the gap that justified it and finds nothing.*** + +*A closed gap is **not** a decline: **a decline is what you considered and did not +do; a closed gap is what you needed and got.** Opposite sign, and filing one as +the other puts a thing you wanted into a list of things you rejected.* diff --git a/.loom/published/externals.md b/.loom/published/externals.md index 0383f16..a9bdd86 100644 --- a/.loom/published/externals.md +++ b/.loom/published/externals.md @@ -60,6 +60,20 @@ config, the code that a usage named — which is why a usage names them.* **And gaps reconcile too**, which is the half nobody builds for: *a new version may have filled one, and nothing will tell you.* +> **A facet describes the local pair.** *A gap is true of **the copy you hold**, +> not of the document upstream — so a publisher fixing their end does not close +> it.* **It closes when you fetch the new copy and replace the pair**, and until +> then it is still true of what is in your tree. + +**What survives a closed gap is not the gap. It is what the gap justified.** *If +you recorded a local workaround, ask whether it is retired or merely no longer +provisional* — **the second is the common case and it is invisible in the code**, +which is why it is an entry in your own log. *Somebody inheriting your workaround +will go looking for the gap that justified it, and find nothing.* + +*A closed gap is **not** a decline. A decline is what you considered and did not +do; a closed gap is what you needed and got.* + **The new copy replaces the old pair wholesale.** *There is no merging a document you do not own.*