ADR 0436 §1's ban on root and the operator account for a bus process ended, so design 20 now says whose own secrets are, the validator's two rules in their place and how each is checked; zfs-owns-zfs A-37 notes its premise ended.
28 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| to-be | proposed |
|
2026-11-18 |
|
Writing a module
A worked guide: what a module is built of, the manifest form of each part, and the packages it publishes.
The reference for what a manifest may say is the manifest validator, the rules of the seat mesh-catalog's holder
that judge every manifest (ADR 0578 §1), with design 32 for what the bus makes of it;
the reference for how a build is modelled is design 18; the reference for what the code
and the mesh say to each other is design 19. This is how you actually write one.
First: what is in the SDK, exactly
The protocol, and nothing else (ADR 0074). An SDK is an implementation of the module protocol in one language. If something is not in the protocol it does not belong in an SDK, and that rule is what stops it becoming the 34,000-line shared library this design exists to avoid (ADR 0039).
Split the way the protocol is split:
| the SDK gives you | so that you can |
|---|---|
| connection — reads the sealed credential, pins the certificate, takes your identity from it | reach the broker as this module on this machine, and not be able to claim otherwise |
| events — emit, subscribe, the envelope, dedup | react to what happens in the mesh |
| tools — register and serve | be asked questions |
| provisioning — receive a grant, return a credential | give a consumer an instance of what you provide |
What it does not give you, deliberately:
- No configuration loader. Configuration arrives as files the mesh wrote and environment the mesh set. Reading a file is not a thing an SDK needs to teach.
- No API clients. A Plex client belongs in the Plex module. It changes when Plex changes, which has nothing to do with any other module — frequent and cascading is the disease. Logic over a seat is not such a client: it is the seat's client package, in the seat's contracts module (below), never in the SDK and never in a holder.
- No storage, no HTTP framework, no logging library. Use the language's.
If you find yourself wanting to add something to the SDK, the test is ADR 0039's: does editing it recompile unrelated modules, and does it change often? Both, and it does not belong. It goes to its owner instead: a seat's contract or client, the module that owns it, or its domain's SDK (Where a seat's code goes, below; ADR 0634 §1).
Where a seat's code goes
Added 2026-11-04, widened 2026-11-05 (ADR 0625, ADR 0627, ADR 0634, ADR 0635; design 26 Where a seat's code goes is the whole rule). Shared code lives with its owner (ADR 0634 §1): a module that calls or holds a seat, or shares code with other modules, meets these places, and each piece of code has one, the first that fits:
| the code | lives in | written |
|---|---|---|
| a seat's types, subjects, the layouts of its states and a typed call per verb or accept | the seat's contract: a package of its own per language in its domain's contracts module (mesh-<domain>-contracts, or mesh-contracts for the Core domain and a domain with none), for a seat defined whole; a seat at the seat list's grain has only its definition, which every reader reads from the bus (ADR 0635 §1, §2) |
generated from the seat's definition, never by hand |
| logic two or more callers or holders would otherwise each write over that seat (an ask and its awaited answer, publishing a file in parts to a registry) | the seat's client package, beside its contract, owned by the contracts module | by hand; it uses only its own seat's contract, mesh-sdk's runtime and its own domain's SDK, never another seat's client, and names no holder, no module's tool and no module's subject |
| logic and state layouts one module owns, where it holds no seat for them | that module's own package, which other modules import from it: by path in the same repository (ADR 0609 §2), by a published version from another (ADR 0573 §1), so its manifest declares it as a package artifact; its fingerprint counts only that package's files (ADR 0593 §2), so its importers rebuild only when it changes | by hand, in the owner module |
| logic and forms no seat carries and no one module owns, used by one domain's modules or seats only (moving a file in parts, the build steps' shared logic) | that domain's domain SDK, mesh-<domain>-sdk, a package-only module (ADR 0634 §2) |
by hand; it imports only mesh-sdk and contract packages, names no module's tool or subject, and holds no seat's type or state layout |
| what every module needs whatever the seat (the bus connection, the tools bundle's runtime, state), and a part modules or seats of more than one domain share that names no seat, verb or seat's type | mesh-sdk | by hand; it takes no seat-specific type, imports no contracts module, and reads the seat list from the bus |
| the seat's implementation | the holder module | by hand, against the contract; never the place of the contract or a client |
So a module imports the contracts and clients of the seats it uses, the packages of the modules whose state it reads, its domain's SDK where it uses it, and mesh-sdk. Its users rebuild when something they use changes, not when any seat or any domain does. A seat you define yourself, outside the mesh's own contracts, gets a contracts module of its own, which may share your holder module's repository (ADR 0625 §7): a second holder then imports only the contract, never your holder. A contracts module and a domain SDK are modules like any other, found by their manifests in folders of a repository and delivered to no node (ADR 0634 §8). And a role no other module could ever take over is no seat at all: it is your module's own tools and events (ADR 0625 §8).
How it is checked: by the checks design 26 lists: the generators' tests, mesh-sdk's import and package-list tests, the build modules' regenerate-and-compare step, the catalog check of a client and the manifest validator's refusal of a contracts module that claims a seat; the home of each new exported name, a domain SDK's importers included, and a role made a seat or a seat left as one module's tools, by the review of the pull request that adds it (ADR 0634 §10).
Who reads a manifest, and what each one judges
Rewritten 2026-11-12 from the manifest validator's code on mesh-delivery's main (the operator, 2026-11-12: "first look into the indexer's code that reads the manifest and update our module-development documentation accordingly").
A manifest is read by four parts, and each judges only what is its own:
| part | reads | judges | where a refusal is said |
|---|---|---|---|
the manifest validator, the rules of the seat mesh-catalog's holder (the indexer) |
every manifest it takes in, and every manifest a change touches, at the change's head | the manifest strictly: every field known, at every depth; every rule a manifest is held to alone (a name's form, an artifact's words, a claim on a seat of the seat list, kept data, events, secrets, health, a container's run-once, schedule and while-stopped) and every rule between the manifests of one catalog |
the change's check, naming each problem; and the indexer's verdict, which every other part takes (ADR 0578 §1, §2) |
| the builder and its build modules | build |
which build module builds each artifact (kind and language) and whether an upstream reference is pinned by digest (ADR 0478, ADR 0498) |
the build's refusal, naming the artifact |
| the node-engine, through its composer in the change's composition step and on each node | the resources of each module composed for one node | each resource's type and fields strictly, by the node-engine's vocabulary (mesh-sdk's declaration package): a field a type does not use is refused, never ignored, and an action is refused (ADR 0005) |
the composition step of the change, for each machine the change touches; the node's verdict at apply |
| every other part (the assigner, the grants part, the tool runner, the provisioner) | the manifest, decoded leniently | nothing: it takes the indexer's verdict (ADR 0578 §3) | — |
A field the running manifest validator does not know makes the indexer set the manifest aside to wait for a newer validator; the change's check, which runs the validator built from the change's head, refuses it (ADR 0578 §1, as changed). So a field is added to the validator in the same change that first writes it.
The manifest validator does not judge a resource's own fields: those are the node-engine's vocabulary, judged where a module is composed for a machine. A module assigned to no machine is therefore judged by the validator alone.
What a module is built of
A module is one piece of software (ADR 0040), and may be built of several parts. Each part is an artifact in
build.artifacts, named locally, and most are run by a resource in resources that names the artifact by its
artifact field: the resolved manifest names the artifact's digest where the repository's manifest names the
artifact (a source and a digest for a bundle or an archive, an image for an image).
The artifact kinds the manifest validator accepts are five, and a builder builds each with one build module:
| kind | its words | built by |
|---|---|---|
bundle — the module's own code |
language; for Go also system (one of the systems the mesh builds for), from (the package it compiles, relative to the module) and binary; for TypeScript entrypoints and, where it keeps imports, external; loads, env and bus for a tools bundle (below); paths for a language other than Go |
the Go or the Node build module: a bundle in Go or TypeScript (ADR 0478); a bundle in another language is a build module of its own first |
package — code other modules compile against |
language (Go or TypeScript), series, paths (the files it is built from, ADR 0499), generated-from for a contracts module's |
its language's build module, which asks the registry seat of its language to publish it (ADR 0605 §3, ADR 0606) |
image — a container image built from a recipe |
from (a Dockerfile), target, compiles (the Go package a recipe compiles, ADR 0267), context (a second repository its build reaches into) |
the image build module |
upstream — somebody else's image, copied |
from, a reference pinned by its digest (@sha256:) |
the image build module (ADR 0498 §4) |
archive — files packed as they stand |
from (a directory of the module), or an upstream release by url, sha256 and version, with file or within (ADR 0316) |
the Go build module |
Every artifact may also say needs (an edge no other line says), and every kind but upstream its series. A bundle reached by nothing (no
loads, no tools, no resource naming it) is refused by name (issue 216); a resource naming a package is refused,
since a package is a build input and runs nowhere.
The parts, and the manifest form of each:
| part | the manifest form | what runs it |
|---|---|---|
| tools | a bundle with loads naming what the runtime loads (for a Go bundle its binary), and the module's tools listing every tool it serves; replaces for the shell commands a tool replaces |
the node's tool runner (ADR 0175); with runs-as, a runtime of its own under the module's account (below) |
| a long-running service of its own code | a process resource: artifact (a bundle), name (what the unit is called), run (the command, relative to the unpacked bundle), user, env and env-file, restart-on, health, yields, replaces (the ids it takes over from) |
the node-engine, as a unit that stays up |
| its own bus account for a process | the process's bus: the emits, state, queues, invokes and asks it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the account the process runs as, whatever that account (ADR 0680 §1; Whose a process's own secrets are, below) |
the grants part composes the account from it |
| a scheduled job | a process or container resource with schedule, a five-field cron; never with run-once; a process with no restart-on, replaces or witness; a scheduled container may name while-stopped (below) |
the node-engine, again on each fire (ADR 0053) |
| a one-time step (a seed, a first-start step, a validator of a file) | a process or container resource with run-once true: a run-once step, which gates every resource after it; restart-on makes it run again when what it names changes (ADR 0052, ADR 0099) |
the node-engine, to completion |
| a migration of its own state before a new version runs | prepares true, and a container or process that stays up running an artifact the module built: the mesh runs that program in its preparation mode (ADR 0135); never a run-once step written by hand for it |
the node-engine, before the new version starts |
| a seat's implementation | claims, each {name, scope, serves} for a seat on the seat list (the verbs it serves; a kinded seat's kind); a seat the module defines for itself in seats; the verbs answered by its tools bundle or a process |
as its tools or its process |
| an image | an image or upstream artifact, and a container resource naming it by artifact; or a container naming an image pinned by digest in image directly, for an image the module does not copy; a container stays up unless it says run-once or schedule |
the node-engine, on the container runtime the module's capabilities name |
| a host program from the operating system | a package resource (package, absent) and a service resource per unit it ships (unit, state, boot, scope, restart-on, reload-on, health); never an action |
the node's package manager and service manager |
| files | file and directory resources (a directory by place or path), an archive resource unpacking an archive artifact, template files in the module's templates directory |
the node-engine and the provisioner client |
Whose a process's own secrets are (ADR 0680). Amended 2026-11-18. Every own secret a process reads, its bus
credential first, is owned by the account that process runs as, whatever that account is: an account the module
makes (a user resource of that name), the operator account (${machine:account}), or root (ADR 0680 §1). The
manifest names it, as the secret's owner or the module's secrets-owner, and the process runs as it (its user)
or as root, as the second rule below holds; the node-engine writes the secret owned by it at mode 0600 (ADR 0680 §1). An account the module makes stays
the usual case, not a rule; a process that declares bus still names the account it runs as. ADR 0436 §1's "never
root and never the operator account" no longer holds for a process that declares bus, and the manifest validator's
two rules that refused them (as an own secret's owner and as a bus process's account) are gone (ADR 0680 §2). The
manifest validator holds two rules instead:
- Every account named is one the mesh knows. An own secret's
owner, asecrets-ownerand the account of a process that declaresbusare each the operator account, root or an account the module makes; any other is refused, and so is abusprocess naming no account (ADR 0680 §2). - A process can read every own secret it names. A process resource that names an own secret (its path in the
process's
runorenv) and runs as neither that secret's resolved owner (itsowner, elsesecrets-owner) nor root is refused (ADR 0680 §3). A container module is excepted, since a container reads its secrets as its own account, and a process account's secret needs no such rule, since it is delivered owned by the process's account (ADR 0436 §2).
A secret owned by the operator account is as private as what runs as that account on its node: the node's tool
runner, and through it every agent session there (ADR 0436 §9). That exposure is accepted (ADR 0680 §1); what bounds
a process account's credential is its grants, which answer no tool and no seat's verb (ADR 0436 §3). A module's
runs-as is unchanged: it names an account the module makes (ADR 0259 §8, below).
How it is checked: the node-engine's tests write an own secret owned by the account its manifest names, at mode
0600, for an account the module makes, for the operator account and for root; the manifest validator's tests, run on
every change of the validator and over every manifest a change of mesh-catalog touches, accept an own secret owned by
${machine:account} or root, a bus process running as either, a process running as the resolved owner of the own
secret it names (also through secrets-owner), a process running as root, and a container module naming another
account's own secret, and refuse a bus process naming no account or one the module does not make, and a process
naming another account's own secret; the controller's grant test still finds no process account able to answer a
call (ADR 0680 §4).
A runtime of its own. A module that says runs-as names an account it makes (a user resource of that name,
never root nor the operator's); its tools bundle is then served by a runtime of its own, as that account, on a bus
account of its own (ADR 0259 §8), whose readiness is the manifest's runtime-health (ADR 0366). Its secrets belong to
that account (secrets-owner), and its bus account's secret is the own secret broker. A tools bundle that holds an
account of its own instead says bus on its artifact, a Go bundle only, with the own secret broker-<binary> in a
directory the runtime's account may pass (ADR 0564).
What it keeps on the bus. Kept data is asked for in requires, each entry in its long form: name (a local name,
lower-case letters, digits and hyphens), storage (key-value, stream, object-store or ledger), template
(state, events, work-queue, log, objects, ledger) and its options, or a bare stream's configuration
(ADR 0595 §1 to §3). The manifest validator holds each option to its bound. The old sections state, logs,
streams and objects are kept by the parts the bus module needs before it can answer, and by no new entry
anywhere else: those parts ask nothing by template, and any other module's use of an old section is refused once no
accepted module outside them uses that section any more (ADR 0619 §1, ADR 0595 §11). One local name is in one form.
A module reads another module's data by asking its tools or seat verbs, never by its bus state (ADR 0201, as changed
by ADR 0596).
What it says and hears. emits names its events locally; consumes names <emitter>.<event>, with * for one
name and ** for the rest; invokes names each tool <module>.<tool> or verb seat:<seat>.<verb> it calls, or *,
and an entry's long form {verb, fields} names the fields of the answer it relies on (ADR 0152); uses names the
seats it sends to; needs-approval marks a tool, verb or event that waits for the operator's approval.
What someone may change. Each config value a module reads is declared once under config (or its alias
settings, never both), with its type, its default where it is a preference, and whether it is trusted; a file takes
it by takes-config or a template file's ${config:<key>} (ADR 0262, ADR 0348).
How it is checked: the manifest validator's tests (mesh-delivery modules/mesh-delivery-indexer/judge) refuse each form above that a manifest gets wrong, by name; the builder's plan test refuses a kind or language no build module builds; the node-engine's declaration tests refuse a field a resource type does not use; and the showcase module in mesh-catalog declares one part of each kind its language allows and composes on a node.
The showcase, worked
The catalog's showcase module is the worked example: one TypeScript bundle, several entrypoints, every mode.
| part | artifact | resource | its words |
|---|---|---|---|
| the module's code | code, a bundle in TypeScript, entrypoints for the tools, the provisioner, the service, the run-once step and the report |
— | — |
| a run-once step | code |
migrate, a process |
run the step's entrypoint, run-once true, env-file |
| the service | code |
server, a process |
run the service's entrypoint, user the module's account, env-file, restart-on its settings file |
| a scheduled report | code |
reporting, a process |
run the report's entrypoint, schedule a five-field cron |
| a container from somebody else's image | helper, an upstream pinned by digest |
tools, a container |
network, volumes mounting its broker secret, args |
| packed files | files, an archive from a directory |
packed, an archive |
path, unknown |
| its settings file | templates, the module's templates directory |
settings, a file |
path, mode, template |
| a seat it defines for itself | — | — | seats, and claims of it |
Nothing in it says how any part is hosted beyond its resource type — that is the mesh's: the builder picks the toolchain from the language, compiles each artifact alone and publishes it, the assigner places the module, and the node-engine writes the units. A module in several languages is several bundles, each naming its own language and compiled alone; each language is one more build module the mesh must have, and one more set of dependencies to keep current. The reason to use two is that one genuinely suits a part better, not that you can.
Its code, in each language's own terms
Each part is an ordinary project in its language, depending on the mesh's packages the way it would depend on
anything, resolved from the mesh's own package registries, which are the ordinary registries for each ecosystem
hosted by the mesh (the registry seats, ADR 0605): npm install and go mod tidy work, and a developer's laptop
resolves what a build does. A Go module requires a mesh package at the zero version only: the builder builds
against the newest version of the package series the manifest's packages accepts (ADR 0573 §2, §4, ADR 0606), so no
member of a change names another's version.
Each part uses only the part of the protocol it needs: the event consumer never learns what a grant is, and a run-once step emits only.
Publishing a package is a capability
A module may publish libraries as well as run code. The SDK is not special; it is simply the first module that did this, and its own consumers are the mesh's modules.
A package artifact, in Go or TypeScript, is built from the trunk and published to the mesh's registry seat for its
language under its next version, <series>.<n>, which the builder counts (ADR 0606 §1 to §3); a branch's build is a
tagged version, taken only by a build that asks its tag (ADR 0607). Another module then depends on it the ordinary
way, accepting a package series by its manifest's packages.
Why this belongs to modules rather than being a separate thing. A client for a piece of software changes when that software changes, and the module that owns the software is the only thing that knows. Putting the Plex client anywhere else is the shared-library disease with extra steps.
What design 20 once left open here is decided: the registries are the registry seats (ADR 0605), who publishes is the build module of the package's language, and a build resolves a series, never a range, recorded as its build edge (ADR 0606, ADR 0573).
A file and the thing that reads it are guarded by a gate
Written 2026-09-21, from resolving 04-ISSUES/066.
The apply is not a transaction: every resource is attempted, every failure reported, and only a
failed gate stops what follows it (ADR 0053).
So a send can half-happen, and the pairing that matters is a configuration file beside the
service that reads it. A module keeps that pair correct by declaring them in this order: the file;
a run-once step (a run-once container or process) that validates it; the service, with restart-on naming the
file. A file the validating step refuses reaches the disk and nothing else — the gate fails, the service after it is
left as it was, and the machine reports the send failed. The service never serves what the
step refused. That is the grouping, made from what the manifest already has; no primitive
withholds a file from the disk, and a service that reads its file live rather than at start is the
one shape this does not protect, and should not be written.
How it is checked: the lab's coupled-pair spike declares exactly this pair, sends a refused file, and asserts the file on disk is the new one, the service serves the old one, and the machine reports the send failed.
A run-once step may itself name what it reads under restart-on; for a run-once step the word means
run again — a step that fetches a fact from a provider names the binding it reads, and runs
again when the provider moved. The service that consumes what the step made names the step, so it
is recreated with the new fact
(ADR 0099). How it is
checked: the node-engine's unit tests run a run-once step again when its named file changed and not otherwise,
and recreate a container naming a run-once step after it ran.
A scheduled run may hold its own module's containers still
Written 2026-10-02, from ADR 0189 and issue 108.
Some work cannot be done underneath a running service: an artifact store's collector rollouts the storage and requires every writer stopped. A run-once step runs beside containers and a scheduled run is the same container again, so until this a module had no way to say it — and the mesh inherited a store that has never collected anything, because the predecessor said it with a shell script and a script beside a module is not a resource in it.
A scheduled container may name while-stopped: resource ids of its own module's containers, which
the node-engine stops before the run and starts again after it, in the reverse order, whatever the run
did. Three boundaries, each refused where it can be seen earliest — its own module's containers
only, because a module that could quiesce a neighbour could stop the mesh; scheduled runs only,
because at apply the declaration is applied in order and a run-once step already gates what follows, so a
one-time offline job says before rather than instead of; and restoring that is not conditional
on anything, because the only real risk of the field is a window that never closes.
How it is checked: the node-engine's unit tests assert stop–run–start in that order, the restart after a run that failed, the reverse order for several containers, and a service left down said loudly. The manifest validator refuses, from the manifest alone, a window with no schedule, one on a run-once container, one naming a container the module does not declare, and one naming itself.
Acceptance
- A manifest written by this design's tables is accepted by the manifest validator, built by the builder and composed by the node-engine for a machine, with no form one of them refuses: checked by the showcase module's check on every change to it.
- Every refusal names the module, the part and the field, where its author reads it: the change's check.
Milestones
None of its own. This design is the guide every module's change follows; a change to what a manifest may say is a decision and a change of the manifest validator, the builder or the node-engine first, and this design follows it.