Files
hq/03-DESIGN/01-to-be/20-writing-a-module.md
T
jschoubben 180a096a3e Follow ADR 0680 in design 20: a process's own secrets belong to the account it runs as
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.
2026-11-18 01:09:07 +01:00

28 KiB
Raw Blame History

layer, status, code, updated, decisions
layer status code updated decisions
to-be proposed
mesh-catalog modules/showcase
mesh-delivery modules/mesh-delivery-indexer/judge (the manifest validator)
mesh-delivery modules/mesh-delivery-builder
mesh-sdk go/catalogue (the manifest's shapes)
mesh-sdk go/declaration (the node-engine's resource vocabulary)
mesh-contracts
2026-11-18
ADR 0680
ADR 0578
ADR 0595
ADR 0619
ADR 0634
ADR 0635
ADR 0625
ADR 0627
ADR 0573
ADR 0605
ADR 0606
ADR 0607
ADR 0609
ADR 0593
ADR 0499
ADR 0498
ADR 0478
ADR 0436
ADR 0366
ADR 0316
ADR 0267
ADR 0259
ADR 0262
ADR 0348
ADR 0564
ADR 0596
ADR 0201
ADR 0193
ADR 0192
ADR 0189
ADR 0175
ADR 0152
ADR 0150
ADR 0142
ADR 0135
ADR 0099
ADR 0074
ADR 0053
ADR 0052
ADR 0040
ADR 0039
ADR 0005

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, a secrets-owner and the account of a process that declares bus are each the operator account, root or an account the module makes; any other is refused, and so is a bus process 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 run or env) and runs as neither that secret's resolved owner (its owner, else secrets-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.