tasks.md

# HearthNet — Task Tracker

Status Summary (June 2026)

All Phase 1 (M01-M13, X01-X04), Phase 2 (M14-M25, X05-X07), and Phase 3 experimental (M26-M31) modules are implemented. 62 tests pass (51 unit/integration + 11 E2E Playwright).

---

Phase 1 — Complete

• M01 Identity (Ed25519, canonical JSON, node/community manifests)
• M02 Discovery (mDNS, UDP broadcast, PeerRegistry with async events)
• M03 Capability bus (schema validation, router, health, traces)
• M04 LLM (Ollama, llama.cpp, HF Transformers backends; OpenAI online fallback)
• M05 RAG (chunker, ChromaDB + in-memory, IngestPipeline, bus embed)
• M06 Marketplace (event-sourced, post/list/expire/search)
• M07 File blobs (BLAKE3 CID store, chunking, TransferManager)
• M08 UI (Gradio, 6 tabs: Ask/Chat/Marketplace/Files/Emergency/Settings)
• M09 Emergency (async probe loop, DNS+HTTP, anti-flap, StateBus)
• M10 Chat (event-sourced, ChatView, DeliveryManager)
• M11 Embedding (embed.text, SimpleHashBackend, SentenceTransformerBackend)
• M12 CLI (click, ask/node info/caps/call/doctor/trace)
• M13 Onboarding (InviteBlob, QR, create/join/redeem community)
• X01 Transport (FastAPI server 12 endpoints, HttpClient, SSE, TLS)
• X02 Events (SQLite WAL, LamportClock, ReplayEngine, MaterialisedView, SnapshotStore)
• X03 Observability (structured JSON logging, prometheus metrics optional, trace ring buffer)
• X04 Config (typed frozen Config, TOML load/save, XDG paths, env overlay)

---

Phase 2 — Complete

• M14 Federation (FederationManifest, bilateral peering, FederationService)
• M15 Relay tier (RelayClient, NAT traversal, keepalive, push token registry)
• M16 Capability tokens (hntoken://v1/ Ed25519 JWS-style, AuthService)
• M17 OCR (Tesseract + TrOCR backends, image/pdf capabilities)
• M18 Translation (NLLB backend, LRU cache, 4000-char limit)
• M19 STT/TTS (WhisperBackend local STT, EdgeTtsBackend synthesis)
• M20 Vision (Florence-2 image describe, generate placeholder)
• M21 Tool calls (ToolDefinition, ToolCall, ToolResult, ToolExecutor, run_loop)
• M22 Mobile native (MobileInviteBlob, hnapp:// deep links, MobilePushService)
• M23 E2E encryption (X3DH, Double Ratchet fixed bug, envelope, prekeys)
• M24 Reranking (BGE + CrossEncoder, 100-doc limit, bus integration)
• M25 Group chat (ThreadService, ThreadViewStore, event-sourced)
• X05 DHT (Kademlia, 256-bucket routing table, KademliaNode, bootstrap)
• X06 WebSocket (WebSocketSession, WebSocketClient, WebsocketPubSub)
• X07 Federated metrics (NodeMetricsTick, MetricsAggregator, OTLP export)

---

Phase 3 — Experimental Stubs (feature-flag gated)

All enabled via config.research.* flags (all default False).

• M26 Distributed inference (ShardDescriptor, Pipeline, PipelineOrchestrator)
• M27 MoE routing (ExpertDescriptor, ExpertRegistry, MoeRouter)
• M28 Federated learning (FedLearnCoordinator, RoundManifest)
• M29 LoRa beacons (32-byte frame encoding, LoraBeaconService)
• M30 Evidence graph (Claim, ClaimStore, Attestation, Dispute; EBKH import)
• M31 Civil defense NRW (Alert, RoleCertificate, AuditChain, CivilDefenseService)

---

Quality Gates — All Passing

• ruff — no lint errors
• bandit — 0 HIGH findings, intentional nosec items documented
• mypy — passes (optional deps handled with TYPE_CHECKING guards)
• pylint — no blocking issues
• pytest — 62/62 pass (51 unit + 11 E2E Playwright)

---

Test Suites

File	Tests	Coverage
tests/test_phase1_routing.py	8	Bus routing, failover, capabilities
tests/test_phase1_emergency_snapshot.py	5	Emergency mode, controller snapshot
tests/test_phase2_modules.py	23	M14-M25, X05-X07
tests/test_phase3_experimental.py	15	M26-M31, ResearchConfig
tests/test_e2e_playwright.py	11	Gradio UI E2E (real browser, Playwright)

---

Architecture Notes

• All services implement health() -> dict returning {"status": "ok" | "unavailable"}
• All service handlers receive RouteRequest(capability, version_req, body, caller, trace_id)
• Response format: {"output": {...}, "meta": {}}
• No mocks in implementation paths; heavy optional deps fail gracefully
• OpenAI only as opt-in online fallback — never the default local path
• No security-tool suppression pragmas except narrow reviewed nosec comments

---

Known Remaining Gaps

• Wire real event log (X02) into HearthNode on startup (services still use demo/fallback)
• Wire X01 FastAPI transport into node for real inter-node HTTP calls
• Wire M02 mDNS/UDP discovery into node startup
• M22 Flutter mobile app (separate repo; Python anchor-side helpers are done)
• Contract conformance suite against CAPABILITY_CONTRACT.md (X09 spec)
• Gossip sync (X02 SyncClient/Server) between live nodes
• Live UI push updates via WebSocket (X06 pubsub wired into UI)
• Add M08 mobile static app helpers (hearthnet/ui/mobile/)