venues get a document, written from entry 6
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>
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# 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.**
|
||||
Reference in New Issue
Block a user