The missing applier. mesh-control already derives a node's whole nftables rule
set from the union of its modules' listens and writes it to /etc/nftables.conf;
this module declares filtering:{into} to receive it and loads it — the nftables
service, reloaded on 'filtering' whenever the rules change. A firewall_rules
tool reads the live table so a declared scope can be checked against what is
really enforced. Closes the loop from listens.from to a packet actually dropped.
Manifest parses; tool typechecks.
The mesh's resolver is more than config after all. Tools: dnsmasq_names (what
this node answers, from the generated wildcard file) and dnsmasq_resolve (resolve
a name through this node's own resolver — the check that wildcard-resolution
actually answers). Event: it watches the wildcard file and emits
module.dnsmasq.name.added/.removed as machines' names become resolvable here —
DNS having propagated to this node, distinct from the mesh's node.* events.
Typechecks; manifest parses.
searxng: a search tool — tools-only, a stateless search has nothing to observe.
icecast: status tool, emits stream.started/.stopped by diffing live mountpoints.
photos: status/albums/recent tools, emits item.added (immich-shaped API, coded
defensively since the stub ships a placeholder image — flagged in the code).
Typecheck; manifests parse.
registry (docker v2): catalog/tags/delete tools, emits image.pushed (a build's
image is now pullable). verdaccio (npm): list/info tools, emits
package.published. portainer: endpoints/stacks/containers tools — tools-only,
since its only events are the underlying containers' lifecycle, which the host
owns. Typecheck; manifests parse.
home-assistant: states/call-service/config tools, emits state.changed bounded
to actuator/contact domains (not attribute ticks), overridable via a watch
allowlist. influxdb: health/buckets/flux-query tools — tools-only, since a
time-series DB has no lifecycle event to emit here. Typecheck; manifests parse.
nzbget (usenet, JSON-RPC) and qbittorrent (torrents, WebUI API with manual SID
session). Tools: status, queue/torrents, add, pause/resume, delete. Both poll
and emit module.<app>.download.added and module.<app>.download.completed — the
key plex consumes to rescan; completion is keyed off real success (nzbget
history SUCCESS, qbittorrent progress reaching 1), not mere queue disappearance,
so a failed or deleted item is not reported as done. Typecheck; manifests parse.
Ported their real HTTP APIs (hal carried no client for these). jackett: an
indexer proxy — tools only (list indexers, search), no events, no broker
account, because it answers queries and has no timeline to observe. bazarr:
subtitle tools + emits module.bazarr.subtitle.downloaded (poll history, diff).
ombi: request tools + emits request.created/.approved. All pure emitters
(their decisions originate here). Typecheck; manifests parse.
redis provides redis-cache: a real admin client speaking RESP over a raw socket
(node:net, no deps); provisioner makes a keyspace-scoped ACL user per grant.
postgres provides postgres-database: admin client executing through psql (the
consistent shell-out port, like minio's mc), full DDL for create/drop database+
role, a CSV row parser, read-only query tool. Both emit
module.<x>.<thing>.provisioned/.deprovisioned from the provisioner. Both
typecheck; manifests parse.
Object store, an s3-bucket provider. Client ported with no npm deps: S3 data
plane over fetch + SigV4 (node:crypto), scoped access keys via the mc CLI (the
admin API needs an Argon2 payload node built-ins can't make — the honest port
hal also used). Tools: list buckets/objects, bucket info, presigned url. The
provisioner makes a bucket + scoped key per grant and emits
module.minio.bucket.created/removed (the secret stays off the bus). Typechecks;
manifest parses.
(Trimmed the generated self-consuming ledger: a provider need not subscribe to
its own emits.)
The Servarr apps (TV, movies), each self-contained from hal's shared arr
client. Tools: status, library, search, queue, calendar. Events by polling the
download queue: a new item emits module.<app>.<thing>.grabbed, an item that
leaves as completed emits module.<app>.download.completed — the exact key plex
consumes to rescan. A grab that left as failed/warning is not reported as a
completion. Both typecheck; manifests parse.
Git hosting. 15 tools (repos, issues, PRs, labels, api passthrough) moved out
of the shared sdk. Emits repo.created (from a light poll, catching repos born
of git push or the web UI), issue.opened and pull.merged (from the tools at the
moment of the action) — the poll owns repo.created alone so it is never
announced twice. Typechecks; manifest parses.
Identity provider. 22 admin tools (realms, users, clients + secrets, groups,
roles) over the admin API, moved out of the shared sdk. Emits user created/
deleted, password reset, client/group/role created — from the write tools
themselves, since Keycloak's value is the changes it makes, not pollable
state. Consumes nothing: it is upstream of everything that authenticates
against it. Typechecks; manifest parses.
Email server. Users/aliases/domains over the admin REST API, mail read via
doveadm in the imap container; ten tools. Emits user/alias created/deleted by
polling and diffing the admin API, so a change in the web admin is announced
as readily as one via a tool. Consumes nothing — deliberately, since mutating
mail accounts off another module's event could silently lose mail. Typechecks
against the sdk; manifest parses.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
Moves plex's API client and tools out of the shared hal sdk into the module,
so a Plex API change rebuilds only plex. Tools: status, search, sessions,
recently-added, refresh. And a real event design: it emits playback
started/stopped and item.added by watching the server, and consumes
module.*.download.completed to rescan so a downloader's fetch becomes a
visible item. Typechecks against the sdk; manifest parses with its emits/
consumes and broker own-secret.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
A container resource takes a digest-pinned image, not a build artifact — the
host refuses 'artifact' on a container. Verified: the mesh assigns it and the
host runs it in the lab.
Now a real assigned module, not just a handler: consumes '#', declares its
broker own-secret, and runs the runtime image as a container that mounts the
sealed credential and its trail. own-secrets:{broker} is the file the mesh
seals it (module issue); the container reads MESH_BROKER_FILE from the mount
and takes its node/module identity from the credential. Parses against the
catalogue schema.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
The trail's id is now the event's x-event-id — the handle a reader dedups
the at-least-once stream on — not the type@time placeholder the first cut
used. Carries causation/schema through when present.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
The universal consumer from ADR 0046 — no privilege, just a module that
consumes '#' and writes each event to an append-only trail. Its whole code
is on('#', record); the manifest declares consumes:['#'] and a log dir.
Records module.*, mesh.* and node.* events alike (ADR 0047's namespace).
Type-checks against @novox/mesh-sdk; the handler test records a module
event and a node event with their metadata; the manifest parses against
the consumes-enabled schema.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
umami is now a whole module, not a manifest: its own API client, its
tools, and its provisioner all live in the module and build on
@novox/mesh-sdk.
- client.ts — umami's API client, moved out of the shared sdk into the
module (ADR 0044); umami's tools and provisioner both import it.
- tools/ — umami_create_site / umami_delete_site on the sdk tool harness
(registerModuleTools); the tool logic and client are the module's.
- provisioner/ — the adapter making umami a provider of the mesh
'analytics' interface: a consumer contributes {domain}, receives
{siteId, snippet, dashboard}. ~20 lines, because the watch/seal/grant
loop is the sdk harness's.
Type-checks against the real mesh-sdk (tsc --noEmit clean); the manifest
parses against internal/catalogue. Remaining to actually run: build and
publish the module + its mesh-provision-umami-analytics image (the
placeholder digest), which is the pipeline's job.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
umami was only half a module: it required postgres but did not provide
what it exists to offer. It now provides the mesh 'analytics' interface
(ADR 0045) — a webapp requires analytics and umami's provisioner creates
its site and returns the grant — mirroring the postgres provider pattern
(serves/receives/grants + a provisioner container that adapts umami's API
to the mesh contract).
Also: split the listen (one port, two surfaces — the mesh-gated dashboard
and the public collection endpoint browsers POST to, hence from:anywhere),
and an admin own-secret for the provisioner to drive umami's API.
Parses against internal/catalogue. Still to build: the provisioner image
(mesh-provision-umami-analytics — the adapter, real code like
postgres-provisioner; placeholder digest for now) and umami's tools/client
in the module (ADR 0044), which need the sdk harness.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
Each module becomes modules/<name>/ holding module.json, with room for
the rest of what a module is — its tools, health checks, provisioning,
lifecycle — which the conversion from hal still has to bring across.
The flat <name>.json was only the resource-declaration half.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
Thirty modules the mesh builds, provisions and runs, as manifests — one
per module, flat under modules/. They were in mesh-control/examples/,
which framed the mesh's real modules as illustrations of a control-plane
package; they are neither examples nor the control plane's. The engine
that reads them stays in mesh-control; the data lives here, consumed as
a build source.
Answers the tier-4 question novox/hq ADR 0030 left open — where the
catalogue lives — in favour of one flat repository, which the drop of
domain grouping (seats, claims and tags instead) makes the right shape.
Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
jschoubben