prd splitted + contracts

docs/00-OVERVIEW.md

@@ -0,0 +1,366 @@
+# HearthNet — Spec Set Overview
+
+This directory is the implementation-level specification for HearthNet. It supersedes the design-level PRD for any conflict on the wire format, file layout, or API surface.
+
+The documents are intentionally redundant in some places so each module spec can be read independently during implementation.
+
+---
+
+## 0. How to read this set
+
+Read in this order:
+
+1. **00-OVERVIEW.md** (this file) — module map, dependency graph, build order
+2. **GLOSSARY.md** — canonical names for every entity that appears in more than one doc
+3. **CAPABILITY_CONTRACT.md** — the wire-level source of truth; everything else must comply
+4. **cross-cutting/X01..X04** — concerns that touch every module
+5. **modules/M01..M13** — per-module specs in dependency order
+
+Cross-references between documents use the shorthand `[M03 §4.2]` (module 3, section 4.2) or `[CONTRACT §7.1]` (the contract document, section 7.1).
+
+---
+
+## 1. Module map
+
+### Numbered modules (from PRD v2 §20)
+
+| ID  | Module                  | Spec file                                    | Concern                                             |
+|-----|-------------------------|----------------------------------------------|------------------------------------------------------|
+| M01 | Identity & manifests    | `modules/M01-identity.md`                    | Crypto identity, signing, verification, manifests    |
+| M02 | Discovery               | `modules/M02-discovery.md`                   | Finding peers on a LAN or via relay                  |
+| M03 | Capability bus          | `modules/M03-bus.md`                         | Routing requests to capabilities                     |
+| M04 | LLM service             | `modules/M04-llm.md`                         | Language model inference capabilities                |
+| M05 | RAG service             | `modules/M05-rag.md`                         | Retrieval-augmented generation                       |
+| M06 | Marketplace service     | `modules/M06-marketplace.md`                 | Community posts, offers, requests                    |
+| M07 | File / blobs            | `modules/M07-file-blobs.md`                  | Content-addressed storage and transfer               |
+| M08 | UI                      | `modules/M08-ui.md`                          | Gradio dashboard + topology viz + mobile             |
+| M09 | Emergency detector      | `modules/M09-emergency.md`                   | Internet up/down detection + mode transitions        |
+| M10 | Chat service            | `modules/M10-chat.md`                        | Direct messages + store-and-forward                  |
+| M11 | Embedding service       | `modules/M11-embedding.md`                   | Text and image embedding capabilities                |
+| M12 | CLI                     | `modules/M12-cli.md`                         | `hearthnet` command-line entry points                |
+| M13 | Onboarding              | `modules/M13-onboarding.md`                  | First-run UX, invite QR, key generation flow         |
+
+### Cross-cutting modules
+
+| ID  | Module          | Spec file                              | Concern                                             |
+|-----|-----------------|----------------------------------------|------------------------------------------------------|
+| X01 | Transport       | `cross-cutting/X01-transport.md`       | HTTP server, HTTP client, TLS, streaming, backpressure |
+| X02 | Events          | `cross-cutting/X02-events.md`          | Event log, Lamport clocks, snapshots, gossip sync    |
+| X03 | Observability   | `cross-cutting/X03-observability.md`   | Logging, metrics, tracing, self-diagnostics          |
+| X04 | Config          | `cross-cutting/X04-config.md`          | Configuration loading and validation                 |
+
+---
+
+## 2. Dependency graph
+
+```
+                      ┌──────────┐
+                      │  config  │  X04
+                      └────┬─────┘
+                           │ (everyone reads it)
+            ┌──────────────┴──────────────┐
+            ▼                             ▼
+       ┌─────────┐                  ┌─────────────┐
+       │ identity│  M01             │observability│  X03
+       └────┬────┘                  └─────────────┘
+            │
+   ┌────────┼────────────┬────────────┐
+   ▼        ▼            ▼            ▼
+┌──────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
+│events│ │discovery│ │transport│ │  blobs   │   X02 / M02 / X01 / part-of-M07
+└──┬───┘ └────┬────┘ └────┬────┘ └────┬─────┘
+   │          │           │           │
+   │          └───────┬───┘           │
+   │                  ▼               │
+   │             ┌─────────┐          │
+   │             │   bus   │  M03     │
+   │             └────┬────┘          │
+   │                  │               │
+   │   ┌─────────┬────┴────┬────────┐ │
+   │   ▼         ▼         ▼        ▼ ▼
+   │ ┌─────┐ ┌──────┐ ┌────────┐ ┌────────┐
+   │ │ llm │ │embed │ │  rag   │ │  file  │   M04 / M11 / M05 / M07
+   │ └─────┘ └──┬───┘ └───┬────┘ └────────┘
+   │            │         │
+   │            └─────────┘   (rag uses embed)
+   │
+   │  ┌────────────┐  ┌──────┐
+   ├─►│ marketplace│  │ chat │   M06 / M10
+   │  └────────────┘  └──────┘
+   │            │         │
+   └────────────┘         │
+                          │
+                ┌─────────▼──────────┐
+                │     emergency      │   M09
+                └────────┬───────────┘
+                         │
+                ┌────────▼───────────┐
+                │        ui          │   M08
+                └────────────────────┘
+                         │
+                ┌────────▼───────────┐
+                │   onboarding       │   M13
+                └────────────────────┘
+                         │
+                ┌────────▼───────────┐
+                │        cli         │   M12
+                └────────────────────┘
+```
+
+Hard rules:
+
+- **No service imports from another service.** Services talk to each other only via the bus.
+- **No layer below the bus imports anything above it.** Transport never imports a service; identity never imports the bus.
+- **The bus does not know what services exist** at build time. Services register themselves at startup.
+- **UI never imports a service directly.** It calls capabilities via the bus.
+
+---
+
+## 3. File tree (Python package layout)
+
+```
+hearthnet/
+├── __init__.py
+├── __main__.py                       # python -m hearthnet → cli.main()
+├── version.py                        # __version__ = "0.1.0"
+│
+├── config.py                         # X04
+│
+├── identity/                         # M01
+│   ├── __init__.py
+│   ├── keys.py
+│   ├── manifest.py
+│   └── tokens.py                     # Phase 2
+│
+├── observability/                    # X03
+│   ├── __init__.py
+│   ├── logging.py
+│   ├── metrics.py
+│   ├── tracing.py
+│   └── doctor.py
+│
+├── events/                           # X02
+│   ├── __init__.py
+│   ├── log.py
+│   ├── lamport.py
+│   ├── types.py
+│   ├── replay.py
+│   ├── snapshot.py
+│   └── sync.py
+│
+├── discovery/                        # M02
+│   ├── __init__.py
+│   ├── mdns.py
+│   ├── udp.py
+│   ├── peers.py                      # peer registry (in-memory)
+│   └── relay.py                      # Phase 2
+│
+├── transport/                        # X01
+│   ├── __init__.py
+│   ├── server.py
+│   ├── client.py
+│   ├── streams.py
+│   ├── backpressure.py
+│   └── tls.py
+│
+├── blobs/                            # M07 (the storage half)
+│   ├── __init__.py
+│   ├── store.py
+│   ├── chunker.py
+│   └── transfer.py
+│
+├── bus/                              # M03
+│   ├── __init__.py
+│   ├── capability.py
+│   ├── registry.py
+│   ├── router.py
+│   ├── health.py
+│   ├── schema.py
+│   └── trace.py
+│
+├── services/                         # L4
+│   ├── __init__.py
+│   ├── base.py
+│   ├── llm/                          # M04
+│   │   ├── __init__.py
+│   │   ├── service.py
+│   │   ├── tokenizers.py
+│   │   └── backends/
+│   │       ├── __init__.py
+│   │       ├── base.py
+│   │       ├── llama_cpp.py
+│   │       ├── ollama.py
+│   │       ├── lmstudio.py
+│   │       ├── hf_api.py
+│   │       └── anthropic_api.py
+│   ├── embedding/                    # M11
+│   │   ├── __init__.py
+│   │   ├── service.py
+│   │   └── backends.py
+│   ├── rag/                          # M05
+│   │   ├── __init__.py
+│   │   ├── service.py
+│   │   ├── chunker.py
+│   │   ├── ingest.py
+│   │   └── store.py
+│   ├── file/                         # M07 (the service half)
+│   │   ├── __init__.py
+│   │   └── service.py
+│   ├── marketplace/                  # M06
+│   │   ├── __init__.py
+│   │   ├── service.py
+│   │   ├── post.py
+│   │   └── views.py
+│   └── chat/                         # M10
+│       ├── __init__.py
+│       ├── service.py
+│       ├── delivery.py
+│       └── views.py
+│
+├── emergency/                        # M09
+│   ├── __init__.py
+│   ├── detector.py
+│   └── state.py
+│
+├── ui/                               # M8 + M13
+│   ├── __init__.py
+│   ├── app.py
+│   ├── topology.py
+│   ├── theme.py
+│   ├── onboarding.py                 # M13
+│   ├── tabs/
+│   │   ├── __init__.py
+│   │   ├── ask.py
+│   │   ├── chat.py
+│   │   ├── marketplace.py
+│   │   ├── files.py
+│   │   ├── emergency.py
+│   │   └── settings.py
+│   └── mobile/                       # static assets
+│       ├── index.html
+│       ├── app.js
+│       └── style.css
+│
+├── cli.py                            # M12
+├── node.py                           # Orchestrator (composes everything)
+└── doctor.py                         # (re-export of observability.doctor)
+
+tests/
+├── unit/                             # per-module
+│   ├── test_identity_keys.py
+│   ├── test_identity_manifest.py
+│   ├── test_events_log.py
+│   ├── ...
+└── integration/                      # multi-node
+    ├── test_three_node_mesh.py
+    ├── test_emergency_mode.py
+    └── test_rejoin_sync.py
+```
+
+---
+
+## 4. Canonical conventions
+
+### 4.1 Type aliases (use these names everywhere)
+
+```python
+NodeID         = str        # "ed25519:XXXX-XXXX-XXXX-XXXX"
+CommunityID    = str        # "ed25519:..."
+CapabilityName = str        # "llm.chat"
+Version        = tuple[int, int]   # (1, 0)
+Lamport        = int
+CID            = str        # "blake3:..."
+EventID        = str        # ULID
+TraceID        = str        # ULID
+SchemaHash     = str        # "blake3:..."
+WallClock      = str        # RFC 3339 UTC: "2026-05-26T08:14:22Z"
+Signature      = str        # "ed25519:<base64-url-nopad>"
+Topic          = str        # "marketplace.post.created"
+ErrorCode      = Literal[
+    "not_found", "capacity_exceeded", "schema_mismatch", "unauthorized",
+    "revoked", "internal_error", "not_implemented", "timeout", "partition",
+    "invalid_signature", "expired", "rate_limited", "bad_request",
+]
+TrustLevel     = Literal["unknown", "member", "trusted", "anchor"]
+Profile        = Literal["anchor", "hearth", "spark", "bridge"]
+Stability      = Literal["experimental", "beta", "stable"]
+```
+
+These are defined in `hearthnet.types` and re-exported by every module that uses them. Never invent a synonym.
+
+### 4.2 Naming
+
+- Functions: `snake_case`, verb-first (`load_keys`, `verify_signature`, `route_request`)
+- Classes: `PascalCase`, noun (`NodeManifest`, `CapabilityBus`, `RagService`)
+- Constants: `SCREAMING_SNAKE` (`MANIFEST_TTL_SECONDS`)
+- Module-private: leading underscore (`_compute_canonical_json`)
+- Async functions: same naming as sync, no `async_` prefix
+- Protocols / interfaces: `PascalCase` ending in capability noun (`LlmBackend`, `Service`)
+
+### 4.3 Error handling
+
+- All errors that cross a process boundary become an `HearthNetError` with an `ErrorCode`
+- All errors that stay in-process are domain exceptions inheriting from `HearthNetError`
+- Never raise `RuntimeError` or bare `Exception` in production code
+- Logging exceptions: always with `exc_info=True` so traceback survives
+
+### 4.4 Async vs sync
+
+- I/O is async (asyncio)
+- CPU-bound work (PDF parsing, embedding) runs in `asyncio.to_thread` or a dedicated process pool
+- Public APIs are async unless explicitly noted (`load_keys` is sync, returns from disk)
+
+### 4.5 Time
+
+- All wall-clock timestamps in events: RFC 3339 UTC, e.g. `2026-05-26T08:14:22Z`
+- All durations: integers in seconds, named `*_seconds` (never `*_secs`, `*_s`)
+- Logical ordering: Lamport clocks; wall clock is advisory only
+
+### 4.6 Sizes
+
+- Bytes: integers, named `*_bytes`
+- KB/MB/GB shown to users only at the UI layer, never in protocol/event payloads
+
+---
+
+## 5. Build order (hackathon-aligned)
+
+Strictly follow this order. Each step is independently demoable.
+
+| Step | Modules built                          | What you can demo            |
+|------|----------------------------------------|------------------------------|
+| 1    | X04 (config), X03 (logging only)       | Process boots, logs to file  |
+| 2    | M01 (identity, manifests)              | `hearthnet init` works       |
+| 3    | X02 (events log + Lamport, no sync)    | Marketplace events persist   |
+| 4    | X01 (transport, server only)           | Two nodes can ping each other|
+| 5    | M02 (discovery, mDNS only)             | Two nodes find each other    |
+| 6    | M03 (bus with fake echo service)       | A capability call round-trips|
+| 7    | M04 (LLM, llama.cpp or LM Studio backend) | Real LLM call across nodes |
+| 8    | M11 (embeddings)                       | Embed text via the bus       |
+| 9    | M05 (RAG)                              | RAG-grounded answer          |
+| 10   | M08 (UI shell + topology viz)          | Visible mesh, visible routing|
+| 11   | M09 (emergency detector)               | Banner toggles on cable yank |
+| 12   | M06 (marketplace)                      | Post visible across nodes    |
+| 13   | M10 (chat)                             | Cross-node DM                |
+| 14   | M07 (file/blobs)                       | CID-addressed file transfer  |
+| 15   | M12 (CLI), M13 (onboarding)            | First-run UX polished        |
+| 16   | X02 sync, X03 metrics, X03 doctor      | Production-ish polish        |
+
+---
+
+## 6. Versioning of this spec set
+
+Every spec file carries a header `Spec version: vX.Y` and a `Last touched: <date>`. Bump the minor on additive changes, the major on breaking changes. The contract document's version is the version everyone else complies with — module specs may lag by one minor.
+
+The Python package version (`hearthnet.version.__version__`) and the contract version are independent. The contract version appears in the `version` field of every node manifest and is checked at handshake.
+
+---
+
+## 7. Out-of-band documents
+
+Not in this spec set but referenced:
+
+- **PRD v2** (`../HEARTHNET_PRD_v2.md`) — vision, scope, monetisation, phased roadmap
+- **README** (in repo root, written later) — user-facing quickstart
+- **THREAT_MODEL.md** (Phase 2) — formal security write-up
+- **DEPLOYMENT.md** (Phase 2) — for the appliance and relay-tier operators

docs/CAPABILITY_CONTRACT.md

@@ -0,0 +1,1332 @@
+# HearthNet Capability Contract
+
+**Spec version:** v1.0
+**Last touched:** 2026-06-07
+**Scope:** wire-level protocol, capability schemas, event schemas, signing rules.
+
+This document is the source of truth. Any conflict with a module spec is resolved in favour of this document.
+
+---
+
+## 1. Conventions
+
+### 1.1 Encodings
+
+- **Wire format**: JSON, UTF-8, no BOM. Numbers fit IEEE 754 double; integers fit in 53 bits. Where 64-bit precision is needed (rare), use strings.
+- **Binary content**: Base64-URL without padding, prefixed by encoding tag where ambiguous (`ed25519:`, `blake3:`).
+- **Timestamps**: RFC 3339 UTC with `Z`, e.g. `2026-05-26T08:14:22Z`. No timezone offsets, no fractional seconds beyond milliseconds (`...22.281Z` is allowed for tracing only).
+- **Durations**: integer seconds, suffix `_seconds` in field names.
+- **Sizes**: integer bytes, suffix `_bytes`. UI may convert to KB/MB; wire never does.
+
+### 1.2 Canonical JSON
+
+For any payload that is signed or hashed, the canonical form is:
+
+- Keys sorted lexicographically at every level
+- No whitespace between tokens
+- Numbers without trailing zeros: `1.0` → `1`, `1.10` → `1.1`
+- Strings UTF-8, non-ASCII characters not escaped
+- `null` allowed only where the schema declares it
+
+A reference implementation is `hearthnet.identity.keys.canonical_json(obj) -> bytes`. Use it always.
+
+### 1.3 Signing primitive
+
+Ed25519 over the canonical-JSON byte string of the payload excluding the `signature` field itself. The signature field is added back after signing. To verify, strip `signature`, re-canonicalise, verify.
+
+### 1.4 Hashing primitive
+
+BLAKE3. Output: 32 bytes, presented as lowercase hex with the prefix `blake3:`. Where short forms are needed (display), use the first 16 hex chars: `blake3:abc123...`. The full hex is always used in protocol fields.
+
+### 1.5 Identifier forms
+
+See [GLOSSARY.md](GLOSSARY.md). Identifiers in protocol payloads always use the full form. Display forms are UI-only.
+
+---
+
+## 2. Versioning
+
+### 2.1 Capability version
+
+A capability declares `version: "X.Y"` where X is major, Y is minor.
+
+- **Compatibility**: a request asking for `name@>=A.B` is satisfied by an offered `name@X.Y` iff `X == A` and `Y >= B`.
+- **Major bumps**: breaking. Old callers receive `schema_mismatch`.
+- **Minor bumps**: additive only. Old callers continue to work. New fields are optional with documented defaults.
+- The `schema_hash` (BLAKE3 of the request + response schema) is recomputed on every bump. Two nodes with the same `schema_hash` for a capability speak identically.
+
+### 2.2 Contract version
+
+This document is versioned independently of capabilities. Node manifests carry `contract_version: "1.0"` so peers can refuse to talk to incompatible contract revisions.
+
+### 2.3 Event schema version
+
+Each event carries a `schema_version` field. Old events are kept verbatim; readers translate via a versioned schema registry. Never rewrite history.
+
+---
+
+## 3. Capability namespace
+
+### 3.1 Prefix allocation
+
+| Prefix | Owner | Stability of prefix | Defined in |
+|--------|-------|---------------------|------------|
+| `llm.*` | LLM service | stable | M04 |
+| `embed.*` | Embedding service | stable | M11 |
+| `rag.*` | RAG service | stable | M05 |
+| `file.*` | File service | stable | M07 |
+| `market.*` | Marketplace | stable | M06 |
+| `chat.*` | Chat | stable | M10 |
+| `community.*` | Trust ops | stable | M01 + X02 |
+| `federation.*` | Cross-community | beta | Phase 2 |
+| `ocr.*` | OCR (Phase 2) | reserved | — |
+| `tts.*` `stt.*` | Speech (Phase 2) | reserved | — |
+| `trans.*` | Translation (Phase 2) | reserved | — |
+| `img.*` | Images (Phase 2) | reserved | — |
+| `experimental.*` | Anything not promoted | unstable | any |
+
+Reserved prefixes may not be used. Capabilities outside the reserved set must start with `experimental.`.
+
+### 3.2 Complete capability list (this release)
+
+| Name | Stability | Stream? | Trust required | Section |
+|------|-----------|---------|----------------|---------|
+| `llm.chat@1.0` | stable | yes | member | §4.1 |
+| `llm.complete@1.0` | stable | yes | member | §4.2 |
+| `embed.text@1.0` | stable | no | member | §4.3 |
+| `rag.query@1.0` | stable | no | member | §4.4 |
+| `rag.ingest@1.0` | stable | no | trusted | §4.5 |
+| `rag.list_corpora@1.0` | stable | no | member | §4.6 |
+| `file.read@1.0` | stable | yes (chunks) | member | §4.7 |
+| `file.list@1.0` | stable | no | member | §4.8 |
+| `file.advertise@1.0` | stable | no | member | §4.9 |
+| `file.put@1.0` | stable | yes (chunks) | trusted | §4.10 |
+| `market.list@1.0` | stable | no | member | §4.11 |
+| `market.post@1.0` | stable | no | member | §4.12 |
+| `market.expire@1.0` | stable | no | member (own only) | §4.13 |
+| `market.search@1.0` | stable | no | member | §4.14 |
+| `chat.send@1.0` | stable | no | member | §4.15 |
+| `chat.history@1.0` | stable | no | member (self only) | §4.16 |
+| `community.invite@1.0` | stable | no | member with invite right | §4.17 |
+| `community.revoke@1.0` | stable | no | 3 of trusted | §4.18 |
+
+`federation.*`, `ocr.*`, `tts.*`, `stt.*`, `trans.*`, `img.*` are out of scope for this release; placeholders only.
+
+---
+
+## 4. Per-capability specifications
+
+For each capability the spec gives:
+
+- **Purpose**
+- **Trust required**
+- **Idempotency**
+- **Request schema** (JSON Schema-ish; required fields marked)
+- **Response schema** (or stream frame schema)
+- **Errors** (codes that this capability may return beyond the universal set)
+- **Example request and response**
+
+The universal error codes apply to every capability: `bad_request`, `unauthorized`, `revoked`, `capacity_exceeded`, `internal_error`, `timeout`, `partition`, `invalid_signature`, `expired`, `rate_limited`.
+
+### 4.1 `llm.chat@1.0`
+
+- **Purpose**: Multi-turn chat completion. Server-streams tokens.
+- **Trust**: member
+- **Idempotency**: no (token sampling is non-deterministic)
+- **Stream**: yes (SSE)
+
+#### Request
+
+```json
+{
+  "params": {
+    "model": "qwen2.5-7b-instruct",          // required, must match an offered model
+    "ctx": 8192                              // optional, default = declared max
+  },
+  "input": {
+    "messages": [                            // required, ≥ 1
+      {"role": "system", "content": "..."},  // optional
+      {"role": "user",   "content": "..."},  // required at least once
+      {"role": "assistant", "content": "..."}
+    ],
+    "max_tokens":   512,                     // optional, default 1024
+    "temperature":  0.7,                     // optional, default 0.7
+    "top_p":        0.95,                    // optional, default 0.95
+    "stop":         ["</s>"],                // optional
+    "seed":         42,                      // optional; if set, server SHOULD make deterministic
+    "tools":        [],                      // optional, OpenAI-compatible tool defs (Phase 2)
+    "tool_choice":  "auto",                  // optional
+    "stream":       true                     // optional, default true
+  }
+}
+```
+
+#### Response — non-stream (only if `stream:false`)
+
+```json
+{
+  "output": {
+    "message": {"role": "assistant", "content": "..."},
+    "tool_calls": []                         // optional
+  },
+  "meta": {
+    "model": "qwen2.5-7b-instruct",
+    "tokens_in": 42,
+    "tokens_out": 178,
+    "stop_reason": "end",                    // "end" | "max_tokens" | "stop_sequence" | "cancelled"
+    "ms": 1834
+  }
+}
+```
+
+#### Stream frames
+
+```
+event: token
+data: {"text":"Sie ", "logprob": -0.21}
+
+event: tool_call_delta                       (only if tools used; Phase 2)
+data: {"id":"...","name":"search","arguments_delta":"{\"q\":\"..."}
+
+event: done
+data: {"tokens_out": 178, "stop_reason": "end", "ms": 1834}
+```
+
+A `done` frame is always sent. Client closing the connection mid-stream cancels generation within 200ms (server SHOULD abort).
+
+#### Errors
+
+Beyond universal:
+- `not_implemented` — server registered the capability but backend is missing the model
+- `bad_request` — malformed messages, empty messages, role sequence violation
+
+### 4.2 `llm.complete@1.0`
+
+- **Purpose**: Single-shot completion (no chat structure). Used by RAG internally and by classical tooling.
+- **Trust**: member
+- **Stream**: yes
+
+#### Request
+
+```json
+{
+  "params": {"model": "qwen2.5-7b-instruct"},
+  "input": {
+    "prompt":       "...",                   // required
+    "max_tokens":   256,
+    "temperature":  0.7,
+    "top_p":        0.95,
+    "stop":         ["\n\n"],
+    "seed":         null,
+    "stream":       true
+  }
+}
+```
+
+#### Response (non-stream)
+
+```json
+{
+  "output": {"text": "..."},
+  "meta": {"model": "...", "tokens_in": 12, "tokens_out": 80, "stop_reason": "end", "ms": 312}
+}
+```
+
+#### Stream frames
+
+Same as `llm.chat` but only `token` and `done`. No `tool_call_delta`.
+
+### 4.3 `embed.text@1.0`
+
+- **Purpose**: Embed one or many strings into vectors.
+- **Trust**: member
+- **Idempotency**: yes (assuming deterministic backend)
+
+#### Request
+
+```json
+{
+  "params": {"model": "bge-small-en-v1.5"},
+  "input":  {
+    "texts": ["...", "...", "..."],          // required, 1..256
+    "normalize": true                        // optional, default true
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "embeddings": [[0.012, -0.043, ...], [...], [...]],
+    "dim": 384
+  },
+  "meta": {"model": "bge-small-en-v1.5", "ms": 38}
+}
+```
+
+#### Errors
+
+- `bad_request` — > 256 texts, or any text > 8192 chars
+
+### 4.4 `rag.query@1.0`
+
+- **Purpose**: Retrieve top-K relevant chunks from a named corpus.
+- **Trust**: member
+- **Idempotency**: yes
+
+#### Request
+
+```json
+{
+  "params": {"corpus": "niederrhein-emergency"},
+  "input": {
+    "query":  "Wie reinige ich Regenwasser?",
+    "k":      5,                             // optional, default 5, max 20
+    "filter": {                              // optional metadata filter
+      "language": "de",
+      "min_year": 2000
+    },
+    "include_text": true                     // optional, default true
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "chunks": [
+      {
+        "rank": 1,
+        "score": 0.84,
+        "text":  "Regenwasser kann durch Filtration ...",
+        "metadata": {
+          "doc_cid": "blake3:...",
+          "doc_title": "Notfall-Trinkwasser",
+          "page": 12,
+          "chunk_id": "ch_001"
+        }
+      }
+    ]
+  },
+  "meta": {"corpus": "niederrhein-emergency", "ms": 24, "embedding_model": "bge-small-en-v1.5"}
+}
+```
+
+#### Errors
+
+- `not_found` — corpus does not exist
+- `bad_request` — k > 20
+
+### 4.5 `rag.ingest@1.0`
+
+- **Purpose**: Add a document to a corpus.
+- **Trust**: trusted (corpus pollution is a real risk)
+- **Idempotency**: by content hash (`doc_cid`)
+
+#### Request
+
+```json
+{
+  "params": {"corpus": "niederrhein-emergency"},
+  "input": {
+    "doc_cid": "blake3:...",                 // required; document must already be in blob store
+    "title":   "Notfall-Trinkwasser",
+    "language": "de",
+    "metadata": {"author": "...", "year": 2024}
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "doc_cid": "blake3:...",
+    "chunks_indexed": 87,
+    "tokens_indexed": 18342
+  },
+  "meta": {"corpus": "niederrhein-emergency", "ms": 4210, "ingest_event_id": "01HXR..."}
+}
+```
+
+The ingest also publishes a `rag.document.ingested` event (§7).
+
+#### Errors
+
+- `not_found` — `doc_cid` not resolvable to a blob
+- `bad_request` — unsupported media type
+
+### 4.6 `rag.list_corpora@1.0`
+
+#### Request
+
+```json
+{"params": {}, "input": {}}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "corpora": [
+      {"name": "niederrhein-emergency", "docs": 6, "chunks": 412, "size_bytes": 18243842, "language_majority": "de"}
+    ]
+  },
+  "meta": {"ms": 2}
+}
+```
+
+### 4.7 `file.read@1.0`
+
+- **Purpose**: Fetch a single chunk by CID, or a whole blob via streaming chunks.
+- **Trust**: member
+- **Stream**: yes (chunk frames)
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input":  {"cid": "blake3:..."}            // either a chunk CID or a blob manifest CID
+}
+```
+
+#### Response (single chunk, non-stream)
+
+If `cid` resolves to a chunk:
+
+```json
+{
+  "output": {
+    "cid": "blake3:...",
+    "size_bytes": 262144,
+    "data_b64": "..."                        // chunk bytes, base64
+  },
+  "meta": {"ms": 5}
+}
+```
+
+#### Stream frames (manifest CID, multi-chunk)
+
+If `cid` resolves to a blob manifest:
+
+```
+event: manifest
+data: {"cid":"blake3:...","size_bytes":4824711,"chunk_size_bytes":262144,"chunks":[{"i":0,"cid":"blake3:..."}, ...]}
+
+event: chunk
+data: {"i":0,"cid":"blake3:...","size_bytes":262144,"data_b64":"..."}
+
+event: chunk
+data: {"i":1,"cid":"blake3:...","size_bytes":262144,"data_b64":"..."}
+
+event: done
+data: {"chunks":19,"ms":4218}
+```
+
+Clients verify each chunk's BLAKE3 before storing.
+
+#### Errors
+
+- `not_found` — server does not have this CID
+
+### 4.8 `file.list@1.0`
+
+#### Request
+
+```json
+{"params": {}, "input": {"prefix": "blake3:abc"}}    // prefix optional
+```
+
+#### Response
+
+```json
+{"output": {"cids": ["blake3:abc...", "blake3:abd..."]}, "meta": {"ms": 3}}
+```
+
+### 4.9 `file.advertise@1.0`
+
+- **Purpose**: Used during gossip sync; one node tells another it now holds a CID.
+- **Trust**: member
+- **Idempotency**: yes
+
+#### Request
+
+```json
+{"params": {}, "input": {"cids": ["blake3:..."]}}
+```
+
+#### Response
+
+```json
+{"output": {"recorded": 1}, "meta": {"ms": 1}}
+```
+
+### 4.10 `file.put@1.0`
+
+- **Purpose**: Offer a blob to a remote node (typically used to share an emergency PDF widely).
+- **Trust**: trusted
+- **Stream**: yes (client-stream of chunks)
+
+#### Request — initial frame
+
+```json
+{"params": {}, "input": {"manifest": {"cid":"blake3:...", "size_bytes":..., "chunks":[...]}}}
+```
+
+Server responds with a `ready` event including a list of chunks it does not yet have. Client then streams those chunks. On completion, server replies with `done`.
+
+```
+event: ready
+data: {"needed":[0,1,2,3, ...]}
+
+(client sends:)
+event: chunk
+data: {"i":0,"cid":"blake3:...","data_b64":"..."}
+
+(server:)
+event: done
+data: {"received":4,"ms":1832}
+```
+
+#### Errors
+
+- `unauthorized` — caller not trusted
+- `capacity_exceeded` — disk full or GC threshold reached
+
+### 4.11 `market.list@1.0`
+
+- **Purpose**: List current (non-expired) marketplace posts in this community.
+- **Trust**: member
+- **Idempotency**: yes (snapshot read)
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "category": "offer",                     // optional: "offer" | "request" | "info" | "emergency"
+    "tags":     ["wasser"],                  // optional
+    "since_lamport": 4000,                   // optional, for delta sync
+    "limit":    50                           // optional, default 50, max 500
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "posts": [
+      {
+        "event_id": "01HXR...",
+        "lamport":  4218,
+        "author":   "ed25519:...",
+        "category": "request",
+        "title":    "Suche Wasserkanister, 20L",
+        "body":     "...",
+        "location": {"lat": 51.5, "lng": 6.2, "label": "Issum"},
+        "tags":     ["wasser","notfall"],
+        "created_at": "2026-05-26T08:14:22Z",
+        "expires_at": "2026-05-27T08:14:22Z"
+      }
+    ],
+    "max_lamport": 4231
+  },
+  "meta": {"ms": 8}
+}
+```
+
+### 4.12 `market.post@1.0`
+
+- **Purpose**: Create a marketplace post.
+- **Trust**: member
+- **Idempotency**: yes, by `client_id` (caller-generated UUID)
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "client_id": "01HXR...",                 // required, used for dedup
+    "category":  "request",
+    "title":     "Suche Wasserkanister, 20L",
+    "body":      "Brauche bis morgen ...",
+    "location":  {"lat": 51.5, "lng": 6.2, "label": "Issum"},
+    "tags":      ["wasser","notfall"],
+    "ttl_seconds": 86400                     // optional, default 7 days, max 30 days
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {"event_id": "01HXR...", "lamport": 4218},
+  "meta": {"ms": 6}
+}
+```
+
+The post emits a `market.post.created` event (§7).
+
+### 4.13 `market.expire@1.0`
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "client_id": "01HXR...",                 // dedup
+    "event_id":  "01HXR...",                 // the original post's id
+    "reason":    "fulfilled"                 // "fulfilled" | "withdrawn" | "user_request" | "stale"
+  }
+}
+```
+
+#### Response
+
+```json
+{"output": {"event_id": "01HXS...", "lamport": 4252}, "meta": {"ms": 3}}
+```
+
+#### Errors
+
+- `unauthorized` — caller is not the original author and not a trusted moderator
+- `not_found` — original post not found
+
+### 4.14 `market.search@1.0`
+
+- **Purpose**: Semantic search across posts using embeddings.
+- **Trust**: member
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "query": "wasser notfall kanister",
+    "k": 10
+  }
+}
+```
+
+#### Response
+
+Same shape as `market.list` but ordered by semantic similarity. Each post has an additional `score` field.
+
+### 4.15 `chat.send@1.0`
+
+- **Purpose**: Send a direct message to one recipient.
+- **Trust**: member
+- **Idempotency**: yes, by `client_id`
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "client_id":  "01HXR...",
+    "recipient":  "ed25519:...",             // recipient NodeID (full form)
+    "body":       "Hi, hast du heute Strom?",
+    "attachments": [                         // optional
+      {"cid": "blake3:...", "name": "schaltplan.pdf"}
+    ]
+  }
+}
+```
+
+#### Response
+
+```json
+{"output": {"event_id": "01HXR...", "lamport": 4301, "delivered": "direct"}, "meta": {"ms": 4}}
+```
+
+`delivered` is `"direct"` if recipient is online, `"forwarded"` if held by store-and-forward, `"queued"` if no anchor is willing.
+
+### 4.16 `chat.history@1.0`
+
+- **Purpose**: Retrieve local chat history with one peer.
+- **Trust**: self only — node returns only its own conversations
+- **Idempotency**: yes
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "peer":  "ed25519:...",                  // optional; if omitted, return all peers
+    "since_lamport": 4000,
+    "limit": 200
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "messages": [
+      {
+        "event_id": "01HXR...",
+        "lamport":  4301,
+        "from":     "ed25519:...",
+        "to":       "ed25519:...",
+        "body":     "...",
+        "attachments": [],
+        "created_at": "2026-05-26T08:14:22Z",
+        "delivered_at": "2026-05-26T08:14:23Z",
+        "read_at":      "2026-05-26T08:15:00Z"
+      }
+    ]
+  },
+  "meta": {"ms": 5}
+}
+```
+
+### 4.17 `community.invite@1.0`
+
+- **Purpose**: Invite a new device into the community.
+- **Trust**: member with the `can_invite` policy bit
+- **Idempotency**: yes, by `invitee_node_id`
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "invitee_node_id": "ed25519:...",        // full pubkey
+    "display_name":    "Hannes' Tablet",
+    "initial_level":   "member",             // "member" or "trusted"
+    "expires_at":      "2026-05-27T00:00:00Z"
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "output": {
+    "invite_blob": "ed25519:<base64-url-nopad>"   // a signed, scannable invite, encoded for QR
+  },
+  "meta": {"event_id": "01HXR...", "lamport": 4310, "ms": 3}
+}
+```
+
+The invite produces a `community.member.invited` event. The invitee redeems it locally; redemption creates a `community.member.joined` event.
+
+### 4.18 `community.revoke@1.0`
+
+- **Purpose**: Remove a member. Requires 3 trusted-member signatures over the same revocation payload.
+- **Trust**: see signature requirements
+
+#### Request
+
+```json
+{
+  "params": {},
+  "input": {
+    "client_id": "01HXR...",
+    "target_node_id": "ed25519:...",
+    "reason": "compromised|inactive|policy_violation|other",
+    "co_signers": [
+      {"node_id": "ed25519:...", "signature": "ed25519:..."},
+      {"node_id": "ed25519:...", "signature": "ed25519:..."},
+      {"node_id": "ed25519:...", "signature": "ed25519:..."}
+    ]
+  }
+}
+```
+
+The co-signatures are each over the canonical-JSON of the payload excluding `co_signers` (i.e. each co-signer signs the revoke intent independently). The caller is one of the co-signers; the bus rejects with `unauthorized` if fewer than 3 distinct trusted signers are present.
+
+#### Response
+
+```json
+{"output": {"event_id": "01HXR...", "lamport": 4400}, "meta": {"ms": 7}}
+```
+
+---
+
+## 5. Wire format
+
+### 5.1 Request
+
+```http
+POST /bus/v1/call HTTP/1.1
+Host: <host>:<port>
+Content-Type: application/json
+Accept: application/json, text/event-stream
+X-HearthNet-Capability: <capability_name>
+X-HearthNet-Capability-Version: <major.minor>
+X-HearthNet-Request-Id: <trace_id_ulid>
+X-HearthNet-From: <full_node_id>
+X-HearthNet-Community: <full_community_id>
+X-HearthNet-Timestamp: <wall_clock>
+X-HearthNet-Signature: <ed25519_signature>
+
+<JSON body>
+```
+
+The signature covers the canonical JSON of:
+
+```json
+{
+  "capability": "...",
+  "version": "1.0",
+  "request_id": "...",
+  "from": "...",
+  "community": "...",
+  "timestamp": "...",
+  "body": <request body, canonicalised>
+}
+```
+
+Servers verify by reconstructing this object and checking the signature against the caller's pubkey (derived from `X-HearthNet-From`).
+
+### 5.2 Response — non-stream
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-HearthNet-Request-Id: <trace_id>
+X-HearthNet-From: <server_node_id>
+X-HearthNet-Timestamp: <wall_clock>
+X-HearthNet-Signature: <ed25519 over response>
+
+<JSON body>
+```
+
+Servers SHOULD sign responses. Clients MAY ignore the signature for non-mutating capabilities. For all `*.post`, `*.invite`, `*.revoke`, `*.ingest`, `*.expire`, `chat.send`, signature verification is mandatory.
+
+### 5.3 Response — stream
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+X-HearthNet-Request-Id: <trace_id>
+X-HearthNet-From: <server_node_id>
+
+event: <event_name>
+data: <JSON, single line>
+
+event: <event_name>
+data: <JSON>
+...
+```
+
+Frame events:
+
+- `token`, `tool_call_delta`, `chunk`, `manifest`, `ready` — capability-specific
+- `progress` — `data: {"current": N, "total": M, "stage": "..."}` (any capability)
+- `ack` — `data: {"upto": N}` (client → server backpressure)
+- `error` — terminal error frame, replaces `done`
+- `done` — terminal success frame
+
+Every stream ends with exactly one of `done` or `error`. After that the connection closes.
+
+### 5.4 Error response
+
+```http
+HTTP/1.1 <status>
+Content-Type: application/json
+X-HearthNet-Request-Id: <trace_id>
+
+{
+  "error":   "<code>",
+  "message": "<human-readable, optional>",
+  "retry_after_ms": 2000,
+  "alt_capabilities": ["llm.chat@0.9"],
+  "alt_nodes": ["ed25519:..."],
+  "schema_hash_expected": "blake3:..."        // only for schema_mismatch
+}
+```
+
+### 5.5 Status code mapping
+
+| Status | Error codes |
+|--------|-------------|
+| 200 | (success) |
+| 400 | `bad_request`, `schema_mismatch` |
+| 401 | `invalid_signature`, `unauthorized` |
+| 403 | `revoked` |
+| 404 | `not_found` |
+| 408 | `timeout` |
+| 410 | `expired` |
+| 429 | `rate_limited`, `capacity_exceeded` |
+| 500 | `internal_error` |
+| 501 | `not_implemented` |
+| 503 | `partition` |
+
+For streams, an `error` frame replaces these; the HTTP status is 200 because the stream was accepted.
+
+---
+
+## 6. Manifests
+
+### 6.1 Node manifest
+
+```json
+{
+  "version": 1,
+  "contract_version": "1.0",
+  "node_id": "ed25519:<full_pubkey>",
+  "display_name": "garage-pc",
+  "community_id": "ed25519:<full_pubkey>",
+  "profile": "anchor",
+  "endpoints": [
+    {"transport": "https", "host": "192.168.188.25", "port": 7080}
+  ],
+  "hardware": {
+    "gpu":           "RTX 5090",
+    "vram_gb":       32,
+    "ram_gb":        128,
+    "cpu_cores":     24,
+    "disk_free_gb":  4000
+  },
+  "capabilities": [
+    {
+      "name":         "llm.chat",
+      "version":      "1.0",
+      "stability":    "stable",
+      "schema_hash":  "blake3:...",
+      "params":       {"model": "qwen2.5-7b-instruct", "quant": "q4_k_m", "ctx": 8192},
+      "max_concurrent": 4
+    }
+  ],
+  "uptime_seconds": 43210,
+  "load": {"cpu": 0.12, "vram_used_gb": 6.4, "in_flight_total": 0},
+  "issued_at":  "2026-05-26T08:14:22Z",
+  "expires_at": "2026-05-26T08:14:52Z",
+  "signature":  "ed25519:..."
+}
+```
+
+#### Rules
+
+- `expires_at - issued_at == 30 s` exactly
+- Re-issued every `MANIFEST_REPUBLISH_INTERVAL_SECONDS` (20s)
+- Signed by the node's device key
+- Stale manifests (past `expires_at`) are rejected with `expired`
+- Verifying nodes pin the first-seen public key per `node_id`; a later manifest with a different key for the same `node_id` is rejected with `invalid_signature`
+
+### 6.2 Community manifest
+
+```json
+{
+  "version": 1,
+  "community_id": "ed25519:<root_pubkey>",
+  "name": "Niederrhein Demo",
+  "root_key": "ed25519:<root_pubkey>",
+  "created_at": "2026-05-26T08:00:00Z",
+  "lamport_at_creation": 0,
+  "policy": {
+    "min_signatures_to_invite": 1,
+    "min_signatures_to_demote": 3,
+    "min_signatures_to_revoke": 3,
+    "capability_token_ttl_seconds": 86400,
+    "federation_enabled": true,
+    "default_member_can_invite": true
+  },
+  "members": [
+    {
+      "node_id":   "ed25519:...",
+      "level":     "anchor",
+      "added_at":  "2026-05-26T08:00:00Z",
+      "added_by":  "ed25519:..."
+    }
+  ],
+  "revoked": [
+    {"node_id": "ed25519:...", "revoked_at": "..."}
+  ],
+  "head_lamport": 4218,
+  "signature": "ed25519:..."
+}
+```
+
+The community manifest is **derived** from the event log. It is the materialised view at `head_lamport`. It is signed by either the root key (initial creation) or any anchor (subsequent regeneration). Other nodes verify regenerations by replaying events from the previous head.
+
+---
+
+## 7. Events (the community log)
+
+### 7.1 Common event envelope
+
+```json
+{
+  "schema_version": 1,
+  "event_id":       "01HXR...",              // ULID
+  "lamport":        4218,
+  "wall_clock":     "2026-05-26T08:14:22Z",
+  "community_id":   "ed25519:...",
+  "author":         "ed25519:...",
+  "event_type":     "market.post.created",
+  "data":           { /* type-specific */ },
+  "signature":      "ed25519:..."            // over canonical JSON of all above
+}
+```
+
+### 7.2 Canonical event types
+
+For each: `data` schema, who may produce, who consumes.
+
+#### `community.created`
+
+```json
+{
+  "name": "Niederrhein Demo",
+  "founder_node_id": "ed25519:...",
+  "policy": { /* full policy as in community manifest */ }
+}
+```
+
+Producer: founder, exactly once at community birth.
+Consumer: all.
+
+#### `community.member.invited`
+
+```json
+{
+  "invitee_node_id": "ed25519:...",
+  "display_name":    "Hannes' Tablet",
+  "initial_level":   "member",
+  "expires_at":      "2026-05-27T00:00:00Z"
+}
+```
+
+Producer: any member with `can_invite`.
+Consumer: all.
+
+#### `community.member.joined`
+
+```json
+{
+  "invite_event_id": "01HXR...",
+  "node_manifest":   { /* full manifest at join time */ }
+}
+```
+
+Producer: the invitee, on first connection.
+Consumer: all.
+
+#### `community.member.revoked`
+
+```json
+{
+  "target_node_id": "ed25519:...",
+  "reason":         "compromised",
+  "co_signers":     [{"node_id":"...", "signature":"..."}, ...]
+}
+```
+
+Producer: any trusted member who has gathered 3 co-signatures.
+Consumer: all.
+
+#### `community.member.promoted` / `community.member.demoted`
+
+```json
+{
+  "target_node_id": "ed25519:...",
+  "new_level":      "trusted",
+  "co_signers":     [...]
+}
+```
+
+Producer: trusted member with required signatures (1 promote, 3 demote).
+Consumer: all.
+
+#### `community.policy.updated`
+
+```json
+{
+  "policy": { /* new policy */ }
+}
+```
+
+Producer: root key only.
+Consumer: all.
+
+#### `node.manifest.updated`
+
+```json
+{
+  "manifest": { /* full node manifest */ }
+}
+```
+
+Producer: each node, advisory; not strictly required in the log but useful for replay-based audit.
+Consumer: all.
+
+#### `market.post.created`
+
+```json
+{
+  "client_id": "...",
+  "category": "request",
+  "title":    "...",
+  "body":     "...",
+  "location": {"lat":..., "lng":..., "label":"..."},
+  "tags":     ["..."],
+  "ttl_seconds": 86400
+}
+```
+
+Producer: any member.
+Consumer: all.
+
+#### `market.post.updated`
+
+```json
+{
+  "client_id": "...",
+  "target_event_id": "01HXR...",
+  "fields": {"body": "..."}
+}
+```
+
+Producer: original author only.
+Consumer: all.
+
+#### `market.post.expired`
+
+```json
+{
+  "client_id": "...",
+  "target_event_id": "01HXR...",
+  "reason": "fulfilled|withdrawn|user_request|stale"
+}
+```
+
+Producer: original author OR any trusted moderator (with `reason != "user_request"`).
+Consumer: all.
+
+#### `chat.message.sent`
+
+```json
+{
+  "client_id": "...",
+  "recipient": "ed25519:...",
+  "body":      "...",
+  "attachments": [{"cid":"...","name":"..."}]
+}
+```
+
+Producer: sender.
+Consumer: sender + recipient (others may see envelope only, but `data` MAY be encrypted in Phase 2).
+
+#### `chat.message.delivered`
+
+```json
+{"target_event_id": "01HXR...", "delivered_at": "..."}
+```
+
+Producer: recipient.
+Consumer: sender.
+
+#### `chat.message.read`
+
+```json
+{"target_event_id": "01HXR...", "read_at": "..."}
+```
+
+Producer: recipient (optional, may be disabled by user).
+Consumer: sender.
+
+#### `file.cid.advertised`
+
+```json
+{"cid": "blake3:...", "sizes_bytes": 4824711}
+```
+
+Producer: holder.
+Consumer: all (used for fan-out file discovery).
+
+#### `file.cid.unpinned`
+
+```json
+{"cid": "blake3:..."}
+```
+
+Producer: holder.
+Consumer: all.
+
+#### `rag.document.ingested`
+
+```json
+{
+  "corpus":   "niederrhein-emergency",
+  "doc_cid":  "blake3:...",
+  "title":    "...",
+  "language": "de",
+  "chunks":   87
+}
+```
+
+Producer: ingester.
+Consumer: all members.
+
+#### `federation.peer.added` / `federation.peer.removed` (Phase 2)
+
+Reserved.
+
+### 7.3 Lamport rules
+
+Every node maintains a per-community Lamport counter.
+
+```
+on send:    lamport_send = ++lamport
+on receive: lamport = max(lamport, received.lamport) + 1
+```
+
+### 7.4 Ordering
+
+- Replay order: by `lamport` ascending, tie-broken by `event_id` ascending (ULIDs sort by time naturally)
+- Conflict resolution: last-writer-wins by Lamport; `community.member.revoked` is checked first when replaying actions by the revoked party
+
+### 7.5 Snapshots
+
+A snapshot at Lamport L is:
+
+```json
+{
+  "schema_version": 1,
+  "community_id": "ed25519:...",
+  "lamport": <L>,
+  "wall_clock": "...",
+  "state": { /* materialised views: community manifest, marketplace_current, ... */ },
+  "covers_events_up_to": <L>,
+  "signature": "ed25519:..."
+}
+```
+
+Signed by any anchor. Other nodes verify the signature and the membership of the signer.
+
+### 7.6 Sync protocol (gossip)
+
+Two nodes meeting:
+
+1. A → B: `GET /sync/v1/heads` → returns `{community_id: max_lamport}` per known community
+2. A computes delta; for each community where A is ahead, A → B: `POST /sync/v1/events` with all events `lamport > B.head`
+3. B verifies signatures, applies, returns `{accepted, rejected, new_head_lamport}`
+4. Roles reverse; B sends what A is missing
+
+This is also covered in [X02 §6](cross-cutting/X02-events.md).
+
+---
+
+## 8. Pub-sub topics
+
+Topics are used for live notifications between connected peers (in addition to durable events in the log).
+
+| Topic | Payload | Producer | Subscriber |
+|-------|---------|----------|------------|
+| `community.member.added` | event envelope | any member | all |
+| `community.member.revoked` | event envelope | trusted | all |
+| `node.manifest.updated` | manifest | each node | all |
+| `marketplace.post.created` | event envelope | any member | all |
+| `marketplace.post.expired` | event envelope | author or trusted | all |
+| `chat.message.<recipient>` | event envelope | sender | recipient |
+| `emergency.mode.changed` | `{online: bool, since: "..."}` | each node locally | local UI only — never on the wire |
+| `federation.peer.added` | event envelope | anchor | all anchors |
+| `capability.registered` | descriptor | local bus | local UI only |
+| `capability.deregistered` | name+version | local bus | local UI only |
+
+Transport: HTTP long-polling for MVP (`GET /pubsub/v1/subscribe?topic=...`), WebSocket in Phase 2.
+
+---
+
+## 9. Error codes (complete reference)
+
+| Code | When | Retry? |
+|------|------|--------|
+| `bad_request` | Malformed payload | no, fix and resend |
+| `schema_mismatch` | Schema hash differs | no, upgrade and resend |
+| `invalid_signature` | Signature verification failed | no |
+| `unauthorized` | Caller lacks required trust level | no |
+| `revoked` | Caller's NodeID is revoked | no |
+| `expired` | Manifest or token past `expires_at` | no, re-issue and resend |
+| `not_found` | Resource doesn't exist | no |
+| `not_implemented` | Capability declared but unimplemented | no |
+| `timeout` | Exceeded server-side deadline | yes, with backoff |
+| `partition` | Peer unreachable | yes, with backoff |
+| `capacity_exceeded` | Concurrent limit reached | yes, honour `retry_after_ms` |
+| `rate_limited` | Rate budget exceeded | yes, honour `retry_after_ms` |
+| `internal_error` | Server-side bug or crash | maybe, idempotent capabilities only |
+
+---
+
+## 10. Signing reference
+
+```python
+# canonical_json(obj) → bytes  (sorted keys, no whitespace, no trailing zeros on floats)
+
+def sign(payload: dict, sk: SigningKey) -> dict:
+    p = {k: v for k, v in payload.items() if k != "signature"}
+    msg = canonical_json(p)
+    sig = sk.sign(msg).signature
+    p["signature"] = f"ed25519:{base64url_nopad(sig)}"
+    return p
+
+def verify(payload: dict, vk: VerifyKey) -> bool:
+    sig_field = payload.get("signature", "")
+    if not sig_field.startswith("ed25519:"):
+        return False
+    sig = base64url_nopad_decode(sig_field[len("ed25519:"):])
+    p = {k: v for k, v in payload.items() if k != "signature"}
+    msg = canonical_json(p)
+    try:
+        vk.verify(msg, sig)
+        return True
+    except BadSignature:
+        return False
+```
+
+For HTTP requests, the signed payload is the synthetic envelope of §5.1, not the raw body.
+
+---
+
+## 11. Schema hash computation
+
+For a capability descriptor, the schema hash is BLAKE3 of the canonical JSON of:
+
+```json
+{
+  "name":            "<capability_name>",
+  "version":         "<major.minor>",
+  "request_schema":  <JSON Schema>,
+  "response_schema": <JSON Schema or null>,
+  "stream_schema":   <JSON Schema or null>
+}
+```
+
+If two implementations want to interoperate without reading docs, they MUST produce the same schema hash. Treat schemas as data; never use language-specific Pydantic features in the schema (extra `discriminator`, etc.) without normalising first.
+
+---
+
+## 12. Open questions tracked here
+
+1. **Encrypted chat (Phase 2)** — when added, `chat.message.sent.data.body` becomes ciphertext; envelope (`event_type`, `author`, `recipient`, `lamport`) stays in cleartext. The signature still covers the ciphertext.
+2. **Multi-party group chat** — out of scope this release. Reserved event type `chat.group.*`.
+3. **Federation manifest** — when added, will look like a community manifest with `peers: []` field. Reserved.
+4. **WebSocket upgrade** — when added, the `/bus/v1/call` endpoint will accept an `Upgrade: websocket` header; behaviour is otherwise the same.
+5. **Tool calls in `llm.chat`** — declared as Phase 2; the stream frame `tool_call_delta` is reserved.
+
+---
+
+*End of HearthNet Capability Contract v1.0.*

docs/GLOSSARY.md

@@ -0,0 +1,141 @@
+# HearthNet Glossary
+
+Canonical names. Every spec uses these. Do not introduce synonyms.
+
+---
+
+## Identifiers
+
+| Term | Form | Notes |
+|------|------|-------|
+| **NodeID** | `ed25519:XXXX-XXXX-XXXX-XXXX` | First 8 bytes of Ed25519 public key, base32, grouped by 4 |
+| **NodeID (full)** | `ed25519:<base64-url-nopad>` of full pubkey | Used only in manifests; never displayed to users |
+| **CommunityID** | `ed25519:<...>` of community root pubkey | Same format as full NodeID |
+| **CapabilityName** | dotted lowercase: `llm.chat`, `rag.query` | Namespace allocation: see CONTRACT §3.1 |
+| **Version** | `(major, minor)` tuple — wire form `"1.0"` | Patch component does not exist on the wire |
+| **SchemaHash** | `blake3:<hex>` | BLAKE3 of canonical-JSON of capability schema |
+| **CID** | `blake3:<hex>` | Content identifier for blobs |
+| **EventID** | ULID (26 chars, monotonic, encodes wall-clock) | Globally unique per community in practice |
+| **TraceID** | ULID | Identifies one logical request across hops |
+| **Signature** | `ed25519:<base64-url-nopad>` | Always over canonical-JSON |
+| **WallClock** | RFC 3339 UTC: `2026-05-26T08:14:22Z` | Display-only; never used for ordering |
+| **Lamport** | `int >= 0` | Per-community monotonic logical counter |
+| **Topic** | dotted lowercase: `marketplace.post.created` | Pub-sub topic name |
+
+---
+
+## Concepts
+
+| Term | Definition |
+|------|------------|
+| **Anchor** | A node profile: always-on, GPU-equipped, primary capability provider |
+| **Hearth** | A node profile: mid-tier, typically a laptop, runs some services |
+| **Spark** | A node profile: thin client (Pi, mobile, browser); consumes capabilities |
+| **Bridge** | A node profile: relay-only, no inference, federates communities (Phase 2) |
+| **Profile** | One of `anchor` / `hearth` / `spark` / `bridge` — declared in node manifest |
+| **Community** | A trust root: a group of nodes sharing one root key and one event log |
+| **Federation** | Cross-community trust + capability access (Phase 2) |
+| **Capability** | A named, versioned, schema-bound RPC offered by a node |
+| **Capability descriptor** | The metadata for one capability: name, version, schema, params, guarantees |
+| **Capability entry** | The bus's local record of one remote capability: descriptor + health |
+| **Bus / capability bus** | The L3 routing component each service registers with |
+| **Service** | An L4 module that provides one or more capabilities |
+| **Node manifest** | A signed JSON document describing what a node is and offers; expires every 30s |
+| **Community manifest** | A signed JSON document describing community membership and policy |
+| **Event** | A signed, Lamport-stamped record in the community's append-only log |
+| **Event log** | The community's full ordered history; one SQLite db per node |
+| **Snapshot** | A signed materialised state at some Lamport |
+| **Materialised view** | A derived index built by replaying events (member list, marketplace, etc.) |
+| **Blob** | An immutable byte string identified by its CID |
+| **Chunk** | A 256KB slice of a blob, itself CID-addressed |
+| **TrustLevel** | One of `unknown` / `member` / `trusted` / `anchor` |
+| **Stability** | One of `experimental` / `beta` / `stable` for a capability |
+| **Emergency mode** | UI + behavioural state when the internet-detector reports offline |
+
+---
+
+## Errors (closed set — see CONTRACT §9)
+
+| Code | Meaning |
+|------|---------|
+| `not_found` | No node offers the requested capability, or the requested resource is gone |
+| `capacity_exceeded` | Node is at declared `max_concurrent`; retry with backoff or pick another |
+| `schema_mismatch` | Request body does not match the declared schema for this capability/version |
+| `unauthorized` | Caller is not a community member, or lacks the required trust level |
+| `revoked` | Caller's NodeID is in the revoked set of the community |
+| `internal_error` | Service crashed handling this request |
+| `not_implemented` | Capability is declared but the handler is a stub |
+| `timeout` | Operation exceeded its declared deadline |
+| `partition` | Remote node is presumed unreachable (mDNS lost, repeated failures) |
+| `invalid_signature` | Signature verification failed on a manifest, event, or request |
+| `expired` | Manifest, token, or event TTL has passed |
+| `rate_limited` | Caller exceeded the per-peer-per-capability rate budget |
+| `bad_request` | Malformed JSON, missing required field, etc. |
+
+---
+
+## File paths (XDG-style; resolved via `platformdirs`)
+
+| Path | Purpose |
+|------|---------|
+| `<DATA>/keys/device.ed25519` | Private key, 0600 |
+| `<DATA>/keys/device.pub` | Public key |
+| `<DATA>/communities/<community_id>/manifest.json` | Latest signed community manifest |
+| `<DATA>/communities/<community_id>/events.sqlite` | Event log |
+| `<DATA>/communities/<community_id>/snapshots/<lamport>.bin` | Signed snapshots |
+| `<DATA>/blobs/<aa>/<bb...>` | CID-addressed blobs |
+| `<CONFIG>/config.toml` | User configuration |
+| `<CACHE>/embeddings/<corpus>` | Vector store on-disk files |
+| `<LOG>/<date>.log` | Daily rotating logs |
+
+`<DATA>` = `platformdirs.user_data_dir("hearthnet")` (Linux: `~/.local/share/hearthnet/`).
+
+---
+
+## Default ports
+
+| Port | Purpose | Configurable? |
+|------|---------|---------------|
+| 7080 | Bus HTTP server | yes (`config.transport.port`) |
+| 7860 | Gradio UI | yes (`config.ui.port`) |
+| 42424 | UDP discovery multicast | no (interop) |
+| 5353 | mDNS | no (system) |
+
+---
+
+## Defaults (numeric — central reference)
+
+| Constant | Value | Where defined |
+|----------|-------|---------------|
+| `MANIFEST_TTL_SECONDS` | 30 | M01 |
+| `MANIFEST_REPUBLISH_INTERVAL_SECONDS` | 20 | M01 |
+| `DISCOVERY_UDP_INTERVAL_SECONDS` | 5 (active) / 30 (stable) | M02 |
+| `EMERGENCY_PROBE_INTERVAL_SECONDS` | 10 (online) / 2 (offline) | M09 |
+| `EMERGENCY_PROBE_TIMEOUT_SECONDS` | 2 | M09 |
+| `EMERGENCY_TRANSITION_DEBOUNCE_SECONDS` | 30 | M09 |
+| `CONNECTION_IDLE_SECONDS` | 60 | X01 |
+| `RECONNECT_BACKOFF_CAP_SECONDS` | 30 | X01 |
+| `STREAM_WINDOW_FRAMES` | 16 | X01 |
+| `STREAM_ACK_INTERVAL_FRAMES` | 8 | X01 |
+| `STREAM_ACK_TIMEOUT_SECONDS` | 5 | X01 |
+| `RPC_DEFAULT_TIMEOUT_SECONDS` | 30 | X01 |
+| `LLM_GENERATION_DEFAULT_TIMEOUT_SECONDS` | 120 | M04 |
+| `CHUNK_SIZE_BYTES` | 262144 (256 KiB) | M07 |
+| `BLOB_GC_DISK_THRESHOLD` | 0.80 | M07 |
+| `RAG_CHUNK_TOKENS` | 1000 | M05 |
+| `RAG_CHUNK_OVERLAP_TOKENS` | 200 | M05 |
+| `RAG_DEFAULT_K` | 5 | M05 |
+| `RAG_MAX_K` | 20 | M05 |
+| `HEALTH_WINDOW_CALLS` | 100 | M03 |
+| `HEALTH_QUARANTINE_THRESHOLD` | 0.5 | M03 |
+| `HEALTH_QUARANTINE_SECONDS` | 60 | M03 |
+| `RATE_LIMIT_SOFT_RPS_PER_CAP` | 10 | X01 |
+| `RATE_LIMIT_HARD_RPS_PER_CAP` | 100 | X01 |
+| `RATE_LIMIT_SOFT_RPS_TOTAL` | 100 | X01 |
+| `RATE_LIMIT_HARD_RPS_TOTAL` | 1000 | X01 |
+| `EVENT_LOG_RETENTION_DAYS` | 30 | X02 |
+| `SNAPSHOT_LAG_LAMPORT` | 1000 | X02 |
+| `TRACE_RING_BUFFER` | 10000 | X03 |
+| `LOG_RETENTION_DAYS` | 14 | X03 |
+
+Implementation hint: put these in `hearthnet/constants.py` and import everywhere. Do not hardcode in modules.

docs/M01-identity.md

@@ -0,0 +1,372 @@
+# M01 — Identity & Manifests
+
+**Spec version:** v1.0
+**Depends on:** X04 (config), PyNaCl, cryptography (for TLS cert generation)
+**Depended on by:** X02 (events), X01 (transport), M02 (discovery), M03 (bus), and every service that signs anything
+
+---
+
+## 1. Responsibility
+
+- Cryptographic identity (Ed25519 keypair) for one device
+- Signing and verification of arbitrary canonical-JSON payloads
+- Creation, signing, verification of **node manifests**
+- Creation, signing, verification of **community manifests**
+- Canonical JSON encoding (the one that signatures are computed over)
+- TLS certificate generation (self-signed, pinned to the device key on first contact)
+- Optional: capability tokens (Phase 2)
+
+This module owns no event log — that is X02. It owns no networking — that is X01. It owns only crypto and document formats.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/identity/
+├── __init__.py         # re-exports
+├── keys.py             # KeyPair, canonical_json, sign, verify, TLS cert
+├── manifest.py         # NodeManifest, CommunityManifest, builders, verifiers
+└── tokens.py           # Phase 2; stubs only in MVP
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `keys.py`
+
+```python
+# hearthnet/identity/keys.py
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+NodeID    = str  # "ed25519:XXXX-XXXX-XXXX-XXXX" (short) or "ed25519:<base64-url-nopad>" (full)
+Signature = str  # "ed25519:<base64-url-nopad>"
+
+@dataclass(frozen=True)
+class KeyPair:
+    """Wraps Ed25519 signing key + verify key plus their string forms."""
+    signing_key:    nacl.signing.SigningKey
+    verify_key:     nacl.signing.VerifyKey
+    node_id_full:   str          # "ed25519:<base64-url-nopad of 32 bytes>"
+    node_id_short:  str          # "ed25519:XXXX-XXXX-XXXX-XXXX" (8 bytes, base32, 4-grouped)
+
+    def sign(self, payload: dict) -> dict:
+        """Return a new dict equal to payload with signature field added."""
+
+    def sign_bytes(self, data: bytes) -> Signature:
+        """Sign raw bytes; return 'ed25519:<base64-url-nopad>'."""
+
+# --- generation / loading ---
+
+def generate() -> KeyPair:
+    """Create a fresh Ed25519 keypair (uses os.urandom)."""
+
+def load(keys_dir: Path) -> KeyPair:
+    """Load device.ed25519 + device.pub from keys_dir.
+       Raises IdentityError('keys_missing') if not present,
+       IdentityError('keys_invalid') if malformed.
+       Validates permissions are 0600 on Unix."""
+
+def load_or_generate(keys_dir: Path) -> KeyPair:
+    """Load if present; otherwise generate and persist."""
+
+def save(kp: KeyPair, keys_dir: Path) -> None:
+    """Persist signing key as device.ed25519 (0600) and verify key as device.pub."""
+
+# --- public-key handling ---
+
+def short_node_id(verify_key_bytes: bytes) -> str:
+    """First 8 bytes base32, grouped: 'ed25519:XXXX-XXXX-XXXX-XXXX'."""
+
+def full_node_id(verify_key_bytes: bytes) -> str:
+    """All 32 bytes, base64-url no pad, prefixed: 'ed25519:<b64>'."""
+
+def parse_node_id(node_id: str) -> bytes:
+    """Decode the full form back to 32 bytes. Short form raises ValueError."""
+
+def verify_key_from_full(node_id_full: str) -> nacl.signing.VerifyKey:
+    """Convenience: parse and wrap."""
+
+# --- canonical JSON ---
+
+def canonical_json(obj: Any) -> bytes:
+    """Sorted keys, no whitespace, no trailing zeros on numbers, UTF-8.
+       Used everywhere a signature is computed."""
+
+# --- signing / verification ---
+
+def sign_payload(payload: dict, kp: KeyPair) -> dict:
+    """Add a 'signature' field over canonical_json(payload \\ {signature})."""
+
+def verify_payload(payload: dict, vk: nacl.signing.VerifyKey) -> bool:
+    """True iff the 'signature' field validates over canonical_json(payload \\ {signature})."""
+
+def verify_payload_with_node_id(payload: dict, expected_node_id_full: str) -> bool:
+    """Convenience: derive verify key from node_id and call verify_payload."""
+
+# --- TLS ---
+
+def generate_self_signed_cert(kp: KeyPair, host: str = "0.0.0.0") -> tuple[bytes, bytes]:
+    """Generate an X.509 self-signed cert+key for TLS. The CN includes the short node id.
+       Returns (cert_pem, key_pem). The cert is rotated when the device key changes (i.e. never)."""
+
+class IdentityError(Exception):
+    """code in {'keys_missing','keys_invalid','keys_permissions','bad_node_id','sign_failed','verify_failed'}"""
+    code: str
+```
+
+### 3.2 `manifest.py`
+
+```python
+# hearthnet/identity/manifest.py
+from dataclasses import dataclass, field
+from typing import Any
+from datetime import datetime, timezone, timedelta
+
+# ---- types ----
+
+@dataclass(frozen=True)
+class Endpoint:
+    transport: str                  # "https"
+    host:      str
+    port:      int
+
+@dataclass(frozen=True)
+class HardwareSpec:
+    gpu:           str | None
+    vram_gb:       float
+    ram_gb:        float
+    cpu_cores:     int
+    disk_free_gb:  float
+
+@dataclass(frozen=True)
+class CapabilitySpec:
+    """As it appears INSIDE a node manifest (subset of the full descriptor in M03)."""
+    name:             str
+    version:          str           # "1.0"
+    stability:        str           # "stable" | "beta" | "experimental"
+    schema_hash:      str           # "blake3:..."
+    params:           dict[str, Any]
+    max_concurrent:   int
+
+@dataclass(frozen=True)
+class NodeManifest:
+    version:           int          # always 1 for this contract version
+    contract_version:  str          # "1.0"
+    node_id:           str          # full form
+    display_name:      str
+    community_id:      str
+    profile:           str          # "anchor" | "hearth" | "spark" | "bridge"
+    endpoints:         list[Endpoint]
+    hardware:          HardwareSpec
+    capabilities:      list[CapabilitySpec]
+    uptime_seconds:    int
+    load:              dict[str, Any]
+    issued_at:         str          # RFC 3339
+    expires_at:        str          # RFC 3339
+    signature:         str
+
+    def as_dict(self) -> dict: ...
+    def is_expired(self, now: datetime | None = None) -> bool: ...
+
+# ---- node manifest builder & verifier ----
+
+def build_node_manifest(
+    kp: KeyPair,
+    community_id: str,
+    display_name: str,
+    profile: str,
+    endpoints: list[Endpoint],
+    hardware: HardwareSpec,
+    capabilities: list[CapabilitySpec],
+    uptime_seconds: int,
+    load: dict[str, Any],
+) -> NodeManifest:
+    """Build and sign a fresh node manifest. issued_at = now,
+       expires_at = now + MANIFEST_TTL_SECONDS."""
+
+def parse_node_manifest(blob: bytes | dict) -> NodeManifest:
+    """Parse JSON bytes or dict into a typed NodeManifest. Does NOT verify signature."""
+
+def verify_node_manifest(manifest: NodeManifest, *, now: datetime | None = None) -> None:
+    """Verify signature + expiry. Raises IdentityError on failure:
+       'invalid_signature' | 'expired' | 'bad_manifest' (malformed structure)."""
+
+# ---- community manifest ----
+
+@dataclass(frozen=True)
+class CommunityPolicy:
+    min_signatures_to_invite:   int
+    min_signatures_to_demote:   int
+    min_signatures_to_revoke:   int
+    capability_token_ttl_seconds: int
+    federation_enabled:         bool
+    default_member_can_invite:  bool
+
+@dataclass(frozen=True)
+class CommunityMember:
+    node_id:   str
+    level:     str         # "anchor" | "trusted" | "member"
+    added_at:  str
+    added_by:  str
+
+@dataclass(frozen=True)
+class RevokedEntry:
+    node_id:    str
+    revoked_at: str
+
+@dataclass(frozen=True)
+class CommunityManifest:
+    version:               int
+    community_id:          str
+    name:                  str
+    root_key:              str
+    created_at:            str
+    lamport_at_creation:   int
+    policy:                CommunityPolicy
+    members:               list[CommunityMember]
+    revoked:               list[RevokedEntry]
+    head_lamport:          int
+    signature:             str
+
+    def is_member(self, node_id: str) -> bool: ...
+    def level_of(self, node_id: str) -> str | None: ...
+    def is_revoked(self, node_id: str) -> bool: ...
+
+def build_community_manifest(
+    root_kp: KeyPair,
+    name: str,
+    policy: CommunityPolicy,
+) -> CommunityManifest:
+    """Build and sign the genesis community manifest. lamport_at_creation = 0, head_lamport = 0,
+       members = [root as 'anchor'], revoked = []."""
+
+def regenerate_community_manifest_from_state(
+    materialised_state: dict,
+    signing_kp: KeyPair,
+) -> CommunityManifest:
+    """Given a materialised view from the event log, produce a fresh signed manifest.
+       Signing key may be any anchor's key, not just root."""
+
+def parse_community_manifest(blob: bytes | dict) -> CommunityManifest: ...
+def verify_community_manifest(cm: CommunityManifest) -> None: ...
+```
+
+### 3.3 `tokens.py` (Phase 2 — stubs only in MVP)
+
+```python
+# hearthnet/identity/tokens.py
+@dataclass(frozen=True)
+class CapabilityToken:
+    issuer:     str             # NodeID issuing the token
+    subject:    str             # NodeID who may use it
+    capability: str             # "rag.query"
+    issued_at:  str
+    expires_at: str
+    nonce:      str             # ULID
+    signature:  str
+
+def issue_token(...) -> CapabilityToken: ...     # Phase 2
+def verify_token(token: CapabilityToken, expected_issuer: str) -> None: ...  # Phase 2
+```
+
+---
+
+## 4. On-disk format
+
+```
+<DATA>/keys/
+├── device.ed25519     # raw 32-byte signing key, no header, 0600
+└── device.pub         # raw 32-byte verify key, 0644
+```
+
+Single-key design (no rotation, no chain). Rationale: a community member's key is their identity; rotation creates a new identity. If a key is compromised, the right action is to revoke that NodeID and the user re-onboards with a new key.
+
+---
+
+## 5. Behaviour
+
+### 5.1 First-run flow
+
+```
+load_or_generate(keys_dir) →
+  if device.ed25519 exists:
+    read, validate permissions, parse → KeyPair
+  else:
+    generate → save → KeyPair
+```
+
+### 5.2 Manifest TTL and republish
+
+The node orchestrator (`node.py`) republishes manifest every `MANIFEST_REPUBLISH_INTERVAL_SECONDS` (20s). Receivers consider any manifest with `expires_at < now` as `expired` and drop it.
+
+### 5.3 Verification budget
+
+Verification is cheap (Ed25519 is fast), but at scale (1000 events/sec) it can add up. Verifying nodes cache `(payload_hash, sig, result)` for 60 seconds to avoid re-verifying identical bytes.
+
+### 5.4 Pinned keys
+
+The first time we see a NodeID's verify key, we pin it in memory. A subsequent manifest with the same NodeID but a different verify key is rejected with `invalid_signature` and logged at `warning`. This is TOFU (trust-on-first-use) and is acceptable inside a community where invites carry the verify key.
+
+---
+
+## 6. Errors
+
+All errors raise `IdentityError` with a `code` in: `keys_missing`, `keys_invalid`, `keys_permissions`, `bad_node_id`, `sign_failed`, `verify_failed`, `bad_manifest`, `expired`, `invalid_signature`.
+
+These codes map cleanly onto the wire error codes in [CONTRACT §9](../CAPABILITY_CONTRACT.md).
+
+---
+
+## 7. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.identity.keys_dir       # where keys live
+config.identity.auto_generate  # default True
+```
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_keypair_roundtrip` — save / load returns equal keys
+- `test_short_node_id_format` — matches `ed25519:[A-Z2-7]{4}(-[A-Z2-7]{4}){3}`
+- `test_canonical_json_is_stable` — sort + no-whitespace is deterministic
+- `test_canonical_json_numbers` — `1.0`, `1.00`, `1` all canonicalise to `1`
+- `test_sign_verify_roundtrip` — random payloads
+- `test_verify_fails_on_modified_field` — flip one byte, verify returns False
+- `test_node_manifest_expiry` — exact TTL boundary behaviour
+- `test_community_manifest_genesis` — root key is sole anchor
+- `test_tls_cert_includes_short_node_id` — CN match
+
+### Integration
+- `test_manifest_round_trip_over_http` — server emits, client receives, parses, verifies
+- `test_tofu_key_pinning` — second different key for same NodeID is rejected
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| Wire signing rules | [CONTRACT §1.3, §5.1](../CAPABILITY_CONTRACT.md) |
+| Canonical JSON | [CONTRACT §1.2](../CAPABILITY_CONTRACT.md) |
+| Node manifest schema | [CONTRACT §6.1](../CAPABILITY_CONTRACT.md) |
+| Community manifest schema | [CONTRACT §6.2](../CAPABILITY_CONTRACT.md) |
+| Used by event signing | [X02 §3](../cross-cutting/X02-events.md) |
+| Used by transport TLS pinning | [X01 §4](../cross-cutting/X01-transport.md) |
+| Used by bus per-request verification | [M03 §5.6](M03-bus.md) |
+
+---
+
+## 10. Open questions
+
+1. **Mobile clients store keys in `localStorage`** — not great. Phase 2: WebCrypto + IndexedDB.
+2. **Key rotation** — currently impossible without identity change. Phase 3 may add a "linked-keys" event.
+3. **HSM / Yubikey support** — out of scope; possible Phase 3.

docs/M02-discovery.md

@@ -0,0 +1,264 @@
+# 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) |

docs/M03-bus.md

@@ -0,0 +1,632 @@
+# M03 — Capability Bus
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity), X01 (transport, for outbound calls), X03 (observability), X04 (config), M02 (discovery, for peer events)
+**Depended on by:** every service (M04, M05, M06, M07, M10, M11), M08 (UI calls capabilities via bus), M09 (registers nothing but reads peer state via bus), M12 (CLI inspects bus state)
+
+This is **the** integration point. Re-read [00-OVERVIEW §2](../00-OVERVIEW.md) before changing this file.
+
+---
+
+## 1. Responsibility
+
+- Maintain a registry of **capabilities**: local (offered by us) and remote (offered by other nodes)
+- Validate every call against a JSON schema declared by the capability descriptor
+- Route every call to the best provider via a scoring algorithm
+- Track per-(node, capability) health and quarantine misbehaving providers
+- Enforce per-capability concurrency limits and per-peer rate budgets (delegating to X01)
+- Emit structured trace events for every call (via X03)
+- Provide sticky routing for multi-turn capabilities (chat)
+
+What the bus does **not** do:
+- It does not move bytes (X01 does)
+- It does not persist anything (X02 does, for events)
+- It does not know any service's internals (services register themselves)
+
+---
+
+## 2. File layout
+
+```
+hearthnet/bus/
+├── __init__.py          # exports: CapabilityBus, CapabilityDescriptor, CapabilityEntry
+├── capability.py        # dataclasses: CapabilityDescriptor, CapabilityEntry, RouteRequest
+├── registry.py          # Registry: local + remote capability index
+├── router.py            # Router: scoring algorithm
+├── health.py            # HealthTracker: rolling-window per-(node, cap) stats
+├── schema.py            # SchemaValidator + schema_hash computation
+└── trace.py             # TraceHook: emit standardised trace events
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `capability.py`
+
+```python
+# hearthnet/bus/capability.py
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Callable, Awaitable
+
+CapabilityName = str                # "llm.chat"
+Version        = tuple[int, int]    # (1, 0)
+
+# --- Descriptor: the full capability spec, used at registration ---
+
+@dataclass(frozen=True)
+class CapabilityDescriptor:
+    """The complete contract for one capability offered by one service.
+       Registered exactly once per (service, capability)."""
+    name:             CapabilityName
+    version:          Version             # (1, 0)
+    stability:        str                 # "stable" | "beta" | "experimental"
+    request_schema:   dict                # JSON Schema
+    response_schema:  dict | None         # JSON Schema; None if pure stream
+    stream_schema:    dict | None         # JSON Schema for stream frames; None if non-streaming
+    params:           dict[str, Any]      # capability-instance params (e.g. {"model": "..."})
+    max_concurrent:   int                 # per-node limit
+    trust_required:   str                 # "member" | "trusted" | "anchor" | "self"
+    timeout_seconds:  int                 # default deadline for this capability
+    idempotent:       bool
+
+    @property
+    def version_str(self) -> str:
+        """E.g. '1.0'"""
+
+    def schema_hash(self) -> str:
+        """BLAKE3 over canonical-JSON of {name, version, request_schema, response_schema, stream_schema}.
+        Prefixed 'blake3:'. See CONTRACT §11."""
+
+# --- Entry: the bus's record of one capability instance ---
+
+@dataclass
+class CapabilityEntry:
+    """The bus's view of one (node, capability) pair.
+       For local capabilities, node_id == self.node_id and handler != None."""
+    node_id:           str                # full form
+    descriptor:        CapabilityDescriptor
+    is_local:          bool
+    handler:           Callable | None    # only for local entries
+    endpoint:          Endpoint | None    # only for remote entries
+    in_flight:         int = 0
+    last_seen:         float = 0.0        # monotonic seconds
+    p50_latency_ms:    float = 0.0
+    p99_latency_ms:    float = 0.0
+    success_rate:      float = 1.0        # rolling HEALTH_WINDOW_CALLS
+    quarantined_until: float = 0.0
+    sticky_sessions:   set[str] = field(default_factory=set)
+
+# --- Internal request envelope ---
+
+@dataclass(frozen=True)
+class RouteRequest:
+    """An inbound call after signature/membership check.
+       Constructed by the transport layer before being handed to the bus."""
+    capability:    CapabilityName
+    version_req:   Version             # the *requested* major+minimum minor
+    body:          dict                # the JSON body (params + input)
+    caller:        str                 # full NodeID
+    trace_id:      str
+    session_id:    str | None          # for sticky routing
+    deadline_ms:   int                 # absolute monotonic ms
+    stream:        bool                # caller-requested
+```
+
+### 3.2 `registry.py`
+
+```python
+# hearthnet/bus/registry.py
+class Registry:
+    """Holds CapabilityEntry instances keyed by (node_id, name, version).
+       Thread-safe via asyncio.Lock."""
+
+    def __init__(self, our_node_id: str): ...
+
+    # -- local registration --
+
+    def register_local(
+        self,
+        descriptor: CapabilityDescriptor,
+        handler: Callable[[RouteRequest], Awaitable[dict] | AsyncIterator[dict]],
+    ) -> None:
+        """Register a capability our process offers. Idempotent if descriptor unchanged.
+        Raises BusError('schema_invalid') if request/response schemas don't validate against JSON Schema meta-schema.
+        Raises BusError('namespace_violation') if name is outside this service's declared prefix."""
+
+    def deregister_local(self, name: CapabilityName, version: Version) -> None: ...
+
+    # -- remote sync (driven by M02 peer events + the periodic manifest fetch) --
+
+    def update_from_peer_manifest(self, peer: PeerRecord, manifest: NodeManifest) -> Diff:
+        """Compare offered capabilities to existing entries; add/remove as needed.
+           Returns a Diff describing changes."""
+
+    def remove_peer(self, node_id: str) -> int:
+        """Remove all entries for a peer. Returns count removed."""
+
+    # -- queries --
+
+    def find(
+        self,
+        name: CapabilityName,
+        version_req: Version,
+        params_filter: Callable[[dict], bool] | None = None,
+    ) -> list[CapabilityEntry]:
+        """Return all entries matching name and version compatibility.
+        See CONTRACT §2.1 for compatibility rules."""
+
+    def entry(self, node_id: str, name: CapabilityName, version: Version) -> CapabilityEntry | None: ...
+
+    def all_local(self) -> list[CapabilityEntry]: ...
+    def all(self) -> list[CapabilityEntry]: ...
+
+    # -- subscriptions --
+
+    def subscribe(self) -> AsyncIterator[RegistryEvent]:
+        """Yield 'added' / 'removed' / 'updated' events. Used by UI topology viz."""
+
+@dataclass(frozen=True)
+class Diff:
+    added:   list[CapabilityEntry]
+    removed: list[CapabilityEntry]
+    updated: list[CapabilityEntry]
+
+@dataclass(frozen=True)
+class RegistryEvent:
+    kind:    str                # "added" | "removed" | "updated"
+    entry:   CapabilityEntry
+```
+
+### 3.3 `health.py`
+
+```python
+# hearthnet/bus/health.py
+class HealthTracker:
+    """Rolling-window health stats per (node_id, capability_name, version).
+       Constant memory: O(nodes × capabilities)."""
+
+    def __init__(self, window: int = HEALTH_WINDOW_CALLS): ...
+
+    def record(self, entry: CapabilityEntry, *, success: bool, latency_ms: float) -> None:
+        """Append a sample; recompute p50/p99/success_rate; update entry in place.
+        Quarantines entry if success_rate drops below HEALTH_QUARANTINE_THRESHOLD."""
+
+    def is_quarantined(self, entry: CapabilityEntry) -> bool: ...
+
+    def reset(self, entry: CapabilityEntry) -> None:
+        """Clear stats — used after quarantine timeout."""
+```
+
+Internal: each entry holds a fixed-size ring buffer of `(success, latency_ms)` samples. Old samples drop off as new ones arrive.
+
+### 3.4 `schema.py`
+
+```python
+# hearthnet/bus/schema.py
+class SchemaValidator:
+    """JSON Schema validation, with caching."""
+
+    def __init__(self): ...
+
+    def validate_request(self, descriptor: CapabilityDescriptor, body: dict) -> None:
+        """Raises BusError('schema_mismatch') with expected schema_hash if invalid."""
+
+    def validate_response(self, descriptor: CapabilityDescriptor, body: dict) -> None: ...
+    def validate_stream_frame(self, descriptor: CapabilityDescriptor, frame: dict) -> None: ...
+
+def compute_schema_hash(descriptor_partial: dict) -> str:
+    """BLAKE3 over canonical-JSON. See CONTRACT §11.
+       Argument shape:
+         {
+           'name': ..., 'version': ...,
+           'request_schema': {...},
+           'response_schema': {...} or None,
+           'stream_schema':   {...} or None,
+         }
+       Returns 'blake3:<hex>'."""
+```
+
+### 3.5 `router.py`
+
+```python
+# hearthnet/bus/router.py
+class Router:
+    """Selects the best CapabilityEntry for a request."""
+
+    def __init__(self, registry: Registry, config: BusConfig, our_node_id: str): ...
+
+    def route(self, req: RouteRequest) -> CapabilityEntry | None:
+        """Return the chosen entry, or None if no candidate is viable.
+        Candidates must:
+          - match name and version (CONTRACT §2.1)
+          - pass params_compatible() (capability-specific, see §5.5)
+          - not be quarantined
+          - have in_flight < max_concurrent
+          - have last_seen within freshness window (60s)
+        Scoring: see §5.4."""
+
+    def route_sticky(self, req: RouteRequest) -> CapabilityEntry | None:
+        """If req.session_id is bound to an entry, return that entry if still viable.
+        Otherwise fall back to route() and bind."""
+
+    def release_session(self, session_id: str) -> None: ...
+```
+
+### 3.6 `trace.py`
+
+```python
+# hearthnet/bus/trace.py
+@dataclass(frozen=True)
+class CallTraceEvent:
+    ts:          str
+    trace_id:    str
+    capability:  CapabilityName
+    version:     str
+    from_node:   str
+    to_node:     str
+    is_local:    bool
+    result:      str            # "ok" | error_code
+    ms:          float
+    tokens_in:   int | None     # llm.*-specific
+    tokens_out:  int | None
+    bytes_in:    int
+    bytes_out:   int
+
+class TraceHook:
+    """Emits trace events to the ring buffer (X03) and Prometheus metrics."""
+
+    def __init__(self): ...
+
+    def on_call_start(self, req: RouteRequest, entry: CapabilityEntry) -> None: ...
+    def on_call_end(
+        self,
+        req: RouteRequest,
+        entry: CapabilityEntry,
+        *,
+        result: str,
+        latency_ms: float,
+        bytes_in: int,
+        bytes_out: int,
+        tokens_in: int | None = None,
+        tokens_out: int | None = None,
+    ) -> None: ...
+```
+
+### 3.7 `CapabilityBus` (the facade)
+
+```python
+# hearthnet/bus/__init__.py
+class CapabilityBus:
+    """The integration point. Services register with this; transport dispatches to it."""
+
+    def __init__(
+        self,
+        node_id_full: str,
+        community_id: str,
+        config: BusConfig,
+        transport_client: HttpClient,
+        community_manifest_provider: Callable[[], CommunityManifest],
+    ):
+        self.registry  = Registry(our_node_id=node_id_full)
+        self.health    = HealthTracker()
+        self.schema    = SchemaValidator()
+        self.router    = Router(self.registry, config, our_node_id=node_id_full)
+        self.trace     = TraceHook()
+        self._client   = transport_client
+        ...
+
+    # --- service-side: registration ---
+
+    def register_service(self, service: 'Service') -> None:
+        """Calls service.capabilities() and registers each with the local handler."""
+
+    def register_capability(
+        self,
+        descriptor: CapabilityDescriptor,
+        handler: Callable[[RouteRequest], Awaitable[dict] | AsyncIterator[dict]],
+    ) -> None:
+        """Lower-level alternative when a module has no Service class."""
+
+    # --- transport-side: dispatch ---
+
+    async def handle_call(self, req: RouteRequest) -> dict | AsyncIterator[dict]:
+        """Called by the X01 server after auth.
+        Decides local vs remote, validates schema, runs the handler or makes a remote call,
+        records trace + health, returns the payload (or yields frames)."""
+
+    # --- caller-side: outbound capability invocation ---
+
+    async def call(
+        self,
+        capability: CapabilityName,
+        version_req: Version,
+        body: dict,
+        *,
+        session_id: str | None = None,
+        timeout_seconds: float | None = None,
+    ) -> dict:
+        """Used by services that need to invoke other capabilities (e.g. rag.query calling embed.text).
+        Goes through the router. If chosen entry is local, runs handler directly.
+        If remote, uses X01 client. Records trace + health."""
+
+    async def stream(
+        self,
+        capability: CapabilityName,
+        version_req: Version,
+        body: dict,
+        *,
+        session_id: str | None = None,
+    ) -> AsyncIterator[Frame]:
+        """Streaming version of call()."""
+
+    # --- peer integration ---
+
+    def on_peer_added(self, peer: PeerRecord) -> None: ...
+    def on_peer_updated(self, peer: PeerRecord) -> None: ...
+    def on_peer_removed(self, node_id: str) -> None: ...
+
+    # --- introspection (used by UI / CLI) ---
+
+    def topology_snapshot(self) -> 'TopologySnapshot': ...
+    def recent_traces(self, n: int = 50) -> list[CallTraceEvent]: ...
+    def stats(self) -> dict: ...
+
+
+@dataclass(frozen=True)
+class TopologySnapshot:
+    our_node_id:        str
+    peers:              list[PeerRecord]
+    capabilities_local: list[CapabilityEntry]
+    capabilities_remote: list[CapabilityEntry]
+    in_flight_total:    int
+
+class BusError(Exception):
+    """code in {schema_invalid, namespace_violation, schema_mismatch, not_found, capacity_exceeded,
+               quarantined, partition, timeout, internal_error}"""
+    code: str
+```
+
+---
+
+## 4. The Service protocol (consumed from `services/base.py`)
+
+```python
+# hearthnet/services/base.py
+class Service(Protocol):
+    """Implemented by every L4 service module."""
+    name:    str            # "llm" | "rag" | "marketplace" | ...
+    version: str            # service version, separate from capability version
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable]]:
+        """Return (descriptor, handler) pairs for each capability this service offers.
+        Handlers signature: (RouteRequest) -> Awaitable[dict] | AsyncIterator[dict]"""
+
+    async def start(self) -> None:
+        """Warm up backends, open DBs, etc."""
+
+    async def stop(self) -> None:
+        """Release resources."""
+
+    def health(self) -> dict:
+        """Implementation-specific health blob (used by /health)."""
+```
+
+---
+
+## 5. Behaviour
+
+### 5.1 Bootstrap
+
+```
+node.py creates CapabilityBus
+  ↓
+node.py instantiates services, calls bus.register_service(s) for each
+  ↓
+each service.start() runs (model loaded, DB opened, etc.)
+  ↓
+node.py wires bus.on_peer_added <- PeerRegistry.subscribe()
+  ↓
+node.py wires X01 server handler to bus.handle_call
+  ↓
+bus is live
+```
+
+### 5.2 Peer event handling
+
+When [M02](M02-discovery.md) emits `PeerEvent("added")` with a verified manifest:
+
+```
+bus.on_peer_added(peer)
+  → registry.update_from_peer_manifest(peer, peer.manifest) → Diff
+  → for each added entry: emit RegistryEvent('added')
+  → for each removed entry: emit RegistryEvent('removed')
+```
+
+### 5.3 Inbound call lifecycle (`handle_call`)
+
+```
+1. transport receives, verifies signature, builds RouteRequest
+2. bus.handle_call(req):
+   a. session_id present?
+        yes → entry = router.route_sticky(req)
+        no  → entry = router.route(req)
+   b. entry is None → raise BusError('not_found')
+   c. enforce trust_required (compare against caller's level in community manifest)
+   d. validate_request(entry.descriptor, req.body)
+   e. entry.in_flight >= max_concurrent → raise BusError('capacity_exceeded') with retry_after
+   f. entry.in_flight += 1
+   g. trace.on_call_start(req, entry)
+   h. if entry.is_local:
+        result = await entry.handler(req)
+      else:
+        result = await self._client.call(entry.endpoint, ...)
+   i. validate_response(entry.descriptor, result)  (if non-stream)
+   j. trace.on_call_end(...), health.record(...)
+   k. entry.in_flight -= 1
+   l. return result
+```
+
+For streaming: same flow but `result` is an async iterator; validation is per-frame; final telemetry recorded on `done` or `error`.
+
+### 5.4 Routing algorithm (Router.route)
+
+```python
+def route(req):
+    candidates = registry.find(req.capability, req.version_req)
+    candidates = [
+        e for e in candidates
+        if not health.is_quarantined(e)
+        and e.in_flight < e.descriptor.max_concurrent
+        and (e.is_local or e.last_seen > monotonic() - 60)
+        and params_compatible(e.descriptor.params, req.body.get("params", {}))
+    ]
+    if not candidates:
+        return None
+    if config.prefer_local:
+        local = [e for e in candidates if e.is_local]
+        if local and local[0].in_flight / max(local[0].descriptor.max_concurrent, 1) < config.local_load_threshold:
+            return local[0]
+    return min(candidates, key=score)
+
+def score(e):
+    latency = e.p50_latency_ms if e.p50_latency_ms > 0 else 500.0   # unknown → assume 500ms
+    load = e.in_flight / max(e.descriptor.max_concurrent, 1)
+    reliability_penalty = (1 - e.success_rate) * 1000
+    locality_bonus = -50 if e.is_local else 0
+    return latency * (1 + load) + reliability_penalty + locality_bonus
+```
+
+### 5.5 `params_compatible` (per-capability)
+
+The bus alone cannot know which `params` matter for compatibility (model name for `llm.chat`, corpus for `rag.query`). Services register a `params_compatible` predicate alongside their descriptor:
+
+```python
+# In service's capabilities() return value, tuple is actually:
+#   (descriptor, handler, params_compatible)
+# where params_compatible: Callable[[dict, dict], bool]
+#   args: (offered_params, requested_params) → True if requested can be served
+```
+
+Default predicate: `lambda offered, requested: True` (any-matches-any). LLM service overrides to check model/quant/ctx; RAG overrides to check corpus name; etc. Documented per-service in M04 / M05 / etc.
+
+### 5.6 Sticky routing
+
+For multi-turn capabilities (`llm.chat` continuations, future `chat.thread`):
+
+- Caller passes `session_id`
+- First call: router picks an entry, records `entry.sticky_sessions.add(session_id)`
+- Subsequent calls with same `session_id`: router returns same entry if still viable
+- TTL: 10 minutes idle (driven by a background sweeper)
+- On entry removal (peer left): session unbinds; next call gets a new entry; caller MAY observe context loss (capability handler returns `bad_request` if context required)
+
+### 5.7 Quarantine
+
+```
+health.record(entry, success, latency):
+    append to ring buffer
+    recompute success_rate over last HEALTH_WINDOW_CALLS samples (or fewer if young)
+    if success_rate < HEALTH_QUARANTINE_THRESHOLD:
+        entry.quarantined_until = monotonic() + HEALTH_QUARANTINE_SECONDS
+        log.warning("quarantined", capability, node_id, success_rate)
+        metrics.counter("hearthnet_quarantines_total").inc()
+
+router.route considers quarantined_until <= monotonic() before including.
+```
+
+After quarantine timeout, the next call is a "probe": if it succeeds, history resets; if it fails, immediate re-quarantine.
+
+### 5.8 Outbound `call` from a service
+
+```
+service code: await bus.call("embed.text", (1,0), {"params": {...}, "input": {...}})
+  → router.route(...) → entry
+  → if entry.is_local: dispatch to handler directly (no HTTP roundtrip)
+  → else: client.call(entry.endpoint, ...)
+```
+
+Local short-circuit is the reason a service in the same process can use the bus without paying network cost.
+
+---
+
+## 6. Errors (BusError code mapping)
+
+| BusError code | Wire `ErrorCode` | HTTP status |
+|---------------|-----------------|-------------|
+| `schema_invalid` | (raised at registration; never on wire) | — |
+| `namespace_violation` | (raised at registration) | — |
+| `schema_mismatch` | `schema_mismatch` | 400 |
+| `not_found` | `not_found` | 404 |
+| `capacity_exceeded` | `capacity_exceeded` | 429 |
+| `quarantined` | `partition` | 503 |
+| `partition` | `partition` | 503 |
+| `timeout` | `timeout` | 408 |
+| `internal_error` | `internal_error` | 500 |
+
+Plus auth-level errors raised before the bus sees the request: `unauthorized`, `revoked`, `invalid_signature`, `expired`, `rate_limited` — see [X01 §3.3](../cross-cutting/X01-transport.md).
+
+---
+
+## 7. Configuration
+
+From [X04](../cross-cutting/X04-config.md):
+
+```python
+config.bus.prefer_local
+config.bus.local_load_threshold
+```
+
+Constants used: `HEALTH_WINDOW_CALLS`, `HEALTH_QUARANTINE_THRESHOLD`, `HEALTH_QUARANTINE_SECONDS`.
+
+---
+
+## 8. Tests
+
+### Unit
+
+- `test_register_local_validates_descriptor`
+- `test_register_local_namespace_violation_raises`
+- `test_schema_hash_stable_across_runs`
+- `test_schema_hash_changes_on_schema_change`
+- `test_router_prefers_local_when_underloaded`
+- `test_router_prefers_remote_when_local_overloaded`
+- `test_router_skips_quarantined`
+- `test_router_breaks_ties_by_latency_then_reliability`
+- `test_health_quarantines_at_threshold`
+- `test_health_resets_after_quarantine_window`
+- `test_params_compatible_predicate_invoked`
+- `test_sticky_session_binds_then_unbinds_on_peer_removal`
+- `test_in_flight_decrements_on_handler_exception`
+
+### Integration
+
+- `test_two_nodes_route_to_each_other` — two in-process buses, one registers `llm.chat`, the other calls
+- `test_three_nodes_load_balance` — three providers, 100 calls, distribution within 30% of even
+- `test_quarantine_after_chaos` — fault inject one provider, observe quarantine then recovery
+- `test_streaming_call_records_full_trace`
+- `test_sticky_routing_preserves_session_across_calls`
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| Capability descriptor concept | [CONTRACT §2, §11](../CAPABILITY_CONTRACT.md) |
+| Schema hash computation | [CONTRACT §11](../CAPABILITY_CONTRACT.md) |
+| Version compatibility | [CONTRACT §2.1](../CAPABILITY_CONTRACT.md) |
+| Wire-level error codes | [CONTRACT §9](../CAPABILITY_CONTRACT.md) |
+| Transport dispatch | [X01 §3.3](../cross-cutting/X01-transport.md) |
+| Peer registry | [M02 §3.1](M02-discovery.md) |
+| Trace ring buffer | [X03 §5](../cross-cutting/X03-observability.md) |
+| Service protocol consumers | [M04](M04-llm.md), [M05](M05-rag.md), [M06](M06-marketplace.md), [M07](M07-file-blobs.md), [M10](M10-chat.md), [M11](M11-embedding.md) |
+| UI consumes topology_snapshot | [M08 §3.2](M08-ui.md) |
+
+---
+
+## 10. Open questions
+
+1. **Per-capability params predicate registration** — currently a third tuple element. Cleaner alternative: store as method on a `CapabilitySpec` subclass. Decide before M04 lands.
+2. **Sticky session TTL** — fixed 10 minutes? Or per-capability declared? MVP: fixed. Phase 2: declared.
+3. **Load balancing fairness** — current scorer is greedy. Should we add a small random jitter to avoid herd-on-fastest? MVP: no. If we see herd in tests, add ε-noise.
+4. **Schema cache invalidation** — currently keyed by `schema_hash`. Implicit invalidation on hash change. Should be sufficient.

docs/M04-llm.md

@@ -0,0 +1,352 @@
+# M04 — LLM Service
+
+**Spec version:** v1.0
+**Depends on:** M03 (bus), X04 (config), X03 (observability), backend libs (llama-cpp-python, ollama HTTP, httpx for HTTP backends)
+**Depended on by:** M05 (RAG uses llm.complete internally), M08 (UI passes user queries through llm.chat)
+
+---
+
+## 1. Responsibility
+
+Provide `llm.chat@1.0` and `llm.complete@1.0`. Wrap multiple inference backends (llama.cpp, Ollama, LM Studio, HF Inference API, Anthropic API, OpenAI-compatible HTTP). Register one capability instance per (backend, model, quant) tuple so the bus can see them as separate routable providers.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/services/llm/
+├── __init__.py
+├── service.py                 # LlmService
+├── tokenizers.py              # rough token counting per family
+└── backends/
+    ├── __init__.py
+    ├── base.py                # LlmBackend Protocol
+    ├── llama_cpp.py           # llama-cpp-python in-process
+    ├── ollama.py              # Ollama HTTP at http://localhost:11434
+    ├── lmstudio.py            # LM Studio HTTP (OpenAI-compatible)
+    ├── hf_api.py              # HuggingFace Inference API
+    └── anthropic_api.py       # Anthropic Messages API
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `backends/base.py`
+
+```python
+# hearthnet/services/llm/backends/base.py
+from dataclasses import dataclass
+from typing import AsyncIterator, Protocol
+
+@dataclass(frozen=True)
+class Token:
+    text:    str
+    logprob: float | None
+    stop:    bool
+
+@dataclass(frozen=True)
+class ChatResult:
+    text:       str
+    tokens_in:  int
+    tokens_out: int
+    stop_reason: str    # "end" | "max_tokens" | "stop_sequence" | "cancelled"
+    ms:         int
+
+@dataclass(frozen=True)
+class BackendModel:
+    """One model an LlmBackend can serve."""
+    name:           str       # "qwen2.5-7b-instruct"
+    quant:          str       # "q4_k_m", "q8_0", "fp16", "api"
+    ctx_max:        int       # 8192
+    modalities:     list[str] # ["text"] or ["text", "vision"]
+    requires_internet: bool   # API backends → True; local → False
+
+class LlmBackend(Protocol):
+    """Abstract backend. Implementations cover one provider."""
+
+    name:       str           # "llama_cpp" | "ollama" | ...
+    models:     list[BackendModel]
+
+    async def warm(self, model: str) -> None: ...
+    async def close(self) -> None: ...
+
+    async def chat(
+        self,
+        *,
+        model: str,
+        messages: list[dict],
+        max_tokens: int = 1024,
+        temperature: float = 0.7,
+        top_p: float = 0.95,
+        stop: list[str] | None = None,
+        seed: int | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[Token]:
+        """Yields Tokens. The final Token has stop=True."""
+
+    async def complete(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        max_tokens: int = 256,
+        temperature: float = 0.7,
+        top_p: float = 0.95,
+        stop: list[str] | None = None,
+        seed: int | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[Token]: ...
+
+    def count_tokens(self, model: str, text: str) -> int:
+        """Approximate token count; uses a per-model tokenizer if available."""
+
+    def max_concurrent(self, model: str) -> int:
+        """Backend-specific concurrency limit. Used in capability descriptor."""
+
+    def health(self) -> dict: ...
+```
+
+### 3.2 Concrete backends
+
+```python
+# hearthnet/services/llm/backends/llama_cpp.py
+class LlamaCppBackend(LlmBackend):
+    """In-process llama-cpp-python. Loads one model at a time per instance.
+       Multiple LlamaCppBackend instances may coexist if VRAM allows."""
+
+    def __init__(self, model_path: Path, model_meta: BackendModel, gpu_layers: int = -1):
+        ...
+
+# hearthnet/services/llm/backends/ollama.py
+class OllamaBackend(LlmBackend):
+    """HTTP-based Ollama at http://localhost:11434 (or remote)."""
+
+    def __init__(self, base_url: str = "http://localhost:11434", models: list[str] | None = None):
+        """If models is None, discover via GET /api/tags."""
+
+# hearthnet/services/llm/backends/lmstudio.py
+class LmStudioBackend(LlmBackend):
+    """OpenAI-compatible HTTP at http://host:1234.
+       Used in Christof's home setup at 192.168.188.25:1234."""
+
+    def __init__(self, base_url: str, default_model: str): ...
+
+# hearthnet/services/llm/backends/hf_api.py
+class HfApiBackend(LlmBackend):
+    """HuggingFace Inference API. Requires HF_TOKEN env var (declared in config.llm.backends[].api_key_env)."""
+
+    def __init__(self, model: str, token_env: str = "HF_TOKEN"): ...
+
+# hearthnet/services/llm/backends/anthropic_api.py
+class AnthropicApiBackend(LlmBackend):
+    """Anthropic Messages API. Phase 1.5; useful when internet up."""
+
+    def __init__(self, model: str = "claude-sonnet-4-6", token_env: str = "ANTHROPIC_API_KEY"): ...
+```
+
+### 3.3 `tokenizers.py`
+
+```python
+# hearthnet/services/llm/tokenizers.py
+def count_tokens_approx(model_family: str, text: str) -> int:
+    """Fast heuristic: chars / 3.5 for Latin scripts, /2 for CJK.
+       Used when no real tokenizer is available."""
+
+def model_family(model_name: str) -> str:
+    """'qwen2.5-7b-instruct' → 'qwen', 'llama-3-8b' → 'llama', etc."""
+```
+
+### 3.4 `service.py`
+
+```python
+# hearthnet/services/llm/service.py
+class LlmService:
+    name    = "llm"
+    version = "1.0"
+
+    def __init__(self, config: LlmConfig):
+        self._backends: list[LlmBackend] = self._build_backends(config)
+
+    def _build_backends(self, config: LlmConfig) -> list[LlmBackend]:
+        """Instantiate each declared backend; skip backends that fail to initialise (with warning)."""
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Emits one (descriptor, handler, predicate) per (backend, model, capability_kind) combo:
+        - For each backend × each model: one llm.chat entry and one llm.complete entry.
+        - Each descriptor's params include model, quant, ctx, backend."""
+
+    async def start(self) -> None:
+        """Warm one backend (the first listed) to avoid cold-start lag on first call."""
+
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handlers ---
+
+    async def handle_chat(self, req: RouteRequest) -> AsyncIterator[dict]:
+        """Streams SSE frames per CONTRACT §4.1.
+        Picks the backend from req.body['params']['model'] (matched at routing).
+        Maps backend Token → SSE 'token' frames; emits 'done' with meta."""
+
+    async def handle_complete(self, req: RouteRequest) -> AsyncIterator[dict]:
+        """Same shape as chat but for CONTRACT §4.2."""
+```
+
+### 3.5 Capability descriptors
+
+For each `(backend, model)` pair, the service registers:
+
+```python
+# llm.chat instance
+CapabilityDescriptor(
+    name="llm.chat",
+    version=(1, 0),
+    stability="stable",
+    request_schema={...},        # CONTRACT §4.1 schema
+    response_schema={...},       # for non-stream fallback
+    stream_schema={
+        "oneOf": [
+            {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "logprob": {"type": ["number", "null"]}}},
+            {"type": "object", "required": ["tokens_out", "stop_reason", "ms"]}     # done frame
+        ]
+    },
+    params={
+        "model":   "<model.name>",
+        "quant":   "<model.quant>",
+        "ctx":     model.ctx_max,
+        "backend": "<backend.name>",
+        "modalities": model.modalities,
+    },
+    max_concurrent=backend.max_concurrent(model.name),
+    trust_required="member",
+    timeout_seconds=LLM_GENERATION_DEFAULT_TIMEOUT_SECONDS,
+    idempotent=False,
+)
+```
+
+### 3.6 `params_compatible` predicate
+
+```python
+def params_compatible(offered: dict, requested: dict) -> bool:
+    # Required match: model.
+    # Optional match: ctx (caller's must be <= offered).
+    if requested.get("model") != offered.get("model"):
+        return False
+    if "ctx" in requested and requested["ctx"] > offered["ctx"]:
+        return False
+    return True
+```
+
+---
+
+## 4. Behaviour
+
+### 4.1 Multi-backend selection
+
+Multiple backends may serve the same model name (e.g. llama_cpp local + LM Studio remote both offer `qwen2.5-7b-instruct`). They register as separate capability entries. The bus router picks among them by latency/load — no service-internal preference logic.
+
+### 4.2 Streaming and cancellation
+
+- `handle_chat` is an async generator
+- Each backend `Token` becomes one SSE `token` frame
+- On client disconnect, the generator is cancelled; the backend's `chat()` async iterator receives `GeneratorExit`, propagates cancellation to the underlying library (llama.cpp: set abort flag; HTTP backends: close connection)
+- Cleanup must complete within 200 ms
+
+### 4.3 Internet-dependent backends
+
+`HfApiBackend` and `AnthropicApiBackend` set `requires_internet=True` on their `BackendModel`. The service still registers them, but the [M09](M09-emergency.md) detector triggers deregistration from the local bus when offline. On restore, they are re-registered.
+
+### 4.4 Tool calls (Phase 2)
+
+The `tool_call_delta` stream frame in [CONTRACT §4.1](../CAPABILITY_CONTRACT.md) is reserved. Backends that support tool calls (Anthropic, OpenAI, OpenAI-compatible) will emit these in a future version. MVP: ignored / empty.
+
+### 4.5 Deterministic mode
+
+If `seed` is present in request, backends that support seeded sampling apply it. `llama_cpp` does; HTTP APIs vary. When unsupported, backend still serves but does NOT promise determinism.
+
+### 4.6 Token counting
+
+Token counts in `meta.tokens_in` / `meta.tokens_out`:
+- `llama_cpp`: exact from the model
+- HTTP backends with usage in response: exact
+- Others: approximate via `tokenizers.count_tokens_approx`
+
+---
+
+## 5. Errors
+
+| Condition | Wire code |
+|-----------|-----------|
+| Unknown model | `not_found` |
+| Backend HTTP 5xx | `internal_error` |
+| Backend HTTP rate limit | `rate_limited` (forwarded; `retry_after_ms` if available) |
+| Empty messages array | `bad_request` |
+| Context exceeded | `bad_request` (with message indicating size) |
+| Generation timed out | `timeout` |
+| Backend crashed mid-stream | emit `error` frame, then close |
+
+---
+
+## 6. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```toml
+[[llm.backends]]
+name  = "lmstudio"
+url   = "http://192.168.188.25:1234"
+model = "qwen2.5-7b-instruct"
+
+[[llm.backends]]
+name  = "llama_cpp"
+url   = ""                # local path; see backend
+model = "qwen2.5-1.5b-instruct-q4_k_m.gguf"
+
+[[llm.backends]]
+name        = "anthropic_api"
+model       = "claude-sonnet-4-6"
+api_key_env = "ANTHROPIC_API_KEY"
+```
+
+Constant: `LLM_GENERATION_DEFAULT_TIMEOUT_SECONDS = 120`.
+
+---
+
+## 7. Tests
+
+### Unit
+- `test_capabilities_one_entry_per_model_per_backend`
+- `test_handler_chat_emits_token_then_done`
+- `test_handler_chat_cancellation_within_200ms`
+- `test_params_compatible_model_must_match`
+- `test_params_compatible_ctx_upper_bound`
+- `test_internet_dependent_backend_deregistered_on_offline`
+
+### Integration
+- `test_lmstudio_backend_streams_real_tokens` (requires LM Studio at the configured address; skip otherwise)
+- `test_three_node_llm_load_balance`
+- `test_remote_call_through_bus_returns_full_response`
+
+---
+
+## 8. Cross-references
+
+| What | Where |
+|------|-------|
+| `llm.chat@1.0` wire | [CONTRACT §4.1](../CAPABILITY_CONTRACT.md) |
+| `llm.complete@1.0` wire | [CONTRACT §4.2](../CAPABILITY_CONTRACT.md) |
+| Service protocol | [M03 §4](M03-bus.md) |
+| Streaming format | [CONTRACT §5.3](../CAPABILITY_CONTRACT.md), [X01 §6](../cross-cutting/X01-transport.md) |
+| Used by RAG | [M05 §5](M05-rag.md) |
+| Emergency mode deregistration | [M09 §5](M09-emergency.md) |
+
+---
+
+## 9. Open questions
+
+1. **Vision models** — Phase 2; reserved `modalities: ['text','vision']`. Request schema gains `messages[].content[].type='image_url'`.
+2. **Tool calls** — Phase 2; reserved frame `tool_call_delta`. Will integrate Anthropic + OpenAI styles.
+3. **Local model autodiscovery** — should `llama_cpp` backend scan a models directory? Useful but easy to defer.
+4. **Per-model preset profiles** — Phase 2: bind a `system_prompt_template` to a model. Not yet.

docs/M05-rag.md

@@ -0,0 +1,325 @@
+# M05 — RAG Service
+
+**Spec version:** v1.0
+**Depends on:** M03 (bus, for both registration and invoking embed.text), M07 (blobs, for source document storage), X04 (config), X03 (observability), X02 (events, for `rag.document.ingested`), `chromadb`, `pypdf`
+**Depended on by:** M08 (UI), other applications that consume retrieved chunks
+
+---
+
+## 1. Responsibility
+
+Implement `rag.query@1.0`, `rag.ingest@1.0`, `rag.list_corpora@1.0`. Maintain per-corpus vector stores. Chunk and embed ingested documents. Store original document blobs via [M07](M07-file-blobs.md).
+
+RAG is **never** the LLM provider — answer generation is a separate hop the caller makes after retrieving chunks. This separation is deliberate: it keeps `rag.query` cacheable and reusable.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/services/rag/
+├── __init__.py
+├── service.py          # RagService
+├── chunker.py          # text → chunks
+├── ingest.py           # document → chunks → embeddings → store
+└── store.py            # ChromaDB wrapper, one collection per corpus
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `chunker.py`
+
+```python
+# hearthnet/services/rag/chunker.py
+@dataclass(frozen=True)
+class Chunk:
+    text:     str
+    metadata: dict      # {doc_cid, doc_title, page, chunk_index, language}
+
+def chunk_text(
+    text: str,
+    *,
+    tokens_per_chunk: int = RAG_CHUNK_TOKENS,        # 1000
+    overlap_tokens:   int = RAG_CHUNK_OVERLAP_TOKENS, # 200
+    metadata: dict | None = None,
+) -> list[Chunk]:
+    """Split using a sliding window measured in approximate tokens.
+    Respects paragraph boundaries where possible; falls back to sentence then word."""
+
+def chunk_pdf(pdf_bytes: bytes, *, doc_metadata: dict) -> list[Chunk]:
+    """Extract text per page using pypdf, then chunk_text per page.
+    Each chunk carries page number in metadata."""
+```
+
+### 3.2 `store.py`
+
+```python
+# hearthnet/services/rag/store.py
+class CorpusStore:
+    """One ChromaDB collection per corpus name."""
+
+    def __init__(self, corpora_dir: Path, corpus: str, embedding_dim: int):
+        ...
+
+    def add_chunks(self, chunks: list[Chunk], embeddings: list[list[float]]) -> None: ...
+    def has_document(self, doc_cid: str) -> bool: ...
+    def query(
+        self,
+        embedding: list[float],
+        *,
+        k: int,
+        filter: dict | None = None,
+    ) -> list[ScoredChunk]: ...
+    def count(self) -> int: ...
+    def size_bytes(self) -> int: ...
+    def language_majority(self) -> str | None: ...
+
+@dataclass(frozen=True)
+class ScoredChunk:
+    chunk:    Chunk
+    score:    float    # similarity, higher = better
+
+def list_corpora(corpora_dir: Path) -> list[str]: ...
+def corpus_info(corpora_dir: Path, corpus: str) -> dict: ...
+```
+
+### 3.3 `ingest.py`
+
+```python
+# hearthnet/services/rag/ingest.py
+class IngestPipeline:
+    def __init__(
+        self,
+        bus: CapabilityBus,           # to call embed.text@1.0
+        blob_store: BlobStore,        # from M07
+        corpora_dir: Path,
+        event_log: EventLog,
+    ):
+        ...
+
+    async def ingest_document(
+        self,
+        doc_cid: str,
+        corpus: str,
+        title: str,
+        language: str,
+        metadata: dict,
+        author_kp: KeyPair,
+    ) -> IngestResult:
+        """1. Fetch blob bytes from blob_store by doc_cid (assumed already stored).
+        2. Detect content type (currently: PDF only).
+        3. Chunk.
+        4. Batch embed via bus.call('embed.text', (1,0), ...).
+        5. Write to CorpusStore.
+        6. Append rag.document.ingested event via event_log.
+        Idempotent on doc_cid: re-ingesting is a no-op (logged, returns existing result)."""
+
+@dataclass(frozen=True)
+class IngestResult:
+    doc_cid:        str
+    chunks_indexed: int
+    tokens_indexed: int
+    ingest_event_id: str
+    ms:             int
+```
+
+### 3.4 `service.py`
+
+```python
+# hearthnet/services/rag/service.py
+class RagService:
+    name    = "rag"
+    version = "1.0"
+
+    def __init__(
+        self,
+        config: RagConfig,
+        bus: CapabilityBus,
+        blob_store: BlobStore,
+        event_log: EventLog,
+        community_manifest_provider: Callable[[], CommunityManifest],
+    ):
+        self._stores: dict[str, CorpusStore] = {}
+        self._ingest = IngestPipeline(bus, blob_store, config.corpora_dir, event_log)
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Registers one entry per existing corpus for rag.query (params include corpus name).
+        rag.ingest registered once (corpus is a request param).
+        rag.list_corpora registered once."""
+
+    async def start(self) -> None:
+        """Discover existing corpora on disk, open ChromaDB collections."""
+
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handlers ---
+
+    async def handle_query(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.4.
+        1. Embed query via bus.call('embed.text', (1,0), ...).
+        2. CorpusStore.query(embedding, k).
+        3. Format response."""
+
+    async def handle_ingest(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.5.
+        Checks caller is at least 'trusted'.
+        Delegates to IngestPipeline.ingest_document."""
+
+    async def handle_list_corpora(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.6."""
+```
+
+### 3.5 Capability descriptors and predicates
+
+```python
+# rag.query: registered per corpus
+descriptor_query = CapabilityDescriptor(
+    name="rag.query", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={"corpus": "<corpus_name>", "embedding_model": "<model>", "k_max": RAG_MAX_K},
+    max_concurrent=4,
+    trust_required="member",
+    timeout_seconds=10,
+    idempotent=True,
+)
+
+def query_params_compatible(offered: dict, requested: dict) -> bool:
+    return requested.get("corpus") == offered.get("corpus")
+
+# rag.ingest: registered once
+descriptor_ingest = CapabilityDescriptor(
+    name="rag.ingest", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={"corpora_available": "<list of corpus names>"},
+    max_concurrent=2,
+    trust_required="trusted",
+    timeout_seconds=300,
+    idempotent=True,
+)
+```
+
+---
+
+## 4. Behaviour
+
+### 4.1 Embedding via the bus, not direct import
+
+`RagService` never imports `EmbeddingService`. It uses `bus.call("embed.text", (1, 0), ...)`. Reasons:
+- Embeddings might run on another node (e.g. a GPU anchor) while RAG runs on a CPU hearth
+- The bus handles load balancing and quarantine automatically
+- Keeps the service module dependency graph honest
+
+### 4.2 Corpus naming
+
+- `[a-z0-9-]+` only, max 64 chars
+- One corpus per ChromaDB collection
+- Two reserved names: `personal` (per-user, NEVER federated) and `system` (read-only, ships with HearthNet)
+
+### 4.3 Ingest idempotency
+
+A `(corpus, doc_cid)` already in the store is a no-op. This makes re-ingestion safe across restarts and gossip re-delivery of `rag.document.ingested` events.
+
+### 4.4 Event log integration
+
+After a successful ingest, append a `rag.document.ingested` event ([X02 §3.1](../cross-cutting/X02-events.md), [CONTRACT §7.2](../CAPABILITY_CONTRACT.md)). Other nodes seeing this event MAY pre-fetch the blob (via `file.read`) and ingest into their own RAG corpus, depending on their replication policy. (Replication policy is out of scope for MVP; nodes do not auto-replicate.)
+
+### 4.5 Multi-tenant isolation
+
+Each corpus is open in read or read/write mode by the node. The `personal` corpus is local-only and is NEVER routable from other nodes (the service does not register a `rag.query` capability for it).
+
+### 4.6 PDF extraction quality
+
+`pypdf` is OK for digital PDFs. For scanned PDFs, OCR is needed; this is M-Phase-2 (`ocr.*` namespace). Ingest of a scanned PDF without OCR will produce empty chunks; service detects and returns `bad_request` with hint.
+
+### 4.7 Query language detection
+
+Optional: detect query language; pass as metadata filter to the store. MVP: detection skipped; caller's filter is respected.
+
+---
+
+## 5. Composition flow (typical user query)
+
+```
+UI → bus.call("llm.chat", ..., body containing user message)
+         ↓ (handler in LLM service, but UI may also explicitly call rag.query first)
+UI → bus.call("rag.query", (1,0), {params: {corpus: ...}, input: {query: ...}})
+         ↓
+RagService.handle_query
+   → bus.call("embed.text", (1,0), ...)       # may go remote
+   → CorpusStore.query → list[ScoredChunk]
+   → return chunks with metadata
+         ↓
+UI builds prompt with chunks + question
+UI → bus.call("llm.chat", ..., messages including context)
+```
+
+The UI orchestrates this in M08. RAG service does NOT chain into the LLM itself.
+
+---
+
+## 6. Errors
+
+| Condition | Wire code |
+|-----------|-----------|
+| Unknown corpus on query | `not_found` |
+| `k > RAG_MAX_K` | `bad_request` |
+| Blob not resolvable on ingest | `not_found` |
+| Unsupported MIME type on ingest | `bad_request` |
+| Caller not trusted for ingest | `unauthorized` |
+| Embedding model unavailable (no embed.text providers) | `partition` (bus quarantine state) |
+
+---
+
+## 7. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.rag.enabled       # bool
+config.rag.corpora_dir   # default <CACHE>/embeddings
+```
+
+Constants: `RAG_CHUNK_TOKENS`, `RAG_CHUNK_OVERLAP_TOKENS`, `RAG_DEFAULT_K`, `RAG_MAX_K`.
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_chunk_text_respects_paragraph_boundaries`
+- `test_chunk_pdf_carries_page_number`
+- `test_corpus_store_add_then_query_recovers_chunk`
+- `test_ingest_idempotent_on_doc_cid`
+- `test_query_handler_calls_embed_via_bus_not_direct_import`
+- `test_query_handler_rejects_unknown_corpus`
+- `test_personal_corpus_not_registered_as_capability`
+
+### Integration
+- `test_demo_corpus_query_returns_relevant_chunks` — load the 6 demo PDFs, query, expect top hit
+- `test_ingest_then_other_node_sees_event` — two-node gossip
+- `test_query_falls_back_to_remote_when_local_corpus_missing` — two nodes, only one has corpus
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| `rag.*` wire spec | [CONTRACT §4.4–4.6](../CAPABILITY_CONTRACT.md) |
+| Service protocol | [M03 §4](M03-bus.md) |
+| Uses embed.text | [M11](M11-embedding.md) |
+| Uses blob store | [M07 §3](M07-file-blobs.md) |
+| Emits rag.document.ingested | [X02](../cross-cutting/X02-events.md), [CONTRACT §7.2](../CAPABILITY_CONTRACT.md) |
+| UI query composition | [M08 §4](M08-ui.md) |
+
+---
+
+## 10. Open questions
+
+1. **Re-embedding when models change** — if the configured embedding model changes, the existing corpora are stale. Decision (MVP): refuse to start with mismatched model; print a `hearthnet rag reindex` hint. Phase 2: auto-reindex.
+2. **Federation of corpora** — Phase 2: a corpus may be marked "federated" and queries fan out to other communities. Out of scope here.
+3. **Reranking** — Phase 2: a `rerank.text@1.0` capability could be inserted between embedding and final ranking. Reserved namespace.
+4. **Hybrid search** — keyword + dense. ChromaDB has limited support. Phase 2.

docs/M06-marketplace.md

@@ -0,0 +1,336 @@
+# M06 — Marketplace Service
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity, for signed events), M03 (bus), X02 (events, for storage + replay), X04 (config), X03 (observability), optionally M11 (embedding, for `market.search`)
+**Depended on by:** M08 (UI marketplace tab)
+
+---
+
+## 1. Responsibility
+
+Provide `market.list`, `market.post`, `market.expire`, `market.search` capabilities. Maintain a materialised view of current (non-expired) posts derived from the community event log.
+
+The marketplace is **event-sourced**: posts are not stored as a table the service writes to. They are derived from `market.post.*` events in the X02 log. This makes posts automatically signed, durable, and gossipable.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/services/marketplace/
+├── __init__.py
+├── service.py        # MarketplaceService
+├── post.py           # Post dataclass + helpers
+└── views.py          # MarketplaceView: MaterialisedView from X02
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `post.py`
+
+```python
+# hearthnet/services/marketplace/post.py
+from dataclasses import dataclass
+from typing import Literal
+
+Category = Literal["offer", "request", "info", "emergency"]
+
+@dataclass(frozen=True)
+class Location:
+    lat:   float
+    lng:   float
+    label: str
+
+@dataclass(frozen=True)
+class Post:
+    """The marketplace's domain object.
+       Derived from a market.post.created event + zero or more market.post.updated events,
+       and terminated by a market.post.expired event."""
+    event_id:   str           # ULID of the original .created event
+    lamport:    int
+    author:     str           # NodeID full form
+    category:   Category
+    title:      str
+    body:       str
+    location:   Location | None
+    tags:       list[str]
+    created_at: str
+    expires_at: str
+    expired_via_event_id: str | None      # set when expired
+    expiry_reason: str | None              # "fulfilled" | "withdrawn" | ...
+
+    def is_expired(self, now: datetime | None = None) -> bool: ...
+```
+
+### 3.2 `views.py`
+
+```python
+# hearthnet/services/marketplace/views.py
+class MarketplaceView:
+    """MaterialisedView (X02 protocol).
+       Subscribes to event_types: market.post.created, .updated, .expired."""
+
+    def __init__(self): ...
+
+    # MaterialisedView protocol:
+    def reset(self) -> None: ...
+    def apply(self, event: Event) -> None: ...
+    def snapshot_state(self) -> dict: ...
+    def restore_state(self, state: dict) -> None: ...
+
+    # queries used by the service handlers:
+    def list(
+        self,
+        *,
+        category: Category | None = None,
+        tags: list[str] | None = None,
+        since_lamport: int = 0,
+        limit: int = 50,
+    ) -> list[Post]: ...
+
+    def get(self, event_id: str) -> Post | None: ...
+    def max_lamport(self) -> int: ...
+
+    # bulk listings for search:
+    def all_active(self) -> list[Post]: ...
+```
+
+### 3.3 `service.py`
+
+```python
+# hearthnet/services/marketplace/service.py
+class MarketplaceService:
+    name    = "marketplace"
+    version = "1.0"
+
+    def __init__(
+        self,
+        config: MarketConfig,
+        bus: CapabilityBus,
+        event_log: EventLog,
+        replay_engine: ReplayEngine,
+        author_kp: KeyPair,            # this node's key, for signing posts
+        community_manifest_provider: Callable[[], CommunityManifest],
+    ):
+        self.view = MarketplaceView()
+        replay_engine.register(
+            "marketplace",
+            self.view,
+            event_types=["market.post.created", "market.post.updated", "market.post.expired"],
+        )
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Registers: market.list, market.post, market.expire, market.search."""
+
+    async def start(self) -> None:
+        """Replay relevant events into the view; install background sweeper for auto-expiry."""
+
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handlers ---
+
+    async def handle_list(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.11."""
+
+    async def handle_post(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.12.
+        Validates ttl ≤ config.market.max_ttl_seconds.
+        Idempotency by client_id: if an event with matching (author, client_id) already exists, return its event_id.
+        Otherwise: append market.post.created event via event_log.append_local."""
+
+    async def handle_expire(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.13.
+        Checks caller is original author OR trusted moderator.
+        Appends market.post.expired event."""
+
+    async def handle_search(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.14.
+        1. bus.call('embed.text', (1,0), {texts: [query]})
+        2. For each active post, embed (cached) and score via cosine.
+        3. Return top-k.
+        Cache embedding per (event_id, body+title hash)."""
+```
+
+### 3.4 Capability descriptors
+
+```python
+descriptor_list = CapabilityDescriptor(
+    name="market.list", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=8,
+    trust_required="member", timeout_seconds=5, idempotent=True,
+)
+
+descriptor_post = CapabilityDescriptor(
+    name="market.post", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=4,
+    trust_required="member", timeout_seconds=10, idempotent=True,
+)
+
+descriptor_expire = CapabilityDescriptor(
+    name="market.expire", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=4,
+    trust_required="member", timeout_seconds=5, idempotent=True,
+)
+
+descriptor_search = CapabilityDescriptor(
+    name="market.search", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=4,
+    trust_required="member", timeout_seconds=10, idempotent=True,
+)
+```
+
+All four use the default `lambda offered, requested: True` params predicate.
+
+---
+
+## 4. Behaviour
+
+### 4.1 Event-sourcing in practice
+
+```
+client → market.post (via bus)
+  ↓
+service.handle_post
+  → validate
+  → idempotency check on (author, client_id)
+  → event_log.append_local("market.post.created", data, author_kp)
+  → X02 fans out the new event to ReplayEngine
+  → MarketplaceView.apply(event) updates in-memory state
+  → service returns {event_id, lamport}
+```
+
+```
+peer sync brings remote market.post.created event
+  ↓
+event_log.append_received(event)
+  → ReplayEngine triggers MarketplaceView.apply(event)
+  → next market.list call sees the new post
+```
+
+The service NEVER writes posts directly. The event log is the only mutator.
+
+### 4.2 Auto-expiry sweeper
+
+Background task scanning the view every 60 seconds:
+
+- For each post where `now >= expires_at` AND no `.expired` event seen: append `market.post.expired` event with reason `"stale"` and the local node as author.
+- This is best-effort; only the post's author or a trusted member is supposed to expire it, but for "stale" reason, any anchor MAY do it.
+
+Conflict: if two nodes auto-expire concurrently, both events land, view de-duplicates by `target_event_id`. Last-writer-wins per Lamport (no functional difference — both say "expired").
+
+### 4.3 Search caching
+
+Embedding all active posts on every search is wasteful. Cache strategy:
+
+- Per-post embedding cached in memory keyed by `(event_id, hash(title+body))`
+- On `.updated` event, invalidate
+- Cache size bounded; LRU eviction at 5000 entries
+
+Phase 1.5 optimisation. MVP may re-embed each time.
+
+### 4.4 Trust check for expire
+
+```python
+def can_expire(caller_node_id, post, reason, community_manifest):
+    if caller_node_id == post.author:
+        return True
+    if reason in ("fulfilled", "withdrawn", "user_request"):
+        return caller_node_id == post.author   # author-only for these reasons
+    if reason == "stale":
+        return community_manifest.level_of(caller_node_id) in ("trusted", "anchor")
+    return False
+```
+
+### 4.5 Categories vs tags
+
+- `category` is a fixed enum (4 values)
+- `tags` are free-form, sourced from user input; the UI presents popular tags as suggestions
+
+### 4.6 Geofencing
+
+`location` is advisory. Display only. No filtering in MVP. Phase 2: `market.list` filter on distance.
+
+---
+
+## 5. Composition with `market.search`
+
+```
+UI input: "wasser notfall"
+  ↓
+bus.call("market.search", (1,0), {input: {query: "wasser notfall", k: 10}})
+  → MarketplaceService.handle_search
+       → bus.call("embed.text", (1,0), {texts: ["wasser notfall"]})
+       → score each active post (cached embedding) → top-k
+       → return posts with scores
+```
+
+The marketplace service depends on `embed.text` being available somewhere on the mesh. If embedding is unavailable, search falls back to substring matching (logged at `warning`).
+
+---
+
+## 6. Errors
+
+| Condition | Wire code |
+|-----------|-----------|
+| ttl_seconds > max_ttl_seconds | `bad_request` |
+| caller not authorised to expire | `unauthorized` |
+| target post not found (expire/update) | `not_found` |
+| no embedding provider for search | `partition` (degrades to substring) |
+
+---
+
+## 7. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.market.enabled
+config.market.default_ttl_seconds   # 7 days
+config.market.max_ttl_seconds       # 30 days
+```
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_post_event_appears_in_view_after_apply`
+- `test_post_is_idempotent_on_client_id`
+- `test_expire_unauthorized_caller_rejected`
+- `test_auto_expire_appends_event_with_stale_reason`
+- `test_replay_then_snapshot_then_restore_equal_state`
+- `test_search_falls_back_to_substring_when_embedding_unavailable`
+
+### Integration
+- `test_two_node_post_visible_after_sync`
+- `test_three_node_concurrent_posts_all_visible`
+- `test_expire_propagates_then_list_excludes`
+- `test_market_search_returns_relevant`
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| `market.*` wire | [CONTRACT §4.11–4.14](../CAPABILITY_CONTRACT.md) |
+| Event types | [CONTRACT §7.2](../CAPABILITY_CONTRACT.md) |
+| Event log | [X02](../cross-cutting/X02-events.md) |
+| Embed via bus | [M11](M11-embedding.md) |
+| UI marketplace tab | [M08 §5.4](M08-ui.md) |
+
+---
+
+## 10. Open questions
+
+1. **Geographic filter** — Phase 2 with a `location_filter: {center, radius_km}`.
+2. **Moderation tooling** — a "report" flow with admin queue; Phase 2.
+3. **Inter-community marketplace federation** — Phase 2 / 3.
+4. **Encryption of post bodies** — currently cleartext within community. Could encrypt at-rest in event log. Out of scope.

docs/M07-file-blobs.md

@@ -0,0 +1,357 @@
+# M07 — File & Blobs
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity, for signing advertise events), M03 (bus), X01 (transport, for streamed chunk transfer), X02 (events), X04 (config), `blake3`
+**Depended on by:** M05 (RAG stores source PDFs as blobs), M10 (chat attachments), M08 (UI file browser)
+
+---
+
+## 1. Responsibility
+
+Two coupled concerns sharing one module:
+
+1. **Blob store** (`hearthnet.blobs.*`): on-disk content-addressed store, chunking, hash verification
+2. **File service** (`hearthnet.services.file.*`): exposes `file.read`, `file.list`, `file.advertise`, `file.put` capabilities to the bus
+
+The split exists because the blob store is also used by [M05](M05-rag.md) (for storing source PDFs) without going through the bus.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/blobs/
+├── __init__.py
+├── store.py              # BlobStore: filesystem-backed CID store
+├── chunker.py            # split / reassemble + BLAKE3
+└── transfer.py           # parallel chunk fetch across multiple sources
+
+hearthnet/services/file/
+├── __init__.py
+└── service.py            # FileService: registers file.* capabilities
+```
+
+---
+
+## 3. Blob store (`hearthnet.blobs.*`)
+
+### 3.1 `chunker.py`
+
+```python
+# hearthnet/blobs/chunker.py
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class ChunkRef:
+    index:    int
+    cid:      str          # "blake3:<hex>" of this chunk's bytes
+    size_bytes: int
+
+@dataclass(frozen=True)
+class BlobManifest:
+    cid:             str           # "blake3:<hex>" — the merkle root, derived from chunks
+    size_bytes:      int
+    chunk_size_bytes: int          # CHUNK_SIZE_BYTES = 262144
+    chunks:          list[ChunkRef]
+    mime_type:       str | None
+    filename:        str | None    # advisory only, not part of the CID
+
+def hash_bytes(data: bytes) -> str:
+    """BLAKE3 → 'blake3:<hex>'."""
+
+def chunk_blob(data: bytes, *, chunk_size: int = CHUNK_SIZE_BYTES) -> tuple[BlobManifest, list[bytes]]:
+    """Split bytes into 256KB chunks. Compute per-chunk CID and the merkle-root CID for the manifest."""
+
+def manifest_cid(manifest: BlobManifest) -> str:
+    """Compute the manifest's CID: BLAKE3 over canonical-JSON of {chunks[].cid, size_bytes, chunk_size_bytes}."""
+
+def reassemble(chunks: list[bytes]) -> bytes:
+    """Concat chunks in index order. Caller is responsible for verifying each chunk's CID first."""
+
+def verify_chunk(data: bytes, expected_cid: str) -> None:
+    """Raises BlobError('hash_mismatch') if data's BLAKE3 != expected_cid."""
+```
+
+### 3.2 `store.py`
+
+```python
+# hearthnet/blobs/store.py
+class BlobStore:
+    """Sharded filesystem store at <DATA>/blobs/<aa>/<bb...>.bin"""
+
+    def __init__(self, dir_path: Path, gc_threshold: float = BLOB_GC_DISK_THRESHOLD):
+        ...
+
+    # -- single-chunk ops --
+
+    def has(self, cid: str) -> bool: ...
+    def read_chunk(self, cid: str) -> bytes:
+        """Raises BlobError('not_found') if absent. Verifies hash on read."""
+    def write_chunk(self, cid: str, data: bytes) -> None:
+        """Verifies hash before writing; idempotent if already present."""
+    def delete_chunk(self, cid: str) -> bool: ...
+
+    # -- blob (manifest + chunks) ops --
+
+    def has_blob(self, manifest_cid: str) -> bool:
+        """True iff the manifest exists AND all referenced chunks exist."""
+
+    def read_manifest(self, manifest_cid: str) -> BlobManifest: ...
+
+    def write_blob(self, manifest: BlobManifest, chunks: list[bytes]) -> None:
+        """Atomically write manifest + chunks. Hash-verifies each chunk."""
+
+    def read_blob_bytes(self, manifest_cid: str) -> bytes:
+        """Reassemble whole blob into memory. For small blobs only (< 100 MB)."""
+
+    async def read_blob_stream(self, manifest_cid: str) -> AsyncIterator[tuple[ChunkRef, bytes]]:
+        """Stream chunks for large blobs."""
+
+    # -- introspection / GC --
+
+    def list_cids(self, prefix: str | None = None) -> list[str]: ...
+    def total_bytes(self) -> int: ...
+    def pin(self, cid: str) -> None: ...
+    def unpin(self, cid: str) -> None: ...
+    def is_pinned(self, cid: str) -> bool: ...
+
+    def gc(self, target_fraction: float = 0.7) -> int:
+        """Run LRU eviction of unpinned blobs until disk usage < target_fraction.
+        Returns bytes freed."""
+
+class BlobError(Exception):
+    """code in {'not_found','hash_mismatch','io_error','disk_full','manifest_invalid'}"""
+    code: str
+```
+
+### 3.3 `transfer.py`
+
+```python
+# hearthnet/blobs/transfer.py
+class TransferManager:
+    """Coordinates parallel chunk fetch from multiple peer sources."""
+
+    def __init__(self, store: BlobStore, bus: CapabilityBus, concurrency: int = 4):
+        ...
+
+    async def fetch_blob(
+        self,
+        manifest_cid: str,
+        *,
+        sources: list[str] | None = None,    # NodeIDs known to hold; if None, ask via bus
+    ) -> BlobManifest:
+        """1. Fetch manifest (via bus.call('file.read', ...)).
+        2. Determine missing chunks.
+        3. For each missing chunk, pick a source (round-robin, load-aware via bus), fetch via stream.
+        4. Verify each chunk, write to store.
+        5. Return manifest once complete.
+        Resumable: re-running after partial completion skips already-present chunks."""
+
+    async def advertise(self, cids: list[str]) -> None:
+        """Tell other nodes we hold these CIDs. Emits file.cid.advertised events
+        and direct file.advertise calls to known peers (best-effort)."""
+```
+
+---
+
+## 4. File service (`hearthnet.services.file.*`)
+
+### 4.1 `service.py`
+
+```python
+# hearthnet/services/file/service.py
+class FileService:
+    name    = "file"
+    version = "1.0"
+
+    def __init__(self, config: FileConfig, store: BlobStore, event_log: EventLog):
+        ...
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Registers: file.read, file.list, file.advertise, file.put."""
+
+    async def start(self) -> None: ...
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handlers ---
+
+    async def handle_read(self, req: RouteRequest) -> AsyncIterator[dict] | dict:
+        """CONTRACT §4.7.
+        If CID is a chunk → return single chunk JSON (non-stream).
+        If CID is a manifest → stream: 'manifest' frame, then chunks, then 'done'."""
+
+    async def handle_list(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.8."""
+
+    async def handle_advertise(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.9.
+        Records the caller as a source for the given CIDs in an in-memory index.
+        Optionally emits file.cid.advertised event to gossip."""
+
+    async def handle_put(self, req: RouteRequest) -> AsyncIterator[dict]:
+        """CONTRACT §4.10.
+        Client streams chunks; server verifies and stores.
+        Requires trust 'trusted' (disk-poisoning risk)."""
+```
+
+### 4.2 Capability descriptors
+
+```python
+descriptor_read = CapabilityDescriptor(
+    name="file.read", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...},
+    stream_schema={...},    # manifest + chunk + done frames
+    params={},
+    max_concurrent=8,
+    trust_required="member",
+    timeout_seconds=300,
+    idempotent=True,
+)
+
+descriptor_list = CapabilityDescriptor(
+    name="file.list", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=4,
+    trust_required="member", timeout_seconds=5, idempotent=True,
+)
+
+descriptor_advertise = CapabilityDescriptor(
+    name="file.advertise", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=16,
+    trust_required="member", timeout_seconds=5, idempotent=True,
+)
+
+descriptor_put = CapabilityDescriptor(
+    name="file.put", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...},
+    stream_schema={...},     # ready + chunk + done
+    params={}, max_concurrent=2,
+    trust_required="trusted", timeout_seconds=600, idempotent=True,
+)
+```
+
+### 4.3 `params_compatible`
+
+All `file.*` capabilities use the default `lambda offered, requested: True`. Any node with the capability can serve any CID it has; the bus query later checks `has(cid)` and returns `not_found` if absent.
+
+---
+
+## 5. Behaviour
+
+### 5.1 Storage layout on disk
+
+```
+<DATA>/blobs/
+├── ab/
+│   ├── c123def456...bin         # chunk
+│   └── c123def456...manifest.json
+├── cd/
+│   └── ...
+└── pinned.txt                   # newline-separated CIDs that must not be GC'd
+```
+
+Sharded by first 2 hex chars of CID (256 directories, ~uniform).
+
+### 5.2 Hash verification is always-on
+
+Every read and every write verifies the chunk's BLAKE3 against its CID. Cost is small (BLAKE3 is fast); benefit is bit-rot detection and protection from a malicious advertiser sending bad bytes.
+
+### 5.3 Pinning
+
+- The `personal` RAG corpus pins its source documents
+- Snapshot blobs are pinned by [X02](../cross-cutting/X02-events.md)
+- The community manifest blob is pinned
+- User-pinned via UI
+
+Anything else is GC-eligible.
+
+### 5.4 GC
+
+When disk usage exceeds `BLOB_GC_DISK_THRESHOLD` (0.80), evict LRU unpinned blobs until below `0.7 × disk_capacity`. Tracked by file mtime (read updates mtime; common Linux mount option).
+
+### 5.5 Source discovery
+
+When a node needs a CID it doesn't have:
+
+1. Ask the bus: `file.list@1.0` with `prefix=<short CID>` against known peers
+2. Aggregate the responders into a sources list
+3. Optionally also consult `file.cid.advertised` events in the log
+4. Pass sources to `TransferManager.fetch_blob`
+
+Phase 2: a DHT-like source index. MVP: per-request fan-out.
+
+### 5.6 Concurrent fetches
+
+`TransferManager` issues N concurrent chunk fetches across sources. Each chunk request goes via the bus (so health/quarantine work). On per-chunk failure, retry from a different source; after 3 attempts on a chunk, fail the whole blob with `partition`.
+
+### 5.7 Backpressure on PUT
+
+When a node receives `file.put`, it inspects free disk before accepting. If below 1 GB after putative add, refuse with `capacity_exceeded`.
+
+---
+
+## 6. Errors
+
+| Condition | Wire code |
+|-----------|-----------|
+| CID not present | `not_found` |
+| Hash verification failed | `bad_request` (caller sent corrupted bytes) |
+| Out of disk | `capacity_exceeded` |
+| Caller not trusted for put | `unauthorized` |
+| Chunk size mismatch | `bad_request` |
+
+---
+
+## 7. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.file.blobs_dir       # default <DATA>/blobs
+config.file.gc_threshold    # default 0.8
+```
+
+Constants: `CHUNK_SIZE_BYTES`, `BLOB_GC_DISK_THRESHOLD`.
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_chunk_then_reassemble_roundtrip`
+- `test_manifest_cid_deterministic`
+- `test_verify_chunk_detects_one_bit_flip`
+- `test_store_write_then_read_returns_same_bytes`
+- `test_store_rejects_wrong_cid_on_write`
+- `test_pinning_prevents_gc`
+- `test_gc_evicts_lru_unpinned`
+
+### Integration
+- `test_two_node_blob_fetch` — node A has blob, node B requests via bus, succeeds
+- `test_three_source_parallel_fetch` — three nodes hold the blob, B fetches in parallel, distribution observed
+- `test_chunk_corruption_falls_over_to_alt_source` — one source returns bad chunk; fetcher retries from another
+- `test_put_requires_trusted_caller`
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| `file.*` wire | [CONTRACT §4.7–4.10](../CAPABILITY_CONTRACT.md) |
+| BLAKE3 + CID format | [GLOSSARY.md](../GLOSSARY.md), [CONTRACT §1.4](../CAPABILITY_CONTRACT.md) |
+| Used by RAG ingest | [M05 §3.3](M05-rag.md) |
+| Used by chat attachments | [M10 §3.3](M10-chat.md) |
+| `file.cid.advertised` event | [CONTRACT §7.2](../CAPABILITY_CONTRACT.md), [X02](../cross-cutting/X02-events.md) |
+| Snapshot pinning | [X02 §5](../cross-cutting/X02-events.md) |
+
+---
+
+## 10. Open questions
+
+1. **DHT source index** — Phase 2 nice-to-have.
+2. **Background replication** — Phase 2: a node may auto-replicate blobs of high "interest" (referenced by recent events). Out of scope MVP.
+3. **Encrypted blobs** — for personal corpus, blobs are stored in cleartext on local disk. Add at-rest encryption Phase 2.
+4. **Resumable PUT mid-transfer crash** — Phase 1.5: server keeps a partial-transfer index keyed by client_id + manifest_cid; client can resume.

docs/M08-ui.md

@@ -0,0 +1,338 @@
+# M08 — UI (Gradio Dashboard + Mobile Client)
+
+**Spec version:** v1.0
+**Depends on:** M03 (bus, the ONLY data source the UI talks to), X03 (observability, for trace display), X04 (config), M09 (emergency state subscribed), `gradio>=6.0.0`
+**Depended on by:** M13 (onboarding extends the UI), M12 (CLI may launch UI)
+
+The UI's strict rule: **it never imports a service module**. Every piece of data comes via `bus.call(...)` or via the bus's introspection APIs (`topology_snapshot`, `recent_traces`). This keeps the UI swappable.
+
+---
+
+## 1. Responsibility
+
+Present a local-host web UI at `http://127.0.0.1:7860` showing:
+
+- Live topology of the mesh
+- An "ask" pane wired to `llm.chat` + `rag.query`
+- A chat tab for direct messages
+- A marketplace tab
+- A files tab
+- An emergency tab (visible only when offline)
+- A settings tab
+- A mobile web client served at `/mobile`
+
+---
+
+## 2. File layout
+
+```
+hearthnet/ui/
+├── __init__.py
+├── app.py                  # build_ui(): assembles Gradio Blocks
+├── topology.py             # Cytoscape.js-backed topology component
+├── theme.py                # Colour tokens, fonts, CSS
+├── onboarding.py           # M13 owns this; reachable from settings
+├── tabs/
+│   ├── __init__.py
+│   ├── ask.py              # LLM passthrough with optional RAG
+│   ├── chat.py             # direct messages
+│   ├── marketplace.py
+│   ├── files.py
+│   ├── emergency.py        # only mounted when offline state active
+│   └── settings.py
+└── mobile/                 # served as static at /mobile
+    ├── index.html
+    ├── app.js
+    └── style.css
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `app.py`
+
+```python
+# hearthnet/ui/app.py
+import gradio as gr
+
+class UiApp:
+    def __init__(
+        self,
+        bus: CapabilityBus,
+        state_bus: StateBus,                # M09
+        config: UiConfig,
+        node_id_short: str,
+        community_name: str,
+    ):
+        ...
+
+    def build(self) -> gr.Blocks:
+        """Assemble the full UI."""
+
+    async def launch_async(self) -> None:
+        """Non-blocking launch. Used by node.py."""
+
+    async def shutdown(self) -> None: ...
+
+def build_ui(bus, state_bus, config, **meta) -> UiApp:
+    """Convenience constructor used by node.py."""
+```
+
+### 3.2 `topology.py`
+
+```python
+# hearthnet/ui/topology.py
+class TopologyComponent:
+    """Wraps Cytoscape.js inside a Gradio HTML component.
+       Auto-refreshes from bus.topology_snapshot() every 2s.
+       Animates recent trace events (last 10s) along edges."""
+
+    def __init__(self, bus: CapabilityBus): ...
+
+    def render(self) -> gr.HTML: ...
+
+    def push_trace(self, event: CallTraceEvent) -> None:
+        """Trigger an edge animation. Color by capability prefix."""
+
+    def push_topology(self, snapshot: TopologySnapshot) -> None: ...
+
+# Cytoscape config:
+# - Nodes: one per known peer + one for self
+# - Edges: dynamic; appear on trace events; fade after 5s
+# - Edge colour:  llm.*=teal,  rag.*=purple,  file.*=amber,
+#                 chat.*=blue, market.*=green, community.*=grey
+# - Node colour:  online=green, stale=amber, offline=red
+# - Node label:   display_name + capability badges
+# - On node click: side panel shows full manifest
+```
+
+---
+
+## 4. Composition
+
+The Gradio Blocks tree:
+
+```
+gr.Blocks(theme=hearthnet_theme, title="HearthNet")
+├── header bar
+│   ├── community name + node display name
+│   ├── status pill (online/offline) → bound to state_bus
+│   └── settings gear
+├── topology pane (always visible at top)
+└── tabs:
+    ├── Ask          (always)
+    ├── Chat         (always; badge with unread count)
+    ├── Marketplace  (always)
+    ├── Files        (always)
+    ├── Notfall      (visible only when state.mode != "online")
+    └── Settings     (always; includes Onboarding entry point)
+```
+
+---
+
+## 5. Tabs
+
+### 5.1 Ask tab — `tabs/ask.py`
+
+A simple chat interface:
+
+- Top: Corpus selector (dropdown, populated via `bus.call("rag.list_corpora", ...)`)
+- Top right: Model selector (capabilities from `bus.topology_snapshot().capabilities_*` filtered by name=`llm.chat`)
+- Centre: Chat history (Gradio Chatbot)
+- Bottom: Input + Send
+
+Behaviour on send:
+
+```
+1. if corpus selected:
+   chunks = bus.call("rag.query", (1,0), {params:{corpus}, input:{query:msg, k:5}})
+   build system prompt with chunks + sources
+2. messages = [system_with_chunks, ...history, user_msg]
+3. stream = bus.stream("llm.chat", (1,0), {params:{model}, input:{messages, stream:true}})
+4. accumulate tokens into a streaming response in the Chatbot
+5. on done: append sources panel (clickable to open file)
+```
+
+### 5.2 Settings tab — `tabs/settings.py`
+
+- Node identity (read-only)
+- Community membership (read-only; "leave community" with double-confirm)
+- LLM backend list (read-only; edit via config.toml)
+- Theme toggle (Hearth / Spark dark mode)
+- Debug toggles (verbose logging, trace ring buffer dump)
+- Onboarding entrypoints: "Create new community", "Join via invite"
+- Privacy: "Erase all data" (triple-confirm, wipes keys + state)
+
+### 5.3 Chat tab — `tabs/chat.py`
+
+- Left: peer list with last-message timestamps, unread badges
+  - Source: `bus.call("chat.history", (1,0), {input:{}})` → group by peer
+- Right: message thread for selected peer
+  - Auto-refresh on local pubsub topic `chat.message.<our_short_id>`
+- Bottom: input + send + attachment button (opens file picker → uploads as blob via `file.put` → attaches CID)
+- "Encrypted" indicator placeholder (Phase 2)
+
+### 5.4 Marketplace tab — `tabs/marketplace.py`
+
+- Top: Category filter, tag filter, search box (semantic)
+- Centre: Cards (one per post)
+- Bottom-right: "Neuer Beitrag" → modal for new post
+- "Mark fulfilled" / "Withdraw" on each card if author == us
+
+### 5.5 Files tab — `tabs/files.py`
+
+- Left: corpus / pinned / recent
+- Centre: file grid
+- Upload area at top
+- Click: preview (image / PDF / text), download, advertise to peers
+
+### 5.6 Emergency tab — `tabs/emergency.py`
+
+Visible only when `state_bus.current().mode != "online"`. Designed for big buttons, low-stress reading. Large amber banner at top.
+
+Contents:
+
+- Big "Was tun?" button → opens the most relevant corpus (default `niederrhein-emergency`)
+- Neighbour list (last seen times prominent)
+- Direct chat shortcut
+- "Update" indicator: how far behind the event log we are vs. last sync
+- Shared resources table (generator availability, water, light) — Phase 2
+
+### 5.7 Banner
+
+```
+INTERNET OFFLINE — LOKAL AKTIV
+seit 14:32 · 3 Nachbar*innen erreichbar
+```
+
+When degraded:
+```
+EINGESCHRÄNKTE VERBINDUNG · Lokale Dienste aktiv
+```
+
+---
+
+## 6. Mobile client (`mobile/`)
+
+Plain static HTML + JS, no framework. Served by [X01](../cross-cutting/X01-transport.md) at `/mobile/*`. Same bus API (signed requests, but credentials stored in `IndexedDB`).
+
+Minimum features:
+- Ask (LLM passthrough)
+- Chat
+- Marketplace browse
+- Emergency mode banner
+- No topology viz (too dense for small screen)
+
+Auth on mobile: the user scans an invite QR with the camera → key derived in WebCrypto → stored in IndexedDB.
+
+---
+
+## 7. Theming (`theme.py`)
+
+Two themes:
+
+- **Hearth (default)** — warm, parchment background, dark walnut accents
+- **Spark (high-contrast / dark)** — black bg, amber accents — also the emergency theme
+
+CSS variables:
+
+```css
+--hn-bg:         #f4ead7;  /* hearth */
+--hn-bg-dark:    #1a1816;  /* spark */
+--hn-accent:     #b45309;  /* amber */
+--hn-accent-2:   #14b8a6;  /* teal */
+--hn-accent-3:   #6d28d9;  /* purple, used for rag */
+--hn-text:       #2c1810;
+--hn-text-dark:  #f4ead7;
+--hn-error:      #b91c1c;
+--hn-warn:       #d97706;
+--hn-ok:         #15803d;
+```
+
+When emergency mode is active, theme switches to Spark with amber accents and the banner.
+
+---
+
+## 8. Behaviour
+
+### 8.1 Topology refresh
+
+Every 2 s the topology component calls `bus.topology_snapshot()`. Diff with previous; only changed nodes/edges trigger re-render. Trace ring is read via `bus.recent_traces(50)` every 1 s and pushed as animations.
+
+### 8.2 Live updates without polling
+
+Where possible the UI subscribes:
+
+- `state_bus.subscribe()` for emergency banner
+- `bus.registry.subscribe()` for topology pane (additive)
+- Pubsub `marketplace.post.created` for marketplace tab live refresh
+- Pubsub `chat.message.<our_short_id>` for chat tab notifications
+
+### 8.3 Error display
+
+- Capability call errors → toast at top with code and "details" expander
+- Backend warm-up takes time → spinner with "Modell wird geladen ..."
+- Network failures during a stream → frame "verbindung abgerissen" injected; user can retry
+
+### 8.4 Settings persistence
+
+Settings tab edits go to `config.toml` via [X04 §3](../cross-cutting/X04-config.md). Some require restart; UI clearly indicates this.
+
+### 8.5 First-run handoff to M13
+
+If on startup `config.community.community_id is None`, the UI redirects to onboarding (see [M13](M13-onboarding.md)) instead of showing tabs.
+
+---
+
+## 9. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.ui.host             # 127.0.0.1
+config.ui.port             # 7860
+config.ui.launch_browser   # auto-open in browser on launch
+```
+
+---
+
+## 10. Tests
+
+### Unit
+- `test_theme_tokens_present`
+- `test_emergency_tab_hidden_when_online`
+- `test_emergency_tab_shown_when_offline`
+- `test_topology_diff_avoids_unchanged_render` (mock bus)
+- `test_settings_writes_to_config_file_atomically`
+
+### Integration
+- `test_ask_tab_does_rag_then_llm_in_order` — mock bus, observe call sequence
+- `test_marketplace_tab_refreshes_on_pubsub_event`
+- `test_mobile_endpoint_serves_index_html`
+
+### Manual
+- Demo dry-run script: open UI, type query, observe topology animation, unplug WAN, observe banner ≤ 5s. Document in `tests/demo_script.md`.
+
+---
+
+## 11. Cross-references
+
+| What | Where |
+|------|-------|
+| Bus introspection APIs | [M03 §3.7](M03-bus.md) |
+| Emergency state source | [M09 §3.1](M09-emergency.md) |
+| Pubsub topics | [CONTRACT §8](../CAPABILITY_CONTRACT.md) |
+| Onboarding flow | [M13](M13-onboarding.md) |
+| Mobile served by | [X01 §3.2](../cross-cutting/X01-transport.md) |
+| Trace event format | [M03 §3.6](M03-bus.md) |
+
+---
+
+## 12. Open questions
+
+1. **Gradio version compatibility** — Gradio 6.x evolves quickly. Pin a minor.
+2. **Native mobile** — Phase 2 (Flutter or React Native). Web works for hackathon.
+3. **Accessibility** — colour contrast meets WCAG AA in both themes; not yet audited.
+4. **Internationalisation** — UI strings in German + English. Switchable. Plattdeutsch as a stretch.
+5. **Cytoscape vs D3** — Cytoscape preferred (less code). Performance budget: 50 nodes, 500 edges.

docs/M09-emergency.md

@@ -0,0 +1,222 @@
+# M09 — Emergency Mode Detector
+
+**Spec version:** v1.0
+**Depends on:** M03 (bus, to deregister internet-dependent capabilities), X04 (config), X03 (observability), `httpx`, `socket`
+**Depended on by:** M08 (UI shows banner), M04 (re-registers internet backends on restore), M02 (increases discovery cadence)
+
+---
+
+## 1. Responsibility
+
+Detect whether the node has working internet access. Publish state transitions locally. Cause the bus to deregister/re-register internet-dependent capabilities and let other modules react.
+
+Out of scope:
+- VPN / overlay status
+- Per-service connectivity checks
+- Cellular signal strength
+
+---
+
+## 2. File layout
+
+```
+hearthnet/emergency/
+├── __init__.py
+├── detector.py        # Detector: probe loop, state machine
+└── state.py           # EmergencyState dataclass + StateBus
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `state.py`
+
+```python
+# hearthnet/emergency/state.py
+from dataclasses import dataclass
+from typing import Literal
+
+Mode = Literal["online", "degraded", "offline"]
+
+@dataclass(frozen=True)
+class EmergencyState:
+    mode:        Mode
+    since:       str           # RFC 3339
+    last_probe:  str
+    probe_results: dict[str, bool]   # target → success
+
+class StateBus:
+    """In-process pubsub for state changes. UI and other modules subscribe."""
+
+    def __init__(self): ...
+    def current(self) -> EmergencyState: ...
+    async def subscribe(self) -> AsyncIterator[EmergencyState]: ...
+    def _emit(self, state: EmergencyState) -> None: ...    # internal
+```
+
+### 3.2 `detector.py`
+
+```python
+# hearthnet/emergency/detector.py
+class Detector:
+    def __init__(
+        self,
+        config: EmergencyConfig,
+        bus: CapabilityBus,
+        state_bus: StateBus,
+    ):
+        ...
+
+    async def run(self) -> None:
+        """Main loop. Cancel-safe.
+        Probe cadence:
+          - online → every EMERGENCY_PROBE_INTERVAL_ONLINE (10s)
+          - degraded → every EMERGENCY_PROBE_INTERVAL_OFFLINE (2s)
+          - offline → every EMERGENCY_PROBE_INTERVAL_OFFLINE (2s)
+        Each tick:
+          1. probe all targets concurrently with 2s timeout
+          2. compute new mode
+          3. apply debounce (EMERGENCY_TRANSITION_DEBOUNCE_SECONDS, anti-flap)
+          4. if mode changed:
+              - state_bus._emit(new_state)
+              - if entered offline: bus deregisters internet-dependent capabilities
+              - if entered online: bus re-registers them
+              - emit log + metric
+        """
+
+    async def shutdown(self) -> None: ...
+
+    # --- probe primitives ---
+
+    async def _probe_dns(self, host: str) -> bool: ...
+    async def _probe_http(self, url: str) -> bool: ...
+```
+
+---
+
+## 4. State machine
+
+```
+              ┌────────┐  any probe fails  ┌──────────┐
+              │ ONLINE ├──────────────────►│ DEGRADED │
+              └───┬────┘                    └─────┬────┘
+                  ▲                               │  ≥2 probes fail for 30s
+                  │ all probes pass for 10s       ▼
+                  │                          ┌──────────┐
+                  └──────────────────────────┤ OFFLINE  │
+                                             └──────────┘
+```
+
+Anti-flap: if more than 3 transitions occur within 60 seconds, the detector stays in the more pessimistic state (degraded or offline) until the window passes.
+
+---
+
+## 5. Behaviour
+
+### 5.1 Probes
+
+Default targets (from `EmergencyConfig.probe_targets`):
+
+- `1.1.1.1` (DNS A query)
+- `8.8.8.8` (DNS A query)
+- `cloudflare.com` (HTTPS HEAD)
+- `quad9.net` (HTTPS HEAD)
+
+Mode rule:
+
+- `online` requires all 4 succeed
+- `offline` requires ≥ 2 to fail
+- everything between is `degraded`
+
+### 5.2 Effects on the bus
+
+When entering `offline`:
+
+```python
+for entry in bus.registry.all_local():
+    if entry.descriptor.params.get("requires_internet"):
+        bus.registry.deregister_local(entry.descriptor.name, entry.descriptor.version)
+        log.info("offline.deregistered", capability=entry.descriptor.name)
+```
+
+When returning to `online`:
+
+```python
+for backend in llm_service._backends:
+    if backend.requires_internet:
+        llm_service._register_backend(backend)        # re-emit descriptors
+```
+
+`requires_internet` is a convention: services that wrap remote APIs (`anthropic_api`, `hf_api`) set this flag on their `BackendModel` and inject it into the capability descriptor params at registration time.
+
+### 5.3 Effects on M02 discovery
+
+Detector also calls `peer_registry.set_pruning_aggressive(offline)`:
+
+- Offline: prune stale peers after 30 s instead of 90
+- Online: standard 90 s
+
+This makes offline mode adapt faster to neighbour churn.
+
+### 5.4 UI surface (M08 consumes)
+
+The state bus is the source for the amber `INTERNET OFFLINE — LOKAL AKTIV` banner. UI subscribes; flips theme; switches LLM passthrough to local-only backends visibly.
+
+### 5.5 Clock sanity probe (only when online)
+
+When online for ≥ 30 s, send an extra HEAD to a single anchor and check the `Date` header. If our system clock differs by > 60 s, log a warning. We do NOT auto-correct.
+
+### 5.6 No on-wire pubsub
+
+`emergency.mode.changed` is local only ([CONTRACT §8](../CAPABILITY_CONTRACT.md)). Other nodes do their own detection.
+
+---
+
+## 6. Errors
+
+This module raises nothing externally; all failures are logged. Internal probe failures are the *normal* signal that drives state.
+
+---
+
+## 7. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.emergency.probe_targets    # list[str]
+```
+
+Constants: `EMERGENCY_PROBE_INTERVAL_ONLINE`, `EMERGENCY_PROBE_INTERVAL_OFFLINE`, `EMERGENCY_PROBE_TIMEOUT_SECONDS`, `EMERGENCY_TRANSITION_DEBOUNCE_SECONDS`.
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_state_transitions_with_synthetic_probes`
+- `test_anti_flap_holds_pessimistic_state`
+- `test_deregister_called_on_offline_entry`
+- `test_reregister_called_on_online_entry`
+
+### Integration
+- `test_demo_unplug_triggers_banner_within_5s` — simulate WAN drop with `iptables` rule, observe state change
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| Online/offline pubsub topic (local) | [CONTRACT §8](../CAPABILITY_CONTRACT.md) |
+| LLM internet-dependent backends | [M04 §4.3](M04-llm.md) |
+| Discovery cadence change | [M02 §4.3](M02-discovery.md) |
+| UI banner | [M08 §5.5](M08-ui.md) |
+
+---
+
+## 10. Open questions
+
+1. **Captive portal detection** — Phase 2: probe a known-content URL and compare body hash. MVP: false positives accepted.
+2. **IPv6-only networks** — current probes are dual-stack via OS. Should work; not yet tested.
+3. **Custom probe scripts** — Phase 2: let users add their own targets.

docs/M10-chat.md

@@ -0,0 +1,295 @@
+# M10 — Chat Service
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity, for signing), M03 (bus), X02 (events), X04 (config), X03 (observability), M07 (attachments via blobs)
+**Depended on by:** M08 (UI chat tab)
+
+---
+
+## 1. Responsibility
+
+Provide `chat.send` and `chat.history` capabilities. Handle direct-message delivery: directly if recipient is online; via store-and-forward through an anchor if offline. Maintain a per-peer chat view materialised from `chat.message.*` events.
+
+E2E encryption between users is Phase 2 ([CONTRACT §12 open question 1](../CAPABILITY_CONTRACT.md)). MVP relies on TLS-in-transit + signed-at-rest within a trusted community.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/services/chat/
+├── __init__.py
+├── service.py        # ChatService
+├── delivery.py       # DeliveryManager: direct vs store-and-forward
+└── views.py          # ChatView: MaterialisedView
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `views.py`
+
+```python
+# hearthnet/services/chat/views.py
+@dataclass(frozen=True)
+class ChatMessage:
+    event_id:     str
+    lamport:      int
+    sender:       str           # NodeID full form
+    recipient:    str
+    body:         str
+    attachments:  list[dict]    # [{cid, name}]
+    created_at:   str
+    delivered_at: str | None
+    read_at:      str | None
+
+class ChatView:
+    """MaterialisedView from chat.message.sent / .delivered / .read events."""
+
+    def __init__(self, our_node_id_full: str):
+        ...
+
+    # MaterialisedView protocol:
+    def reset(self) -> None: ...
+    def apply(self, event: Event) -> None: ...
+    def snapshot_state(self) -> dict: ...
+    def restore_state(self, state: dict) -> None: ...
+
+    # queries:
+    def history_with(
+        self,
+        peer: str | None = None,
+        *,
+        since_lamport: int = 0,
+        limit: int = 200,
+    ) -> list[ChatMessage]: ...
+    def peers(self) -> list[str]:
+        """All NodeIDs we have exchanged messages with."""
+    def unread_count(self, peer: str) -> int: ...
+```
+
+### 3.2 `delivery.py`
+
+```python
+# hearthnet/services/chat/delivery.py
+class DeliveryManager:
+    """Decides direct vs store-and-forward; performs delivery attempts."""
+
+    def __init__(
+        self,
+        bus: CapabilityBus,
+        event_log: EventLog,
+        author_kp: KeyPair,
+        peer_registry: PeerRegistry,
+        config: ChatConfig,
+    ):
+        ...
+
+    async def deliver(self, message_event: Event) -> str:
+        """Attempt delivery.
+        Returns: 'direct' | 'forwarded' | 'queued'.
+        Strategy:
+          1. Look up recipient in peer_registry.
+          2. If online and reachable: push via pubsub topic chat.message.<recipient_short>.
+          3. Else: pick 2 anchors with chat.store_and_forward capability (Phase 2),
+                   call them with the encrypted-blob carrying message.
+                   Fall back to leaving it in our log for eventual sync.
+          4. Mark with method."""
+
+    async def on_local_message_arrived(self, message_event: Event) -> None:
+        """When we receive a chat.message.sent event addressed to us:
+           - emit pubsub chat.message.<our_short_id> for UI
+           - append chat.message.delivered event"""
+
+    async def on_pubsub_message(self, payload: dict) -> None:
+        """When the pubsub topic delivers a message to us, process it
+           (which may include appending the event to our log if not already there)."""
+```
+
+### 3.3 `service.py`
+
+```python
+# hearthnet/services/chat/service.py
+class ChatService:
+    name    = "chat"
+    version = "1.0"
+
+    def __init__(
+        self,
+        config: ChatConfig,
+        bus: CapabilityBus,
+        event_log: EventLog,
+        replay_engine: ReplayEngine,
+        peer_registry: PeerRegistry,
+        author_kp: KeyPair,
+        our_node_id_full: str,
+    ):
+        self.view = ChatView(our_node_id_full=our_node_id_full)
+        replay_engine.register(
+            "chat",
+            self.view,
+            event_types=["chat.message.sent", "chat.message.delivered", "chat.message.read"],
+        )
+        self.delivery = DeliveryManager(bus, event_log, author_kp, peer_registry, config)
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Registers: chat.send, chat.history."""
+
+    async def start(self) -> None:
+        """Replay; subscribe to pubsub topic chat.message.<our_short_id>."""
+
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handlers ---
+
+    async def handle_send(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.15.
+        1. Idempotency by (author, client_id).
+        2. Append chat.message.sent event.
+        3. DeliveryManager.deliver(event) → returns delivery method.
+        4. Return {event_id, lamport, delivered}."""
+
+    async def handle_history(self, req: RouteRequest) -> dict:
+        """CONTRACT §4.16. Self-only: refuses calls where caller != our node_id."""
+```
+
+### 3.4 Capability descriptors
+
+```python
+descriptor_send = CapabilityDescriptor(
+    name="chat.send", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=8,
+    trust_required="member", timeout_seconds=15, idempotent=True,
+)
+
+descriptor_history = CapabilityDescriptor(
+    name="chat.history", version=(1, 0), stability="stable",
+    request_schema={...}, response_schema={...}, stream_schema=None,
+    params={}, max_concurrent=8,
+    trust_required="self",          # the bus enforces caller == our_node_id
+    timeout_seconds=5, idempotent=True,
+)
+```
+
+The `trust_required="self"` is a new level introduced by chat. The bus interprets it as: only the local UI calling through localhost may invoke this capability. Remote callers receive `unauthorized`.
+
+---
+
+## 4. Behaviour
+
+### 4.1 Send → delivery sequence
+
+```
+UI → bus.call("chat.send", (1,0), {input: {client_id, recipient, body, attachments}})
+  → ChatService.handle_send
+       → idempotency check
+       → event_log.append_local("chat.message.sent", data, author_kp)
+            ↳ this fans out to ReplayEngine which calls ChatView.apply()
+       → DeliveryManager.deliver(event)
+            ↳ if recipient online:
+                 → publish to pubsub topic chat.message.<recipient_short>
+            ↳ else (Phase 2):
+                 → bus.call("chat.forward", ...) on two anchors with the capability
+            ↳ else:
+                 → noop, will sync via X02 eventually
+       → return {event_id, lamport, delivered: "direct"|"forwarded"|"queued"}
+```
+
+### 4.2 Receive sequence
+
+```
+pubsub topic chat.message.<our_short_id> fires with event payload
+  → DeliveryManager.on_pubsub_message
+       → event_log.append_received(event)            (deduplicated by event_id)
+            ↳ ChatView.apply()
+       → event_log.append_local("chat.message.delivered", {target_event_id}, our_kp)
+            ↳ propagated back to sender via gossip
+       → emit local notification (UI hook)
+```
+
+### 4.3 Read receipts (optional)
+
+When the UI scrolls past a message, it appends `chat.message.read`. If `config.chat.read_receipts_enabled = false`, the UI doesn't emit it.
+
+### 4.4 Store-and-forward (Phase 2 stub)
+
+MVP path: if recipient offline, message stays in our log; recipient gets it when they sync. This is fine for community members on the same LAN where everyone gossips.
+
+Phase 2: a separate `chat.forward.put@1.0` capability registered by anchors. Sender ships the event to 2 anchors. When recipient reappears, they probe `chat.forward.fetch@1.0` against anchors. After successful delivery, anchors drop the cached event.
+
+### 4.5 Attachments
+
+`attachments` is a list of `{cid, name}`. The actual blob is sent separately via [M07](M07-file-blobs.md). The chat event only references the CID. Receivers fetch on demand.
+
+### 4.6 No self-chat
+
+`recipient == our_node_id` is rejected with `bad_request`.
+
+### 4.7 Group chat (Phase 2)
+
+Reserved `chat.thread.*` namespace. Out of scope here.
+
+---
+
+## 5. Errors
+
+| Condition | Wire code |
+|-----------|-----------|
+| recipient not a community member | `not_found` |
+| caller calling history but not localhost | `unauthorized` |
+| empty body and no attachments | `bad_request` |
+| attachment CID not known to recipient | (silent; recipient fetches via M07 on read) |
+
+---
+
+## 6. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.chat.enabled
+config.chat.store_and_forward   # Phase 2 flag
+```
+
+Phase 2: `config.chat.read_receipts_enabled`.
+
+---
+
+## 7. Tests
+
+### Unit
+- `test_send_appends_event_and_returns_id`
+- `test_send_idempotent_on_client_id`
+- `test_history_rejects_remote_caller`
+- `test_view_apply_updates_state`
+- `test_self_chat_rejected`
+
+### Integration
+- `test_two_node_direct_delivery`
+- `test_recipient_offline_then_online_sees_message_after_sync`
+- `test_delivered_event_propagates_back_to_sender`
+
+---
+
+## 8. Cross-references
+
+| What | Where |
+|------|-------|
+| `chat.*` wire | [CONTRACT §4.15–4.16](../CAPABILITY_CONTRACT.md) |
+| Event types | [CONTRACT §7.2](../CAPABILITY_CONTRACT.md) |
+| Event log | [X02](../cross-cutting/X02-events.md) |
+| Attachments | [M07](M07-file-blobs.md) |
+| Pubsub topics | [CONTRACT §8](../CAPABILITY_CONTRACT.md), [X01 §8](../cross-cutting/X01-transport.md) |
+| UI chat tab | [M08 §5.3](M08-ui.md) |
+
+---
+
+## 9. Open questions
+
+1. **E2E encryption** — Phase 2. Will use X25519 + ChaCha20-Poly1305. Body encrypted; envelope (sender, recipient, lamport) stays cleartext. Signature still over ciphertext.
+2. **Group chat** — Phase 2.
+3. **Voice notes** — Phase 2, would use `stt.*` for transcript, blob for audio.
+4. **Phone notifications** — Phase 2, requires the relay tier.

docs/M11-embedding.md

@@ -0,0 +1,203 @@
+# M11 — Embedding Service
+
+**Spec version:** v1.0
+**Depends on:** M03 (bus), X04 (config), X03 (observability), `sentence-transformers`, `torch`
+**Depended on by:** M05 (RAG uses embed.text), M06 (marketplace.search uses embed.text)
+
+---
+
+## 1. Responsibility
+
+Provide capabilities `embed.text@1.0` (and Phase 2 `embed.image@1.0`). Wrap one or more embedding backends, register them with the bus, batch incoming requests for throughput.
+
+Embeddings are separated from `llm.*` because their workload is different: small models, high throughput, batchable, often CPU-runnable.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/services/embedding/
+├── __init__.py
+├── service.py             # EmbeddingService
+└── backends.py            # SentenceTransformerBackend, OllamaEmbedBackend (Phase 2)
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `backends.py`
+
+```python
+# hearthnet/services/embedding/backends.py
+from typing import Protocol
+
+class EmbeddingBackend(Protocol):
+    name:        str      # "sentence_transformers" | "ollama" | "hf_api"
+    model:       str      # "BAAI/bge-small-en-v1.5"
+    dim:         int      # 384 for bge-small
+    max_input:   int      # max chars per text
+
+    async def embed(self, texts: list[str], *, normalize: bool = True) -> list[list[float]]: ...
+    async def warm(self) -> None: ...
+    async def close(self) -> None: ...
+    def health(self) -> dict: ...
+
+
+class SentenceTransformerBackend:
+    """Local backend using sentence-transformers + torch."""
+
+    def __init__(self, model: str, device: str = "auto"):
+        """device: 'auto' picks cuda if available else cpu."""
+
+    async def embed(self, texts, *, normalize=True): ...
+    async def warm(self): ...
+    async def close(self): ...
+    def health(self): ...
+```
+
+### 3.2 `service.py`
+
+```python
+# hearthnet/services/embedding/service.py
+class EmbeddingService:
+    name    = "embedding"
+    version = "1.0"
+
+    def __init__(self, config: EmbeddingConfig):
+        self._backend: EmbeddingBackend = SentenceTransformerBackend(
+            model=config.model, device=config.device
+        )
+
+    def capabilities(self) -> list[tuple[CapabilityDescriptor, Callable, ParamsPredicate]]:
+        """Returns one entry for embed.text@1.0."""
+
+    async def start(self) -> None: ...
+    async def stop(self) -> None: ...
+    def health(self) -> dict: ...
+
+    # --- handler ---
+
+    async def handle_embed_text(self, req: RouteRequest) -> dict:
+        """Implements embed.text@1.0 (CONTRACT §4.3)."""
+```
+
+### 3.3 Capability descriptor (`embed.text@1.0`)
+
+```python
+descriptor = CapabilityDescriptor(
+    name="embed.text",
+    version=(1, 0),
+    stability="stable",
+    request_schema={
+        "type": "object",
+        "required": ["params", "input"],
+        "properties": {
+            "params": {"type": "object", "properties": {
+                "model": {"type": "string"},
+            }, "required": ["model"]},
+            "input": {"type": "object", "required": ["texts"], "properties": {
+                "texts":     {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 256},
+                "normalize": {"type": "boolean", "default": True},
+            }},
+        },
+    },
+    response_schema={
+        "type": "object",
+        "required": ["output", "meta"],
+        "properties": {
+            "output": {"type": "object", "required": ["embeddings", "dim"], "properties": {
+                "embeddings": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}},
+                "dim":        {"type": "integer"},
+            }},
+            "meta":   {"type": "object", "required": ["model", "ms"]},
+        },
+    },
+    stream_schema=None,
+    params={"model": "<from backend>"},
+    max_concurrent=8,
+    trust_required="member",
+    timeout_seconds=15,
+    idempotent=True,
+)
+```
+
+### 3.4 `params_compatible` predicate
+
+```python
+def params_compatible(offered: dict, requested: dict) -> bool:
+    # request must specify model; must match offered exactly
+    return requested.get("model") == offered.get("model")
+```
+
+---
+
+## 4. Behaviour
+
+### 4.1 Batching (optional optimisation; Phase 1.5)
+
+If multiple requests arrive within a small window (e.g. 20 ms), combine their `texts` arrays into one backend call. Demultiplex results back. MVP: no batching (per-request), simpler.
+
+### 4.2 Validation
+
+- > 256 texts → `bad_request`
+- Any text > 8192 chars → `bad_request`
+- Unknown model → `not_found` (model not loaded; consider asking another node)
+
+### 4.3 Resource sizing
+
+`max_concurrent = 8` is a sensible default on CPU. On GPU, increase via subclass that overrides `max_concurrent`. The number is declared in the manifest so the bus can throttle correctly.
+
+---
+
+## 5. Errors
+
+Only the universal codes from [CONTRACT §9](../CAPABILITY_CONTRACT.md):
+- `bad_request` — texts too long, too many, etc.
+- `not_found` — model not loaded
+- `internal_error` — backend crash
+
+---
+
+## 6. Configuration
+
+From [X04 §3](../cross-cutting/X04-config.md):
+
+```python
+config.embedding.model   # "BAAI/bge-small-en-v1.5"
+config.embedding.device  # "auto"
+```
+
+---
+
+## 7. Tests
+
+### Unit
+- `test_descriptor_schema_validates_meta_schema`
+- `test_handler_rejects_oversized_text`
+- `test_handler_rejects_too_many_texts`
+- `test_params_compatible_exact_model_match`
+- `test_embed_normalises_to_unit_length`
+
+### Integration
+- `test_rag_calls_embed_via_bus` — RAG ingests, embeds via bus.call(), no direct service-to-service import
+- `test_remote_embed_fallback` — local backend not loaded, bus routes to peer
+
+---
+
+## 8. Cross-references
+
+| What | Where |
+|------|-------|
+| `embed.text@1.0` wire spec | [CONTRACT §4.3](../CAPABILITY_CONTRACT.md) |
+| Service protocol | [M03 §4](M03-bus.md) |
+| Consumed by RAG | [M05 §5](M05-rag.md) |
+| Consumed by marketplace.search | [M06 §5](M06-marketplace.md) |
+
+---
+
+## 9. Open questions
+
+1. **Phase 2 `embed.image@1.0` (CLIP)** — adds an image backend; `params` includes modality. Reserved.
+2. **Batching policy** — measured trade-off; deferred. Defaults to immediate dispatch in MVP.

docs/M12-cli.md

@@ -0,0 +1,394 @@
+# M12 — CLI
+
+**Spec version:** v1.0
+**Depends on:** X04 (config), M01 (identity), M03 (bus, via IPC), X03 (observability for doctor), `click`
+**Depended on by:** Users; packaging
+
+---
+
+## 1. Responsibility
+
+Provide the `hearthnet` command. Each subcommand is small, scriptable, exit-code-correct. The CLI either:
+
+- Runs in **standalone mode**: does not need a running node (init, doctor on cold disk, export, erase)
+- Talks to a **running node** over local HTTP (`status`, `caps`, `log`, `trace`), bypassing the UI
+
+The CLI never imports a service module. For node-state queries it uses the bus's HTTP API on `127.0.0.1:7080` like any other client.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/
+├── cli.py              # Click app, all subcommands
+├── __main__.py         # `python -m hearthnet` → cli.main()
+└── doctor.py           # re-export from X03 for `hearthnet doctor`
+```
+
+Installed as console script in `pyproject.toml`:
+
+```toml
+[project.scripts]
+hearthnet = "hearthnet.cli:main"
+```
+
+---
+
+## 3. Subcommands
+
+### 3.1 `hearthnet init`
+
+```
+hearthnet init [--name NAME] [--profile PROFILE] [--non-interactive]
+```
+
+Bootstraps a new node:
+
+1. Resolves XDG paths, creates dirs
+2. Generates keypair if absent (M01)
+3. Writes default `config.toml`
+4. Interactive prompts (unless `--non-interactive`):
+   - Display name
+   - Profile (auto-detected from hardware)
+   - Create or join community
+5. If create: builds genesis community manifest, writes it, prints invite QR to terminal (Unicode block art) and saves PNG
+6. If join: prompts for invite text, redeems
+
+Exits 0 on success, 2 on user abort, 1 on error.
+
+### 3.2 `hearthnet run`
+
+```
+hearthnet run [--config PATH] [--no-ui] [--debug]
+```
+
+Starts the node:
+
+1. Loads config (X04)
+2. Configures observability (X03)
+3. Loads keypair (M01) — refuses if missing
+4. Verifies community manifest present — if not, redirects to init
+5. Composes the node (see [`node.py` in the package layout](#5-the-orchestrator-nodepy))
+6. Blocks until SIGINT / SIGTERM
+
+`--no-ui` skips Gradio (useful for headless anchor / RPi).
+`--debug` raises log level to debug.
+
+### 3.3 `hearthnet status`
+
+```
+hearthnet status [--json]
+```
+
+Connects to local node at `127.0.0.1:7080`. Reports:
+
+- Our node ID + display name + profile
+- Community ID + name + member count
+- Online state (online/degraded/offline) + duration in this state
+- Peers visible (count + summaries)
+- Registered local capabilities (count + names)
+- In-flight calls
+- Event log head Lamport
+- Disk usage (blobs + events)
+
+Exits 0 if reachable, 3 if not reachable, 1 on bad response.
+
+### 3.4 `hearthnet caps`
+
+```
+hearthnet caps [--remote-only | --local-only] [--name PATTERN]
+```
+
+Lists capability entries. Columns: `name`, `version`, `stability`, `node`, `model/params`, `health`, `p50ms`, `in_flight`.
+
+### 3.5 `hearthnet call`
+
+```
+hearthnet call NAME[@VERSION] --body '<json>' [--stream]
+```
+
+Make a one-shot capability call. Useful for scripting and testing.
+
+```
+hearthnet call llm.chat@1.0 --stream \
+  --body '{"params":{"model":"qwen2.5-7b-instruct"},"input":{"messages":[{"role":"user","content":"Hi"}]}}'
+```
+
+Streams to stdout. Non-zero exit code reflects wire error code (mapped: see [CONTRACT §9](../CAPABILITY_CONTRACT.md)).
+
+### 3.6 `hearthnet log`
+
+```
+hearthnet log [--follow] [--level LEVEL] [--component NAME]
+```
+
+Tails the structured log file. With `--follow`, behaves like `tail -F` and filters live.
+
+### 3.7 `hearthnet trace`
+
+```
+hearthnet trace recent [N] [--capability NAME]
+```
+
+Pulls the trace ring buffer via `/trace/recent`. Pretty-prints last N traces.
+
+### 3.8 `hearthnet doctor`
+
+```
+hearthnet doctor [--check NAME]
+```
+
+Runs X03's self-diagnostics (`run_all` or `run_one`). Coloured terminal output:
+
+```
+✔  keys_present          /home/christof/.local/share/hearthnet/keys/device.ed25519
+✔  keys_loadable         Ed25519, 32 bytes
+✘  mdns_socket           Port 5353 in use by avahi-daemon
+     → fix: sudo systemctl stop avahi-daemon
+...
+```
+
+Exit code: 0 if all pass, 1 if any fail, 2 if doctor itself crashed.
+
+### 3.9 `hearthnet export`
+
+```
+hearthnet export [--out PATH]
+```
+
+Exports all local data for this user (GDPR right-to-export):
+
+- Public manifest
+- Our authored events
+- Our chat history
+- Our pinned files (CIDs + filenames)
+- Our marketplace posts
+- Settings (without secrets)
+
+Output: a signed ZIP at `<PATH>` (default `~/hearthnet-export-<date>.zip`).
+
+### 3.10 `hearthnet erase`
+
+```
+hearthnet erase [--keep-keys] [--yes]
+```
+
+Erases local state. Prompts thrice. With `--keep-keys`, retains the device key (allowing rejoin later).
+
+Order of erase:
+
+1. Stop running node (best-effort over IPC)
+2. Wipe `<DATA>/communities/<id>/` (events, manifests, snapshots)
+3. Wipe `<DATA>/blobs/` (unless pinned with `--keep-blobs`)
+4. Wipe `<CACHE>/embeddings/`
+5. Wipe `<LOG>` (unless `--keep-logs`)
+6. Wipe `<DATA>/keys/` unless `--keep-keys`
+7. Print summary
+
+### 3.11 `hearthnet rag`
+
+```
+hearthnet rag list
+hearthnet rag ingest PATH --corpus NAME
+hearthnet rag reindex --corpus NAME [--embedding-model MODEL]
+```
+
+Local CLI for RAG operations. Calls `rag.list_corpora`, `rag.ingest`, and (for reindex) a privileged local-only flow that re-embeds an existing corpus.
+
+### 3.12 `hearthnet invite`
+
+```
+hearthnet invite create --node-id NODEID --level LEVEL --ttl HOURS
+hearthnet invite redeem TEXT_OR_PATH
+```
+
+CLI equivalents of the M13 onboarding flows. Useful for headless anchors.
+
+### 3.13 `hearthnet version`
+
+Prints `__version__`, contract version, Python version, OS. One line.
+
+---
+
+## 4. CLI architecture (Click)
+
+```python
+# hearthnet/cli.py
+import click
+
+@click.group()
+@click.option("--config", type=click.Path(), help="Path to config.toml")
+@click.pass_context
+def main(ctx, config):
+    ctx.obj = load_config(Path(config) if config else None)
+
+@main.command()
+@click.option("--name")
+...
+def init(...): ...
+
+# ... etc. Each subcommand is its own function.
+```
+
+Each command function is < 40 lines and delegates to module-level helpers in the same file. Tests can call the helpers directly without invoking Click runtime.
+
+---
+
+## 5. The orchestrator (`node.py`)
+
+The CLI's `run` subcommand calls into `hearthnet.node.start`. This is not strictly part of M12 but is documented here for completeness because it's the central wiring point.
+
+```python
+# hearthnet/node.py
+async def start(config: Config) -> None:
+    # 1. observability
+    observability.logging.configure(config.observability)
+    observability.metrics.configure(config.observability)
+
+    # 2. identity
+    kp = identity.keys.load_or_generate(config.identity.keys_dir)
+
+    # 3. community check (M13 redirect if missing)
+    if config.community.community_id is None:
+        await onboarding.run_blocking(config, kp)         # writes config; restart cycle
+        return
+
+    # 4. core state
+    event_log = events.EventLog(config.community.state_dir / "events.sqlite",
+                                config.community.community_id)
+    snapshot_store = events.SnapshotStore(config.community.state_dir / "snapshots",
+                                          config.community.community_id)
+    replay_engine = events.ReplayEngine(event_log)
+    community_manifest = identity.manifest.load_or_regenerate(...)
+
+    # 5. blobs
+    blob_store = blobs.BlobStore(config.file.blobs_dir, gc_threshold=config.file.gc_threshold)
+
+    # 6. transport + bus
+    pinned = transport.PinnedCerts(...)
+    http_client = transport.HttpClient(kp, kp.node_id_full, config.community.community_id, pinned)
+    bus = CapabilityBus(kp.node_id_full, config.community.community_id, config.bus,
+                        http_client, lambda: community_manifest)
+
+    # 7. peer registry + discovery
+    peer_registry = discovery.PeerRegistry(kp.node_id_full, config.community.community_id)
+    mdns_announcer = discovery.MdnsAnnouncer(...)
+    mdns_browser   = discovery.MdnsBrowser(peer_registry, config.community.community_id)
+    udp_announcer  = discovery.UdpAnnouncer(...)
+    udp_listener   = discovery.UdpListener(peer_registry, config.community.community_id)
+
+    # 8. services
+    services_list = []
+    if config.embedding:
+        services_list.append(EmbeddingService(config.embedding))
+    if config.llm.backends:
+        services_list.append(LlmService(config.llm))
+    if config.rag.enabled:
+        services_list.append(RagService(config.rag, bus, blob_store, event_log, lambda: community_manifest))
+    if config.file:
+        services_list.append(FileService(config.file, blob_store, event_log))
+    if config.market.enabled:
+        services_list.append(MarketplaceService(config.market, bus, event_log, replay_engine, kp,
+                                                lambda: community_manifest))
+    if config.chat.enabled:
+        services_list.append(ChatService(config.chat, bus, event_log, replay_engine, peer_registry, kp,
+                                         kp.node_id_full))
+
+    for s in services_list:
+        bus.register_service(s)
+        await s.start()
+
+    # 9. emergency detector
+    state_bus = emergency.StateBus()
+    detector  = emergency.Detector(config.emergency, bus, state_bus)
+
+    # 10. transport server
+    http_server = transport.HttpServer(config.transport, kp, bus,
+                                       event_sync=events.SyncServer(event_log),
+                                       community_manifest_provider=lambda: community_manifest)
+
+    # 11. UI
+    ui_app = ui.build_ui(bus, state_bus, config.ui,
+                         node_id_short=kp.node_id_short, community_name=community_manifest.name)
+
+    # 12. wire peer events → bus
+    peer_registry.subscribe(...).on_event(bus.on_peer_added, bus.on_peer_updated, bus.on_peer_removed)
+
+    # 13. periodic manifest publish
+    publisher = ManifestPublisher(kp, community_manifest_provider=...,  bus=bus,
+                                  peer_registry=peer_registry, interval_seconds=MANIFEST_REPUBLISH_INTERVAL_SECONDS)
+
+    # 14. periodic sync
+    syncer = events.SyncClient(event_log, http_client)
+    sync_loop = PeriodicTask(lambda: syncer.run_round(peer_registry), interval_seconds=300)
+
+    # 15. run everything
+    await asyncio.gather(
+        http_server.run(),
+        mdns_announcer.start(), mdns_browser.start(),
+        udp_announcer.run(), udp_listener.run(),
+        detector.run(),
+        publisher.run(),
+        sync_loop.run(),
+        ui_app.launch_async(),
+    )
+```
+
+This is the canonical wiring. Anything that looks different across modules is wrong.
+
+---
+
+## 6. Exit code reference
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Generic error (see stderr) |
+| 2    | User aborted / bad usage |
+| 3    | No running node (for commands needing IPC) |
+| 4    | Auth / signature failure |
+| 5    | Disk full / capacity exceeded |
+
+---
+
+## 7. Configuration
+
+The CLI reads the same `config.toml` as the daemon. `--config` overrides the path.
+
+---
+
+## 8. Tests
+
+### Unit (per subcommand handler)
+- `test_init_writes_config_and_keys`
+- `test_status_against_mock_node_returns_table`
+- `test_call_streams_stdout_then_zero`
+- `test_doctor_exit_code_reflects_failures`
+- `test_erase_keep_keys`
+
+### Integration
+- `test_full_init_then_run_then_status` — spawn subprocess, await readiness, query
+- `test_call_returns_nonzero_on_wire_error`
+- `test_export_zip_is_signed_and_parseable`
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| Self-diagnostics | [X03 §6](../cross-cutting/X03-observability.md) |
+| Onboarding helpers | [M13](M13-onboarding.md) |
+| Bus introspection endpoints | [M03 §3.7](M03-bus.md), [X01 §3.2](../cross-cutting/X01-transport.md) |
+| Trace ring buffer endpoint | [X01 §3.2](../cross-cutting/X01-transport.md), [X03 §5](../cross-cutting/X03-observability.md) |
+| Config | [X04](../cross-cutting/X04-config.md) |
+
+---
+
+## 10. Open questions
+
+1. **Daemon mode on Linux** — `systemd` user unit? Ship one in packaging? Phase 1.5.
+2. **Windows service / macOS LaunchAgent** — Phase 2.
+3. **Shell completion** — Click supports it; ship completions for bash/zsh/fish.
+4. **Progress bars for ingest / fetch** — `rich` progress; nice but optional.

docs/M13-onboarding.md

@@ -0,0 +1,336 @@
+# M13 — Onboarding
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity), M08 (UI), X04 (config), X02 (events, to emit `community.*` events), `qrcode`, `Pillow`
+**Depended on by:** First-run flow in `node.py`; entry point from M08 settings tab
+
+---
+
+## 1. Responsibility
+
+The first time a user runs HearthNet, get them from "downloaded a binary" to "joined a community with a working node" in under two minutes. Specifically:
+
+- Generate a device keypair if not present
+- Offer two paths: **create** new community or **join** existing one
+- Create flow: collect community name + policy, sign genesis manifest, display invite QR
+- Join flow: scan / paste an invite, redeem it, emit `community.member.joined` event
+- Optional: name the device, choose a profile (defaulted from hardware probe)
+
+Out of scope:
+- Federation between communities (Phase 2)
+- Multiple-community membership on one device (Phase 2)
+
+---
+
+## 2. File layout
+
+```
+hearthnet/ui/
+└── onboarding.py        # build_onboarding(), redeem_invite(), invite_to_qr()
+
+hearthnet/identity/
+└── manifest.py          # build_community_manifest() — reused
+```
+
+A standalone `hearthnet init` CLI command in [M12](M12-cli.md) shares the same primitives.
+
+---
+
+## 3. Public API
+
+### 3.1 `onboarding.py`
+
+```python
+# hearthnet/ui/onboarding.py
+from dataclasses import dataclass
+import qrcode
+from io import BytesIO
+
+@dataclass(frozen=True)
+class InviteBlob:
+    """The thing that travels between devices to enable joining."""
+    schema_version: int          # 1
+    community_id:   str          # full
+    community_name: str          # display
+    inviter_node_id: str         # full
+    invitee_node_id: str         # full of the device being invited
+    initial_level:   str         # "member" | "trusted"
+    bootstrap_endpoints: list[Endpoint]   # how to reach the inviter
+    expires_at:     str
+    signature:      str          # inviter's signature over canonical-JSON
+
+# --- encoding ---
+
+def encode_invite(blob: InviteBlob) -> str:
+    """Compact representation suitable for QR / paste. Format:
+    'hearthnet://v1/<base64-url-nopad of canonical-JSON>'.
+    Aim: < 500 bytes (fits standard QR at error level M)."""
+
+def decode_invite(text: str) -> InviteBlob:
+    """Parse + verify signature. Raises OnboardingError on invalid."""
+
+# --- QR ---
+
+def invite_to_qr_png(blob: InviteBlob, *, box_size: int = 8) -> bytes:
+    """Render the invite as a QR PNG. Used by UI for display."""
+
+# --- create flow ---
+
+def create_community(
+    name: str,
+    policy: CommunityPolicy,
+    kp: KeyPair,
+    state_dir: Path,
+    event_log: EventLog,
+) -> CommunityManifest:
+    """1. Build genesis community manifest (root = kp).
+    2. Persist manifest to <state_dir>/manifest.json.
+    3. Append community.created event to event_log.
+    4. Append community.member.invited + .joined for root device.
+    Returns the manifest."""
+
+# --- join flow ---
+
+def make_invite(
+    invitee_node_id_full: str,
+    inviter_kp: KeyPair,
+    community_manifest: CommunityManifest,
+    bootstrap_endpoints: list[Endpoint],
+    initial_level: str = "member",
+    ttl_seconds: int = 86400,
+) -> InviteBlob:
+    """Create + sign an invite blob. Also emit a community.member.invited event."""
+
+def redeem_invite(
+    blob: InviteBlob,
+    our_kp: KeyPair,
+    transport_client: HttpClient,
+    event_log: EventLog,
+) -> CommunityManifest:
+    """1. Verify the invite signature, expiry, that invitee_node_id matches us.
+    2. Connect to one of bootstrap_endpoints; fetch /community/manifest.
+    3. Verify the community manifest's signature chain (root key in invite matches).
+    4. Run an initial X02 sync to populate the event log.
+    5. Emit a community.member.joined event (our authorship) including our node manifest.
+    6. Persist community manifest locally.
+    Returns the manifest. Raises OnboardingError on failure."""
+
+# --- UI builders (Gradio components) ---
+
+def build_onboarding(config: Config, kp_provider: Callable[[], KeyPair]) -> 'gr.Blocks':
+    """Standalone Blocks UI for the first-run flow. Two-step wizard:
+       Step 1: 'Erstmal Schlüssel erzeugen' (auto, with progress)
+       Step 2: choice — create or join
+         - create: form (name, policy options) → preview manifest → confirm → show QR
+         - join:   text area / camera upload for QR → preview invite → confirm → redeem
+       Returns the assembled Blocks. node.py mounts this BEFORE the main UI when
+       config.community.community_id is None."""
+
+class OnboardingError(Exception):
+    """code in {'invite_invalid','invite_expired','invitee_mismatch','bootstrap_unreachable',
+              'community_manifest_invalid','sync_failed','already_member'}"""
+    code: str
+```
+
+---
+
+## 4. Flows in detail
+
+### 4.1 Create-community flow
+
+```
+User clicks "Neue Community gründen"
+  ↓
+Form:
+  • Community name (free text, 1..64 chars)
+  • Allow new members to invite? (default true)
+  • Minimum signatures to revoke a member: 3 (advanced)
+  ↓
+On submit:
+  policy = CommunityPolicy(
+      min_signatures_to_invite = 1,
+      min_signatures_to_demote = 3,
+      min_signatures_to_revoke = 3,
+      capability_token_ttl_seconds = 86400,
+      federation_enabled = True,
+      default_member_can_invite = checkbox_value,
+  )
+  manifest = create_community(name, policy, our_kp, state_dir, event_log)
+  config.community.community_id = manifest.community_id
+  X04.save(config)
+  ↓
+"Du bist Gründer!" panel
+  • Show community short id
+  • Show your role: anchor
+  • Show QR code for inviting first member (preconfigured invite to ANY device)
+    → actually: show a "create invite" button that asks for the invitee's NodeID
+  ↓
+Continue → main UI
+```
+
+### 4.2 Join-community flow
+
+```
+User clicks "Einer Community beitreten"
+  ↓
+"Wie hast du die Einladung erhalten?"
+  • Paste link / text
+  • Upload QR image
+  • Use camera (mobile only)
+  ↓
+decode_invite(text or scan) → InviteBlob
+  • verify signature
+  • check expiry
+  • check invitee_node_id == our_node_id_full
+  ↓
+Preview:
+  • Community name
+  • Inviter display name (lookup via bootstrap_endpoints[0]/manifest)
+  • Initial level: member
+  • "Beitreten" button
+  ↓
+On confirm:
+  redeem_invite(blob, our_kp, transport_client, event_log)
+    → fetch community manifest from bootstrap
+    → run X02 sync to fetch all history
+    → emit community.member.joined event
+    → persist community manifest
+  config.community.community_id = blob.community_id
+  X04.save(config)
+  ↓
+"Willkommen!" → main UI
+```
+
+### 4.3 Inviting someone (post-onboarding, from settings tab)
+
+```
+Settings → "Mitglied einladen"
+  ↓
+Two options:
+  (a) Generate invite for a specific NodeID
+       - user pastes invitee NodeID full form (they got it from their device)
+       - or scans a "I'm a fresh device" QR shown on their screen
+  (b) Use the in-person setup wizard (Phase 2: BLE pairing)
+  ↓
+make_invite(...) → InviteBlob
+  • Emit community.member.invited event (so the rest of the community knows)
+  • Display QR for the invitee to scan
+  • Expires in 24h
+```
+
+### 4.4 "I'm a fresh device" QR
+
+Before joining, a freshly-installed device displays a QR encoding only its `node_id_full` (no signature; this is a public key). The inviter scans this QR with their existing device to build an invite. Format:
+
+```
+hearthnet-id://v1/<base64-url-nopad of {"node_id_full": "...", "display_name": "Hannes' Tablet"}>
+```
+
+This is unsigned because nothing private is in it. The inviter is the source of trust.
+
+---
+
+## 5. Behaviour
+
+### 5.1 First-run detection
+
+`node.py` checks at startup:
+
+```python
+if config.community.community_id is None:
+    # mount onboarding UI; don't start most services yet
+    ...
+else:
+    # normal startup
+```
+
+After the user completes onboarding, `node.py` continues with the full startup sequence (now with a valid community).
+
+### 5.2 Re-onboarding (changing community)
+
+The settings tab has a "Leave community" action. After confirm, the local data for that community is moved to `<DATA>/communities/<id>.archived/` and the user is sent back to onboarding. The user keeps the same keypair unless they explicitly choose to regenerate it (which then makes a new identity).
+
+### 5.3 What we sign and what we don't
+
+| Artifact | Signed by | Why |
+|----------|-----------|-----|
+| Invite blob | Inviter | So invitee can prove this came from a member |
+| Genesis community manifest | Founder (root) | Establishes the root of trust |
+| `community.member.joined` event | The joining device | Asserts "I am here, with this manifest" |
+| Fresh-device ID QR | Nobody | It's just a public key; sees + uses |
+
+### 5.4 Failure modes during join
+
+- Bootstrap endpoints unreachable → `bootstrap_unreachable` with retry option
+- Invite expired → `invite_expired`, must request a new one
+- Invitee mismatch → `invitee_mismatch` (someone tried to redeem someone else's invite)
+- Already a member → `already_member`, no-op with a message
+
+### 5.5 Privacy of invites
+
+An invite contains:
+- Community ID, name
+- Inviter NodeID
+- Invitee NodeID
+- Bootstrap endpoints
+
+It does **not** contain the event log. Anyone seeing an invite knows the community exists and who is who, but not what was said in it.
+
+---
+
+## 6. Errors
+
+`OnboardingError` codes:
+
+- `invite_invalid` — malformed or bad signature
+- `invite_expired` — past TTL
+- `invitee_mismatch` — invite addressed to a different NodeID
+- `bootstrap_unreachable` — can't reach inviter for manifest fetch
+- `community_manifest_invalid` — fetched manifest fails verification
+- `sync_failed` — initial event-log sync failed
+- `already_member` — we're already in this community
+
+---
+
+## 7. Configuration
+
+No new config keys. Uses `config.identity.*` and `config.community.*` from [X04](../cross-cutting/X04-config.md).
+
+---
+
+## 8. Tests
+
+### Unit
+- `test_invite_encode_decode_roundtrip`
+- `test_invite_qr_under_500_bytes`
+- `test_invite_expired_rejected`
+- `test_invite_addressed_to_someone_else_rejected`
+- `test_create_community_emits_three_events` (created + invited self + joined self)
+- `test_redeem_invite_results_in_joined_event`
+
+### Integration
+- `test_two_node_join_flow_end_to_end` — node A creates community, generates invite, node B redeems, both see each other as members
+- `test_join_during_partial_partition` — bootstrap unreachable, retry succeeds
+- `test_redeem_then_immediately_sync_marketplace` — historical posts visible after sync
+
+---
+
+## 9. Cross-references
+
+| What | Where |
+|------|-------|
+| Community manifest schema | [CONTRACT §6.2](../CAPABILITY_CONTRACT.md) |
+| `community.*` events | [CONTRACT §7.2](../CAPABILITY_CONTRACT.md) |
+| Identity primitives | [M01](M01-identity.md) |
+| UI integration | [M08 §8.5](M08-ui.md) |
+| CLI `hearthnet init` | [M12 §3](M12-cli.md) |
+| Event log + sync | [X02](../cross-cutting/X02-events.md) |
+
+---
+
+## 10. Open questions
+
+1. **Multi-community membership** — out of scope MVP. Phase 2: same keypair, multiple `<DATA>/communities/<id>/` dirs.
+2. **Recovery if device key lost** — currently impossible (key = identity). Phase 2: "social recovery" via 2-of-3 trusted members re-issuing a re-joined identity.
+3. **BLE pairing** — Phase 2; faster than QR for adjacent devices.
+4. **Camera capture on mobile web** — `getUserMedia` is available; needs HTTPS. Self-signed cert may trip browsers; document workaround.

docs/X01-transport.md

@@ -0,0 +1,379 @@
+# X01 — Transport
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity), X04 (config), X03 (observability), FastAPI, uvicorn, httpx
+**Depended on by:** M03 (bus), M02 (discovery, indirectly), X02 (sync endpoints)
+
+---
+
+## 1. Responsibility
+
+Moves bytes between nodes over HTTP/1.1+TLS. Provides:
+
+- An HTTP server hosting the bus, pubsub, sync, and metrics endpoints
+- An HTTP client with TLS pinning and signature signing
+- Server-Sent Events (SSE) for streaming
+- Backpressure on streams (window-based)
+- Rate limiting per (peer, capability)
+- Self-signed TLS cert generation and pinning
+
+This module knows nothing about *what* it transports. It dispatches calls to the bus, which routes to services.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/transport/
+├── __init__.py
+├── server.py            # FastAPI app factory + lifecycle
+├── client.py            # HttpClient: signed requests, TLS pinning
+├── streams.py           # SSE writer/reader, frame parsing
+├── backpressure.py      # Window-based flow control
+└── tls.py               # Cert load/generate, peer pinning store
+```
+
+---
+
+## 3. HTTP server
+
+### 3.1 Public API
+
+```python
+# hearthnet/transport/server.py
+from fastapi import FastAPI
+from typing import Awaitable, Callable
+
+class HttpServer:
+    def __init__(
+        self,
+        config: TransportConfig,
+        kp: KeyPair,
+        bus: 'CapabilityBus',
+        event_sync: 'SyncServer',
+        community_manifest_provider: Callable[[], CommunityManifest],
+    ):
+        ...
+
+    def app(self) -> FastAPI:
+        """The configured FastAPI app. Used by tests."""
+
+    async def run(self) -> None:
+        """Block, serving until cancelled."""
+
+    async def shutdown(self) -> None: ...
+```
+
+### 3.2 Endpoints (mounted)
+
+| Route | Method | Purpose | Handler |
+|-------|--------|---------|---------|
+| `/bus/v1/call` | POST | Capability call (sync or stream) | bus dispatch |
+| `/manifest` | GET | Current node manifest JSON | identity |
+| `/community/manifest` | GET | Current community manifest | identity |
+| `/sync/v1/heads` | GET | Sync heads | X02 |
+| `/sync/v1/events` | POST | Sync delta | X02 |
+| `/pubsub/v1/subscribe` | GET (long-poll) | Topic subscription | bus pubsub |
+| `/health` | GET | Liveness | observability |
+| `/ready` | GET | Readiness (≥1 capability + ≥1 peer) | observability |
+| `/metrics` | GET | Prometheus | observability |
+| `/trace/recent` | GET | Last N traces (JSON) | observability |
+
+`/mobile/*` for the mobile web client is mounted by [M08](../modules/M08-ui.md) outside transport's concern.
+
+### 3.3 Request lifecycle
+
+```
+HTTP request arrives
+  ↓
+extract X-HearthNet-* headers
+  ↓
+verify signature (M01) using X-HearthNet-From
+  ↓
+check author is a community member (community manifest)
+  ↓
+attach trace (X03) from X-HearthNet-Request-Id
+  ↓
+rate-limit check (this module)
+  ↓
+dispatch to bus.handle_call(capability, version, body, caller)
+  ↓
+return response (or stream)
+```
+
+Failures at each stage emit a typed error matching [CONTRACT §9](../CAPABILITY_CONTRACT.md).
+
+---
+
+## 4. TLS
+
+### 4.1 Cert generation
+
+On first run, generate a self-signed X.509 certificate with:
+
+- Subject CN = `<short_node_id>.hearthnet.local`
+- SAN = `IP:<config.transport.host>` if not 0.0.0.0, else all interfaces
+- Public key derived from the device Ed25519 key (Ed25519 is a TLS 1.3 signature algorithm)
+- Valid for 10 years (covers normal device life)
+
+Cert + key persisted at `<DATA>/tls/server.crt` and `<DATA>/tls/server.key`.
+
+### 4.2 Pinning store
+
+```python
+# hearthnet/transport/tls.py
+class PinnedCerts:
+    """Stores the first-seen TLS cert fingerprint per NodeID.
+       Mismatches on subsequent connections raise a warning and refuse the connection."""
+
+    def __init__(self, db_path: Path): ...
+    def record(self, node_id: str, fingerprint: bytes) -> None: ...
+    def expected(self, node_id: str) -> bytes | None: ...
+    def verify(self, node_id: str, presented: bytes) -> bool: ...
+```
+
+### 4.3 Hostname verification
+
+Disabled. We pin to NodeID, not DNS. Peers are referenced by IP+port from manifests.
+
+---
+
+## 5. HTTP client
+
+### 5.1 Public API
+
+```python
+# hearthnet/transport/client.py
+class HttpClient:
+    def __init__(
+        self,
+        kp: KeyPair,
+        node_id: str,
+        community_id: str,
+        pinned_certs: PinnedCerts,
+        timeout_default_seconds: float = RPC_DEFAULT_TIMEOUT_SECONDS,
+    ):
+        ...
+
+    async def call(
+        self,
+        peer: Endpoint,
+        capability: str,
+        version: str,
+        body: dict,
+        *,
+        trace_id: str | None = None,
+        timeout_seconds: float | None = None,
+    ) -> dict:
+        """Sync RPC. Signs request, opens TLS connection (or reuses pinned),
+        sends, awaits response, verifies response signature if present,
+        returns body. Raises CallError on transport / protocol failure."""
+
+    async def stream(
+        self,
+        peer: Endpoint,
+        capability: str,
+        version: str,
+        body: dict,
+        *,
+        trace_id: str | None = None,
+        cancel: asyncio.Event | None = None,
+    ) -> AsyncIterator[Frame]:
+        """Open SSE stream. Yields Frame objects (event_name + data dict).
+        Honours backpressure: sends ACK frames automatically.
+        On cancel: closes connection, server aborts within 200ms."""
+
+    async def close(self) -> None: ...
+
+class CallError(Exception):
+    code: ErrorCode
+    message: str
+    retry_after_ms: int | None
+    alt_capabilities: list[str]
+    alt_nodes: list[str]
+```
+
+### 5.2 Connection management
+
+- One `httpx.AsyncClient` per peer, reused across calls
+- Idle timeout `CONNECTION_IDLE_SECONDS` (60s), then close
+- On disconnect, lazy reconnect on next call
+- Reconnect backoff: exponential, cap `RECONNECT_BACKOFF_CAP_SECONDS` (30s)
+
+### 5.3 Signing
+
+For every outbound request, the client constructs:
+
+```python
+envelope = {
+    "capability": capability,
+    "version":    version,
+    "request_id": trace_id or new_ulid(),
+    "from":       node_id_full,
+    "community":  community_id,
+    "timestamp":  rfc3339_now(),
+    "body":       body,
+}
+sig = kp.sign_bytes(canonical_json(envelope))
+```
+
+Headers set: `X-HearthNet-Capability`, `-Version`, `-Request-Id`, `-From`, `-Community`, `-Timestamp`, `-Signature`.
+
+---
+
+## 6. Streaming
+
+### 6.1 SSE writer (server)
+
+```python
+# hearthnet/transport/streams.py
+class SseWriter:
+    def __init__(self, response: StreamingResponse): ...
+    async def emit(self, event: str, data: dict) -> None: ...
+    async def emit_token(self, token: dict) -> None: ...     # convenience
+    async def emit_progress(self, current: int, total: int, stage: str) -> None: ...
+    async def emit_error(self, code: ErrorCode, **kwargs) -> None: ...
+    async def emit_done(self, **meta) -> None: ...
+    async def emit_ack(self, upto: int) -> None: ...
+    @property
+    def cancelled(self) -> bool: ...
+```
+
+### 6.2 SSE reader (client)
+
+```python
+class SseReader:
+    async def __aiter__(self) -> AsyncIterator[Frame]: ...
+    async def cancel(self) -> None: ...
+
+@dataclass(frozen=True)
+class Frame:
+    event: str        # "token", "chunk", "progress", "ack", "done", "error", "manifest", "ready", ...
+    data:  dict
+    seq:   int        # local sequence number for backpressure
+```
+
+### 6.3 Backpressure
+
+```python
+# hearthnet/transport/backpressure.py
+class FlowControl:
+    """Window-based flow control for one stream."""
+    def __init__(self, window: int = STREAM_WINDOW_FRAMES, ack_interval: int = STREAM_ACK_INTERVAL_FRAMES):
+        ...
+
+    @property
+    def window_used(self) -> int: ...
+    def send(self) -> None: ...           # call before emitting a frame; blocks (await) when full
+    def ack(self, upto: int) -> None: ...
+
+    @property
+    def needs_ack(self) -> bool: ...      # reader checks this; emits ack frame
+```
+
+### 6.4 Cancellation
+
+- Client closes the HTTP connection
+- Server's request task is cancelled
+- Service handler's generator receives `GeneratorExit` (or async equivalent)
+- Service emits final telemetry and exits within 200ms
+- A finally block guarantees resources are freed
+
+---
+
+## 7. Rate limiting
+
+```python
+# hearthnet/transport/__init__.py (or rate_limit.py)
+class RateLimiter:
+    """Token-bucket per (peer, capability) and per peer total."""
+    def __init__(self, config: TransportConfig): ...
+
+    def check(self, peer_node_id: str, capability: str) -> RateCheck:
+        """Returns ok, soft-limited, or hard-limited.
+        Soft → return 429 with retry_after_ms
+        Hard → drop without response (logged + counter)."""
+
+@dataclass(frozen=True)
+class RateCheck:
+    allowed:        bool
+    soft_exceeded:  bool
+    retry_after_ms: int
+```
+
+Limits from constants:
+- `RATE_LIMIT_SOFT_RPS_PER_CAP = 10`
+- `RATE_LIMIT_HARD_RPS_PER_CAP = 100`
+- `RATE_LIMIT_SOFT_RPS_TOTAL = 100`
+- `RATE_LIMIT_HARD_RPS_TOTAL = 1000`
+
+---
+
+## 8. Pub-sub (long-poll)
+
+```python
+# hearthnet/transport/server.py (sub-component)
+class PubSubServer:
+    """In-memory topic registry; long-poll subscribers."""
+
+    async def publish(self, topic: str, payload: dict) -> None: ...
+
+    async def subscribe(self, topic: str, *, last_seq: int = 0, timeout_seconds: float = 30) -> dict:
+        """Long-poll: returns next message or {timeout: true} after timeout_seconds."""
+```
+
+`/pubsub/v1/subscribe?topic=marketplace.post.created&last_seq=0&timeout=30`
+
+WebSocket variant deferred to Phase 2.
+
+---
+
+## 9. Errors
+
+Server returns errors in the format of [CONTRACT §5.4](../CAPABILITY_CONTRACT.md). Client raises `CallError` carrying the same code.
+
+---
+
+## 10. Configuration
+
+From [X04](X04-config.md):
+
+```python
+config.transport.host
+config.transport.port
+config.transport.tls_cert      # optional override
+config.transport.tls_key       # optional override
+```
+
+Constants: `STREAM_WINDOW_FRAMES`, `STREAM_ACK_INTERVAL_FRAMES`, `STREAM_ACK_TIMEOUT_SECONDS`, `RPC_DEFAULT_TIMEOUT_SECONDS`, `CONNECTION_IDLE_SECONDS`, `RECONNECT_BACKOFF_CAP_SECONDS`, `RATE_LIMIT_*`.
+
+---
+
+## 11. Tests
+
+### Unit
+- `test_request_signing_roundtrip` — sign on client, verify on server
+- `test_envelope_canonicalisation` — same input → same signature
+- `test_sse_frame_format` — parses both ways
+- `test_flow_control_blocks_when_full` — `send()` awaits until ack arrives
+- `test_rate_limit_soft_then_hard`
+- `test_tls_pinning_first_seen_then_mismatch`
+
+### Integration
+- `test_two_node_call_roundtrip`
+- `test_stream_with_cancellation`
+- `test_concurrent_streams_share_connection`
+- `test_chaos_packet_loss_30pct` (using `tc`)
+
+---
+
+## 12. Cross-references
+
+| What | Where |
+|------|-------|
+| Wire format | [CONTRACT §5](../CAPABILITY_CONTRACT.md) |
+| Signing rules | [CONTRACT §10](../CAPABILITY_CONTRACT.md), [M01 §3.1](../modules/M01-identity.md) |
+| Bus dispatch | [M03](../modules/M03-bus.md) |
+| Sync endpoints | [X02 §6](X02-events.md) |
+| Pub-sub topics | [CONTRACT §8](../CAPABILITY_CONTRACT.md) |
+| Mobile UI mount point | [M08](../modules/M08-ui.md) |

docs/X02-events.md

@@ -0,0 +1,452 @@
+# X02 — Events
+
+**Spec version:** v1.0
+**Depends on:** M01 (identity), X04 (config), X03 (observability), SQLite (stdlib)
+**Depended on by:** M06 (marketplace), M10 (chat), M03 (bus indirectly), M01 (community manifest regeneration)
+
+---
+
+## 1. Responsibility
+
+The community-wide append-only event log. Provides:
+
+- Durable storage of signed events
+- Lamport clock management
+- Replay into materialised views
+- Snapshots for fast bootstrap
+- Gossip sync between peers
+
+This module knows nothing about *what* an event means semantically (that is each consuming module's concern). It enforces only ordering, signing, and durability.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/events/
+├── __init__.py
+├── log.py             # EventLog: SQLite append + read
+├── lamport.py         # LamportClock
+├── types.py           # Event dataclass + canonical event_type strings
+├── replay.py          # Replay engine for materialised views
+├── snapshot.py        # SnapshotStore: write/read signed snapshots
+└── sync.py            # Gossip sync protocol (heads exchange + delta push)
+```
+
+---
+
+## 3. Public API
+
+### 3.1 `types.py`
+
+```python
+# hearthnet/events/types.py
+from dataclasses import dataclass
+from typing import Any, Literal
+
+EventType = Literal[
+    "community.created",
+    "community.member.invited",
+    "community.member.joined",
+    "community.member.revoked",
+    "community.member.promoted",
+    "community.member.demoted",
+    "community.policy.updated",
+    "node.manifest.updated",
+    "market.post.created",
+    "market.post.updated",
+    "market.post.expired",
+    "chat.message.sent",
+    "chat.message.delivered",
+    "chat.message.read",
+    "file.cid.advertised",
+    "file.cid.unpinned",
+    "rag.document.ingested",
+    "federation.peer.added",      # reserved
+    "federation.peer.removed",    # reserved
+]
+
+@dataclass(frozen=True)
+class Event:
+    schema_version: int           # always 1 in this release
+    event_id:       str           # ULID
+    lamport:        int
+    wall_clock:     str           # RFC 3339
+    community_id:   str
+    author:         str           # NodeID full form
+    event_type:     EventType
+    data:           dict[str, Any]
+    signature:      str
+```
+
+### 3.2 `lamport.py`
+
+```python
+# hearthnet/events/lamport.py
+class LamportClock:
+    """In-memory + persisted Lamport clock for one community.
+
+    On every send: next = ++current
+    On every receive: current = max(current, received) + 1
+    Persisted to SQLite on every change (atomic update inside event insert tx).
+    """
+
+    def __init__(self, conn: sqlite3.Connection, community_id: str):
+        """Loads the current value from the events table head."""
+
+    @property
+    def current(self) -> int: ...
+
+    def tick_for_send(self) -> int:
+        """Returns the next Lamport value AND persists it. Idempotent within a tx."""
+
+    def observe(self, received_lamport: int) -> None:
+        """Update on receive."""
+```
+
+### 3.3 `log.py`
+
+```python
+# hearthnet/events/log.py
+class EventLog:
+    """SQLite-backed append-only event log for one community."""
+
+    def __init__(self, db_path: Path, community_id: str):
+        """Open or create the DB. Creates schema if absent."""
+
+    # -- writing --
+
+    def append_local(self, event_type: EventType, data: dict, author_kp: KeyPair) -> Event:
+        """Mint a new local event: tick Lamport, sign, persist, emit pubsub.
+        Returns the persisted Event."""
+
+    def append_received(self, event: Event) -> bool:
+        """Persist an event received from a peer.
+        Returns True if new, False if duplicate.
+        Verifies signature and ordering; raises EventLogError on invalid."""
+
+    # -- reading --
+
+    def head(self) -> int:
+        """Highest lamport in this community."""
+
+    def get(self, event_id: str) -> Event | None: ...
+
+    def replay(
+        self,
+        *,
+        since_lamport: int = 0,
+        event_types: list[EventType] | None = None,
+        limit: int | None = None,
+    ) -> Iterator[Event]:
+        """Yield events in (lamport, event_id) order."""
+
+    def heads_by_type(self) -> dict[EventType, int]:
+        """Highest lamport per event_type. Used by sync."""
+
+    # -- pubsub fanout (in-process subscribers only) --
+
+    def subscribe(self, event_types: list[EventType] | None = None) -> AsyncIterator[Event]: ...
+
+class EventLogError(Exception):
+    """code in {'invalid_signature','out_of_order','unknown_author','revoked_author','schema_unknown','db_corrupt'}"""
+    code: str
+```
+
+### 3.4 `replay.py`
+
+```python
+# hearthnet/events/replay.py
+class MaterialisedView(Protocol):
+    """Each consuming module implements this to derive its state from the event stream."""
+    def reset(self) -> None: ...
+    def apply(self, event: Event) -> None: ...
+    def snapshot_state(self) -> dict: ...
+    def restore_state(self, state: dict) -> None: ...
+
+class ReplayEngine:
+    def __init__(self, log: EventLog):
+        self.log = log
+        self.views: dict[str, MaterialisedView] = {}
+
+    def register(self, name: str, view: MaterialisedView, event_types: list[EventType]) -> None:
+        """Register a view for replay."""
+
+    def rebuild(self, view_name: str, from_lamport: int = 0) -> None:
+        """Reset view, replay all relevant events from `from_lamport`."""
+
+    def rebuild_all(self) -> None: ...
+
+    def on_event(self, event: Event) -> None:
+        """Apply a single new event to all subscribed views. Called by EventLog.append_*."""
+```
+
+### 3.5 `snapshot.py`
+
+```python
+# hearthnet/events/snapshot.py
+@dataclass(frozen=True)
+class Snapshot:
+    schema_version:  int
+    community_id:    str
+    lamport:         int
+    wall_clock:      str
+    state:           dict          # union of all view snapshot_state() results
+    covers_events_up_to: int
+    signature:       str
+
+class SnapshotStore:
+    def __init__(self, dir_path: Path, community_id: str):
+        """<DATA>/communities/<id>/snapshots/"""
+
+    def latest(self) -> Snapshot | None: ...
+
+    def write(self, snap: Snapshot) -> None:
+        """Write atomically; filename = `<lamport>.bin`."""
+
+    def list(self) -> list[int]:
+        """Lamports of all snapshots on disk, ascending."""
+
+    def prune(self, keep_last_n: int = 7) -> None: ...
+
+def build_snapshot(
+    log: EventLog,
+    engine: ReplayEngine,
+    signing_kp: KeyPair,
+    at_lamport: int | None = None,
+) -> Snapshot:
+    """Walk views, collect snapshot_state(), sign. If at_lamport is None,
+       use head - SNAPSHOT_LAG_LAMPORT."""
+
+def restore_from_snapshot(snap: Snapshot, engine: ReplayEngine, log: EventLog) -> None:
+    """Verify signature; for each view, call restore_state(); then replay events
+       from snap.covers_events_up_to+1 forward to log.head()."""
+```
+
+### 3.6 `sync.py`
+
+```python
+# hearthnet/events/sync.py
+@dataclass(frozen=True)
+class HeadsReport:
+    community_id:  str
+    heads_by_type: dict[EventType, int]
+    head:          int
+
+class SyncClient:
+    """Initiated by one node against a peer."""
+    def __init__(self, log: EventLog, transport_client: HttpClient):
+        ...
+
+    async def sync_with(self, peer_endpoint: Endpoint) -> SyncResult:
+        """1) GET /sync/v1/heads → HeadsReport
+        2) compute missing → POST /sync/v1/events with our missing
+        3) receive their missing
+        4) apply, returns counts"""
+
+class SyncServer:
+    """Bound to the bus transport; exposes /sync/v1/heads and /sync/v1/events."""
+    def __init__(self, log: EventLog):
+        ...
+    async def serve_heads(self) -> HeadsReport: ...
+    async def serve_events(self, events: list[Event]) -> dict: ...
+
+@dataclass(frozen=True)
+class SyncResult:
+    sent_count:     int
+    received_count: int
+    duration_ms:    int
+```
+
+---
+
+## 4. SQLite schema
+
+```sql
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+
+CREATE TABLE IF NOT EXISTS events (
+  event_id        TEXT PRIMARY KEY,           -- ULID
+  community_id    TEXT NOT NULL,
+  schema_version  INTEGER NOT NULL DEFAULT 1,
+  lamport         INTEGER NOT NULL,
+  wall_clock      TEXT NOT NULL,
+  author          TEXT NOT NULL,
+  event_type      TEXT NOT NULL,
+  data            TEXT NOT NULL,              -- JSON
+  signature       TEXT NOT NULL,
+  received_at     TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_lamport
+  ON events(community_id, lamport, event_id);
+
+CREATE INDEX IF NOT EXISTS idx_events_type
+  ON events(community_id, event_type, lamport);
+
+CREATE TABLE IF NOT EXISTS clock (
+  community_id TEXT PRIMARY KEY,
+  lamport      INTEGER NOT NULL
+);
+```
+
+The clock row is updated inside the same transaction as the event insert for atomicity.
+
+---
+
+## 5. Behaviour
+
+### 5.1 Insert flow (local event)
+
+```
+begin tx
+  lamport = clock + 1
+  event_id = ulid()
+  build envelope { ... }
+  sign with author_kp
+  insert into events
+  update clock
+commit
+fan out to in-process subscribers
+fan out to remote pubsub subscribers (best-effort)
+emit log line + metrics
+```
+
+### 5.2 Insert flow (received event)
+
+```
+parse + dataclass validate
+verify signature (M01)
+check author is a current member (read community manifest)
+check event_type ∈ EventType
+if duplicate event_id: return False (no-op)
+begin tx
+  clock = max(clock, event.lamport) + 1
+  insert
+  do NOT bump clock again for this transaction
+commit
+trigger replay engine
+emit log + metrics
+return True
+```
+
+### 5.3 Replay correctness
+
+- All views must be commutative under (lamport, event_id) ordering
+- The view contract is: starting from `reset()`, applying the full ordered event stream produces the same `snapshot_state()` regardless of insertion order at the log layer
+- Tests assert this with property-based testing (hypothesis)
+
+### 5.4 Snapshots
+
+- Auto-built once per day at 03:00 local (configurable; off-peak)
+- Lamport at which snapshot covers: `head - SNAPSHOT_LAG_LAMPORT` (default 1000)
+- Older events not deleted unless `EVENT_LOG_RETENTION_DAYS` is exceeded (default 30 days, post-snapshot)
+
+### 5.5 Sync rules
+
+- Sync runs every 5 minutes (or on demand)
+- During emergency mode, sync runs every 30 seconds with other local nodes only
+- Sync is symmetric and idempotent — running twice causes no double-applies
+
+---
+
+## 6. Gossip sync protocol (wire)
+
+### `GET /sync/v1/heads`
+
+Response:
+
+```json
+{
+  "community_id": "ed25519:...",
+  "head": 4218,
+  "heads_by_type": {
+    "market.post.created": 4218,
+    "chat.message.sent": 4192,
+    "...": 0
+  }
+}
+```
+
+### `POST /sync/v1/events`
+
+Body:
+
+```json
+{
+  "community_id": "ed25519:...",
+  "events": [ /* full Event objects */ ]
+}
+```
+
+Response:
+
+```json
+{
+  "accepted": 17,
+  "rejected": 1,
+  "rejected_reasons": [{"event_id": "...", "reason": "invalid_signature"}],
+  "new_head": 4235
+}
+```
+
+---
+
+## 7. Errors
+
+`EventLogError` codes:
+
+- `invalid_signature` — signature did not validate
+- `out_of_order` — lamport ≤ current AND event_id not novel (very rare; manifests as duplicate)
+- `unknown_author` — author NodeID not in current member list
+- `revoked_author` — author in revoked list at or before the event's lamport
+- `schema_unknown` — `event_type` not in the closed set
+- `db_corrupt` — SQLite integrity check failed
+
+---
+
+## 8. Configuration
+
+From [X04](X04-config.md):
+
+```python
+config.community.state_dir   # <DATA>/communities/<id>
+```
+
+Plus constants from [GLOSSARY.md](../GLOSSARY.md):
+`EVENT_LOG_RETENTION_DAYS`, `SNAPSHOT_LAG_LAMPORT`.
+
+---
+
+## 9. Tests
+
+### Unit
+- `test_lamport_send_increments`
+- `test_lamport_observe_caps_above`
+- `test_append_local_persists_and_signs`
+- `test_append_received_rejects_bad_signature`
+- `test_replay_idempotent` — replay twice → same state
+- `test_replay_order_independence` — Hypothesis-driven, shuffle event arrival order → same end state
+- `test_snapshot_roundtrip` — build, write, read, restore → equal state
+- `test_duplicate_event_id_is_noop`
+
+### Integration
+- `test_two_node_sync_converges` — drift one node, sync, both equal
+- `test_three_way_partition_then_heal` — three nodes, partition into 1+2, partial sync, heal, all equal
+- `test_snapshot_assisted_join` — new node bootstraps from snapshot + recent events faster than full replay
+
+---
+
+## 10. Cross-references
+
+| What | Where |
+|------|-------|
+| Event envelope | [CONTRACT §7.1](../CAPABILITY_CONTRACT.md) |
+| Event types catalogue | [CONTRACT §7.2](../CAPABILITY_CONTRACT.md) |
+| Lamport rules | [CONTRACT §7.3](../CAPABILITY_CONTRACT.md) |
+| Sync protocol on wire | [CONTRACT §7.6](../CAPABILITY_CONTRACT.md) |
+| Marketplace view | [M06 §4](../modules/M06-marketplace.md) |
+| Chat view | [M10 §4](../modules/M10-chat.md) |
+| Community manifest derivation | [M01 §3.2](../modules/M01-identity.md) |
+| Signing | [M01 §3.1](../modules/M01-identity.md) |

docs/X03-observability.md

@@ -0,0 +1,215 @@
+# X03 — Observability
+
+**Spec version:** v1.0
+**Depends on:** X04 (config), stdlib, prometheus_client (optional)
+**Depended on by:** every module that does I/O
+
+---
+
+## 1. Responsibility
+
+Provides logging, metrics, tracing, and self-diagnostics. No module imports `logging` directly; they import `get_logger(__name__)` from this module.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/observability/
+├── __init__.py        # exports: get_logger, metrics, trace, doctor
+├── logging.py         # structured JSON logging
+├── metrics.py         # Prometheus-compatible counters/histograms
+├── tracing.py         # per-request trace IDs + ring buffer
+└── doctor.py          # self-diagnostics
+```
+
+---
+
+## 3. Logging
+
+### 3.1 Public API
+
+```python
+# hearthnet.observability.logging
+
+def configure(config: ObservabilityConfig) -> None:
+    """Install handlers, formatters, rotation. Idempotent. Call once at startup."""
+
+def get_logger(name: str) -> Logger:
+    """Return a stdlib logger configured to emit JSON lines.
+       Convention: name = module's __name__ (e.g. 'hearthnet.bus.router')."""
+
+class JsonFormatter(logging.Formatter):
+    """Renders LogRecords as one-line JSON: ts, level, logger, msg, **extras."""
+```
+
+### 3.2 Conventions
+
+- Use `extra=` to attach structured fields: `log.info("routed", extra={"capability": "llm.chat", "to": node_id, "ms": 12})`
+- Never `f"log message {variable}"` for production diagnostics; use structured fields instead
+- Log levels:
+  - `debug` — internal state, only useful with `--debug`
+  - `info` — meaningful protocol events (manifest received, capability registered, peer joined)
+  - `warning` — recoverable problem (signature failed, peer unreachable, quarantine)
+  - `error` — unexpected failure (exception caught, service crash)
+- Exceptions: always `log.exception("what happened", extra={...})` — captures traceback automatically
+- Rate-limit noisy warnings: `RateLimitedLogger` wrapper, log at most once per second per (logger, message_key)
+
+### 3.3 On-disk format
+
+```json
+{"ts":"2026-05-26T08:14:22.281Z","level":"info","logger":"hearthnet.bus.router","msg":"routed","trace_id":"01HXR...","capability":"llm.chat","to":"7H4G-...","ms":12}
+```
+
+One line per event. Files rotate daily at midnight UTC. Retention: `LOG_RETENTION_DAYS = 14` from constants.
+
+---
+
+## 4. Metrics
+
+### 4.1 Public API
+
+```python
+# hearthnet.observability.metrics
+
+def configure(config: ObservabilityConfig) -> None:
+    """Set up registries, start the metrics endpoint if enabled."""
+
+# Counter / histogram / gauge factory functions:
+def counter(name: str, doc: str, labels: list[str] = []) -> Counter
+def histogram(name: str, doc: str, labels: list[str] = [], buckets: list[float] | None = None) -> Histogram
+def gauge(name: str, doc: str, labels: list[str] = []) -> Gauge
+
+# Convenience for "everything else returns None when metrics disabled":
+def disabled() -> bool
+```
+
+### 4.2 Standard metric set
+
+```
+hearthnet_requests_total{capability, result}                     counter
+hearthnet_request_duration_ms{capability, quantile}              histogram
+hearthnet_active_streams{capability}                             gauge
+hearthnet_nodes_online{community}                                gauge
+hearthnet_event_log_size{community}                              gauge
+hearthnet_event_log_lamport_head{community}                      gauge
+hearthnet_emergency_mode{state}                                  gauge   // 0 or 1
+hearthnet_blob_storage_bytes                                     gauge
+hearthnet_llm_tokens_generated_total{model, backend}             counter
+hearthnet_llm_concurrent{model}                                  gauge
+hearthnet_capability_health_success_rate{capability, node}       gauge
+hearthnet_rate_limited_total{capability, reason}                 counter
+hearthnet_signature_failures_total{reason}                       counter
+```
+
+### 4.3 Scrape endpoint
+
+`GET /metrics` on the transport server (port 7080). Plain text, Prometheus format. No auth — same trust domain as the rest of the bus.
+
+---
+
+## 5. Tracing
+
+### 5.1 Public API
+
+```python
+# hearthnet.observability.tracing
+
+class Trace:
+    trace_id:   str
+    capability: str
+    started_at: float       # monotonic seconds
+    spans:      list[Span]
+
+@contextmanager
+def span(name: str, **extras) -> Iterator[Span]:
+    """Open a sub-span on the current trace. Auto-closes."""
+
+def new_trace(capability: str) -> Trace:
+    """Start a new trace (typically at the top of a capability handler)."""
+
+def current_trace() -> Trace | None:
+    """Get the trace attached to the current asyncio task."""
+
+def attach(trace: Trace) -> None:
+    """Attach a trace to the current task. Used by transport when it receives a request with an X-HearthNet-Request-Id."""
+
+def detach() -> None:
+    """End the trace; record to the ring buffer; emit done log."""
+
+def get_recent(n: int = 100) -> list[Trace]:
+    """Return last N completed traces from the ring buffer (used by /trace endpoint)."""
+```
+
+### 5.2 Storage
+
+Ring buffer in memory, `TRACE_RING_BUFFER = 10000` from constants. Optionally exported to OpenTelemetry in Phase 2.
+
+### 5.3 Trace IDs are ULIDs
+
+ULIDs are used because they sort by time and need no separate timestamp field.
+
+---
+
+## 6. Doctor
+
+### 6.1 Public API
+
+```python
+# hearthnet.observability.doctor
+
+@dataclass
+class CheckResult:
+    name:    str
+    ok:      bool
+    detail:  str
+    fix:     str | None
+
+def run_all(config: Config, bus: CapabilityBus) -> list[CheckResult]:
+    """Run every check; return list of results."""
+
+def run_one(name: str, config: Config, bus: CapabilityBus) -> CheckResult:
+    """Run a single named check."""
+
+# Each check is a registered function:
+def register(name: str, check: Callable[[Config, CapabilityBus], CheckResult]) -> None
+```
+
+### 6.2 Standard checks
+
+| Name | Verifies |
+|------|----------|
+| `keys_present` | Device key file exists, has 0600 permissions |
+| `keys_loadable` | Keys parse as Ed25519 |
+| `community_present` | Community manifest exists |
+| `event_log_writable` | SQLite open and writable |
+| `mdns_socket` | mDNS socket can bind |
+| `udp_multicast` | UDP discovery socket can bind |
+| `transport_port` | Bus port is free or owned by us |
+| `at_least_one_capability` | Bus has registered ≥ 1 capability |
+| `disk_space` | Free space ≥ 1 GB |
+| `clock_sanity` | System clock within ±60s of HTTP-reachable anchor (only when internet up) |
+| `llm_backend_reachable` | At least one LLM backend responds |
+| `recent_error_rate` | Last 100 traces have < 20% error rate |
+
+### 6.3 CLI integration
+
+`hearthnet doctor` runs `run_all`, prints a coloured report, exits non-zero on any failure. See [M12](../modules/M12-cli.md).
+
+---
+
+## 7. Tests
+
+- `test_logger_writes_json_lines` — assert each line parses as JSON with expected fields
+- `test_metrics_endpoint_format` — Prometheus text format conforms
+- `test_trace_context_propagation` — `attach`/`detach` round-trips across `asyncio.gather`
+- `test_doctor_all_pass_on_default_config` — `run_all` returns all-OK on fresh init
+- `test_doctor_keys_missing` — failure case for `keys_present`
+
+---
+
+## 8. References
+
+- Config: [X04 §3](X04-config.md)
+- Trace IDs propagate via [CONTRACT §5.1](../CAPABILITY_CONTRACT.md) `X-HearthNet-Request-Id`
+- Bus emits trace events: [M03 §5.6](../modules/M03-bus.md)

docs/X04-config.md

@@ -0,0 +1,273 @@
+# X04 — Configuration
+
+**Spec version:** v1.0
+**Depends on:** stdlib only
+**Depended on by:** every module
+
+---
+
+## 1. Responsibility
+
+Single source of runtime configuration. Loads from disk, validates, and exposes a typed `Config` object. No module reads environment variables, files, or CLI flags directly — they all read from a `Config` instance handed to them.
+
+---
+
+## 2. File layout
+
+```
+hearthnet/
+├── config.py        # implementation
+└── constants.py     # immutable numeric constants (from GLOSSARY.md §Defaults)
+```
+
+`config.toml` lives at `<CONFIG>/config.toml` (see [GLOSSARY.md](../GLOSSARY.md) for path resolution).
+
+---
+
+## 3. The Config object
+
+```python
+# hearthnet/config.py
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+@dataclass(frozen=True)
+class IdentityConfig:
+    """Where keys live, and whether to auto-generate if missing."""
+    keys_dir:     Path                        # <DATA>/keys
+    auto_generate: bool = True
+
+@dataclass(frozen=True)
+class CommunityConfig:
+    """Which community this node belongs to, and where its state lives."""
+    community_id: Optional[str] = None        # None → must run `hearthnet init`
+    state_dir:    Path = Path()               # <DATA>/communities/<id>
+
+@dataclass(frozen=True)
+class TransportConfig:
+    host: str = "0.0.0.0"
+    port: int = 7080
+    tls_cert: Optional[Path] = None           # None → self-signed
+    tls_key:  Optional[Path] = None
+
+@dataclass(frozen=True)
+class DiscoveryConfig:
+    mdns_enabled: bool = True
+    udp_enabled:  bool = True
+    udp_multicast_group: str = "239.255.42.42"
+    udp_port: int = 42424
+    relay_urls:   list[str] = field(default_factory=list)   # Phase 2
+
+@dataclass(frozen=True)
+class BusConfig:
+    prefer_local: bool = True
+    local_load_threshold: float = 0.80
+
+@dataclass(frozen=True)
+class LlmBackendConfig:
+    name:  str                                # "llama_cpp" | "ollama" | "lmstudio" | "hf_api" | "anthropic_api"
+    url:   Optional[str] = None
+    model: Optional[str] = None
+    api_key_env: Optional[str] = None         # env var name; the actual key is never stored in config
+
+@dataclass(frozen=True)
+class LlmConfig:
+    backends: list[LlmBackendConfig] = field(default_factory=list)
+
+@dataclass(frozen=True)
+class EmbeddingConfig:
+    model: str = "BAAI/bge-small-en-v1.5"
+    device: str = "auto"                      # "cpu" | "cuda" | "auto"
+
+@dataclass(frozen=True)
+class RagConfig:
+    enabled: bool = True
+    corpora_dir: Path = Path()                # <CACHE>/embeddings
+
+@dataclass(frozen=True)
+class FileConfig:
+    blobs_dir: Path = Path()                  # <DATA>/blobs
+    gc_threshold: float = 0.80
+
+@dataclass(frozen=True)
+class MarketConfig:
+    enabled: bool = True
+    default_ttl_seconds: int = 86400 * 7      # 7 days
+    max_ttl_seconds:     int = 86400 * 30
+
+@dataclass(frozen=True)
+class ChatConfig:
+    enabled: bool = True
+    store_and_forward: bool = True
+
+@dataclass(frozen=True)
+class EmergencyConfig:
+    probe_targets: list[str] = field(default_factory=lambda: [
+        "1.1.1.1", "8.8.8.8", "cloudflare.com", "quad9.net"
+    ])
+
+@dataclass(frozen=True)
+class UiConfig:
+    host: str = "127.0.0.1"
+    port: int = 7860
+    launch_browser: bool = True
+
+@dataclass(frozen=True)
+class ObservabilityConfig:
+    log_level: str = "info"
+    log_dir:   Path = Path()                  # <LOG>
+    metrics_enabled: bool = True
+    otlp_endpoint: Optional[str] = None       # Phase 2
+
+@dataclass(frozen=True)
+class Config:
+    identity:      IdentityConfig
+    community:     CommunityConfig
+    transport:     TransportConfig
+    discovery:     DiscoveryConfig
+    bus:           BusConfig
+    llm:           LlmConfig
+    embedding:     EmbeddingConfig
+    rag:           RagConfig
+    file:          FileConfig
+    market:        MarketConfig
+    chat:          ChatConfig
+    emergency:     EmergencyConfig
+    ui:            UiConfig
+    observability: ObservabilityConfig
+```
+
+---
+
+## 4. Public API
+
+### `load(path: Path | None = None) -> Config`
+
+Loads from `path` if given, otherwise from the platform-standard location. Applies defaults for omitted sections. Validates and returns a frozen `Config`.
+
+Raises:
+- `ConfigError("invalid_toml")` — TOML parse failure
+- `ConfigError("invalid_field", field=...)` — type or value validation
+- `ConfigError("path_resolution")` — XDG resolution failed (e.g. read-only filesystem)
+
+### `default_config() -> Config`
+
+Returns a Config populated entirely from defaults. Used by tests and `hearthnet init`.
+
+### `save(config: Config, path: Path | None = None) -> None`
+
+Serialises a Config to TOML and writes atomically (write to tempfile, rename). Used by `hearthnet init`.
+
+### `resolve_paths(config: Config) -> Config`
+
+Resolves empty `Path()` fields to their canonical XDG locations. Called by `load()` automatically. Idempotent.
+
+### `validate(config: Config) -> None`
+
+Cross-field validation (e.g. transport port not equal to udp port). Raises `ConfigError` on failure. Called by `load()`.
+
+### `ConfigError(Exception)`
+
+```python
+class ConfigError(Exception):
+    def __init__(self, code: str, **details):
+        self.code = code
+        self.details = details
+        super().__init__(f"{code}: {details}")
+```
+
+---
+
+## 5. Default config.toml
+
+```toml
+[identity]
+auto_generate = true
+
+[community]
+# community_id is set by `hearthnet init`
+
+[transport]
+host = "0.0.0.0"
+port = 7080
+
+[discovery]
+mdns_enabled = true
+udp_enabled  = true
+
+[bus]
+prefer_local = true
+local_load_threshold = 0.8
+
+[[llm.backends]]
+name  = "lmstudio"
+url   = "http://192.168.188.25:1234"
+model = "qwen2.5-7b-instruct"
+
+[embedding]
+model  = "BAAI/bge-small-en-v1.5"
+device = "auto"
+
+[rag]
+enabled = true
+
+[file]
+gc_threshold = 0.8
+
+[market]
+enabled = true
+default_ttl_seconds = 604800
+max_ttl_seconds = 2592000
+
+[chat]
+enabled = true
+store_and_forward = true
+
+[ui]
+host = "127.0.0.1"
+port = 7860
+launch_browser = true
+
+[observability]
+log_level = "info"
+metrics_enabled = true
+```
+
+---
+
+## 6. Cross-cutting constants
+
+`hearthnet/constants.py` holds the values from [GLOSSARY.md §Defaults](../GLOSSARY.md). These are NOT configurable. Examples:
+
+```python
+MANIFEST_TTL_SECONDS                   = 30
+MANIFEST_REPUBLISH_INTERVAL_SECONDS    = 20
+EMERGENCY_PROBE_INTERVAL_ONLINE        = 10
+EMERGENCY_PROBE_INTERVAL_OFFLINE       = 2
+STREAM_WINDOW_FRAMES                   = 16
+CHUNK_SIZE_BYTES                       = 262144
+HEALTH_WINDOW_CALLS                    = 100
+HEALTH_QUARANTINE_THRESHOLD            = 0.5
+HEALTH_QUARANTINE_SECONDS              = 60
+# ... see GLOSSARY.md for the complete list
+```
+
+Rationale for non-configurability: these affect interop. A node tweaking `MANIFEST_TTL_SECONDS` will desync from the network.
+
+---
+
+## 7. Tests
+
+- `test_default_config_round_trips` — `save(default_config()); load()` returns equal config
+- `test_invalid_toml_raises` — malformed TOML → `ConfigError("invalid_toml")`
+- `test_missing_required_field_raises` — community section without `community_id` is OK (post-init); but other validations apply
+- `test_path_resolution_xdg` — empty paths resolve to user_data_dir, etc.
+- `test_env_var_substitution` — `${ENV_VAR}` in TOML strings is expanded by `load()`
+
+---
+
+## 8. References
+
+- Constants list: [GLOSSARY.md](../GLOSSARY.md) §Defaults
+- Used by all modules; this is the universal entry point