fleetmesh-node 0.2.0__py3-none-any.whl

node/app/core.py

@@ -0,0 +1,867 @@
+"""NodeApp: what `meshnode run` starts. Construction, the compartment
+assembly in start(), the run loop, the inbound door and status.json.
+
+Separate from control.py so the file that registers the compartments - the
+one scripts/check-cli.py reads for tick order - holds nothing else.
+"""
+from __future__ import annotations
+
+import collections
+import json
+import os
+import threading
+import time
+from typing import Any, Callable, Mapping, MutableMapping, Sequence, cast
+
+from ..config.node import NodeConfigDict
+
+from fleetmesh_core.accounting import standing
+from fleetmesh_core.identity import identity
+from fleetmesh_core.peering import peering
+from .. import (channels as channels_mod, compartment as compartment_mod,
+                keystore, metrics as metrics_mod, transport as transport_mod)
+from ..channels import journal
+from fleetmesh_core.wire import validate
+from ..protocols.nostr import blobstore as blobstore_mod, eventstore, peers as peers_mod
+from ..storage import accounts as accounts_mod, grants as grants_mod
+from ..protocols import ProtocolManager
+from ..transport.host import ProtocolHost
+from . import router as router_mod
+from ..compartment import context as context_mod
+from ..metrics import adapters as metrics_adapters
+from ..metrics.face import face_metrics
+from ..protocols.nostr import client as relay, descriptor
+from ..planes.identity.announce import compartment as announce_mod
+from ..planes.identity.discovery import compartment as discovery_wire
+from ..planes.identity.presence import compartment as presence_mod
+from ..planes.identity.linked import compartment as linked_mod
+from ..planes.store.sync import core as sync_wire
+from ..planes.store.retention import compartment as retention_mod
+from ..planes.store.blob_wire import core as blob_wire_mod
+from ..planes.store.blob_replication import compartment as blob_repl_mod
+from ..planes.peering.trust import compartment as trust_mod
+from ..planes.peering.strain import compartment as strain_mod
+from ..planes.peering.peering import core as peering_wire
+from ..planes.peering.budget import core as budget_mod
+from ..planes.peering.capacity import compartment as capacity_mod
+from ..planes.peering.reporter import core as reporter_mod
+from ..planes.transport.link import compartment as link_mod
+from ..planes.transport.lan import compartment as lan_mod
+from ..planes.transport.p2p import compartment as p2p_wire
+from ..planes.transport.mediation import compartment as mediation_mod
+from ..planes.transport.bridge import compartment as bridge_mod
+from ..planes.services.gossip import core as gossip_wire
+from ..planes.services.compute import compartment as compute_mod
+from ..planes.services.compute_wire import compartment as compute_wire_mod
+from ..planes.services.settle import compartment as settlement_mod
+from ..planes.services.paidfetch import compartment as fetch_pricing_mod
+from ..planes.services.sidecars import compartment as sidecars_mod
+from ..planes.services.dvm import gateway as dvm_mod
+from ..planes.services.nsite import compartment as nsite_mod
+from ..planes.services.video import compartment as video_mod
+from ..planes.operations.scheduler import compartment as scheduler_mod
+from ..planes.operations.updates import core as updates_mod
+from ..compartment import lifecycle as lifecycle_mod
+from . import socket as control_mod
+from ..config import NodeConfig
+from ..interfaces import NostrEvent
+from .config import _blob_storage_cap, load_config, typed_config
+from .control import ControlMixin
+from .plugins import load_plugins, plugin_sidecars
+from .systemd import sd_notify
+from .views import PLANES as _VIEW_PLANES, node_health, node_status
+
+# How anything in the node says something an operator will read, and how a
+# trust entry is understood. Both live where a compartment can reach them
+# without importing the node that imports the compartment.
+_line, _short = journal.line, journal.short
+trust_decision, trust_tiers = trust_mod.decision, trust_mod.tiers
+
+# The node's compartments in tick order. This is the one list scripts/check-cli.py,
+# the `subsystems` command and the docs agree on. The order is a decision, not
+# a derivation: the relay journal 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; then the paid and
+# fronted services, which are inert until configured. Optional compartments sit
+# where they tick and are built only when their config section is present.
+MANIFEST: tuple[type[compartment_mod.Compartment], ...] = (
+    link_mod.Link,
+    trust_mod.Trust,
+    strain_mod.StrainLedger,
+    peering_wire.Peering,
+    budget_mod.Budget,
+    capacity_mod.Capacity,
+    sync_wire.SyncPeer,
+    reporter_mod.Reporter,
+    discovery_wire.Discovery,
+    announce_mod.Announce,
+    lan_mod.Lan,
+    p2p_wire.P2PTransport,            # optional: cfg['p2p']
+    gossip_wire.GossipMesh,           # optional: cfg['gossip']
+    presence_mod.Presence,
+    linked_mod.LinkedFace,            # the schema.org face; reads presence's 10050 and budget's ledger
+    retention_mod.Retention,
+    scheduler_mod.Scheduler,
+    compute_mod.Compute,              # optional: cfg['compute']
+    compute_wire_mod.ComputeWire,     # optional: cfg['compute']
+    bridge_mod.RelayBridge,           # optional: cfg['bridge']
+    settlement_mod.Settlement,
+    mediation_mod.Mediation,
+    blob_wire_mod.BlobWire,
+    blob_repl_mod.Replication,
+    fetch_pricing_mod.PaidFetch,
+    sidecars_mod.Sidecars,
+    dvm_mod.DVMGateway,               # optional: cfg['dvm']
+    nsite_mod.NsiteGateway,           # optional: cfg['nsite']; after bridge, which it uses for manifests
+    video_mod.VideoTransitCompartment,  # optional: cfg['video']; after nsite, the other HTTP face
+    updates_mod.Updates,              # optional: cfg['updates']; last - it reports on all the above
+)
+
+
+class NodeApp(ControlMixin):
+    # The compartments, set on the node by Registry.assemble() under each
+    # class's `attr` (or `name`). Declared so the node's surface is stated,
+    # and so the checker knows it: setattr is invisible to mypy. The six (6)
+    # optional ones - p2p, gossip, compute, bridge, dvm, updates - are absent
+    # on a node whose config does not enable them.
+    manifest: tuple[type[compartment_mod.Compartment], ...]   # MANIFEST plus any configured plugins
+    link: link_mod.Link
+    trust: trust_mod.Trust
+    strain: strain_mod.StrainLedger
+    peering: peering_wire.Peering
+    budget: budget_mod.Budget
+    capacity: capacity_mod.Capacity
+    sync: sync_wire.SyncPeer
+    reporter: reporter_mod.Reporter
+    discovery: discovery_wire.Discovery
+    announce: announce_mod.Announce
+    lan: lan_mod.Lan
+    p2p: p2p_wire.P2PTransport
+    gossip: gossip_wire.GossipMesh
+    presence: presence_mod.Presence
+    retention: retention_mod.Retention
+    scheduler: scheduler_mod.Scheduler
+    compute: compute_mod.Compute
+    compute_wire: compute_wire_mod.ComputeWire
+    bridge: bridge_mod.RelayBridge
+    settlement: settlement_mod.Settlement
+    mediation: mediation_mod.Mediation
+    blob_wire: blob_wire_mod.BlobWire
+    blob_replication: blob_repl_mod.Replication
+    paid_fetch: fetch_pricing_mod.PaidFetch
+    sidecars: sidecars_mod.Sidecars
+    dvm: dvm_mod.DVMGateway
+    video: video_mod.VideoTransitCompartment
+
+    def __init__(self, directory: str, cfg: Mapping[str, Any] | None = None,
+                 clock: Callable[[], int] | None = None,
+                 relays_override: Sequence[str] | None = None) -> None:
+        self.dir: str = directory
+        self.cfg: MutableMapping[str, Any] = dict(cfg if cfg is not None else load_config(directory))
+        # The typed view of the same file. Compartments get their block through
+        # NodeContext.block(); the ambient keys the node itself reads are below.
+        self.settings: NodeConfig = typed_config(self.cfg)
+        self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self.relays: list[str] = list(relays_override if relays_override is not None else self.cfg['relays'])
+        self.ks: keystore.Keystore = keystore.Keystore.load_or_generate(directory)
+        self.store: eventstore.NodeStore = eventstore.NodeStore(os.path.join(directory, 'events.sqlite'))
+        self.grants: grants_mod.GrantStore = grants_mod.GrantStore(os.path.join(directory, 'grants.sqlite'))
+        self.accounts: accounts_mod.AccountStore = accounts_mod.AccountStore(os.path.join(directory, 'accounts.sqlite'))
+        blobs_cfg = self.settings.blobs
+        self.blobs: blobstore_mod.BlobStore = blobstore_mod.BlobStore(
+            os.path.join(directory, 'blobs'), max_storage_bytes=_blob_storage_cap(self.cfg),
+            fanout=blobs_cfg.fanout, data_dir=blobs_cfg.data_dir)
+        # What this node measures, declared by the compartments rather than
+        # written out here. Built before the face so the face's
+        # `metrics_provider` can close over it; the declarations arrive later,
+        # at assemble(), and `read()` walks whatever is registered when a
+        # scrape happens.
+        self.monitors: metrics_mod.Monitors = metrics_mod.Monitors()
+
+        # The unified protocol host multiplexer
+        host_cfg = self.settings.protocol_suites.host
+        host_ip = host_cfg.listen if (host_cfg.listen != '127.0.0.1' or not self.settings.face.host) else self.settings.face.host
+        host_port = host_cfg.port if (host_cfg.port != 0 or not self.settings.face.port) else self.settings.face.port
+        self.host: ProtocolHost = ProtocolHost(
+            host=host_ip,
+            port=host_port,
+            name=self.settings.name,
+            clock=self.clock,
+        )
+
+        # The protocol manager orchestrating all active suites
+        self.protocols: ProtocolManager = ProtocolManager(
+            node_dir=directory,
+            keystore=self.ks,
+            clock=self.clock,
+            name=self.settings.name,
+        )
+        self.protocols.load_suites_config(
+            self.settings.protocol_suites,
+            backend_store=self.store,
+            blob_store=self.blobs,
+            grants=self.grants,
+            node_instance=self,
+            strain_ledger=getattr(self, 'strain', None),
+        )
+        self.protocols.mount_ingress(self.host)
+
+        nostr_pkg = self.protocols.get_package('nostr')
+        relay_srv = getattr(nostr_pkg, 'relay_server', None) if nostr_pkg is not None else None
+        self.face: Any = relay_srv
+        if relay_srv is not None:
+            relay_srv.metrics_provider = metrics_adapters.provider(self.monitors)
+            self.monitors.register(face_metrics(relay_srv), owner='face')
+            if relay_srv.blossom is not None:
+                apm = self.settings.storage.allow_private_mirror
+                relay_srv.blossom.allow_private_mirror = list(apm) if isinstance(apm, tuple) else apm
+
+        self.descriptor: NostrEvent | None = None
+        self.timeout: float = 15.0
+        self.peers: peers_mod.Peers = peers_mod.Peers(self.relays, clock=self.clock)
+        self.transport: transport_mod.TransportRouter = transport_mod.TransportRouter(
+            self.ks, self.peers, self.relays,
+            endpoints=self.cfg.get('endpoints', []),
+            clock=self.clock,
+            seen_store=(self.accounts.seen_wrap, self.accounts.put_seen_wrap),
+            ack_store=self.accounts,
+            sidecar_dir=self.dir,
+            enable_nostr=(nostr_pkg is not None),
+        )
+        self.protocols.mount_transport_rungs(self.transport)
+        pol = self.settings.policy
+        self.policy: peering.Policy = peering.Policy(pow_bits=self.settings.pow_bits, open_enrolment=pol.open_enrolment,
+                                                     protocols=list(pol.protocols),
+                                                     tiers=trust_tiers(self.cfg.get('trust')))
+        self.ledger: standing.Ledger = standing.Ledger()
+        self.events: channels_mod.NodeEventBus = channels_mod.NodeEventBus()
+        self.events.tap = channels_mod.Tap(clock=self.clock)
+        # What this node says, fanned out from one declaration per event.
+        # After `self.events`, because the bus is one of the places a record
+        # goes: anything already subscribed to a topic by name keeps working.
+        # Not `self.log`: that name is already a 500-entry deque of tick and
+        # handler failures (below), and shadowing it would have silently
+        # replaced one with the other. `says` is what this does.
+        self.says: channels_mod.Log = channels_mod.Log(
+            backends=[channels_mod.ConsoleBackend()], clock=self.clock,
+            bus=self.events, monitors=self.monitors)
+        self.stores: context_mod.NodeStores = context_mod.NodeStores(
+            events=self.store,
+            grants=self.grants,
+            accounts=self.accounts,
+            blobs=self.blobs,
+        )
+        self.router: router_mod.ProtocolRouter = router_mod.ProtocolRouter()
+        self._stop: threading.Event = threading.Event()
+        self.context: context_mod.NodeContext = context_mod.NodeContext(
+            dir=self.dir, ks=self.ks, cfg=cast(NodeConfigDict, self.cfg), clock=self.clock, events=self.events,
+            stores=self.stores, relays=self.relays, transport=self.transport, router=self.router,
+            face=self.face, host=self.host, peers=self.peers, policy=self.policy, ledger=self.ledger,
+            timeout=self.timeout, stop=self._stop, node=self, persist_cfg=self.save_coverage,
+            redescribe=self.redescribe,
+            regrant=self.regrant,
+            propose=self.propose,
+            pull=self.pull,
+            amend=self._amend,
+            build_descriptor=self.build_descriptor,
+            says=self.says,
+        )
+        # What was a dozen dicts here is now the state of the compartment that
+        # keeps it: the pulls belong to the scheduler, the publications to
+        # discovery, the descriptor and the heartbeats to presence, the relay
+        # journal to link. The node keeps only what the node owns.
+        self.log: collections.deque[Any] = collections.deque(maxlen=500)
+        self.counts: collections.Counter[str] = collections.Counter()      # handler failed, tick failed, config rejected
+        self.rejected: collections.Counter[str] = collections.Counter()    # messages refused at the door, by reason
+        self._last_said: dict[str, float] = {}                     # rate limit on repeated log lines
+        self._last_tick: Sequence[tuple[Any, ...]] = ()   # what the last tick did, for status.json
+        self._last_tick_error: str | None = None
+        self._config_error: str | None = None
+        self._tick_lock: threading.RLock = threading.RLock()      # the run loop and the control socket both tick
+        self._built: bool = False
+        self._stopped: bool = False
+        # Config blocks edited on disk that wait for a node restart, as last
+        # said: their owner does not declare restart, so the edit is reported
+        # once per change rather than once a tick.
+        self._waiting: MutableMapping[str, Any] = {}
+
+    # ---- assembly ----------------------------------------------------------------
+    DESCRIPTOR_FILE: str = 'descriptor.json'
+    # Present while descriptor.json holds a descriptor no relay has accepted
+    # yet. start() mines before it assembles (peering reads the descriptor at
+    # assembly) but publishes only once the compartments have started, so a
+    # refused start leaves a mined, unpublished descriptor behind. Reusing it
+    # keeps the proof of work; this marker is what makes the next start that
+    # does succeed publish it, rather than assume the relays already have it.
+    PENDING_FILE: str = 'descriptor.pending'
+
+    def _endpoints(self) -> list[tuple[str, str, int]]:
+        """What the descriptor advertises, which is what the operator configured.
+
+        It used to fall back to this node's own relay face, and the face binds
+        loopback on an ephemeral port by default: the descriptor then advertised
+        an address no peer could reach, and one that changed on every restart,
+        so the proof of work could never be reused either. `endpoint` is
+        optional on a kind 11801. A node with nothing reachable to advertise
+        says nothing, and is still reachable over the nostr transport, which is
+        the binding the specification says always works.
+        """
+        return [(e['transport'], e['address'], e.get('priority', 50)) for e in self.cfg['endpoints']]
+
+    def load_descriptor(self) -> NostrEvent | None:
+        """The descriptor this node published last time, if it is still the one
+        it would publish now.
+
+        A descriptor costs a NIP-13 proof of work to mine - twenty bits, which
+        took fourteen seconds on a small droplet - and it is a replaceable
+        event, so republishing a fresh one on every start burns that work and
+        churns the relay for nothing. The first two-machine run re-mined on
+        every service restart because nothing here read the file back. It is
+        reused only when it would still be published unchanged: valid under the
+        digest this node speaks, not yet inside its renewal window, and
+        describing the same class and endpoints the config now asks for.
+        """
+        path = os.path.join(self.dir, self.DESCRIPTOR_FILE)
+        if not os.path.exists(path):
+            return None
+        try:
+            with open(path, encoding='utf-8') as f:
+                d = json.load(f)
+        except (ValueError, OSError):
+            return None
+        now = self.clock()
+        if identity.validate_descriptor(d, now=now, digest=descriptor.DIGEST):
+            return None
+        exp = int([t for t in d['tags'] if t[0] == 'expiration'][0][1])
+        if now >= exp - (exp - d['created_at']) // 10:
+            return None
+        want = [['endpoint', s, a, str(p)] for s, a, p in sorted(self._endpoints(), key=lambda e: (int(e[2]), e[0]))]
+        if [t for t in d['tags'] if t[0] == 'endpoint'] != want:
+            return None
+        cls = [t[1] for t in d['tags'] if t[0] == 'class'][0]
+        # Optional protocols (the sidecar capabilities) are declared by the
+        # compartment that verifies them, after start, and are not config:
+        # they neither qualify nor disqualify a reuse here. `sidecars` brings
+        # the descriptor into agreement with the live self-tests itself.
+        optional = set(identity.CONSTANTS['descriptor'].get('optional_protocols', ()))
+        if cls != self.cfg['class'] or identity.protocols_of(d) - optional != set(self.cfg['protocols']) | set(identity.REQUIRED_PROTOCOLS):
+            return None
+        # The operator is the declaration the independence model reads, and
+        # the plain capabilities are what a leaf searches for. Both are
+        # config; a change to either is a new descriptor, not a reused one.
+        operator = [t[1] for t in d['tags'] if t[0] == 'operator']
+        if operator != [self.cfg.get('operator')]:
+            return None
+        hints = {t[1] for t in d['tags'] if t[0] == 'c' and len(t) > 1 and not t[1].startswith('https://')}
+        if hints != set(self.cfg.get('capabilities') or ()):
+            return None
+        self.descriptor = d
+        return d
+
+    def _descriptor(self) -> NostrEvent:
+        """The descriptor once start() has loaded or mined it. Reaching for it
+        earlier is a programming error, not a state the node should paper over."""
+        if self.descriptor is None:
+            raise RuntimeError('the descriptor is not built yet; start() mines or loads it')
+        return self.descriptor
+
+    def build_descriptor(self) -> NostrEvent:
+        # Any built compartment may add capability identifiers (`c` tags) and
+        # descriptor tags: sidecars declare the protocols they front, paid_fetch
+        # its prices, a plugin the dialect it speaks. Before start() assembles
+        # the compartments none have anything to add, which is also right.
+        protocols = list(self.cfg['protocols'])
+        extra_tags: list[list[str]] = []
+        subs = getattr(self, 'subsystems', None)
+        for sub in (subs or ()):
+            add = getattr(sub, 'capability_protocols', None)
+            if callable(add):
+                protocols += [p for p in add() if p not in protocols]
+            tags = getattr(sub, 'descriptor_tags', None)
+            if callable(tags):
+                extra_tags += list(tags())
+        capabilities = list(self.cfg.get('capabilities', ()))
+        if getattr(self, 'settings', None) is not None and not self.settings.protocol_suites.nostr.enabled:
+            capabilities = [c for c in capabilities if c not in ('relay', 'negentropy', 'blossom')]
+        if getattr(self, 'protocols', None) is not None:
+            for tag in self.protocols.descriptor_capabilities():
+                tag_list = list(tag)
+                if len(tag_list) == 2 and tag_list[0] == 'c' and tag_list[1] in capabilities:
+                    continue
+                if tag_list not in extra_tags:
+                    extra_tags.append(tag_list)
+        self.descriptor = descriptor.build(self.ks, self.cfg['class'], self._endpoints(), self.cfg['operator'],
+                                           protocols, now=self.clock(),
+                                           capabilities=capabilities, bits=self.cfg.get('pow_bits'),
+                                           extra_tags=extra_tags)
+        path = os.path.join(self.dir, self.DESCRIPTOR_FILE)
+        tmp = path + '.tmp'
+        with open(tmp, 'w', encoding='utf-8') as f:
+            json.dump(self.descriptor, f, indent=2)
+        os.replace(tmp, path)
+        return self.descriptor
+
+    def redescribe(self) -> NostrEvent:
+        """Rebuild the descriptor from what the compartments say NOW and
+        publish it. For a compartment whose declaration changed after start
+        (a sidecar's self-tests began passing, or stopped): the kind 11801
+        must say what is true, and a replaceable event costs one proof of
+        work to correct - cheaper than a leaf dialling a protocol nothing
+        here answers."""
+        d = self.build_descriptor()
+        if self.relays:
+            relay.publish_all(self.relays, d, self.timeout)
+        return d
+
+    def start(self) -> NodeApp:
+        """Bring the node up. All or nothing: a start that raises leaves no
+        bound face, no running transport and no started compartment behind.
+
+        Audit L1, option c - both halves:
+
+        a. `_start` puts every point that can refuse - assemble, wire, the
+           plugin-origin check, route, and each compartment's start() -
+           before anything another machine can see. The face starts serving
+           only after the router exists, and a freshly mined descriptor is
+           published only after Registry.start returns. (The face's socket
+           is bound when the RelayServer is constructed, which is earlier;
+           the `from_context` readers hold that object and read its port
+           lazily, so none of them needs it serving.)
+        b. This wrapper is the backstop. With Registry.start's own unwinding,
+           a refused start releases its port at once rather than at process
+           exit, and no compartment that started is left running.
+
+        A refused start therefore publishes nothing. What it mined stays on
+        disk under PENDING_FILE and is published by the next start that
+        succeeds.
+        """
+        try:
+            return self._start()
+        except BaseException:
+            self._abandon_start()
+            raise
+
+    def _abandon_start(self) -> None:
+        """Release whatever a failed start had taken. Every step is guarded:
+        the raise that brought us here is the one the operator must see."""
+        self._stop.set()
+        steps: list[Callable[[], Any]] = []
+        if getattr(self, 'control', None) is not None:
+            steps.append(self.control.stop)
+        if self._built:
+            steps.append(self.subsystems.stop)
+        steps += [self.transport.stop]
+        if self.face is not None:
+            steps.append(self.face.stop)
+        if getattr(self, 'protocols', None) is not None:
+            steps.append(self.protocols.stop_all)
+        if getattr(self, 'host', None) is not None:
+            steps.append(self.host.stop)
+        for step in steps:
+            try:
+                step()
+            except Exception as e:
+                _line('  while abandoning the start:', '%s: %s' % (type(e).__name__, e))
+        self._stopped = True
+
+    def _start(self) -> NodeApp:
+        _line('starting', self.ks.did[:22] + '…', 'class', self.cfg['class'])
+        pending = os.path.join(self.dir, self.PENDING_FILE)
+        if self.descriptor is None and self.load_descriptor() is None:
+            mined = self.build_descriptor()
+            with open(pending, 'w', encoding='utf-8') as f:
+                f.write(mined['id'] + '\n')
+            _line('  mined a descriptor', mined['id'][:12] + '…',
+                  '(%d bits)' % identity.pow_bits(mined['id']))
+        elif os.path.exists(pending):
+            _line('  reusing a descriptor no relay has accepted yet',
+                  self._descriptor()['id'][:12] + '…')
+        else:
+            _line('  reusing the descriptor it already published',
+                  self._descriptor()['id'][:12] + '…')
+        # The compartments, built from one context in the declared tick order.
+        # Each class says what it needs (`requires`) and the assembler refuses
+        # a manifest that contradicts it; what each one takes from the node is
+        # in its own `from_context`, not here. See MANIFEST for the order and
+        # the reasons behind it.
+        self.subsystems = compartment_mod.Registry(say=self.says.say)
+        self.context.descriptor = self._descriptor
+        self.context.digest = descriptor.DIGEST
+        self.manifest = load_plugins(self.settings.plugins.specs, MANIFEST)
+        self.subsystems.assemble(self.context, self.manifest)
+        # Every edge that runs against tick order (link records into strain,
+        # peering refuses through capacity, budget reports through the
+        # reporter, the face asks paid_fetch for a price ...) is named by the
+        # compartment that owns it, in its `wire()`, and reached here once
+        # the whole manifest exists. The node no longer holds that list.
+        self.subsystems.wire(self.context)
+        # Every compartment's declared channels and metrics, in one place. A
+        # rejected metric is kept in the registry's state rather than raised:
+        # one malformed declaration must not stop a node booting, and it is
+        # reported by `meshnode health` instead of vanishing.
+        self.says.register_from(list(self.subsystems))
+        self.monitors.register_from(list(self.subsystems))
+        # And the lifecycle's own: every compartment moves through the same
+        # machine, so its transitions are the registry's to say and count.
+        self.says.register(lifecycle_mod.CHANNELS)
+        self.monitors.register(self.subsystems.lifecycle_metrics(), owner='lifecycle')
+        # And every declared store's size, bound and counts, labelled by
+        # compartment: memory metered without a compartment writing a metric.
+        self.monitors.register(self.subsystems.store_metrics(), owner='stores')
+        self.settle_engine: settlement_mod.SettlementEngine = self.settlement.engine
+        self.mediator: mediation_mod.MediatorService = self.mediation.service
+
+        # The router is a dumb ladder: each compartment declares the
+        # protocols it speaks (`piuris`, `exact_types`) and the registry
+        # puts its `handle` behind them. A plugin speaks its own origin; one
+        # that claims fleetmesh.org's is refused before it is routed. One
+        # that fronts a sidecar declares its manifest(s) as `sidecars`
+        # (dicts, or '@/path.json'); they join the registry before the
+        # sidecars compartment runs its first self-test below.
+        for cls in self.manifest:
+            if cls in MANIFEST:
+                continue
+            for piuri in getattr(cls, 'piuris', ()) or ():
+                if piuri.startswith(identity.FLEETMESH):
+                    raise ValueError('plugin %s claims fleetmesh.org protocol %s; plugins speak their own origin' % (cls.name, piuri))
+            for sc in plugin_sidecars(cls):
+                self.sidecars.declare(sc)
+        self.router = router_mod.ProtocolRouter()
+        self.subsystems.route(self.router)
+        # What the last process left for the compartments that declare
+        # `snapshot`, handed back before any of them starts. Never raises; a
+        # refusal is recorded on the compartment's lifecycle and it starts
+        # fresh. The file is discarded only once the start succeeds, so a
+        # refused start does not cost the next one its continuity.
+        saved, saved_at, why_not = lifecycle_mod.read_snapshots(self.dir, self.clock())
+        if why_not:
+            _line('  ' + why_not)
+        for name, what in self.subsystems.restore(saved, saved_at).items():
+            _line('  %s: %s' % (name, what))
+        # Everything above can refuse and none of it is visible off this
+        # machine. From here on the node starts being seen: the face serves
+        # (before the compartments start, because some of them dial it), the
+        # transport subscribes, and - once they have started - the
+        # descriptor is published.
+        self.host.start()
+        self.protocols.start_all()
+        if self.face is not None:
+            self.face.start()
+        self.strain.record('restart')
+        self.transport.start()
+        wait_listen_timeout = float(self.cfg.get('wait_listening_timeout', 5.0))
+        if self.relays and wait_listen_timeout > 0 and not self.transport.wait_listening(wait_listen_timeout):
+            # Said, not waited on for ever. Until a relay acknowledges the
+            # subscription this node cannot receive a live wrap and would not
+            # know it had missed one, because kind 21059 is ephemeral and no
+            # relay keeps a copy. Starting anyway is right - the stored kind
+            # replays, the compartments have work that needs no inbox, and
+            # `link` will keep saying so - but starting silently is not.
+            _line('  no relay has acknowledged the inbox subscription yet;',
+                  'live messages sent before it does are lost')
+        if not self.settings.face.port and not self.settings.protocol_suites.host.port:
+            # Port 0 asks the kernel for any free port, which is right for a test
+            # and wrong for a node an operator runs: the relay face moved on every
+            # restart, so every client holding its address lost it. Record what we
+            # were given, once.
+            port_assigned = self.host.port if self.host is not None else (self.face.server.port if self.face and self.face.server else 0)
+            self.cfg['face'] = dict(self.cfg.get('face') or {}, port=port_assigned)
+            self.save_coverage()
+            _line('  recorded the edge face port', port_assigned, 'so it survives a restart')
+        edge_url = self.face.url if self.face is not None else self.host.url
+        _line('  edge face', edge_url, '| relays', ', '.join(self.relays) or '(none)',
+              '| descriptor', self._descriptor()['id'][:12] + '…')
+        if not self.cfg['endpoints']:
+            _line('  no endpoint configured: reachable over the nostr transport only')
+        _line('  peers configured:', len(self.cfg.get('peers', [])),
+              '| grants held:', len(self.grants.list()))
+        # The registry's own lifecycle verb, which nothing called: presence
+        # holds the heartbeat subscription open and had no way to say so.
+        # It unwinds itself when a required compartment cannot start, so
+        # `_built` - which tells stop() to stop the compartments - is set only
+        # once they have (audit L1: it used to be set before, and a failed
+        # start then sent the budget's farewell for a node that never served).
+        self.subsystems.start()
+        self._built = True
+        lifecycle_mod.discard_snapshots(self.dir)
+        self._publish_pending(pending)
+        self.control = control_mod.Server(self.dir, self.control_request).start()
+        threading.Thread(target=self._serve, daemon=True).start()
+        sd_notify('READY=1\nSTATUS=Fleetmesh node active')
+        self._start_watchdog()
+        return self
+
+    def _publish_pending(self, pending: str) -> None:
+        """Publish a descriptor no relay has accepted yet, now that the node
+        has really started. The marker goes only when a relay accepted it: a
+        node with no relays configured, or none reachable, publishes on the
+        next start instead of believing it already had."""
+        if not os.path.exists(pending) or not self.relays:
+            return
+        out = relay.publish_all(self.relays, self._descriptor())
+        if any(ok for ok, _ in out.values()):
+            os.unlink(pending)
+        else:
+            _line('  no relay accepted the descriptor yet; the next start publishes it')
+
+    def _start_watchdog(self) -> None:
+        watchdog_usec = os.environ.get('WATCHDOG_USEC')
+        if watchdog_usec:
+            try:
+                usec = int(watchdog_usec)
+                if usec > 0:
+                    interval = (usec / 1_000_000.0) / 2.0
+                    threading.Thread(target=self._watchdog_loop, args=(interval,), daemon=True).start()
+            except (ValueError, TypeError):
+                pass
+
+    def _watchdog_loop(self, interval: float) -> None:
+        while not self._stop.is_set():
+            if self._stop.wait(interval):
+                break
+            sd_notify('WATCHDOG=1')
+
+    def run(self) -> None:
+        """Tick on the configured cadence until stop()."""
+        while not self._stop.is_set():
+            try:
+                for d in self.tick():
+                    _line(' ', ' '.join(_short(x) for x in d))
+            except Exception as e:      # one bad tick must not stop the node
+                self.log.append(('tick failed', str(e)))
+                self.counts['tick failed'] += 1
+                self._last_tick_error = '%s: %s' % (type(e).__name__, e)
+                _line('  tick failed:', e)
+            self._stop.wait(self.cfg.get('tick_seconds', 30))
+
+    def stop(self) -> None:
+        # Once. `meshnode run` stops from the SIGTERM handler and again from
+        # its finally:, and each pass said goodbye: every peer got the same
+        # window's farewell at two sequence numbers a few seconds apart, and
+        # whichever end saw the second first read the first as a receipt the
+        # wire had dropped. The three-continent mesh reported that gap on two
+        # of three nodes after its first restart.
+        if self._stopped:
+            return
+        self._stopped = True
+        sd_notify('STOPPING=1\nSTATUS=Fleetmesh node shutting down')
+        self._stop.set()
+        # Before the transport goes, tell every peer what this node used. A node
+        # that simply vanishes leaves its issuer with traffic measured and no
+        # receipt, which is active silence and an S2 - and an S2 drops the tier
+        # to probation, which only a person can raise again. That made the
+        # fleet-wide restart a digest change requires cost every peering its
+        # tier, every time.
+        if getattr(self, '_built', False):
+            # The registry stops every compartment, and the budget's stop is the
+            # farewell. Calling it here as well sent every peer two receipts for
+            # the same window at two sequence numbers - valid, and pointless.
+            for name, did in self.subsystems.stop():
+                for d in (did or []):
+                    _line('  ' + ' '.join(str(x) for x in d))
+            # After stop(), so the snapshot is what each compartment ended
+            # with. Only on a clean stop: a process that died wrote nothing,
+            # and the next one starts its compartments fresh.
+            snaps = self.subsystems.snapshot()
+            if snaps:
+                try:
+                    lifecycle_mod.write_snapshots(self.dir, self.clock(), snaps)
+                    _line('  kept the state of', ', '.join(snaps), 'for the next start')
+                except OSError as e:
+                    _line('  could not keep compartment state:', '%s: %s' % (type(e).__name__, e))
+        if getattr(self, 'control', None) is not None:
+            self.control.stop()
+        self.transport.stop()
+        if self.face is not None:
+            self.face.stop()
+        if getattr(self, 'protocols', None) is not None:
+            self.protocols.stop_all()
+        if getattr(self, 'host', None) is not None:
+            self.host.stop()
+
+    def close(self) -> None:
+        """Safely stop node workers and close all persistent database connections.
+
+        A close that fails is counted and said. The four stores here are shut
+        in turn and a failure in one must not leave the other three open, so
+        the exception is still caught - but it is no longer discarded: a store
+        that cannot close (a locked database, a disk full at commit) is
+        exactly the one an operator needs told about at restart, and
+        `except Exception: pass` told nobody (audit 2026-10-07, L5)."""
+        self.stop()
+        for name in ('store', 'accounts', 'grants', 'blobs', 'video'):
+            st = getattr(self, name, None)
+            if st is not None and hasattr(st, 'close'):
+                try:
+                    st.close()
+                except Exception as e:
+                    self.log.append(('close failed', '%s: %s' % (name, e)))
+                    self.counts['close failed'] += 1
+                    _line('  closing %s failed:' % name, '%s: %s' % (type(e).__name__, e))
+
+
+    # ---- inbound -------------------------------------------------------------------
+    def _say_once(self, key: str, *parts: Any, every: float = 60) -> None:
+        """One log line per key per minute. A peer that sends the same
+        malformed message forever must not own the journal."""
+        now = time.time()
+        if now - self._last_said.get(key, 0) < every:
+            return
+        self._last_said[key] = now
+        if len(self._last_said) > 500:
+            self._last_said = {k: v for k, v in self._last_said.items() if now - v < every}
+        _line(*parts)
+
+    def _serve(self) -> None:
+        while not self._stop.is_set():
+            inbound = self.transport.receive(timeout=0.5)
+            if inbound is None:
+                continue
+            # The door. A message without the shape of its type is dropped here
+            # with a reason, counted, and never reaches a handler; what a handler
+            # had done before it raised on a bad field used to stay done.
+            why = validate.check(inbound.message)
+            if why is not None:
+                self.rejected[why] += 1
+                self._say_once('rejected:' + why, '! rejected', _short(inbound.sender),
+                               str(inbound.message.get('type'))[-40:], '-', why)
+                continue
+            try:
+                done = self.router.dispatch(inbound)
+            except Exception as e:
+                self.log.append(('handler failed', inbound.message.get('type'), str(e)))
+                self.counts['handler failed'] += 1
+                self._say_once('handler:' + str(inbound.message.get('type')),
+                               '! handler failed on', inbound.message.get('type'), '-', e)
+                done = ('error',)
+            if done is not None:
+                self.log.append(done)
+                if done[0] not in ('ignored',):
+                    _line('<', ' '.join(_short(x) for x in done[:3]))
+
+    # What an operator may change while the node runs. The rest - class, keys,
+    # relays - is what the node is. Every live key belongs to the compartment
+    # that reads it, and this is what is left over: nothing.
+    LIVE_KEYS: tuple[str, ...] = ()
+
+    def reload_config(self) -> None:
+        """Take up whatever the operator has written since the last tick.
+
+        Every command writes the config and nothing else, because a running node
+        owns its directory and its relay face port and a second process cannot
+        stand one up beside it. So the file is the interface, and it is read in
+        one place: `trust` was being re-read and `coverage` was not, which meant
+        a shard added to the file was never claimed until the node restarted.
+        Neither is named here now. A compartment declares the keys it re-reads
+        and the registry collects them, so the list cannot fall behind the
+        mechanism that depends on it.
+        """
+        try:
+            fresh = load_config(self.dir) or {}
+        except (OSError, ValueError) as e:
+            # The last good config stays in force. Said once a minute, not once
+            # a tick, and shown in status so an operator finds it without the log.
+            self._config_error = str(e)
+            self.counts['config rejected'] += 1
+            self._say_once('config', '! config.json is not usable, keeping the last good one:', e)
+            return
+        self._config_error = None
+        for key in tuple(self.LIVE_KEYS) + self.subsystems.live_keys():
+            if key in fresh:
+                self.cfg[key] = fresh[key]
+        if self._built and self.capacity.set_total(self.cfg.get('capacity')):
+            _line('  aggregate ceiling is now',
+                  ', '.join('%s %s' % kv for kv in sorted(self.capacity.total.items()))
+                  or 'undeclared - this node will accept load until it fails')
+        if self._built:
+            self._reconfigure(fresh)
+
+    def _reconfigure(self, fresh: Mapping[str, Any]) -> list[str]:
+        """Take up a changed config block that is not live, by restarting its owner.
+
+        A live key is copied above and its compartment re-reads it. Any other
+        block used to wait silently for the next node restart. Now, when the
+        compartment that owns it declares `Lifecycle(restart=True)`, the new
+        block is parsed first - the running settings stay if it does not
+        parse - then adopted, and the compartment restarted in place. One that
+        does not declare restart keeps the running settings and the operator
+        is told, once a minute, that the edit waits for the node.
+
+        Returns the names restarted.
+        """
+        done: list[str] = []
+        for s in self.subsystems:
+            blk = getattr(s, 'config_cls', None)
+            own = getattr(blk, 'key', '') if blk is not None else ''
+            if blk is None or not own or own in s.live or fresh.get(own) == self.cfg.get(own):
+                continue
+            name = s.name or ''
+            if not self.subsystems.restartable(name):
+                # Once per edit: the running settings are right until the
+                # node restarts, so this is news when it changes, not weather.
+                if self._waiting.get(own) != fresh.get(own):
+                    self._waiting[own] = fresh.get(own)
+                    _line('  %s changed in config.json;' % own, name, 'takes it up when the node restarts')
+                continue
+            try:
+                blk.from_dict(fresh.get(own) or {})
+            except Exception as e:
+                self._say_once('config:' + own, '! %s in config.json is not usable, keeping the running one:' % own, e)
+                continue
+            if own in fresh:
+                self.cfg[own] = fresh[own]
+            else:
+                self.cfg.pop(own, None)
+            state = self.subsystems.restart(name, 'its %s block changed' % own)
+            _line('  %s restarted for its new %s settings:' % (name, own), state)
+            done.append(name)
+        return done
+
+    def tick(self, now: int | None = None) -> list[tuple[Any, ...]]:
+        with self._tick_lock:
+            return self._tick(now)
+
+    def _tick(self, now: int | None = None) -> list[tuple[Any, ...]]:
+        """One tick: take up the config, run every compartment, write the status.
+
+        This was a hundred and thirty lines with five mechanisms in it. What is
+        left is the three things the node itself owns - the config file, the
+        registry, and status.json - and one line about clock drift, which is
+        read here because it is the operator's to act on at both ends and not
+        one node's to fix.
+        """
+        now = now if now is not None else self.clock()
+        seen_drift = len(self.budget.clock_drift)
+        self.reload_config()
+        did = self.subsystems.tick(now)
+        self._last_tick = did
+        for peer, epoch, drift, _at in self.budget.clock_drift[seen_drift:]:
+            _line('  a receipt from', _short(peer), 'is timed %ds from this clock' % drift,
+                  '- check NTP on both ends before reading any divergence')
+        self.write_status(did)
+        sd_notify('WATCHDOG=1')
+        return did
+
+    # ---- status --------------------------------------------------------------------
+    PLANES: tuple[tuple[str, str, tuple[str, ...]], ...] = _VIEW_PLANES
+
+    def status(self) -> Mapping[str, Any]:
+        return node_status(self)
+
+    def health(self) -> Mapping[str, Any]:
+        """What is failing, and how often: the operator's view of every error
+        plane the node has. Nothing here is a finding about a peer."""
+        return node_health(self)
+
+    def write_status(self, did: Sequence[tuple[Any, ...]] | None = None) -> Mapping[str, Any]:
+        if did:
+            self._last_tick = did
+        st = self.status()
+        path = os.path.join(self.dir, 'status.json')
+        tmp = path + '.tmp'
+        with open(tmp, 'w', encoding='utf-8') as f:
+            json.dump(st, f, indent=2)
+        os.replace(tmp, path)
+        return st
+