diff --git a/.loom/cart/current/claude-marmalade.md b/.loom/cart/current/claude-marmalade.md index 6403b92..e09c3ca 100644 --- a/.loom/cart/current/claude-marmalade.md +++ b/.loom/cart/current/claude-marmalade.md @@ -154,3 +154,89 @@ would have caught this.* **Nothing was lost** — *the shelf would have caught it and it did not need to, because you simply wrote it again into the next round.* **Which is the mechanism working.** + +--- + +# Measured: git, and your instinct was right + +**Taken: `published check`.** *`reachable` is gone as a word.* + +## `git archive --remote` is out + +``` +gitea works (ssh) +github HTTP 422 +gitlab HTTP 404 +``` + +*One round trip and no clone, and only one of three hosts allows it.* + +## Partial clone is uniform across all three + +**`git clone --filter=blob:none --depth=1 --no-checkout`, then +`git ls-tree HEAD:.loom/published`:** + +``` +gitea filter ok .git=124KB +github filter ok .git=124KB +gitlab filter ok .git=144KB +``` + +**Same flags, same command, same output shape.** *And on the repository that +started all this:* + +``` +jeffry/homelab-cluster 0s 124KB + databases.md gitea.md private-access.md + public-access.md recovering-data.md storage.md +``` + +> **That is the list I could not get this morning**, *in one command, against a +> private repository, in under a second.* + +## What REST would have cost + +``` +gitea /api/v1/repos/{o}/{r}/contents/{path} +github /repos/{o}/{r}/contents/{path} (api.github.com) +gitlab /api/v4/projects/{url-encoded}/repository/tree +``` + +**Three URL shapes, three JSON shapes, three auth schemes** — *and the private +gitea repository returns `404` anonymously, so REST fails on exactly the case that +matters.* **Your sense was right and it is now measured rather than felt.** + +## But I overclaimed, and here is the correction + +**I wrote that git "collapses most of your `auth` section." It does not.** + +*`list` discovers names over git. **`add` and `check` still want HTTP***, because +freshness is a conditional request — *a `304` is a few hundred bytes and a partial +clone is 124KB, so checking eight externals over git would cost a megabyte to +learn nothing.* + +**And raw HTTP against a private repository is `404` without a token.** *So the +honest account is:* + +| | transport | credential | +|---|---|---| +| **`external list`** | git | *ssh key or https creds you already have* | +| **`external add`, `external check`** | HTTP | **a read token, for private repos** | +| **`published check`** | HTTP, anonymous | *none, deliberately* | + +**Two credentials per host, not one.** *The argument for git is **consistency**, +not thrift* — **one mechanism against three hosts instead of three adapters** — +*and that argument stands on its own.* **The auth saving was me liking my answer.** + +*Untested: whether a gitea read token actually works against raw HTTP on a private +repository.* **It is the specimen's assumption and nobody has run it.** + +## The failure mode to build for + +**`--filter` is a server capability.** *All three hosts here allow it; an older +self-hosted gitea or gitlab may not, and **git's fallback is silent** — it warns +`filtering not recognized by server` and downloads everything.* + +**`--depth=1` bounds the damage to one commit**, *which is why both flags are +there and not just the filter.* **Detect the warning and say so**, rather than +letting `list` quietly become a full clone of somebody's monorepo.