fleetmesh-node 0.2.0__py3-none-any.whl

node/app/control.py

@@ -0,0 +1,670 @@
+"""The operator's face of the node: the control-socket dispatcher, the
+actions only the daemon can take, and the shims that forward to compartments.
+
+A mixin, not a module of functions, because every method here reads and
+writes the node's own state (`self.grants`, `self.peering`, `self.cfg`) and
+tests and the CLI call them as NodeApp methods. NodeApp in core.py inherits
+it; nothing else does.
+"""
+from __future__ import annotations
+
+import collections
+import threading
+from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Optional, TypedDict, cast
+
+from ..interfaces import CommandSpec
+
+from fleetmesh_core.accounting import accounting, standing, window
+from fleetmesh_core.identity import identity
+from fleetmesh_core.services import lifecycle
+from fleetmesh_core.storage import store as store_mod
+from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent, StandingTellBody
+from .. import (channels as channels_mod,
+                release as release_mod, transport as transport_mod)
+from ..channels.bus import BusEnvelope, BusState
+from . import socket as control_mod
+from ..storage import grants as grants_mod
+from ..protocols.nostr import client as relay, descriptor  # noqa: E402
+from ..channels.journal import line as _line, short as _short
+from ..compartment.command import CommandError
+from ..compartment import lifecycle as compartment_lifecycle
+from .commands import NODE_COMMANDS_BY_KEY
+from .config import CONTROL, save_config
+from .views import GrantView, WindowView, _live_peers, grant_view, windows_view
+
+if TYPE_CHECKING:
+    from .. import compartment as compartment_mod, keystore
+    from ..protocols.nostr import peers as peers_mod
+    from ..planes.peering import budget as budget_mod, peering as peering_wire, reporter as reporter_mod
+    from ..planes.store import sync as sync_wire
+    from ..storage import accounts as accounts_mod
+    from ..planes.identity.discovery import compartment as discovery_wire
+from ..planes.identity.presence import compartment as presence_mod
+from ..planes.operations.scheduler import compartment as scheduler_mod
+
+
+MAX_PULL_TIMEOUT = 600          # an operator-driven pull holds a connection slot and a sync session this long at most
+
+
+VersionResult = TypedDict('VersionResult', {
+    'protocol': str,
+    'fleetmesh': str,
+    'digest': str,
+    'release': Mapping[str, Optional[str]],
+    'did': str,
+    'pubkey': str,
+    'class': str,
+    'commands': list[str],
+})
+
+
+class CommandDetail(CommandSpec, total=False):
+    name: str
+
+
+class RepublishResult(TypedDict):
+    descriptor: str
+    relays: Mapping[str, tuple[bool, str]]
+
+
+class EventsResult(BusState):
+    topics: list[str]
+    events: list[BusEnvelope]
+
+
+class StandingResult(TypedDict):
+    answer: str
+    body: Optional[Mapping[str, Any]]
+
+
+class ReportItem(TypedDict):
+    reporter: str
+    severity: Optional[str]
+    admissible: bool
+    reasons: list[str]
+    weight: float
+    id: str
+    created_at: int
+
+
+class ReportsResult(TypedDict):
+    view: str
+    reports: list[ReportItem]
+
+
+class PeerGrantSummary(TypedDict):
+    tier: Optional[str]
+    status: str
+
+
+class PeerPendingSummary(TypedDict):
+    tier: Optional[str]
+    from_epoch: int
+
+
+class PeerEvaluationSummary(TypedDict):
+    epoch: int
+    severity: Optional[str]
+    state: str
+
+
+class PeerViewRow(TypedDict):
+    peer: str
+    issued: Optional[PeerGrantSummary]
+    received: Optional[PeerGrantSummary]
+    pending: Optional[PeerPendingSummary]
+    last_evaluated: Optional[PeerEvaluationSummary]
+    standing: Optional[StandingTellBody]
+    zeroed_until: Optional[int]
+    pulls: list[str]
+    descriptor: Optional[str]
+    shared: list[str]
+    not_shared: list[str]
+    digest: Optional[str]
+    notices: list[str]
+
+
+class RefusalResult(TypedDict):
+    subsystem: str | None
+    at: int
+    kind: str
+    subject: str | None
+    why: str
+    detail: Mapping[str, Any] | str
+
+
+class SubsystemStateResult(TypedDict):
+    name: str
+    state: str
+
+
+class RetireSteps(TypedDict, total=False):
+    reason: str
+    at: int
+    did: list[list[Any]]
+    peers: list[str]
+    handed: int
+    withdrawn: int
+    revoked: bool
+
+
+class TerminateResult(TypedDict):
+    peer: str
+    reason: str
+    told: Mapping[str, Any]
+    pulls_removed: int
+
+
+def _arg_int(cmd: str, args: Mapping[str, Any], name: str, default: int) -> int:
+    v = args.get(name)
+    if v is None:
+        return default
+    if isinstance(v, bool) or not isinstance(v, (int, float, str)):
+        raise control_mod.ControlError('%s: %s must be an integer' % (cmd, name))
+    try:
+        out = int(v)
+    except (TypeError, ValueError):
+        raise control_mod.ControlError('%s: %s must be an integer, not %r' % (cmd, name, str(v)[:32]))
+    if out < 0:
+        raise control_mod.ControlError('%s: %s must not be negative' % (cmd, name))
+    return out
+
+
+def _arg_float(cmd: str, args: Mapping[str, Any], name: str, default: float) -> float:
+    v = args.get(name)
+    if v is None:
+        return default
+    if isinstance(v, bool) or not isinstance(v, (int, float, str)):
+        raise control_mod.ControlError('%s: %s must be a number' % (cmd, name))
+    try:
+        out = float(v)
+    except (TypeError, ValueError):
+        raise control_mod.ControlError('%s: %s must be a number, not %r' % (cmd, name, str(v)[:32]))
+    if out != out or out in (float('inf'), float('-inf')):
+        raise control_mod.ControlError('%s: %s must be finite' % (cmd, name))
+    return out
+
+
+def _arg_hex(cmd: str, args: Mapping[str, Any], name: str) -> str:
+    """A 64-hex pubkey, lower-cased. Everything downstream keys tables on it."""
+    v = args.get(name)
+    if not isinstance(v, str) or len(v) != 64:
+        raise control_mod.ControlError('%s: %s must be a 64-hex pubkey' % (cmd, name))
+    try:
+        bytes.fromhex(v)
+    except ValueError:
+        raise control_mod.ControlError('%s: %s must be a 64-hex pubkey' % (cmd, name))
+    return v.lower()
+
+
+def _topics_arg(raw: Any) -> set[str] | None:
+    if raw is None or raw == []:
+        return None
+    if isinstance(raw, str):
+        raw = [t for t in raw.split(',') if t]
+    if not isinstance(raw, list) or not all(isinstance(t, str) for t in raw):
+        raise control_mod.ControlError('topics is a list of topic names; `events` lists them')
+    return set(raw)
+
+
+class ControlMixin(object):
+    # What the mixin reads off the node it is mixed into. Declarations only,
+    # for the checker; NodeApp.__init__ and start() assign every one of them.
+    if TYPE_CHECKING:
+        dir: str
+        cfg: MutableMapping[str, Any]
+        clock: Callable[[], int]
+        relays: list[str]
+        ks: keystore.Keystore
+        grants: grants_mod.GrantStore
+        accounts: accounts_mod.AccountStore
+        peers: peers_mod.Peers
+        transport: transport_mod.TransportRouter
+        ledger: standing.Ledger
+        timeout: float
+        _stop: threading.Event
+        _built: bool
+        subsystems: compartment_mod.Registry
+        events: channels_mod.NodeEventBus
+        peering: peering_wire.Peering
+        budget: budget_mod.Budget
+        sync: sync_wire.SyncPeer
+        reporter: reporter_mod.Reporter
+        discovery: discovery_wire.Discovery
+        presence: presence_mod.Presence
+        scheduler: scheduler_mod.Scheduler
+
+        def _descriptor(self) -> NostrEvent: ...
+        def tick(self, now: int | None = None) -> list[tuple[Any, ...]]: ...
+        def status(self) -> Mapping[str, Any]: ...
+        def health(self) -> Mapping[str, Any]: ...
+
+    def control_request(self, cmd: str, args: Mapping[str, Any],
+                        actor: Any = None) -> Any:
+        """Answer one control request, recording who asked.
+
+        `actor` is built at the socket boundary (node/control.py:actor_of),
+        because SO_PEERCRED can only be read off a live connection and by the
+        time a command runs the socket is gone. It is held in a ContextVar
+        (node/config/change.py:ACTING) for the length of this request, so a
+        config change raised during the command is attributed to the person
+        who caused it - and only to them. An attribute on the node was shared
+        by every connection thread, so two concurrent requests could swap
+        authors.
+
+        Nothing here checks an ability. `Command.permission` and
+        `Parameter.requires` are declared and unenforced on purpose: this
+        socket is chmod 0o600, so everyone who can reach it is already the
+        owner, and a check against that is a control which protects nothing
+        while reading as though it does. Enforcement belongs with a principal
+        that is not already the owner - a UCAN delegation over the wire, or a
+        socket opened to several unix users - and the markers come off then.
+        """
+        from ..config import change as change_mod  # noqa: PLC0415
+        with change_mod.acting_as(actor):
+            try:
+                return self._answer_request(cmd, args)
+            except CommandError as e:
+                # The caller's mistake, checked against the declaration: a
+                # refusal they read, kept out of the ring that counts bugs.
+                raise control_mod.ControlError(str(e))
+
+    @property
+    def acting(self) -> Any:
+        """The actor of the request running on this thread, or None."""
+        from ..config import change as change_mod  # noqa: PLC0415
+        return change_mod.acting()
+
+    def _answer_request(self, cmd: str, args: Mapping[str, Any]) -> Any:
+        """One request over the control socket, dispatched on CONTROL. Reads
+        answer from the daemon's live state; actions are the things only the
+        daemon can do. The config file is the way to change what the node is
+        told to do."""
+        table = self.commands()
+        if cmd not in table:
+            raise control_mod.ControlError('unknown command %r; `commands` lists the %d this socket answers'
+                                           % (str(cmd)[:32], len(table)))
+        missing = [k for k, v in table[cmd]['args'].items() if v == 'required' and k not in args]
+        if missing:
+            raise control_mod.ControlError('%s needs %s' % (cmd, ', '.join(missing)))
+        cmd_obj = NODE_COMMANDS_BY_KEY.get(cmd)
+        if cmd_obj is not None:
+            return cmd_obj.execute(self, args)
+        if self._built and cmd in self.subsystems.commands():
+            return self.subsystems.dispatch(cmd, dict(args))
+        raise control_mod.ControlError('%s is in the table and not in the dispatcher' % cmd)
+
+    # ---- node command handlers -----------------------------------------------------
+    def cmd_version(self) -> VersionResult:
+        return {'protocol': control_mod.PROTOCOL, 'fleetmesh': descriptor.VERSION, 'digest': descriptor.DIGEST,
+                'release': release_mod.running().as_dict(),
+                'did': self.ks.did, 'pubkey': self.ks.node_pk, 'class': self.cfg['class'],
+                'commands': list(self.commands())}
+
+    def cmd_commands(self) -> list[CommandDetail]:
+        return [dict(name=name, **spec) for name, spec in self.commands().items()]
+
+    def cmd_subsystems(self) -> Mapping[str, Mapping[str, Any]]:
+        return self.subsystems.report()
+
+    def cmd_lifecycle(self) -> Mapping[str, compartment_lifecycle.LifecycleRecord]:
+        return self.subsystems.lifecycle()
+
+    def cmd_tick(self) -> list[list[Any]]:
+        return [list(d) for d in self.tick()]
+
+    def cmd_republish(self) -> RepublishResult:
+        desc = self._descriptor()
+        return {'descriptor': desc['id'],
+                'relays': relay.publish_all(self.relays, desc, self.timeout) if self.relays else {}}
+
+    def cmd_grant(self, args: Mapping[str, Any]) -> GrantView:
+        return grant_view(self.grants, _arg_hex('grant', args, 'peer'))
+
+    def cmd_windows(self, args: Mapping[str, Any]) -> list[WindowView]:
+        return windows_view(self.accounts, _arg_hex('windows', args, 'peer'), _arg_int('windows', args, 'last', 0))
+
+    def cmd_refusals(self, args: Mapping[str, Any]) -> list[RefusalResult]:
+        return [{'subsystem': n, 'at': r.at, 'kind': r.kind,
+                 'subject': (r.subject or '')[:16] or None, 'why': r.why, 'detail': r.detail}
+                for n, r in self.subsystems.refusals(_arg_int('refusals', args, 'last', 5))]
+
+    def cmd_resume(self, args: Mapping[str, Any]) -> SubsystemStateResult:
+        name = str(args.get('name') or '')
+        actor = self.acting
+        who = getattr(actor, 'operator', '') or 'the operator'
+        try:
+            state = self.subsystems.resume(name, why='resumed by %s' % who)
+        except KeyError as e:
+            raise control_mod.ControlError(str(e.args[0] if e.args else e))
+        return {'name': name, 'state': state}
+
+    def cmd_restart(self, args: Mapping[str, Any]) -> SubsystemStateResult:
+        name = str(args.get('name') or '')
+        who = getattr(self.acting, 'operator', '') or 'the operator'
+        try:
+            state = self.subsystems.restart(name, why='by %s' % who)
+        except (KeyError, ValueError) as e:
+            raise control_mod.ControlError(str(e.args[0] if e.args else e))
+        return {'name': name, 'state': state}
+
+    def cmd_events(self, args: Mapping[str, Any]) -> EventsResult:
+        topics = _topics_arg(args.get('topics'))
+        tap = self.events.tap
+        assert tap is not None
+        evs = tap.since(_arg_int('events', args, 'since', 0), topics, _arg_int('events', args, 'last', 0))
+        st = tap.state()
+        return {
+            'seq': st['seq'],
+            'ring': st['ring'],
+            'ring_max': st['ring_max'],
+            'subscribers': st['subscribers'],
+            'oldest': st['oldest'],
+            'topics': sorted(channels_mod.WIRE),
+            'events': evs,
+        }
+
+    def cmd_subscribe(self, args: Mapping[str, Any]) -> control_mod.Stream:
+        topics = _topics_arg(args.get('topics'))
+        tap = self.events.tap
+        assert tap is not None
+        sub = tap.subscribe(topics)
+        backlog = collections.deque(tap.since(_arg_int('subscribe', args, 'since', 0), topics)) if args.get('since') is not None else collections.deque()
+
+        def pull(timeout: float) -> Optional[BusEnvelope]:
+            if backlog:
+                return backlog.popleft()
+            return sub.next(timeout)
+        return control_mod.Stream({'seq': tap.seq, 'topics': sorted(topics) if topics else None,
+                                   'replaying': len(backlog)}, pull, lambda: tap.unsubscribe(sub))
+
+    def cmd_pull(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        peer, shard, filt = _arg_hex('pull', args, 'peer'), args.get('shard'), args.get('filter')
+        if not isinstance(shard, str) or not isinstance(filt, dict):
+            raise control_mod.ControlError('pull takes shard as a string and filter as an object')
+        timeout = _arg_float('pull', args, 'timeout', 60.0)
+        if not 0 < timeout <= MAX_PULL_TIMEOUT:
+            raise control_mod.ControlError('pull timeout must be in (0, %d] seconds' % MAX_PULL_TIMEOUT)
+        why = self.budget.throttled(peer)
+        if why is not None and not args.get('force'):
+            raise control_mod.ControlError('the grant does not cover a session now: %s (--force pulls anyway, and the window prices it)' % why)
+        return self.pull(peer, shard, filt, timeout=timeout)
+
+    def cmd_terminate(self, args: Mapping[str, Any]) -> TerminateResult:
+        return self.terminate(_arg_hex('terminate', args, 'peer'), str(args.get('reason') or 'operator')[:200])
+
+    def cmd_standing(self, args: Mapping[str, Any]) -> StandingResult:
+        kind, body = self.reporter.ask_standing(_arg_hex('standing', args, 'peer'), _arg_hex('standing', args, 'target'))
+        if kind is None:
+            raise control_mod.ControlError('no answer from the peer')
+        return {'answer': kind, 'body': body}
+
+    def cmd_reports(self, args: Mapping[str, Any]) -> ReportsResult:
+        target = _arg_hex('reports', args, 'target')
+        view, weighed = self.reporter.view(target)
+        found = self.reporter.reports_about(target)
+        return {'view': view, 'reports': [{'reporter': r['reporter'], 'severity': r['severity'],
+                                            'admissible': r['admissible'], 'reasons': r['reasons'],
+                                            'weight': self.reporter.weight_of(r['reporter']),
+                                            'id': r['event']['id'], 'created_at': r['event']['created_at']}
+                                           for r in found]}
+
+    def cmd_retire(self, args: Mapping[str, Any]) -> RetireSteps:
+        out = self.retire(str(args.get('reason') or 'operator')[:200], bool(args.get('revoke')),
+                          _arg_int('retire', args, 'lapses_in', 86400))
+        self._stop.set()          # the tick loop ends; `run` calls stop, which says farewell
+        return out
+
+    def commands(self) -> collections.OrderedDict[str, CommandSpec]:
+        """Every command this socket answers: the node's own, and one per
+        command each compartment declares.
+
+        The compartments' were unreachable. `control_request` refused anything
+        not in CONTROL before it ever looked at the registry, so the branch that
+        dispatched `peering.show` could not be reached and no subsystem command
+        had ever been answered. A dispatch table that documents itself has to be
+        the same table the guard reads.
+        """
+        built = getattr(self, '_built', False)
+        sub_key = tuple(s.name for s in self.subsystems) if built else ()
+        cached = getattr(self, '_commands_cache', None)
+        if cached is not None and cached[0] == built and cached[1] == sub_key:
+            return collections.OrderedDict(cached[2])
+        table = collections.OrderedDict(CONTROL)
+        if built:
+            for name, spec in self.subsystems.commands().items():
+                table[name] = CommandSpec(args=spec.get('args', {}), does=spec.get('does', ''),
+                                          reply=spec.get('reply', ''))
+        self._commands_cache = (built, sub_key, table)
+        return collections.OrderedDict(table)
+
+    def retire(self, reason: str = 'operator', revoke: bool = False,
+               lapses_in: int = 86400) -> RetireSteps:
+        """Leave the mesh in order, rather than by going quiet.
+
+        `farewell` closed one of the four ways a node's departure cost its
+        peers something: the accounting. Everything under the accounting was
+        still left behind. The coverage claims kept pointing at a node that was
+        gone, so every reader that believed one pulled and timed out; the
+        shards this node held first-hand lost their authority, because nobody
+        else may assert what it only replicated; and each of those peers
+        recorded strain against a node that had done nothing but stop.
+
+        Four steps, in this order, and the order is the whole of it:
+
+          announce  a heartbeat saying this is a departure, so the silence
+                    that follows is not priced as stress by anyone listening.
+          close     every asserted shard gets a range ending now. A handover
+                    signs for a closed set, so an open range cannot be passed
+                    on, and the shards worth passing on are exactly the ones
+                    nobody ever bounded.
+          hand over the statement goes to every peer holding a live grant,
+                    stored. The peer keeps it only if it fingerprints to what
+                    the peer holds, so being wrong about who has the data
+                    costs nothing.
+          withdraw  every claim is republished best-effort with an expiration.
+                    After the handovers, never before: a withdrawal takes back
+                    the very claim a handover copies its terms from.
+          farewell  what `stop` already does, and it goes last because a
+                    receipt is the last thing this node has to say.
+
+        This is a retirement and not a restart. A restart MUST NOT run it: the
+        claims would come back on the next tick with their ranges closed and
+        their authority given away, which is a fleet upgrade paying the price
+        this exists to avoid. `meshnode retire` is a separate command for that
+        reason, and `run` never calls it.
+
+        Reversible up to the last step. A node that retires and is started
+        again publishes its claims afresh; what it does not get back is the
+        `until` it closed, which is a line in the config, and the handovers it
+        signed, which are permanent by design. `revoke` is the one step that
+        is not reversible at all, so it is off unless asked for.
+
+        Nothing here may raise. A node that cannot retire cleanly must still
+        stop.
+        """
+        now = self.clock()
+        did: list[tuple[Any, ...]] = []
+        steps: RetireSteps = {'reason': reason, 'at': now}
+        try:
+            # First, and before anything is given away: say this is a
+            # departure. Under FLP nothing else distinguishes a node that went
+            # from one that went quiet, so a peer holding a schedule against
+            # this one would otherwise record a partition it was about to be
+            # told about.
+            did += self.presence.announce_retiring(now)
+        except Exception as e:
+            did.append(('announcement failed', '%s: %s' % (type(e).__name__, e)))
+        try:
+            did += self.discovery.close_ranges(now)
+        except Exception as e:
+            did.append(('close failed', '%s: %s' % (type(e).__name__, e)))
+        peers_held = [p for p in _live_peers(self.grants)
+                      if (row := self.grants.get(p, grants_mod.ISSUED)) and row.get('status') == 'live']
+        try:
+            did += self.sync.hand_over_all(peers_held, now)
+        except Exception as e:
+            did.append(('handover failed', '%s: %s' % (type(e).__name__, e)))
+        try:
+            did += self.discovery.withdraw_coverage(now, lapses_in=lapses_in)
+        except Exception as e:
+            did.append(('withdrawal failed', '%s: %s' % (type(e).__name__, e)))
+        if revoke:
+            try:
+                ev = lifecycle.revocation(self.ks.node_pk, reason, now)
+                signed = store_mod.make_signed_event(self.ks.node_sk, now, ev['kind'], ev['tags'], ev['content'])
+                relay.publish_all(self.relays, signed, self.timeout)
+                did.append(('revoked', signed['id'], reason))
+            except Exception as e:
+                did.append(('revocation failed', '%s: %s' % (type(e).__name__, e)))
+        for d in did:
+            _line('  ' + ' '.join(_short(str(x)) for x in d))
+        steps['did'] = [list(d) for d in did]
+        steps['peers'] = peers_held
+        steps['handed'] = sum(1 for d in did if d[0] == 'handed over')
+        steps['withdrawn'] = sum(1 for d in did if d[0] == 'coverage withdrawn')
+        steps['revoked'] = bool(revoke and any(d[0] == 'revoked' for d in did))
+        return steps
+
+    def save_coverage(self) -> None:
+        """Write the config back after a compartment changed what this node
+        claims. One place, because a running node owns its directory and the
+        file is what the next tick reads. Compartments reach it as
+        `ctx.persist_cfg`; the node reaches it directly."""
+        save_config(self.dir, {k: v for k, v in self.cfg.items() if not k.startswith('_')})
+
+    def terminate(self, peer_pk: str, reason: str = 'operator') -> TerminateResult:
+        """End a peering: zero both grants here, tell the peer, and stop
+        pulling from it. The trust decision, if any, is left where it is."""
+        rows = [self.grants.get(peer_pk, d) for d in (grants_mod.ISSUED, grants_mod.RECEIVED)]
+        if not any(r is not None and r['status'] == 'live' for r in rows):
+            raise control_mod.ControlError('no live peering with %s' % peer_pk[:16])
+        msg = self.peering.host.terminate(peer_pk, reason=reason)
+        self.grants.zero(peer_pk, self.clock())
+        sent: Mapping[str, Any] = {}
+        try:
+            sent = self.transport.send(msg, peer_pk, stored=True)
+        except transport_mod.TransportError as e:
+            sent = {'error': str(e)}
+        before = len(self.cfg.get('peers', []))
+        self.cfg['peers'] = [p for p in self.cfg.get('peers', []) if p.get('pubkey') != peer_pk]
+        if len(self.cfg['peers']) != before:
+            self.save_coverage()
+        _line('  terminated the peering with', _short(peer_pk), '-', reason)
+        return {'peer': peer_pk, 'reason': reason, 'told': sent, 'pulls_removed': before - len(self.cfg['peers'])}
+
+    def peer_view(self) -> list[PeerViewRow]:
+        """Every peer this node holds a grant with, as an operator reads it."""
+        out: list[PeerViewRow] = []
+        ours = set(identity.PROTOCOLS)
+        for pk in sorted({g['peer'] for g in self.grants.list()}):
+            desc = self.peers.descriptor(pk)
+            theirs = identity.protocols_of(desc) if desc else set()
+            shared = identity.shared_protocols(theirs, ours) if desc else set()
+            issued = self.grants.get(pk, grants_mod.ISSUED)
+            received = self.grants.get(pk, grants_mod.RECEIVED)
+            pend = self.grants.pending(pk)
+            evals = [r for r in self.budget.evaluations if r.peer == pk]
+            out.append({'peer': pk,
+                        'issued': {'tier': issued['payload'].get('tier'), 'status': issued['status']} if issued else None,
+                        'received': {'tier': received['payload'].get('tier'), 'status': received['status']} if received else None,
+                        'pending': {'tier': pend['payload'].get('tier'), 'from_epoch': pend['decided_epoch'] + 1} if pend else None,
+                        'last_evaluated': ({'epoch': evals[-1].epoch, 'severity': evals[-1].severity,
+                                            'state': evals[-1].state} if evals else None),
+                        'standing': self.ledger.tell(pk),
+                        'zeroed_until': self.budget.zero_until.get(pk),
+                        'pulls': [p['shard'] for p in self.cfg.get('peers', []) if p.get('pubkey') == pk],
+                        'descriptor': desc.get('id') if desc else None,
+                        # What the two nodes can run with each other, and the
+                        # schema the peer declared when it differs from ours.
+                        'shared': sorted(p[len(identity.FLEETMESH):] for p in shared),
+                        'not_shared': sorted(p[len(identity.FLEETMESH):] for p in theirs - shared) if desc else [],
+                        'digest': (self.peering.host.digest_mismatch.get(pk) or '')[:16] or None,
+                        'notices': identity.notices(desc, digest=descriptor.DIGEST) if desc else []})
+        return out
+
+    # ---- actions -------------------------------------------------------------------
+    # A shard filter is a NIP-01 filter and routinely carries tag keys ('#t');
+    # node.interfaces.NostrFilter names no tag keys, so the plain mapping is
+    # the accurate type until that TypedDict grows them.
+    def propose(self, peer_pk: str, shard: str, filt: Mapping[str, Any], mode: str = 'both', timeout: float = 30.0) -> tuple[str, Mapping[str, Any]]:
+        want = [{'shard': shard, 'filter': dict(filt), 'mode': mode}]
+        return self.peering.propose(peer_pk, want, timeout=timeout)
+
+    def pull(self, peer_pk: str, shard: str, filt: Mapping[str, Any], timeout: float = 30.0) -> Mapping[str, Any]:
+        return self.sync.pull(peer_pk, shard, dict(filt), timeout=timeout)
+
+    def regrant(self, peer_pk: str, tier: str, now: int | None = None) -> Optional[GrantPayload]:
+        """Re-issue a live grant at a tier the operator has just decided on.
+
+        A tier is only ever raised by a person, so the decision has to reach an
+        existing peering as well as the next one. This writes a new grant at the
+        new tier, publishes it as a fresh kind 30801 under the same blinded
+        identifier, and tells the subject with peering/1.0/amend - the same path
+        a window evaluation uses, because it is the same kind of change.
+        """
+        now = now if now is not None else self.clock()
+        row = self.grants.get(peer_pk, grants_mod.ISSUED)
+        if row is None:
+            return None
+        # A person deciding is the one thing allowed to skip the earning. The
+        # specification says an operator MAY seed a tier for a node it knows out
+        # of band, recorded as a signed event and reversible, so a regrant opens
+        # at the ceiling rather than at the opening fraction a stranger gets.
+        held = row['payload']
+        payload = cast(GrantPayload, dict(held, tier=tier,
+                       limits={k: v for k, v in window.ceilings(tier).items() if k != 'dup_ratio'}))
+        # And it lands at the boundary, like every other decision. Seeding a
+        # tier mid-window published a new envelope while the subject was still
+        # sending receipts against the old one; every one of those was refused
+        # as naming a grant that did not govern that window, the window closed
+        # on a claim one receipt short of what was measured, and the divergence
+        # priced an honest peer S2. Seen on the mesh the first time a seed was
+        # re-applied after the ladder had overridden it.
+        decided = accounting.epoch(now, held.get('window') or 3600)
+        out = self.peering.decide(peer_pk, payload, 'operator set the tier to %s' % tier,
+                                  None, decided)
+        _line('  granted', _short(peer_pk), 'tier', tier,
+              '- in force from window', out['effective_from'])
+        return payload
+
+    # ---- the node's own ceiling ----------------------------------------------------
+    def _amend(self, peer_pk: str, payload: Mapping[str, Any], reason: str, cause: str, now: int) -> tuple[NostrEvent, GrantPayload]:
+        """Write and publish a grant, and tell the subject what changed it.
+
+        The one place a grant leaves this node outside a window evaluation.
+        `cause` is what separates a remedy from a shed from a person, and a
+        subject that could not tell them apart would price its issuer for
+        owning a small machine.
+        """
+        # The one path that still lands inside the running window, and it is a
+        # deliberate exception rather than the leftover the other two were. A
+        # shed is the node saying it is over its own ceiling now; deferring the
+        # lower limits to the next boundary would leave it carrying load it has
+        # already decided it cannot carry, for up to an hour. The cost is the
+        # one the other paths were changed to avoid - the subject's receipts for
+        # the rest of this window name the grant it still holds, and the window
+        # closes divergent - so a shed is worth an S2 against a peer that did
+        # nothing wrong only because the alternative is the node falling over.
+        # If that trade ever stops being worth it, this is the line to change.
+        out = self.peering.issue(peer_pk, payload, cause, reason,
+                                 effective_epoch=accounting.epoch(now, payload.get('window') or 3600),
+                                 now=now)
+        return out['envelope'], out['payload']
+
+    # ---- what the compartments do, reached from the node ---------------------------
+    # Each of these is the compartment's, and each is kept here because a caller
+    # outside the node - a test, the control socket - asks the node for it. They
+    # forward and do nothing else; the state and the refusals live in the
+    # compartment, which is the point.
+    def on_heartbeat(self, hb: NostrEvent) -> list[tuple[Any, ...]]:
+        return self.presence.on_heartbeat(hb)
+
+    def publish_discovery(self, now: int | None = None) -> list[tuple[str, ...]]:
+        return self.discovery.publish_discovery(now)
+
+    def publish_coverage(self, now: int | None = None) -> list[tuple[str, ...]]:
+        return self.discovery.publish_coverage(now)
+
+    def forward_clock(self, key: str, now: int) -> int:
+        return self.discovery.forward_clock(key, now)