the path does not record the origin — a lock does

loom-cli's builder tried to run check against a real tree and could not. The
stored path does not round-trip to a URL: we hold
git.hypertheory-labs.dev/loom/externals/externals.md and the document is served
from /loom/externals/raw/branch/main/.loom/published/externals.md, measured as a
404.

Two segments are dropped and the second is not routing. The raw route and branch
are recoverable only by knowing the host's URL shape and guessing a branch name.
And .loom/published/ — which publication.md says is the entire contract — means a
consumer's tree did not record whether a copy came from a published surface or a
file its owner may rename at will.

The short form is worse than incomplete: a host may redirect it to whatever the
default branch is at the time you ask, so a lock holding one is locked to a moving
target and a branch rename reports as a change in the document. Locks record the
resolved URL.

This is the ETag mistake one layer down, and the builder named the appetite behind
both: the design is beautiful when nothing is written down, and both times what
made it possible was a property of one host. Second occurrence, so it is recorded
as a pattern to check for.

Also records that gitea's ETag being the blob hash is a migration aid rather than
a mechanism — the builder used it to check eight documents with no locks at all,
which is worth doing once and nothing after. The next person to notice the
coincidence will think they found the good idea again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-07 13:45:30 -04:00
co-authored by Claude Opus 5
parent e62bbe17c1
commit aff2065297
2 changed files with 84 additions and 2 deletions
+55
View File
@@ -48,3 +48,58 @@ 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.*
---
**Decided** (2026-09-07, loom + claude-substrate — `discovered`, `cart: osprey`):
**the path does not record the origin. A lock does**, holding the resolved URL and
the publisher's `ETag`, in `.loom/externals/.locks`.
**Advances** the one command that has to send a request being able to construct
one.
**Because** `loom-cli`'s builder tried to run `check` against a real tree and
could not. **The stored path does not round-trip to a URL** — *we hold
`git.hypertheory-labs.dev/loom/externals/externals.md` and the document is served
from `/loom/externals/raw/branch/main/.loom/published/externals.md`.* **It 404s,
measured.**
**Two segments are dropped and the second is not routing:**
- *the host's raw route and the branch* — **recoverable only by knowing that
host's URL shape and guessing a branch name**
- **`.loom/published/`** — *which `publication.md` says is the entire contract.*
**So a consumer's tree did not record whether a copy came from a published
surface or from a file its owner may rename at will.**
*And the short form is worse than incomplete: a host may redirect it to **whatever
the default branch is at the time you ask**, so a lock holding one is locked to a
moving target and a branch rename reports as a change in the document.*
> **This is the `ETag` mistake one layer down**, and the builder named the
> appetite behind both: ***the design is beautiful when nothing is written
> down**, and both times what made it possible was a property of one host.*
*Second occurrence, so it is a pattern rather than an incident: **when a design
claims something is derivable and therefore need not be recorded, check whether
the derivation is a fact about the general case or about the host in front of
you.***
---
**Finding** (2026-09-07, claude-substrate — `cart: osprey`): **gitea's `ETag`
being the blob hash is a migration aid, not a mechanism.**
*`loom-cli`'s builder ran `check` across eight documents with **no locks at all**,
by hashing local copies and comparing — **the exact thing this convention
forbids** — and it worked, because on this host the two coincide.*
**It is worth doing once, to lock what was fetched by hand before a tool existed.
It is worth nothing after that**, and it works on gitea only.
*Recorded because **the next person to notice the coincidence will think they have
found the good idea again**, and there is now a log entry saying it was found
twice and rejected twice.*
*Seven of the eight were byte-identical to upstream, so this host's raw serving
normalises nothing — **which is a fact about this host and not a licence.***