fleetmesh-node 0.2.0__py3-none-any.whl

node/metrics/face.py

@@ -0,0 +1,110 @@
+"""The relay face's metrics, as declarations.
+
+`relayserver.render_metrics` built these eight by hand, with the names, HELP
+and TYPE typed inline and every reading wrapped in `hasattr` plus a bare
+`except: pass`. They were the only metrics the node exposed.
+
+Declaring them changes nothing an operator scrapes, and that is the point.
+Every exposed name and every TYPE is reproduced exactly, because a metric
+name is an interface: a dashboard, an alert rule and a recording rule are all
+written against it, and renaming one to suit a convention breaks them
+silently. Two of these are not what their names suggest - `fleetmesh_blobs_total`
+is a gauge despite the counter suffix, and `fleetmesh_events_stored_total`
+counts what is in the store now and can go down - and both are kept as they
+are rather than corrected. The place to fix an exposition name is a release
+note, not a refactor.
+
+What does change: the readings come through `Monitors`, so a sampler that
+raises is counted rather than swallowed by `except: pass`, and the face's
+numbers sit in the same census as every compartment's.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping
+
+from . import COUNTER, GAUGE, Metric
+
+
+def _try(fn: Callable[[], Any], default: Any = 0) -> Any:
+    """A reading, or the default.
+
+    The old code caught everything and moved on, which is why a store that
+    could not be counted reported zero and nobody knew. `Monitors.read`
+    counts a sampler that raises, so a sampler here lets a real error through
+    and only guards the shape - an object that does not implement `count` at
+    all, which is a configuration and not a fault.
+    """
+    try:
+        return fn()
+    except (AttributeError, TypeError):
+        return default
+
+
+def face_metrics(face: Any) -> tuple[Metric, ...]:
+    """The eight the relay face has always exposed, bound to this server.
+
+    `face` is the RelayServer. The samplers close over it rather than being
+    handed values, so each scrape reads the live number.
+    """
+    def stored() -> int:
+        return int(_try(lambda: face.store.count()))
+
+    def conns() -> int:
+        with face._lock:
+            return len(face._conns)
+
+    def subs() -> int:
+        with face._lock:
+            return sum(len(s) for s in face._subs.values())
+
+    def blob_count() -> int:
+        if face.blob_store is None:
+            return 0
+        return int(_try(lambda: face.blob_store.count()))
+
+    def blob_bytes() -> int:
+        if face.blob_store is None:
+            return 0
+        return int(_try(lambda: face.blob_store.total_bytes(), 0) or 0)
+
+    def by_tier() -> Mapping[str, int]:
+        """Peers per trust tier, which is the one labelled metric here."""
+        out: dict[str, int] = {}
+        if face.grants is None:
+            return out
+        for g in _try(lambda: list(face.grants.list()), []):
+            payload = g.get('payload')
+            t = payload.get('tier') if isinstance(payload, dict) else g.get('tier', 'unknown')
+            out[str(t)] = out.get(str(t), 0) + 1
+        return out
+
+    return (
+        # Named `_total` and typed counter since it was written, though it
+        # counts what is in the store now and can fall. Kept as it is: the
+        # name is what alerts are written against.
+        Metric(name='events_stored', description='Total events stored in local store.',
+               kind=COUNTER, sample=stored, tags=('face', 'store')),
+        Metric(name='active_connections', description='Current active WebSocket connections.',
+               kind=GAUGE, sample=conns, tags=('face', 'connections')),
+        Metric(name='active_subscriptions', description='Current active event subscriptions.',
+               kind=GAUGE, sample=subs, tags=('face', 'subscriptions')),
+        Metric(name='events_accepted', description='Total valid events accepted through relay face.',
+               kind=COUNTER, sample=lambda: int(getattr(face, 'accepted', 0)),
+               tags=('face', 'events')),
+        Metric(name='events_refused_future',
+               description='Total events refused due to future timestamps.',
+               kind=COUNTER, sample=lambda: int(getattr(face, 'refused_future', 0)),
+               tags=('face', 'events', 'refusals')),
+        # A gauge wearing a counter's suffix, preserved deliberately.
+        Metric(name='blobs_total', description='Total content-addressed blobs in Blossom CAS.',
+               kind=GAUGE, sample=blob_count, tags=('face', 'blobs')),
+        Metric(name='blobs_bytes_total',
+               description='Total size in bytes of blobs in Blossom CAS.',
+               kind=GAUGE, sample=blob_bytes, tags=('face', 'blobs')),
+        Metric(name='peers_by_tier',
+               description='Number of peers categorized by trust tier.',
+               kind=GAUGE, labels=('tier',), sample=by_tier, tags=('face', 'peering')),
+    )
+
+
+__all__ = ['face_metrics']

node/planes/__init__.py

@@ -0,0 +1,21 @@
+"""Architectural planes of the Fleetmesh node.
+
+As defined in fleetmesh.org/docs/implementing.md and enforced mechanically
+by check-implementing.py:
+  1. identity   (discovery, announce, presence, linked)
+  2. store      (sync, retention, blob_wire, blob_replication)
+  3. peering    (trust, strain, peering, budget, capacity, reporter)
+  4. transport  (link, lan, p2p, mediation, bridge)
+  5. services   (gossip, compute, compute_wire, settle, paidfetch, sidecars, dvm, nsite)
+  6. operations (scheduler, updates)
+"""
+from . import identity, store, peering, transport, services, operations
+
+__all__ = [
+    'identity',
+    'store',
+    'peering',
+    'transport',
+    'services',
+    'operations',
+]

node/planes/identity/__init__.py

@@ -0,0 +1,20 @@
+"""Identity plane: discovery, announce, presence, linked."""
+from . import announce, discovery, linked, presence
+from .announce.compartment import Announce
+from .discovery.compartment import Discovery, DiscoveryConfig
+from .linked.compartment import LinkedConfig, LinkedFace
+from .presence.compartment import Presence, PresenceConfig
+
+__all__ = [
+    'Announce',
+    'Discovery',
+    'DiscoveryConfig',
+    'LinkedConfig',
+    'LinkedFace',
+    'Presence',
+    'PresenceConfig',
+    'announce',
+    'discovery',
+    'linked',
+    'presence',
+]

node/planes/identity/announce/__init__.py

@@ -0,0 +1,9 @@
+"""The gossipsub announce topic, reached through a sidecar, as a compartment.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Announce
+from .types import AnnounceStateReport, AnnounceTotals
+
+__all__ = ['Announce', 'AnnounceStateReport', 'AnnounceTotals']
+

node/planes/identity/announce/compartment.py

@@ -0,0 +1,447 @@
+"""The gossipsub announce topic, reached through a sidecar, as a compartment.
+
+Bridge 2 in the specification: a node republishes its descriptor on
+`/fleetmesh/announce/1` so that nodes which have never shared a relay with it
+hear about it anyway. The relay path (bridge 1, `discovery_wire.py`) always
+works; this one reaches further.
+
+It is a sidecar and not a library because of what a library would cost. `fleetmesh_core/`
+is standard library only and `node/` depends on `cryptography` and nothing
+else - `ws.py` is a hand-rolled RFC 6455 for exactly that reason. Installing
+the one maintained Python libp2p pulls in sixty-three packages, eight of them
+compiled; it does not install on Python 3.14 at all; and it is trio where this
+node is threads. A second implementer reading the specification should not
+inherit that, so the libp2p stack lives in its own process with its own
+dependencies and this file speaks to it over a unix socket in the node's
+directory, one JSON object per line, the same shape `control.py` already uses.
+
+The node never starts the sidecar and never needs it. No socket is not an
+error, it is a node with one discovery bridge instead of two, and it is said
+once rather than once a tick.
+
+**Nothing here trusts the sidecar.** Every row it hands over goes through
+`admit` - the same function the sidecar ran before gossipsub propagated
+anything - and then through `peers.learn`, exactly as a descriptor fetched
+from a relay does. The work floor is re-applied here because it is this
+node's policy and not the sidecar's.
+
+The one check `admit` needs from the sidecar is which libp2p peer originated
+the message, because a Multikey is compared against it. A sidecar that lies
+about the originator can only make this node reject a descriptor it would
+have accepted; it cannot make it accept one, because the Multikey is inside
+an event the node key signed.
+
+The pilot bridge (node/sidecar_bridge): the link to the sidecar, saying it
+once each way, the version gate, the `announce.sidecar` and `announce.probe`
+commands and the restart all come from `Bridge`, as they will for every other
+sidecar. What is left here is what is announce's own - the topic, `admit`,
+what a drain may teach this node.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from typing import Any, Callable, Optional, cast
+
+from node import channels as ch_mod
+from node.protocols.nostr import descriptor as descriptor_mod
+from node.compartment import lifecycle as lifecycle_mod
+from node import metrics as mx_mod
+from node.compartment import stores as st
+from node.config import AnnounceConfig
+from fleetmesh_core.crypto import keys
+from fleetmesh_core.identity import identity
+from fleetmesh_core.wire.interfaces import NostrEvent
+from node.compartment import Command, Need
+from node.compartment.sidecar import UP, Bridge, Sidecar, SidecarError, jsonline_call
+
+SOCK: str = 'announce.sock'
+PROTOCOL: str = 'fleetmesh-announce/1'
+
+
+from .types import AnnounceStateReport
+TOPIC: str = '/fleetmesh/announce/1'
+MAX_LINE: int = 1 << 20
+# What one drain may bring back. A topic is a flood channel with no grant in
+# front of it, so the bound is here rather than in the sender's good manners.
+DRAIN_MAX: int = 64
+KIND: int = 11801
+# What one descriptor may weigh on the topic. A kind 11801 carrying every tag
+# the specification allows is a couple of kilobytes; ten times that is a
+# payload nobody needs and everybody would carry.
+PAYLOAD_MAX: int = 20000
+# The proof-of-work floor this node requires of a descriptor heard on the
+# topic. Local policy, not a protocol constant: two nodes with different
+# floors interoperate, the stricter one simply propagates less. Zero means
+# the descriptor's own declared target is the only bar, which is what a node
+# on a private mesh wants.
+POW_BITS: int = 0
+
+
+def socket_path(directory: str, configured: Optional[str] = None) -> str:
+    """Where the sidecar listens. Same derivation as the control socket, for
+    the same reason: macOS caps a unix socket path near a hundred bytes and a
+    test's temporary directory is longer than that."""
+    if configured:
+        return os.path.abspath(os.path.expanduser(configured))
+    real = os.path.realpath(directory)
+    p = os.path.join(real, SOCK)
+    if len(p.encode()) < 100:
+        return p
+    return os.path.join(tempfile.gettempdir(),
+                        'fleetmesh-announce-%s.sock' % hashlib.sha256(real.encode()).hexdigest()[:16])
+
+
+def transport_multikey(desc: NostrEvent) -> Optional[str]:
+    """The `key transport` Multikey a descriptor declares, or None."""
+    for t in desc.get('tags', []):
+        if t and t[0] == 'key' and len(t) > 2 and t[1] == 'transport':
+            return t[2]
+    return None
+
+
+def binds(desc: NostrEvent, ed25519_hex: str) -> bool:
+    """Whether the descriptor names this Ed25519 key as its transport key.
+
+    The gossipsub message was signed under StrictSign by the *originator*, and
+    a forwarder does not re-sign, so this is the originator's key and the
+    descriptor must be the originator's own. A descriptor relayed by a third
+    node is still valid on a flood topic - the check is against what the
+    descriptor claims, never against who handed it over.
+    """
+    mk = transport_multikey(desc)
+    if not mk or not ed25519_hex:
+        return False
+    try:
+        kind, raw = keys.parse_multikey(mk)
+    except ValueError:
+        return False
+    return kind == 'transport' and raw.hex() == ed25519_hex.lower()
+
+
+def admit(
+    payload: Any,
+    origin: Optional[str],
+    now: int,
+    pow_bits: int = 0,
+    payload_max: int = PAYLOAD_MAX,
+) -> tuple[Optional[NostrEvent], Optional[str]]:
+    """Whether the topic should carry this. (descriptor, None) or (None, why).
+
+    The whole of the defence on a flood channel with no grant in front of it,
+    and the one place it is written. The sidecar calls this before gossipsub
+    propagates anything, and the node calls it again on what the sidecar hands
+    over, because a separate process is not a reason to believe a descriptor.
+
+    Ordered cheapest first: a size that needs no parse, a parse, a kind, a
+    signature, the descriptor rules, the work, and last the binding, which is
+    the only check that needs to know who sent it.
+
+    `origin` is the *originator's* Ed25519 key - gossipsub StrictSign's
+    `from`, not the peer who handed the message over. A forwarder does not
+    re-sign, and a descriptor relayed by a third node is still valid here.
+    """
+    if isinstance(payload, (bytes, bytearray)):
+        if len(payload) > payload_max:
+            return None, 'payload over %d bytes' % payload_max
+        try:
+            desc = json.loads(bytes(payload).decode('utf-8'))
+        except (ValueError, UnicodeDecodeError):
+            return None, 'payload is not JSON'
+    else:
+        desc = payload
+    if not isinstance(desc, dict):
+        return None, 'not an event'
+    if desc.get('kind') != KIND:
+        return None, 'not a kind %d' % KIND
+    if not descriptor_mod.genuine(desc):
+        return None, 'signature does not verify'
+    problems = identity.validate_descriptor(desc, now=now, digest=descriptor_mod.DIGEST)
+    if problems:
+        return None, 'descriptor: %s' % str(problems[0])[:48]
+    if pow_bits and identity.pow_bits(str(desc.get('id') or '')) < pow_bits:
+        return None, 'below %d bits of work' % pow_bits
+    desc_ev = cast(NostrEvent, desc)
+    if not binds(desc_ev, origin or ''):
+        return None, 'transport key does not bind'
+    return desc_ev, None
+
+
+def call(path: str, cmd: str, timeout: float = 5.0, **args: Any) -> Any:
+    """One request, one reply, one connection. Raises SidecarError for all of
+    no sidecar, a sidecar that will not answer, and a sidecar that says no.
+
+    For a caller outside a node (a script, the sidecar's own tests). Inside
+    one, the sidecar is reached through the bridge - `Announce.call` - which
+    also moves the link and checks the protocol the sidecar answered in.
+    """
+    return jsonline_call(path, cmd, timeout=timeout, **args)[0]
+
+
+from .types import AnnounceTotals
+
+
+class Announce(Bridge):
+
+    name: str = 'announce'
+    reads: tuple[str, ...] = ('announce',)
+    config_cls = AnnounceConfig
+
+    SIDECAR = Sidecar(
+        name='announce', protocol=PROTOCOL,
+        upstream='py-libp2p gossipsub on %s' % TOPIC,
+        standalone='fleetmesh-announce NODE_DIR [--bootstrap MULTIADDR]',
+        probe='status')
+    CONSEQUENCE = 'this node is discoverable over relays only'
+
+    # Declared by the bridge from SIDECAR, under these names, with their
+    # counters (announce_sidecar_reachable / _unreachable / _incompatible).
+    SIDECAR_REACHABLE: str = 'announce.sidecar.reachable'
+    SIDECAR_UNREACHABLE: str = 'announce.sidecar.unreachable'
+    SIDECAR_INCOMPATIBLE: str = 'announce.sidecar.incompatible'
+    DESCRIPTOR_PUBLISHED: str = 'announce.descriptor.published'
+    PEERS_LEARNED: str = 'announce.peers.learned'
+
+    CHANNELS = (
+        ch_mod.Channel(
+            name=DESCRIPTOR_PUBLISHED,
+            description='The node descriptor was republished to the gossipsub announce topic.',
+            level=ch_mod.INFO,
+            wire=lambda id, topic: {'id': id, 'topic': topic},
+            say='published {id} on {topic}',
+            tags=('announce', 'descriptor')),
+        ch_mod.Channel(
+            name=PEERS_LEARNED,
+            description='New descriptors heard on the announce topic were verified and learned.',
+            level=ch_mod.INFO,
+            wire=lambda learned, heard, topic: {'learned': learned, 'heard': heard, 'topic': topic},
+            say='{learned} new peers learned from {heard} heard on {topic}',
+            tags=('announce', 'peers')),
+    )
+
+    METRICS = (
+        mx_mod.Metric(
+            name='announce_published',
+            description='Times this node published its descriptor on the announce topic.',
+            kind=mx_mod.COUNTER, counts=DESCRIPTOR_PUBLISHED,
+            tags=('announce', 'descriptor')),
+        mx_mod.Metric(
+            name='announce_peers_learned',
+            description='Times new peers were learned from the announce topic.',
+            kind=mx_mod.COUNTER, counts=PEERS_LEARNED,
+            tags=('announce', 'peers')),
+    )
+
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Announce Status',
+            description='the announce topic: whether the sidecar is there, what it has carried, '
+                        'and what this node refused off the topic',
+            tags=('announce', 'sidecar', 'status'),
+            parameters=(),
+            permission='announce/show',
+            process=('sidecar',),
+            run='state',
+            reply='{enabled, socket, connected, topic, peer_id, mesh_peers, published, '
+                  'heard, learned, sidecar}',
+            reads=('totals',),
+        ),
+    )
+
+    # What the topic has carried since this node first ran - not since its
+    # last upgrade: SNAPSHOT, so the lifecycle hands it to the next process.
+    # Not `published`: the next process's link starts unknown and the sidecar
+    # must hear the descriptor again (it may have restarted too).
+    STORES = (
+        st.Store(key='totals', description='descriptors carried up the topic, learned, and echoed back',
+                 kind=st.COUNTERS, shape=AnnounceTotals, persist=st.SNAPSHOT),
+    )
+    # Restartable like every bridge; snapshot v1 is the shape of `totals`.
+    LIFECYCLE = lifecycle_mod.Lifecycle(restart=True, snapshot=1)
+    NEEDS = (
+        Need('peers', 'peers'),
+        Need('directory', 'dir'),
+        Need('timeout', 'timeout'),
+        Need('descriptor', 'descriptor'),
+    )
+
+    def __init__(
+        self,
+        peers: Any,
+        directory: str,
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 5.0,
+        node: Optional[Any] = None,
+        descriptor: Optional[Callable[[], Optional[NostrEvent]]] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        # The node's own descriptor, read each publish through a getter
+        # because it is built after this compartment is.
+        self.descriptor: Callable[[], Optional[NostrEvent]] = descriptor or (lambda: getattr(node, 'descriptor', None))
+        self.peers: Any = peers
+        self.dir: str = directory
+        # Read once: a node that heard itself would otherwise cache itself.
+        self.node_pk: str = getattr(getattr(node, 'ks', None), 'node_pk', '') or ''
+        self.timeout: float = timeout
+        self.published: Optional[str] = None      # the descriptor id last handed to the sidecar
+        self.totals: st.Counters                  # built and bound by the base, from STORES
+        self.mesh_peers: int = 0
+        self.peer_id: Optional[str] = None
+
+    # The totals by name, as they were read before they were a store.
+    @property
+    def heard(self) -> int:
+        """Descriptors the sidecar carried up."""
+        return self.totals['heard']
+
+    @heard.setter
+    def heard(self, n: int) -> None:
+        self.totals['heard'] = n
+
+    @property
+    def learned(self) -> int:
+        """Of those, the ones this node did not already hold."""
+        return self.totals['learned']
+
+    @learned.setter
+    def learned(self, n: int) -> None:
+        self.totals['learned'] = n
+
+    @property
+    def echoed(self) -> int:
+        """And the ones that were this node's own publish returning."""
+        return self.totals['echoed']
+
+    @echoed.setter
+    def echoed(self, n: int) -> None:
+        self.totals['echoed'] = n
+
+    # ---- the bridge -----------------------------------------------------------
+    def endpoint(self) -> str:
+        return self.path
+
+    def wanted(self) -> bool:
+        return self.enabled
+
+    def forget(self) -> None:
+        # A sidecar that went away, or a bridge restarted, must hear the
+        # descriptor again when the link comes back.
+        self.published = None
+
+    # ---- configuration --------------------------------------------------------
+    @property
+    def enabled(self) -> bool:
+        return self.settings().enabled
+
+    @property
+    def path(self) -> str:
+        return socket_path(self.dir, self.settings().socket)
+
+    @property
+    def pow_bits(self) -> int:
+        return self.settings().pow_bits
+
+    # ---- the tick -------------------------------------------------------------
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        if not self.enabled:
+            return []
+        did: list[tuple[Any, ...]] = []
+        try:
+            did += self._publish(now)
+            did += self._drain(now)
+        except SidecarError:
+            # The bridge has moved the link, said so once and refused it;
+            # a missing sidecar costs this tick its gossip and nothing else.
+            return did
+        return did
+
+    def _publish(self, now: int) -> list[tuple[Any, ...]]:
+        """The node's own descriptor on the topic, republished only when it changes."""
+        desc = self.descriptor()
+        if not isinstance(desc, dict) or not desc.get('id'):
+            return []
+        if self.published == desc['id']:
+            return []
+        self.call('publish', descriptor=desc)
+        self.published = desc['id']
+        self.say(self.DESCRIPTOR_PUBLISHED, desc['id'][:12] + '…', TOPIC)
+        return [('announce', desc['id'][:12] + '…', 'published on ' + TOPIC)]
+
+    def _drain(self, now: int) -> list[tuple[Any, ...]]:
+        """Everything the sidecar heard since the last tick, checked here again."""
+        res = self.call('drain', max=DRAIN_MAX)
+        if not isinstance(res, dict):
+            bad = 'drain answered something that is not an object'
+            self._down(bad, now)
+            raise SidecarError(bad)
+        self.peer_id = res.get('peer_id') or self.peer_id
+        try:
+            self.mesh_peers = int(res.get('mesh_peers') or 0)
+        except (TypeError, ValueError):
+            self.mesh_peers = 0
+        learned = 0
+        for row in (res.get('heard') or [])[:DRAIN_MAX]:
+            if not isinstance(row, dict):
+                continue
+            self.totals.incr('heard')
+            payload = row.get('descriptor')
+            origin = str(row.get('from') or '')
+            # The same check the sidecar ran before propagating it. Run again
+            # because a separate process is not a reason to believe an event,
+            # and because the work floor is this node's policy and not its.
+            desc, why = admit(payload, origin, now, pow_bits=self.pow_bits)
+            if desc is None:
+                subject = (payload.get('pubkey') if isinstance(payload, dict) else None) or None
+                self.refusals.refuse('heard', str(why), subject=subject,
+                                     detail={'from': origin[:16]}, at=now)
+                continue
+            if self.node_pk and desc['pubkey'] == self.node_pk:
+                # A node hears its own publish: gossipsub runs the validator on
+                # the way out, so the descriptor this node just put on the topic
+                # comes straight back. Learning it would put this node in its own
+                # peer cache, which is where `known()` is read from. Not a
+                # refusal - it is the topic working.
+                self.totals.incr('echoed')
+                continue
+            if self.peers.learn(desc):
+                learned += 1
+            # A descriptor this node already holds at the same age is ordinary
+            # on a flood topic and is not a refusal: the same descriptor
+            # arrives many times over, which is what the topic is for.
+        self.totals.incr('learned', learned)
+        for reason, n in sorted((res.get('dropped') or {}).items()):
+            # What the sidecar's own validator refused before propagating it.
+            # Counted here so `meshnode refusals` shows one topic, not two.
+            self.refusals.refuse('sidecar', str(reason)[:64], detail={'count': n}, at=now)
+        if learned:
+            self.say(self.PEERS_LEARNED, learned, len(res.get('heard') or []), TOPIC)
+        return [('announce', '%d heard' % len(res.get('heard') or []), '%d new' % learned)] if learned else []
+
+    # ---- being watched --------------------------------------------------------
+    def state(self) -> AnnounceStateReport:
+        return {
+            'enabled': self.enabled,
+            'socket': self.path,
+            'connected': self.link == UP,
+            'topic': TOPIC,
+            'peer_id': self.peer_id,
+            'mesh_peers': self.mesh_peers,
+            'pow_bits': self.pow_bits,
+            'published': self.published,
+            'heard': self.heard,
+            'learned': self.learned,
+            'echoed': self.echoed,
+        }
+
+    def trouble(self) -> list[str]:
+        # Down or incompatible is the bridge's to say, the same way for every
+        # sidecar; an empty topic is announce's own.
+        out = super().trouble()
+        if out or not self.wanted():
+            return out
+        if self.link == UP and not self.mesh_peers:
+            return ['on %s with no gossipsub peers: nothing hears this node there' % TOPIC]
+        return []

node/planes/identity/announce/types.py

@@ -0,0 +1,26 @@
+"""Types and records for the Announce compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class AnnounceStateReport(TypedDict, total=False):
+    """The report Announce.state() gives of itself."""
+    enabled: bool
+    socket: Optional[str]
+    connected: bool
+    topic: str
+    peer_id: Optional[str]
+    mesh_peers: int
+    pow_bits: int
+    published: Optional[str | int]
+    heard: int
+    learned: int
+    echoed: int
+
+
+class AnnounceTotals(TypedDict):
+    """What the announce topic has carried: one counter each."""
+    heard: int      # descriptors the sidecar carried up
+    learned: int    # of those, the ones this node did not already hold
+    echoed: int     # and the ones that were this node's own publish returning

node/planes/identity/discovery/__init__.py

@@ -0,0 +1,9 @@
+"""What this node tells the mesh it is and what it holds, as a compartment.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Discovery
+from .types import DiscoveryStateReport
+
+__all__ = ['Discovery', 'DiscoveryStateReport']
+