# Venues

**`.loom/venues/<name>.md` — a choice you made about something that has no
document of its own to hang it on.**

*Kafka. React. HTTP. The organisation you work for.* **Things that constrain what
you build without ever being invoked, and without publishing anything at you that
you could adopt.**

---

## Venue and external are two questions, not two kinds of thing

**`external` is *who published it*. `venue` is *whether you had to decide
anything about it*.** *They are orthogonal. A thing may be both, either, or
neither.*

| | published at us | we recorded a choice | files |
|---|---|---|---|
| Kafka, React, HTTP | yes, by the world | yes — *protobuf for schema* | venue only |
| a service another team owns | yes, by them | not yet — the use is in the code | external only |
| a cluster your own org publishes | yes | yes | both |
| a library you use exactly as documented | yes | no | neither |

**Both files are governed by the same rule, applied to two different ambients:**

> **An external entry exists when the reader cannot be assumed to know the
> thing.** *A venue file exists when you made a choice worth recording.*

**Nobody needs telling what Kafka is, so there is no external entry** — *but "we
use protobuf for schema" is a choice, so there is a venue file.* **Nobody outside
can know what your internal API is for, so there is an external entry** — *and
until using it requires an exception or a preference, there is nothing to
accommodate and no venue file, because the actual use is in the code.*

*This is why sorting things into two bins does not work and people keep trying.
The bins were never the problem. The question was.*

## A venue file is an account of your own decisions

**Which is what makes it local by construction.** *An external is a copy of
somebody's document and could in principle be centralised.* **A venue file has no
upstream** — *there is nobody to reconcile with, because the only party who
decided anything was you.*

**So it does not go stale the way a copy does.** *It goes stale when you change
your mind and do not say so*, which no fetch will ever detect.

> **A venue file that carries no delta should not exist.** *If you use the thing
> exactly as documented, write nothing.* **Recording the adoption is ceremony.**

## If there is a document, hang the choice on the document

**Put a choice where reconciliation will look for it.** *When the thing you
decided about publishes something you have adopted, the choice belongs in the
`.usages.md` beside that copy and not in a venue file* — **because that is the
file somebody opens when the document moves**, *and a venue file is not.*

*The venue file is for what is left: the constraints of a thing that publishes
nothing you can hold.*

## A venue is where an authority claim belongs

**Because a venue fact carries a reason and can therefore be shown wrong.**

*The alternative is worse and common: somebody with authority enters a
conversation as a voice, and "we do it this way" arrives with no reason attached
and nothing that could contradict it.* **Written as a venue constraint, the same
instruction becomes a claim about the world**, *and a claim about the world is
something a later reader can discover was false.*

## Checking it is still true

**Nobody will tell you.** *There is no publisher to ask, no `ETag`, and no
conditional request that will ever come back `200`.*

**So a venue file needs what a published document needs: a date, and the reason
underneath the choice.** *The reason is the whole of it* — **"we use protobuf for
schema" is unfalsifiable a year later; "we use protobuf because the consumers are
in three languages and JSON schema drift was costing us a release a quarter" can
be checked against a world that may have changed.**