diff --git a/03-DESIGN/01-to-be/11-a-board.md b/03-DESIGN/01-to-be/11-a-board.md new file mode 100644 index 0000000..7395523 --- /dev/null +++ b/03-DESIGN/01-to-be/11-a-board.md @@ -0,0 +1,55 @@ +--- +layer: to-be +status: designed +code: [] +updated: 2026-08-30 +decisions: + - 02-DECISIONS/0008-a-context-owns-its-store.md + - 02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md +--- + +# A board + +**A place to see the mesh.** Read from a survey of the one that exists, so what is proposed here +is a shorter list than what is there, deliberately. + +## What the existing board does, and what of it belongs here + +Eight sections. Four are about work and workers and are held back with the rest of that domain; +the other four are about the mesh itself. + +| | what it shows | where it stands here | +|---|---|---| +| **the mesh** | every node, what each runs, what each takes from another, module versions | **everything behind it exists** — it is a reader, not a second source | +| **builds** | a build, its stages, its log | needs the builder | +| **sessions** | model sessions, their usage, and switching between accounts | [ADR 0024](../../02-DECISIONS/0024-model-access-is-a-provision.md) | +| **channels** | nodes messaging each other | the agent layer | + +## The constraint that matters, and it is not a feature + +**The existing board is one service that reads every context's database.** It joins nodes to +provisions to modules to sessions by querying each store directly, because that is the shortest +path to a page that shows all of them at once. + +That is [ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md) violated by the one +component with a reason to violate it, and the cost is not hypothetical — it is the same cost the +shared library has: **a boundary nothing may cross is a boundary that can move; one thing crossing +it is enough to freeze it.** A board that reads the provisioning tables directly is a board that +breaks when provisioning changes its tables, and the change then gets weighed against the board. + +**So a board reads through interfaces and holds nothing.** Everything on the mesh page above is +already answerable by asking the control plane — what nodes exist, what each resolves to, what it +takes from elsewhere, which module came from which commit. A board that asks those questions is a +client. A board that queries `inventory` is a second control plane with a worse contract. + +**It stores nothing of its own.** No cache that can disagree, no table of "what the mesh looked +like last time". If a question is slow to answer, the answer belongs in the context that owns it, +where everything else asking gets it too. + +## What it is not + +- **Not the way to change things.** Reading is the whole of it to begin with. Every action the + board could offer already exists as a command, and a button that does something no command does + is a second implementation of a decision. +- **Not a dashboard of graphs.** What a person needs from a mesh is *which machine is not doing + what it was told*, and that is a list, not a chart.