docs/modules/M02-discovery.md

# M02 — Discovery

**Spec version:** v1.0
**Depends on:** M01 (identity), X04 (config), X03 (observability), X01 (transport, for the manifest fetch URL), `python-zeroconf`
**Depended on by:** M03 (bus, for peer enumeration), M09 (emergency mode increases discovery cadence)

---

## 1. Responsibility

Find peers on the local network. Maintain a live in-memory registry of known peers with their manifests, last-seen timestamps, and latencies. Republish our own presence.

Out of scope:
- DHT (Phase 2)
- LoRa beacons (Phase 3)
- Internet relay (Phase 2)

---

## 2. File layout

```
hearthnet/discovery/
├── __init__.py
├── mdns.py              # zeroconf-based service browser + announcer
├── udp.py               # UDP broadcast announcer + listener
├── peers.py             # PeerRegistry: in-memory state
└── relay.py             # Phase 2 stub
```

---

## 3. Public API

### 3.1 `peers.py`

```python
# hearthnet/discovery/peers.py
from dataclasses import dataclass

@dataclass
class PeerRecord:
    node_id:        str             # short form
    node_id_full:   str
    display_name:   str
    community_id:   str
    profile:        str
    endpoints:      list[Endpoint]
    manifest:       NodeManifest | None  # None until fetched
    last_seen:      float           # monotonic time
    rtt_ms:         float | None    # measured by health probe
    source:         str             # "mdns" | "udp" | "relay"

class PeerRegistry:
    """In-memory map of NodeID → PeerRecord. Thread-safe via asyncio.Lock."""

    def __init__(self, our_node_id_full: str, community_id: str):
        ...

    def upsert(self, record: PeerRecord) -> bool:
        """Add or update; returns True if new peer."""

    def remove(self, node_id_full: str) -> bool: ...

    def get(self, node_id_full: str) -> PeerRecord | None: ...

    def all(self) -> list[PeerRecord]: ...

    def for_community(self, community_id: str) -> list[PeerRecord]: ...

    def prune_stale(self, max_age_seconds: int = 90) -> int:
        """Remove peers not seen recently. Returns count removed."""

    # subscribers (called when peer added / removed / updated):
    def subscribe(self) -> AsyncIterator[PeerEvent]: ...

@dataclass(frozen=True)
class PeerEvent:
    kind:   str        # "added" | "removed" | "updated"
    peer:   PeerRecord
```

### 3.2 `mdns.py`

```python
# hearthnet/discovery/mdns.py
class MdnsAnnouncer:
    """Publishes our own service via mDNS."""
    def __init__(
        self,
        kp: KeyPair,
        node_id_short: str,
        display_name: str,
        community_id_short: str,
        profile: str,
        port: int,
        capabilities_names: list[str],
        manifest_url: str,
    ):
        ...
    async def start(self) -> None: ...
    async def stop(self) -> None: ...
    def update(self, *, capabilities_names: list[str] | None = None) -> None:
        """Refresh TXT records (e.g. when capabilities change)."""

class MdnsBrowser:
    """Listens for other nodes via mDNS, populates the registry."""
    def __init__(self, registry: PeerRegistry, our_community_id: str):
        ...
    async def start(self) -> None: ...
    async def stop(self) -> None: ...
```

### 3.3 Service definition

- Service type: `_hearthnet._tcp.local.`
- Instance name: `<display_name>-<short_node_id_4chars>`
- Port: from manifest's first endpoint
- TXT records:
  - `v=1`
  - `node=<short_node_id>`
  - `community=<short_community_id>`
  - `profile=<anchor|hearth|spark|bridge>`
  - `caps=<comma-separated cap names>` (max 200 bytes; truncate if needed)
  - `manifest_url=https://<host>:<port>/manifest`
  - `contract_version=1.0`

### 3.4 `udp.py`

```python
# hearthnet/discovery/udp.py
class UdpAnnouncer:
    """Periodic UDP multicast of node presence."""
    def __init__(
        self,
        kp: KeyPair,
        registry: PeerRegistry,
        node_id_short: str,
        community_id_short: str,
        port: int,
        capabilities_names: list[str],
        multicast_group: str = "239.255.42.42",
        multicast_port: int = 42424,
    ):
        ...
    async def run(self) -> None:
        """Loop: emit announcement every DISCOVERY_UDP_INTERVAL_SECONDS.
        Active interval when fewer than 2 peers; stable interval otherwise."""

class UdpListener:
    """Receives multicast announcements, populates registry."""
    def __init__(self, registry: PeerRegistry, our_community_id: str): ...
    async def run(self) -> None: ...
```

### 3.5 UDP payload

```json
{"v":1,"node":"7H4G-Y9KL","community":"NIED-...","port":7080,"caps":["llm.chat","rag.query"]}
```

Max 1KB. No signature on the announce itself (we'll re-fetch & verify the full manifest from `manifest_url`).

---

## 4. Behaviour

### 4.1 First contact flow

```
mDNS or UDP discovers a peer at <host:port> for community X (matches ours)
  ↓
PeerRegistry.upsert(stub PeerRecord with manifest=None)
  ↓
asyncio task: HTTP GET https://<host>:<port>/manifest (via X01 client)
  ↓
parse + verify_node_manifest (M01)
  ↓
if community matches AND author is a member (community manifest): keep
otherwise: remove
  ↓
PeerEvent("added") emitted
```

### 4.2 Refresh

- mDNS TXT updates trigger re-fetch of `/manifest`
- Every 30 seconds, we attempt to refresh peers whose manifests are within 10 seconds of expiry
- Peers whose manifests expired and could not be refetched are pruned after 90 seconds

### 4.3 Mode behaviour

When [M09](M09-emergency.md) reports offline:

- `UdpAnnouncer` switches to fast interval
- `MdnsAnnouncer` doesn't change (already low-overhead)
- Stale peer pruning becomes more aggressive (30s instead of 90s) — we want fresh data quickly

### 4.4 Multi-interface handling

- mDNS uses `zeroconf` defaults (all interfaces)
- UDP listener binds to `INADDR_ANY` on the multicast group; SO_REUSEPORT so multiple processes can coexist on the same host

### 4.5 Privacy

mDNS announces the short NodeID, profile, and a list of capability names. This is visible to any device on the LAN. We accept this — it is the price of zero-config.

Devices NOT in our community still see our presence but cannot make calls (rejected at the bus signature check).

---

## 5. Errors

`DiscoveryError` codes:

- `socket_in_use` — UDP port already bound
- `mdns_unavailable` — zeroconf fails to start (Linux without avahi, etc.)
- `manifest_fetch_failed` — HTTP error fetching `/manifest`
- `manifest_invalid` — propagated from M01 verification

Errors are logged but not fatal; the node continues with whichever discovery transport works.

---

## 6. Configuration

From [X04](X04-config.md):

```python
config.discovery.mdns_enabled
config.discovery.udp_enabled
config.discovery.udp_multicast_group
config.discovery.udp_port
config.discovery.relay_urls       # Phase 2
```

Constants: `DISCOVERY_UDP_INTERVAL_SECONDS`.

---

## 7. Tests

### Unit
- `test_peer_registry_upsert_returns_true_first_time`
- `test_peer_registry_prune_stale`
- `test_udp_payload_under_1kb`
- `test_mdns_txt_records_parse`

### Integration
- `test_two_nodes_find_each_other_via_mdns` (in-process zeroconf)
- `test_udp_fallback_when_mdns_disabled`
- `test_foreign_community_peer_filtered_out`

---

## 8. Cross-references

| What | Where |
|------|-------|
| Manifest fetch + verify | [M01 §3.2](M01-identity.md) |
| Service definition | [CONTRACT §6.1](../CAPABILITY_CONTRACT.md) (manifest schema) |
| Bus consumes peer events | [M03 §5.2](M03-bus.md) |
| Emergency mode influence | [M09 §5](M09-emergency.md) |
| Phase 2 internet relay | this module's `relay.py` (stub) |