036 — The target: a mesh that happens on the bus

This is where the gaps in 01-evidence.md point. It is a picture to test proposals against, not a design. Each paragraph names the gap it answers.

Every link between modules is a subject

A module owns its state: its files, its database, its container. It is reached only by its tools, its seat's verbs, its events and its buckets.

No module acts on another's container, socket or files. A store module serves its own dump. The registry says what it holds. The resolver's verbs are called over the bus like any other seat's. A download client answers whether it is reachable with a key (G5).
Every act is grantable. Because every act is a subject, the bus can refuse it, and the controller can say who may perform it.

The bus is not for bulk bytes, and two kinds of traffic stay off it by name:

Bulk bytes stay where they are. The bytes of an artifact and of a git repository, and an app using its database, keep their own protocols.
Who reaches them is decided on the bus. Where to reach them is a provision, and what exists is announced on the bus (G4).

Every important state is watchable

For each thing a person would look at, the owner keeps three things on the bus:

A bucket of current state, one key per thing: a node, an assignment, a plan, a build, a delivery, a setting, a licence, an open ask.
An event for each change, naming the thing and what changed. Another module can consume it, and a view can redraw from it.
A history stream, where the past matters, with a retention the owner declares (G8).

The store remains the owner's record where it needs one. The bucket is written from it on change, never instead of it. The open conditions already work this way. Plans, builds, nodes, assignments, settings and licences come next (G2, G6). A verb is still how something is asked or done. It stops being the only way to see.

Views are built from the bus

A view is a web page or a terminal UI that shows part of the mesh. View is proposed here as the glossary word for this. It has no backend of its own:

It connects to the bus over WebSocket, through the proxy, as the person using it.
It reads the buckets it shows, watches them, and subscribes to the events that explain a change.
It acts by calling the same tools and verbs an agent calls. A decision travels as an answer to an ask, carrying its proof, and the controller checks it (the approval flow, §6 of the evidence).

The person is admitted by an auth callout served by a mesh module. That module checks the person's login with the mesh's identity provider and issues a short-lived bus user. The user's grant is derived from the view's declaration: these buckets to read, these events to hear, these tools to call. No password is written into the server's file for a person, and a person's access ends when the credential expires (G1).

The bus survives a machine

Every machine runs a leaf node:

Local traffic stays local. A module's connection is local, and tool calls between modules on one machine keep working when the hub is away, as they must on a laptop behind a VPN client.
What must not be lost is replicated. The control-node's server is one of three in a cluster, and the declarations, the control stream and the controller's buckets are kept on three disks rather than one. The nightly snapshot remains the guard against our own mistakes, not against a disk (G3).

The bus watches itself

Server events become conditions. The nats module holds a system-account user and turns the server's own events into conditions, like any other probe: a slow consumer, a permission refused, a client reconnecting in a loop, a consumer that nothing feeds.
Exhausted messages are kept. A message delivered as often as allowed lands in a dead-letter stream that a view can show (G7).
Nothing to rescue by paging. Answers stay within one message because views read keys, not whole lists (G9).

What is not wanted

No view with a database of its own that copies the mesh's state. That copy drifts, which is the thing the mesh exists to prevent.
No HTTP API on the controller beside the bus (G10).
No second signing hierarchy for its own sake. The callout issues users under the account the mesh already has, unless a separate account for people turns out to be the simpler grant.

4.4 KiB Raw Blame History