diff --git a/README.md b/README.md index e931e8f..99ab7bb 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ and for finding out when it changes.*** | **"how do I depend on somebody's document and know when it changes?"** | [externals](https://git.hypertheory-labs.dev/loom/externals) | | **"how do we work something out before one of us changes it?"** | [cart](https://git.hypertheory-labs.dev/loom/cart) | | **"how do I mark up your file without editing it?"** | [annotating](https://git.hypertheory-labs.dev/loom/annotating) | -| **"why is it like this?"** | *`settled` — **private***, and every repository's own `.loom/event-log.md` | +| **"why is it like this?"** | *`settled` — **private**, [what it is](settled.md)* — and every repository's own `.loom/event-log.md` | **And if you want an example rather than a description:** **[`jeffry/homelab-cluster`](https://git.hypertheory-labs.dev/jeffry/homelab-cluster)** diff --git a/settled.md b/settled.md new file mode 100644 index 0000000..fc38dca --- /dev/null +++ b/settled.md @@ -0,0 +1,47 @@ +# What `settled` is + +**`settled` is private. This page is not, and it is here rather than there** — +*because a page explaining a private repository, published inside that private +repository, is not published.* **That was the first fix and it did not work; this +is the second.** + +--- + +## Why a decision about `externals` is not in `externals` + +**Most of them are.** *`externals` has its own log, and how a consumer reconciles +is recorded there.* + +**What lives here is the shape of the whole:** *that there is a `bedrock` at all; +which repositories exist and why; that affordances, stagings, roles and beads are +bracketed and what that defers; that a registry is a fan-out reader rather than a +service.* **None of those belong to any one repository, and putting them in one +would make that repository quietly authoritative over its siblings.** + +> **An entry goes in the log of the repository whose decision it is.** *This is +> the repository for decisions that are nobody's in particular.* + +## It is not a new kind + +**One file: an `event-log`.** *The kind is exactly the one `bedrock` describes.* +**What is different is ownership, not shape** — *and if this ever holds something +that is not an event log, it has become a new kind and should say so here.* + +## Why it is private + +**A record of how a thing came to be shaped is mostly a record of being wrong in +public.** *Roughly a third of its entries correct earlier ones.* **That is the log +working**, and it is also not something to hand a stranger as an introduction. + +*The consequence, stated because it is a real cost: **the justification for a +constraint may be unreadable by the person the constraint lands on.** If that +starts to bite, this page is the wrong fix and opening the log is the right one.* + +## If you are stuck + +**You do not want the entries. You want the one sentence you could not guess**, +which is at the top of this page. + +**And the entries are not the way in.** *[`loom/.loom`](https://git.hypertheory-labs.dev/loom/.loom) +routes by question; [`bedrock`](https://git.hypertheory-labs.dev/loom/bedrock) +holds the primitives and a starting page.*