Spaces:
Running on Zero
Running on Zero
| # 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 | |