jeffryandClaude Opus 5
26f8b98dc6
Four documents used the word and none defined it. cart.md leaned on it hardest — an authority claim entering as a venue fact carries a reason and can be shown wrong — which is a real mechanism resting on an undefined term. It is bedrock's because venues/ is one of the directories starting.md already lists beside published/ and gaps/. A concept named in the primitives was being half-defined in a downstream convention's four-line aside, which is the same diagnosis loom-cli made about publication two days ago. Second instance of that shape. Nothing is invented: entry 6 settled this on 2026-09-05 and the table is that entry's. New here is that a venue file is local because it has no upstream, and that it goes stale in a way no fetch can detect — so it needs the reason underneath the choice or it cannot be checked at all. Entry 84. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
# 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.**
|