jschoubben
418261213c
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/delivery superseded: a newer head of the same pull request
ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy. The records and efforts are removed; every link or path to them reads "ADR NNNN" or "research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer README with the reading order's six topics, which the knowledge base reads through the records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that judged records (the knowledge base holds each at propose; checks/README.md says where) and refuse a record written here again. Playbooks 01 and 02 and the skills write and read records with the knowledge base's verbs.
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- "ADR 0002"
|
|
- "ADR 0010"
|
|
---
|
|
|
|
# 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 dashboard. 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.
|