1.2. Compartments Architecture
1.2.1. Compartments: the subsystem/1 declaration and how a node is assembled
A fleetmesh node is twenty-three core compartments and nine optional ones. Each is a
Compartment, built from one NodeContext, registered in a declared tick
order, and read through the same four verbs (state, trouble, report,
command). This document is the contract a compartment is written against -
the one in the tree and the one someone writes outside it.
1.2.1.1. The compartments, in tick order
# |
compartment |
built |
|---|---|---|
1 |
|
always |
2 |
|
always |
3 |
|
always |
4 |
|
always |
5 |
|
always |
6 |
|
always |
7 |
|
always |
8 |
|
always |
9 |
|
always |
10 |
|
always |
11 |
|
always |
12 |
|
always |
13 |
|
always |
14 |
|
always |
15 |
|
always |
16 |
|
always |
17 |
|
always |
18 |
|
always |
19 |
|
always |
20 |
|
always |
21 |
|
always |
22 |
|
always |
23 |
|
always |
24 |
|
only with its config block |
25 |
|
only with its config block |
26 |
|
only with its config block |
27 |
|
only with its config block |
28 |
|
only with its config block |
29 |
|
only with its config block |
30 |
|
only with its config block |
31 |
|
only with its config block |
32 |
|
only with its config block |
Generated from MANIFEST in fleetmesh_node/app/core.py by
scripts/check-cli.py --write, which is also the tripwire: before this table
existed the document spelled its own count by hand and never named
discovery, p2p or gossip at all, and nothing went red for it
(audit 2026-10-07, C4).
1.2.1.2. One model, four words
There are two kinds of thing, not four:
word |
what it is |
where it is declared |
|---|---|---|
compartment |
a |
|
sidecar |
an external HTTP process the node fronts: a JSON manifest, not code |
|
“Built-in” vs “plugin” is who shipped the compartment, not a different
contract: meshnode plugin-check runs the same rules over node.budget:Budget
as over a third party’s class, and test_extensions.py holds every built-in
to it. “Optional” (enabled_by) is a built-in that is constructed only when
its config block is present. The subsystem/1 string is the wire name of this
contract (api, the subsystems verb, health.subsystems) and is kept as is;
the code name is fleetmesh_node.compartment (there is no node.subsystem module).
1.2.1.3. Why there is a contract
Before this, fleetmesh_node/app/core.py built every compartment by hand: twenty-four
constructor calls in six different signature styles, each handed node=self
so it could reach anything the signature forgot, and the order of those calls
was the tick order, policed by a regex in scripts/check-cli.py against five
documents that had each drifted at least once. Adding a compartment meant
editing the assembly function and knowing, from a comment, which others had to
exist first.
Now a compartment declares what it is and what it needs as class attributes,
says what it takes from the node in one classmethod, and is listed once in
MANIFEST. The assembler refuses a manifest that contradicts a declaration at
startup, with both names in the message, rather than three ticks in with an
AttributeError. The check script reads the manifest, not a regex over
source.
1.2.1.4. The declaration
class Reporter(FindingsMixin, PublishMixin, ReadingMixin, Compartment):
name: str = 'reporter' # the one word CLI/status/docs use
attr: Optional[str] = None # node attribute, when not `name`
requires: tuple[str, ...] = () # compartments built before this one
optional: bool = False # off unless `enabled_by` is configured
enabled_by: Optional[str] = None # the config key that turns it on
reads: tuple[str, ...] = ('projection',) # config keys read
live: tuple[str, ...] = () # of those, re-read every tick
api: str = 'subsystem/1' # the declaration version written against
protocol: str = '' # schema digest built against, or ''
@classmethod
def from_context(cls, ctx: NodeContext) -> 'Reporter':
return cls(ctx.ks, ctx.transport, ctx.stores.grants, ctx.relays,
ledger=ctx.ledger, clock=ctx.clock, timeout=ctx.timeout,
project=bool(ctx.cfg.get('projection', True)),
accounts=ctx.stores.accounts, node=ctx.node)
What each field means to the assembler:
name- required. Registration refuses a nameless class and two with the same name.attr- the attribute the node keeps the instance under, when it differs fromname(paidfetch→node.paid_fetch,settle→node.settlement). Defaults toname.requires- names that must already be registered when this one is built. Checked, not sorted: see “Order is a decision”.optional/enabled_by- an optional compartment is built only whencfg[enabled_by]is present and truthy (enabled_bydefaults toname). It sits in the manifest where it would tick; absence from config means it is skipped, not stubbed.api- a compartment written against another major (subsystem/2) is refused. Minor and patch differences are not. This is how a compartment built outside the tree says which contract it expects.protocol- optional. When set and the context carries adigest, a mismatch is refused: the compartment was built against a schema this node does not speak. Leave it''for a compartment that reads no schema.from_context- the one constructor the assembler calls. The base class default iscls(node=ctx.node), which is exactly right forSettlementandMediationand is the shim that let every unmigrated compartment keep building while the others moved.
1.2.1.5. What NodeContext carries
fleetmesh_node/compartment/context.py. A dataclass, built once in NodeApp.__init__:
field |
what |
|---|---|
|
the node directory and a file under it |
|
keystore; |
|
the live config dict, one key now, or the |
|
|
|
the node event bus |
|
|
|
the relay URLs this node uses |
|
the DIDComm transport, protocol router, relay face |
|
the peer table, peering policy, standing ledger |
|
the node’s default timeout and its stop event |
|
the kind 11801 once start() has it; raises before |
|
the schema digest this node speaks |
|
the NodeApp - a labelled escape hatch, see below |
|
|
node stays because three compartments reach for something that is a method
of the node and not a store: trust calls node.regrant, scheduler calls
node.propose and node.pull. Compartments that require another receive it
through ctx.node.<attr> because the assembler has already set it there. A
compartment reaching into ctx.node for anything else is naming a dependency
the context should carry; add it to the context.
1.2.1.6. Order is a decision
MANIFEST in fleetmesh_node/app/core.py is the tick order. The assembler validates
it against requires rather than topologically sorting from it, on purpose:
the relay journal ticks first, so a subscription that dropped is said before anything that depends on it; then the operator’s decisions, which outrank the ladder; then the mechanisms; then what the node publishes about itself; then the pulls, which are the only load it chooses.
None of that is in the dependency graph. A sort would be free to reorder
trust after budget, which is legal by requires and wrong by intent.
So the list is written by hand, with its reasons, and the assembler holds it
to the one thing it can check: nothing is built before what it needs.
Two edges run against tick order and are bound after assembly rather than passed at construction, because the assembler builds in tick order:
linkrecords a reconnect intostrain, but ticks before it →self.link.bind(self.strain)peeringrefuses a stranger throughcapacity, which ticks afterbudget, which ticks afterpeering→self.peering.bind(self.capacity)
A bind() is a statement that the graph has a back-edge. There are two. A
third should prompt the question of whether the tick order is right.
1.2.1.7. Writing one
Subclass
Compartment(or compose mixins over it, asbudget/,compute/,reporter/do). Setname,reads,live; setrequiresto what you reach throughctx.node; setoptional/enabled_byif the node runs without you.Write
from_context. Everything you need comes fromctx; the test for whether it belongs infrom_contextis “would a test have to build a NodeApp to construct this?” - if yes, the constructor still takes it as a plain argument andfrom_contextis where the node supplies it.Add the class to
MANIFESTwhere it should tick. Ifrequiresnames something later in the list, the node refuses to start and tells you.Declare the attribute on
NodeApp(name: Type) so the checker knows it;setattris invisible to mypy.python3 scripts/check-cli.pyreads the manifest and holds every “N compartments” in the docs to it. Update the docs it names.
A compartment outside the tree does the same, imports Compartment and
NodeContext, sets api = 'subsystem/1' and, if it reads a schema,
protocol = <the digest it was built against>. The node refuses it with a
reason if either does not match. That is the whole compatibility story so
far; see docs/updates.md for what a node does about versions it did not
write.
1.2.1.8. The config a compartment reads
config.json is typed in fleetmesh_node/config/: NodeConfig is the whole file as
a frozen dataclass, built from one Block per section (records.py for the
lists and maps the node itself reads - Endpoint, PeerPull,
CoverageClaim, TrustDecision - and compartments.py for one block per
compartment: BridgeConfig, DVMConfig, CapacityConfig, …). Each
block writes two things: check(raw, p), which adds a sentence to p for
every problem (dvm.max_fuel must be a positive integer), and
from_dict(raw), the typed shape. fleetmesh_node.app.config.DEFAULTS is
NodeConfig.defaults_dict() and validate_config is NodeConfig.check:
the file has one source of truth and one place that says what is wrong.
Two things fall out of this:
An unknown top-level key is refused by name. A misspelt block (
capacitty) used to be read as “absent”, which is exactly the silent failure a check exists to catch. An out-of-tree compartment puts its block underextensions: {name: {...}}, which the node carries without reading; the compartment that owns it checks it.readsis enforced.fleetmesh_node/tests/test_config_contract.pywalks each manifest compartment’s source forself.config('k'),ctx.cfg.get('k'),ctx.cfg_of('k'),cfg['k']and holds every key it finds to the compartment’s declaredreads(the node’s own identity keys -class,relays,endpoints,operator,name- are ambient). It also holds every declared key to oneNodeConfigknows about. A compartment that reaches for a block it did not declare fails the suite with the key named.
Adding a config key to a compartment depends on whether its block has been
converted to Parameter (fleetmesh_node/config/parameter.py). undeclared() says
which have not.
A converted block (ParamBlock): add one Parameter to PARAMS and the
dataclass field that holds it. Nothing else. check and from_dict are
derived, so there is no sentence to write twice and no default to state
twice - updates.check_every used to carry its default in the field and
again in from_dict, which is the duplication the class exists to end. The
parameter also says whether a reload reaches it, and the compartment’s live
tuple is derived from that in Compartment.__init_subclass__: live and
Parameter.live were two spellings of one fact, and the parameters win
because whether a reload reaches a value is a property of the value. The
first run of that derivation found capacity claiming a key no parameter
backed.
An unconverted block: add the field with a default, a check line, a
from_dict line, and the key to reads, as before.
defaults_dict does not write compartment blocks - a default file asks for
nothing, and for the optional compartments presence is the switch
(enabled_by).
A parameter also carries what an operator may do with it. sources names the
escalation layers allowed to set it and is enforced; requires names the UCAN
ability a delegation must carry and is declared only, because nothing
authenticates a principal yet. secret=True keeps a credential out of every
report and every audit row. See the module docstring for the escalation order.
1.2.1.9. What a compartment says and measures
Two more declaration surfaces, in the same shape and for the same reason.
CHANNELS(fleetmesh_node/channels/) is what this compartment can say. AChannelcarries both renderings -wirefor a reader andsayfor a person, the latter preferably a format string - so one declaration feeds the journal, the control socket and any other backend an operator configured. Before this a compartment chose betweenjournal.lineandevents.emitby hand, 45 call sites against 6, and the two carried different events.METRICS(fleetmesh_node/metrics/) is what it measures. A counter naming a channel incountsis incremented by that channel being raised, so the log line and the count come from one declaration and cannot disagree. Gauges read throughsample; histograms take explicit buckets. The exposed Prometheus name is derived and checked at registration, because a name Prometheus rejects is a metric that silently never arrives.
Use the channel-name constants rather than strings at the raise site: a
mistyped constant is a NameError at import, a mistyped string is an
undeclared channel found later by a counter.
every_parameter(), every_channel() and every_metric() enumerate all
three, which is what makes uniform defaults and complete monitoring something
to check rather than hope for.
How a compartment gets its block:
config_cls = DVMConfigon the class names the Block that types its own key.self.settings()parses that block from the file as it is now, throughconfig()so the read counts againstreads. A compartment whose key is inlivecalls it when it needs the value (blob_wire,blob_replication,capacity); the rest read it once infrom_context. The contract test holdsconfig_cls.keytoreadsand toNodeConfig.BLOCKS.ctx.block(BridgeConfig)does the same from aNodeContext, for a constructor that wants the block as an argument.ctx.block_getter(cls)is the live form.Tests may still hand a constructor a plain dict; the constructor runs it through
from_dict, so the block is the shape either way.
An optional compartment’s block may be plain true - presence is the
switch, so "compute": true and "dvm": true mean “on, every default”.
Blocks whose fields are “a boolean or a list of hosts”
(blob_replication.allow_private, storage.allowPrivateMirror) carry a
tuple for the list; callers that pass it on as JSON turn it back into a
list.
The node’s own ambient keys (face, policy, storage, name,
pow_bits) are read from node.settings, the NodeConfig the file parsed
to; node.cfg stays the dict the file is saved from.
1.2.1.10. The shapes a compartment handles: three kinds of dict
dict[str, Any] checks nothing, so the code says which of three things a
mapping is and types each one differently.
Records that live in-process - receipts, grants, findings, invoices, jobs, sessions, quotes: anything a store writes, a tick reads back and a second function reasons about. These are
@dataclass(frozen when immutable,slots=True), withfrom_row/to_row(orfrom_json/to_json) at the sqlite or JSON edge. Attribute access replaces string-key.get()guards; mypy sees a renamed field everywhere at once. Precedent:fleetmesh_node/planes/services/paidfetch/compartment.py,fleetmesh_node/config/compartments.py.Wire bodies at the door - what
fleetmesh_core/wire/validate.pyadmits from a peer. Untrusted until a schema check has run, so they stay mappings and are annotated with thetotal=FalseTypedDicts infleetmesh_core/wire/wire_types.py(every field optional: the type narrows what a field is, never promises it is there). The checkers infleetmesh_core/wire/validate.pytakedict[str, Any]on purpose: that is the untrusted input. Once a body has been validated and a compartment keeps it, it becomes a record (first bullet).Reports to the operator -
state(),health(),trouble(), what the control socket serialises for the CLI. Born as output, JSON within the microsecond, never consumed as a Python object in-process. These returnMapping[str, object]; where the CLI formats specific keys (peers, budget, compute, the health summary) aTypedDictinfleetmesh_node/interfaces.pyanchors the key names under mypy. Not dataclasses: a constructor in the post-stop()path is one more place to raise.
scripts/check-dicts.py records the per-file count of dict[str, Any] in
scripts/dict-baseline.json and fails when any file grows; converting a
record lowers the total and --write re-records it (and refuses when the
total did not fall). A file may grow only when the commit names it a JSON
edge - --write --edge PATH - and even then only while the total falls; an
unnamed file that grew is refused under --write too. The count can only go
down, and every exception is on the command line, not inferred from the diff.
Where the floor is, as of the fifteenth conversion (651 occurrences):
fleetmesh_core/wire/validate.py holds checker signatures by design; fleetmesh_core/storage/sync.py and
fleetmesh_core/peering/peering.py are the reference implementation and wire-shaped on purpose;
fleetmesh_node/planes/services/settle/gateways.py reads wallet JSON that is not this project’s to type. Below
those, what remains is -> dict[str, Any] on handlers whose reply the
control socket serialises at once, which Mapping[str, object] would state
more honestly when someone next touches them.
1.2.1.11. Where a module lives
The root of fleetmesh_node/ is the shared surface: what more than a handful of
packages import. interfaces, compartment, grants, peers, keystore,
keys, journal, relay, sqlitestore, validate, control,
wire_types - and the entry points (meshnode, context,
demo, cluster). Everything else has an owner:
fleetmesh_node/<name>/- every compartment the manifest names is its own package, one directory per compartment, whatever its size. One that is a single module isfleetmesh_node/<name>/compartment.pywith an__init__.pythat exports its class (link,strain,trust,capacity,presence,linked,retention,scheduler,announce,discovery_wire,lan,bridge,fetch_pricing,blob_replication,sidecars,nsite,p2p_wire); one that is several modules keeps them besidecompartment.py(peering_wire/,sync_wire/,budget/,compute/,mediation/,settlement/,dvm/,reporter/). Imported byfleetmesh_node/app/core.pyand by the compartments thatrequiresthem - nothing else. Two modules that used to sit among the compartments were not compartments:enclaveis the keystore’s sealed-key helper and lives atfleetmesh_node/keystore/; the handover rules thatsync_wireandvalidateshare arefleetmesh_node/planes/store/sync/rules.py.fleetmesh_node/transport/- the ladder and its rungs: the relay rung,fips_rung,rung(the iroh and libp2p adapters), and the daemons and framings the rungs drive (iroh_transport,iroh_live,fips_transport,lineproto,didcomm_inbound) plus the LAN finders (mdns,dnstxt).didcomm,ws,cborandcurvestay at the root: they are codecs the face and the money modules use as much as the ladder.the nostr face, not yet a package:
relayserver,blossom,blobstore,netfetch,gateways,eventstore,eventbus,descriptor,origin,release.money, not yet a package:
payment,cashu,zk,accounts.
A module moves by git mv into its package, its relative imports go one
level up, and a facade stays at the old path for one release that re-binds
the new module’s public names. The facade is a
root module too, so scripts/check-root.py - which holds the root to
scripts/root-baseline.json and whose --write only ever shrinks it - goes
down when the facade is deleted, not when the move lands.
1.2.1.12. Tests
fleetmesh_node/tests/test_config_contract.py- the config contract above: defaults areNodeConfig()’s, everyreadskey is known, every read is declared, the seven once-unchecked blocks are checked, every problem at once.fleetmesh_node/tests/test_assemble.py- the assembler alone, on fixture classes: manifest order, dependency refusal, optional on/off, API major refusal, digest refusal only when the context has one,attron the node.The whole suite exercises the real manifest: every
NodeApp(...).start()infleetmesh_node/tests/andfleetmesh_node/examples/demo.pygoes throughassemble().