A module has exactly one durable consumer, and each subscribe() started its own reader of it. Two
readers split the stream between them, and a reader that receives a message its own pattern does not
match acknowledges it — which is the right answer for a filter wider than anything registered, and
silent loss when the message was another handler's. The first module to subscribe twice would have
dropped roughly half of each kind of event with nothing reporting it.
Every registration is now dispatched from one reader, and a message is acknowledged once every handler
it is for has taken it.
The runtime gains `prepare`, which brings this module's state to the shape this version needs and
exits (novox/hq ADR 0135). The entrypoints come from MESH_PREPARE, which a module's own image names
beside the entrypoints it already lists there — the module knows which of its files prepares its
state and nothing else could. No broker is connected: preparation runs before the version that would
use it. An empty list fails rather than passing quietly, because the mesh asks this only of a module
whose manifest says it prepares something, and exiting 0 would let that version serve against a
state nobody shaped.
Every user's inbox is private to it and the grant names it; a reply space the client invented was
refused, and with it every pull for the next message and every answer to a tool call.
Every module on the new runtime reached the handshake and failed on 'does not match
certificate's altnames': the bus's certificate names the seat, not the address a machine dials
it by, and pinning the exact certificate already decides everything a name check could. The
client's transport spreads the TLS options into Node's tls.connect, so the hostname check is
replaced with one that passes and the pinned certificate is the one authority accepted.
Every module that dialled the new bus failed its handshake with "wrong version
number": the runtime pinned the server's certificate by a raw TLS connection to a
port on which the server speaks first, in the clear. The pin is taken after the
INFO line now, on the same socket, and then the real connection verifies against
exactly that certificate.
And the old transport is deleted — its client, its tests, its dependency — with
the wire-compatibility pins that only existed for the move (novox/hq ADR 0131,
design 28 task 5.5). A credential names the bus, and there is one.
A module moved to the bus being built was handed a credential for it — nats://
with user, password and fingerprint beside the address — and nothing else in its
environment changed. The runtime always dialled the old bus, so every moved module
kept serving and answered nobody. The scheme in the credential is enough to know
which bus to speak; the nats broker was already written and never chosen.
Every module's event names were converted from the old bus's routing keys to local
names, and this client maps them back. If that mapping is wrong anywhere a live mesh's
events stop being delivered — silently, because a binding that matches nothing is not an
error.
So the mapping is pinned against the literal routing keys the mesh published before,
taken from the manifests as they were: what each module now emits, what each now binds,
and that a handler still matches what the bus delivers. Including the audit logger's
"everything", which must stay `#` on this bus.
And a key already in the old form is left alone, so a module built from an older manifest
keeps working beside one built from a current manifest — which is the state the mesh will
actually be in between deployments.
Design 25 §7's second item. Two surfaces over one thing — a command line for somebody
at a terminal, an MCP server for an agent — and both are adapters over the same three
calls: what tools are there, what does this one take, call it. A second way of reaching
a tool would be a second thing to keep correct.
It uses the client a module's runtime uses. Not a bridge and not a second protocol: a
person connects as their own bus user and publishes on the tool subjects their account
permits, so "what may this person do" is answered by the same permission list that
answers it for a module, and an audit has nothing separate to read.
`mesh tools` lists what the *catalogue* has, not what this credential may call. The two
differ and the difference is the point: somebody seeing only their own tools cannot tell
"not installed" from "not yours", and those need different people to fix them.
A failed call says which of three things happened, because the remedies are in three
different places: nobody serves that tool, this credential may not call it, or the tool
itself was slow. Without that they are one timeout and a stack trace.
The MCP surface decides nothing. The tool names are the ones a person types, the schemas
are the modules' own, and an answer is passed through unshaped — an adapter that
summarised somebody else's answer would be deciding what matters in it. A tool that fails
comes back as a tool error rather than a protocol error, because the request was
well-formed and the mesh answered it.
Written against the protocol directly: it is three methods and one framing, and a
dependency here would be a dependency on every workstation.
Tests drive both surfaces against a real bus, including that a host's notification is
answered with nothing and an unknown method is refused. They run one file at a time,
because each stands up a module serving the same tool subjects and run together their
requests get split between them — which showed up as one test reading another's answer.
A module names its events locally and each transport works out where they land.
That is what design 29 says and what neither client did: both passed the name
straight through, which happened to be right on the old bus because modules were
writing routing keys, and wrong on the new one (novox/hq 04-ISSUES/127).
The old bus's client now turns a local name into `module.<emitter>.<event>` on the
way out and back on the way in. Without that, converting the modules to local
names would have broken the mesh that is actually running.
**A handler and a manifest now say the same thing.** The key a module sees was the
event name alone, so a manifest declaring `consumes: builder.built` produced a
pattern that could never match what it was compared against — and a module
consuming one event from two emitters could only tell them apart by reading a
header. The subject already carries the emitter, so naming it in the key makes a
mismatch between manifest and code a typo instead of a category error.
Both matchers accept `**` for the rest of a name, which is how a manifest spells
it; the old bus's `#` still works, because both buses ship until the rollout.
Same cleanup: the comments explained each decision by contrast with what
came before instead of stating it. The certificate constraint stays — it is
a fact about the mesh's certificates, not a comparison.
Read back from the stream rather than from the client that wrote it, so the
check is what reached the wire. The runner lives with the implementation;
the fixture stays in one place.
Task 3.6 of novox/hq ADR 0116. A module is still written against request,
handle, publish, subscribe, close; only what is underneath changes. main.ts
still selects the AMQP client — steps 1 to 4 leave every node on AMQP, so
this ships beside it and is selected at the rollout.
Round-tripped against a real server (test/roundtrip.mjs): a tool answered
across two connections, a throwing handler reaching the caller as an error
rather than a timeout, an event delivered once with its key, body, node and
event id intact, and an event landing under its emitter's own namespace.
Three things the compiler and the server corrected:
- the envelope's field is `key`, not `type`, and the payload is `env.body`
with metadata in headers — not the whole envelope re-encoded. An
implementation that nested the envelope would pass all its own tests and
agree with nobody, which is what the conformance suite exists to stop.
- the NATS client's TLS options are PEM strings with no verify hook, so the
AMQP client's `checkServerIdentity: () => undefined` has no equivalent.
The fingerprint check still happens and is still the guarantee, but the
bus's certificate must now carry a SAN matching the address nodes dial.
That is a constraint on the mesh's certificates, recorded where it bites.
- a durable consumer is bound, never created: a module's account cannot
reach the JetStream API, and a runtime creating its own would be a module
choosing its own delivery semantics.
The retry loop treated everything but a cert-pin mismatch as transient,
so a refused login (revoked/mis-sealed credential) or a malformed broker
URL retried for ever logging 'not reachable yet' — the silent
non-progress the fix set out to remove, and a contradiction of its own
docstring. fatalBrokerReason now classifies those three as fatal and
everything else (connection refused, timeout, DNS) as retryable, with a
unit test covering the split — the honest proof the bed cannot give,
since it only ever starts the consumer after the broker is up.
The pin case is now a typed PinMismatchError caught by instanceof, not a
prose substring a reword could silently downgrade to an infinite retry
against an impostor. Added a little jitter so modules do not stampede a
recovering broker in lockstep.
At startup 'the broker is not reachable yet' is the normal case — a
container comes up in seconds, the overlay tunnel a moment later.
Exiting delegated the retry to the container runtime, which read as a
crash-loop to every restart-counting health check and every person
watching docker ps. Serve mode now retries with capped backoff, aloud,
indefinitely; a pinned-certificate mismatch still refuses at once, and
one-shot commands (emit, invoke, run) still fail fast.
One name per thing, per the HQ glossary: the module/container/image/binary/repo
becomes mesh-controller, the seat the-controller, and the store+broker pair the
foundation (embedded base bundles, default template and example lock renamed with
their go:embed directives). No behaviour change — a pure vocabulary rename.
Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
A machine's docker may carry no buildx, so --mount=type=secret cannot be relied
on. Instead a deps stage copies in the builder-written .npmrc, resolves
node_modules from the mesh's registry, and the toolchain stage copies those
node_modules out without the credential — so it is in no published layer.
Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
package.json names @novox/mesh-sdk by version and the install is a
buildkit-secret-mounted resolve from the mesh's package registry, closing the
git-URL half of issue 053. The lock is regenerated against the registry (a
follow-up switches install to ci with a committed lock).
Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
A module's recipe starts from this image and invokes the compiler out of it, so
the compiler had to be here. The same image was also what every module ran in,
so every running container on every machine carried a compiler it would never
invoke: 23 of the 28 MB of libraries. An earlier attempt to prune the build
tools produced a smaller image that nothing could be built on, and the comment
defending their return made a workaround look like a decision.
One recipe, because the two must agree about the operating system, the language
version and the library, and two files drift.
Two lines added to prove that changing this image makes everything standing on
it go stale. The proof worked and the lines were never meant to stay: nothing
reads MESH_RUNTIME.
Every module's recipe starts from this image and invokes the compiler out of
it. Pruning build dependencies made a smaller image that nothing could be
built on.
It declares the hook npm is supposed to run after a git install, and this npm
does not run it — so the package arrives as sources with every entry point
pointing at a compiled directory that is not there.
It copied in a compiled directory that is not in source control and resolved
the toolkit to a sibling checkout, so only a workstation with two repositories
side by side could produce it — and its fingerprint was then typed into every
module by hand. Nothing could rebuild it, so nothing could check it, and the
rule that catches a base moving had no version on the far end of its edge.
The recipe now also says what the image in service actually is. It claimed
Alpine and has been serving Debian for as long as nobody could rebuild it.
The run-once step of ADR 0052 reuses a module's runtime image but must run
its bootstrap/seed entrypoint offline and exit, not the broker-bound serve
loop. Add 'mesh-tools run <entrypoint>': import the compiled entrypoint,
await its top-level work, exit — no broker, so a first-boot seed runs before
the module has anything to talk to. Exit code is the step's, which is how the
host gates the container that depends on it.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
Replies go through the RPC exchange keyed by the caller's reply-queue name, not
the default exchange — so a serving module's scoped account answers with write
on mesh.rpc alone, never the default exchange (which would let it publish into
any queue). 'mesh-tools invoke <module> <tool> [args]' is the caller's side, the
sibling of emit. Verified against a real broker: a scoped account serves its
tool and is refused another module's serve queue.
The mesh scoped the account to a node and module; the credential now carries
both, so the runtime names its queue and stamps its events as the mesh
authorised without a manifest interpolating a node the vocabulary has no token
for. Verified: with only MESH_BROKER_FILE, the audit logger consumed as
anchor/audit-logger.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
A module reads its broker credential from MESH_BROKER_FILE — the sealed
{url,fingerprint} the mesh delivered — and connects over amqps pinned to
exactly that certificate. The pin is two-phase (fetch cert, verify, then
trust only it), because Node's checkServerIdentity does not run under
rejectUnauthorized:false, so a naive connect-then-check would already have
sent the password to whoever answered.
A scoped module (assumeExchanges) never declares the exchanges (its account
may not) nor its own queue with a dead-letter (the broker refuses that to a
non-administrator) — the mesh pre-declared the queue, so it passively checks
it, binds and consumes. The RPC reply queue is lazy, and a module that
registered no tools serves none: a pure-events consumer touches only what its
account allows.
Verified end-to-end against a real broker as the scoped account: the audit
logger consumes # and records events, over an account that is not the
broker's own.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
'mesh-tools emit <type> [json]' connects, emits one ADR 0047 event (awaiting
the publish confirm), and exits. The serve path already runs a module's
on('#') subscription as an import side effect, so the runtime hosts both an
emitter and the audit-logger consumer.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
mesh-admin
jschoubben