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

link

always

2

trust

always

3

strain

always

4

peering

always

5

budget

always

6

capacity

always

7

sync

always

8

reporter

always

9

discovery

always

10

announce

always

11

lan

always

12

presence

always

13

linked

always

14

network

always

15

retention

always

16

scheduler

always

17

settlement

always

18

mediation

always

19

blob_wire

always

20

blob_replication

always

21

paid_fetch

always

22

sidecars

always

23

remote

always

24

p2p

only with its config block

25

gossip

only with its config block

26

compute

only with its config block

27

compute_wire

only with its config block

28

bridge

only with its config block

29

dvm

only with its config block

30

nsite

only with its config block

31

video

only with its config block

32

updates

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 fleetmesh_node.compartment.Compartment subclass the node builds, ticks, reports and commands

MANIFEST in fleetmesh_node/app/core.py (built-in) or plugins: in the config (plugin)

sidecar

an external HTTP process the node fronts: a JSON manifest, not code

fleetmesh_node/planes/services/sidecars/manifests/, sidecars.<name>.manifest, or a plugin’s sidecars attribute

“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 from name (paidfetch → node.paid_fetch, settle → node.settlement). Defaults to name.

  • 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 when cfg[enabled_by] is present and truthy (enabled_by defaults to name). 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 a digest, 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 is cls(node=ctx.node), which is exactly right for Settlement and Mediation and 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

dir, path(*parts)

the node directory and a file under it

ks

keystore; ctx.pubkey, ctx.did derive from it

cfg, cfg_of(key), cfg_getter()

the live config dict, one key now, or the lambda: cfg several compartments take

clock

() -> int, injectable for tests

events

the node event bus

stores

NodeStores(events, grants, accounts, blobs)

relays

the relay URLs this node uses

transport, router, face

the DIDComm transport, protocol router, relay face

peers, policy, ledger

the peer table, peering policy, standing ledger

timeout, stop

the node’s default timeout and its stop event

descriptor()

the kind 11801 once start() has it; raises before

digest

the schema digest this node speaks

node

the NodeApp - a labelled escape hatch, see below

node_class

cfg['class']

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:

  • link records a reconnect into strain, but ticks before it → self.link.bind(self.strain)

  • peering refuses a stranger through capacity, which ticks after budget, which ticks after peering → 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

  1. Subclass Compartment (or compose mixins over it, as budget/, compute/, reporter/ do). Set name, reads, live; set requires to what you reach through ctx.node; set optional/enabled_by if the node runs without you.

  2. Write from_context. Everything you need comes from ctx; the test for whether it belongs in from_context is “would a test have to build a NodeApp to construct this?” - if yes, the constructor still takes it as a plain argument and from_context is where the node supplies it.

  3. Add the class to MANIFEST where it should tick. If requires names something later in the list, the node refuses to start and tells you.

  4. Declare the attribute on NodeApp (name: Type) so the checker knows it; setattr is invisible to mypy.

  5. python3 scripts/check-cli.py reads 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 under extensions: {name: {...}}, which the node carries without reading; the compartment that owns it checks it.

  • reads is enforced. fleetmesh_node/tests/test_config_contract.py walks each manifest compartment’s source for self.config('k'), ctx.cfg.get('k'), ctx.cfg_of('k'), cfg['k'] and holds every key it finds to the compartment’s declared reads (the node’s own identity keys - class, relays, endpoints, operator, name - are ambient). It also holds every declared key to one NodeConfig knows 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. A Channel carries both renderings - wire for a reader and say for 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 between journal.line and events.emit by 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 in counts is incremented by that channel being raised, so the log line and the count come from one declaration and cannot disagree. Gauges read through sample; 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 = DVMConfig on the class names the Block that types its own key. self.settings() parses that block from the file as it is now, through config() so the read counts against reads. A compartment whose key is in live calls it when it needs the value (blob_wire, blob_replication, capacity); the rest read it once in from_context. The contract test holds config_cls.key to reads and to NodeConfig.BLOCKS.

  • ctx.block(BridgeConfig) does the same from a NodeContext, 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), with from_row / to_row (or from_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.py admits from a peer. Untrusted until a schema check has run, so they stay mappings and are annotated with the total=False TypedDicts in fleetmesh_core/wire/wire_types.py (every field optional: the type narrows what a field is, never promises it is there). The checkers in fleetmesh_core/wire/validate.py take dict[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 return Mapping[str, object]; where the CLI formats specific keys (peers, budget, compute, the health summary) a TypedDict in fleetmesh_node/interfaces.py anchors 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 is fleetmesh_node/<name>/compartment.py with an __init__.py that 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 beside compartment.py (peering_wire/, sync_wire/, budget/, compute/, mediation/, settlement/, dvm/, reporter/). Imported by fleetmesh_node/app/core.py and by the compartments that requires them - nothing else. Two modules that used to sit among the compartments were not compartments: enclave is the keystore’s sealed-key helper and lives at fleetmesh_node/keystore/; the handover rules that sync_wire and validate share are fleetmesh_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, cbor and curve stay 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 are NodeConfig()’s, every reads key 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, attr on the node.

  • The whole suite exercises the real manifest: every NodeApp(...).start() in fleetmesh_node/tests/ and fleetmesh_node/examples/demo.py goes through assemble().