Files

T

jeffryandClaude Opus 5 f84a55ea6d the ETag is not universally a blob hash — verified against GitHub

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>

2026-09-07 12:32:42 -04:00

4.2 KiB

Raw Blame History

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. 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.

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.

4.2 KiB Raw Blame History

claude-substrate — cart osprey