From 045924ec36b837a26ae2323f458e4fa6976dc20c Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Tue, 8 Sep 2026 10:48:47 -0400 Subject: [PATCH] tansy converts: three entries, no shelf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Publishes what the tool guarantees, on a condition that fired rather than a decision reversed. Records the narrower promise that replaced promising the command surface — a change to it lands on the page consumers already lock, so a rename reports 200 the day it happens. And records a limit found by accident that follows from a guarantee rather than from anybody's code: an ETag is opaque, we promise never to interpret one, so two of them can be compared and never ordered. A consumer can know two versions disagree and can never know which is behind. Anybody building freshness on this inherits it. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris --- .loom/event-log.md | 59 +++++++++++++++++++ .loom/externals/.locks | 2 +- .../loom/externals/externals.md | 21 +++++++ 3 files changed, 81 insertions(+), 1 deletion(-) diff --git a/.loom/event-log.md b/.loom/event-log.md index 70a5736..babad43 100644 --- a/.loom/event-log.md +++ b/.loom/event-log.md @@ -1092,3 +1092,62 @@ three times, and then declined.* *Recorded as a working note rather than a decision: **when a word could be read narrowly or broadly, this repository has evidence that I pick narrow.*** + +## 2026-09-08 — published: what the tool guarantees `tansy` + +**`.loom/published/guarantees.md`**, *and step 4 of `publication` was run: `200` +anonymously, off no credential of ours.* + +**The earlier decision did not reverse; its condition fired.** *`.loom/published/` +was recorded as deferred rather than declined, on the condition that somebody +depends on the tool's behaviour rather than reading its help.* **A docs site whose +build calls `add`, `check` and `apply` is that consumer.** + +*The delta is not the command list — that is a copy of what the code owns.* +**`--help` says what the tool does; a published page says what will keep being +true**, *and a reader cannot learn from a binary which of its behaviours survives +the next version.* + +**The page includes what is not promised**, *which is the half a reimplementation +needs most:* **the command surface, the orientation file's format across +versions, the precision of the visibility signal, and that anything is checked +when nobody is looking.** + +## 2026-09-08 — we do not promise the surface; we promise the change lands `tansy` + +**A consumer's README tells a person to type `loomctl external add loom/ +.md`.** *Nothing parses it — which is exactly why no check would catch a +rename.* **The thing that moved would not be a document anybody adopted.** + +**Promising the surface would freeze the CLI. So the promise is narrower and +runs:** + +> **We do not promise the surface holds. We promise a change to it lands on the +> page you already lock.** + +*`guarantees.md` carries an append-only `Surface changes` section*, **so a rename +reports `200` to every consumer the day it happens.** + +**Belief that could be shown wrong:** *that anybody remembers to write in it.* +**Nothing enforces the section** — *the same weakness as a facet nobody updates.* + +## 2026-09-08 — two ETags can be compared and never ordered `tansy` + +**Found by accident, and it is a consequence of a rule we published this +morning.** + +*The docs site stamped a hand-written guide with the `ETag` it was read against, +and its banner said `written against an older guarantees`.* **It was backwards: +the guide was ahead of the site's copy, not behind.** + +**And it cannot be fixed by trying harder.** *An `ETag` is opaque — that is the +point of it, and we guarantee we never interpret one.* **So a consumer can know +that two versions disagree and can never know which is behind.** + +*The banner now claims no direction.* **Anybody building freshness on this +inherits the same limit**, *and it belongs in the log because it follows from the +guarantee rather than from anybody's code.* + +*Consequence nobody predicted: reconciling cleared the banner with no +acknowledgement, which is correct — an acknowledgement is for a guide that is +behind, and this one was ahead.* diff --git a/.loom/externals/.locks b/.loom/externals/.locks index 38c95a4..2bcae21 100644 --- a/.loom/externals/.locks +++ b/.loom/externals/.locks @@ -11,4 +11,4 @@ git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md https://git.hyperth git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/sibling-facets.md "a46446a34ccb8bfc533d3cce19f4c88548c4fa04" public git.hypertheory-labs.dev/loom/bedrock/starting.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md "b9eefba0f4668a496ccfc6a1377277f0721456d2" public git.hypertheory-labs.dev/loom/cart/cart.md https://git.hypertheory-labs.dev/loom/cart/raw/branch/main/.loom/published/cart.md "15331f1a9cc81bf61a44830cfbb7c274f4c2b119" public -git.hypertheory-labs.dev/loom/externals/externals.md https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md "a7586eb52caf275d9bcedbbd8042c43e5aaad0b9" public +git.hypertheory-labs.dev/loom/externals/externals.md https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md "50673ccffc14d57150ac0a9027b0712d9dcf940d" diff --git a/.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.md b/.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.md index a7586eb..50673cc 100644 --- a/.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.md +++ b/.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.md @@ -62,6 +62,7 @@ what to decide are not.** - **where it was fetched from** — *resolved, as above* - **the publisher's `ETag`** — *verbatim* +- **the visibility the source could be read at, when it was fetched** **It is committed**, because the thing it locks is committed, and *a lock that travels separately from what it locks is the drift this is meant to prevent.* @@ -71,6 +72,26 @@ travels separately from what it locks is the drift this is meant to prevent.* > asserts your copy is the one being served, which is the thing you were going to > check. +### Why visibility is in the lock and not left to the moment + +**Access is checked once and the copy is durable.** *A token gets you the read; +nothing revisits it afterwards.* **So the adoption's legitimacy rests on the +relative visibility of two repositories — and that is changeable by a checkbox, a +year later, by somebody who never saw the adoption.** + +> **Record `public` or `not-public`. Never `private`.** *An anonymous request can +> tell you a repository is not public. It cannot tell two repositories private to +> **different people** apart* — **which is exactly the case where private into +> private genuinely widens access.** *Record the word you can verify.* + +**Checking it costs one request per run, not one per document**, *because the only +thing that must be current is **your own** visibility.* **Re-check a source only +when the alarm would fire** — *you are public, it was recorded not-public* — *and +if it has since gone public, update the lock and say nothing.* + +*A stored visibility decays in both directions, which is why the alarm re-checks +rather than trusting the record.* + ## Freshness is a conditional request **Locked on the publisher's `ETag`, verbatim — never a hash you compute.** *A