jschoubben
e1febe8e0f
The consolidation left a sparse sequence -- 1, 4, 6, 7, 9, 10, 12, 15, 16, 18, 19, 25, 34, 35, 36, 37, 40, 42, 44, 45, 48, 49, 58 -- where the gaps were only the archaeology of what used to be there. Renumbered contiguously. Renames run in ascending order, so every target number is already free and no two files ever collide. The reference rewrite is one simultaneous pass rather than a sequence of replacements. Numbers moved into slots other numbers were vacating -- the node host went 37 to 16 while the lab went 16 to 9 -- so replacing one at a time would have cascaded and silently pointed things at the wrong record. Seven plain-text references survived the merges as prose rather than links, naming records that no longer existed: the enrolment token, the link boundary, what a declaration is, reachability, the repository structure. Each mapped to the consolidated record that now holds it. Verified rather than assumed: every [ADR NNNN](path) link now has matching text and target, checked across the whole repository, and the checker passes. Frontmatter `consolidates:` lists dropped -- they named records that are gone, and each consolidated record already says in prose what it absorbed.
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
|
|
- 02-DECISIONS/0023-delivery.md
|
|
---
|
|
|
|
# Interfaces and observability
|
|
|
|
How the mesh is reached, and how anyone can tell what it is doing.
|
|
|
|
## Capabilities are the primary interface
|
|
|
|
The mesh's primary interface is not a web console. It is a set of **capabilities**, exposed to
|
|
a session and callable in language.
|
|
|
|
A capability is contributed by a module and is available on any node, wherever it actually
|
|
runs: local ones directly, remote ones through a stand-in created at startup that forwards over
|
|
the broker. The caller does not know the difference, and the credentials never move.
|
|
|
|
This is the mesh's stated vision made concrete — an agent states an intent and the mesh works
|
|
out which node holds the thing. It is also why a capability's **schema** is load-bearing in a
|
|
way that is easy to underestimate: a parameter name that collides with the transport's own
|
|
reserved names breaks the call, and a validation-library version mismatch has silently dropped
|
|
every argument while the call still appeared to succeed.
|
|
|
|
## The board
|
|
|
|
A web interface presents the mesh — nodes, modules, pipelines, agents, work. It is a **view**.
|
|
Its own guidance is that shared logic belongs in the mesh's library rather than inline in the
|
|
board, precisely so the board does not quietly become a second implementation of the mesh's
|
|
rules.
|
|
|
|
## Public exposure
|
|
|
|
Nodes carrying a public name run a reverse proxy as the sole entry point. A module declares the
|
|
names its interfaces answer on, portably, and the proxy's configuration is **generated** from
|
|
those declarations rather than written — generated files are marked as such and anything
|
|
hand-written beside them is left alone.
|
|
|
|
Nodes without a public role use a local equivalent with locally-trusted certificates. The
|
|
generation step degrades quietly on a node with no proxy, which is intended and is one more
|
|
place where "nothing happened" is the correct outcome and looks identical to a failure.
|
|
|
|
Certificate issuance currently always targets the public authority's production endpoint,
|
|
which consumes real quota for every experiment
|
|
([`04-ISSUES/004`](../../04-ISSUES/004-certificate-issuance-targets-production/00-report.md)).
|
|
|
|
## Health
|
|
|
|
Nodes run checks and report. The mesh's health surface answers whether things are up.
|
|
|
|
What it does **not** answer is whether they are correct, and that gap is the recurring theme of
|
|
this whole system: the deploy path reports transport rather than effect, so absence reads as
|
|
success. A check that confirms a service is running does not confirm the service is running the
|
|
code that was just deployed, and a node has been left on old code with a version marker that
|
|
had already advanced.
|
|
|
|
## Thoughts
|
|
|
|
Every node's daemon runs a periodic loop that surfaces observations from that node's own
|
|
context. They are stored in the mesh and can inform a session or trigger action.
|
|
|
|
It is the one part of the mesh that is not request-driven — the mesh noticing things rather
|
|
than being asked.
|
|
|
|
## The honest summary
|
|
|
|
Observability tells you the mesh is **up**. Establishing that it is **right** currently means
|
|
reading the operational record and checking by hand.
|
|
|
|
That is the gap the lab is designed to close
|
|
([`01-to-be/01-end-to-end-testing.md`](../01-to-be/01-end-to-end-testing.md)): a place where a
|
|
change can be run end to end and a verdict produced, cheaply enough that producing one is
|
|
routine.
|