fleetmesh-node 0.2.0__py3-none-any.whl

node/config/compartments.py

@@ -0,0 +1,1144 @@
+"""One config block per compartment.
+
+Each block is owned by the compartment that reads it and declared here so
+NodeConfig can compose them and `Registry.assemble` can hand each compartment
+its own, already checked. The fields are exactly the keys the compartment
+reads today, with the defaults it already applied; nothing an operator has
+written changes meaning. Seven of these blocks (announce, capacity, compute,
+dvm, lan, transport, and most of bridge) had no default and no check before:
+a misspelt key in them was silent.
+
+Every block defaults to off or to zero: a node does nothing it was not asked
+to, and charges nothing until a price is set.
+"""
+from __future__ import annotations
+
+import dataclasses
+import re
+from typing import Any, Mapping, MutableMapping, Optional, Union
+
+from fleetmesh_core.services import dvm as _ref_dvm
+from .base import (Block, Problems, all_int, all_str, is_hex64, is_http_url, is_relay_url, non_negative_int, opt,
+                   positive_int)
+from . import parameter as par
+from .parameter import Parameter, ParamBlock
+
+# --- bridge --------------------------------------------------------------
+
+DEFAULT_INGRESS_KINDS: list[int] = [
+    0, 1, 3, 6, 7, 1059, 1984, 1985,
+    11801, 11802, 11803, 21801, 21802,
+    30166, 30385, 30801, 30802, 30803, 30810, 30811,
+]
+DEFAULT_EGRESS_KINDS: list[int] = list(DEFAULT_INGRESS_KINDS)
+DEFAULT_INGRESS_FILTERS: list[Mapping[str, Any]] = [{'kinds': DEFAULT_INGRESS_KINDS}]
+DEFAULT_RATE_LIMIT_PER_MIN: int = 1200
+DEFAULT_MAX_FUTURE_SECONDS: int = 900
+DEFAULT_MAX_EVENT_BYTES: int = 256 * 1024
+
+
+@dataclasses.dataclass(frozen=True)
+class BridgeIngress(Block):
+    enabled: bool = True
+    filters: tuple[Mapping[str, Any], ...] = tuple(DEFAULT_INGRESS_FILTERS)
+    rate_limit: int = DEFAULT_RATE_LIMIT_PER_MIN
+    max_future_seconds: int = DEFAULT_MAX_FUTURE_SECONDS
+    max_bytes: int = DEFAULT_MAX_EVENT_BYTES
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('bridge.ingress must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'bridge.ingress.enabled must be a boolean')
+        opt(raw, 'filters', lambda v: isinstance(v, list) and all(isinstance(f, dict) for f in v), p,
+            'bridge.ingress.filters must be a list of filter objects')
+        opt(raw, 'rate_limit', positive_int, p, 'bridge.ingress.rate_limit must be a positive integer')
+        opt(raw, 'max_future_seconds', non_negative_int, p, 'bridge.ingress.max_future_seconds must be a non-negative integer')
+        opt(raw, 'max_bytes', positive_int, p, 'bridge.ingress.max_bytes must be a positive integer')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BridgeIngress':
+        return cls(enabled=bool(raw.get('enabled', True)), filters=tuple(raw.get('filters', DEFAULT_INGRESS_FILTERS)),
+                   rate_limit=int(raw.get('rate_limit', DEFAULT_RATE_LIMIT_PER_MIN)),
+                   max_future_seconds=int(raw.get('max_future_seconds', DEFAULT_MAX_FUTURE_SECONDS)),
+                   max_bytes=int(raw.get('max_bytes', DEFAULT_MAX_EVENT_BYTES)))
+
+
+@dataclasses.dataclass(frozen=True)
+class BridgeEgress(Block):
+    enabled: bool = True
+    kinds: tuple[int, ...] = tuple(DEFAULT_EGRESS_KINDS)
+    auto: bool = True
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('bridge.egress must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'bridge.egress.enabled must be a boolean')
+        opt(raw, 'kinds', all_int, p, 'bridge.egress.kinds must be a list of kind numbers')
+        opt(raw, 'auto', lambda v: isinstance(v, bool), p, 'bridge.egress.auto must be a boolean')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BridgeEgress':
+        return cls(enabled=bool(raw.get('enabled', True)), kinds=tuple(raw.get('kinds', DEFAULT_EGRESS_KINDS)),
+                   auto=bool(raw.get('auto', True)))
+
+
+STRFRY_PLUGIN_REF = 'fleetmesh_strfry.plugin:StrfryBridgePlugin'
+STRFRY_MOVED = ('bridge.strfry is no longer a part of the bridge: the strfry relay bridge is the '
+                'fleetmesh-strfry plugin. Remove the block and add %r to "plugins" (its url and '
+                'policy go under extensions.strfry), or run `python -m fleetmesh_strfry run` beside '
+                'the node.' % STRFRY_PLUGIN_REF)
+
+
+@dataclasses.dataclass(frozen=True)
+class BridgeConfig(ParamBlock):
+    """The public-Nostr bridge: which relays, what comes in, what goes out."""
+    key = 'bridge'
+    DERIVED = False
+    enabled: bool = True
+    relays: Optional[tuple[str, ...]] = None     # None: the node's relays
+    ingress: BridgeIngress = BridgeIngress()
+    egress: BridgeEgress = BridgeEgress()
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='Public Nostr Relay Bridge',
+            description='Bridge external standard Nostr relays with the local fleetmesh node. On by default.',
+            type=bool, default=True, must='be a boolean', live=True,
+            tags=('bridge', 'relay'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[Optional[list]](
+            key='relays', name='External Relay URLs',
+            description='Designated external standard Nostr relays (ws:// or wss://) to bridge with.',
+            type=list, default=None, must='be a list of ws:// or wss:// URLs', live=True,
+            tags=('bridge', 'relay'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not switch_or_object('bridge', raw, p):
+            return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'bridge.enabled must be a boolean')
+        opt(raw, 'relays', lambda v: isinstance(v, list) and all(is_relay_url(r) for r in v), p,
+            'bridge.relays must be a list of ws:// or wss:// URLs')
+        for sub, blk in (('ingress', BridgeIngress), ('egress', BridgeEgress)):
+            if sub in raw:
+                blk.check(raw[sub], p)
+        if 'strfry' in raw:
+            p.add(STRFRY_MOVED)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BridgeConfig':
+        if isinstance(raw, bool):
+            return cls(enabled=raw)
+        return cls(enabled=bool(raw.get('enabled', True)),
+                   relays=tuple(raw['relays']) if raw.get('relays') is not None else None,
+                   ingress=BridgeIngress.from_dict(raw.get('ingress') or {}),
+                   egress=BridgeEgress.from_dict(raw.get('egress') or {}))
+
+
+# --- the sidecar compartments -------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class AnnounceConfig(ParamBlock):
+    """The libp2p gossip announce sidecar: off unless enabled."""
+    key = 'announce'
+    enabled: bool = False
+    socket: Optional[str] = None
+    pow_bits: int = 0
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='Gossipsub announce',
+            description='Republish the descriptor on the gossipsub announce topic through the sidecar. '
+                        'Off unless enabled.',
+            type=bool, default=False, must='be a boolean', live=True,
+            tags=('announce', 'discovery'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[Optional[str]](
+            key='socket', name='Sidecar socket path',
+            description='Path to the unix domain socket the announce sidecar listens on. '
+                        'Defaults to announce.sock in the node directory.',
+            type=str, default=None, must='be a path', live=True,
+            coerce=lambda v: str(v) if v is not None else None,
+            tags=('announce', 'sidecar'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[int](
+            key='pow_bits', name='Proof of work floor',
+            description='Minimum proof-of-work bits required for descriptors heard on the announce topic.',
+            type=int, default=0, minimum=0, maximum=40,
+            must='be an integer from 0 to 40', live=True,
+            coerce=lambda v: int(v) if isinstance(v, (int, str)) and str(v).lstrip('-').isdigit() else 0,
+            tags=('announce', 'pow'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class LanConfig(ParamBlock):
+    """mDNS discovery on the local network: off unless enabled.
+
+    Note what this block does NOT do: presence does not turn it on. `p2p`
+    below looks identical and does. See ParamBlock.PRESENCE_ENABLES.
+    """
+    key = 'lan'
+    enabled: bool = False
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='mDNS discovery',
+            description='Announce and discover peers over mDNS on the local network. Off '
+                        'unless set, and unlike p2p the presence of the block alone does '
+                        'not turn it on.',
+            type=bool, default=False, must='be a boolean', live=True,
+            tags=('lan', 'discovery'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class P2PConfig(ParamBlock):
+    """The libp2p transport sidecar. The key's presence turns it on; the
+    block may be `true` or an object.
+
+    `PRESENCE_ENABLES` is what that sentence means, and it is load-bearing:
+    the field default is False but `from_dict({})` yields True, because a
+    node that mentions p2p at all wants it. Before this the difference lived
+    only in the body of from_dict, where it looked like a typo.
+    """
+    key = 'p2p'
+    SWITCHABLE = True
+    PRESENCE_ENABLES = 'enabled'
+    enabled: bool = False
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='libp2p transport',
+            description='Run the libp2p transport sidecar. True as soon as the block is '
+                        'present; write false to name the block and leave it off.',
+            type=bool, default=False, must='be a boolean',
+            tags=('p2p', 'transport'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+    )
+
+
+# --- capacity -------------------------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class CapacityConfig(ParamBlock):
+    """What this node has to give, {resource: amount}; only positive numbers count.
+
+    `DERIVED = False`: the raw form is the mapping itself, with no field names
+    in the file at all, so `check` and `from_dict` stay hand-written. The
+    parameter below is declared anyway so the census is complete - a setting
+    `every_parameter()` cannot show is a setting an operator cannot find.
+    """
+    key = 'capacity'
+    DERIVED = False
+    total: dict[str, float] = dataclasses.field(default_factory=dict)
+
+    PARAMS = (
+        Parameter[dict](
+            key='total', name='Offered capacity',
+            description='What this node has to give, as {resource: amount}. The block is '
+                        'the mapping itself rather than an object containing one. Only '
+                        'positive numbers are kept.',
+            type=dict, default=dict, must='be an object of {resource: amount}',
+            # live: the Capacity compartment re-reads this on every tick, which
+            # is why it declares `live = ('capacity',)`. The derivation in
+            # Compartment.__init_subclass__ caught this parameter saying
+            # otherwise on the first run of the cross-check.
+            live=True, tags=('capacity', 'offer'),
+            sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('capacity must be an object of {resource: amount}'); return
+        for k, v in raw.items():
+            if not isinstance(k, str) or isinstance(v, bool) or not isinstance(v, (int, float)):
+                p.add('capacity[%s] must be a number' % str(k)[:24])
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'CapacityConfig':
+        return cls(total={k: v for k, v in (raw or {}).items() if isinstance(v, (int, float)) and v > 0})
+
+
+@dataclasses.dataclass(frozen=True)
+class GossipConfig(ParamBlock):
+    """Group-topic epidemic gossip (graft/prune/publish mesh). The key's
+    presence turns it on; the block may be `true` or an object.
+
+    All four defaults were written twice before this - once in the fields and
+    once in `from_dict` - which is the duplication `Parameter` exists to end.
+    """
+    key = 'gossip'
+    SWITCHABLE = True
+    PRESENCE_ENABLES = 'enabled'
+    enabled: bool = False
+    mesh_degree: int = 6
+    seen_ttl_seconds: int = 24 * 3600
+    max_topics: int = 64
+
+    # The ceilings the two settings below may be raised to, and no further.
+    # GossipMesh sizes its stores from these (node/stores: a bound is fixed
+    # on the class), so a config that asked for more topics than the store
+    # holds would be refused at the store with a message about the store,
+    # not the setting. Refused here instead, naming the setting.
+    TOPIC_CEILING = 1024
+    MESH_DEGREE_CEILING = 64
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='Epidemic gossip',
+            description='Run the group-topic gossip mesh. True as soon as the block is '
+                        'present; write false to name the block and leave it off.',
+            type=bool, default=False, must='be a boolean',
+            tags=('gossip',), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[int](
+            key='mesh_degree', name='Mesh degree',
+            description='How many peers a topic mesh keeps grafted.',
+            type=int, default=6, minimum=1, maximum=MESH_DEGREE_CEILING,
+            must='be a positive integer, at most %d' % MESH_DEGREE_CEILING,
+            tags=('gossip', 'topology'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[int](
+            key='seen_ttl_seconds', name='Seen TTL',
+            description='How long a seen event id is remembered, to suppress a re-flood.',
+            type=int, default=24 * 3600, minimum=1, must='be a positive integer',
+            # Not live: the value is handed to SeenStore at construction
+            # (gossip_wire/core.py), so a reload does not reach it. Claiming
+            # otherwise would be the report-what-you-do-not-do defect again.
+            tags=('gossip', 'retention'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[int](
+            key='max_topics', name='Topic ceiling',
+            description='How many topics this node will carry at once.',
+            type=int, default=64, minimum=1, maximum=TOPIC_CEILING,
+            must='be a positive integer, at most %d' % TOPIC_CEILING,
+            tags=('gossip', 'capacity'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+    )
+
+
+# --- compute, dvm, settlement, mediation ----------------------------------
+
+def switch_or_object(name: str, raw: Any, p: Problems) -> bool:
+    """An optional compartment is turned on by its key's presence, so the
+    block may be plain `true` (on, every default) as well as an object.
+    Returns whether `raw` is an object the caller should go on checking."""
+    if isinstance(raw, bool):
+        return False
+    if not isinstance(raw, Mapping):
+        p.add('%s must be true, false or an object' % name)
+        return False
+    return True
+
+
+@dataclasses.dataclass(frozen=True)
+class ComputeConfig(ParamBlock):
+    """The compute market. `mock_mode` runs the executors as stubs."""
+    key = 'compute'
+    SWITCHABLE = True
+    mock_mode: bool = False
+    zk_pinned_vks: tuple[str, ...] = ()     # Groth16 verification-key digests the operator pins
+
+    PARAMS = (
+        Parameter[bool](
+            key='mock_mode', name='Mock executors',
+            description='Run the compute executors as stubs instead of executing anything. '
+                        'A node in this state sells work it does not do, so it is a host '
+                        'decision and never a remote one.',
+            type=bool, default=False, must='be a boolean',
+            tags=('compute', 'testing'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[tuple](
+            key='zk_pinned_vks', name='Pinned verification keys',
+            description='Groth16 verification-key digests this operator pins. A proof '
+                        'verifying against an unpinned key is not accepted.',
+            type=tuple, item=str, default=(), must='be a list of 64-hex digests',
+            verify_regex=r'[0-9a-fA-F]{64}',
+            coerce=lambda v: tuple(str(x).lower() for x in v),
+            # A trust anchor: what this node will believe a proof against. Not
+            # from a manifest, for the reason updates.release_key is not.
+            tags=('compute', 'zk', 'trust'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+
+DEFAULT_DVM_KINDS: list[int] = sorted({*_ref_dvm.DEFAULT_KINDS, _ref_dvm.TRANSCODE_KIND})   # fleetmesh_core/dvm.py owns the default + NIP-90 5201 transcode
+
+
+@dataclasses.dataclass(frozen=True)
+class DVMConfig(ParamBlock):
+    """NIP-90 data-vending: which kinds, what a mega-fuel costs, the fuel cap."""
+    key = 'dvm'
+    DERIVED = False
+    enabled: bool = True
+    supported_kinds: tuple[int, ...] = tuple(DEFAULT_DVM_KINDS)
+    rate_msat_per_mfuel: int = 45
+    max_fuel: int = 50_000_000_000
+    blossom_servers: tuple[str, ...] = ()
+    delegate_to_mesh: bool = False
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='DVM Gateway',
+            description='Enable the NIP-90 Data Vending Machine gateway.',
+            type=bool, default=True, must='be a boolean', live=True,
+            tags=('dvm', 'gateway'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[tuple](
+            key='supported_kinds', name='Supported DVM Kinds',
+            description='NIP-90 job request kinds this DVM node handles.',
+            type=tuple, default=tuple, must='be a list of integer kind numbers', live=True,
+            tags=('dvm', 'kinds'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[int](
+            key='rate_msat_per_mfuel', name='Rate msat per Mfuel',
+            description='Pricing in millisatoshis per mega-fuel unit.',
+            type=int, default=45, must='be a non-negative integer', live=True,
+            tags=('dvm', 'pricing'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[int](
+            key='max_fuel', name='Maximum Fuel Limit',
+            description='Upper bound on fuel consumption per job.',
+            type=int, default=50_000_000_000, must='be a positive integer', live=True,
+            tags=('dvm', 'limits'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[tuple](
+            key='blossom_servers', name='Blossom Servers',
+            description='Blossom servers used for DVM input/output blob transfers.',
+            type=tuple, default=tuple, must='be a list of http(s) URLs', live=True,
+            tags=('dvm', 'blossom'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[bool](
+            key='delegate_to_mesh', name='Delegate to Mesh',
+            description='Whether to delegate requests to mesh compute order book.',
+            type=bool, default=False, must='be a boolean', live=True,
+            tags=('dvm', 'delegation'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not switch_or_object('dvm', raw, p):
+            return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'dvm.enabled must be a boolean')
+        opt(raw, 'delegate_to_mesh', lambda v: isinstance(v, bool), p, 'dvm.delegate_to_mesh must be a boolean')
+        opt(raw, 'supported_kinds', all_int, p, 'dvm.supported_kinds must be a list of kind numbers')
+        opt(raw, 'rate_msat_per_mfuel', non_negative_int, p, 'dvm.rate_msat_per_mfuel must be a non-negative integer')
+        opt(raw, 'max_fuel', positive_int, p, 'dvm.max_fuel must be a positive integer')
+        opt(raw, 'blossom_servers', lambda v: isinstance(v, list) and all(is_http_url(s) for s in v), p,
+            'dvm.blossom_servers must be a list of http(s) URLs')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'DVMConfig':
+        if isinstance(raw, bool):
+            return cls()
+        return cls(enabled=bool(raw.get('enabled', True)), supported_kinds=tuple(raw.get('supported_kinds', DEFAULT_DVM_KINDS)),
+                   rate_msat_per_mfuel=int(raw.get('rate_msat_per_mfuel', 45)), max_fuel=int(raw.get('max_fuel', 50_000_000_000)),
+                   blossom_servers=tuple(raw.get('blossom_servers') or ()),
+                   delegate_to_mesh=bool(raw.get('delegate_to_mesh', False)))
+
+
+@dataclasses.dataclass(frozen=True)
+class NsiteConfig(ParamBlock):
+    """NIP-5A static-site gateway: which hostnames are sites, where blobs
+    come from when the author's servers are silent, how much to cache, and
+    whether a custom domain must be claimed in the manifest.
+
+    `suffixes`: hostnames under which the left-most label is a site
+    (`npub1….nsite.example.org`). `custom_domains`: serve a domain whose
+    `_nsite.<domain>` TXT names a site. `require_domain_tag`: that site's
+    manifest must also carry `["domain", "<domain>"]` - on by default so a
+    DNS record alone cannot front someone else's site. `allow_domains` turns
+    the gateway closed (only these), `deny_domains` blocks named ones.
+    Quotas are per cached blob, per site and for the whole cache.
+    """
+    key = 'nsite'
+    DERIVED = False
+    enabled: bool = True
+    suffixes: tuple[str, ...] = ()
+    custom_domains: bool = True
+    require_domain_tag: bool = True
+    allow_domains: tuple[str, ...] = ()
+    deny_domains: tuple[str, ...] = ()
+    fallback_servers: tuple[str, ...] = ()
+    relays: tuple[str, ...] = ()
+    allow_legacy_kind: bool = False
+    frame_ancestors: tuple[str, ...] = ()
+    cross_origin_isolation: bool = False
+    max_blob_bytes: int = 16 * 1024 * 1024
+    max_site_bytes: int = 256 * 1024 * 1024
+    max_cache_bytes: int = 4 * 1024 * 1024 * 1024
+    manifest_ttl_seconds: int = 300
+    domain_ttl_seconds: int = 6 * 3600
+    fetch_timeout: float = 10.0
+
+    PARAMS = (
+        Parameter[bool](
+            key='enabled', name='Nsite Gateway',
+            description='Enable NIP-5A static-site hosting gateway.',
+            type=bool, default=True, must='be a boolean', live=True,
+            tags=('nsite', 'gateway'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[tuple](
+            key='suffixes', name='Gateway Hostname Suffixes',
+            description='Host suffixes under which subdomains are routed to nsite static sites.',
+            type=tuple, default=tuple, must='be a list of host names', live=True,
+            tags=('nsite', 'routing'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[bool](
+            key='custom_domains', name='Custom Domains Support',
+            description='Allow custom domains via CNAME and _nsite DNS TXT records.',
+            type=bool, default=True, must='be a boolean', live=True,
+            tags=('nsite', 'dns'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[bool](
+            key='require_domain_tag', name='Require Domain Tag in Manifest',
+            description='Require site manifest to carry a matching domain tag to bind.',
+            type=bool, default=True, must='be a boolean', live=True,
+            tags=('nsite', 'security'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not switch_or_object('nsite', raw, p):
+            return
+        for k in ('enabled', 'custom_domains', 'require_domain_tag', 'allow_legacy_kind', 'cross_origin_isolation'):
+            opt(raw, k, lambda v: isinstance(v, bool), p, 'nsite.%s must be a boolean' % k)
+        for k in ('suffixes', 'allow_domains', 'deny_domains', 'frame_ancestors'):
+            opt(raw, k, all_str, p, 'nsite.%s must be a list of host names' % k)
+        opt(raw, 'fallback_servers', lambda v: isinstance(v, list) and all(is_http_url(s) for s in v), p,
+            'nsite.fallback_servers must be a list of http(s) URLs')
+        opt(raw, 'relays', lambda v: isinstance(v, list) and all(is_relay_url(s) for s in v), p,
+            'nsite.relays must be a list of ws(s) URLs')
+        for k in ('max_blob_bytes', 'max_site_bytes', 'max_cache_bytes', 'manifest_ttl_seconds', 'domain_ttl_seconds'):
+            opt(raw, k, positive_int, p, 'nsite.%s must be a positive integer' % k)
+        opt(raw, 'fetch_timeout', lambda v: isinstance(v, (int, float)) and not isinstance(v, bool) and v > 0, p,
+            'nsite.fetch_timeout must be a positive number of seconds')
+        if isinstance(raw, dict) and raw.get('enabled', True) and not raw.get('suffixes') and not raw.get('custom_domains', True):
+            p.add('nsite: with no suffixes and custom_domains off the gateway can serve nothing')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'NsiteConfig':
+        if isinstance(raw, bool):
+            return cls()
+        g = lambda k, d: raw.get(k, d)  # noqa: E731
+        return cls(enabled=bool(g('enabled', True)), suffixes=tuple(g('suffixes', ()) or ()),
+                   custom_domains=bool(g('custom_domains', True)), require_domain_tag=bool(g('require_domain_tag', True)),
+                   allow_domains=tuple(g('allow_domains', ()) or ()), deny_domains=tuple(g('deny_domains', ()) or ()),
+                   fallback_servers=tuple(g('fallback_servers', ()) or ()), relays=tuple(g('relays', ()) or ()),
+                   allow_legacy_kind=bool(g('allow_legacy_kind', False)),
+                   frame_ancestors=tuple(g('frame_ancestors', ()) or ()),
+                   cross_origin_isolation=bool(g('cross_origin_isolation', False)),
+                   max_blob_bytes=int(g('max_blob_bytes', cls.max_blob_bytes)),
+                   max_site_bytes=int(g('max_site_bytes', cls.max_site_bytes)),
+                   max_cache_bytes=int(g('max_cache_bytes', cls.max_cache_bytes)),
+                   manifest_ttl_seconds=int(g('manifest_ttl_seconds', cls.manifest_ttl_seconds)),
+                   domain_ttl_seconds=int(g('domain_ttl_seconds', cls.domain_ttl_seconds)),
+                   fetch_timeout=float(g('fetch_timeout', cls.fetch_timeout)))
+
+
+@dataclasses.dataclass(frozen=True)
+class SettlementConfig(ParamBlock):
+    """How compute is paid for: a NWC wallet, or a live Cashu mint."""
+    key = 'settlement'
+    nwc_uri: Optional[str] = None
+    live_cashu: bool = False
+    mint_url: Optional[str] = None       # None: payment.DEFAULT_MINT_URL
+
+    PARAMS = (
+        Parameter[Optional[str]](
+            key='nwc_uri', name='Wallet connection',
+            description='A Nostr Wallet Connect URI this node pays and is paid through.',
+            type=str, default=None, must='be a nostr+walletconnect:// URI',
+            verify_regex=r'nostr\+walletconnect://.+',
+            # A credential. `secret` keeps it out of every report and every
+            # audit row; host-only sources keep it out of anything that could
+            # set it remotely.
+            secret=True, tags=('settlement', 'money', 'credential'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[bool](
+            key='live_cashu', name='Live Cashu mint',
+            description='Use a real Cashu mint rather than the offline token path. Real '
+                        'money moves when this is on.',
+            type=bool, default=False, must='be a boolean',
+            tags=('settlement', 'money'), sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[Optional[str]](
+            key='mint_url', name='Mint URL',
+            description='The Cashu mint to use. Unset means payment.DEFAULT_MINT_URL.',
+            type=str, default=None, must='be an http(s) URL',
+            verify_regex=r'https?://.+',
+            tags=('settlement', 'money'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class MediationConfig(ParamBlock):
+    """The mediator / leaf-phone compartment. Reserved: no operator keys yet.
+
+    An empty PARAMS is the correct and final answer here, not work left
+    over: `converted()` asks whether a block states its settings as
+    parameters, not whether it has any.
+    """
+    key = 'mediation'
+
+
+@dataclasses.dataclass(frozen=True)
+class TransportConfig(ParamBlock):
+    """compute-wire transport preferences. Reserved: no operator keys yet."""
+    key = 'transport'
+
+
+# --- blobs ------------------------------------------------------------------
+
+BLOB_WIRE_CAPS: tuple[str, ...] = ('bytes_per_day', 'max_concurrent', 'max_blob_bytes', 'max_total_bytes')
+
+
+@dataclasses.dataclass(frozen=True)
+class BlobWireConfig(ParamBlock):
+    """blob/1.0: who this node accepts offers from, the chunk size, the caps.
+
+    `accept_from` is `none`, `grantees`, or a list of pubkeys. The caps are
+    per peer and default to the window constants (node/blob_wire.py reads
+    them from window.C, so they are None here and resolved there): zero is
+    "no bytes", not "unlimited".
+    """
+    key = 'blob_wire'
+    accept_from: Union[str, tuple[str, ...]] = 'none'
+    chunk_bytes: Optional[int] = None
+    bytes_per_day: Optional[int] = None
+    max_concurrent: Optional[int] = None
+    max_blob_bytes: Optional[int] = None
+    max_total_bytes: Optional[int] = None
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='accept_from', name='Accept From', description='Whom to accept offers from', type=str, default='none', tags=('blob', 'wire')),
+        Parameter(key='chunk_bytes', name='Chunk Bytes', description='Transfer chunk size', type=int, default=None, tags=('blob', 'wire')),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('blob_wire must be an object'); return
+        opt(raw, 'accept_from', lambda v: v in ('none', 'grantees') or (isinstance(v, list) and all(is_hex64(x) for x in v)),
+            p, 'blob_wire.accept_from must be none, grantees, or a list of 64-hex pubkeys')
+        opt(raw, 'chunk_bytes', positive_int, p, 'blob_wire.chunk_bytes must be a positive integer')
+        for k in BLOB_WIRE_CAPS:
+            opt(raw, k, non_negative_int, p, 'blob_wire.%s must be a non-negative integer' % k)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BlobWireConfig':
+        af = raw.get('accept_from', 'none')
+        return cls(accept_from=tuple(str(x).lower() for x in af) if isinstance(af, list) else af,
+                   chunk_bytes=raw.get('chunk_bytes'), **{k: raw.get(k) for k in BLOB_WIRE_CAPS})
+
+
+@dataclasses.dataclass(frozen=True)
+class BlobReplicationConfig(ParamBlock):
+    """How many copies of each blob to keep across partners, and where from."""
+    key = 'blob_replication'
+    copies: int = 2
+    allow_private: Union[bool, tuple[str, ...]] = False     # true, or the hosts a LAN cluster allows
+    source_url: Optional[str] = None
+    servers: tuple[str, ...] = ()
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='copies', name='Target Copies', description='Target copy count across network', type=int, default=2, tags=('blob', 'replication')),
+        Parameter(key='allow_private', name='Allow Private', description='Allow private LAN addresses', type=bool, default=False, tags=('blob', 'replication')),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('blob_replication must be an object'); return
+        opt(raw, 'copies', non_negative_int, p, 'blob_replication.copies must be a non-negative integer')
+        opt(raw, 'allow_private', lambda v: isinstance(v, bool) or all_str(v), p,
+            'blob_replication.allow_private must be a boolean or a list of hosts')
+        opt(raw, 'source_url', is_http_url, p, 'blob_replication.source_url must be an http(s) URL')
+        opt(raw, 'servers', all_str, p, 'blob_replication.servers must be a list of URLs')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BlobReplicationConfig':
+        ap = raw.get('allow_private', False)
+        return cls(copies=int(raw.get('copies', 2)), allow_private=tuple(ap) if isinstance(ap, list) else bool(ap),
+                   source_url=raw.get('source_url'), servers=tuple(raw.get('servers') or ()))
+
+
+@dataclasses.dataclass(frozen=True)
+class StorageConfig(Block):
+    """The MeshNode manifest's storage block, as the node reads it."""
+    key = 'storage'
+    max_bytes: Optional[int] = None
+    allow_private_mirror: Union[bool, tuple[str, ...]] = False   # true, or the LAN hosts a /mirror may read from
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('storage must be an object'); return
+        if 'maxBytes' in raw and raw['maxBytes'] not in (None, ''):
+            try:
+                int(raw['maxBytes'])
+            except (TypeError, ValueError):
+                p.add('blob storage cap is not an integer: %r' % (raw['maxBytes'],))
+        opt(raw, 'allowPrivateMirror', lambda v: isinstance(v, bool) or all_str(v), p,
+            'storage.allowPrivateMirror must be a boolean or a list of hosts')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'StorageConfig':
+        mb = raw.get('maxBytes')
+        cap = int(mb) if mb not in (None, '') else 0
+        ap = raw.get('allowPrivateMirror', False)
+        return cls(max_bytes=cap if cap > 0 else None,
+                   allow_private_mirror=tuple(ap) if isinstance(ap, list) else bool(ap))
+
+
+@dataclasses.dataclass(frozen=True)
+class BlobsConfig(Block):
+    """The node's own blob store: cap (wins over storage.maxBytes) and on-disk layout.
+
+    ``fanout`` (0..8, default 1) and ``data_dir`` (default ``<node>/blobs/data``)
+    let an operator share a sha256 tree with another CAS laid out the same way
+    (magpie: its ``objects/`` at fanout 2). Both are one-way doors: the store
+    records them on first open and refuses a later change.
+    """
+    key = 'blobs'
+    max_storage_bytes: Optional[int] = None
+    fanout: int = 1
+    data_dir: Optional[str] = None
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('blobs must be an object'); return
+        if 'max_storage_bytes' in raw and raw['max_storage_bytes'] not in (None, ''):
+            try:
+                int(raw['max_storage_bytes'])
+            except (TypeError, ValueError):
+                p.add('blob storage cap is not an integer: %r' % (raw['max_storage_bytes'],))
+        if 'fanout' in raw and raw['fanout'] not in (None, ''):
+            f = raw['fanout']
+            if isinstance(f, bool) or not isinstance(f, int) or not 0 <= f <= 8:
+                p.add('blobs.fanout must be an integer 0..8: %r' % (f,))
+        if 'data_dir' in raw and raw['data_dir'] not in (None, '') and not isinstance(raw['data_dir'], str):
+            p.add('blobs.data_dir must be a path string: %r' % (raw['data_dir'],))
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'BlobsConfig':
+        v = raw.get('max_storage_bytes')
+        cap = int(v) if v not in (None, '') else 0
+        f = raw.get('fanout')
+        d = raw.get('data_dir')
+        return cls(max_storage_bytes=cap if cap > 0 else None,
+                   fanout=int(f) if f not in (None, '') else 1,
+                   data_dir=str(d) if d not in (None, '') else None)
+
+
+# --- the external engines ------------------------------------------------
+
+_PLUGIN_REF = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*$')
+
+
+@dataclasses.dataclass(frozen=True)
+class PluginSpec:
+    """One out-of-tree compartment: `ref` is `package.module:ClassName`;
+    `after` names the manifest compartment it ticks right after (default: last)."""
+    ref: str
+    after: Optional[str] = None
+
+
+@dataclasses.dataclass(frozen=True)
+class PluginsConfig(Block):
+    """Out-of-tree compartments loaded into the manifest at startup.
+
+        "plugins": [{"ref": "fleetmesh_foo.node:Foo", "after": "budget"}]
+
+    A plugin is operator-trusted code: it is imported into the node's
+    process and sees everything a core compartment sees, keys included.
+    Installing one is the same act of trust as editing node/app/core.py;
+    the config block exists so that act is declared in one file an operator
+    reads, not hidden in a site-packages directory. Untrusted or
+    third-party extensions belong out of process (a sidecar) - see
+    docs/extending.md. Each plugin reads its own config under
+    `extensions.<name>`.
+    """
+    key = 'plugins'
+    specs: tuple[PluginSpec, ...] = ()
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, list):
+            p.add('plugins must be a list of {ref, after?}'); return
+        for i, e in enumerate(raw):
+            if isinstance(e, str):
+                e = {'ref': e}
+            if not isinstance(e, Mapping) or not isinstance(e.get('ref'), str):
+                p.add('plugins[%d] needs a string ref "package.module:Class"' % i); continue
+            if not _PLUGIN_REF.match(e['ref']):
+                p.add('plugins[%d].ref is not package.module:Class: %r' % (i, e['ref']))
+            if 'after' in e and e['after'] is not None and not isinstance(e['after'], str):
+                p.add('plugins[%d].after must be a compartment name' % i)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'PluginsConfig':
+        specs = []
+        for e in raw or ():
+            if isinstance(e, str):
+                e = {'ref': e}
+            specs.append(PluginSpec(ref=e['ref'], after=e.get('after')))
+        return cls(specs=tuple(specs))
+
+
+@dataclasses.dataclass(frozen=True)
+class SidecarEntry:
+    """One sidecar an operator runs: on only with an endpoint. `manifest` is
+    where its description comes from - absent for a built-in (grasp,
+    ncontainer, magpie: the node ships those), `@/path/file.json` or an
+    inline object for anyone else's."""
+    enabled: bool = False
+    endpoint: Optional[str] = None
+    manifest: Any = None            # None | '@/path.json' | dict
+
+    @property
+    def on(self) -> bool:
+        return bool(self.enabled and self.endpoint)
+
+
+# What `grasp:`/`ncontainer:`/`magpie:` were before they moved under `sidecars`.
+SIDECAR_KEYS_MOVED = ('grasp', 'ncontainer', 'magpie')
+SIDECAR_MOVED = ('%s is now an entry of the "sidecars" block: '
+                 '"sidecars": {"%s": {"enabled": true, "endpoint": "..."}}. The old top-level key is read for '
+                 'this release and refused in the next.')
+_SIDECAR_NAME = re.compile(r'^[a-z][a-z0-9_-]{0,31}$')
+
+
+@dataclasses.dataclass(frozen=True)
+class SidecarsConfig(ParamBlock):
+    """The services this node fronts, by name. Each is declared on the
+    descriptor only after its manifest's self-tests pass (node/sidecars.py).
+
+        "sidecars": {
+          "grasp":  {"enabled": true, "endpoint": "http://127.0.0.1:9000"},
+          "myhost": {"enabled": true, "endpoint": "http://127.0.0.1:9300",
+                     "manifest": "@/etc/fleetmesh/myhost.sidecar.json"}
+        }
+    """
+    key = 'sidecars'
+    entries: Mapping[str, SidecarEntry] = dataclasses.field(default_factory=dict)
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='entries', name='Sidecar Entries', description='Configured sidecar services', type=dict, default={}, tags=('sidecars', 'services')),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('sidecars must be an object of {name: {enabled, endpoint[, manifest]}}'); return
+        for name, e in raw.items():
+            if not isinstance(name, str) or not _SIDECAR_NAME.match(name):
+                p.add('sidecars: %r is not a sidecar name (short lowercase identifier)' % (name,)); continue
+            if not isinstance(e, Mapping):
+                p.add('sidecars.%s must be an object' % name); continue
+            opt(e, 'enabled', lambda v: isinstance(v, bool), p, 'sidecars.%s.enabled must be a boolean' % name)
+            opt(e, 'endpoint', is_http_url, p, 'sidecars.%s.endpoint must be an http(s) URL' % name)
+            if e.get('enabled') and not e.get('endpoint'):
+                p.add('sidecars.%s.enabled needs sidecars.%s.endpoint' % (name, name))
+            m = e.get('manifest')
+            if m is not None and not (isinstance(m, Mapping) or (isinstance(m, str) and m.startswith('@'))):
+                p.add('sidecars.%s.manifest must be an inline object or "@/path/to/manifest.json"' % name)
+            extra = set(e) - {'enabled', 'endpoint', 'manifest'}
+            if extra:
+                p.add('sidecars.%s has unknown keys: %s' % (name, ', '.join(sorted(extra))))
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'SidecarsConfig':
+        out = {}
+        for name, e in (raw or {}).items():
+            e = e or {}
+            out[name] = SidecarEntry(enabled=bool(e.get('enabled', False)), endpoint=e.get('endpoint'),
+                                     manifest=e.get('manifest'))
+        return cls(entries=out)
+
+    def to_dict(self) -> Mapping[str, Any]:
+        d: dict[str, Mapping[str, Any]] = {}
+        for name, e in self.entries.items():
+            row: MutableMapping[str, Any] = {'enabled': e.enabled}
+            if e.endpoint is not None:
+                row['endpoint'] = e.endpoint
+            if e.manifest is not None:
+                row['manifest'] = e.manifest
+            d[name] = row
+        return d
+
+
+def sidecars_of(cfg: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    """The raw `sidecars` entries, with the moved top-level keys folded in
+    for this release. One place reads both shapes; everything else sees
+    the new one."""
+    out: dict[str, Mapping[str, Any]] = dict(cfg.get('sidecars') or {})
+    for k in SIDECAR_KEYS_MOVED:
+        if k in cfg and k not in out and isinstance(cfg[k], Mapping):
+            out[k] = cfg[k]
+    return out
+
+
+# --- updates: check-and-report ------------------------------------------------
+
+# The project's release signer: npub1dxlsl0y...4xs7uy, the identity that signs
+# everything fleetmesh publishes on nostr (OpenBao fleetmesh/publisher; release.sh
+# stamps it into every manifest it signs). The committed manifests once carried
+# the FIXTURE key from fixtures/npack/ instead, and a node that trusted that
+# would have refused every genuine release - test_updates pins this to the
+# packaged manifests so the three cannot drift apart again.
+#
+# This is the fallback, not the default. The default `updates.release_key` is
+# "the key that made me": the publisher stamped into the tree by release.sh
+# (node/PUBLISHER) or, in a checkout, the one in packages/fleetmesh-node's
+# manifest - see default_release_key(). A fork's build therefore listens to the
+# fork's signer without anyone editing a config. The operator can always write
+# another key; it is a plain config value and state() shows which is in effect.
+PROJECT_RELEASE_KEY: str = '69bf0fbc8211488fc321bee5bfa07bae184a881b0b16c3fb6e13a4b1dda28124'
+
+
+def default_release_key() -> str:
+    from ..release import running
+    return running().publisher or PROJECT_RELEASE_KEY
+DEFAULT_CHECK_EVERY_SECONDS: int = 21600
+UPDATE_POLICIES: tuple[str, ...] = ('pinned',)   # 'track:patch' / 'track:minor' arrive with the apply tier
+TRACK_NOT_YET: str = ("updates.policy: %r is not available yet; this release checks and reports. "
+                      "Use 'pinned'")
+
+
+@dataclasses.dataclass(frozen=True)
+class UpdatesConfig(ParamBlock):
+    """Check-and-report against an operator-pinned release key. See docs/updates.md.
+
+    The first compartment converted to `Parameter` (node/config/parameter.py).
+    Each setting is declared once in `PARAMS`; `check` and `from_dict` are
+    derived from it, and the four sentences an operator can be told are the
+    four `must` clauses below. Nothing here states a default twice -
+    `check_every` used to state `DEFAULT_CHECK_EVERY_SECONDS` in the field and
+    again in `from_dict`.
+    """
+    key = 'updates'
+    SWITCHABLE = True
+
+    release_key: str = dataclasses.field(default_factory=default_release_key)
+    channel: tuple[str, ...] = ()
+    check_every: int = DEFAULT_CHECK_EVERY_SECONDS
+    policy: Mapping[str, str] = dataclasses.field(default_factory=lambda: {'*': 'pinned'})
+    pinned: Optional[str] = None
+
+    PARAMS = (
+        Parameter[str](
+            key='release_key', name='Release signing key',
+            description='Who may sign a release this node will mention. Defaults to the key '
+                        'that signed the release this tree came from.',
+            type=str, default=default_release_key, must='be a 64-hex pubkey',
+            verify_regex=r'[0-9a-fA-F]{64}', coerce=lambda v: str(v).lower(),
+            tags=('updates', 'trust'), env='FLEETMESH_RELEASE_KEY',
+            # The key that decides which releases this node will mention, so
+            # the host and nobody else. No ability is named, which means no
+            # delegation can ever carry it; and no manifest, because a fleet
+            # declaration reaching the release-signing key is a supply chain
+            # with one more link in it than anyone intended.
+            sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[tuple](
+            key='channel', name='Release channel relays',
+            description='Relays the kind 9900 release events live on. Empty means the '
+                        "node's own relays.",
+            type=tuple, item=str, default=(), must='be a list of ws(s) relay URLs',
+            verify_regex=r'wss?://.+', coerce=lambda v: tuple(str(u) for u in v),
+            tags=('updates', 'relays'), sources=(par.ARG, par.ENV, par.FILE, par.MANIFEST)),
+        Parameter[int](
+            key='check_every', name='Check interval',
+            description='Seconds between checks. 0 means only on `meshnode updates.check`.',
+            type=int, default=DEFAULT_CHECK_EVERY_SECONDS, minimum=0,
+            must='be a non-negative integer of seconds',
+            tags=('updates', 'cadence'), live=True,
+            # The only setting in this block that is safe to hand out: it
+            # paces a check and cannot change what the node trusts. Named as
+            # a UCAN ability rather than a role, and declared only - nothing
+            # authenticates a principal yet (see ACCESS_DECLARED_ONLY).
+            requires='config/updates.cadence'),
+        Parameter[dict](
+            key='policy', name='Per-compartment update policy',
+            description="Policy per compartment or '*'. Only 'pinned' exists in this tier; a "
+                        'track is refused by name so an operator who writes one learns it does '
+                        'nothing instead of believing it does.',
+            type=dict, default=lambda: {'*': 'pinned'}, choices=UPDATE_POLICIES,
+            must='be an object of compartment -> policy', tags=('updates', 'policy'),
+            coerce=dict, validate=lambda label, raw, p: _check_update_policy(label, raw, p),
+            sources=(par.ARG, par.ENV, par.FILE)),
+        Parameter[Optional[str]](
+            key='pinned', name='Pinned release',
+            description='What the operator says they run. Unset means Release.running().',
+            type=str, default=None, must='be a semver string (e.g. 0.1.0)',
+            validate=lambda label, raw, p: _check_pinned(label, raw, p),
+            tags=('updates', 'release'), sources=(par.ARG, par.ENV, par.FILE)),
+    )
+
+
+def _check_update_policy(label: str, raw: Any, p: Problems) -> None:
+    """`updates.policy`: a mapping whose values are an enum, plus one sentence
+    for a policy that does not exist yet.
+
+    A parameter's own fields cannot say this - the enum applies to the values
+    of a mapping, and `track:` has its own message - so the parameter carries
+    this instead, and is still the single place the setting is declared.
+    """
+    pol = raw.get('policy')
+    if pol is None:
+        return
+    if not isinstance(pol, Mapping) or not all(isinstance(k, str) for k in pol):
+        p.add('%s.policy must be an object of compartment -> policy' % label)
+        return
+    for k, v in pol.items():
+        if isinstance(v, str) and v.startswith('track:'):
+            p.add(TRACK_NOT_YET % v)
+        elif v not in UPDATE_POLICIES:
+            p.add('%s.policy.%s must be one of %s' % (label, k, ', '.join(UPDATE_POLICIES)))
+
+
+def _check_pinned(label: str, raw: Any, p: Problems) -> None:
+    """`updates.pinned`: a semver, parsed by the release module rather than
+    matched by a pattern, so one definition of a version decides."""
+    pinned = raw.get('pinned')
+    if pinned is None:
+        return
+    from ..release import parse_semver
+    if not isinstance(pinned, str) or parse_semver(pinned) is None:
+        p.add('%s.pinned must be a semver string (e.g. 0.1.0)' % label)
+
+
+# --- fetch pricing -------------------------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class CashuRail(Block):
+    mints: tuple[str, ...] = ()
+    unit: str = 'sat'
+    sweep_above_sat: int = 0
+    sweep_to: Optional[str] = None
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('fetch_pricing.rails.cashu must be an object'); return
+        opt(raw, 'mints', lambda v: isinstance(v, list) and all(is_http_url(m) for m in v), p,
+            'fetch_pricing.rails.cashu.mints must be a list of http(s) URLs')
+        opt(raw, 'unit', lambda v: isinstance(v, str), p, 'fetch_pricing.rails.cashu.unit must be a string')
+        opt(raw, 'sweep_above_sat', non_negative_int, p, 'fetch_pricing.rails.cashu.sweep_above_sat must be a non-negative integer')
+        opt(raw, 'sweep_to', lambda v: v is None or isinstance(v, str), p, 'fetch_pricing.rails.cashu.sweep_to must be a string or null')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'CashuRail':
+        return cls(mints=tuple(raw.get('mints') or ()), unit=str(raw.get('unit') or 'sat'),
+                   sweep_above_sat=int(raw.get('sweep_above_sat') or 0), sweep_to=raw.get('sweep_to'))
+
+
+PRICING_RULE_KEYS: tuple[str, ...] = ('min_bytes', 'max_bytes', 'content_type', 'uploader', 'msat_per_mb', 'msat')
+
+
+@dataclasses.dataclass(frozen=True)
+class PricingRule(Block):
+    """One match-and-price rule; first match wins. See node/fetch_pricing.py."""
+    min_bytes: Optional[int] = None
+    max_bytes: Optional[int] = None
+    content_type: Optional[str] = None
+    uploader: Optional[str] = None
+    msat_per_mb: Optional[int] = None
+    msat: int = 0
+
+    @staticmethod
+    def check_one(i: int, e: Any, p: Problems) -> None:
+        if not isinstance(e, Mapping):
+            p.add('fetch_pricing.rules[%d] must be an object' % i); return
+        for k in ('min_bytes', 'max_bytes', 'msat_per_mb', 'msat'):
+            if k in e and not non_negative_int(e[k]):
+                p.add('fetch_pricing.rules[%d].%s must be a non-negative integer' % (i, k))
+        for k in ('content_type', 'uploader'):
+            if k in e and not isinstance(e[k], str):
+                p.add('fetch_pricing.rules[%d].%s must be a string' % (i, k))
+        unknown = sorted(set(e) - set(PRICING_RULE_KEYS))
+        if unknown:
+            p.add('fetch_pricing.rules[%d] has keys no rule reads: %s' % (i, ', '.join(unknown)))
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'PricingRule':
+        return cls(min_bytes=raw.get('min_bytes'), max_bytes=raw.get('max_bytes'), content_type=raw.get('content_type'),
+                   uploader=raw.get('uploader'), msat_per_mb=raw.get('msat_per_mb'), msat=int(raw.get('msat', 0)))
+
+
+@dataclasses.dataclass(frozen=True)
+class FetchPricingConfig(ParamBlock):
+    """What a fetch costs. Everything defaults to zero or off."""
+    key = 'fetch_pricing'
+    default_msat: int = 0
+    free_for_partners: bool = True
+    free_bytes_per_day: Optional[int] = None
+    max_account_fee_msat: int = 0
+    grasp_session_msat: int = 0
+    sidecar_session_msat: Mapping[str, int] = dataclasses.field(default_factory=dict)
+    rules: tuple[PricingRule, ...] = ()
+    cashu: CashuRail = CashuRail()
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='default_msat', name='Default Price (msat)', description='Default fetch price in millisatoshis', type=int, default=0, tags=('fetch', 'pricing')),
+        Parameter(key='free_for_partners', name='Free for Partners', description='Waive fetch fee for peering partners', type=bool, default=True, tags=('fetch', 'pricing')),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('fetch_pricing must be an object'); return
+        opt(raw, 'default_msat', non_negative_int, p, 'fetch_pricing.default_msat must be a non-negative integer')
+        opt(raw, 'free_for_partners', lambda v: isinstance(v, bool), p, 'fetch_pricing.free_for_partners must be a boolean')
+        opt(raw, 'free_bytes_per_day', lambda v: v is None or non_negative_int(v), p,
+            'fetch_pricing.free_bytes_per_day must be a non-negative integer or null')
+        opt(raw, 'max_account_fee_msat', non_negative_int, p, 'fetch_pricing.max_account_fee_msat must be a non-negative integer')
+        opt(raw, 'grasp_session_msat', non_negative_int, p, 'fetch_pricing.grasp_session_msat must be a non-negative integer')
+        ssm = raw.get('sidecar_session_msat', {})
+        if not isinstance(ssm, Mapping) or not all(isinstance(k, str) and _SIDECAR_NAME.match(k) and non_negative_int(v)
+                                                   for k, v in ssm.items()):
+            p.add('fetch_pricing.sidecar_session_msat must be {sidecar name: non-negative msat}')
+        rules = raw.get('rules', [])
+        if not isinstance(rules, list):
+            p.add('fetch_pricing.rules must be a list')
+        else:
+            for i, e in enumerate(rules):
+                PricingRule.check_one(i, e, p)
+        rails = raw.get('rails', {})
+        if not isinstance(rails, Mapping):
+            p.add('fetch_pricing.rails must be an object')
+        elif 'cashu' in rails:
+            CashuRail.check(rails['cashu'], p)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'FetchPricingConfig':
+        rails = raw.get('rails') or {}
+        return cls(default_msat=int(raw.get('default_msat') or 0), free_for_partners=bool(raw.get('free_for_partners', True)),
+                   free_bytes_per_day=raw.get('free_bytes_per_day'), max_account_fee_msat=int(raw.get('max_account_fee_msat') or 0),
+                   grasp_session_msat=int(raw.get('grasp_session_msat') or 0),
+                   sidecar_session_msat={k: int(v) for k, v in (raw.get('sidecar_session_msat') or {}).items()},
+                   rules=tuple(PricingRule.from_dict(r) for r in raw.get('rules') or []),
+                   cashu=CashuRail.from_dict(rails.get('cashu') or {}))
+
+    def to_dict(self) -> Mapping[str, Any]:
+        """The file shape keeps `rails: {cashu: ...}`, so the default stays byte-identical."""
+        d = dict(super().to_dict())
+        d['rails'] = {'cashu': d.pop('cashu')}
+        return d
+
+
+# --- protocol suites ------------------------------------------------------
+
+from .protocols import (
+    ActivityPubProtocolConfig,
+    ATProtoProtocolConfig,
+    HostMultiplexerConfig,
+    NostrProtocolConfig,
+    P2PandaProtocolConfig,
+    ProtocolSuitesConfig,
+    RhioProtocolConfig,
+    SSBProtocolConfig,
+)
+
+
+COMPARTMENT_BLOCKS: tuple[type[Block], ...] = (
+    BridgeConfig, AnnounceConfig, LanConfig, P2PConfig, GossipConfig, CapacityConfig, ComputeConfig, DVMConfig,
+    SettlementConfig, MediationConfig, TransportConfig, BlobWireConfig, BlobReplicationConfig,
+    StorageConfig, BlobsConfig, SidecarsConfig, FetchPricingConfig, UpdatesConfig,
+    PluginsConfig,
+)
+
+__all__ = [c.__name__ for c in COMPARTMENT_BLOCKS] + [
+    'BridgeIngress', 'BridgeEgress', 'STRFRY_PLUGIN_REF', 'STRFRY_MOVED', 'SidecarEntry', 'SIDECAR_KEYS_MOVED', 'SIDECAR_MOVED', 'sidecars_of', 'CashuRail', 'PricingRule',
+    'HostMultiplexerConfig', 'NostrProtocolConfig', 'ATProtoProtocolConfig', 'ActivityPubProtocolConfig', 'SSBProtocolConfig',
+    'P2PandaProtocolConfig', 'RhioProtocolConfig', 'ProtocolSuitesConfig',
+    'COMPARTMENT_BLOCKS', 'PRICING_RULE_KEYS', 'BLOB_WIRE_CAPS', 'switch_or_object', 'DEFAULT_INGRESS_KINDS', 'DEFAULT_EGRESS_KINDS',
+    'DEFAULT_INGRESS_FILTERS', 'DEFAULT_RATE_LIMIT_PER_MIN', 'DEFAULT_MAX_FUTURE_SECONDS',
+    'DEFAULT_MAX_EVENT_BYTES', 'DEFAULT_DVM_KINDS', 'PROJECT_RELEASE_KEY', 'default_release_key', 'UPDATE_POLICIES', 'TRACK_NOT_YET']
+