docs/prd_v2.md

# HearthNet — Technical PRD v2

**Distributed neighbourhood AI mesh**
*Resilient, community-owned local AI infrastructure that survives internet outages.*

---

| | |
|---|---|
| **Status** | Draft v2 — supersedes v1  |
| **Author** | Christof |
| **Target** | Gradio Winter '25 Hackathon submission + post-hackathon product roadmap |
| **License (planned)** | AGPLv3 for the kernel, MIT for clients |
| **Repo (planned)** | github.com/Chris4K/hearthnet |
| **Demo (planned)** | huggingface.co/spaces/Chris4K/hearthnet-demo |

---

## 0. The 2-minute pitch

Imagine the internet cable in your neighbourhood gets cut. Right now, that means no Google, no ChatGPT, no maps, no marketplace, no messaging. The cloud goes silent and you're alone with whatever's on your phone.

HearthNet changes that. It's a local AI mesh that turns the computers already in your neighbourhood — your gaming PC, your neighbour's old laptop, the Raspberry Pi in someone's attic — into a shared, resilient AI cooperative. Discovery is automatic. You don't configure anything. You open the app, it finds the nodes nearby, you ask a question. The answer is generated locally, on someone's GPU, three streets away.

When the internet is up, it federates with the cloud. When the internet drops, you don't even notice — the system switches to local mode, and the AI, the file library, the neighbourhood marketplace, and the local chat all keep working.

The architecture is built around one idea: a **capability bus**. Every node announces what it can do — run inference, store files, hold a vector index, relay messages. Every request finds the best node for the job. New service? Plug it in. New transport — LoRa, mesh radio? Plug it in below. The kernel stays small. The system gets stronger as the community grows.

For the hackathon, we demo the full loop live: a mesh of three real nodes on stage, LLM routing across them, RAG over an emergency PDF library, a community marketplace, and a clean fail-over when we unplug the WAN cable. Phase 2 brings real-distance transports and federated learning across communities. Phase 3 explores actual distributed inference.

The cloud owns AI today. HearthNet is the bet that communities will own it tomorrow.

---

## 1. Executive summary

HearthNet is a peer-to-peer software stack that lets a small number of devices on the same network (or, later, the same neighbourhood) discover each other, share compute and storage, and provide AI services to each other and to thin clients. The system is designed to keep working when the wider internet does not.

The technical core is a **capability bus**: a small, transport-agnostic routing layer that knows which nodes can fulfil which request, picks the best one, enforces a schema contract, handles backpressure, and reports health. Everything else — the LLM, the RAG, the file share, the marketplace, the UI — is a plug-in.

The MVP is a single-binary Python application that runs on Linux, macOS, and Windows, exposes a Gradio web UI on `localhost:7860`, joins a LAN mesh via mDNS, and uses llama.cpp or Ollama for inference. The demo runs on three machines: a workstation with a GPU, a laptop, and a Raspberry Pi acting as a thin client.

Post-hackathon the project has three viable commercial paths: retail-continuity offering, a municipal/civil-defence pilot in NRW, and a "HearthNet-in-a-Box" appliance for community groups.

---

## 2. Vision & positioning

### 2.1 The problem we're solving

Modern households are now utterly dependent on cloud AI. The same is increasingly true for businesses, schools, and emergency services. When the cable, the DSL line, or the cloud provider drops, productivity stops. Communities have no fallback.

At the same time, the average household has multiple idle computers — a gaming PC at 5% utilisation, a workstation that runs Slack, an old laptop in a drawer. Aggregated across a neighbourhood, this is a non-trivial amount of compute. None of it cooperates today.

### 2.2 What HearthNet is

A peer-to-peer, local-first AI fabric that:

- Discovers nodes automatically on the local network
- Routes AI/data requests to the best available node
- Tolerates partitions, internet outages, and node churn
- Federates with the cloud when available, falls back gracefully when not
- Is owned by its participants — no central operator, no telemetry pipeline to a vendor

### 2.3 What HearthNet is not

- Not a replacement for high-end cloud AI on always-online workloads
- Not a competitor to Tor or I2P — anonymity is not a goal
- Not Petals — distributed-tensor inference is an experimental Phase 3 explore, not the core
- Not a blockchain. There are no tokens, no consensus across communities, no incentive design beyond reciprocity
- Not magic. It will not let you run GPT-4-class models on a Raspberry Pi

### 2.4 Differentiation

Most hackathon AI projects today use cloud APIs and are dead the moment the API goes down or runs out of credits. HearthNet's whole point is the opposite: it gets *more* useful as the network gets less reliable.

---

## 3. Goals & non-goals

### 3.1 Primary goals (P0)

- Zero-configuration discovery on a LAN
- Capability-based service routing across nodes
- One real AI service (LLM inference) routed across at least 3 nodes
- One real data service (RAG over a small PDF corpus)
- Persistent local marketplace with offline-tolerant sync
- A clean emergency-mode UX triggered by WAN failure
- A live topology visualisation suitable for stage demo
- Single-binary install on Linux, macOS, Windows

### 3.2 Secondary goals (P1)

- Mobile-friendly client that connects to a host node
- Content-addressed file sharing with chunk-level dedup
- Cross-community federation over the internet when available
- Embedded skill library reuse from existing FORGE work

### 3.3 Stretch goals (P2)

- One experimental Petals-style distributed-layer demo on a small model (1.5B or smaller), as a feature flag
- LoRa beacon for "node alive" pings over distance, no AI traffic
- Translation service for German ↔ English ↔ Plattdeutsch

### 3.4 Explicit non-goals (this release)

- Full distributed-tensor inference for production use
- WireGuard or Tailscale overlay (use plain TLS on LAN)
- Anonymous routing (Tor-style)
- Cryptocurrency, token, or financial-incentive layer
- Sub-millisecond latency for any operation
- Replacing professional emergency-response systems
- Storing personally-identifying data centrally anywhere

---

## 4. The demo loop

The full hackathon demo is one continuous two-minute story, scripted to hit every feature exactly once. Build only what this story needs; everything else is a slide.

### 4.1 Setup on stage

- Three physical machines: workstation with GPU ("**Forge**"), laptop ("**Hearth**"), Raspberry Pi 5 ("**Spark**")
- One travel router with a clearly-visible WAN cable
- All three nodes pre-joined to a community called `niederrhein-demo`
- A pre-loaded RAG corpus: 6 PDFs covering rainwater purification, generator safety, first aid, German civil-defence procedure, and a Sankt-Martin children's song book
- Three pre-populated marketplace posts so the page is not empty on open

### 4.2 The script (~120 seconds)

| t | What happens | What it demonstrates |
|---|---|---|
| 0:00 | Open the Gradio UI on the laptop. Topology shows 3 connected nodes, green | Discovery works |
| 0:10 | Ask: *"Wie reinige ich Regenwasser ohne Strom?"* | LLM + RAG over local PDFs |
| 0:15 | Animated edge from Hearth → Forge → Hearth as the request routes and streams back | Capability routing visible |
| 0:35 | Open marketplace tab, post: *"Suche Wasserkanister, 20L"* | Marketplace + signed events |
| 0:50 | **Yank the WAN cable** | Trigger |
| 0:54 | Banner appears: *"INTERNET OFFLINE — LOKAL AKTIV"*, UI re-skins amber | Emergency mode |
| 1:00 | Same question, different phrasing | Still works, now visibly local |
| 1:20 | Send a chat message to "Frank" (Spark node) — store-and-forward across mesh | Local comms |
| 1:35 | Plug WAN cable back in | Trigger |
| 1:40 | Banner clears, federation event log replays, new cloud-side node appears greying-in | Reconciliation |
| 1:55 | Closing line | — |

### 4.3 Design implications of the demo

- The topology viz must animate request flow, not just node presence
- The emergency banner must trigger in under 5 seconds
- Marketplace posts must be content-addressed and signed so the rejoin merge has something to demonstrate
- The LLM must stream tokens — silence for 10 seconds while a model loads will lose the room
- A "fake mesh" mode is needed for dry runs (and as a fallback if something dies on stage)

---

## 5. System architecture

### 5.1 Layered model

```
┌──────────────────────────────────────────────────────────────┐
│ L5 — Application                                             │
│      Gradio dashboard · topology viz · emergency UX · mobile │
├──────────────────────────────────────────────────────────────┤
│ L4 — Service plane                                           │
│      LLM · RAG · files · marketplace · chat · embeddings     │
├══════════════════════════════════════════════════════════════┤
│ L3 — CAPABILITY BUS  ← the integration point                 │
│      Registry · router · health · schema · backpressure      │
├══════════════════════════════════════════════════════════════┤
│ L2 — Messaging                                               │
│      RPC · pub-sub · streams · content-addressed chunks      │
├──────────────────────────────────────────────────────────────┤
│ L1 — Identity & discovery                                    │
│      Device keys · signed manifests · mDNS · UDP · DHT later │
├──────────────────────────────────────────────────────────────┤
│ L0 — Physical transport                                      │
│      LAN/WiFi · ethernet · hotspot · internet relay · LoRa   │
└──────────────────────────────────────────────────────────────┘
       Trust & federation (signed community manifests) cross-cut L1–L4
       Observability (logs, traces, metrics) cross-cut all layers
```

### 5.2 Loose coupling, in one rule

> No service knows about a transport. No transport knows about a service. Both speak only to the capability bus.

This is the only structural rule that matters. If a feature requires a service to import a transport module, the design is wrong and the feature should be redesigned to register a new capability instead.

### 5.3 Process model

A HearthNet node is **one process** by default. Internally it runs:

- The L1 discovery loop (asyncio task)
- The L2 messaging server (FastAPI on a configurable port, default `:7080`)
- The L3 capability bus
- One or more L4 services as in-process modules registered with the bus
- The L5 Gradio app on a separate port (default `:7860`)

Services *may* run out of process and connect to the bus over local IPC, for sandboxing or because they need a different runtime (e.g. llama.cpp in C++). This is supported but not required for MVP.

### 5.4 Node profiles

| Profile | Hardware | Services it runs | Network role |
|---|---|---|---|
| **Anchor** | GPU workstation, ≥32GB RAM, ≥1TB disk | LLM, RAG, files, marketplace, chat, embeddings | Provider |
| **Hearth** | Laptop, 16GB RAM | RAG, files, marketplace, chat, embeddings | Mixed |
| **Spark** | Raspberry Pi 4/5, mobile, browser | Chat, marketplace UI, file cache | Client |
| **Bridge** | Cloud VM | None inferring, only relay & federation | Relay (Phase 2) |

A node decides its profile at startup based on detected hardware, but the user can override.

---

## 6. Layered specification

### 6.1 L0 — Physical transport

The system runs over whatever IP transport is present. No L0 abstraction is exposed to higher layers beyond "is internet up" and "is LAN up". MVP supports:

- WiFi on the local subnet
- Ethernet
- Mobile hotspot (one node acts as router)
- Internet relay (Phase 2: an HTTPS relay node helps two NAT'd peers reach each other)
- LoRa beacons (Phase 3: one-way "I am alive" pings only, no data)

Heuristics for "is internet up":

1. DNS resolve two unrelated anchors (`1.1.1.1`, `8.8.8.8`)
2. HTTPS HEAD to two unrelated anchors with short timeouts
3. ICMP if available, but never relied on
4. Both must succeed within 3 seconds to count as "up"

The detector runs every 10 seconds when up, every 2 seconds when down (to detect restore quickly).

### 6.2 L1 — Identity & discovery

#### 6.2.1 Device keys

Each node generates an Ed25519 keypair on first run. Stored in `~/.hearthnet/keys/` with `0600` permissions. The private key never leaves the device. The public key is the node's permanent ID.

Display form for humans: first 8 bytes of the public key, base32-encoded, formatted as `XXXX-XXXX-XXXX-XXXX`. Long enough to avoid collisions in a community, short enough to read aloud.

#### 6.2.2 Node manifest

A signed JSON document describing what this node is and what it can do. Re-signed and re-broadcast on any change. Schema in §7.1.

#### 6.2.3 Community manifest

A signed JSON document describing the community: name, root key, members, policies. Signed by the root key (the community founder's device key). New members are added by appending a signed invite event. Schema in §8.3.

#### 6.2.4 Discovery transports

- **mDNS / Zeroconf** — primary, works out of the box on LAN. Service type: `_hearthnet._tcp.local.`
- **UDP broadcast** — secondary, for networks that block mDNS. Multicast group `239.255.42.42:42424`. Payload: a one-line manifest summary
- **DHT (Kademlia)** — Phase 2, for cross-LAN discovery via internet relay
- **LoRa beacon** — Phase 3, for long-distance "this community exists" pings

Discovery flow:

1. Node starts, generates manifest, signs it
2. Broadcasts via all available discovery transports
3. Listens for other manifests
4. For each new node: verify signature against community manifest (if same community), then establish an L2 connection
5. Send a probe RPC: get health, latency, declared capabilities
6. Register the remote capabilities locally with provenance

### 6.3 L2 — Messaging

#### 6.3.1 Wire protocol

Plain HTTP/1.1 over TLS for MVP. Connection per peer, reused. Headers carry capability name, request ID, and signature. Body is JSON (or binary for chunks). Streaming responses use Server-Sent Events.

Phase 2 considers HTTP/3 (QUIC) for better mobile and lossy-link behaviour, especially for streamed token output. The capability bus does not care which is used.

#### 6.3.2 Message types

- **Request/reply** — one-shot RPC, standard pattern
- **Stream** — server-streams a sequence of frames (LLM tokens, file chunks, progress events)
- **Pub-sub** — fire-and-forget event topic with subscription, used for manifest updates and marketplace events
- **Chunk transfer** — bulk binary, content-addressed, may be parallel from multiple sources

#### 6.3.3 Content-addressed storage

Files larger than 64KB are split into 256KB chunks. Each chunk is hashed with BLAKE3. The file is described by a small **manifest** listing chunk CIDs and the merkle root.

Nodes advertise which CIDs they hold. When a node needs a file, it asks the bus for sources by CID, then fetches chunks in parallel.

#### 6.3.4 Backpressure

Every stream has a flow-control window (frames-in-flight). Servers stop sending when the window is full; clients refresh the window with ACK frames. Default window: 16 frames. Token streams use this so a slow client doesn't blow up server memory.

#### 6.3.5 Retries

Idempotent requests retry up to 3 times with exponential backoff. Non-idempotent requests (anything mutating, e.g. marketplace post) carry a client-generated UUID so the server can dedupe.

### 6.4 L3 — Capability bus

This is the part of the system that justifies the whole project. Spec in §11.

### 6.5 L4 — Service plane

Each service is a Python module that implements a small interface:

```python
class Service(Protocol):
    name: str
    version: str
    def capabilities(self) -> list[CapabilityDescriptor]: ...
    async def handle(self, capability: str, payload: dict) -> dict | AsyncIterator[dict]: ...
```

Services in §12.

### 6.6 L5 — Application plane

The Gradio web UI is the primary interface for MVP. Mobile is a thin web client (no native app for hackathon). The dashboard is the only UI surface — there is no separate admin interface. Power users get a CLI (`hearthnet status`, `hearthnet capability list`, etc.).

---

## 7. Capability contract — the key abstraction

This is the most important section. If anything in this PRD is wrong, fix this last. If anything is right, build this first.

### 7.1 Node manifest schema

```json
{
  "version": 1,
  "node_id": "ed25519:7H4G-Y9KL-2P3M-X8QR",
  "display_name": "garage-pc",
  "community_id": "ed25519:NIEDERRHEIN-DEMO-...",
  "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",
      "params": {
        "model": "qwen2.5-7b-instruct",
        "quant": "q4_k_m",
        "ctx": 8192,
        "modality": ["text"]
      },
      "schema_hash": "blake3:..."
    },
    {
      "name": "rag.query",
      "version": "1.0",
      "params": {"corpus": "niederrhein-emergency", "k_max": 20},
      "schema_hash": "blake3:..."
    }
  ],
  "uptime_seconds": 43210,
  "load": {"cpu": 0.12, "vram_used_gb": 6.4},
  "issued_at": "2026-05-26T08:14:22Z",
  "expires_at": "2026-05-26T08:14:52Z",
  "signature": "ed25519:..."
}
```

Notes:

- Manifests **expire** in 30 seconds. A node re-broadcasts before expiry. This is the heartbeat.
- `schema_hash` is the hash of the request/response JSON schema for that capability. Two nodes with the same hash speak the exact same contract.
- `load` is advisory; the router uses it to pick under-loaded nodes.

### 7.2 Capability descriptor schema

```json
{
  "name": "llm.chat",
  "version": "1.0",
  "stability": "stable",
  "request_schema": { /* JSON Schema */ },
  "response_schema": { /* JSON Schema */ },
  "stream": true,
  "params": {
    "model": "qwen2.5-7b-instruct",
    "quant": "q4_k_m",
    "ctx": 8192
  },
  "guarantees": {
    "max_latency_ms_p50": 1200,
    "max_concurrent": 4
  }
}
```

`name` is a dotted namespace (`llm.*`, `rag.*`, `file.*`, `market.*`, `chat.*`, `embed.*`, `ocr.*`, `tts.*`, `stt.*`, `trans.*`).

`version` is semver, but only major.minor — patch is irrelevant on the wire.

`stability` is `experimental`, `beta`, or `stable`. Clients can filter.

### 7.3 Wire format — request

```http
POST /bus/v1/call HTTP/1.1
Host: 192.168.188.25:7080
Content-Type: application/json
X-HearthNet-Capability: llm.chat
X-HearthNet-Capability-Version: 1.0
X-HearthNet-Request-Id: 01HXR8...
X-HearthNet-From: ed25519:CLIENT-NODE-ID
X-HearthNet-Signature: ed25519:...
Accept: application/json, text/event-stream

{
  "params": {"model": "qwen2.5-7b-instruct", "ctx": 8192},
  "input": {
    "messages": [
      {"role": "user", "content": "Wie reinige ich Regenwasser ohne Strom?"}
    ],
    "max_tokens": 512,
    "temperature": 0.7
  }
}
```

### 7.4 Wire format — non-stream response

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-HearthNet-Request-Id: 01HXR8...
X-HearthNet-From: ed25519:SERVER-NODE-ID
X-HearthNet-Signature: ed25519:...

{
  "output": {
    "message": {"role": "assistant", "content": "..."}
  },
  "meta": {
    "tokens_in": 42,
    "tokens_out": 178,
    "ms": 1834,
    "model": "qwen2.5-7b-instruct"
  }
}
```

### 7.5 Wire format — stream response

```http
HTTP/1.1 200 OK
Content-Type: text/event-stream
X-HearthNet-Request-Id: 01HXR8...
X-HearthNet-From: ed25519:SERVER-NODE-ID

event: token
data: {"text":"Sie"}

event: token
data: {"text":" können"}

event: token
data: {"text":" Regenwasser"}

event: done
data: {"tokens_out":3,"ms":380,"signature":"ed25519:..."}
```

### 7.6 Wire format — error

```http
HTTP/1.1 503 Service Unavailable
X-HearthNet-Request-Id: 01HXR8...

{
  "error": "capacity_exceeded",
  "retry_after_ms": 2000,
  "alt_capabilities": ["llm.chat@0.9"],
  "alt_nodes": ["ed25519:OTHER-ANCHOR-NODE-ID"]
}
```

Error codes are a closed set: `not_found`, `capacity_exceeded`, `schema_mismatch`, `unauthorized`, `revoked`, `internal_error`, `not_implemented`, `timeout`, `partition`.

### 7.7 Versioning rules

- Major version bump → breaking change. Old clients must be rejected with `schema_mismatch`.
- Minor version bump → additive. Old clients still work, new fields are optional.
- Two nodes match on capability if `name` matches and `version` major is equal and the requested version minor ≤ offered version minor.
- `schema_hash` is computed from the canonical (sorted-key, no-whitespace) JSON of the request+response schemas. Two nodes with identical hashes can call each other with zero coordination.

### 7.8 Capability discovery flow

1. Client wants to do `llm.chat`
2. Asks local bus: "who offers `llm.chat@>=1.0`?"
3. Bus returns a ranked list of remote nodes that meet the criteria
4. Client picks the top one (or the bus does — see §11)
5. Client sends the request with the chosen node's signature requirement
6. Server validates, executes, replies (or streams)
7. Bus records latency, success/failure, updates ranking

---

## 8. Identity, trust & federation

### 8.1 Trust model in one paragraph

Trust is **community-scoped**. A community has a root key (the founder's device key). Members are added by signed invite events. To join, a new device generates a key, presents its public key to an existing member (in person, via QR code), and receives a signed invite. The invite is a signed event appended to the community log. The new device is now a member. All capability calls within the community are signed; signatures are checked against the community member list.

There are no certificate authorities, no PKI, no chains of trust. This is good enough for a neighbourhood. It is not good enough for the whole internet, and that is fine.

### 8.2 Trust levels

| Level | Meaning | Who can be this |
|---|---|---|
| `unknown` | Just discovered, not in any community | Random discoverable nodes |
| `member` | Signed in to this community | Default for invited devices |
| `trusted` | Marked by 3+ members as trusted | Used for risky capabilities (file delete, federation gateway) |
| `anchor` | Marked by the root key as infrastructure | Always-on, primary providers |

A node's level changes via signed events. Demoting needs more signatures than promoting (3 to demote a `trusted`, 1 to promote to `trusted`).

### 8.3 Community manifest schema

```json
{
  "version": 1,
  "community_id": "ed25519:...",
  "name": "Niederrhein Demo",
  "root_key": "ed25519:...",
  "created_at": "2026-05-26T08:00:00Z",
  "policy": {
    "min_signatures_to_invite": 1,
    "min_signatures_to_demote": 3,
    "capability_token_ttl_seconds": 86400,
    "federation_enabled": true
  },
  "members": [
    {"node_id": "ed25519:...", "level": "anchor", "added_at": "..."},
    {"node_id": "ed25519:...", "level": "member", "added_at": "..."}
  ],
  "signature": "ed25519:..."
}
```

The manifest is the result of replaying the community event log; it is materialised so new nodes don't have to replay everything to join.

### 8.4 Capability tokens

Optional layer for fine-grained delegation. A node can issue a short-lived token allowing a specific other node to make a specific capability call. Used in Phase 2 for federation across communities: community A's anchor signs a token allowing community B's anchor to query its RAG. MVP does not use tokens; signing is per-request.

### 8.5 Revocation

To revoke a member, three other members publish a signed `revoke` event. The community manifest is regenerated. All other nodes update their local copy and refuse to honour signatures from the revoked node going forward.

There is no online revocation list. The community manifest itself is the revocation mechanism.

### 8.6 Federation between communities (Phase 2)

Two communities pair when their root keys cross-sign a federation manifest. Federation grants specific capabilities (e.g. "you may query our RAG, but not our marketplace"). Federated calls travel via a Bridge node or a public relay.

### 8.7 Threat model (MVP)

In scope:

- **Drop-in node**: a random LAN device tries to join; rejected, not a member
- **Stale manifest replay**: old signed manifest re-broadcast; rejected by expiry
- **Single member compromised**: can act as themselves but cannot promote others without colluders; revocable
- **Network observer**: sees who talks to whom; we accept this (no anonymity goal)

Out of scope:

- **Root key compromised**: catastrophic; community must regenerate
- **Sybil at community level**: not protected against — communities are trust roots, not Sybil-resistant
- **Side-channel attacks**: not protected against on shared hardware
- **Malicious model output**: not protected against; this is a content policy problem, not a protocol one

---

## 9. Discovery in detail

### 9.1 mDNS service definition

```
Service type:  _hearthnet._tcp.local.
Instance name: <display_name>-<short_node_id>
Port:          7080
TXT records:
  v=1
  node=<short_node_id>
  community=<short_community_id>
  profile=anchor|hearth|spark|bridge
  caps=llm.chat,rag.query,file.read,...
  manifest_url=https://<host>:<port>/manifest
```

`caps` lists capability names only. Full descriptors are fetched via `manifest_url`.

### 9.2 UDP broadcast format

Plain JSON line, ≤ 1KB, on `239.255.42.42:42424`:

```json
{"v":1,"node":"short_id","community":"short_id","port":7080,"caps":["llm.chat","rag.query"]}
```

Rate: every 5 seconds when discovering, every 30 seconds when stable.

### 9.3 Internet-relay discovery (Phase 2)

A small relay node accepts manifest registrations from communities and serves a "members of community X seen recently" query. Used to bootstrap cross-LAN federation. Anyone can run a relay; communities decide which to trust.

### 9.4 LoRa beacon (Phase 3)

868MHz (EU) or 915MHz (US), short payload: `<community_short_id, node_short_id, seq>`. One way, no AI traffic. Purpose: a phone with a LoRa module knows a HearthNet community exists in range, even with no WiFi.

### 9.5 First-run UX

The first time a user runs HearthNet:

1. Generate device key (silent)
2. Ask: *Create a new community or join existing?*
3. If create: prompt for community name, sign founding manifest. Show a QR code with the community ID and invite policy.
4. If join: prompt for QR scan or invite link. Acquire signed invite from an existing member (in person, via the app). Now a member.

Total time to first useful state: under 60 seconds.

---

## 10. Messaging & transport detail

### 10.1 Connection lifecycle

- Peer discovered via L1
- Bus initiates TLS handshake (self-signed cert, pinned to the node's key on first contact)
- Subsequent connections re-use the pinned cert; mismatch = refused + log
- Idle connections close after 60 seconds
- Failed reconnect uses exponential backoff capped at 30 seconds

### 10.2 Streaming protocol details

LLM token streams use SSE for simplicity (works in browsers, easy to debug, fits HTTP/2). Per-frame format:

```
event: token
data: {"text":"...", "logprobs":[...], "stop":false}

event: token
data: {"text":"...", "stop":false}

event: done
data: {"tokens_out":N, "stop_reason":"end", "ms":M}
```

Clients close the connection to cancel. Servers respect cancellation within 200ms.

### 10.3 Chunk transfer

A file with CID `blake3:abc...` is described by a manifest:

```json
{
  "cid": "blake3:abc...",
  "size": 4824711,
  "chunk_size": 262144,
  "chunks": [
    {"i": 0, "cid": "blake3:..."},
    {"i": 1, "cid": "blake3:..."}
  ]
}
```

A client wanting the file:

1. Asks the bus: who has `blake3:abc...`?
2. Gets a list of source nodes
3. For each chunk, picks a source (round-robin or load-aware), requests it
4. Verifies the chunk hash before accepting
5. Reassembles when all chunks received

This is BitTorrent-lite. About 300 lines of Python. Provides dedup, integrity, and parallel transfer for free.

### 10.4 Pub-sub topics

| Topic | Producer | Consumer | Payload |
|---|---|---|---|
| `community.member.added` | Any member with invite right | All members | Signed invite event |
| `community.member.revoked` | 3 members | All members | Signed revoke event |
| `node.manifest.updated` | Each node | All members | Updated node manifest |
| `marketplace.post.created` | Posting member | All members | Signed marketplace event |
| `marketplace.post.expired` | Original poster or auto | All members | Signed expiry event |
| `chat.message.<recipient>` | Sending member | Recipient | Signed chat message |
| `emergency.mode.changed` | Each node locally | UI only | `{"online": bool, "since": "..."}` |
| `federation.peer.added` | Anchor with federation right | All anchors | Signed federation event |

All events are signed. All have a Lamport timestamp. All can be replayed.

### 10.5 Backpressure detail

Each stream has:

- `window_size`: max frames in flight (default 16)
- `frames_sent`: count
- `frames_acked`: count
- When `frames_sent - frames_acked >= window_size`, sender pauses

ACK frame:

```
event: ack
data: {"upto": 42}
```

Client sends ACKs every 8 frames received (half-window). If 5 seconds pass with no ACK, sender treats stream as broken.

---

## 11. Capability bus internals

### 11.1 Data structures

```python
class CapabilityEntry:
    node_id: str
    capability: str          # "llm.chat"
    version: tuple[int,int]  # (1, 0)
    schema_hash: str
    params: dict
    last_seen: float
    p50_latency_ms: float
    p99_latency_ms: float
    success_rate: float      # rolling 100 calls
    in_flight: int
    declared_max_concurrent: int
```

The bus keeps one of these per (node, capability) pair.

### 11.2 Routing algorithm

When a local service or client requests capability `C@V`:

```python
def route(capability: str, version_req: VersionReq, params: dict) -> CapabilityEntry | None:
    candidates = [
        e for e in registry
        if e.capability == capability
        and version_compatible(e.version, version_req)
        and params_compatible(e.params, params)
        and e.last_seen > now() - 60
        and e.in_flight < e.declared_max_concurrent
    ]
    if not candidates:
        return None
    # Score: lower is better
    def score(e):
        latency = e.p50_latency_ms
        load = e.in_flight / max(e.declared_max_concurrent, 1)
        reliability_penalty = (1 - e.success_rate) * 1000
        return latency * (1 + load) + reliability_penalty
    return min(candidates, key=score)
```

`params_compatible` is capability-specific. For `llm.chat`, the model name and minimum context length must match. For `rag.query`, the corpus name must match.

### 11.3 Local vs remote

If the local node also offers the capability, prefer local unless local load exceeds a threshold (default 80% of `declared_max_concurrent`). This biases toward local execution which is faster and avoids network for offline mode.

### 11.4 Sticky routing

For multi-turn capabilities (chat continuations referencing a prior conversation), the bus keeps a session → node binding for the conversation duration. Default TTL: 10 minutes idle.

### 11.5 Health tracking

After each call, record:

- success / fail
- latency
- response size

Ideally uses gradio trackio https://github.com/gradio-app/trackio
Rolling window of last 100 calls per (node, capability). Old entries decayed. A node with success rate < 0.5 over the last 20 calls is **quarantined** (skipped for 60 seconds, then probed).

### 11.6 Schema enforcement

Both sides validate against the JSON schema declared in the capability descriptor. Reject mismatches with `schema_mismatch` and the expected `schema_hash`. This is the contract.

### 11.7 Backpressure at the bus level

The bus has a max in-flight per (capability, node) pair. When saturated, new requests either:

- Queue with a configurable timeout, or
- Get rejected with `capacity_exceeded` and an `alt_nodes` list

MVP: queue with 1s timeout, then reject.

### 11.8 Observability hooks

Every call emits a trace event:

```json
{
  "ts": "2026-05-26T08:14:33.281Z",
  "trace_id": "01HXR8...",
  "capability": "llm.chat",
  "from": "node_short_id_A",
  "to": "node_short_id_B",
  "version": "1.0",
  "result": "ok",
  "ms": 1234,
  "tokens_in": 42,
  "tokens_out": 178
}
```

Traces go to a local SQLite ring buffer. Optionally exported to OpenTelemetry in Phase 2.

---

## 12. Services

### 12.1 LLM inference service (`llm.*`)

#### Capabilities

- `llm.chat@1.0` — multi-turn chat
- `llm.complete@1.0` — single-shot completion
- `llm.embed@1.0` — text embeddings (often a separate model)
- `llm.classify@1.0` — zero-shot classification (Phase 2)

#### Backends

- llama.cpp server (primary)
- Ollama (drop-in)
- vLLM (Phase 2, for batched throughput on the anchor)
- LM Studio (Christof's existing setup at `192.168.188.25:1234`)
- HF Inference API (when internet is up, as another route the bus may pick)
- Anthropic / OpenAI / others (Phase 2, with user-supplied keys)

The adapter pattern:

```python
class LlmBackend(Protocol):
    name: str
    async def chat(self, messages, **params) -> AsyncIterator[Token]: ...
    async def embed(self, texts) -> list[list[float]]: ...
```

The service module registers one capability per backend × model × quant combination, so the bus sees `llm.chat:qwen2.5-7b@q4`, `llm.chat:qwen2.5-7b@q8`, `llm.chat:gemma-3-9b@q4` as separate things.

#### MVP models

- `qwen2.5-7b-instruct@q4_k_m` (anchor) — primary chat
- `qwen2.5-1.5b-instruct@q4` (hearth) — fallback when anchor busy
- BGE-small embedding model (anchor + hearth) — RAG
- Christof's existing Proto-Cognitive Architecture v5.2 model as an experimental third option (HybridLLM with PinnedEpisodicStore)

#### Resource control

- Each backend declares `max_concurrent` based on VRAM
- Bus respects this hard limit
- Long requests can be **cancelled** mid-generation by closing the stream

### 12.2 RAG service (`rag.*`)

#### Capabilities

- `rag.query@1.0` — query a corpus, return chunks with scores
- `rag.ingest@1.0` — add a document to a corpus (member-only)
- `rag.list_corpora@1.0` — list local corpora

#### Storage

- ChromaDB for vectors (local file-based)
- Documents stored as content-addressed blobs (§10.3)
- One Chroma collection per corpus

#### Corpora

- `niederrhein-emergency` — the demo corpus (6 emergency PDFs)
- `community-knowledge` — user-contributed
- `personal` — per-user, not shared

#### Query flow

1. Embed query (via local `llm.embed` capability, routed by bus)
2. Search Chroma top-K
3. Return chunks with metadata: source doc CID, page, score
4. Caller passes chunks as LLM context

#### Ingest flow

1. Member uploads PDF via UI
2. PDF parsed (PyPDF2 → text + page numbers)
3. Chunked (1000 tokens, 200 overlap)
4. Each chunk embedded
5. Stored in Chroma with metadata
6. Original PDF stored as CID blob, advertised on the chunk service
7. `marketplace.knowledge.added` event published

### 12.3 File / chunk service (`file.*`)

#### Capabilities

- `file.read@1.0` — fetch a chunk by CID
- `file.list@1.0` — list locally-held CIDs
- `file.advertise@1.0` — claim to hold a CID (Phase 2: gossip)
- `file.put@1.0` — accept a chunk (member-only, opt-in)

#### Storage layout

```
~/.hearthnet/blobs/
  <first2bytes>/<rest of CID>.bin
```

Sharded for filesystem performance.

#### Garbage collection

- Default LRU eviction at 80% disk capacity threshold
- "Pinned" CIDs (user-marked) never evicted
- Marketplace event log + community manifest are always pinned

### 12.4 Marketplace service (`market.*`)

#### Capabilities

- `market.list@1.0` — list current posts
- `market.post@1.0` — create a post (signed)
- `market.expire@1.0` — mark expired (signed by original poster or after TTL)
- `market.search@1.0` — semantic search using embeddings

#### Data model

A post is an **event**:

```json
{
  "event_type": "market.post.created",
  "event_id": "01HXR8...",
  "lamport": 4218,
  "wall_clock": "2026-05-26T08:14:22Z",
  "author": "ed25519:NODE-ID",
  "community": "ed25519:COMMUNITY-ID",
  "data": {
    "category": "offer|request|info|emergency",
    "title": "Suche Wasserkanister, 20L",
    "body": "...",
    "location": {"lat": 51.5, "lng": 6.2, "label": "Issum"},
    "ttl_seconds": 86400,
    "tags": ["wasser","notfall"]
  },
  "signature": "ed25519:..."
}
```

This is EBKH-shaped on purpose. Reuse the event sourcing patterns Christof already built.

#### Sync semantics

Append-only log. Lamport timestamps for ordering. CRDT-style merge on rejoin: replay events in Lamport order, dedupe by `event_id`. Last-writer-wins on conflicting updates to the same post (rare, since posts are mostly create+expire).

### 12.5 Chat service (`chat.*`)

#### Capabilities

- `chat.send@1.0` — send a direct message (signed)
- `chat.history@1.0` — local history retrieval
- `chat.thread@1.0` — group conversation (Phase 2)

#### Delivery

- Direct messages are signed, addressed by recipient node ID
- If recipient is online, deliver directly
- If recipient is offline, **store-and-forward**: encrypted blob held by 2 randomly-chosen anchor nodes, delivered when recipient reconnects
- Read receipts are signed events

#### Encryption

MVP: TLS at transport, signed at app layer, no end-to-end encryption between users. Acceptable inside a trusted community.

Phase 2: optional E2E using X25519 + ChaCha20Poly1305. Signal-style ratchet deferred to Phase 3.

### 12.6 Embedding service (`embed.*`)

Separated from `llm.*` because embeddings have different scaling characteristics (small model, high throughput, often batch).

Capabilities:

- `embed.text@1.0` — embed a list of strings
- `embed.image@1.0` — embed an image (Phase 2, CLIP)

### 12.7 OCR service (Phase 2, `ocr.*`)

For ingesting scanned PDFs and photos of documents (emergency notices on lampposts, hand-written notes).

Backends: Tesseract for MVP, TrOCR for handwriting.

### 12.8 Translation service (Phase 2, `trans.*`)

German ↔ English ↔ Plattdeutsch (the Niederrhein angle).

Backends: NLLB for general, optional fine-tune for Plattdeutsch (likely a Christof project).

### 12.9 Speech services (Phase 2, `tts.*` `stt.*`)

- Whisper for STT
- Edge-TTS or XTTS-v2 for TTS (Christof already has the XTTS pipeline from his podcast generator)

### 12.10 Image services (Phase 2, `img.*`)

- Florence-2 for captioning (Christof's pipeline)
- FLUX.1-dev LoRA for generation (Christof's pipeline)
- Particularly useful for "describe this damage photo" emergency use cases

---

## 13. Emergency mode

### 13.1 Detection

A small daemon runs in every node. Every 10 seconds when believed-online, every 2 seconds when believed-offline.

Probes:

1. DNS resolve `cloudflare.com` and `quad9.net`
2. HTTPS HEAD `https://1.1.1.1/cdn-cgi/trace` and `https://www.google.com/generate_204`
3. All four with 2-second timeouts
4. Online = ≥3 of 4 succeed

State machine:

- `ONLINE` → `DEGRADED` (one probe failed) → `OFFLINE` (≥2 failed for 30s)
- `OFFLINE` → `ONLINE` directly when all 4 succeed for 10s

Each transition publishes `emergency.mode.changed` locally.

### 13.2 UX changes when offline

- Top banner: `INTERNET OFFLINE — LOKAL AKTIV` (amber)
- Topology graph collapses to local nodes only (cloud-side bridges go grey)
- Cloud-routed LLM backends (HF API, Anthropic) drop out of the capability registry
- Marketplace shows a "Notfall-Modus" filter prominent
- A new tab appears: **Notfall** — direct links to the emergency PDF corpus, neighbour list with last-seen times, generator/water/light shared resources
- Chat switches to store-and-forward UI

### 13.3 Behavioural changes when offline

- LLM router prefers local-only models
- File transfers stop seeking internet-hosted sources
- Federation pause (peer communities cannot be reached)
- Discovery rate increases (UDP broadcasts more often, to find newly-arrived neighbours faster)

### 13.4 Restore behaviour

When internet returns:

1. Banner clears
2. Re-register cloud capabilities
3. Replay any queued federation events to peer communities
4. Resync marketplace event log with bridge nodes if any
5. Send queued chat messages
6. Optional: notify the user of how many events synced

### 13.5 Anti-flapping

If transitions occur more than 3 times in 60 seconds, system stays in the more pessimistic state for the rest of that window. Prevents banner flicker.

---

## 14. Reconciliation & sync

### 14.1 The event log

Every community has a single conceptual append-only log. In practice it lives as a SQLite database per node, plus a CID-addressed snapshot file recreated nightly.

Schema (simplified):

```sql
CREATE TABLE events (
  event_id TEXT PRIMARY KEY,    -- ULID
  lamport INTEGER NOT NULL,
  wall_clock TEXT NOT NULL,
  community_id TEXT NOT NULL,
  author_node TEXT NOT NULL,
  event_type TEXT NOT NULL,
  data JSON NOT NULL,
  signature TEXT NOT NULL,
  received_at TEXT NOT NULL
);
CREATE INDEX idx_events_lamport ON events(community_id, lamport);
CREATE INDEX idx_events_type ON events(community_id, event_type, lamport);
```

### 14.2 Materialised views

Reading the raw log every time is slow. Each node maintains materialised views:

- `community_manifest` (current member list)
- `marketplace_current` (un-expired posts)
- `chat_history_per_peer`
- `node_health_snapshot`

Views are rebuilt by replaying events from the last snapshot.

### 14.3 Lamport clocks

Each node maintains a Lamport counter. Every event written or received bumps it:

```python
def receive(event):
    lamport = max(self.lamport, event.lamport) + 1
    store(event)
```

### 14.4 Sync protocol

When node A meets node B:

1. A asks B: "what is your highest Lamport per (community, event_type)?"
2. B responds with a vector
3. A computes the delta and sends its missing events
4. B does the same in the other direction
5. Both verify signatures, store events, update materialised views

This is gossip-based, eventually consistent, and resilient to partition.

### 14.5 Conflict resolution

- **Marketplace post update** (e.g. price change): last-writer-wins by Lamport timestamp
- **Member revoke vs. member action**: revoke wins if Lamport(revoke) < Lamport(action); otherwise the action is honoured
- **Two communities with same name**: not a conflict — communities are identified by root key, not by name

### 14.6 Snapshot & compaction

Once per night, each node:

1. Computes the materialised state at `lamport = current_max - 1000`
2. Writes it as a signed snapshot blob (CID-addressed)
3. Marks events below that Lamport as "snapshot-covered"
4. Optionally garbage-collects old events (configurable; default keeps 30 days)

New joiners fetch the latest snapshot + recent events, instead of replaying from genesis.

---

## 15. Application plane

### 15.1 UI surfaces

| Surface | Tech | Purpose |
|---|---|---|
| Gradio dashboard | Gradio 6.0.0 | Primary local-host UI |
| Topology viz | Cytoscape.js inside Gradio | Live mesh state with request animation |
| Chat tab | Gradio chat component | Per-peer conversation |
| Files tab | Gradio file explorer | Browse + upload CID blobs |
| Marketplace tab | Gradio dataframe | Filter, post, search |
| Emergency tab | Bespoke layout | Visible only when offline; large buttons |
| CLI | Click | `hearthnet status`, `hearthnet caps`, `hearthnet log` |
| Mobile web | Vanilla HTML + JS | Lightweight, served from any anchor |

### 15.2 Topology visualisation requirements

- Real-time node list with online/offline indicators
- Animated request flow along edges when a call is in flight
- Color codes capability per edge (LLM = teal, RAG = purple, file = amber, chat = blue)
- Node tooltip shows capabilities, load, latency
- Click a node → opens its public manifest in a side panel
- Edge thickness scales with recent traffic

This is the single visual element judges remember. Build it early.

### 15.3 Mobile client (lightweight)

A static HTML+JS file served from any anchor at `/mobile`. Communicates with the host node via the same bus API. No installation; bookmark to home screen.

Features for MVP: chat, marketplace browse, emergency mode banner, ask-a-question (LLM passthrough). No topology viz on mobile.

### 15.4 First-time install UX

1. `pip install hearthnet` (or download single binary)
2. `hearthnet init` — generates keys, asks for community
3. `hearthnet run` — starts the node
4. Browser opens to `http://localhost:7860`
5. If joining an existing community, displays a "scan invite QR" screen
6. If creating, displays the new community QR code for others to scan

Total time: under 2 minutes from download to first message.

---

## 16. Data model summary

### 16.1 Event types (canonical list)

| Type | Producer | Consumer |
|---|---|---|
| `community.created` | Founder | All |
| `community.member.invited` | Member with right | All |
| `community.member.joined` | Joining device | All |
| `community.member.revoked` | 3 members | All |
| `community.policy.updated` | Root key | All |
| `node.manifest.updated` | Each node | All |
| `capability.registered` | Each node | Local bus only |
| `capability.deregistered` | Each node | Local bus only |
| `market.post.created` | Member | All |
| `market.post.updated` | Author | All |
| `market.post.expired` | Author or auto | All |
| `chat.message.sent` | Sender | Recipient |
| `chat.message.delivered` | Recipient | Sender |
| `chat.message.read` | Recipient | Sender (optional) |
| `file.cid.advertised` | Holder | Local bus, then gossip |
| `file.cid.unpinned` | Holder | Local bus |
| `rag.document.ingested` | Ingester | All members |
| `federation.peer.added` | Anchor | All anchors |
| `federation.peer.removed` | Anchor | All anchors |
| `emergency.mode.changed` | Each node locally | UI only, not in log |

### 16.2 Schema versioning

Every event has a `schema_version`. Old events are kept verbatim; new readers translate via a versioned schema registry. Never rewrite history.

### 16.3 Storage locations

```
~/.hearthnet/
  keys/
    device.ed25519                  (private, 0600)
    device.pub
  communities/
    <community_id>/
      manifest.json                  (latest signed materialised manifest)
      events.sqlite                  (event log)
      snapshots/<lamport>.bin        (signed snapshots)
  blobs/<aa>/<bb...>                 (CID-addressed)
  config.toml
  logs/<date>.log
```

---

## 17. Security

### 17.1 Cryptographic primitives

- **Identity**: Ed25519 (signatures)
- **Key agreement** (Phase 2 E2E): X25519
- **Symmetric** (Phase 2 E2E): ChaCha20-Poly1305
- **Hashing**: BLAKE3 for CIDs, SHA-256 for compatibility where needed
- **TLS**: rustls or Python `ssl` defaults, TLS 1.3 only

### 17.2 Signature scopes

Every:

- Node manifest
- Capability descriptor (signed as part of the node manifest)
- Marketplace event
- Chat message
- Community manifest (root-signed)

is signed. Signature verification is **mandatory** on receipt. Unsigned or invalid events are dropped without log spam (single counter increment).

### 17.3 Sandboxing

User-uploaded content (PDFs, images) is processed in subprocess workers with `nice`-restricted resource limits. No `exec` of user-provided data. No URL fetching from user input without explicit allowlist.

### 17.4 Rate limiting

Per (peer, capability):

- 10 RPS soft limit (responds with `capacity_exceeded`)
- 100 RPS hard limit (drops with no response)

Per (peer, all capabilities):

- 100 RPS soft, 1000 RPS hard

### 17.5 GDPR considerations

This is a Christof project. GDPR-correct from day one is a requirement.

- All personal data (chat, marketplace) is local-first. No central server holds it.
- Users can run `hearthnet erase` to wipe their event participation (best-effort: their signed events still exist on other nodes, but their device key is destroyed, so they cannot be linked back to a person).
- A `personal` corpus in RAG never leaves the device.
- Deletion of marketplace posts: a `market.post.expired` event with `reason: "user_request"` is published; consuming nodes hide the original.
- Right to data export: `hearthnet export` produces a zip of all local data signed by the user.


---

## 18. Observability

### 18.1 Logging

Structured JSON to `~/.hearthnet/logs/<date>.log`. Levels: `debug`, `info`, `warn`, `error`. Default `info`. Log rotation daily, retention 14 days.

### 18.2 Metrics

Prometheus-format scrape endpoint at `:7080/metrics`:

- `hearthnet_requests_total{capability, result}`
- `hearthnet_request_duration_ms{capability, quantile}`
- `hearthnet_nodes_online{community}`
- `hearthnet_event_log_size{community}`
- `hearthnet_emergency_mode{state}`
- `hearthnet_blob_storage_bytes`
- `hearthnet_llm_tokens_generated_total{model}`

### 18.3 Tracing

Every bus call gets a trace ID. Traces are stored locally in SQLite (ring buffer, 10k events). Optional OTLP export in Phase 2.

### 18.4 Health endpoints

- `GET /health` — 200 if process alive
- `GET /ready` — 200 if at least one peer discovered AND at least one capability registered
- `GET /metrics` — Prometheus

### 18.5 Self-diagnostics

`hearthnet doctor` runs a battery of checks:

- mDNS reachable?
- TLS cert valid?
- Discovery sending and receiving?
- At least one peer visible?
- Local services registered?
- Disk space healthy?
- Recent error rate?

Returns a coloured report and a non-zero exit code on failure. Drop-in for CI and on-stage troubleshooting.

---

## 19. Testing strategy

### 19.1 Unit

Every service has unit tests for its capability handlers using a `FakeBus`. Coverage target: 70% on services, 90% on bus.

### 19.2 Integration

A test harness spins up 3 in-process nodes on different ports in the same Python process, with mocked discovery. Integration tests cover:

- Discovery → manifest exchange → first call
- LLM routing prefers low-latency node
- Marketplace event syncs after re-connection
- File transfer with one chunk source going offline mid-stream
- Schema mismatch rejection
- Capability quarantine after failures

### 19.3 Chaos

Three real OS-level processes on the same machine, with `tc` (Linux traffic control) introducing latency, packet loss, and partitions. Scenarios:

- Anchor reboots mid-RAG-query
- 70% packet loss for 30 seconds
- Network partition where 1 node sees 2 others see each other but not it
- Clock skew of ±60 seconds between nodes

### 19.4 Demo dry-runs

Daily in the week before the demo, run the full 2-minute script end to end. Record. Watch for the dead-air moments (model loading, mDNS delay, banner appearance latency). Fix.

### 19.5 Adversarial

- Send malformed manifests
- Send manifests signed by a non-member key
- Send replayed (old) events
- Send oversized payloads
- Send valid signatures from a revoked member

All must fail closed with no leak and no crash.

---

## 20. Hackathon MVP scope

### 20.1 Modules and effort

| ID | Module | Effort (evening hours) | Reuse from existing work |
|---|---|---|---|
| M1 | Node identity & manifest | 4–6 | — |
| M2 | Discovery (mDNS + UDP) | 4–6 | — |
| M3 | Capability bus | 8–12 | NEXUS gateway patterns |
| M4 | LLM inference service | 4–6 | LM Studio at 192.168.188.25, FORGE |
| M5 | RAG service | 6–8 | Christof's existing RAG pipelines |
| M6 | Marketplace service | 4–6 | EBKH event-sourcing patterns |
| M7 | File/chunk service | 6–10 | — |
| M8 | Gradio dashboard + topology viz | 12–16 | FORGE Spaces patterns |
| M9 | Emergency-mode detector | 2–3 | — |
| M10 | Chat service | 4–6 | — |
| M11 | Embedding service | 2–3 | sentence-transformers, existing |
| M12 | CLI (`hearthnet status`, etc.) | 2–4 | — |
| M13 | First-run UX + invite QR | 3–5 | — |
| **Total** | | **61–91h** | |

### 20.2 Build order (demo-driven)

1. **M1 + M2** (identity + discovery) — first because nothing works without them
2. **M3** (bus) with a fake echo service — proves the contract
3. **M4** (LLM) plugged in — first real value
4. **M8** (UI shell + topology viz) — connected to bus, shows mocked nodes initially, then real
5. **M5** (RAG) — demo value
6. **M9** (emergency detector) — wire the banner
7. **M6** (marketplace) — reuses EBKH
8. **M10** (chat) — store-and-forward as bonus
9. **M7** (file/chunk) — last; if cut, files just upload to one node
10. **M11–M13** as time allows

### 20.3 Risk-driven cuts (if behind schedule)

In order of "cut first":

1. **M7 file/chunk** — keep file upload but single-node only
2. **M10 chat** — show in slides only
3. **M13 first-run UX** — judges don't need to install
4. **M12 CLI** — UI is enough
5. **M11 embeddings as separate service** — fold into M5

Never cut: M1, M2, M3, M4, M5, M8, M9.

### 20.4 Definition of done for the demo

- [ ] Three real nodes auto-discover each other on the demo LAN
- [ ] One full LLM query completes with visible token streaming and visible routing
- [ ] One RAG-grounded answer with source citation
- [ ] Two marketplace posts visible across all three nodes
- [ ] WAN-cable unplug triggers the offline banner in ≤5s
- [ ] One question answered while offline using local-only capabilities
- [ ] WAN restore triggers reconciliation visibly
- [ ] Topology viz updates in real time throughout

---

## 21. Out of scope for hackathon

The following are mentioned in the design but **not implemented in MVP**. They are designed-in (no future rewrite needed), just not built yet.

- WireGuard / Tailscale overlay
- LoRa or BLE transports
- DHT-based cross-LAN discovery
- Petals-style distributed-tensor inference
- Federated MoE expert routing across nodes
- Cross-community federation
- End-to-end encryption of chat between users
- Capability tokens (auth is per-request signing only)
- OCR, translation, speech, image generation services (designed; not coded)
- Mobile native app (web only)
- OTLP trace export
- The signed nightly snapshot mechanism (events keep accumulating in MVP)

---

## 22. Phase 2 — post-hackathon (1–3 months)

### 22.1 Internet relay & cross-LAN federation

A small Rust or Python relay any participant can host. Helps NAT'd peers reach each other. Used to bootstrap federation between, e.g., Issum and Geldern communities.

### 22.2 Federated learning experiments

Each anchor periodically computes LoRA gradients on local conversations (consent-required), sends only the gradient deltas to other anchors, averages, applies. A simple version of FedAvg, scoped to LoRA layers of the local LLM. Not full federated learning — practical and scoped.

### 22.3 Capability tokens

OAuth-style short-lived tokens for fine-grained delegation. Especially useful for Bridge nodes between communities.

### 22.4 OCR + translation services

For ingesting paper documents (lamppost notices) and serving the Plattdeutsch / Niederrhein angle.

### 22.5 Speech I/O

STT (Whisper) and TTS (Christof's existing XTTS-v2 + Edge-TTS pipeline). Particularly valuable for elderly community members in an emergency context.

### 22.6 Hetzner / IONOS deployment

A relay tier hosted by Christof at `relay.hearthnet.de`, with the existing PHP 8.3 + Python bridge infrastructure used for ki-fusion-labs. Free for small communities, paid for larger ones (revenue path 1).

### 22.7 Mobile native client

Flutter or React Native. Bypasses the "must keep browser tab open" limitation. Push notifications via the existing relay tier.

### 22.8 Marketplace search via embeddings

`market.search@1.0` registered as a capability. Embed posts on creation, semantic search. Probably <1 day given the infrastructure is there.

### 22.9 Federated identity import

Optional: import an existing identity (HF, GitHub key, etc.) to bootstrap trust. Decouples HearthNet identity from device.

### 22.10 Improved topology visualisation

3D mesh, request heatmaps, historical replay. Pure polish, but valuable for demos and selling.

---

## 23. Phase 3 — research-shaped (6–12 months)

### 23.1 Distributed-layer inference experiment

A genuinely-distributed inference path for one specific small model (1.5B–3B), Petals-style, as a feature flag. Acceptable latency probably only on Ethernet-connected nodes within the same household. The point is the demo, not production. Wire it under the existing `llm.chat` capability with a `distributed: true` parameter and a clear latency warning.

### 23.2 MoE-style expert routing

Each community has expert nodes: "the electrician's node has the Schaltplan corpus", "the gardener's node has the Pflanzen knowledge". The router learns which questions to send where. Mix human + AI experts: route a question to a real neighbour as fallback. Connect to the marketplace.

### 23.3 LoRa "I exist" beacons

868MHz transmitter on an anchor. Phones with LoRa modules learn community exists in range. Useful in real disaster scenarios where WiFi is gone.

### 23.4 Christof's research integrations

- **Proto-Cognitive Architecture v5.2** as an `llm.chat` backend with experimental episodic-memory features
- **Hebbian residual memory** experiments on Qwen2.5-1.5B as another backend
- **BitNet 1.58-bit** quantised models for very low resource nodes (Pi 5 + USB SSD)
- **EBKH** as the evidence layer for marketplace truth-checking (claim-graph for "is this actually safe drinking water?")

### 23.5 Civil-defence pilot

Pilot with one NRW municipality. Bevölkerungsschutz partners. Real test under a planned blackout exercise. This is the credibility-building step toward larger deployments.

---

## 24. Phase 4 — long-term vision

A "neighbourhood internet" where:

- Communities own their compute
- Communities federate with adjacent communities
- Communities can survive multi-day outages
- AI is a community resource like a library or a kitchen, not a subscription
- The protocol is open, the implementation is reference, the ecosystem is many

The grand version of HearthNet looks more like a protocol (think Matrix or ActivityPub) than a product. We are building the reference implementation that proves the protocol is worth standardising.

---

## 25. Reuse from existing systems

Christof has built a lot of this stuff already. The PRD is *not* "build everything from scratch". It is "compose the existing FORGE/EBKH/NEXUS/PicoClaw work behind a coherent mesh protocol". Concretely:

| Existing system | What it gives HearthNet |
|---|---|
| **FORGE** (15 HF Spaces, multi-agent platform) | Service skeleton, tool plumbing, GDPR delete endpoints, auto-seeding patterns |
| **EBKH** (event-sourced claim graph, 28 packages, 48 event types) | The event log, snapshot pattern, schema-versioned events |
| **NEXUS** (LLM gateway) | Multi-provider LLM adapter with health/latency tracking |
| **htmlClaw / OpenClaw** (single-file WebGPU browser agent) | Possible browser-only node profile (Phase 2): a HearthNet node that lives entirely in a tab |
| **Proto-Cognitive Architecture v5.2** | Optional advanced LLM backend with episodic memory |
| **BitNet kernel** | Backend for ultra-low-resource nodes |
| **DSGVO Löschprotokoll** (MinIO + PostgreSQL + FastAPI + Streamlit) | Audit-trail and erase patterns for compliance |
| **Florence-2 + FLUX.1 pipeline** | Image services backend |
| **smolagents + Edge-TTS / XTTS-v2 podcast generator** | Speech services backend |
| **LM Studio at 192.168.188.25:1234** | The first real LLM backend during dev |
| **JARVIS / TheCore notes** | Agent architecture inspiration for the router |
| **HuggingFace MCP work (Chris4K)** | MCP integration in Phase 2 (HearthNet nodes as MCP servers) |

The build effort is real, but it is integration effort, not invention effort. That ratio is what makes this hackathon-doable.

---

## 26. Technology stack

### 26.1 Languages

- **Python +3.11+** — primary, for everything except where noted
- **Rust** — Phase 2 relay (optional, Python relay fine for MVP)
- **HTML/CSS/JavaScript** — UI, front, mobile client, no frameworks (Christof preference)
- **C++** — only via llama.cpp, not authored

### 26.2 Libraries

| Concern | Library | Why |
|---|---|---|
| Web server | FastAPI + uvicorn | Christof's existing stack |
| UI | Gradio 6.0.0 | Hackathon requirement, Christof familiar |
| Discovery | python-zeroconf | de-facto for mDNS |
| Crypto | PyNaCl (Ed25519) + cryptography (TLS) | Boring, secure |
| Hashing | blake3 | Fast CID hashing |
| Vector DB | ChromaDB (file-based) | Local-first, simple |
| Embeddings | sentence-transformers | BGE-small is plenty |
| LLM | llama-cpp-python OR ollama HTTP | Backend-agnostic via adapter |
| Event store | SQLite + JSON | Zero-config, transactional |
| Pub-sub | In-process asyncio + HTTP push for remote | No broker needed |
| Topology viz | Cytoscape.js embedded in Gradio HTML | Christof has used Cytoscape before |
| Charts | Chart.js | Christof has used Chart.js before |
| CLI | Click | Standard |
| Testing | pytest + pytest-asyncio | Standard |
| Tracing | OpenTelemetry SDK (Phase 2) | Optional |

### 26.3 Explicit non-choices

- **Not** Node.js or npm — Christof preference
- **Not** React or any heavy frontend framework — Christof preference, also Gradio doesn't need it
- **Not** Docker as a hard requirement — single-binary install must work
- **Not** a custom binary protocol — JSON over HTTP is enough and debuggable

---

## 27. Deployment topologies

### 27.1 Home (3 nodes typical)

- Anchor on a workstation
- 1–2 Hearth nodes on laptops
- 0–3 Spark thin clients on phones / Pi

### 27.2 Small business

- 1–2 Anchors in the back office
- 5–15 Spark clients at workstations
- Optional Bridge to a sister branch via Phase 2 relay

### 27.3 Civic / municipal

- Anchor per community building (Feuerwache, Bürgerhaus, Kirche)
- Federation between buildings
- Sparks via citizen smartphones with the mobile client
- Bridge to civil defence systems (Phase 3, requires policy work)

### 27.4 Disaster pilot

- Mobile anchor (camper-van rig with battery + Starlink fallback)
- LoRa beacons for spread
- Manual Spark distribution (USB drives with the mobile client)

---

## 28. Go-to-market & monetisation

These are aspirational, not part of the hackathon. Including them because the PRD is also a thinking document.

### 28.1 Path A — retail-continuity pilot

stores depend on technical devices. Internet drops happen. A small HearthNet anchor in the back room of every store plus Sparks at every cashier desk = an internal mesh for orders, inventory checks, and customer comms that survives a WAN outage. Internal pilot first; later an outward-facing product offered to other cold-chain retailers.

Estimated revenue path: 1–2 year horizon, internal first.

### 28.2 Path B — NRW Bevölkerungsschutz pilot

Each Kreis has civil-defence mandates. A neighbourhood AI mesh that works without internet fits exactly. Grant-fundable. Stakeholders: Kreis Kleve Bevölkerungsschutz, THW, optionally DRK. Christof's local Sankt-Martins-Comité contacts are a wedge.

Estimated revenue path: 6–12 months, public-sector procurement realities apply.

### 28.3 Path C — HearthNet-in-a-Box appliance

Mini-PC (e.g. Beelink + small NVIDIA GPU or Intel Arc) pre-installed with the stack, a 1TB SSD, a curated emergency corpus, a default model. Ships with a printed booklet for the non-technical setup. Customers: community groups, churches, Vereine, prepper-adjacent, off-grid-curious.

Margins thin on hardware, real margin on optional yearly support + corpus updates.

Estimated revenue path: 3–6 months to first prototype, viable hobby-business scale.

### 28.4 Path D — hosted relay tier

`relay.hearthnet.de` on Hetzner. Free for tiny communities (≤5 anchors), paid above. Bring-your-own-domain for organisations. Used for cross-LAN bootstrap, mobile push, and store-and-forward when no anchor is online for a recipient.

Estimated revenue path: 3 months to launch, low-margin but recurring.

### 28.5 Path E — open-source consulting

The AGPL kernel + paid integration for organisations that want HearthNet inside their infrastructure. Standard open-core business model. Probably the highest near-term revenue per hour.

### 28.6 Anti-paths

- No "neighbourhood crypto-token". Tempting and wrong.
- No ad-supported model. Defeats the purpose.
- No closed-source kernel. Defeats the trust model.

---

## 29. Risks & mitigations

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| mDNS blocked on demo venue WiFi | Medium | High | Travel router on stage, UDP broadcast as fallback, fake-mesh dry-run mode |
| GPU node OOM mid-demo | Low | High | Pre-warmed model, conservative `max_concurrent`, smaller model as fallback |
| Demo computer dies | Low | Catastrophic | Two laptops, identical config, hot-swappable |
| Distributed inference (Phase 3) attempted in MVP | Medium | High | Crossed-out in scope, behind feature flag if anyone tries |
| Capability schema churn | Medium | Medium | Lock v1 schemas before M4 starts, treat as ABI |
| Christof's bandwidth (newborn, Elternzeit) | High | High | Demo-driven scope; M7 and M10 are cuttable |
| Privacy backlash ("you're routing my data through neighbours?") | Medium | Medium | Clear local-first defaults, signed-and-encrypted-in-transit, explicit "personal" corpus that never leaves device |
| GDPR review | Medium | Medium | Reuse DSGVO Löschprotokoll patterns; explicit erase path |
| Hardware vendor lock-in (NVIDIA-only) | Medium | Low | llama.cpp + ollama supports Apple Silicon and AMD; Ollama is the default for non-NVIDIA |
| "It's just a worse cloud" criticism | High | Medium | Lead with the resilience demo, not the AI quality argument |

---

## 30. Success metrics

### 30.1 Hackathon success

- Demo runs end-to-end without intervention on first try in the judge session
- Topology visualisation is clear enough that a non-technical observer can describe what is happening
- At least one judge asks "can I run this at home?"
- Submission is delivered before deadline
- Code is published, repo is clean, README has a one-command quickstart

### 30.2 Post-hackathon technical success (3 months)

- Three real households running HearthNet for at least a week each
- Median end-to-end latency under 2s for `llm.chat` in a typical home LAN
- Zero data-loss incidents in event log under partition + rejoin scenarios
- Mobile client usable on iOS Safari and Android Chrome
- 80%+ test coverage on the bus

### 30.3 Product success (12 months)

- At least one of the four monetisation paths has produced revenue
- One outside contributor merged code
- One academic citation or thoughtful blog post about the architecture
- 100+ HF Spaces stars (proxy for community interest)

---

## 31. Open questions

These need resolution but do not block the hackathon.

1. **Single binary or pip install?** Hackathon: pip. Long-term: single binary built with PyInstaller or Nuitka.
2. **Storage location standard?** XDG on Linux/macOS, `%APPDATA%` on Windows. Decision: follow `platformdirs` library.
3. **Time sync?** Lamport clocks make us mostly clock-independent, but UI timestamps suffer if clocks drift. Decision: display "X minutes ago" only; show absolute time only on the local device's wall clock.
4. **Mobile client served from any anchor — what about the URL?** mDNS for `hearthnet.local` is the goal. Browser support varies. Decision: print the IP+port in the QR code as a fallback.
5. **How does a Spark survive its anchor going down?** With a list of known peers. Decision: each Spark caches the last 10 peer manifests; tries them in order if the bound anchor disappears.
6. **What's the bus's behaviour when two local services register the same capability?** Both registered; router prefers based on declared params. No conflict.
7. **Can a non-member observe public traffic?** Yes — they see signed manifests by virtue of mDNS. They cannot make calls. Decision: keep this; visibility is the price of zero-config.
8. **Federation between communities with conflicting member sets?** Out of scope for MVP.
9. **Web of trust visualisation?** Phase 2 polish.
10. **Should anchors be able to refuse a capability call?** Yes — `unauthorized` is a valid response. Refusal is fine.

---

## 32. Glossary

| Term | Meaning |
|---|---|
| **Anchor** | Always-on node with GPU + storage, primary provider |
| **Bus (capability bus)** | The L3 routing component every service registers with |
| **Capability** | A named, versioned, schema-bound RPC offered by a node |
| **CID** | Content identifier (BLAKE3 hash) used for content-addressed storage |
| **Community** | A trust root; a group of nodes sharing a root key and event log |
| **Emergency mode** | UI + behavioural state when internet detection reports offline |
| **Federation** | Cross-community trust and capability access |
| **Hearth** | Mid-tier node, typically a laptop |
| **Lamport clock** | Logical counter used for event ordering |
| **Manifest** | A signed JSON document (node manifest or community manifest) |
| **Node** | One running HearthNet process |
| **Profile** | One of `anchor`, `hearth`, `spark`, `bridge` — determines services |
| **Service** | An L4 module providing one or more capabilities |
| **Spark** | Thin client (Pi, mobile, browser) |
| **Stable / experimental** | Capability stability flags |

---

## 33. Appendix A — capability namespace allocation

| Prefix | Owner service | Examples |
|---|---|---|
| `llm.*` | LLM service | `llm.chat`, `llm.complete`, `llm.classify` |
| `embed.*` | Embedding service | `embed.text`, `embed.image` |
| `rag.*` | RAG service | `rag.query`, `rag.ingest`, `rag.list_corpora` |
| `file.*` | File service | `file.read`, `file.list`, `file.advertise` |
| `market.*` | Marketplace | `market.list`, `market.post`, `market.search` |
| `chat.*` | Chat | `chat.send`, `chat.history` |
| `community.*` | Trust ops | `community.invite`, `community.revoke` |
| `federation.*` | Cross-community | `federation.peer.add`, `federation.relay` |
| `ocr.*` | OCR (Phase 2) | `ocr.image`, `ocr.pdf` |
| `tts.*` `stt.*` | Speech (Phase 2) | `tts.synthesize`, `stt.transcribe` |
| `trans.*` | Translation (Phase 2) | `trans.text` |
| `img.*` | Images (Phase 2) | `img.describe`, `img.generate` |
| `experimental.*` | Anything not promoted | `experimental.distributed_llm.chat` |

Reserved prefixes; no service may take a name outside its declared prefix.

---

## 34. Appendix B — example end-to-end trace

A user on the laptop asks *"Wie reinige ich Regenwasser ohne Strom?"*. The trace, as it would appear in the trace log:

```
t+0ms     UI: user submits query, calls local bus capability "llm.chat@1.0"
t+1ms     Bus: routing query, looking for "llm.chat" providers
t+2ms     Bus: candidates: [anchor: 7H4G-..., self: 9JKM-...]
          anchor: p50=820ms, in_flight=0/4, success=0.99
          self:   would-be: needs to load model, ~3000ms cold
t+3ms     Bus: scoring → anchor wins (lower latency)
t+4ms     Bus: opening stream to anchor
t+7ms     Anchor: receives request, validates signature, schema OK
t+8ms     Anchor LLM: starts generation
t+9ms     Anchor: calls local "rag.query@1.0" with the user message
t+11ms    Anchor RAG: embeds query (local embed.text)
t+24ms    Anchor RAG: vector search returns 4 chunks from emergency PDF
t+25ms    Anchor LLM: receives chunks, builds context, continues
t+182ms   Anchor: streams first token to laptop
t+184ms   Laptop UI: animates edge from anchor → self, shows first token
t+1402ms  Anchor: emits "done" event, stream closes
t+1404ms  Laptop UI: animation completes, shows source citation
t+1405ms  Bus: records trace: 1401ms, 178 tokens, success
```

Total perceived latency: under 1.5 seconds, with token streaming from ~200ms. Visible routing on screen.

---

## 35. Appendix C — example minimal node startup code

This is illustrative, not normative. Real implementation is split across modules.

```python
# hearthnet/node.py
import asyncio
from hearthnet.identity import load_or_generate_keys, load_community
from hearthnet.discovery import mdns_loop, udp_broadcast_loop
from hearthnet.bus import CapabilityBus
from hearthnet.transport import HttpServer
from hearthnet.services.llm import LlmService
from hearthnet.services.rag import RagService
from hearthnet.services.market import MarketplaceService
from hearthnet.ui.gradio_app import build_ui

async def main():
    keys = load_or_generate_keys()
    community = load_community()
    bus = CapabilityBus(node_id=keys.node_id, community=community)

    # Register local services
    bus.register_service(LlmService(backend="llama_cpp", model="qwen2.5-7b@q4"))
    bus.register_service(RagService(corpus="niederrhein-emergency"))
    bus.register_service(MarketplaceService(community=community))

    # Start transport + discovery
    server = HttpServer(bus=bus, port=7080, keys=keys)
    await asyncio.gather(
        server.run(),
        mdns_loop(bus),
        udp_broadcast_loop(bus),
        emergency_detector(bus),
        build_ui(bus).launch_async(port=7860),
    )

if __name__ == "__main__":
    asyncio.run(main())
```

That is the whole shape. Everything else is filling in.

---

*End of HearthNet PRD v2. Split into per-section docs once implementation starts.*