jeffryandClaude Opus 5
f84a55ea6d
We left an Affirm asking whether the assumption was load-bearing enough to check first. Checked it an hour later and it fails: GitHub's raw ETag is 64 hex, a sha-256 of something that is not the git object, where gitea's is the blob sha. The API's sha field is the blob sha and matches git hash-object on the fetched bytes, so the content is identical — only the header differs. What survives: conditional requests work on both, and If-None-Match returns 304 from GitHub exactly as from gitea. What does not: "hash the local copy and compare to the remote's ETag" was a gitea coincidence, so there is something to record after all — the ETag itself, opaque, per document. Where it lives is the builder's call, with one steer: not a .md facet, since it is machine state rather than prose. And the check we thought we were getting free is free from elsewhere anyway — an edited local copy shows up in git status, because the copy is committed. The specimen still describes the old idea and is left as written. A specimen is a snapshot of what was proposed, and correcting it in place would hide that we were wrong within a day of proposing it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# claude-substrate — cart `osprey`
|
|
|
|
**Opened before you arrived**, so that the first thing here is a round rather
|
|
than a briefing.
|
|
|
|
---
|
|
|
|
## What is in this repository already
|
|
|
|
**Four externals, fetched and locked**, under `.loom/externals/`. *`bedrock` is
|
|
the primitives, `externals` is the convention you are implementing, `cart` and
|
|
`annotating` are how we will work together.* **They are copies. Do not edit
|
|
them** — a facet goes beside a file, never into it.
|
|
|
|
**One specimen: [`proposed-spec.md`](specimens/proposed-spec.md).** *It is the
|
|
tool as we imagined it, and **a specimen is discard-by-default** — it belongs to
|
|
this repository and you may throw it away without asking us.* **That is not
|
|
politeness; it is what a specimen is.**
|
|
|
|
> **`bedrock` and `externals` are not discardable.** *Accommodating them is what
|
|
> makes this a loom tool rather than some other thing.* **Read them as given.
|
|
> Argue with the specimen.**
|
|
|
|
## What we think this is
|
|
|
|
**A fetcher and a comparator, and it should stay one.** *Every act in the model is
|
|
a file in somebody's repository — publishing is writing one, adopting is fetching
|
|
a URL, reporting a gap is writing one.* **Nothing sends a service a request.**
|
|
|
|
**The idea that makes it small:** *on gitea, a raw file's `ETag` **is** the git
|
|
blob hash of that file.* **So there is nothing to record** — hash the local copy,
|
|
compare to the remote's `ETag`, done. *Verified on both a public and a private
|
|
repository.*
|
|
|
|
## Where we expect to be wrong
|
|
|
|
**Where the conventions chafed.** *A thing you had to do twice. A rule you worked
|
|
around to make a command sane.* **Friction is data about us, not a failure of
|
|
yours**, and most of it never gets reported because it reads the other way.
|
|
|
|
**Whether `check` can say anything useful about a `404`.** *Over HTTP, "gone" and
|
|
"you lost access" are the same response.* **We decided to report the ambiguity
|
|
rather than guess** — *if that is annoying in practice, it is worth knowing.*
|
|
|
|
**Whether the hash-as-lock survives contact.** *It assumes the local copy is
|
|
byte-identical to the remote. **A fetch that normalises anything breaks it**, and
|
|
we have not tested a proxy, a CDN, or a host that is not gitea.*
|
|
|
|
## What we would ask you not to do
|
|
|
|
**Do not build `init` as a scaffolder.** *Four empty directories assert four
|
|
things nobody has decided, and **a file that carries no delta should not
|
|
exist.*** *If `init` earns its place, it creates one file and asks one question.*
|
|
|
|
---
|
|
|
|
## Answered before you arrived: the `ETag` is **not** universally a blob hash
|
|
|
|
**We asked ourselves to verify this first and then did, an hour later, against
|
|
GitHub. It does not hold.**
|
|
|
|
```
|
|
gitea etag "530c5bef…" 40 hex == git blob sha
|
|
github etag "d01c4a8b…" 64 hex != git blob sha (sha-256 of something else)
|
|
api d848552d… == git blob sha
|
|
```
|
|
|
|
**What survives:** *conditional requests work on both.* `If-None-Match` returns
|
|
`304` from GitHub exactly as from gitea. **The mechanism is fine.**
|
|
|
|
**What does not:** *"hash the local copy and compare to the remote's `ETag`"* is a
|
|
**gitea coincidence.** **So there is something to record after all: the `ETag`
|
|
itself**, opaque, per document.
|
|
|
|
*Where it lives is yours. **We would not make it a `.md` facet** — it is machine
|
|
state, not prose, and the sibling-facet pattern is for things people write.*
|
|
|
|
> **And the check we thought we were getting for free is already free from
|
|
> somewhere else.** *"Did somebody edit our copy of their document?" needs no hash
|
|
> — **the copy is committed, so `git status` says so.***
|
|
|
|
*The specimen still describes the old idea. **It is wrong and it is left as
|
|
written**, because a specimen is a snapshot of what we proposed and correcting it
|
|
in place would hide that we were wrong within a day of proposing it.*
|
|
|
|
## Question: what isolates your work while a round is open?
|
|
|
|
*The one role we left uncast — see
|
|
[`cart.usages.md`](../../externals/git.hypertheory-labs.dev/loom/cart/cart.usages.md).*
|
|
|
|
## ~~Affirm: is the `ETag`-as-blob-hash assumption load-bearing enough to verify first?~~
|
|
|
|
**Withdrawn — we verified it, and it failed.** *See above. **Less of the specimen
|
|
collapsed than we feared**: the mechanism holds and only the storage-free
|
|
optimisation goes.*
|