From 4e7aa1ff1ff590037280e74b7a76ddbcabf99e25 Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Tue, 8 Sep 2026 10:33:14 -0400 Subject: [PATCH] loom-cli publishes one page: what the tool guarantees, not what it does MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier decision stands rather than reverses. .loom/published/ was recorded as deferred, not declined — it earns publication when somebody depends on the tool's behaviour rather than reading its help — and a docs site whose build calls add, check and apply is that consumer. The condition fired. The delta is real and is not the command list: --help says what the tool does, and a reader cannot learn from it which behaviours survive the next version. The sharpest case is loom's — the tool is now a second holder of externals' rule that the lock is the publisher's ETag and never one you compute, and nothing anywhere said the tool holds it, in a repository where a specimen was written that computed a hash instead. Includes what a contract must include and the ask did not mention: what is not promised. 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. That is the half a reimplementation needs most, and it keeps the page from quietly committing us to the CLI. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris --- .DS_Store | Bin 0 -> 6148 bytes .loom/published/guarantees.md | 93 ++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 .DS_Store create mode 100644 .loom/published/guarantees.md diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..5008ddfcf53c02e82d7eee2e57c38e5672ef89f6 GIT binary patch literal 6148 zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3 zem<@ulZcFPQ@L2!n>{z**++&mCkOWA81W14cNZlEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ zLs35+`xjp>T0 **What it adds over a paste is provenance.** *A pasted document cannot answer +> "where did this come from, and were we allowed to have it" — not because the +> question is hard, but because the evidence is gone.* + +## It never writes over the network + +**No push, no publish, no `POST`, no token that needs write scope.** *Every byte +it writes is a file in your working tree.* **Committing and pushing are yours**, +*because the consequences of a push land on people a tool cannot experience.* + +**A credential given to `loomctl` should never carry write scope**, *and if one +does, nothing here will use it.* + +## Freshness is a conditional request against the publisher's `ETag` + +**Stored verbatim, opaque, never a hash we compute.** *A fetch that normalises +anything breaks a local digest and reports a change that did not happen.* + +*This is `externals`' rule and `loomctl` is a second holder of it. **It is stated +here so that the tool holding it is a fact somebody can find**, and so that +breaking it is visible rather than silent* — **a specimen was written in this +repository that computed a hash instead, and it was wrong within a day.** + +**The URL in a lock is resolved.** *A short form follows whatever the default +branch is at the time you ask, so a branch rename would report as a change in the +document.* + +## It reports; it does not repair + +**Nothing is overwritten.** *A document that moved upstream is written to a +staging area as a candidate, and taking it is a separate act.* **A local copy +that differs from what the publisher serves is left alone** — *it is the only +evidence that something changed while nothing was watching.* + +**`add` adopts what is absent and refuses what is already adopted.** *A document +that is present but unlocked is locked only when the bytes are identical to what +the publisher serves*, **so a lock's claim — this copy is the one being served — +is verified rather than assumed.** + +## The lock file + +**`.loom/externals/.locks`, one record per adopted document, tab-separated, +ordered by path.** + +``` +path url etag [ visibility ] +``` + +- **`path`** — *relative to `.loom/externals/`, and **for a person to read**.* **It + does not round-trip to a URL**; *it drops the route, the branch, and the + publisher's `.loom/published/`.* +- **`url`** — *the resolved origin, branch and all.* +- **`etag`** — *the publisher's, verbatim, including its quotes.* +- **`visibility`** — *optional. What the source could be read as **when it was + fetched**: `public` or `not-public`.* **Never `private`** — *an anonymous + request tells those two apart and nothing finer.* + +**Records with three fields remain valid.** *A repository does not stop working +because the tool learned something new.* + +## What is not promised + +**The command surface.** *Names, flags and output are `--help`'s business and may +change. Nothing should parse them.* + +**The generated orientation file's format.** *It is byte-deterministic within a +version so that its diff is readable; it is not stable across versions.* + +**That visibility is precise.** *The signal distinguishes public from not-public +and nothing finer, so it cannot see two repositories private to different people +— which is the case where adopting between private repositories genuinely widens +access.* **The tool says so where it reports it, rather than implying a verdict it +has not earned.** + +**That anything is checked when you are not looking.** *Nothing here runs on a +schedule, and a document nobody checks is a document nobody is checking.* + +--- + +*Verified fetchable by somebody who is not us on 2026-09-08.*