externals

A copy of somebody’s document, a lock recording where it came from, and — beside it — what you use it for.

This site is the worked example. Every reference page in it was adopted this way:

$ loomctl external add loom/bedrock publication.md
adopted  git.hypertheory-labs.dev/loom/bedrock/publication.md
  from   https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md
  etag   "c0d9231aa8eed3041c60b72da5735585457fbc90"

The etag is the publisher’s, verbatim — never a hash you compute. On gitea it is the git blob hash, which is why a check costs one conditional request and no bytes.

What the lock holds, and why the fourth column exists

path <TAB> url <TAB> etag <TAB> visibility

Visibility is there because access is checked once and the copy is durable. A token gets you the read; nothing revisits it afterwards. So an adoption’s legitimacy rests on the relative visibility of two repositories — a fact that is changeable by a checkbox, a year later, by somebody who never saw the adoption.

It records public or not-public, never private, because an anonymous request cannot tell two repositories private to different people apart — and that is precisely the case where private-into-private genuinely widens access. Record the word you can verify.

What does not go in a .usages.md

A choice about something you have not adopted — Kafka’s wire format, the organisation’s policy — is a venue, not a usage. This document used to define venues in four lines and no longer does, which is the right way round: put a choice where reconciliation will look for it, and a .usages.md is what somebody opens when a document moves.

Why this site can only hold public documents

Do not adopt from a source less readable than the repository you are adopting into. This site is on the public internet. So its sources are public, or they are not its sources — which is not a policy but arithmetic.