a changed external is a polad, and add no longer overwrites anything

Restores something the specimen said and the round that discarded the specimen
lost with it: a changed external becomes a polad in the cart, and somebody
decides. check now stages what moved into .loom/cart/current/polad/ with the ETag
that was served alongside the bytes, and prints the .usages.md beside it, because
reconciliation runs the other way — the facets usually survive and what moves is
the code a usage named. It says so when there is no usages file, which is its own
finding.

With no cart open, check reports and stages nothing. The tool does not open a
round: a cart is a bounded exchange between two presences and starting one is
somebody's act, not a side effect of asking about freshness.

add now adopts what is not here and refuses what is already adopted, superseding
the entry that had it announce an overwrite — it no longer overwrites at all. The
one exception is the only way out of a dead end: a document present but unlocked
was fetched by hand, nothing records its origin, and the path does not round-trip,
so check cannot ask about it and a refusal would strand it forever. add accepts it
and the bytes decide — identical locks it without rewriting anything, which makes
the lock's assertion verified rather than assumed, and different stages a polad and
leaves the local copy alone because it is the only evidence anything moved.

apply exists because the lock is the half a person forgets: moving a polad by hand
leaves a lock describing the copy you just replaced. Recorded with its limit —
for an external, discard does not mean the change goes away, so discarding is
really knowingly stale and nothing yet records that choice.

Measured end to end on this repository: eight hand-fetched documents, all eight
locked, nothing rewritten.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
This commit is contained in:
2026-09-07 14:57:57 -04:00
co-authored by Claude Opus 5
parent 57ed133021
commit 021bf63a11
5 changed files with 383 additions and 94 deletions
+74
View File
@@ -614,3 +614,77 @@ a comparator.*
practice nobody ever runs `check` unaided, a tool that only reports when asked is
a tool that reports nothing**, *and the thing we declined to build is the thing
that was needed.*
## 2026-09-07 — a changed external is a polad, which the specimen said first `marmalade`
**Decided:** *`check` stages what moved into `.loom/cart/current/polad/`*, **a
candidate artifact shaped exactly like what it would become**, *whose exits are
apply or discard.*
**This was in the specimen and we lost it.** *"A changed external becomes a polad
in the cart, and somebody decides."* **The round that discarded the specimen
discarded this with it**, *and it came back only because somebody asked what the
stash should be.*
**Believed to advance:** *`externals` says reconciliation runs the other way*
**given what changed in theirs, what do we change in ours** — *and the facets
usually survive while the manifests, the config and the code that a usage named
are what move.* **So staging prints the `.usages.md` beside it**, *which is the
file that names what to go fix*, **and says so when there is none**: *a usage that
does not name what it justifies is half a usage, and no usage at all is a document
nothing records a dependency on.*
**With no cart open, `check` reports what moved and stages nothing.** *The tool
does not open a round* — **a cart is a bounded exchange between two presences, and
starting one is somebody's act, not a side effect of asking about freshness.**
**Belief that could be shown wrong:** *that requiring an open cart is right.* **If
most changes arrive when no round is open, the useful behaviour is the one that
never runs**, *and the polad needs somewhere else to live.*
## 2026-09-07 — supersedes "add says what it replaced": add does not replace `marmalade`
**`add` adopts what is not here, and refuses what is already adopted.** *The
earlier entry made `add` announce an overwrite; **it no longer overwrites at
all**.*
**Believed to advance:** *a command that both adopts and re-fetches is a command
that overwrites the only evidence a change happened.* **Splitting them gives each
one job** — *`add` adopts, `check` notices.*
**One exception, and it is the only way out of a dead end:** *a document that is
present but **unlocked** was fetched by hand before the tool existed.* **Nothing
records its origin and the path does not round-trip, so `check` cannot ask about
it and `add` refusing would strand it forever.** *So `add` accepts it, and the
bytes decide:*
- **identical** → *the lock is written and nothing is rewritten.* **The assertion
a lock makes — this local copy is the one being served — is then verified rather
than assumed**, *which was the whole objection to adopting a remote `ETag`
blindly.*
- **different** → *staged as a polad; the local copy is left alone*, **because a
copy that differs is the only evidence that something moved while nothing was
watching.**
*Measured on this repository: eight documents adopted by hand, all eight locked
with nothing rewritten.*
## 2026-09-07 — `apply`, because the lock is the half a person forgets `marmalade`
**Decided:** *`loomctl external apply [path…]` moves a staged polad into place and
moves its lock with it.*
**Believed to advance:** *applying by hand is one `mv`, and it leaves a lock
describing the copy you just replaced* — **which is exactly the drift the lock
exists to prevent.** *The polad carries the `ETag` that was served with the bytes
somebody reviewed, so applying locks what was actually read rather than whatever
the publisher serves at apply time.*
**This is not the tool fixing anything.** *It executes a decision a person already
made, one document at a time, after the report.*
**Belief that could be shown wrong:** *that two exits are enough.* **For an
external, discard does not mean the change goes away** — *the upstream moved
whatever we do* — **so discarding is really "knowingly stale", and nothing
currently records that choice.** *If people discard often, that silence is the
next defect.*