feat: implement all M01-M13, X01-X04 modules + quality gate fixes

Phase 1 core implementation complete:
- M01 Identity: Ed25519 keys, canonical JSON, node/community manifests
- M02 Discovery: mDNS (zeroconf), UDP multicast, enhanced PeerRegistry
- M03 Bus: schema validation (jsonschema optional), CallTrace ring buffer
- M04 LLM: Ollama/llama.cpp/HF Transformers backends, OpenAI online fallback
- M05 RAG: sliding-window chunker, CorpusStore (Chroma + in-memory fallback)
- M06 Marketplace: event-sourced with MaterialisedView
- M07 Blobs: BLAKE3 CID store, 256KB chunking, TransferManager, FileService
- M08 UI: UiApp + 6 Gradio tabs (Ask/Chat/Market/Files/Emergency/Settings)
- M09 Emergency: async probe loop, DNS+HTTP probes, anti-flap, StateBus
- M10 Chat: event-backed ChatView, DeliveryManager
- M11 Embedding: embed.text, SimpleHashBackend (no-dep), SentenceTransformer
- M12 CLI: click-based init/run/status/caps/call/doctor/trace/export
- M13 Onboarding: InviteBlob encode/decode, QR PNG, community flows
- X01 Transport: FastAPI server (12 endpoints), signed HTTP client, SSE, TLS
- X02 Events: SQLite WAL log, LamportClock, ReplayEngine, SnapshotStore
- X03 Observability: JSON logging, prometheus metrics, trace ring, doctor
- X04 Config: typed frozen Config, TOML load/save/validate, XDG paths

Security fixes:
- Remove verify=False from emergency HTTP prober (was HIGH bandit finding)
- Add URL validation to CLI (local-only enforcement)
- nosec annotations for intentional bind-all and SQL placeholders

Quality: 13/13 tests pass; ruff auto-fixed; bandit HIGH=0, MEDIUM=7 (all justified)

hearthnet/__main__.py

@@ -0,0 +1,4 @@
+from hearthnet.cli import main
+
+if __name__ == "__main__":
+    main()

hearthnet/blobs/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from hearthnet.blobs.chunker import (
+    BlobError,
+    BlobManifest,
+    ChunkRef,
+    chunk_blob,
+    hash_bytes,
+    manifest_cid,
+    reassemble,
+    verify_chunk,
+)
+from hearthnet.blobs.store import BlobStore
+from hearthnet.blobs.transfer import TransferManager
+
+__all__ = [
+    "BlobError",
+    "BlobManifest",
+    "BlobStore",
+    "ChunkRef",
+    "TransferManager",
+    "chunk_blob",
+    "hash_bytes",
+    "manifest_cid",
+    "reassemble",
+    "verify_chunk",
+]

hearthnet/blobs/chunker.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+CHUNK_SIZE_BYTES = 256 * 1024  # 256 KB
+
+
+class BlobError(Exception):
+    def __init__(self, code: str, message: str = "") -> None:
+        super().__init__(message or code)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class ChunkRef:
+    index: int
+    cid: str  # "blake3:<hex>" or "sha256:<hex>"
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class BlobManifest:
+    cid: str  # merkle root CID
+    size_bytes: int
+    chunk_size_bytes: int
+    chunks: list[ChunkRef]
+    filename: str | None  # advisory only
+
+
+def hash_bytes(data: bytes) -> str:
+    """Hash with BLAKE3 if available, else SHA256. Returns 'blake3:<hex>' or 'sha256:<hex>'."""
+    try:
+        import blake3  # type: ignore[import]
+
+        return "blake3:" + blake3.blake3(data).hexdigest()
+    except ImportError:
+        return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def chunk_blob(
+    data: bytes, *, chunk_size: int = CHUNK_SIZE_BYTES
+) -> tuple[BlobManifest, list[bytes]]:
+    """Split data into chunks. Compute per-chunk CID and merkle-root CID."""
+    chunks_data: list[bytes] = []
+    chunk_refs: list[ChunkRef] = []
+
+    offset = 0
+    index = 0
+    while offset < len(data) or index == 0:
+        piece = data[offset : offset + chunk_size]
+        cid = hash_bytes(piece)
+        chunk_refs.append(ChunkRef(index=index, cid=cid, size_bytes=len(piece)))
+        chunks_data.append(piece)
+        offset += chunk_size
+        index += 1
+        if offset >= len(data):
+            break
+
+    merkle_root = hash_bytes(b"\n".join(sorted(c.cid.encode() for c in chunk_refs)))
+
+    manifest = BlobManifest(
+        cid=merkle_root,
+        size_bytes=len(data),
+        chunk_size_bytes=chunk_size,
+        chunks=chunk_refs,
+        filename=None,
+    )
+    return manifest, chunks_data
+
+
+def manifest_cid(manifest: BlobManifest) -> str:
+    """CID of canonical JSON of {chunks: [{cid,size_bytes}], size_bytes, chunk_size_bytes}."""
+    payload = {
+        "chunk_size_bytes": manifest.chunk_size_bytes,
+        "chunks": [{"cid": c.cid, "size_bytes": c.size_bytes} for c in manifest.chunks],
+        "size_bytes": manifest.size_bytes,
+    }
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+    return hash_bytes(raw)
+
+
+def reassemble(chunks: list[bytes]) -> bytes:
+    """Concat chunks in index order."""
+    return b"".join(chunks)
+
+
+def verify_chunk(data: bytes, expected_cid: str) -> None:
+    """Raise BlobError('hash_mismatch') if hash(data) != expected_cid."""
+    actual = hash_bytes(data)
+    if actual != expected_cid:
+        raise BlobError("hash_mismatch", f"Expected {expected_cid}, got {actual}")

hearthnet/blobs/store.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from hearthnet.blobs.chunker import (
+    BlobError,
+    BlobManifest,
+    ChunkRef,
+    chunk_blob,
+    reassemble,
+    verify_chunk,
+)
+
+
+class BlobStore:
+    """Sharded filesystem store.
+
+    Layout::
+
+        <root>/<aa>/<rest>.bin           — chunk binary
+        <root>/<aa>/<rest>.manifest.json — blob manifest
+        <root>/pinned.txt                — newline-separated pinned CIDs
+    """
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def put(self, data: bytes, filename: str | None = None) -> BlobManifest:
+        """Chunk, hash, store all chunks, write manifest, return BlobManifest."""
+        manifest, chunks_data = chunk_blob(data)
+        # Attach filename (BlobManifest is frozen, rebuild with filename)
+        manifest = BlobManifest(
+            cid=manifest.cid,
+            size_bytes=manifest.size_bytes,
+            chunk_size_bytes=manifest.chunk_size_bytes,
+            chunks=manifest.chunks,
+            filename=filename,
+        )
+        for chunk_ref, chunk_data in zip(manifest.chunks, chunks_data, strict=False):
+            path = self._blob_path(chunk_ref.cid)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if not path.exists():
+                path.write_bytes(chunk_data)
+
+        mpath = self._manifest_path(manifest.cid)
+        mpath.parent.mkdir(parents=True, exist_ok=True)
+        mpath.write_text(
+            json.dumps(self._manifest_to_dict(manifest), sort_keys=True, indent=2),
+            encoding="utf-8",
+        )
+        return manifest
+
+    def get(self, cid: str) -> bytes:
+        """Read and reassemble blob. Raise BlobError('not_found') if missing."""
+        manifest = self.get_manifest(cid)
+        chunks: list[bytes] = []
+        for chunk_ref in manifest.chunks:
+            chunk_data = self.get_chunk(chunk_ref.cid)
+            verify_chunk(chunk_data, chunk_ref.cid)
+            chunks.append(chunk_data)
+        return reassemble(chunks)
+
+    def get_chunk(self, chunk_cid: str) -> bytes:
+        """Read one chunk. Raise BlobError('not_found') if missing."""
+        path = self._blob_path(chunk_cid)
+        if not path.exists():
+            raise BlobError("not_found", f"Chunk {chunk_cid} not found")
+        return path.read_bytes()
+
+    def has(self, cid: str) -> bool:
+        """True iff blob manifest exists."""
+        return self._manifest_path(cid).exists()
+
+    def get_manifest(self, cid: str) -> BlobManifest:
+        """Load manifest from disk."""
+        path = self._manifest_path(cid)
+        if not path.exists():
+            raise BlobError("not_found", f"Blob {cid} not found")
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            raise BlobError("manifest_invalid", str(exc)) from exc
+        return self._manifest_from_dict(raw)
+
+    def list_blobs(self) -> list[BlobManifest]:
+        """List all blob manifests."""
+        manifests: list[BlobManifest] = []
+        for mpath in self.root.rglob("*.manifest.json"):
+            try:
+                raw = json.loads(mpath.read_text(encoding="utf-8"))
+                manifests.append(self._manifest_from_dict(raw))
+            except Exception:
+                pass
+        return manifests
+
+    def pin(self, cid: str) -> None:
+        """Add CID to pinned.txt."""
+        pinned = self._read_pinned()
+        pinned.add(cid)
+        self._write_pinned(pinned)
+
+    def unpin(self, cid: str) -> None:
+        """Remove CID from pinned.txt."""
+        pinned = self._read_pinned()
+        pinned.discard(cid)
+        self._write_pinned(pinned)
+
+    def gc(self, threshold: float = 0.80) -> int:
+        """Remove unpinned blobs if disk usage > threshold. Returns count removed."""
+        usage = shutil.disk_usage(self.root)
+        if usage.used / usage.total <= threshold:
+            return 0
+        pinned = self._read_pinned()
+        removed = 0
+        for manifest in self.list_blobs():
+            if manifest.cid in pinned:
+                continue
+            # Remove chunk files
+            for chunk_ref in manifest.chunks:
+                cpath = self._blob_path(chunk_ref.cid)
+                if cpath.exists():
+                    cpath.unlink()
+            # Remove manifest
+            mpath = self._manifest_path(manifest.cid)
+            if mpath.exists():
+                mpath.unlink()
+            removed += 1
+        return removed
+
+    # ------------------------------------------------------------------
+    # Path helpers
+    # ------------------------------------------------------------------
+
+    def _blob_path(self, cid: str) -> Path:
+        """<root>/<aa>/<rest>.bin where aa = first 2 hex chars of CID hex."""
+        hex_part = self._hex_part(cid)
+        shard = hex_part[:2]
+        rest = hex_part[2:]
+        return self.root / shard / f"{rest}.bin"
+
+    def _manifest_path(self, cid: str) -> Path:
+        hex_part = self._hex_part(cid)
+        shard = hex_part[:2]
+        rest = hex_part[2:]
+        return self.root / shard / f"{rest}.manifest.json"
+
+    def _hex_part(self, cid: str) -> str:
+        """Extract hex from 'blake3:<hex>' or 'sha256:<hex>'."""
+        return cid.split(":", 1)[1]
+
+    # ------------------------------------------------------------------
+    # Serialization helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _manifest_to_dict(m: BlobManifest) -> dict:
+        return {
+            "cid": m.cid,
+            "size_bytes": m.size_bytes,
+            "chunk_size_bytes": m.chunk_size_bytes,
+            "filename": m.filename,
+            "chunks": [
+                {"index": c.index, "cid": c.cid, "size_bytes": c.size_bytes} for c in m.chunks
+            ],
+        }
+
+    @staticmethod
+    def _manifest_from_dict(raw: dict) -> BlobManifest:
+        chunks = [
+            ChunkRef(index=c["index"], cid=c["cid"], size_bytes=c["size_bytes"])
+            for c in raw.get("chunks", [])
+        ]
+        return BlobManifest(
+            cid=raw["cid"],
+            size_bytes=raw["size_bytes"],
+            chunk_size_bytes=raw["chunk_size_bytes"],
+            chunks=chunks,
+            filename=raw.get("filename"),
+        )
+
+    # ------------------------------------------------------------------
+    # Pinned helpers
+    # ------------------------------------------------------------------
+
+    def _pinned_path(self) -> Path:
+        return self.root / "pinned.txt"
+
+    def _read_pinned(self) -> set[str]:
+        p = self._pinned_path()
+        if not p.exists():
+            return set()
+        return {line.strip() for line in p.read_text(encoding="utf-8").splitlines() if line.strip()}
+
+    def _write_pinned(self, pinned: set[str]) -> None:
+        self._pinned_path().write_text("\n".join(sorted(pinned)), encoding="utf-8")

hearthnet/blobs/transfer.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from hearthnet.blobs.chunker import BlobError, BlobManifest, verify_chunk
+from hearthnet.blobs.store import BlobStore
+
+
+class TransferManager:
+    """Coordinates parallel chunk fetch from multiple peer sources.
+
+    MVP: fetch from one source at a time (parallel is Phase 2 optimization).
+    """
+
+    def __init__(self, store: BlobStore, http_client=None) -> None:
+        self.store = store
+        self._http_client = http_client
+
+    async def fetch(self, cid: str, sources: list[str]) -> BlobManifest:
+        """Fetch a blob from one of the sources (tries in order).
+
+        sources: list of base URLs like 'https://host:7080'
+        """
+        last_exc: Exception | None = None
+        for base_url in sources:
+            try:
+                return await self._fetch_from(cid, base_url)
+            except Exception as exc:
+                last_exc = exc
+        raise BlobError(
+            "not_found",
+            f"Could not fetch {cid} from any source. Last error: {last_exc}",
+        )
+
+    async def _fetch_from(self, cid: str, base_url: str) -> BlobManifest:
+        """Fetch blob manifest + all chunks from base_url/file/chunks/<chunk_cid>."""
+        import json
+
+        client = self._http_client
+        if client is None:
+            try:
+                import httpx  # type: ignore[import]
+
+                client = httpx.AsyncClient()
+            except ImportError as exc:
+                raise BlobError(
+                    "io_error", "httpx is required for TransferManager network fetch"
+                ) from exc
+
+        manifest_url = f"{base_url.rstrip('/')}/file/manifest/{cid}"
+        try:
+            resp = await client.get(manifest_url, timeout=30)
+            resp.raise_for_status()
+            raw = resp.json()
+        except Exception as exc:
+            raise BlobError("io_error", f"Failed to fetch manifest from {manifest_url}: {exc}") from exc
+
+        from hearthnet.blobs.store import BlobStore as _BS
+
+        manifest = _BS._manifest_from_dict(raw)
+
+        for chunk_ref in manifest.chunks:
+            if self.store._blob_path(chunk_ref.cid).exists():
+                continue  # already have it
+            chunk_url = f"{base_url.rstrip('/')}/file/chunks/{chunk_ref.cid}"
+            try:
+                resp = await client.get(chunk_url, timeout=60)
+                resp.raise_for_status()
+                chunk_data = resp.content
+            except Exception as exc:
+                raise BlobError(
+                    "io_error", f"Failed to fetch chunk {chunk_ref.cid}: {exc}"
+                ) from exc
+            verify_chunk(chunk_data, chunk_ref.cid)
+            path = self.store._blob_path(chunk_ref.cid)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(chunk_data)
+
+        # Write manifest if not already stored
+        if not self.store.has(manifest.cid):
+            mpath = self.store._manifest_path(manifest.cid)
+            mpath.parent.mkdir(parents=True, exist_ok=True)
+            mpath.write_text(
+                json.dumps(_BS._manifest_to_dict(manifest), sort_keys=True, indent=2),
+                encoding="utf-8",
+            )
+
+        return manifest

hearthnet/bus/schema.py

@@ -0,0 +1,73 @@
+"""JSON Schema validation for capability requests/responses."""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+try:
+    import jsonschema as _jsonschema
+
+    HAS_JSONSCHEMA = True
+except ImportError:
+    _jsonschema = None  # type: ignore[assignment]
+    HAS_JSONSCHEMA = False
+
+from hearthnet.bus.capability import CapabilityDescriptor
+
+
+class SchemaValidator:
+    """JSON Schema validation with caching. No-op if jsonschema not installed."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, Any] = {}  # cache_key -> unused (validate is stateless)
+
+    def validate_request(self, descriptor: CapabilityDescriptor, body: dict) -> None:
+        """Validate request body against descriptor's request_schema.
+
+        Raises ValueError if invalid.
+        """
+        if not HAS_JSONSCHEMA or not descriptor.request_schema:
+            return
+        key = f"req:{descriptor.name}:{descriptor.version_str}"
+        self._validate(descriptor.request_schema, body, key)
+
+    def validate_response(self, descriptor: CapabilityDescriptor, response: dict) -> None:
+        """Validate response against response_schema.
+
+        Raises ValueError if invalid.
+        """
+        if not HAS_JSONSCHEMA or not descriptor.response_schema:
+            return
+        key = f"resp:{descriptor.name}:{descriptor.version_str}"
+        self._validate(descriptor.response_schema, response, key)
+
+    def validate_stream_frame(
+        self, descriptor: CapabilityDescriptor, frame: dict
+    ) -> None:
+        """Validate a streaming frame."""
+        if not HAS_JSONSCHEMA or not descriptor.stream_schema:
+            return
+        key = f"stream:{descriptor.name}:{descriptor.version_str}"
+        self._validate(descriptor.stream_schema, frame, key)
+
+    def _validate(self, schema: dict, instance: dict, cache_key: str) -> None:
+        if not HAS_JSONSCHEMA or _jsonschema is None:
+            return
+        try:
+            _jsonschema.validate(instance, schema)
+        except _jsonschema.ValidationError as exc:
+            raise ValueError(f"Schema validation failed: {exc.message}") from exc
+
+
+def compute_schema_hash(descriptor_partial: dict) -> str:
+    """SHA-256 (or BLAKE3 if available) over canonical-JSON of descriptor."""
+    canonical = json.dumps(
+        descriptor_partial, sort_keys=True, separators=(",", ":")
+    ).encode()
+    try:
+        import blake3  # type: ignore[import]
+
+        return "blake3:" + blake3.blake3(canonical).hexdigest()
+    except ImportError:
+        return "sha256:" + hashlib.sha256(canonical).hexdigest()

hearthnet/bus/trace.py

@@ -0,0 +1,36 @@
+"""Bus trace events for call tracking."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CallTraceEvent:
+    ts: str  # ISO timestamp
+    trace_id: str
+    capability: str
+    version: str
+    caller: str
+    routed_to: str  # node_id
+    is_local: bool
+    success: bool
+    error_code: str | None
+    latency_ms: int
+    bytes_in: int
+    bytes_out: int
+
+
+class TraceHook:
+    """Emits trace events to the ring buffer (X03) and Prometheus metrics."""
+
+    def __init__(self, ring_buffer: Any = None, metrics: Any = None) -> None:
+        self._ring = ring_buffer
+        self._metrics = metrics
+
+    def record(self, event: CallTraceEvent) -> None:
+        if self._ring is not None:
+            try:
+                self._ring.push(event)
+            except Exception:
+                pass

hearthnet/cli.py

@@ -0,0 +1,393 @@
+"""HearthNet CLI — `hearthnet` command."""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import urllib.parse
+import zipfile
+from pathlib import Path
+
+import click
+
+# ---------------------------------------------------------------------------
+# HTTP helpers
+# ---------------------------------------------------------------------------
+
+_ALLOWED_SCHEMES = {"http", "https"}
+_ALLOWED_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _validate_local_url(url: str) -> None:
+    """Raise ValueError if the URL is not a local node URL (security boundary)."""
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in _ALLOWED_SCHEMES:
+        raise ValueError(f"URL scheme must be http/https, got: {parsed.scheme!r}")
+    host = parsed.hostname or ""
+    if host not in _ALLOWED_HOSTS:
+        raise ValueError(
+            f"CLI only connects to local node. Got host: {host!r}. "
+            "Use --base-url http://localhost:<port> to override."
+        )
+
+
+def _http_get(url: str) -> dict:
+    _validate_local_url(url)
+    try:
+        import httpx
+
+        resp = httpx.get(url, timeout=5)
+        resp.raise_for_status()
+        return resp.json()
+    except ImportError:
+        import urllib.error
+        import urllib.request
+
+        try:
+            with urllib.request.urlopen(url, timeout=5) as r:
+                return json.loads(r.read().decode())
+        except urllib.error.URLError as exc:
+            raise ConnectionError(str(exc)) from exc
+    except Exception as exc:
+        msg = str(exc).lower()
+        if any(kw in msg for kw in ("connect", "refused", "unreachable", "network")):
+            raise ConnectionError(str(exc)) from exc
+        raise
+
+
+def _http_post(url: str, body: str) -> dict:
+    _validate_local_url(url)
+    try:
+        import httpx
+
+        resp = httpx.post(url, content=body, headers={"Content-Type": "application/json"}, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+    except ImportError:
+        import urllib.error
+        import urllib.request
+
+        req = urllib.request.Request(
+            url,
+            data=body.encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as r:
+                return json.loads(r.read().decode())
+        except urllib.error.URLError as exc:
+            raise ConnectionError(str(exc)) from exc
+    except Exception as exc:
+        msg = str(exc).lower()
+        if any(kw in msg for kw in ("connect", "refused", "unreachable", "network")):
+            raise ConnectionError(str(exc)) from exc
+        raise
+
+
+# ---------------------------------------------------------------------------
+# CLI group
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+@click.option("--config", "config_path", type=click.Path(), default=None, help="Path to config.toml")
+@click.pass_context
+def main(ctx: click.Context, config_path: str | None) -> None:
+    """HearthNet — community-owned local AI mesh."""
+    ctx.ensure_object(dict)
+    ctx.obj["config_path"] = Path(config_path) if config_path else None
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--name", default=None, help="Display name for this node")
+@click.option(
+    "--profile",
+    type=click.Choice(["anchor", "hearth", "spark"]),
+    default="hearth",
+)
+@click.option("--non-interactive", is_flag=True)
+def init(name: str | None, profile: str, non_interactive: bool) -> None:
+    """Bootstrap a new HearthNet node. Generates keypair, writes config."""
+    config_dir = Path.home() / ".hearthnet"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    keys_dir = config_dir / "keys"
+    keys_dir.mkdir(parents=True, exist_ok=True)
+
+    if not name and not non_interactive:
+        name = click.prompt("Node display name", default=f"HearthNode-{os.urandom(2).hex()}")
+    elif not name:
+        name = f"HearthNode-{os.urandom(2).hex()}"
+
+    try:
+        from hearthnet.identity import load_or_generate
+
+        kp = load_or_generate(keys_dir)
+        click.echo(f"Node ID  : {kp.node_id_full}")
+        click.echo(f"Short ID : {kp.node_id_short}")
+    except Exception as exc:
+        click.echo(f"Warning: could not generate keypair ({exc}). Skipping.", err=True)
+
+    config_file = config_dir / "config.toml"
+    if not config_file.exists():
+        config_file.write_text(
+            f'[node]\nname = "{name}"\nprofile = "{profile}"\n\n[identity]\nkeys_dir = "{keys_dir}"\n'
+        )
+        click.echo(f"Config written to {config_file}")
+    else:
+        click.echo(f"Config already exists at {config_file} — not overwritten.")
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--no-ui", is_flag=True, help="Run without Gradio UI")
+@click.option("--debug", is_flag=True)
+@click.pass_context
+def run(ctx: click.Context, no_ui: bool, debug: bool) -> None:
+    """Start the HearthNet node."""
+    if debug:
+        import logging
+
+        logging.basicConfig(level=logging.DEBUG)
+
+    click.echo("HearthNet node starting…")
+
+    if not no_ui:
+        try:
+            from app import demo  # type: ignore[import]
+
+            demo.launch()
+        except Exception as exc:
+            click.echo(f"Could not start Gradio UI: {exc}", err=True)
+            click.echo("Try `hearthnet run --no-ui` to start without UI.")
+            sys.exit(1)
+    else:
+        click.echo("Running in headless mode. Press Ctrl+C to stop.")
+        try:
+            asyncio.run(_headless())
+        except KeyboardInterrupt:
+            click.echo("Shutting down.")
+
+
+async def _headless() -> None:
+    while True:
+        await asyncio.sleep(3600)
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--json", "as_json", is_flag=True)
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", default=7080, type=int)
+@click.pass_context
+def status(ctx: click.Context, as_json: bool, host: str, port: int) -> None:
+    """Show node status (requires a running node)."""
+    url = f"http://{host}:{port}/health"
+    try:
+        data = _http_get(url)
+    except ConnectionError:
+        click.echo(f"Node not reachable at {host}:{port}")
+        sys.exit(3)
+
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+    else:
+        click.echo(f"Status   : {data.get('status', 'unknown')}")
+        click.echo(f"Node ID  : {data.get('node_id', 'N/A')}")
+        click.echo(f"Version  : {data.get('version', 'N/A')}")
+        extras = {k: v for k, v in data.items() if k not in ("status", "node_id", "version")}
+        for k, v in extras.items():
+            click.echo(f"{k:<10}: {v}")
+
+
+# ---------------------------------------------------------------------------
+# caps
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--remote-only", is_flag=True)
+@click.option("--local-only", is_flag=True)
+@click.option("--name", "name_pattern", default=None)
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", default=7080, type=int)
+def caps(
+    remote_only: bool,
+    local_only: bool,
+    name_pattern: str | None,
+    host: str,
+    port: int,
+) -> None:
+    """List capability entries."""
+    url = f"http://{host}:{port}/bus/v1/capabilities"
+    try:
+        data = _http_get(url)
+    except ConnectionError:
+        click.echo(f"Node not reachable at {host}:{port}")
+        sys.exit(3)
+
+    entries = data if isinstance(data, list) else data.get("capabilities", [])
+
+    if remote_only:
+        entries = [e for e in entries if not e.get("local", False)]
+    elif local_only:
+        entries = [e for e in entries if e.get("local", False)]
+
+    if name_pattern:
+        entries = [e for e in entries if name_pattern.lower() in e.get("name", "").lower()]
+
+    if not entries:
+        click.echo("No capabilities found.")
+        return
+
+    click.echo(f"{'NAME':<30} {'VERSION':<10} {'STABILITY':<12} {'LOCAL'}")
+    click.echo("-" * 60)
+    for entry in entries:
+        click.echo(
+            f"{entry.get('name', '?'):<30} "
+            f"{entry.get('version', '?'):<10} "
+            f"{entry.get('stability', '?'):<12} "
+            f"{'yes' if entry.get('local') else 'no'}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# call
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.argument("capability")
+@click.option("--body", default="{}", help="JSON body")
+@click.option("--stream", is_flag=True)
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", default=7080, type=int)
+def call(capability: str, body: str, stream: bool, host: str, port: int) -> None:
+    """Make a one-shot capability call."""
+    # Validate body is valid JSON before sending
+    try:
+        json.loads(body)
+    except json.JSONDecodeError as exc:
+        click.echo(f"Invalid JSON body: {exc}", err=True)
+        sys.exit(1)
+
+    url = f"http://{host}:{port}/bus/v1/call"
+    payload = json.dumps({"capability": capability, "body": json.loads(body)})
+    try:
+        result = _http_post(url, payload)
+    except ConnectionError:
+        click.echo(f"Node not reachable at {host}:{port}")
+        sys.exit(3)
+
+    click.echo(json.dumps(result, indent=2))
+
+
+# ---------------------------------------------------------------------------
+# doctor
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--check", default=None, help="Run specific check by name")
+def doctor(check: str | None) -> None:
+    """Run self-diagnostics."""
+    try:
+        from hearthnet.observability.doctor import run_all, run_one
+
+        if check:
+            results = [run_one(check)]
+        else:
+            results = run_all()
+        all_passed = all(r.passed for r in results)
+        for r in results:
+            icon = "✔" if r.passed else "✘"
+            click.echo(f"  {icon}  {r.check.name:<25} {r.message}")
+            if not r.passed and r.check.fix_hint:
+                click.echo(f"       → fix: {r.check.fix_hint}")
+        sys.exit(0 if all_passed else 1)
+    except Exception as exc:
+        click.echo(f"doctor crashed: {exc}", err=True)
+        sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# trace
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.argument("n", default=20, type=int)
+@click.option("--capability", default=None)
+@click.option("--host", default="127.0.0.1")
+@click.option("--port", default=7080, type=int)
+def trace(n: int, capability: str | None, host: str, port: int) -> None:
+    """Show recent call traces."""
+    url = f"http://{host}:{port}/trace/recent?n={n}"
+    if capability:
+        url += f"&capability={capability}"
+    try:
+        data = _http_get(url)
+    except ConnectionError:
+        click.echo(f"Node not reachable at {host}:{port}")
+        sys.exit(3)
+
+    entries = data if isinstance(data, list) else data.get("traces", [])
+    if not entries:
+        click.echo("No traces found.")
+        return
+
+    for entry in entries:
+        ts = entry.get("ts", "?")
+        cap = entry.get("capability", "?")
+        dur = entry.get("duration_ms", "?")
+        ok = "OK" if entry.get("success", True) else "ERR"
+        click.echo(f"  [{ts}] {cap:<30} {dur:>6}ms  {ok}")
+
+
+# ---------------------------------------------------------------------------
+# export
+# ---------------------------------------------------------------------------
+
+
+@main.command()
+@click.option("--out", type=click.Path(), default=None)
+def export(out: str | None) -> None:
+    """Export all local data (GDPR right-to-export)."""
+    config_dir = Path.home() / ".hearthnet"
+    out_path = Path(out) if out else Path.cwd() / "hearthnet-export.zip"
+
+    try:
+        with zipfile.ZipFile(out_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            if config_dir.exists():
+                for item in config_dir.rglob("*"):
+                    # Skip private key material
+                    if item.suffix in (".key", ".pem") or item.name.startswith("signing"):
+                        continue
+                    if item.is_file():
+                        zf.write(item, item.relative_to(config_dir.parent))
+            # Add a manifest of what was exported
+            manifest = {
+                "export_version": 1,
+                "exported_from": str(config_dir),
+                "contains": "node config, identity (public parts only)",
+            }
+            zf.writestr("EXPORT_MANIFEST.json", json.dumps(manifest, indent=2))
+        click.echo(f"Exported to {out_path}")
+    except Exception as exc:
+        click.echo(f"Export failed: {exc}", err=True)
+        sys.exit(1)

hearthnet/config.py

@@ -0,0 +1,498 @@
+"""HearthNet — X04 Configuration.
+
+Typed, frozen config loaded from TOML. No module reads env-vars or files
+directly — they all use a Config instance handed to them.
+"""
+from __future__ import annotations
+
+import os
+import tomllib  # stdlib ≥ 3.11; fallback below
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from hearthnet.constants import (
+    CHUNK_SIZE_BYTES,
+    EMBED_DEFAULT_MODEL,
+    HTTP_PORT,
+    MARKET_DEFAULT_TTL_SECONDS,
+    MARKET_MAX_TTL_SECONDS,
+    UI_PORT,
+)
+
+# ── Fall back to tomli for Python < 3.11 ────────────────────────────────────
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:
+        tomllib = None  # type: ignore[assignment]
+
+
+# ── Sub-config dataclasses ───────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class IdentityConfig:
+    keys_dir: Path = field(default_factory=lambda: Path())
+    auto_generate: bool = True
+
+
+@dataclass(frozen=True)
+class CommunityConfig:
+    community_id: str | None = None
+    state_dir: Path = field(default_factory=lambda: Path())
+
+
+@dataclass(frozen=True)
+class TransportConfig:
+    host: str = "0.0.0.0"
+    port: int = HTTP_PORT
+    tls_cert: Path | None = None
+    tls_key: Path | None = None
+
+
+@dataclass(frozen=True)
+class DiscoveryConfig:
+    mdns_enabled: bool = True
+    udp_enabled: bool = True
+    udp_port: int = 7079
+    relay_urls: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class BusConfig:
+    prefer_local: bool = True
+    local_load_threshold: float = 0.80
+
+
+@dataclass(frozen=True)
+class LlmBackendConfig:
+    name: str
+    model: str = ""
+    base_url: str = ""
+    api_key_env: str | None = None
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class LlmConfig:
+    backends: tuple[LlmBackendConfig, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class EmbeddingConfig:
+    model: str = EMBED_DEFAULT_MODEL
+    device: str = "auto"
+
+
+@dataclass(frozen=True)
+class RagConfig:
+    enabled: bool = True
+    corpora_dir: Path = field(default_factory=lambda: Path())
+
+
+@dataclass(frozen=True)
+class FileConfig:
+    blobs_dir: Path = field(default_factory=lambda: Path())
+    chunk_size_bytes: int = CHUNK_SIZE_BYTES
+    gc_threshold: float = 0.80
+
+
+@dataclass(frozen=True)
+class MarketConfig:
+    enabled: bool = True
+    default_ttl_seconds: int = MARKET_DEFAULT_TTL_SECONDS
+    max_ttl_seconds: int = MARKET_MAX_TTL_SECONDS
+
+
+@dataclass(frozen=True)
+class ChatConfig:
+    enabled: bool = True
+    store_and_forward: bool = True
+    read_receipts_enabled: bool = True
+
+
+@dataclass(frozen=True)
+class EmergencyConfig:
+    probe_targets: tuple[str, ...] = field(
+        default_factory=lambda: (
+            "1.1.1.1",
+            "8.8.8.8",
+            "https://cloudflare.com",
+            "https://quad9.net",
+        )
+    )
+
+
+@dataclass(frozen=True)
+class UiConfig:
+    host: str = "127.0.0.1"
+    port: int = UI_PORT
+    launch_browser: bool = True
+
+
+@dataclass(frozen=True)
+class ObservabilityConfig:
+    log_level: str = "info"
+    log_dir: Path | None = None
+    metrics_enabled: bool = True
+    otlp_endpoint: str | None = None
+
+
+@dataclass(frozen=True)
+class Config:
+    identity: IdentityConfig = field(default_factory=IdentityConfig)
+    community: CommunityConfig = field(default_factory=CommunityConfig)
+    transport: TransportConfig = field(default_factory=TransportConfig)
+    discovery: DiscoveryConfig = field(default_factory=DiscoveryConfig)
+    bus: BusConfig = field(default_factory=BusConfig)
+    llm: LlmConfig = field(default_factory=LlmConfig)
+    embedding: EmbeddingConfig = field(default_factory=EmbeddingConfig)
+    rag: RagConfig = field(default_factory=RagConfig)
+    file: FileConfig = field(default_factory=FileConfig)
+    market: MarketConfig = field(default_factory=MarketConfig)
+    chat: ChatConfig = field(default_factory=ChatConfig)
+    emergency: EmergencyConfig = field(default_factory=EmergencyConfig)
+    ui: UiConfig = field(default_factory=UiConfig)
+    observability: ObservabilityConfig = field(default_factory=ObservabilityConfig)
+
+
+# ── ConfigError ───────────────────────────────────────────────────────────────
+
+class ConfigError(Exception):
+    def __init__(self, code: str, **kwargs: object) -> None:
+        super().__init__(code)
+        self.code = code
+        self.context = kwargs
+
+
+# ── XDG path resolution ──────────────────────────────────────────��────────────
+
+def _xdg_data() -> Path:
+    raw = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return Path(raw) / "hearthnet"
+
+
+def _xdg_config() -> Path:
+    raw = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return Path(raw) / "hearthnet"
+
+
+def _xdg_cache() -> Path:
+    raw = os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache")
+    return Path(raw) / "hearthnet"
+
+
+def _default_config_path() -> Path:
+    return _xdg_config() / "config.toml"
+
+
+# ── Path resolution ───────────────────────────────────────────────────────────
+
+def resolve_paths(config: Config) -> Config:
+    """Fill empty Path() fields with XDG-standard locations. Idempotent."""
+    data = _xdg_data()
+    cache = _xdg_cache()
+    cfg = _xdg_config()
+
+    identity = config.identity
+    if identity.keys_dir == Path():
+        identity = IdentityConfig(
+            keys_dir=data / "keys",
+            auto_generate=identity.auto_generate,
+        )
+
+    community = config.community
+    if community.state_dir == Path():
+        cid = community.community_id or "default"
+        community = CommunityConfig(
+            community_id=community.community_id,
+            state_dir=data / "communities" / cid,
+        )
+
+    transport = config.transport
+    tls_cert = transport.tls_cert or data / "tls" / "server.crt"
+    tls_key = transport.tls_key or data / "tls" / "server.key"
+    transport = TransportConfig(
+        host=transport.host,
+        port=transport.port,
+        tls_cert=tls_cert,
+        tls_key=tls_key,
+    )
+
+    rag = config.rag
+    if rag.corpora_dir == Path():
+        rag = RagConfig(enabled=rag.enabled, corpora_dir=cache / "embeddings")
+
+    file_cfg = config.file
+    if file_cfg.blobs_dir == Path():
+        file_cfg = FileConfig(
+            blobs_dir=data / "blobs",
+            chunk_size_bytes=file_cfg.chunk_size_bytes,
+            gc_threshold=file_cfg.gc_threshold,
+        )
+
+    obs = config.observability
+    if obs.log_dir is None:
+        obs = ObservabilityConfig(
+            log_level=obs.log_level,
+            log_dir=data / "logs",
+            metrics_enabled=obs.metrics_enabled,
+            otlp_endpoint=obs.otlp_endpoint,
+        )
+
+    return Config(
+        identity=identity,
+        community=community,
+        transport=transport,
+        discovery=config.discovery,
+        bus=config.bus,
+        llm=config.llm,
+        embedding=config.embedding,
+        rag=rag,
+        file=file_cfg,
+        market=config.market,
+        chat=config.chat,
+        emergency=config.emergency,
+        ui=config.ui,
+        observability=obs,
+    )
+
+
+# ── Validation ────────────────────────────────────────────────────────────────
+
+def validate(config: Config) -> None:
+    """Cross-field validation. Raises ConfigError on failure."""
+    t = config.transport
+    d = config.discovery
+    if t.port == d.udp_port:
+        raise ConfigError("invalid_field", field="transport.port/discovery.udp_port",
+                          reason="transport port and UDP discovery port must differ")
+    if not (1 <= t.port <= 65535):
+        raise ConfigError("invalid_field", field="transport.port", reason="port out of range")
+    if config.bus.local_load_threshold <= 0 or config.bus.local_load_threshold > 1:
+        raise ConfigError("invalid_field", field="bus.local_load_threshold",
+                          reason="must be in (0, 1]")
+
+
+# ── TOML parsing helpers ──────────────────────────────────────────────────────
+
+def _parse_toml(text: str) -> dict:
+    if tomllib is None:
+        raise ConfigError("invalid_toml", reason="no TOML parser available (install tomli)")
+    try:
+        return tomllib.loads(text)
+    except Exception as exc:
+        raise ConfigError("invalid_toml", reason=str(exc)) from exc
+
+
+def _from_dict(raw: dict) -> Config:
+    def _path(v: object) -> Path:
+        return Path(v) if v else Path()
+
+    identity_raw = raw.get("identity", {})
+    identity = IdentityConfig(
+        keys_dir=_path(identity_raw.get("keys_dir")),
+        auto_generate=bool(identity_raw.get("auto_generate", True)),
+    )
+
+    community_raw = raw.get("community", {})
+    community = CommunityConfig(
+        community_id=community_raw.get("community_id") or None,
+        state_dir=_path(community_raw.get("state_dir")),
+    )
+
+    transport_raw = raw.get("transport", {})
+    transport = TransportConfig(
+        host=str(transport_raw.get("host", "0.0.0.0")),
+        port=int(transport_raw.get("port", HTTP_PORT)),
+        tls_cert=_path(transport_raw.get("tls_cert")) or None,
+        tls_key=_path(transport_raw.get("tls_key")) or None,
+    )
+
+    discovery_raw = raw.get("discovery", {})
+    discovery = DiscoveryConfig(
+        mdns_enabled=bool(discovery_raw.get("mdns_enabled", True)),
+        udp_enabled=bool(discovery_raw.get("udp_enabled", True)),
+        udp_port=int(discovery_raw.get("udp_port", 7079)),
+        relay_urls=tuple(discovery_raw.get("relay_urls", [])),
+    )
+
+    bus_raw = raw.get("bus", {})
+    bus = BusConfig(
+        prefer_local=bool(bus_raw.get("prefer_local", True)),
+        local_load_threshold=float(bus_raw.get("local_load_threshold", 0.80)),
+    )
+
+    llm_raw = raw.get("llm", {})
+    backends = []
+    for b in llm_raw.get("backends", []):
+        backends.append(LlmBackendConfig(
+            name=str(b["name"]),
+            model=str(b.get("model", "")),
+            base_url=str(b.get("base_url", "")),
+            api_key_env=b.get("api_key_env") or None,
+        ))
+    llm = LlmConfig(backends=tuple(backends))
+
+    embedding_raw = raw.get("embedding", {})
+    embedding = EmbeddingConfig(
+        model=str(embedding_raw.get("model", EMBED_DEFAULT_MODEL)),
+        device=str(embedding_raw.get("device", "auto")),
+    )
+
+    rag_raw = raw.get("rag", {})
+    rag = RagConfig(
+        enabled=bool(rag_raw.get("enabled", True)),
+        corpora_dir=_path(rag_raw.get("corpora_dir")),
+    )
+
+    file_raw = raw.get("file", {})
+    file_cfg = FileConfig(
+        blobs_dir=_path(file_raw.get("blobs_dir")),
+        chunk_size_bytes=int(file_raw.get("chunk_size_bytes", CHUNK_SIZE_BYTES)),
+        gc_threshold=float(file_raw.get("gc_threshold", 0.80)),
+    )
+
+    market_raw = raw.get("market", {})
+    market = MarketConfig(
+        enabled=bool(market_raw.get("enabled", True)),
+        default_ttl_seconds=int(market_raw.get("default_ttl_seconds", MARKET_DEFAULT_TTL_SECONDS)),
+        max_ttl_seconds=int(market_raw.get("max_ttl_seconds", MARKET_MAX_TTL_SECONDS)),
+    )
+
+    chat_raw = raw.get("chat", {})
+    chat = ChatConfig(
+        enabled=bool(chat_raw.get("enabled", True)),
+        store_and_forward=bool(chat_raw.get("store_and_forward", True)),
+        read_receipts_enabled=bool(chat_raw.get("read_receipts_enabled", True)),
+    )
+
+    emergency_raw = raw.get("emergency", {})
+    emergency = EmergencyConfig(
+        probe_targets=tuple(emergency_raw.get("probe_targets", [
+            "1.1.1.1", "8.8.8.8", "https://cloudflare.com", "https://quad9.net",
+        ])),
+    )
+
+    ui_raw = raw.get("ui", {})
+    ui = UiConfig(
+        host=str(ui_raw.get("host", "127.0.0.1")),
+        port=int(ui_raw.get("port", UI_PORT)),
+        launch_browser=bool(ui_raw.get("launch_browser", True)),
+    )
+
+    obs_raw = raw.get("observability", {})
+    obs = ObservabilityConfig(
+        log_level=str(obs_raw.get("log_level", "info")),
+        log_dir=_path(obs_raw.get("log_dir")) or None,
+        metrics_enabled=bool(obs_raw.get("metrics_enabled", True)),
+        otlp_endpoint=obs_raw.get("otlp_endpoint") or None,
+    )
+
+    return Config(
+        identity=identity,
+        community=community,
+        transport=transport,
+        discovery=discovery,
+        bus=bus,
+        llm=llm,
+        embedding=embedding,
+        rag=rag,
+        file=file_cfg,
+        market=market,
+        chat=chat,
+        emergency=emergency,
+        ui=ui,
+        observability=obs,
+    )
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def default_config() -> Config:
+    """Return a Config populated entirely from defaults."""
+    return resolve_paths(Config())
+
+
+def load(path: Path | None = None) -> Config:
+    """Load from TOML file; apply defaults for omitted sections; validate."""
+    cfg_path = path or _default_config_path()
+    if not cfg_path.exists():
+        cfg = default_config()
+        validate(cfg)
+        return cfg
+    try:
+        text = cfg_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError("path_resolution", reason=str(exc)) from exc
+    raw = _parse_toml(text)
+    cfg = resolve_paths(_from_dict(raw))
+    validate(cfg)
+    return cfg
+
+
+def save(config: Config, path: Path | None = None) -> None:
+    """Serialise config to TOML atomically."""
+    import tempfile
+
+    cfg_path = path or _default_config_path()
+    cfg_path.parent.mkdir(parents=True, exist_ok=True)
+
+    lines: list[str] = []
+    lines.append("[identity]")
+    lines.append(f'keys_dir = "{config.identity.keys_dir}"')
+    lines.append(f"auto_generate = {str(config.identity.auto_generate).lower()}")
+    lines.append("")
+    lines.append("[community]")
+    if config.community.community_id:
+        lines.append(f'community_id = "{config.community.community_id}"')
+    lines.append(f'state_dir = "{config.community.state_dir}"')
+    lines.append("")
+    lines.append("[transport]")
+    lines.append(f'host = "{config.transport.host}"')
+    lines.append(f"port = {config.transport.port}")
+    if config.transport.tls_cert:
+        lines.append(f'tls_cert = "{config.transport.tls_cert}"')
+    if config.transport.tls_key:
+        lines.append(f'tls_key = "{config.transport.tls_key}"')
+    lines.append("")
+    lines.append("[discovery]")
+    lines.append(f"mdns_enabled = {str(config.discovery.mdns_enabled).lower()}")
+    lines.append(f"udp_enabled = {str(config.discovery.udp_enabled).lower()}")
+    lines.append(f"udp_port = {config.discovery.udp_port}")
+    if config.discovery.relay_urls:
+        urls = ", ".join(f'"{u}"' for u in config.discovery.relay_urls)
+        lines.append(f"relay_urls = [{urls}]")
+    lines.append("")
+    lines.append("[bus]")
+    lines.append(f"prefer_local = {str(config.bus.prefer_local).lower()}")
+    lines.append(f"local_load_threshold = {config.bus.local_load_threshold}")
+    lines.append("")
+    lines.append("[embedding]")
+    lines.append(f'model = "{config.embedding.model}"')
+    lines.append(f'device = "{config.embedding.device}"')
+    lines.append("")
+    lines.append("[rag]")
+    lines.append(f"enabled = {str(config.rag.enabled).lower()}")
+    lines.append(f'corpora_dir = "{config.rag.corpora_dir}"')
+    lines.append("")
+    lines.append("[observability]")
+    lines.append(f'log_level = "{config.observability.log_level}"')
+    lines.append(f"metrics_enabled = {str(config.observability.metrics_enabled).lower()}")
+    if config.observability.log_dir:
+        lines.append(f'log_dir = "{config.observability.log_dir}"')
+
+    content = "\n".join(lines) + "\n"
+    fd, tmp = tempfile.mkstemp(dir=cfg_path.parent, prefix=".config_tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        os.replace(tmp, cfg_path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

hearthnet/constants.py

@@ -0,0 +1,75 @@
+"""HearthNet — compile-time constants (numeric defaults, limits).
+
+All module code that needs a tunable default imports from here.
+Never hardcode these values inline.
+"""
+from __future__ import annotations
+
+# ── Node manifest ────────────────────────────────────────────────────────────
+MANIFEST_TTL_SECONDS: int = 30
+MANIFEST_REFRESH_BEFORE_EXPIRY_SECONDS: int = 10
+
+# ── Discovery ────────────────────────────────────────────────────────────────
+MDNS_SERVICE_TYPE: str = "_hearthnet._tcp.local."
+UDP_MULTICAST_GROUP: str = "224.0.0.251"
+UDP_MULTICAST_PORT: int = 7079
+UDP_ANNOUNCE_INTERVAL_ONLINE_SECONDS: int = 15
+UDP_ANNOUNCE_INTERVAL_OFFLINE_SECONDS: int = 5
+PEER_PRUNE_NORMAL_SECONDS: int = 90
+PEER_PRUNE_AGGRESSIVE_SECONDS: int = 30
+PEER_REFRESH_INTERVAL_SECONDS: int = 30
+
+# ── Transport ────────────────────────────────────────────────────────────────
+HTTP_PORT: int = 7080
+UI_PORT: int = 7860
+CONNECTION_IDLE_SECONDS: int = 60
+RECONNECT_BACKOFF_CAP_SECONDS: int = 30
+RATE_LIMIT_WINDOW_SECONDS: int = 60
+RATE_LIMIT_MAX_CALLS: int = 200
+
+# ── Bus ──────────────────────────────────────────────────────────────────────
+BUS_HEALTH_WINDOW: int = 20          # samples per ring-buffer window
+BUS_QUARANTINE_SECONDS: int = 60
+BUS_FRESHNESS_SECONDS: int = 60
+BUS_LOCAL_LOAD_THRESHOLD: float = 0.80
+
+# ── Emergency detector ───────────────────────────────────────────────────────
+EMERGENCY_PROBE_INTERVAL_ONLINE_SECONDS: int = 30
+EMERGENCY_PROBE_INTERVAL_OFFLINE_SECONDS: int = 10
+EMERGENCY_PROBE_TIMEOUT_SECONDS: int = 5
+EMERGENCY_TRANSITION_DEBOUNCE_SECONDS: int = 5
+EMERGENCY_ANTI_FLAP_WINDOW_SECONDS: int = 60
+EMERGENCY_ANTI_FLAP_MAX_TRANSITIONS: int = 3
+EMERGENCY_CLOCK_SKEW_WARN_SECONDS: int = 60
+
+# ── Blobs ─────────────────────────────────────────────────────────────────────
+CHUNK_SIZE_BYTES: int = 256 * 1024  # 256 KB
+BLOB_GC_THRESHOLD: float = 0.80
+
+# ── Events / Lamport ─────────────────────────────────────────────────────────
+SNAPSHOT_KEEP_LAST_N: int = 7
+
+# ── Observability ─────────────────────────────────────────────────────────────
+LOG_RETENTION_DAYS: int = 14
+TRACE_RING_BUFFER_SIZE: int = 1000
+
+# ── Onboarding ───────────────────────────────────────────────────────────────
+INVITE_DEFAULT_TTL_SECONDS: int = 86400   # 24 h
+
+# ── RAG / Embedding ──────────────────────────────────────────────────────────
+RAG_DEFAULT_CHUNK_SIZE_TOKENS: int = 512
+EMBED_MAX_TEXTS: int = 256
+EMBED_MAX_CHARS: int = 8192
+RAG_OVERLAP_TOKENS: int = 64
+EMBED_MAX_TEXTS: int = 256
+EMBED_MAX_CHARS: int = 8192
+EMBED_DEFAULT_MODEL: str = "BAAI/bge-small-en-v1.5"
+
+# ── LLM ──────────────────────────────────────────────────────────────────────
+LLM_STREAM_CANCEL_TIMEOUT_MS: int = 200
+
+# ── Marketplace ──────────────────────────────────────────────────────────────
+MARKET_SWEEP_INTERVAL_SECONDS: int = 60
+MARKET_DEFAULT_TTL_SECONDS: int = 86400 * 7   # 1 week
+MARKET_MAX_TTL_SECONDS: int = 86400 * 30      # 30 days
+MARKET_SEARCH_CACHE_MAX: int = 5000

hearthnet/discovery/__init__.py

@@ -1,3 +1,9 @@
-from hearthnet.discovery.peers import PeerRecord, PeerRegistry
+from hearthnet.discovery.mdns import MdnsAnnouncer, MdnsBrowser
+from hearthnet.discovery.peers import PeerEvent, PeerRecord, PeerRegistry
+from hearthnet.discovery.udp import UdpAnnouncer, UdpListener
 
-__all__ = ["PeerRecord", "PeerRegistry"]
+__all__ = [
+    "PeerRecord", "PeerRegistry", "PeerEvent",
+    "MdnsAnnouncer", "MdnsBrowser",
+    "UdpAnnouncer", "UdpListener",
+]

hearthnet/discovery/mdns.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import asyncio
+import time
+
+# Optional: python-zeroconf
+try:
+    from zeroconf import ServiceInfo
+    from zeroconf.asyncio import AsyncServiceBrowser, AsyncZeroconf
+    HAS_ZEROCONF = True
+except ImportError:
+    HAS_ZEROCONF = False
+
+from hearthnet.constants import MDNS_SERVICE_TYPE
+from hearthnet.discovery.peers import PeerRecord, PeerRegistry
+from hearthnet.types import Endpoint
+
+
+class MdnsAnnouncer:
+    """Publishes our own service via mDNS. No-op if zeroconf not available."""
+
+    def __init__(
+        self,
+        registry: PeerRegistry,
+        node_id: str,
+        display_name: str,
+        port: int = 7080,
+        properties: dict | None = None,
+    ) -> None:
+        self._registry = registry
+        self._node_id = node_id
+        self._display_name = display_name
+        self._port = port
+        self._properties = properties or {}
+        self._zeroconf = None
+        self._info = None
+
+    async def start(self) -> None:
+        if not HAS_ZEROCONF:
+            return
+        try:
+            import socket
+            self._zeroconf = AsyncZeroconf()
+            short = self._node_id.replace("ed25519:", "")[:8]
+            name = f"{self._display_name[:20]}-{short}.{MDNS_SERVICE_TYPE}"
+            props = {
+                "v": "1",
+                "node": self._node_id,
+                "profile": self._properties.get("profile", "hearth"),
+                "caps": ",".join(self._properties.get("caps", [])),
+                "contract_version": "1.0",
+            }
+            self._info = ServiceInfo(
+                MDNS_SERVICE_TYPE,
+                name,
+                addresses=[socket.inet_aton("127.0.0.1")],
+                port=self._port,
+                properties={k: v.encode() for k, v in props.items()},
+            )
+            await self._zeroconf.async_register_service(self._info)
+        except Exception:
+            pass  # mDNS failure is non-fatal
+
+    async def stop(self) -> None:
+        if self._zeroconf and self._info:
+            try:
+                await self._zeroconf.async_unregister_service(self._info)
+                await self._zeroconf.async_close()
+            except Exception:
+                pass
+
+
+class MdnsBrowser:
+    """Listens for other HearthNet nodes via mDNS, populates the registry."""
+
+    def __init__(self, registry: PeerRegistry, our_community_id: str) -> None:
+        self._registry = registry
+        self._community_id = our_community_id
+        self._zeroconf = None
+        self._browser = None
+
+    async def start(self) -> None:
+        if not HAS_ZEROCONF:
+            return
+        try:
+            self._zeroconf = AsyncZeroconf()
+            self._browser = AsyncServiceBrowser(
+                self._zeroconf.zeroconf,
+                MDNS_SERVICE_TYPE,
+                handlers=[self._on_service_state_change],
+            )
+        except Exception:
+            pass
+
+    def _on_service_state_change(self, zeroconf, service_type, name, state_change) -> None:
+        asyncio.create_task(self._handle_change(zeroconf, service_type, name, state_change))
+
+    async def _handle_change(self, zeroconf, service_type, name, state_change) -> None:
+        try:
+            from zeroconf import ServiceStateChange
+            if state_change in (ServiceStateChange.Added, ServiceStateChange.Updated):
+                info = await zeroconf.async_get_service_info(service_type, name)
+                if info:
+                    props = {
+                        k.decode(): v.decode()
+                        for k, v in info.properties.items()
+                        if isinstance(k, bytes)
+                    }
+                    node_id = props.get("node", "")
+                    if not node_id:
+                        return
+                    import socket
+                    addresses = [socket.inet_ntoa(a) for a in info.addresses]
+                    host = addresses[0] if addresses else "127.0.0.1"
+                    record = PeerRecord(
+                        node_id_full=node_id,
+                        display_name=name.split(".")[0],
+                        community_id=props.get("community", ""),
+                        profile=props.get("profile", "hearth"),
+                        endpoints=[Endpoint("https", host, info.port)],
+                        last_seen=time.monotonic(),
+                        source="mdns",
+                    )
+                    self._registry.upsert(record)
+            # ServiceStateChange.Removed: let pruner handle it
+        except Exception:
+            pass
+
+    async def stop(self) -> None:
+        if self._zeroconf:
+            try:
+                await self._zeroconf.async_close()
+            except Exception:
+                pass

hearthnet/discovery/peers.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+import asyncio
 import time
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, AsyncIterator
 
 from hearthnet.types import CommunityID, Endpoint, NodeID, Profile
 
@@ -16,12 +17,13 @@ class PeerRecord:
     endpoints: list[Endpoint] = field(default_factory=list)
     manifest: dict[str, Any] | None = None
     last_seen: float = field(default_factory=time.monotonic)
-    rtt_ms: float | None = None
-    source: str = "simulated"
+    source: str = "memory"  # "mdns" | "udp" | "relay" | "memory"
+    latency_ms: float = 0.0
 
     @property
     def node_id(self) -> str:
-        return self.node_id_full.split(":", 1)[-1][:12]
+        """Short form: first 12 chars after 'ed25519:' or the full node_id if short."""
+        return self.node_id_full
 
     def as_view(self) -> dict[str, Any]:
         return {
@@ -29,43 +31,101 @@ class PeerRecord:
             "display_name": self.display_name,
             "community_id": self.community_id,
             "profile": self.profile,
-            "capabilities": [cap["name"] for cap in (self.manifest or {}).get("capabilities", [])],
+            "last_seen": self.last_seen,
             "source": self.source,
-            "rtt_ms": self.rtt_ms,
         }
 
 
+@dataclass(frozen=True)
+class PeerEvent:
+    kind: str  # "added" | "removed" | "updated"
+    peer: PeerRecord
+
+
 class PeerRegistry:
-    def __init__(self, our_node_id_full: NodeID, community_id: CommunityID) -> None:
-        self.our_node_id_full = our_node_id_full
+    """In-memory map of NodeID → PeerRecord. Thread-safe via asyncio.Lock."""
+
+    def __init__(self, our_node_id: str, community_id: str) -> None:
+        self.our_node_id = our_node_id
+        # Keep legacy attribute name for backward compatibility
+        self.our_node_id_full = our_node_id
         self.community_id = community_id
         self._peers: dict[NodeID, PeerRecord] = {}
-        self.prune_stale_seconds = 90
+        self._lock = asyncio.Lock()
+        self._subscribers: list[asyncio.Queue] = []
+        self._pruning_aggressive = False
+        self._pruning_task: asyncio.Task | None = None
 
     def upsert(self, record: PeerRecord) -> bool:
-        if record.node_id_full == self.our_node_id_full or record.community_id != self.community_id:
-            return False
-        is_new = record.node_id_full not in self._peers
-        record.last_seen = time.monotonic()
+        """Add or update peer. Returns True if new peer was added."""
+        existing = self._peers.get(record.node_id_full)
         self._peers[record.node_id_full] = record
+        is_new = existing is None
+        event_kind = "added" if is_new else "updated"
+        self._notify(PeerEvent(kind=event_kind, peer=record))
         return is_new
 
-    def remove(self, node_id_full: NodeID) -> bool:
-        return self._peers.pop(node_id_full, None) is not None
+    def remove(self, node_id: str) -> None:
+        peer = self._peers.pop(node_id, None)
+        if peer:
+            self._notify(PeerEvent(kind="removed", peer=peer))
 
-    def get(self, node_id_full: NodeID) -> PeerRecord | None:
-        return self._peers.get(node_id_full)
+    def get(self, node_id: str) -> PeerRecord | None:
+        return self._peers.get(node_id)
 
     def all(self) -> list[PeerRecord]:
         return list(self._peers.values())
 
+    def count(self) -> int:
+        return len(self._peers)
+
+    def set_pruning_aggressive(self, aggressive: bool) -> None:
+        self._pruning_aggressive = aggressive
+
+    @property
+    def prune_stale_seconds(self) -> int:
+        from hearthnet.constants import PEER_PRUNE_AGGRESSIVE_SECONDS, PEER_PRUNE_NORMAL_SECONDS
+
+        return PEER_PRUNE_AGGRESSIVE_SECONDS if self._pruning_aggressive else PEER_PRUNE_NORMAL_SECONDS
+
     def prune_stale(self, max_age_seconds: int | None = None) -> int:
-        max_age = max_age_seconds if max_age_seconds is not None else self.prune_stale_seconds
-        cutoff = time.monotonic() - max_age
-        stale = [node_id for node_id, peer in self._peers.items() if peer.last_seen < cutoff]
-        for node_id in stale:
-            self._peers.pop(node_id, None)
+        """Remove peers whose last_seen is beyond the prune threshold."""
+        from hearthnet.constants import PEER_PRUNE_AGGRESSIVE_SECONDS, PEER_PRUNE_NORMAL_SECONDS
+        if max_age_seconds is not None:
+            threshold = max_age_seconds
+        else:
+            threshold = PEER_PRUNE_AGGRESSIVE_SECONDS if self._pruning_aggressive else PEER_PRUNE_NORMAL_SECONDS
+        now = time.monotonic()
+        stale = [nid for nid, peer in self._peers.items() if now - peer.last_seen > threshold]
+        for nid in stale:
+            self.remove(nid)
         return len(stale)
 
-    def set_pruning_aggressive(self, enabled: bool) -> None:
-        self.prune_stale_seconds = 30 if enabled else 90
+    async def start_pruner(self) -> None:
+        self._pruning_task = asyncio.create_task(self._pruner_loop(), name="peer-pruner")
+
+    async def _pruner_loop(self) -> None:
+        while True:
+            await asyncio.sleep(30)
+            self.prune_stale()
+
+    def subscribe(self) -> AsyncIterator[PeerEvent]:
+        q: asyncio.Queue = asyncio.Queue(maxsize=50)
+        self._subscribers.append(q)
+
+        async def gen() -> AsyncIterator[PeerEvent]:
+            try:
+                while True:
+                    event = await q.get()
+                    yield event
+            finally:
+                self._subscribers.remove(q)
+
+        return gen()
+
+    def _notify(self, event: PeerEvent) -> None:
+        for q in list(self._subscribers):
+            try:
+                q.put_nowait(event)
+            except asyncio.QueueFull:
+                pass

hearthnet/discovery/relay.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+class RelayDiscovery:
+    """Phase 2 stub: relay-based peer discovery."""
+
+    async def start(self) -> None:
+        raise NotImplementedError("Relay discovery is Phase 2")
+
+    async def stop(self) -> None:
+        pass

hearthnet/discovery/udp.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+
+from hearthnet.constants import (
+    UDP_ANNOUNCE_INTERVAL_OFFLINE_SECONDS,
+    UDP_ANNOUNCE_INTERVAL_ONLINE_SECONDS,
+    UDP_MULTICAST_GROUP,
+    UDP_MULTICAST_PORT,
+)
+from hearthnet.discovery.peers import PeerRecord, PeerRegistry
+from hearthnet.types import Endpoint
+
+
+class UdpAnnouncer:
+    """Periodic UDP multicast of node presence."""
+
+    def __init__(
+        self,
+        registry: PeerRegistry,
+        node_id: str,
+        community_id: str,
+        port: int = 7080,
+        caps: list[str] | None = None,
+    ) -> None:
+        self._registry = registry
+        self._node_id = node_id
+        self._community_id = community_id
+        self._port = port
+        self._caps = caps or []
+        self._running = False
+        self._task: asyncio.Task | None = None
+        self._offline = False
+
+    def set_offline(self, offline: bool) -> None:
+        self._offline = offline
+
+    async def start(self) -> None:
+        self._running = True
+        self._task = asyncio.create_task(self._announce_loop(), name="udp-announcer")
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _announce_loop(self) -> None:
+        while self._running:
+            await self._announce_once()
+            interval = (
+                UDP_ANNOUNCE_INTERVAL_OFFLINE_SECONDS
+                if self._offline
+                else UDP_ANNOUNCE_INTERVAL_ONLINE_SECONDS
+            )
+            await asyncio.sleep(interval)
+
+    async def _announce_once(self) -> None:
+        try:
+            import socket
+            short_id = self._node_id[8:20] if len(self._node_id) > 8 else self._node_id
+            payload = json.dumps({
+                "v": 1,
+                "node": short_id,
+                "community": self._community_id[:20],
+                "port": self._port,
+                "caps": self._caps[:10],
+            }).encode()
+            if len(payload) > 1024:
+                payload = payload[:1024]
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 2)
+            sock.sendto(payload, (UDP_MULTICAST_GROUP, UDP_MULTICAST_PORT))
+            sock.close()
+        except Exception:
+            pass  # UDP failure is non-fatal
+
+
+class UdpListener:
+    """Receives UDP multicast announcements, populates registry."""
+
+    def __init__(
+        self,
+        registry: PeerRegistry,
+        our_community_id: str,
+        port: int = UDP_MULTICAST_PORT,
+    ) -> None:
+        self._registry = registry
+        self._community_id = our_community_id
+        self._port = port
+        self._running = False
+        self._task: asyncio.Task | None = None
+
+    async def start(self) -> None:
+        self._running = True
+        self._task = asyncio.create_task(self._listen_loop(), name="udp-listener")
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _listen_loop(self) -> None:
+        import socket
+        import struct
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)  # type: ignore[attr-defined]
+            except (AttributeError, OSError):
+                pass
+            sock.bind(("", self._port))
+            mcast_req = struct.pack("4sL", socket.inet_aton(UDP_MULTICAST_GROUP), socket.INADDR_ANY)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mcast_req)
+            sock.setblocking(False)
+            loop = asyncio.get_event_loop()
+            while self._running:
+                try:
+                    data, addr = await loop.run_in_executor(None, sock.recvfrom, 2048)
+                    await self._handle_packet(data, addr[0])
+                except Exception:
+                    await asyncio.sleep(0.1)
+        except Exception:
+            pass
+
+    async def _handle_packet(self, data: bytes, source_ip: str) -> None:
+        try:
+            msg = json.loads(data.decode())
+            if msg.get("v") != 1:
+                return
+            community = msg.get("community", "")
+            if community and not self._community_id.startswith(community[:10]):
+                return
+            node_id = msg.get("node", "")
+            if not node_id:
+                return
+            port = int(msg.get("port", 7080))
+            record = PeerRecord(
+                node_id_full=node_id,
+                display_name=node_id[:12],
+                community_id=community,
+                profile="hearth",
+                endpoints=[Endpoint("https", source_ip, port)],
+                last_seen=time.monotonic(),
+                source="udp",
+            )
+            self._registry.upsert(record)
+        except Exception:
+            pass

hearthnet/emergency/detector.py

@@ -1,23 +1,164 @@
 from __future__ import annotations
 
-from hearthnet.bus import CapabilityBus
-from hearthnet.discovery import PeerRegistry
+import asyncio
+import socket
+from typing import Any
+
+from hearthnet.constants import (
+    EMERGENCY_PROBE_INTERVAL_OFFLINE_SECONDS,
+    EMERGENCY_PROBE_INTERVAL_ONLINE_SECONDS,
+    EMERGENCY_PROBE_TIMEOUT_SECONDS,
+)
 from hearthnet.emergency.state import EmergencyState, StateBus
 
 
 class Detector:
-    def __init__(self, bus: CapabilityBus, state_bus: StateBus, peers: PeerRegistry) -> None:
-        self.bus = bus
-        self.state_bus = state_bus
-        self.peers = peers
+    """Internet connectivity detector with async probe loop."""
+
+    def __init__(
+        self,
+        bus: Any = None,
+        state_bus: StateBus | None = None,
+        peers: Any = None,
+        probe_targets: list[str] | None = None,
+    ) -> None:
+        self._bus = bus
+        self._state_bus = state_bus or StateBus()
+        self._peers = peers
+        self._probe_targets = probe_targets or [
+            "1.1.1.1",
+            "8.8.8.8",
+            "https://cloudflare.com",
+            "https://quad9.net",
+        ]
+        self._running = False
+        self._task: asyncio.Task | None = None
+
+    @property
+    def state_bus(self) -> StateBus:
+        return self._state_bus
+
+    async def start(self) -> None:
+        """Start the background probe loop."""
+        self._running = True
+        self._task = asyncio.create_task(self._probe_loop(), name="emergency-detector")
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _probe_loop(self) -> None:
+        while self._running:
+            results = await self._probe_all()
+            previous = self._state_bus.current().mode
+            state = self._state_bus.emit_probe(results)
+
+            if previous != "offline" and state.mode == "offline":
+                await self._on_offline()
+            elif previous == "offline" and state.mode in ("online", "degraded"):
+                await self._on_restore()
+
+            interval = (
+                EMERGENCY_PROBE_INTERVAL_OFFLINE_SECONDS
+                if state.mode == "offline"
+                else EMERGENCY_PROBE_INTERVAL_ONLINE_SECONDS
+            )
+            await asyncio.sleep(interval)
+
+    async def _probe_all(self) -> dict[str, bool]:
+        tasks = {
+            target: asyncio.create_task(self._probe_one(target))
+            for target in self._probe_targets
+        }
+        results: dict[str, bool] = {}
+        for target, task in tasks.items():
+            try:
+                results[target] = await asyncio.wait_for(task, timeout=EMERGENCY_PROBE_TIMEOUT_SECONDS)
+            except (asyncio.TimeoutError, Exception):
+                results[target] = False
+        return results
+
+    async def _probe_one(self, target: str) -> bool:
+        """Probe a single target. DNS targets: resolve host. HTTP targets: HEAD request."""
+        try:
+            if target.startswith("http"):
+                return await self._probe_http(target)
+            return await self._probe_dns(target)
+        except Exception:
+            return False
+
+    async def _probe_http(self, url: str) -> bool:
+        try:
+            import httpx
+
+            async with httpx.AsyncClient(
+                timeout=EMERGENCY_PROBE_TIMEOUT_SECONDS  # verify=True (default) — certificate
+                # validation is intentional: we want to know if TLS infra is working too.
+            ) as client:
+                resp = await client.head(url)
+                return resp.status_code < 500
+        except ImportError:
+            import urllib.request
+
+            try:
+                urllib.request.urlopen(url, timeout=EMERGENCY_PROBE_TIMEOUT_SECONDS)
+                return True
+            except Exception:
+                return False
+        except Exception:
+            return False
+
+    async def _probe_dns(self, host: str) -> bool:
+        try:
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, socket.getaddrinfo, host, 53)
+            return True
+        except Exception:
+            return False
+
+    async def _on_offline(self) -> None:
+        """Deregister internet-dependent capabilities, increase peer pruning aggressiveness."""
+        if self._bus is not None:
+            try:
+                self._bus.deregister_internet_capabilities()
+            except Exception:
+                pass
+        if self._peers is not None:
+            try:
+                self._peers.set_pruning_aggressive(True)
+            except Exception:
+                pass
+
+    async def _on_restore(self) -> None:
+        """Restore internet-dependent capabilities."""
+        if self._bus is not None:
+            try:
+                self._bus.restore_internet_capabilities()
+            except Exception:
+                pass
+        if self._peers is not None:
+            try:
+                self._peers.set_pruning_aggressive(False)
+            except Exception:
+                pass
 
     def apply_probe_results(self, probe_results: dict[str, bool]) -> EmergencyState:
-        previous = self.state_bus.current().mode
-        state = self.state_bus.emit_probe(probe_results)
+        """Synchronous interface for manual/test use."""
+        previous = self._state_bus.current().mode
+        state = self._state_bus.emit_probe(probe_results)
         if previous != "offline" and state.mode == "offline":
-            self.bus.deregister_internet_capabilities()
-            self.peers.set_pruning_aggressive(True)
-        elif previous == "offline" and state.mode == "online":
-            self.bus.restore_internet_capabilities()
-            self.peers.set_pruning_aggressive(False)
+            if self._bus is not None:
+                self._bus.deregister_internet_capabilities()
+            if self._peers is not None:
+                self._peers.set_pruning_aggressive(True)
+        elif previous == "offline" and state.mode in ("online", "degraded"):
+            if self._bus is not None:
+                self._bus.restore_internet_capabilities()
+            if self._peers is not None:
+                self._peers.set_pruning_aggressive(False)
         return state

hearthnet/emergency/state.py

@@ -1,43 +1,101 @@
 from __future__ import annotations
 
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from typing import Literal
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import AsyncIterator, Literal
 
 Mode = Literal["online", "degraded", "offline"]
 
 
-def utc_now() -> str:
-    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
-
-
 @dataclass(frozen=True)
 class EmergencyState:
     mode: Mode
-    since: str
-    last_probe: str
-    probe_results: dict[str, bool] = field(default_factory=dict)
+    changed_at: float  # monotonic timestamp
+    probe_results: dict[str, bool]  # target -> success
+    consecutive_fails: int = 0
+
+    @property
+    def mode_label(self) -> str:
+        return {
+            "online": "ONLINE",
+            "degraded": "DEGRADED — LIMITED",
+            "offline": "INTERNET OFFLINE — LOKAL AKTIV",
+        }[self.mode]
 
 
 class StateBus:
+    """In-process pub/sub for emergency state changes."""
+
     def __init__(self) -> None:
-        now = utc_now()
-        self._state = EmergencyState(mode="online", since=now, last_probe=now, probe_results={})
+        self._state = EmergencyState(mode="online", changed_at=time.monotonic(), probe_results={})
+        self._subscribers: list[asyncio.Queue] = []
+        self._transition_times: list[float] = []  # for anti-flap
 
     def current(self) -> EmergencyState:
         return self._state
 
+    async def subscribe(self) -> AsyncIterator[EmergencyState]:
+        q: asyncio.Queue = asyncio.Queue(maxsize=10)
+        self._subscribers.append(q)
+        try:
+            while True:
+                state = await q.get()
+                yield state
+        finally:
+            self._subscribers.remove(q)
+
     def emit_probe(self, probe_results: dict[str, bool]) -> EmergencyState:
-        failed = sum(1 for ok in probe_results.values() if not ok)
-        if failed == 0:
-            mode: Mode = "online"
-        elif failed >= 2:
-            mode = "offline"
+        """Compute new mode from probe results, apply anti-flap, emit if changed."""
+        successes = sum(1 for v in probe_results.values() if v)
+        total = len(probe_results)
+        fails = total - successes
+
+        if total == 0:
+            new_mode: Mode = "online"
+        elif fails >= max(2, total // 2):
+            new_mode = "offline"
+        elif fails > 0:
+            new_mode = "degraded"
         else:
-            mode = "degraded"
-        now = utc_now()
-        since = now if mode != self._state.mode else self._state.since
-        self._state = EmergencyState(
-            mode=mode, since=since, last_probe=now, probe_results=dict(probe_results)
+            new_mode = "online"
+
+        old_mode = self._state.mode
+
+        # Anti-flap: if too many transitions in last 60s, stay pessimistic
+        from hearthnet.constants import (
+            EMERGENCY_ANTI_FLAP_MAX_TRANSITIONS,
+            EMERGENCY_ANTI_FLAP_WINDOW_SECONDS,
         )
-        return self._state
+
+        now = time.monotonic()
+        self._transition_times = [
+            t for t in self._transition_times if now - t < EMERGENCY_ANTI_FLAP_WINDOW_SECONDS
+        ]
+        if len(self._transition_times) >= EMERGENCY_ANTI_FLAP_MAX_TRANSITIONS:
+            # Too many flaps — hold pessimistic
+            if old_mode in ("degraded", "offline") and new_mode == "online":
+                new_mode = old_mode  # don't restore yet
+
+        new_state = EmergencyState(
+            mode=new_mode,
+            changed_at=now if new_mode != old_mode else self._state.changed_at,
+            probe_results=probe_results,
+            consecutive_fails=self._state.consecutive_fails + (1 if fails > 0 else 0),
+        )
+
+        if new_mode != old_mode:
+            self._transition_times.append(now)
+            self._state = new_state
+            self._emit(new_state)
+        else:
+            self._state = new_state
+
+        return new_state
+
+    def _emit(self, state: EmergencyState) -> None:
+        for q in list(self._subscribers):
+            try:
+                q.put_nowait(state)
+            except asyncio.QueueFull:
+                pass

hearthnet/events/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from .lamport import LamportClock
+from .log import EventLog, EventLogError
+from .replay import MaterialisedView, ReplayEngine
+from .snapshot import Snapshot, SnapshotStore, build_snapshot, restore_from_snapshot
+from .sync import HeadsReport, SyncClient, SyncResult, SyncServer
+from .types import Event, EventType, new_ulid
+
+__all__ = [
+    "Event",
+    "EventType",
+    "EventLog",
+    "EventLogError",
+    "LamportClock",
+    "ReplayEngine",
+    "MaterialisedView",
+    "SnapshotStore",
+    "Snapshot",
+    "build_snapshot",
+    "restore_from_snapshot",
+    "SyncClient",
+    "SyncServer",
+    "HeadsReport",
+    "SyncResult",
+    "new_ulid",
+]

hearthnet/events/lamport.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import sqlite3
+import threading
+from pathlib import Path
+
+
+class LamportClock:
+    """Thread-safe, SQLite-persisted Lamport clock for one community.
+
+    The clock row lives in the same ``clock`` table as the event log DB so
+    that both the event insert and the clock bump happen in the same
+    transaction.
+    """
+
+    def __init__(self, community_id: str, db_path: Path) -> None:
+        self._community_id = community_id
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        self._value: int = 0
+        self._conn: sqlite3.Connection | None = None
+        self._load()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def tick(self) -> int:
+        """Increment and return the new Lamport value (for local events)."""
+        with self._lock:
+            self._value += 1
+            self._save()
+            return self._value
+
+    def update(self, received: int) -> int:
+        """Advance to max(local, received) + 1 (for received events)."""
+        with self._lock:
+            self._value = max(self._value, received) + 1
+            self._save()
+            return self._value
+
+    def current(self) -> int:
+        with self._lock:
+            return self._value
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+        return self._conn
+
+    def _load(self) -> None:
+        conn = self._get_conn()
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS clock "
+            "(community_id TEXT PRIMARY KEY, lamport INTEGER NOT NULL)"
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT lamport FROM clock WHERE community_id = ?",
+            (self._community_id,),
+        ).fetchone()
+        self._value = row[0] if row else 0
+
+    def _save(self) -> None:
+        """Persist current value.  Called while ``_lock`` is held."""
+        conn = self._get_conn()
+        conn.execute(
+            "INSERT INTO clock (community_id, lamport) VALUES (?, ?) "
+            "ON CONFLICT(community_id) DO UPDATE SET lamport = excluded.lamport",
+            (self._community_id, self._value),
+        )
+        conn.commit()
+
+    def _save_in_tx(self, conn: sqlite3.Connection) -> None:
+        """Persist inside an already-open transaction (no commit here)."""
+        conn.execute(
+            "INSERT INTO clock (community_id, lamport) VALUES (?, ?) "
+            "ON CONFLICT(community_id) DO UPDATE SET lamport = excluded.lamport",
+            (self._community_id, self._value),
+        )

hearthnet/events/log.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import threading
+from collections.abc import AsyncIterator
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .lamport import LamportClock
+from .types import _ALL_EVENT_TYPES, Event, EventType, new_ulid
+
+_SCHEMA = """
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+
+CREATE TABLE IF NOT EXISTS events (
+  event_id        TEXT PRIMARY KEY,
+  event_type      TEXT NOT NULL,
+  community_id    TEXT NOT NULL,
+  author          TEXT NOT NULL,
+  lamport         INTEGER NOT NULL,
+  payload         TEXT NOT NULL,
+  issued_at       TEXT NOT NULL,
+  signature       TEXT NOT NULL,
+  schema_version  INTEGER NOT NULL DEFAULT 1,
+  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
+);
+"""
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
+
+
+def _row_to_event(row: tuple[Any, ...]) -> Event:
+    (
+        event_id,
+        event_type,
+        community_id,
+        author,
+        lamport,
+        payload,
+        issued_at,
+        signature,
+        schema_version,
+        _received_at,
+    ) = row
+    return Event(
+        schema_version=schema_version,
+        event_id=event_id,
+        event_type=event_type,  # type: ignore[arg-type]
+        community_id=community_id,
+        author=author,
+        lamport=lamport,
+        payload=json.loads(payload),
+        issued_at=issued_at,
+        signature=signature,
+    )
+
+
+def _sign(event: Event, kp: Any) -> str:
+    """Return signature string or '' when kp is None."""
+    if kp is None:
+        return ""
+    import base64
+    import hashlib
+
+    raw = _canonical_bytes(event)
+    if hasattr(kp, "sign"):
+        sig_bytes: bytes = kp.sign(raw)
+    else:
+        # Fallback: HMAC-SHA256 keyed by kp as bytes (test usage)
+        import hmac
+
+        sig_bytes = hmac.new(kp, raw, hashlib.sha256).digest()
+    encoded = base64.urlsafe_b64encode(sig_bytes).rstrip(b"=").decode()
+    return f"ed25519:{encoded}"
+
+
+def _canonical_bytes(event: Event) -> bytes:
+    """Deterministic serialisation for signing / verification."""
+    obj = {
+        "schema_version": event.schema_version,
+        "event_id": event.event_id,
+        "event_type": event.event_type,
+        "community_id": event.community_id,
+        "author": event.author,
+        "lamport": event.lamport,
+        "payload": event.payload,
+        "issued_at": event.issued_at,
+    }
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+def _verify(event: Event, kp_store: Any) -> bool:
+    """Return True if the signature is valid or if there is no kp_store."""
+    if kp_store is None:
+        return True
+    if not event.signature:
+        return True
+    if hasattr(kp_store, "verify"):
+        try:
+            import base64
+
+            prefix = "ed25519:"
+            b64 = event.signature[len(prefix) :] if event.signature.startswith(prefix) else event.signature
+            # pad
+            padding = 4 - len(b64) % 4
+            if padding != 4:
+                b64 += "=" * padding
+            sig_bytes = base64.urlsafe_b64decode(b64)
+            raw = _canonical_bytes(event)
+            return kp_store.verify(event.author, raw, sig_bytes)
+        except Exception:
+            return False
+    return True
+
+
+class EventLogError(Exception):
+    """Raised for protocol violations in the event log."""
+
+    def __init__(self, code: str, message: str = "") -> None:
+        super().__init__(message or code)
+        self.code = code
+
+
+class EventLog:
+    """SQLite-backed append-only event log for one community."""
+
+    def __init__(
+        self,
+        db_path: Path,
+        community_id: str,
+        kp_store: Any = None,
+    ) -> None:
+        self._db_path = db_path
+        self._community_id = community_id
+        self._kp_store = kp_store
+        self._lock = threading.Lock()
+        self._subscribers: list[tuple[asyncio.Queue[Event], frozenset[str] | None]] = []
+
+        self._conn = sqlite3.connect(str(db_path), check_same_thread=False)
+        self._init_schema()
+        self._clock = LamportClock(community_id, db_path)
+        self._clock._conn = self._conn  # share connection
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    def _init_schema(self) -> None:
+        for stmt in _SCHEMA.strip().split(";"):
+            stmt = stmt.strip()
+            if stmt:
+                self._conn.execute(stmt)
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # Writing
+    # ------------------------------------------------------------------
+
+    def append_local(
+        self,
+        event_type: EventType,
+        author: str,
+        payload: dict[str, Any],
+        kp: Any = None,
+    ) -> Event:
+        """Mint, sign, and persist a new local event atomically."""
+        if event_type not in _ALL_EVENT_TYPES:
+            raise EventLogError("schema_unknown", f"Unknown event_type: {event_type!r}")
+
+        with self._lock:
+            lamport = self._clock._value + 1
+            event_id = new_ulid()
+            now = _now_utc()
+
+            # Build unsigned event first to produce canonical bytes
+            event = Event(
+                schema_version=1,
+                event_id=event_id,
+                event_type=event_type,
+                community_id=self._community_id,
+                author=author,
+                lamport=lamport,
+                payload=payload,
+                issued_at=now,
+                signature="",
+            )
+            sig = _sign(event, kp)
+            # Replace with signed version
+            import dataclasses
+
+            event = dataclasses.replace(event, signature=sig)
+
+            self._clock._value = lamport
+            self._conn.execute("BEGIN")
+            try:
+                self._conn.execute(
+                    "INSERT INTO events "
+                    "(event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at) "
+                    "VALUES (?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        event.event_id,
+                        event.event_type,
+                        event.community_id,
+                        event.author,
+                        event.lamport,
+                        json.dumps(event.payload, sort_keys=True),
+                        event.issued_at,
+                        event.signature,
+                        event.schema_version,
+                        now,
+                    ),
+                )
+                self._clock._save_in_tx(self._conn)
+                self._conn.execute("COMMIT")
+            except Exception:
+                self._conn.execute("ROLLBACK")
+                raise
+
+        self._fanout(event)
+        return event
+
+    def append_received(self, event: Event) -> bool:
+        """Persist a peer event.  Returns False for duplicates, True if new."""
+        if event.event_type not in _ALL_EVENT_TYPES:
+            raise EventLogError("schema_unknown", f"Unknown event_type: {event.event_type!r}")
+
+        if not _verify(event, self._kp_store):
+            raise EventLogError("invalid_signature", f"Bad signature on {event.event_id}")
+
+        with self._lock:
+            # Duplicate check
+            dup = self._conn.execute(
+                "SELECT 1 FROM events WHERE event_id = ?", (event.event_id,)
+            ).fetchone()
+            if dup:
+                return False
+
+            new_lamport = max(self._clock._value, event.lamport) + 1
+            now = _now_utc()
+
+            self._conn.execute("BEGIN")
+            try:
+                self._conn.execute(
+                    "INSERT INTO events "
+                    "(event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at) "
+                    "VALUES (?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        event.event_id,
+                        event.event_type,
+                        event.community_id,
+                        event.author,
+                        event.lamport,
+                        json.dumps(event.payload, sort_keys=True),
+                        event.issued_at,
+                        event.signature,
+                        event.schema_version,
+                        now,
+                    ),
+                )
+                self._clock._value = new_lamport
+                self._clock._save_in_tx(self._conn)
+                self._conn.execute("COMMIT")
+            except Exception:
+                self._conn.execute("ROLLBACK")
+                raise
+
+        self._fanout(event)
+        return True
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def get(self, event_id: str) -> Event | None:
+        row = self._conn.execute(
+            "SELECT event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at "
+            "FROM events WHERE event_id = ?",
+            (event_id,),
+        ).fetchone()
+        return _row_to_event(row) if row else None
+
+    def since(self, lamport: int, limit: int = 1000) -> list[Event]:
+        """Return events with lamport >= given value, ordered by (lamport, event_id)."""
+        rows = self._conn.execute(
+            "SELECT event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at "
+            "FROM events WHERE community_id = ? AND lamport >= ? "
+            "ORDER BY lamport ASC, event_id ASC LIMIT ?",
+            (self._community_id, lamport, limit),
+        ).fetchall()
+        return [_row_to_event(r) for r in rows]
+
+    def head(self) -> int:
+        """Highest Lamport value stored."""
+        row = self._conn.execute(
+            "SELECT MAX(lamport) FROM events WHERE community_id = ?",
+            (self._community_id,),
+        ).fetchone()
+        return row[0] if row and row[0] is not None else 0
+
+    def by_type(self, event_type: EventType, since_lamport: int = 0) -> list[Event]:
+        rows = self._conn.execute(
+            "SELECT event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at "
+            "FROM events WHERE community_id = ? AND event_type = ? AND lamport >= ? "
+            "ORDER BY lamport ASC, event_id ASC",
+            (self._community_id, event_type, since_lamport),
+        ).fetchall()
+        return [_row_to_event(r) for r in rows]
+
+    def heads_by_type(self) -> dict[str, int]:
+        """Highest lamport per event_type; used by sync."""
+        rows = self._conn.execute(
+            "SELECT event_type, MAX(lamport) FROM events WHERE community_id = ? GROUP BY event_type",
+            (self._community_id,),
+        ).fetchall()
+        return {row[0]: row[1] for row in rows}
+
+    def replay(
+        self,
+        *,
+        since_lamport: int = 0,
+        event_types: list[EventType] | None = None,
+        limit: int | None = None,
+    ) -> list[Event]:
+        """Return events in (lamport, event_id) order, optionally filtered."""
+        if event_types:
+            placeholders = ",".join("?" for _ in event_types)
+            sql = (
+                # nosec B608 — placeholders is computed from len(event_types), not user input
+                f"SELECT event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at "
+                f"FROM events WHERE community_id = ? AND lamport >= ? AND event_type IN ({placeholders}) "
+                f"ORDER BY lamport ASC, event_id ASC"
+            )
+            params: list[Any] = [self._community_id, since_lamport, *event_types]
+        else:
+            sql = (
+                "SELECT event_id,event_type,community_id,author,lamport,payload,issued_at,signature,schema_version,received_at "
+                "FROM events WHERE community_id = ? AND lamport >= ? "
+                "ORDER BY lamport ASC, event_id ASC"
+            )
+            params = [self._community_id, since_lamport]
+
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+
+        rows = self._conn.execute(sql, params).fetchall()
+        return [_row_to_event(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Pubsub
+    # ------------------------------------------------------------------
+
+    def subscribe(
+        self,
+        event_types: list[EventType] | None = None,
+    ) -> AsyncIterator[Event]:
+        """Return an async iterator that yields matching events as they arrive."""
+        q: asyncio.Queue[Event] = asyncio.Queue()
+        ft: frozenset[str] | None = frozenset(event_types) if event_types else None
+        self._subscribers.append((q, ft))
+
+        async def _iter() -> AsyncIterator[Event]:
+            try:
+                while True:
+                    event = await q.get()
+                    yield event
+            except GeneratorExit:
+                pass
+            finally:
+                try:
+                    self._subscribers.remove((q, ft))
+                except ValueError:
+                    pass
+
+        return _iter()  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying SQLite connection."""
+        try:
+            self._conn.close()
+        except Exception:
+            pass
+
+    def _fanout(self, event: Event) -> None:
+        """Push event to all in-process subscribers (best-effort)."""
+        for q, filter_types in list(self._subscribers):
+            if filter_types is None or event.event_type in filter_types:
+                try:
+                    q.put_nowait(event)
+                except asyncio.QueueFull:
+                    pass

hearthnet/events/replay.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from .types import Event, EventType
+
+if TYPE_CHECKING:
+    from .log import EventLog
+
+
+class MaterialisedView(Protocol):
+    """Protocol that all consuming-module views must satisfy."""
+
+    def reset(self) -> None:
+        """Clear all state (called before a full replay)."""
+        ...
+
+    def apply(self, event: Event) -> None:
+        """Incorporate a single event into the view's state."""
+        ...
+
+    def snapshot_state(self) -> dict:
+        """Return a JSON-serialisable representation of current state."""
+        ...
+
+    def restore_state(self, state: dict) -> None:
+        """Reinstate state produced by snapshot_state()."""
+        ...
+
+
+class ReplayEngine:
+    """Routes events to registered materialised views."""
+
+    def __init__(self, log: EventLog) -> None:
+        self.log = log
+        # view_name -> (view, set of event_types it cares about or None for all)
+        self._views: dict[str, tuple[MaterialisedView, frozenset[str] | None]] = {}
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        view: MaterialisedView,
+        event_types: list[EventType] | None = None,
+    ) -> None:
+        """Register *view* under *name*. Pass ``event_types=None`` for all types."""
+        ft: frozenset[str] | None = frozenset(event_types) if event_types else None
+        self._views[name] = (view, ft)
+
+    # Alias used in task spec
+    def register_view(
+        self,
+        view: MaterialisedView,
+        event_types: list[EventType],
+    ) -> None:
+        name = type(view).__name__
+        self.register(name, view, event_types)
+
+    # ------------------------------------------------------------------
+    # Replay
+    # ------------------------------------------------------------------
+
+    def rebuild(self, view_name: str, from_lamport: int = 0) -> None:
+        """Reset the named view and replay all relevant events from *from_lamport*."""
+        view, ft = self._views[view_name]
+        view.reset()
+        event_types = list(ft) if ft is not None else None
+        for event in self.log.replay(since_lamport=from_lamport, event_types=event_types):  # type: ignore[arg-type]
+            view.apply(event)
+
+    def rebuild_all(self, from_lamport: int = 0) -> None:
+        """Reset and replay all registered views."""
+        for name in list(self._views):
+            self.rebuild(name, from_lamport)
+
+    # Alias used in task spec
+    def replay_all(self) -> None:
+        self.rebuild_all(from_lamport=0)
+
+    def replay_since(self, lamport: int) -> None:
+        """Replay (without reset) all views for events at lamport >= *lamport*."""
+        # Collect all event types across views
+        for _name, (view, ft) in self._views.items():
+            event_types = list(ft) if ft is not None else None
+            for event in self.log.replay(since_lamport=lamport, event_types=event_types):  # type: ignore[arg-type]
+                view.apply(event)
+
+    # ------------------------------------------------------------------
+    # Live fanout
+    # ------------------------------------------------------------------
+
+    def _on_event(self, event: Event) -> None:
+        """Route a newly-arrived event to all subscribed views."""
+        for _name, (view, ft) in self._views.items():
+            if ft is None or event.event_type in ft:
+                view.apply(event)
+
+    # Alias used in spec
+    on_event = _on_event

hearthnet/events/snapshot.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .log import EventLog
+    from .replay import ReplayEngine
+
+_SNAPSHOT_LAG_LAMPORT = 1000
+_SCHEMA_VERSION = 1
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
+
+
+def _sign_snapshot(data: bytes, kp: Any) -> str:
+    if kp is None:
+        return ""
+    if hasattr(kp, "sign"):
+        sig_bytes: bytes = kp.sign(data)
+    else:
+        import hashlib
+        import hmac
+
+        sig_bytes = hmac.new(kp, data, hashlib.sha256).digest()
+    return "ed25519:" + base64.urlsafe_b64encode(sig_bytes).rstrip(b"=").decode()
+
+
+def _verify_snapshot(snap: "Snapshot", kp_store: Any) -> bool:
+    if kp_store is None or not snap.signature:
+        return True
+    raw = _canonical_snap_bytes(snap)
+    if hasattr(kp_store, "verify"):
+        try:
+            prefix = "ed25519:"
+            b64 = snap.signature[len(prefix) :] if snap.signature.startswith(prefix) else snap.signature
+            padding = 4 - len(b64) % 4
+            if padding != 4:
+                b64 += "=" * padding
+            sig_bytes = base64.urlsafe_b64decode(b64)
+            return kp_store.verify(snap.author, raw, sig_bytes)
+        except Exception:
+            return False
+    return True
+
+
+def _canonical_snap_bytes(snap: "Snapshot") -> bytes:
+    obj = {
+        "schema_version": snap.schema_version,
+        "community_id": snap.community_id,
+        "at_lamport": snap.at_lamport,
+        "views": snap.views,
+        "issued_at": snap.issued_at,
+        "author": snap.author,
+    }
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    schema_version: int
+    community_id: str
+    at_lamport: int
+    views: dict[str, dict]   # view_name -> state dict
+    issued_at: str
+    author: str
+    signature: str
+
+
+class SnapshotStore:
+    """Stores snapshots as JSON files under *dir_path*/<community_id>/snapshots/."""
+
+    def __init__(self, dir_path: Path, community_id: str) -> None:
+        self._dir = dir_path / community_id / "snapshots"
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def _path_for(self, at_lamport: int) -> Path:
+        return self._dir / f"{at_lamport:020d}.json"
+
+    def write(self, snap: Snapshot) -> None:
+        """Write snapshot atomically."""
+        target = self._path_for(snap.at_lamport)
+        tmp = target.with_suffix(".tmp")
+        payload = {
+            "schema_version": snap.schema_version,
+            "community_id": snap.community_id,
+            "at_lamport": snap.at_lamport,
+            "views": snap.views,
+            "issued_at": snap.issued_at,
+            "author": snap.author,
+            "signature": snap.signature,
+        }
+        tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        os.replace(tmp, target)
+
+    def latest(self) -> Snapshot | None:
+        lamps = self.list()
+        if not lamps:
+            return None
+        return self._load(lamps[-1])
+
+    def list(self) -> list[int]:
+        """Return lamport values of all snapshots on disk, ascending."""
+        values = []
+        for p in sorted(self._dir.glob("*.json")):
+            try:
+                values.append(int(p.stem))
+            except ValueError:
+                pass
+        return values
+
+    def prune(self, keep_last_n: int = 7) -> None:
+        lamps = self.list()
+        to_delete = lamps[:-keep_last_n] if len(lamps) > keep_last_n else []
+        for lamp in to_delete:
+            self._path_for(lamp).unlink(missing_ok=True)
+
+    def _load(self, at_lamport: int) -> Snapshot:
+        data = json.loads(self._path_for(at_lamport).read_text(encoding="utf-8"))
+        return Snapshot(
+            schema_version=data["schema_version"],
+            community_id=data["community_id"],
+            at_lamport=data["at_lamport"],
+            views=data["views"],
+            issued_at=data["issued_at"],
+            author=data["author"],
+            signature=data["signature"],
+        )
+
+
+def build_snapshot(
+    log: EventLog,
+    engine: ReplayEngine,
+    author: str,
+    kp: Any = None,
+    at_lamport: int | None = None,
+) -> Snapshot:
+    """Build a signed snapshot of all view states up to *at_lamport*.
+
+    If *at_lamport* is None, uses ``head - SNAPSHOT_LAG_LAMPORT``.
+    """
+    head = log.head()
+    if at_lamport is None:
+        at_lamport = max(0, head - _SNAPSHOT_LAG_LAMPORT)
+
+    # Rebuild all views up to at_lamport
+    for name, (view, ft) in engine._views.items():
+        view.reset()
+        event_types = list(ft) if ft is not None else None
+        for event in log.replay(since_lamport=0, event_types=event_types):  # type: ignore[arg-type]
+            if event.lamport > at_lamport:
+                break
+            view.apply(event)
+
+    views_state: dict[str, dict] = {}
+    for name, (view, _ft) in engine._views.items():
+        views_state[name] = view.snapshot_state()
+
+    now = _now_utc()
+    snap_unsigned = Snapshot(
+        schema_version=_SCHEMA_VERSION,
+        community_id=log._community_id,
+        at_lamport=at_lamport,
+        views=views_state,
+        issued_at=now,
+        author=author,
+        signature="",
+    )
+    sig = _sign_snapshot(_canonical_snap_bytes(snap_unsigned), kp)
+    import dataclasses
+
+    return dataclasses.replace(snap_unsigned, signature=sig)
+
+
+def restore_from_snapshot(
+    snap: Snapshot,
+    engine: ReplayEngine,
+    log: EventLog,
+    kp_store: Any = None,
+) -> None:
+    """Restore view states from *snap*, then replay any newer events."""
+    if not _verify_snapshot(snap, kp_store):
+        raise ValueError("Snapshot signature verification failed")
+
+    for name, state in snap.views.items():
+        if name in engine._views:
+            engine._views[name][0].restore_state(state)
+
+    # Replay events that arrived after the snapshot
+    for event in log.replay(since_lamport=snap.at_lamport + 1):
+        engine._on_event(event)

hearthnet/events/sync.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .types import Event
+
+if TYPE_CHECKING:
+    from .log import EventLog
+
+
+@dataclass(frozen=True)
+class HeadsReport:
+    community_id: str
+    node_id: str
+    head: int
+    heads_by_type: dict[str, int]
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    sent_count: int
+    received_count: int
+    duration_ms: int
+
+
+def _event_to_dict(event: Event) -> dict[str, Any]:
+    return {
+        "schema_version": event.schema_version,
+        "event_id": event.event_id,
+        "event_type": event.event_type,
+        "community_id": event.community_id,
+        "author": event.author,
+        "lamport": event.lamport,
+        "payload": event.payload,
+        "issued_at": event.issued_at,
+        "signature": event.signature,
+    }
+
+
+def _dict_to_event(d: dict[str, Any]) -> Event:
+    return Event(
+        schema_version=d.get("schema_version", 1),
+        event_id=d["event_id"],
+        event_type=d["event_type"],  # type: ignore[arg-type]
+        community_id=d["community_id"],
+        author=d["author"],
+        lamport=d["lamport"],
+        payload=d.get("payload", {}),
+        issued_at=d["issued_at"],
+        signature=d.get("signature", ""),
+    )
+
+
+class SyncClient:
+    """Pull/push gossip sync against a single peer."""
+
+    def __init__(self, log: EventLog, http_client: Any = None) -> None:
+        self._log = log
+        self._http = http_client
+
+    async def sync_with(self, peer_url: str, community_id: str) -> SyncResult:
+        """Gossip sync with peer:
+        1. GET /sync/v1/heads   → peer HeadsReport
+        2. POST /sync/v1/events → push events peer is missing
+        3. Receive events we are missing and apply them.
+        """
+        start = int(time.time() * 1000)
+
+        if self._http is None:
+            # No transport available; return a no-op result
+            return SyncResult(sent_count=0, received_count=0, duration_ms=0)
+
+        # Step 1: fetch peer heads
+        resp = await self._http.get(f"{peer_url.rstrip('/')}/sync/v1/heads")
+        peer_heads: dict[str, Any] = resp if isinstance(resp, dict) else await resp.json()
+        peer_head: int = peer_heads.get("head", 0)
+
+        # Step 2: send events peer doesn't have
+        local_head = self._log.head()
+        our_missing: list[dict[str, Any]] = []
+        if local_head > peer_head:
+            events_to_send = self._log.since(peer_head + 1)
+            our_missing = [_event_to_dict(e) for e in events_to_send]
+
+        # Step 3: POST our missing and receive theirs
+        body = json.dumps(
+            {
+                "community_id": community_id,
+                "events": our_missing,
+                "our_head": local_head,
+            }
+        )
+        resp2 = await self._http.post(
+            f"{peer_url.rstrip('/')}/sync/v1/events",
+            data=body,
+            headers={"Content-Type": "application/json"},
+        )
+        result_data: dict[str, Any] = resp2 if isinstance(resp2, dict) else await resp2.json()
+
+        # Apply events the peer sent back
+        received_events: list[dict[str, Any]] = result_data.get("events", [])
+        received_count = 0
+        for ed in received_events:
+            try:
+                event = _dict_to_event(ed)
+                if self._log.append_received(event):
+                    received_count += 1
+            except Exception:
+                pass
+
+        duration_ms = int(time.time() * 1000) - start
+        return SyncResult(
+            sent_count=len(our_missing),
+            received_count=received_count,
+            duration_ms=duration_ms,
+        )
+
+
+class SyncServer:
+    """Exposes /sync/v1/heads and /sync/v1/events handler logic."""
+
+    def __init__(self, log: EventLog) -> None:
+        self._log = log
+
+    def heads(self) -> HeadsReport:
+        return HeadsReport(
+            community_id=self._log._community_id,
+            node_id="",  # caller should inject node_id if needed
+            head=self._log.head(),
+            heads_by_type=self._log.heads_by_type(),
+        )
+
+    async def serve_heads(self) -> dict[str, Any]:
+        report = self.heads()
+        return {
+            "community_id": report.community_id,
+            "head": report.head,
+            "heads_by_type": report.heads_by_type,
+        }
+
+    async def serve_events(self, body: dict[str, Any]) -> dict[str, Any]:
+        """Accept events from a peer and return events the peer is missing.
+
+        Expected body keys: ``community_id``, ``events``, ``our_head`` (peer's head).
+        """
+        incoming: list[dict[str, Any]] = body.get("events", [])
+        peer_head: int = body.get("our_head", 0)
+
+        accepted = 0
+        rejected = 0
+        rejected_reasons: list[dict[str, str]] = []
+
+        for ed in incoming:
+            try:
+                event = _dict_to_event(ed)
+                if self._log.append_received(event):
+                    accepted += 1
+            except Exception as exc:
+                rejected += 1
+                rejected_reasons.append(
+                    {
+                        "event_id": ed.get("event_id", ""),
+                        "reason": str(exc),
+                    }
+                )
+
+        # Events the requesting peer is missing
+        missing_for_peer = [
+            _event_to_dict(e) for e in self._log.since(peer_head + 1)
+        ]
+
+        return {
+            "accepted": accepted,
+            "rejected": rejected,
+            "rejected_reasons": rejected_reasons,
+            "new_head": self._log.head(),
+            "events": missing_for_peer,
+        }

hearthnet/events/types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import base64
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any, Literal
+
+EventType = Literal[
+    "community.created",
+    "community.member.joined",
+    "community.member.left",
+    "community.member.invited",
+    "community.member.removed",
+    "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",
+    "rag.document.ingested",
+    "file.advertised",
+    "file.cid.advertised",
+    "file.cid.unpinned",
+    "federation.peer.added",
+    "federation.peer.removed",
+]
+
+_ALL_EVENT_TYPES: frozenset[str] = frozenset(EventType.__args__)  # type: ignore[attr-defined]
+
+
+def new_ulid() -> str:
+    """Generate a sortable unique ID (ULID-compatible 26-char string)."""
+    ts = int(time.time() * 1000)
+    ts_bytes = ts.to_bytes(10, "big")
+    rand_bytes = secrets.token_bytes(10)
+    raw = ts_bytes + rand_bytes  # 20 bytes
+    encoded = base64.b32encode(raw).decode("ascii")  # 32 chars
+    return encoded[:26]
+
+
+@dataclass(frozen=True)
+class Event:
+    schema_version: int       # always 1
+    event_id: str             # ULID
+    event_type: EventType
+    community_id: str
+    author: str               # full node_id
+    lamport: int
+    payload: dict[str, Any]
+    issued_at: str            # RFC 3339 UTC
+    signature: str            # "ed25519:<b64url>" or ""

hearthnet/identity/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+"""hearthnet.identity — M01 Identity module.
+
+Provides Ed25519 key management, canonical JSON, signing/verification,
+and node/community manifests.
+"""
+
+from hearthnet.identity.keys import (
+    IdentityError,
+    KeyPair,
+    canonical_json,
+    full_node_id,
+    generate,
+    load,
+    load_or_generate,
+    parse_node_id,
+    save,
+    short_node_id,
+    sign_payload,
+    verify_payload,
+    verify_payload_with_node_id,
+)
+from hearthnet.identity.manifest import (
+    CommunityManifest,
+    ManifestError,
+    NodeManifest,
+    build_community_manifest,
+    build_node_manifest,
+    verify_community_manifest,
+    verify_node_manifest,
+)
+
+__all__ = [
+    # keys
+    "KeyPair",
+    "IdentityError",
+    "generate",
+    "load",
+    "load_or_generate",
+    "save",
+    "canonical_json",
+    "sign_payload",
+    "verify_payload",
+    "verify_payload_with_node_id",
+    "short_node_id",
+    "full_node_id",
+    "parse_node_id",
+    # manifest
+    "ManifestError",
+    "NodeManifest",
+    "CommunityManifest",
+    "build_node_manifest",
+    "verify_node_manifest",
+    "build_community_manifest",
+    "verify_community_manifest",
+]

hearthnet/identity/keys.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    import nacl.exceptions
+    import nacl.signing
+
+    _NACL_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _NACL_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+NodeID = str  # "ed25519:XXXX-XXXX-XXXX-XXXX" (short) or "ed25519:<b64url>" (full)
+Signature = str  # "ed25519:<b64url>"
+
+
+class IdentityError(Exception):
+    """Raised for all identity-layer failures."""
+
+    def __init__(self, code: str, reason: str = "") -> None:
+        super().__init__(reason or code)
+        self.code = code
+        self.reason = reason
+
+
+@dataclass(frozen=True)
+class KeyPair:
+    signing_key: Any  # nacl.signing.SigningKey
+    verify_key: Any  # nacl.signing.VerifyKey
+    node_id_short: str
+    node_id_full: str
+
+
+# ---------------------------------------------------------------------------
+# ID helpers
+# ---------------------------------------------------------------------------
+
+
+def short_node_id(verify_key_bytes: bytes) -> str:
+    """First 8 bytes base32, grouped in 4-char segments: 'ed25519:XXXX-XXXX-XXXX-XXXX'."""
+    raw = base64.b32encode(verify_key_bytes[:8]).decode("ascii")
+    grouped = "-".join(raw[i : i + 4] for i in range(0, len(raw), 4))
+    return f"ed25519:{grouped}"
+
+
+def full_node_id(verify_key_bytes: bytes) -> str:
+    """All 32 bytes base64url no-pad: 'ed25519:<b64>'."""
+    b64 = base64.urlsafe_b64encode(verify_key_bytes).rstrip(b"=").decode("ascii")
+    return f"ed25519:{b64}"
+
+
+def parse_node_id(node_id: str) -> bytes:
+    """Decode a full node_id to 32 bytes. Short form raises ValueError."""
+    import re
+    if not node_id.startswith("ed25519:"):
+        raise ValueError(f"node_id must start with 'ed25519:': {node_id!r}")
+    payload = node_id[len("ed25519:"):]
+    # Short form is b32-with-dashes: groups of [A-Z2-7=]{1,4} separated by '-'
+    # e.g. "SQ2J-OH7E-LCMU-Y===" — always shorter than 30 chars and matches this pattern.
+    # Full form is 43-char base64url (no '=' padding).
+    if re.fullmatch(r"[A-Z2-7=]{1,4}(-[A-Z2-7=]{1,4}){1,}", payload):
+        raise ValueError(
+            "Short node IDs cannot be decoded to raw bytes; use full form."
+        )
+    # Add padding back for base64url decoding
+    padded = payload + "=" * (4 - len(payload) % 4 if len(payload) % 4 != 0 else 0)
+    raw = base64.urlsafe_b64decode(padded)
+    if len(raw) != 32:
+        raise ValueError(f"Expected 32 bytes, got {len(raw)}")
+    return raw
+
+
+# ---------------------------------------------------------------------------
+# Canonical JSON
+# ---------------------------------------------------------------------------
+
+
+def canonical_json(obj: Any) -> bytes:
+    """Canonical JSON: sorted keys, no whitespace, numbers stripped of trailing zeros, UTF-8."""
+    serialised = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    # Strip trailing zeros from numbers: 1.0 -> 1, 1.10 -> 1.1
+    # We post-process the JSON string carefully without breaking string contents.
+    result = _strip_trailing_zeros(serialised)
+    return result.encode("utf-8")
+
+
+def _strip_trailing_zeros(s: str) -> str:
+    """Remove trailing zeros from JSON numbers without touching string values."""
+    import re
+
+    # Match JSON numbers (integers, floats, exponent forms) that appear outside strings
+    # We parse character-by-character to skip string literals.
+    out: list[str] = []
+    i = 0
+    n = len(s)
+    while i < n:
+        c = s[i]
+        if c == '"':
+            # Scan to end of string, respecting escapes
+            out.append(c)
+            i += 1
+            while i < n:
+                ch = s[i]
+                out.append(ch)
+                if ch == "\\":
+                    i += 1
+                    if i < n:
+                        out.append(s[i])
+                elif ch == '"':
+                    i += 1
+                    break
+                i += 1
+        else:
+            # Look for a number token
+            m = re.match(r"-?(?:0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?", s[i:])
+            if m and (m.group(1) or m.group(2)):
+                num_str = m.group(0)
+                # Parse and reformat
+                try:
+                    val = float(num_str)
+                    # If it represents an integer value, emit as integer
+                    if val == int(val) and "e" not in num_str.lower():
+                        out.append(str(int(val)))
+                    else:
+                        # Strip trailing zeros from decimal part
+                        formatted = f"{val:g}"
+                        out.append(formatted)
+                except (ValueError, OverflowError):
+                    out.append(num_str)
+                i += len(num_str)
+            else:
+                out.append(c)
+                i += 1
+    return "".join(out)
+
+
+# ---------------------------------------------------------------------------
+# Signing / Verification
+# ---------------------------------------------------------------------------
+
+
+def sign_payload(payload: dict, kp: KeyPair) -> dict:
+    """Return a copy of payload with 'signature' field added (signs over payload without signature)."""
+    if not _NACL_AVAILABLE:
+        raise IdentityError("keys_invalid", reason="PyNaCl not installed")
+    unsigned = {k: v for k, v in payload.items() if k != "signature"}
+    raw = canonical_json(unsigned)
+    try:
+        signed = kp.signing_key.sign(raw)
+        sig_bytes = signed.signature
+    except Exception as exc:
+        raise IdentityError("sign_failed", reason=str(exc)) from exc
+    sig_b64 = base64.urlsafe_b64encode(sig_bytes).rstrip(b"=").decode("ascii")
+    result = dict(unsigned)
+    result["signature"] = f"ed25519:{sig_b64}"
+    return result
+
+
+def verify_payload(payload: dict, vk: Any) -> bool:  # vk: nacl.signing.VerifyKey
+    """Verify the 'signature' field of payload against vk. Returns True or raises IdentityError."""
+    if not _NACL_AVAILABLE:
+        raise IdentityError("keys_invalid", reason="PyNaCl not installed")
+    raw_sig = payload.get("signature", "")
+    if not raw_sig.startswith("ed25519:"):
+        raise IdentityError("verify_failed", reason="signature field missing or malformed")
+    sig_b64 = raw_sig[len("ed25519:"):]
+    padding = 4 - len(sig_b64) % 4
+    if padding != 4:
+        sig_b64 += "=" * padding
+    try:
+        sig_bytes = base64.urlsafe_b64decode(sig_b64)
+    except Exception as exc:
+        raise IdentityError("verify_failed", reason=f"bad signature encoding: {exc}") from exc
+    unsigned = {k: v for k, v in payload.items() if k != "signature"}
+    raw = canonical_json(unsigned)
+    try:
+        vk.verify(raw, sig_bytes)
+    except nacl.exceptions.BadSignatureError as exc:
+        raise IdentityError("verify_failed", reason="signature verification failed") from exc
+    except Exception as exc:
+        raise IdentityError("verify_failed", reason=str(exc)) from exc
+    return True
+
+
+def verify_payload_with_node_id(payload: dict, expected_node_id_full: str) -> bool:
+    """Verify payload signature using the public key encoded in expected_node_id_full."""
+    if not _NACL_AVAILABLE:
+        raise IdentityError("keys_invalid", reason="PyNaCl not installed")
+    try:
+        vk_bytes = parse_node_id(expected_node_id_full)
+    except ValueError as exc:
+        raise IdentityError("bad_node_id", reason=str(exc)) from exc
+    try:
+        vk = nacl.signing.VerifyKey(vk_bytes)
+    except Exception as exc:
+        raise IdentityError("keys_invalid", reason=str(exc)) from exc
+    return verify_payload(payload, vk)
+
+
+# ---------------------------------------------------------------------------
+# Key I/O
+# ---------------------------------------------------------------------------
+
+
+def generate() -> KeyPair:
+    """Generate a fresh Ed25519 keypair using os.urandom."""
+    if not _NACL_AVAILABLE:
+        raise IdentityError("keys_invalid", reason="PyNaCl not installed")
+    seed = os.urandom(32)
+    sk = nacl.signing.SigningKey(seed)
+    vk = sk.verify_key
+    vk_bytes = bytes(vk)
+    return KeyPair(
+        signing_key=sk,
+        verify_key=vk,
+        node_id_short=short_node_id(vk_bytes),
+        node_id_full=full_node_id(vk_bytes),
+    )
+
+
+def save(kp: KeyPair, keys_dir: Path) -> None:
+    """Save signing key (chmod 0600) and verify key to keys_dir."""
+    keys_dir.mkdir(parents=True, exist_ok=True)
+    priv_path = keys_dir / "device.ed25519"
+    pub_path = keys_dir / "device.pub"
+    # Write private key (raw 32-byte seed, base64url encoded)
+    sk_bytes = bytes(kp.signing_key)
+    priv_path.write_bytes(
+        base64.urlsafe_b64encode(sk_bytes).rstrip(b"=") + b"\n"
+    )
+    # Restrict permissions on POSIX
+    try:
+        os.chmod(priv_path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+    except AttributeError:
+        pass  # Windows: chmod semantics differ; best-effort
+    # Write public key
+    vk_bytes = bytes(kp.verify_key)
+    pub_path.write_bytes(
+        base64.urlsafe_b64encode(vk_bytes).rstrip(b"=") + b"\n"
+    )
+
+
+def load(keys_dir: Path) -> KeyPair:
+    """Load KeyPair from device.ed25519 + device.pub in keys_dir."""
+    if not _NACL_AVAILABLE:
+        raise IdentityError("keys_invalid", reason="PyNaCl not installed")
+    priv_path = keys_dir / "device.ed25519"
+    pub_path = keys_dir / "device.pub"
+    if not priv_path.exists() or not pub_path.exists():
+        raise IdentityError("keys_missing", reason=f"Key files not found in {keys_dir}")
+    # Check permissions on POSIX
+    try:
+        mode = oct(stat.S_IMODE(priv_path.stat().st_mode))
+        if not mode.endswith("600") and not mode.endswith("400"):
+            raise IdentityError(
+                "keys_permissions",
+                reason=f"Private key {priv_path} has unsafe permissions {mode}",
+            )
+    except AttributeError:
+        pass  # Windows
+    try:
+        sk_b64 = priv_path.read_text().strip()
+        padding = 4 - len(sk_b64) % 4
+        if padding != 4:
+            sk_b64 += "=" * padding
+        sk_bytes = base64.urlsafe_b64decode(sk_b64)
+        sk = nacl.signing.SigningKey(sk_bytes)
+    except IdentityError:
+        raise
+    except Exception as exc:
+        raise IdentityError("keys_invalid", reason=str(exc)) from exc
+    vk = sk.verify_key
+    vk_bytes = bytes(vk)
+    return KeyPair(
+        signing_key=sk,
+        verify_key=vk,
+        node_id_short=short_node_id(vk_bytes),
+        node_id_full=full_node_id(vk_bytes),
+    )
+
+
+def load_or_generate(keys_dir: Path) -> KeyPair:
+    """Load keys if present, otherwise generate and persist."""
+    priv_path = keys_dir / "device.ed25519"
+    if priv_path.exists():
+        return load(keys_dir)
+    kp = generate()
+    save(kp, keys_dir)
+    return kp

hearthnet/identity/manifest.py

@@ -0,0 +1,414 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from hearthnet.identity.keys import (
+    IdentityError,
+    KeyPair,
+    parse_node_id,
+    sign_payload,
+    verify_payload,
+)
+
+try:
+    import nacl.signing
+
+    _NACL_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _NACL_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class ManifestError(Exception):
+    """Raised for manifest validation failures."""
+
+    def __init__(self, code: str, reason: str = "") -> None:
+        super().__init__(reason or code)
+        self.code = code
+        self.reason = reason
+
+
+# ---------------------------------------------------------------------------
+# Value types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    transport: str
+    host: str
+    port: int
+
+
+@dataclass(frozen=True)
+class HardwareSpec:
+    gpu: str | None
+    ram_gb: float
+    cpu_cores: int
+    disk_free_gb: float
+
+
+@dataclass(frozen=True)
+class CapabilitySpec:
+    name: str
+    version: str
+    stability: str
+    params: dict
+    max_concurrent: int
+
+
+# ---------------------------------------------------------------------------
+# NodeManifest
+# ---------------------------------------------------------------------------
+
+_NODE_MANIFEST_TTL_SECONDS = 30
+_COMMUNITY_MANIFEST_TTL_SECONDS = 86400
+
+_REQUIRED_NODE_FIELDS = {
+    "version", "node_id", "display_name", "community_id", "profile",
+    "endpoints", "capabilities", "issued_at", "expires_at", "contract_version",
+    "signature",
+}
+
+_REQUIRED_COMMUNITY_FIELDS = {
+    "version", "community_id", "name", "root_node_id", "members", "policy",
+    "issued_at", "expires_at", "contract_version", "signature",
+}
+
+
+def _parse_rfc3339(s: str) -> datetime:
+    """Parse RFC 3339 UTC timestamp."""
+    # Accept trailing Z or +00:00
+    s = s.rstrip("Z")
+    if "+" in s:
+        s = s[: s.index("+")]
+    return datetime.fromisoformat(s).replace(tzinfo=timezone.utc)
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _rfc3339(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass(frozen=True)
+class NodeManifest:
+    version: int
+    node_id: str
+    display_name: str
+    community_id: str
+    profile: str
+    endpoints: list
+    capabilities: list
+    hardware: HardwareSpec | None
+    issued_at: str
+    expires_at: str
+    contract_version: str
+    signature: str
+
+    def is_expired(self, now: datetime | None = None) -> bool:
+        ts = now or _now_utc()
+        try:
+            exp = _parse_rfc3339(self.expires_at)
+        except (ValueError, AttributeError):
+            return True
+        return ts >= exp
+
+    def as_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "version": self.version,
+            "node_id": self.node_id,
+            "display_name": self.display_name,
+            "community_id": self.community_id,
+            "profile": self.profile,
+            "endpoints": [
+                {"transport": e.transport, "host": e.host, "port": e.port}
+                for e in self.endpoints
+            ],
+            "capabilities": [
+                {
+                    "name": c.name,
+                    "version": c.version,
+                    "stability": c.stability,
+                    "params": c.params,
+                    "max_concurrent": c.max_concurrent,
+                }
+                for c in self.capabilities
+            ],
+            "issued_at": self.issued_at,
+            "expires_at": self.expires_at,
+            "contract_version": self.contract_version,
+            "signature": self.signature,
+        }
+        if self.hardware is not None:
+            d["hardware"] = {
+                "gpu": self.hardware.gpu,
+                "ram_gb": self.hardware.ram_gb,
+                "cpu_cores": self.hardware.cpu_cores,
+                "disk_free_gb": self.hardware.disk_free_gb,
+            }
+        return d
+
+
+@dataclass(frozen=True)
+class CommunityManifest:
+    version: int
+    community_id: str
+    name: str
+    root_node_id: str
+    members: list
+    policy: dict
+    issued_at: str
+    expires_at: str
+    contract_version: str
+    signature: str
+
+    def is_expired(self, now: datetime | None = None) -> bool:
+        ts = now or _now_utc()
+        try:
+            exp = _parse_rfc3339(self.expires_at)
+        except (ValueError, AttributeError):
+            return True
+        return ts >= exp
+
+    def as_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "community_id": self.community_id,
+            "name": self.name,
+            "root_node_id": self.root_node_id,
+            "members": list(self.members),
+            "policy": dict(self.policy),
+            "issued_at": self.issued_at,
+            "expires_at": self.expires_at,
+            "contract_version": self.contract_version,
+            "signature": self.signature,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Builders
+# ---------------------------------------------------------------------------
+
+
+def build_node_manifest(
+    kp: KeyPair,
+    display_name: str,
+    community_id: str,
+    profile: str,
+    endpoints: list[Endpoint],
+    capabilities: list[CapabilitySpec],
+    hardware: HardwareSpec | None = None,
+) -> NodeManifest:
+    now = _now_utc()
+    issued_at = _rfc3339(now)
+    expires_at = _rfc3339(now + timedelta(seconds=_NODE_MANIFEST_TTL_SECONDS))
+    payload: dict[str, Any] = {
+        "version": 1,
+        "node_id": kp.node_id_full,
+        "display_name": display_name,
+        "community_id": community_id,
+        "profile": profile,
+        "endpoints": [
+            {"transport": e.transport, "host": e.host, "port": e.port}
+            for e in endpoints
+        ],
+        "capabilities": [
+            {
+                "name": c.name,
+                "version": c.version,
+                "stability": c.stability,
+                "params": c.params,
+                "max_concurrent": c.max_concurrent,
+            }
+            for c in capabilities
+        ],
+        "issued_at": issued_at,
+        "expires_at": expires_at,
+        "contract_version": "1.0",
+    }
+    if hardware is not None:
+        payload["hardware"] = {
+            "gpu": hardware.gpu,
+            "ram_gb": hardware.ram_gb,
+            "cpu_cores": hardware.cpu_cores,
+            "disk_free_gb": hardware.disk_free_gb,
+        }
+    signed = sign_payload(payload, kp)
+    return NodeManifest(
+        version=signed["version"],
+        node_id=signed["node_id"],
+        display_name=signed["display_name"],
+        community_id=signed["community_id"],
+        profile=signed["profile"],
+        endpoints=[
+            Endpoint(transport=e["transport"], host=e["host"], port=e["port"])
+            for e in signed["endpoints"]
+        ],
+        capabilities=[
+            CapabilitySpec(
+                name=c["name"],
+                version=c["version"],
+                stability=c["stability"],
+                params=c["params"],
+                max_concurrent=c["max_concurrent"],
+            )
+            for c in signed["capabilities"]
+        ],
+        hardware=hardware,
+        issued_at=signed["issued_at"],
+        expires_at=signed["expires_at"],
+        contract_version=signed["contract_version"],
+        signature=signed["signature"],
+    )
+
+
+def verify_node_manifest(manifest_dict: dict) -> NodeManifest:
+    """Verify signature and expiry, return NodeManifest."""
+    missing = _REQUIRED_NODE_FIELDS - set(manifest_dict.keys())
+    if missing:
+        raise ManifestError("missing_field", reason=f"Missing fields: {missing}")
+    node_id = manifest_dict.get("node_id", "")
+    try:
+        vk_bytes = parse_node_id(node_id)
+    except ValueError as exc:
+        raise ManifestError("schema_error", reason=str(exc)) from exc
+    if not _NACL_AVAILABLE:
+        raise ManifestError("invalid_signature", reason="PyNaCl not installed")
+    try:
+        vk = nacl.signing.VerifyKey(vk_bytes)
+    except Exception as exc:
+        raise ManifestError("schema_error", reason=str(exc)) from exc
+    try:
+        verify_payload(manifest_dict, vk)
+    except IdentityError as exc:
+        raise ManifestError("invalid_signature", reason=exc.reason) from exc
+    # Check expiry
+    expires_at = manifest_dict.get("expires_at", "")
+    try:
+        exp = _parse_rfc3339(expires_at)
+    except (ValueError, AttributeError) as exc:
+        raise ManifestError("schema_error", reason=f"Invalid expires_at: {expires_at}") from exc
+    if _now_utc() >= exp:
+        raise ManifestError("expired", reason=f"Manifest expired at {expires_at}")
+    hw_dict = manifest_dict.get("hardware")
+    hardware = (
+        HardwareSpec(
+            gpu=hw_dict.get("gpu"),
+            ram_gb=hw_dict["ram_gb"],
+            cpu_cores=hw_dict["cpu_cores"],
+            disk_free_gb=hw_dict["disk_free_gb"],
+        )
+        if hw_dict
+        else None
+    )
+    return NodeManifest(
+        version=manifest_dict["version"],
+        node_id=manifest_dict["node_id"],
+        display_name=manifest_dict["display_name"],
+        community_id=manifest_dict["community_id"],
+        profile=manifest_dict["profile"],
+        endpoints=[
+            Endpoint(transport=e["transport"], host=e["host"], port=e["port"])
+            for e in manifest_dict["endpoints"]
+        ],
+        capabilities=[
+            CapabilitySpec(
+                name=c["name"],
+                version=c["version"],
+                stability=c["stability"],
+                params=c["params"],
+                max_concurrent=c["max_concurrent"],
+            )
+            for c in manifest_dict["capabilities"]
+        ],
+        hardware=hardware,
+        issued_at=manifest_dict["issued_at"],
+        expires_at=manifest_dict["expires_at"],
+        contract_version=manifest_dict["contract_version"],
+        signature=manifest_dict["signature"],
+    )
+
+
+def build_community_manifest(
+    kp: KeyPair,
+    name: str,
+    members: list[str],
+    policy: dict,
+) -> CommunityManifest:
+    now = _now_utc()
+    issued_at = _rfc3339(now)
+    expires_at = _rfc3339(now + timedelta(seconds=_COMMUNITY_MANIFEST_TTL_SECONDS))
+    community_id = kp.node_id_full
+    payload: dict[str, Any] = {
+        "version": 1,
+        "community_id": community_id,
+        "name": name,
+        "root_node_id": kp.node_id_full,
+        "members": list(members),
+        "policy": dict(policy),
+        "issued_at": issued_at,
+        "expires_at": expires_at,
+        "contract_version": "1.0",
+    }
+    signed = sign_payload(payload, kp)
+    return CommunityManifest(
+        version=signed["version"],
+        community_id=signed["community_id"],
+        name=signed["name"],
+        root_node_id=signed["root_node_id"],
+        members=signed["members"],
+        policy=signed["policy"],
+        issued_at=signed["issued_at"],
+        expires_at=signed["expires_at"],
+        contract_version=signed["contract_version"],
+        signature=signed["signature"],
+    )
+
+
+def verify_community_manifest(manifest_dict: dict) -> CommunityManifest:
+    """Verify signature and expiry, return CommunityManifest."""
+    missing = _REQUIRED_COMMUNITY_FIELDS - set(manifest_dict.keys())
+    if missing:
+        raise ManifestError("missing_field", reason=f"Missing fields: {missing}")
+    root_node_id = manifest_dict.get("root_node_id", "")
+    try:
+        vk_bytes = parse_node_id(root_node_id)
+    except ValueError as exc:
+        raise ManifestError("schema_error", reason=str(exc)) from exc
+    if not _NACL_AVAILABLE:
+        raise ManifestError("invalid_signature", reason="PyNaCl not installed")
+    try:
+        vk = nacl.signing.VerifyKey(vk_bytes)
+    except Exception as exc:
+        raise ManifestError("schema_error", reason=str(exc)) from exc
+    try:
+        verify_payload(manifest_dict, vk)
+    except IdentityError as exc:
+        raise ManifestError("invalid_signature", reason=exc.reason) from exc
+    expires_at = manifest_dict.get("expires_at", "")
+    try:
+        exp = _parse_rfc3339(expires_at)
+    except (ValueError, AttributeError) as exc:
+        raise ManifestError("schema_error", reason=f"Invalid expires_at: {expires_at}") from exc
+    if _now_utc() >= exp:
+        raise ManifestError("expired", reason=f"Manifest expired at {expires_at}")
+    return CommunityManifest(
+        version=manifest_dict["version"],
+        community_id=manifest_dict["community_id"],
+        name=manifest_dict["name"],
+        root_node_id=manifest_dict["root_node_id"],
+        members=manifest_dict["members"],
+        policy=manifest_dict["policy"],
+        issued_at=manifest_dict["issued_at"],
+        expires_at=manifest_dict["expires_at"],
+        contract_version=manifest_dict["contract_version"],
+        signature=manifest_dict["signature"],
+    )

hearthnet/identity/tokens.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+"""tokens.py — Phase 2 stub for capability tokens.
+
+All functions raise NotImplementedError. Implement in Phase 2.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CapabilityToken:
+    """Stub for a signed capability token (Phase 2)."""
+
+    token_id: str
+    issuer_node_id: str
+    subject_node_id: str
+    capability: str
+    issued_at: str
+    expires_at: str
+    signature: str
+
+
+def issue_token(
+    issuer_kp: Any,
+    subject_node_id: str,
+    capability: str,
+    ttl_seconds: int = 300,
+) -> CapabilityToken:
+    """Issue a signed capability token. Phase 2 — not yet implemented."""
+    raise NotImplementedError("CapabilityToken issuance is a Phase 2 feature.")
+
+
+def verify_token(token: CapabilityToken) -> bool:
+    """Verify a capability token's signature and expiry. Phase 2 — not yet implemented."""
+    raise NotImplementedError("CapabilityToken verification is a Phase 2 feature.")
+
+
+def revoke_token(token_id: str) -> None:
+    """Revoke a capability token by ID. Phase 2 — not yet implemented."""
+    raise NotImplementedError("CapabilityToken revocation is a Phase 2 feature.")

hearthnet/observability/__init__.py

@@ -0,0 +1,41 @@
+"""HearthNet — X03 Observability package.
+
+Re-exports the public surface of all sub-modules so callers can do::
+
+    from hearthnet.observability import get_logger, configure, new_trace, span
+
+Full imports:
+    from hearthnet.observability.logging import JsonFormatter, RateLimitedLogger
+    from hearthnet.observability.metrics import counter, histogram, gauge
+    from hearthnet.observability.tracing import Trace, Span, TraceRingBuffer
+    from hearthnet.observability.doctor import run_all, run_one
+"""
+from __future__ import annotations
+
+from hearthnet.observability.logging import (
+    JsonFormatter,
+    RateLimitedLogger,
+    configure,
+    get_logger,
+)
+from hearthnet.observability.tracing import (
+    attach,
+    current_trace,
+    get_ring_buffer,
+    new_trace,
+    span,
+)
+
+__all__ = [
+    # logging
+    "configure",
+    "get_logger",
+    "JsonFormatter",
+    "RateLimitedLogger",
+    # tracing
+    "attach",
+    "current_trace",
+    "get_ring_buffer",
+    "new_trace",
+    "span",
+]

hearthnet/observability/doctor.py

@@ -0,0 +1,286 @@
+"""HearthNet — X03 Observability: Self-diagnostics (doctor).
+
+Public API:
+    run_all()        — run every registered check, return results
+    run_one(name)    — run a single check by name
+    DoctorCheck      — dataclass describing a check
+    DoctorResult     — dataclass with check outcome
+"""
+from __future__ import annotations
+
+import shutil
+import socket
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from hearthnet.config import _default_config_path, _xdg_config
+
+# ── Dataclasses ──────────────────────────────────────────────────────────────
+
+@dataclass
+class DoctorCheck:
+    name: str
+    description: str
+    fix_hint: str = ""
+
+
+@dataclass
+class DoctorResult:
+    check: DoctorCheck
+    passed: bool
+    message: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+# ── Check registry ───────────────────────────────────────────────────────────
+
+_CHECK_FN: dict[str, tuple[DoctorCheck, Callable[[], DoctorResult]]] = {}
+
+
+def _register(check: DoctorCheck) -> Callable:
+    def _decorator(fn: Callable[[], DoctorResult]) -> Callable[[], DoctorResult]:
+        _CHECK_FN[check.name] = (check, fn)
+        return fn
+    return _decorator
+
+
+# ── Built-in checks ──────────────────────────────────────────────────────────
+
+_KEYS_CHECK = DoctorCheck(
+    name="keys_present",
+    description="Check that the keys directory exists.",
+    fix_hint="Run `hearthnet keys generate` to create a device key-pair.",
+)
+
+@_register(_KEYS_CHECK)
+def _keys_present() -> DoctorResult:
+    keys_dir = _xdg_config() / "keys"
+    exists = keys_dir.is_dir()
+    return DoctorResult(
+        check=_KEYS_CHECK,
+        passed=exists,
+        message=f"Keys directory {'found' if exists else 'missing'}: {keys_dir}",
+        extra={"path": str(keys_dir)},
+    )
+
+
+_KEYS_LOADABLE_CHECK = DoctorCheck(
+    name="keys_loadable",
+    description="Verify that device.pub can be read from the keys directory.",
+    fix_hint="Run `hearthnet keys generate` or restore the key file.",
+)
+
+@_register(_KEYS_LOADABLE_CHECK)
+def _keys_loadable() -> DoctorResult:
+    pub = _xdg_config() / "keys" / "device.pub"
+    try:
+        data = pub.read_bytes()
+        return DoctorResult(
+            check=_KEYS_LOADABLE_CHECK,
+            passed=True,
+            message=f"device.pub read OK ({len(data)} bytes)",
+            extra={"path": str(pub), "size": len(data)},
+        )
+    except FileNotFoundError:
+        return DoctorResult(
+            check=_KEYS_LOADABLE_CHECK,
+            passed=False,
+            message=f"device.pub not found at {pub}",
+            extra={"path": str(pub)},
+        )
+    except OSError as exc:
+        return DoctorResult(
+            check=_KEYS_LOADABLE_CHECK,
+            passed=False,
+            message=f"Could not read device.pub: {exc}",
+            extra={"path": str(pub), "error": str(exc)},
+        )
+
+
+_CONFIG_CHECK = DoctorCheck(
+    name="config_loadable",
+    description="Verify that config.toml can be parsed.",
+    fix_hint="Run `hearthnet config init` or fix syntax in config.toml.",
+)
+
+@_register(_CONFIG_CHECK)
+def _config_loadable() -> DoctorResult:
+    cfg_path = _default_config_path()
+    if not cfg_path.exists():
+        return DoctorResult(
+            check=_CONFIG_CHECK,
+            passed=False,
+            message=f"config.toml not found at {cfg_path}",
+            extra={"path": str(cfg_path)},
+        )
+    try:
+        # Attempt to parse without full config validation
+        try:
+            import tomllib
+        except ImportError:
+            try:
+                import tomli as tomllib  # type: ignore[no-redef]
+            except ImportError:
+                return DoctorResult(
+                    check=_CONFIG_CHECK,
+                    passed=False,
+                    message="No TOML parser available (tomllib/tomli missing)",
+                )
+        with open(cfg_path, "rb") as fh:
+            tomllib.load(fh)
+        return DoctorResult(
+            check=_CONFIG_CHECK,
+            passed=True,
+            message=f"config.toml parsed OK: {cfg_path}",
+            extra={"path": str(cfg_path)},
+        )
+    except Exception as exc:
+        return DoctorResult(
+            check=_CONFIG_CHECK,
+            passed=False,
+            message=f"config.toml parse error: {exc}",
+            extra={"path": str(cfg_path), "error": str(exc)},
+        )
+
+
+_MDNS_CHECK = DoctorCheck(
+    name="mdns_socket",
+    description="Try to bind the mDNS multicast port (5353).",
+    fix_hint="Check if another mDNS daemon (avahi, bonjour) is already running.",
+)
+
+_MDNS_PORT = 5353
+
+@_register(_MDNS_CHECK)
+def _mdns_socket() -> DoctorResult:
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind(("", _MDNS_PORT))
+            sock.close()
+            return DoctorResult(
+                check=_MDNS_CHECK,
+                passed=True,
+                message=f"mDNS port {_MDNS_PORT} bindable",
+                extra={"port": _MDNS_PORT},
+            )
+        except OSError as exc:
+            sock.close()
+            return DoctorResult(
+                check=_MDNS_CHECK,
+                passed=False,
+                message=f"Cannot bind mDNS port {_MDNS_PORT}: {exc}",
+                extra={"port": _MDNS_PORT, "error": str(exc)},
+            )
+    except Exception as exc:
+        return DoctorResult(
+            check=_MDNS_CHECK,
+            passed=False,
+            message=f"Socket error: {exc}",
+            extra={"error": str(exc)},
+        )
+
+
+_LOG_DIR_CHECK = DoctorCheck(
+    name="log_dir_writable",
+    description="Check that the log directory is writable.",
+    fix_hint="Ensure the process has write access to the log directory (chmod or set log_dir in config).",
+)
+
+@_register(_LOG_DIR_CHECK)
+def _log_dir_writable() -> DoctorResult:
+    from hearthnet.config import _xdg_data
+    log_dir = _xdg_data() / "logs"
+    try:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        test_file = log_dir / ".write_test"
+        test_file.write_text("ok")
+        test_file.unlink()
+        return DoctorResult(
+            check=_LOG_DIR_CHECK,
+            passed=True,
+            message=f"Log directory is writable: {log_dir}",
+            extra={"path": str(log_dir)},
+        )
+    except OSError as exc:
+        return DoctorResult(
+            check=_LOG_DIR_CHECK,
+            passed=False,
+            message=f"Log directory not writable: {exc}",
+            extra={"path": str(log_dir), "error": str(exc)},
+        )
+
+
+_DISK_CHECK = DoctorCheck(
+    name="disk_space",
+    description="Warn if available disk space is below 500 MB.",
+    fix_hint="Free up disk space or move data directories to a larger volume.",
+)
+
+_DISK_WARN_BYTES = 500 * 1024 * 1024  # 500 MB
+
+@_register(_DISK_CHECK)
+def _disk_space() -> DoctorResult:
+    from hearthnet.config import _xdg_data
+    target = _xdg_data()
+    try:
+        target.mkdir(parents=True, exist_ok=True)
+        usage = shutil.disk_usage(str(target))
+        free_mb = usage.free / (1024 * 1024)
+        passed = usage.free >= _DISK_WARN_BYTES
+        return DoctorResult(
+            check=_DISK_CHECK,
+            passed=passed,
+            message=(
+                f"Disk free: {free_mb:.0f} MB"
+                if passed
+                else f"Low disk space: {free_mb:.0f} MB free (threshold 500 MB)"
+            ),
+            extra={"free_bytes": usage.free, "total_bytes": usage.total, "path": str(target)},
+        )
+    except OSError as exc:
+        return DoctorResult(
+            check=_DISK_CHECK,
+            passed=False,
+            message=f"Could not check disk space: {exc}",
+            extra={"error": str(exc)},
+        )
+
+
+# ── Public functions ──────────────────────────────────────────────────────────
+
+def run_all() -> list[DoctorResult]:
+    """Run all registered checks and return their results."""
+    results = []
+    for _check, fn in _CHECK_FN.values():
+        try:
+            results.append(fn())
+        except Exception as exc:
+            results.append(
+                DoctorResult(
+                    check=_check,
+                    passed=False,
+                    message=f"Check raised an unexpected error: {exc}",
+                    extra={"error": str(exc)},
+                )
+            )
+    return results
+
+
+def run_one(name: str) -> DoctorResult:
+    """Run a single check by name. Raises KeyError for unknown names."""
+    entry = _CHECK_FN.get(name)
+    if entry is None:
+        known = ", ".join(sorted(_CHECK_FN))
+        raise KeyError(f"Unknown doctor check {name!r}. Known checks: {known}")
+    _check, fn = entry
+    try:
+        return fn()
+    except Exception as exc:
+        return DoctorResult(
+            check=_check,
+            passed=False,
+            message=f"Check raised an unexpected error: {exc}",
+            extra={"error": str(exc)},
+        )

hearthnet/observability/logging.py

@@ -0,0 +1,145 @@
+"""HearthNet — X03 Observability: Structured JSON logging.
+
+Public API:
+    configure(config)   — install handlers/formatters. Idempotent.
+    get_logger(name)    — return JSON-emitting stdlib logger
+    JsonFormatter       — one-line JSON log records
+    RateLimitedLogger   — at most one log per second per (logger, key)
+"""
+from __future__ import annotations
+
+import json
+import logging
+import logging.handlers
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from hearthnet.config import ObservabilityConfig
+from hearthnet.constants import LOG_RETENTION_DAYS
+
+_configured = False
+_configure_lock = threading.Lock()
+
+
+class JsonFormatter(logging.Formatter):
+    """Renders a LogRecord as a single JSON line."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S.") + f"{record.msecs:03.0f}Z",
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+
+        # Attach structured extras (skip stdlib internals)
+        _SKIP = {
+            "name", "msg", "args", "created", "filename", "funcName", "levelname",
+            "levelno", "lineno", "module", "msecs", "pathname", "process",
+            "processName", "relativeCreated", "stack_info", "thread", "threadName",
+            "exc_info", "exc_text", "message",
+        }
+        for key, val in record.__dict__.items():
+            if key not in _SKIP:
+                payload[key] = val
+
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+
+        return json.dumps(payload, default=str, ensure_ascii=False)
+
+
+def configure(config: ObservabilityConfig) -> None:
+    """Install handlers and formatters on the root 'hearthnet' logger.
+
+    Idempotent — safe to call multiple times; only runs once.
+    """
+    global _configured
+    with _configure_lock:
+        if _configured:
+            return
+        _configured = True
+
+    level_name = (config.log_level or "info").upper()
+    level = getattr(logging, level_name, logging.INFO)
+
+    root = logging.getLogger("hearthnet")
+    root.setLevel(level)
+    root.handlers.clear()  # reset on reconfigure
+
+    formatter = JsonFormatter()
+
+    # Console handler
+    console = logging.StreamHandler()
+    console.setFormatter(formatter)
+    root.addHandler(console)
+
+    # File handler (daily rotation, 14-day retention)
+    log_dir: Path | None = config.log_dir
+    if log_dir is not None:
+        log_dir = Path(log_dir)
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_path = log_dir / "hearthnet.log"
+        file_handler = logging.handlers.TimedRotatingFileHandler(
+            filename=str(log_path),
+            when="midnight",
+            utc=True,
+            backupCount=LOG_RETENTION_DAYS,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(formatter)
+        root.addHandler(file_handler)
+
+    root.propagate = False
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a stdlib logger that emits JSON lines.
+
+    Convention: ``name = __name__`` of the calling module.
+    """
+    return logging.getLogger(name)
+
+
+class RateLimitedLogger:
+    """Wraps a Logger and suppresses duplicate messages within a 1-second window.
+
+    Keyed by ``(logger_name, message_key)`` — call with an explicit *key*
+    argument to group semantically similar messages:
+
+        rl_log.warning("peer unreachable", key="peer_unreachable")
+    """
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+        self._last: dict[tuple[str, str], float] = {}
+        self._lock = threading.Lock()
+        self._window = 1.0  # seconds
+
+    def _should_emit(self, key: str) -> bool:
+        bucket = (self._logger.name, key)
+        now = time.monotonic()
+        with self._lock:
+            last = self._last.get(bucket, 0.0)
+            if now - last >= self._window:
+                self._last[bucket] = now
+                return True
+        return False
+
+    def _emit(self, level: int, msg: str, key: str, **kwargs: Any) -> None:
+        if self._should_emit(key):
+            self._logger.log(level, msg, **kwargs)
+
+    def debug(self, msg: str, *, key: str = "", **kwargs: Any) -> None:
+        self._emit(logging.DEBUG, msg, key or msg, **kwargs)
+
+    def info(self, msg: str, *, key: str = "", **kwargs: Any) -> None:
+        self._emit(logging.INFO, msg, key or msg, **kwargs)
+
+    def warning(self, msg: str, *, key: str = "", **kwargs: Any) -> None:
+        self._emit(logging.WARNING, msg, key or msg, **kwargs)
+
+    def error(self, msg: str, *, key: str = "", **kwargs: Any) -> None:
+        self._emit(logging.ERROR, msg, key or msg, **kwargs)

hearthnet/observability/metrics.py

@@ -0,0 +1,212 @@
+"""HearthNet — X03 Observability: Prometheus-compatible metrics.
+
+prometheus_client is OPTIONAL. When not installed every factory returns a
+no-op object so call sites need no conditional logic.
+
+Public API:
+    configure(config)   — initialise registries / start HTTP endpoint
+    counter(...)        — Counter factory
+    histogram(...)      — Histogram factory
+    gauge(...)          — Gauge factory
+    disabled() -> bool  — True when prometheus_client is absent or metrics off
+
+Standard HearthNet metrics are created at module import time so they are
+always available as module-level names.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from hearthnet.config import ObservabilityConfig
+
+# ── Optional prometheus_client import ───────────────────────────────────────
+
+try:
+    import prometheus_client as _prom  # type: ignore[import]
+    _PROM_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _prom = None  # type: ignore[assignment]
+    _PROM_AVAILABLE = False
+
+_metrics_enabled: bool = True
+_configure_lock = threading.Lock()
+_configured = False
+
+
+# ── No-op stubs ──────────────────────────────────────────────────────────────
+
+class _NoOpMetric:
+    """Returned in place of a real Prometheus metric when unavailable."""
+
+    def labels(self, **_kwargs: Any) -> "_NoOpMetric":
+        return self
+
+    def inc(self, *_a: Any, **_kw: Any) -> None:
+        pass
+
+    def observe(self, *_a: Any, **_kw: Any) -> None:
+        pass
+
+    def set(self, *_a: Any, **_kw: Any) -> None:
+        pass
+
+
+_NOOP = _NoOpMetric()
+
+
+# ── Factories ────────────────────────────────────────────────────────────────
+
+def disabled() -> bool:
+    """Return True when metrics collection is not active."""
+    return not (_PROM_AVAILABLE and _metrics_enabled)
+
+
+def counter(
+    name: str,
+    doc: str,
+    labels: list[str] | None = None,
+) -> Any:
+    """Return a prometheus_client Counter or a no-op."""
+    if disabled():
+        return _NOOP
+    try:
+        return _prom.Counter(name, doc, labels or [])
+    except Exception:
+        return _NOOP
+
+
+def histogram(
+    name: str,
+    doc: str,
+    labels: list[str] | None = None,
+    buckets: list[float] | None = None,
+) -> Any:
+    """Return a prometheus_client Histogram or a no-op."""
+    if disabled():
+        return _NOOP
+    kwargs: dict[str, Any] = {}
+    if buckets is not None:
+        kwargs["buckets"] = buckets
+    try:
+        return _prom.Histogram(name, doc, labels or [], **kwargs)
+    except Exception:
+        return _NOOP
+
+
+def gauge(
+    name: str,
+    doc: str,
+    labels: list[str] | None = None,
+) -> Any:
+    """Return a prometheus_client Gauge or a no-op."""
+    if disabled():
+        return _NOOP
+    try:
+        return _prom.Gauge(name, doc, labels or [])
+    except Exception:
+        return _NOOP
+
+
+def configure(config: ObservabilityConfig) -> None:
+    """Initialise metrics according to *config*. Idempotent."""
+    global _metrics_enabled, _configured
+    with _configure_lock:
+        if _configured:
+            return
+        _configured = True
+        _metrics_enabled = config.metrics_enabled
+
+
+# ── Standard HearthNet metrics ───────────────────────────────────────────────
+# Created lazily to avoid side-effects at import time when prometheus_client
+# is not installed. Exposed as module-level singletons.
+
+_STD: dict[str, Any] = {}
+_std_lock = threading.Lock()
+
+
+def _std(name: str, kind: str, doc: str, labels: list[str], **kw: Any) -> Any:
+    """Return (and memoize) a named standard metric."""
+    with _std_lock:
+        if name not in _STD:
+            if kind == "counter":
+                _STD[name] = counter(name, doc, labels)
+            elif kind == "histogram":
+                _STD[name] = histogram(name, doc, labels, **kw)
+            else:
+                _STD[name] = gauge(name, doc, labels)
+        return _STD[name]
+
+
+# Convenience accessors for standard metrics -----------------------------------
+
+def requests_total() -> Any:
+    return _std(
+        "hearthnet_requests_total", "counter",
+        "Total routed requests", ["capability", "result"],
+    )
+
+
+def request_duration_ms() -> Any:
+    return _std(
+        "hearthnet_request_duration_ms", "histogram",
+        "Request round-trip duration in milliseconds", ["capability"],
+        buckets=[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
+    )
+
+
+def active_streams() -> Any:
+    return _std(
+        "hearthnet_active_streams", "gauge",
+        "Currently open streaming requests", ["capability"],
+    )
+
+
+def nodes_online() -> Any:
+    return _std(
+        "hearthnet_nodes_online", "gauge",
+        "Known online nodes per community", ["community"],
+    )
+
+
+def event_log_size() -> Any:
+    return _std(
+        "hearthnet_event_log_size", "gauge",
+        "Number of entries in the event log", ["community"],
+    )
+
+
+def emergency_mode() -> Any:
+    return _std(
+        "hearthnet_emergency_mode", "gauge",
+        "Whether emergency mode is active (1) or not (0)", ["state"],
+    )
+
+
+def blob_storage_bytes() -> Any:
+    return _std(
+        "hearthnet_blob_storage_bytes", "gauge",
+        "Total bytes stored in the blob store", [],
+    )
+
+
+def llm_tokens_generated_total() -> Any:
+    return _std(
+        "hearthnet_llm_tokens_generated_total", "counter",
+        "LLM tokens generated since startup", ["model", "backend"],
+    )
+
+
+def capability_health_success_rate() -> Any:
+    return _std(
+        "hearthnet_capability_health_success_rate", "gauge",
+        "Rolling success rate for a capability on a given node", ["capability", "node"],
+    )
+
+
+def signature_failures_total() -> Any:
+    return _std(
+        "hearthnet_signature_failures_total", "counter",
+        "Signature verification failures", ["reason"],
+    )

hearthnet/observability/tracing.py

@@ -0,0 +1,146 @@
+"""HearthNet — X03 Observability: Per-request tracing.
+
+Uses contextvars.ContextVar so traces propagate correctly across asyncio tasks.
+
+Public API:
+    new_trace(capability)  — create and attach a fresh Trace
+    current_trace()        — return the active Trace or None
+    attach(trace)          — set the active Trace on this context
+    span(name, **extras)   — context-manager that records a Span
+    TraceRingBuffer        — thread-safe ring buffer of last N traces
+    get_ring_buffer()      — module-level singleton ring buffer
+"""
+from __future__ import annotations
+
+import secrets
+import threading
+import time
+from collections import deque
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Iterator
+
+from hearthnet.constants import TRACE_RING_BUFFER_SIZE
+
+# ── ULID approximation ───────────────────────────────────────────────────────
+
+def _new_ulid() -> str:
+    """Simple ULID approximation: 13-digit ms timestamp + 12 hex random chars."""
+    try:
+        from python_ulid import ULID  # type: ignore[import]
+        return str(ULID())
+    except ImportError:
+        ts = str(int(time.time() * 1000)).zfill(13)
+        rand = secrets.token_hex(6).upper()
+        return ts + rand
+
+
+# ── Dataclasses ──────────────────────────────────────────────────────────────
+
+@dataclass
+class Span:
+    name: str
+    started_at: float = field(default_factory=time.monotonic)
+    ended_at: float | None = None
+    extras: dict = field(default_factory=dict)
+
+    @property
+    def duration_ms(self) -> float | None:
+        if self.ended_at is None:
+            return None
+        return (self.ended_at - self.started_at) * 1000.0
+
+
+@dataclass
+class Trace:
+    trace_id: str = field(default_factory=_new_ulid)
+    capability: str = ""
+    started_at: float = field(default_factory=time.monotonic)
+    spans: list[Span] = field(default_factory=list)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def add_span(self, span: Span) -> None:
+        with self._lock:
+            self.spans.append(span)
+
+
+# ── Context variable ─────────────────────────────────────────────────────────
+
+_current_trace: ContextVar[Trace | None] = ContextVar("_current_trace", default=None)
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+def new_trace(capability: str) -> Trace:
+    """Create a fresh Trace, attach it to this context, and return it."""
+    trace = Trace(capability=capability)
+    _current_trace.set(trace)
+    get_ring_buffer().push(trace)
+    return trace
+
+
+def current_trace() -> Trace | None:
+    """Return the Trace active on this context, or None."""
+    return _current_trace.get()
+
+
+def attach(trace: Trace) -> None:
+    """Set *trace* as the active trace on this context (e.g. to propagate to a child task)."""
+    _current_trace.set(trace)
+
+
+@contextmanager
+def span(name: str, **extras: object) -> Iterator[Span]:
+    """Context-manager that records a Span on the current Trace (if any).
+
+    Usage::
+
+        async with span("embed", model="nomic"):
+            ...
+    """
+    s = Span(name=name, extras=dict(extras))
+    trace = current_trace()
+    try:
+        yield s
+    finally:
+        s.ended_at = time.monotonic()
+        if trace is not None:
+            trace.add_span(s)
+
+
+# ── Ring buffer ──────────────────────────────────────────────────────────────
+
+class TraceRingBuffer:
+    """Thread-safe bounded ring buffer that keeps the last *maxlen* traces."""
+
+    def __init__(self, maxlen: int = TRACE_RING_BUFFER_SIZE) -> None:
+        self._buf: deque[Trace] = deque(maxlen=maxlen)
+        self._lock = threading.Lock()
+
+    def push(self, trace: Trace) -> None:
+        with self._lock:
+            self._buf.append(trace)
+
+    def snapshot(self) -> list[Trace]:
+        """Return a copy of all buffered traces, oldest first."""
+        with self._lock:
+            return list(self._buf)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._buf)
+
+
+_ring_buffer: TraceRingBuffer | None = None
+_ring_lock = threading.Lock()
+
+
+def get_ring_buffer() -> TraceRingBuffer:
+    """Return the module-level singleton TraceRingBuffer."""
+    global _ring_buffer
+    if _ring_buffer is None:
+        with _ring_lock:
+            if _ring_buffer is None:
+                _ring_buffer = TraceRingBuffer()
+    return _ring_buffer

hearthnet/services/__init__.py

@@ -1,3 +1,6 @@
-from hearthnet.services.demo import ChatService, LlmService, MarketplaceService, RagService
+from hearthnet.services.chat import ChatService
+from hearthnet.services.demo import RagService
+from hearthnet.services.llm import LlmService
+from hearthnet.services.marketplace import MarketplaceService
 
 __all__ = ["ChatService", "LlmService", "MarketplaceService", "RagService"]

hearthnet/services/chat/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from hearthnet.services.chat.delivery import DeliveryManager
+from hearthnet.services.chat.service import ChatService
+from hearthnet.services.chat.views import ChatMessage, ChatView
+
+__all__ = ["ChatService", "ChatView", "ChatMessage", "DeliveryManager"]

hearthnet/services/chat/delivery.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import time
+
+
+class DeliveryManager:
+    """Decides direct vs store-and-forward delivery."""
+
+    def __init__(self, bus=None, our_node_id: str = ""):
+        self._bus = bus
+        self._our_node_id = our_node_id
+        self._queued: list[dict] = []  # store-and-forward queue
+
+    async def deliver(self, message: dict, recipient_node_id: str) -> str:
+        """Try direct delivery. Returns 'direct', 'queued', or 'self'."""
+        if recipient_node_id == self._our_node_id:
+            return "self"
+
+        if self._bus is not None:
+            try:
+                from hearthnet.bus.capability import RouteRequest
+                req = RouteRequest(
+                    capability="chat.send",
+                    version_req=(1, 0),
+                    body={"input": message},
+                    caller=self._our_node_id,
+                    trace_id="",
+                )
+                entry = self._bus.router.route(req)
+                if entry and entry.node_id == recipient_node_id and not entry.is_local:
+                    return "direct"
+            except Exception:
+                pass
+
+        # Store-and-forward
+        self._queued.append({
+            "message": message,
+            "to": recipient_node_id,
+            "queued_at": time.time(),
+        })
+        return "queued"
+
+    def get_queued(self, node_id: str) -> list[dict]:
+        return [q for q in self._queued if q["to"] == node_id]
+
+    def acknowledge(self, message_event_id: str) -> None:
+        self._queued = [
+            q for q in self._queued
+            if q["message"].get("event_id") != message_event_id
+        ]

hearthnet/services/chat/service.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
+from hearthnet.services.chat.delivery import DeliveryManager
+from hearthnet.services.chat.views import ChatView
+
+
+class ChatService:
+    name = "chat"
+    version = "1.0"
+
+    def __init__(self, node_id: str, event_log=None, bus=None) -> None:
+        self._node_id = node_id
+        self._event_log = event_log
+        self._view = ChatView(node_id)
+        self._delivery = DeliveryManager(bus=bus, our_node_id=node_id)
+        # Backward compat: in-memory messages list
+        self.messages: list[dict] = []
+
+    def capabilities(self) -> list[tuple]:
+        return [
+            (CapabilityDescriptor(name="chat.send", max_concurrent=8, idempotent=True), self.send, None),
+            (CapabilityDescriptor(name="chat.history", max_concurrent=8, idempotent=True), self.history, None),
+        ]
+
+    async def send(self, req: RouteRequest) -> dict:
+        payload = dict(req.body.get("input", {}))
+
+        if not payload.get("recipient") and not payload.get("to"):
+            return {"error": "bad_request", "message": "recipient required"}
+
+        recipient = payload.get("recipient") or payload.get("to", "")
+
+        if recipient == self._node_id:
+            return {"error": "bad_request", "message": "Cannot send to self"}
+
+        event_id = payload.get("event_id") or f"msg:{uuid.uuid4().hex}"
+        client_id = payload.get("client_id", event_id)
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        msg_payload = {
+            "to": recipient,
+            "body": payload.get("body", ""),
+            "attachments": payload.get("attachments", []),
+            "sent_at": now,
+            "client_id": client_id,
+        }
+
+        if self._event_log is not None:
+            try:
+                event = self._event_log.append_local(
+                    event_type="chat.message.sent",
+                    author=req.caller or self._node_id,
+                    payload=msg_payload,
+                )
+                self._view.apply(event)
+                delivered = await self._delivery.deliver(msg_payload, recipient)
+                return {
+                    "output": {
+                        "event_id": event.event_id,
+                        "lamport": event.lamport,
+                        "delivered": delivered,
+                    },
+                    "meta": {},
+                }
+            except Exception:
+                pass
+
+        # Demo / backward-compat mode
+        message = {
+            "event_id": event_id,
+            "from": req.caller or self._node_id,
+            "to": recipient,
+            "body": payload.get("body", ""),
+            "attachments": payload.get("attachments", []),
+        }
+        self.messages.append(message)
+        delivered = "direct" if recipient == self._node_id else "queued"
+        return {
+            "output": {
+                "event_id": event_id,
+                "lamport": len(self.messages),
+                "delivered": delivered,
+            },
+            "meta": {},
+        }
+
+    async def history(self, req: RouteRequest) -> dict:
+        peer = req.body.get("input", {}).get("peer")
+
+        if self._event_log is not None:
+            if peer:
+                msgs = [m.as_dict() for m in self._view.messages_with(peer)]
+            else:
+                msgs = [m.as_dict() for m in self._view.all_messages()]
+        else:
+            msgs = [
+                m for m in self.messages
+                if peer is None or m.get("from") == peer or m.get("to") == peer
+            ]
+
+        return {"output": {"messages": msgs}, "meta": {}}

hearthnet/services/chat/views.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ChatMessage:
+    event_id: str
+    from_node: str
+    to_node: str
+    body: str
+    attachments: list[dict]
+    sent_at: str
+    delivered_at: str | None
+    read_at: str | None
+    client_id: str
+
+    def as_dict(self) -> dict:
+        return {
+            "event_id": self.event_id,
+            "from": self.from_node,
+            "to": self.to_node,
+            "body": self.body,
+            "attachments": self.attachments,
+            "sent_at": self.sent_at,
+            "delivered_at": self.delivered_at,
+            "read_at": self.read_at,
+            "client_id": self.client_id,
+        }
+
+
+class ChatView:
+    """MaterialisedView from chat.message.* events."""
+
+    def __init__(self, our_node_id: str) -> None:
+        self._our_node_id = our_node_id
+        self._messages: dict[str, ChatMessage] = {}  # event_id -> ChatMessage
+        self._seen_client_ids: set[str] = set()
+
+    def apply(self, event) -> None:
+        etype = getattr(event, "event_type", None) or event.get("event_type", "")
+        payload = getattr(event, "payload", None) or event.get("payload", {})
+        event_id = getattr(event, "event_id", None) or event.get("event_id", "")
+        author = getattr(event, "author", None) or event.get("author", "")
+
+        if etype == "chat.message.sent":
+            client_id = payload.get("client_id", event_id)
+            if client_id in self._seen_client_ids:
+                return
+            self._seen_client_ids.add(client_id)
+            msg = ChatMessage(
+                event_id=event_id,
+                from_node=author,
+                to_node=payload.get("to", ""),
+                body=payload.get("body", ""),
+                attachments=payload.get("attachments", []),
+                sent_at=payload.get("sent_at", ""),
+                delivered_at=None,
+                read_at=None,
+                client_id=client_id,
+            )
+            self._messages[event_id] = msg
+
+        elif etype == "chat.message.delivered":
+            target_id = payload.get("target_event_id", "")
+            if target_id in self._messages:
+                old = self._messages[target_id]
+                self._messages[target_id] = ChatMessage(
+                    event_id=old.event_id,
+                    from_node=old.from_node,
+                    to_node=old.to_node,
+                    body=old.body,
+                    attachments=old.attachments,
+                    sent_at=old.sent_at,
+                    delivered_at=payload.get("delivered_at", ""),
+                    read_at=old.read_at,
+                    client_id=old.client_id,
+                )
+
+        elif etype == "chat.message.read":
+            target_id = payload.get("target_event_id", "")
+            if target_id in self._messages:
+                old = self._messages[target_id]
+                self._messages[target_id] = ChatMessage(
+                    event_id=old.event_id,
+                    from_node=old.from_node,
+                    to_node=old.to_node,
+                    body=old.body,
+                    attachments=old.attachments,
+                    sent_at=old.sent_at,
+                    delivered_at=old.delivered_at,
+                    read_at=payload.get("read_at", ""),
+                    client_id=old.client_id,
+                )
+
+    def messages_with(self, peer_node_id: str) -> list[ChatMessage]:
+        return [
+            m for m in self._messages.values()
+            if m.from_node == peer_node_id or m.to_node == peer_node_id
+        ]
+
+    def all_messages(self) -> list[ChatMessage]:
+        return sorted(self._messages.values(), key=lambda m: m.sent_at)
+
+    def unread_count(self, peer: str) -> int:
+        return sum(
+            1 for m in self._messages.values()
+            if m.to_node == self._our_node_id and m.from_node == peer and m.read_at is None
+        )
+
+    def snapshot_state(self) -> dict:
+        return {
+            "messages": {eid: m.as_dict() for eid, m in self._messages.items()},
+            "seen_client_ids": list(self._seen_client_ids),
+        }
+
+    def restore_state(self, state: dict) -> None:
+        self._messages = {}
+        for eid, md in state.get("messages", {}).items():
+            self._messages[eid] = ChatMessage(
+                event_id=md["event_id"],
+                from_node=md["from"],
+                to_node=md["to"],
+                body=md["body"],
+                attachments=md.get("attachments", []),
+                sent_at=md["sent_at"],
+                delivered_at=md.get("delivered_at"),
+                read_at=md.get("read_at"),
+                client_id=md.get("client_id", eid),
+            )
+        self._seen_client_ids = set(state.get("seen_client_ids", []))
+
+    def reset(self) -> None:
+        self._messages.clear()
+        self._seen_client_ids.clear()

hearthnet/services/embedding/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from hearthnet.services.embedding.backends import (
+    EmbeddingBackend,
+    SentenceTransformerBackend,
+    SimpleHashBackend,
+)
+from hearthnet.services.embedding.service import EmbeddingService
+
+__all__ = [
+    "EmbeddingBackend",
+    "SimpleHashBackend",
+    "SentenceTransformerBackend",
+    "EmbeddingService",
+]

hearthnet/services/embedding/backends.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class EmbeddingBackend(Protocol):
+    name: str
+    model: str
+    dim: int
+    max_input: int
+
+    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 SimpleHashBackend:
+    """Deterministic test backend using hash-based pseudo-embeddings. No ML deps."""
+
+    name = "simple"
+    model = "hash-16"
+    dim = 16
+    max_input = 8192
+
+    async def embed(self, texts: list[str], *, normalize: bool = True) -> list[list[float]]:
+        """Hash each text to a 16-dim float vector. Deterministic. For testing."""
+        import hashlib
+        import struct
+
+        result = []
+        for text in texts:
+            # SHA-512 yields 64 bytes → 16 × 4-byte floats
+            h = hashlib.sha512(text.encode()).digest()
+            vec = [struct.unpack_from("f", h, i)[0] for i in range(0, 64, 4)]
+            if normalize:
+                norm = sum(x**2 for x in vec) ** 0.5 or 1.0
+                vec = [x / norm for x in vec]
+            result.append(vec)
+        return result
+
+    async def warm(self) -> None:
+        pass
+
+    async def close(self) -> None:
+        pass
+
+    def health(self) -> dict:
+        return {"backend": "simple", "status": "ok"}
+
+
+class SentenceTransformerBackend:
+    """Local backend using sentence-transformers + torch."""
+
+    name = "sentence_transformers"
+
+    def __init__(self, model: str, device: str = "auto") -> None:
+        self.model = model
+        self.dim = 384  # default for bge-small
+        self.max_input = 8192
+        self._model = None
+        self._device = device
+
+    async def embed(self, texts: list[str], *, normalize: bool = True) -> list[list[float]]:
+        """Load model lazily on first embed call."""
+        if self._model is None:
+            await self.warm()
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._embed_sync, texts, normalize)
+
+    def _embed_sync(self, texts: list[str], normalize: bool) -> list[list[float]]:
+        embeddings = self._model.encode(
+            texts, normalize_embeddings=normalize, show_progress_bar=False
+        )
+        return [e.tolist() for e in embeddings]
+
+    async def warm(self) -> None:
+        """Load the model in a thread to avoid blocking event loop."""
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._load_model)
+
+    def _load_model(self) -> None:
+        try:
+            from sentence_transformers import SentenceTransformer
+
+            device = self._device
+            if device == "auto":
+                try:
+                    import torch
+
+                    device = "cuda" if torch.cuda.is_available() else "cpu"
+                except ImportError:
+                    device = "cpu"
+            self._model = SentenceTransformer(self.model, device=device)
+            self.dim = self._model.get_sentence_embedding_dimension() or 384
+        except ImportError as e:
+            raise RuntimeError(f"sentence-transformers not installed: {e}") from e
+
+    async def close(self) -> None:
+        pass
+
+    def health(self) -> dict:
+        return {
+            "backend": "sentence_transformers",
+            "model": self.model,
+            "loaded": self._model is not None,
+        }

hearthnet/services/embedding/service.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
+from hearthnet.constants import EMBED_MAX_CHARS, EMBED_MAX_TEXTS
+from hearthnet.services.embedding.backends import EmbeddingBackend, SimpleHashBackend
+
+
+class EmbeddingService:
+    name = "embedding"
+    version = "1.0"
+
+    def __init__(self, backend: EmbeddingBackend | None = None) -> None:
+        self._backend: EmbeddingBackend = backend or SimpleHashBackend()
+
+    def capabilities(self) -> list[tuple]:
+        descriptor = CapabilityDescriptor(
+            name="embed.text",
+            version=(1, 0),
+            stability="stable",
+            params={"model": self._backend.model, "dim": self._backend.dim},
+            max_concurrent=8,
+            trust_required="member",
+            timeout_seconds=30,
+            idempotent=True,
+        )
+        return [(descriptor, self.handle_embed, self._params_compatible)]
+
+    def _params_compatible(self, offered: dict, requested: dict) -> bool:
+        req_model = requested.get("model")
+        return not req_model or req_model == offered.get("model")
+
+    async def handle_embed(self, req: RouteRequest) -> dict:
+        inp = req.body.get("input", {})
+        texts = inp.get("texts", [])
+        normalize = inp.get("normalize", True)
+
+        if len(texts) > EMBED_MAX_TEXTS:
+            return {
+                "error": "bad_request",
+                "message": f"Too many texts (max {EMBED_MAX_TEXTS})",
+            }
+
+        for t in texts:
+            if len(t) > EMBED_MAX_CHARS:
+                return {
+                    "error": "bad_request",
+                    "message": f"Text too long (max {EMBED_MAX_CHARS} chars)",
+                }
+
+        if not texts:
+            return {
+                "output": {
+                    "embeddings": [],
+                    "model": self._backend.model,
+                    "dim": self._backend.dim,
+                },
+                "meta": {},
+            }
+
+        try:
+            embeddings = await self._backend.embed(texts, normalize=normalize)
+        except Exception as exc:
+            return {"error": "internal_error", "message": str(exc)}
+
+        return {
+            "output": {
+                "embeddings": embeddings,
+                "model": self._backend.model,
+                "dim": self._backend.dim,
+            },
+            "meta": {"count": len(embeddings)},
+        }

hearthnet/services/file/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from hearthnet.services.file.service import FileService
+
+__all__ = ["FileService"]

hearthnet/services/file/service.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from hearthnet.blobs.store import BlobStore
+from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
+
+
+class FileService:
+    name = "file"
+    version = "1.0"
+
+    def __init__(self, store: BlobStore) -> None:
+        self.store = store
+
+    def capabilities(self) -> list[tuple[Any, ...]]:
+        return [
+            (
+                CapabilityDescriptor(
+                    name="file.read",
+                    params={},
+                    trust_required="member",
+                    max_concurrent=8,
+                ),
+                self.handle_read,
+                None,
+            ),
+            (
+                CapabilityDescriptor(
+                    name="file.list",
+                    params={},
+                    trust_required="member",
+                    max_concurrent=8,
+                ),
+                self.handle_list,
+                None,
+            ),
+            (
+                CapabilityDescriptor(
+                    name="file.advertise",
+                    params={},
+                    trust_required="member",
+                    max_concurrent=4,
+                ),
+                self.handle_advertise,
+                None,
+            ),
+            (
+                CapabilityDescriptor(
+                    name="file.put",
+                    params={},
+                    trust_required="trusted",
+                    max_concurrent=2,
+                    timeout_seconds=600,
+                ),
+                self.handle_put,
+                None,
+            ),
+        ]
+
+    async def handle_read(self, req: RouteRequest) -> dict[str, Any]:
+        """input: {cid: str} → output: {cid, size_bytes, filename, chunks: [...]}"""
+        cid = req.body.get("input", {}).get("cid", "")
+        if not self.store.has(cid):
+            return {"error": "not_found", "message": f"Blob {cid} not found"}
+        manifest = self.store.get_manifest(cid)
+        return {
+            "output": {
+                "cid": manifest.cid,
+                "size_bytes": manifest.size_bytes,
+                "filename": manifest.filename,
+                "chunks": [
+                    {"index": c.index, "cid": c.cid, "size_bytes": c.size_bytes}
+                    for c in manifest.chunks
+                ],
+            },
+            "meta": {},
+        }
+
+    async def handle_list(self, req: RouteRequest) -> dict[str, Any]:
+        blobs = self.store.list_blobs()
+        return {
+            "output": {
+                "blobs": [
+                    {"cid": b.cid, "size_bytes": b.size_bytes, "filename": b.filename}
+                    for b in blobs
+                ]
+            },
+            "meta": {},
+        }
+
+    async def handle_advertise(self, req: RouteRequest) -> dict[str, Any]:
+        """input: {cid, filename, size_bytes} → acknowledge, actual transfer is separate"""
+        inp = req.body.get("input", {})
+        return {"output": {"acknowledged": True, "cid": inp.get("cid")}, "meta": {}}
+
+    async def handle_put(self, req: RouteRequest) -> dict[str, Any]:
+        """input: {data_b64: str, filename: str} → store blob → output: {cid, size_bytes}"""
+        inp = req.body.get("input", {})
+        data_b64 = inp.get("data_b64", "")
+        filename = inp.get("filename")
+        try:
+            data = base64.b64decode(data_b64)
+        except Exception:
+            return {"error": "bad_request", "message": "Invalid base64 data"}
+        manifest = self.store.put(data, filename=filename)
+        return {"output": {"cid": manifest.cid, "size_bytes": manifest.size_bytes}, "meta": {}}

hearthnet/services/llm/__init__.py

@@ -0,0 +1,3 @@
+from hearthnet.services.llm.service import LlmService
+
+__all__ = ["LlmService"]

hearthnet/services/llm/backends/__init__.py

@@ -0,0 +1 @@
+from hearthnet.services.llm.backends.base import *

hearthnet/services/llm/backends/base.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Protocol
+
+
+@dataclass(frozen=True)
+class Token:
+    text: str
+    logprob: float = 0.0
+    stop: bool = False
+
+
+@dataclass(frozen=True)
+class ChatResult:
+    text: str
+    tokens_in: int
+    tokens_out: int
+    model: str
+    ms: int
+    stop_reason: str = "stop"
+
+
+@dataclass(frozen=True)
+class BackendModel:
+    name: str
+    family: str  # "llama", "qwen", "mistral", etc.
+    context_length: int
+    requires_internet: bool
+
+
+class LlmBackend(Protocol):
+    name: str
+    models: list[BackendModel]
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str,
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> ChatResult | AsyncIterator[Token]: ...
+
+    async def complete(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> ChatResult | AsyncIterator[Token]: ...
+
+    async def warm(self) -> None: ...
+    async def close(self) -> None: ...
+    def health(self) -> dict: ...
+    def is_available(self) -> bool: ...

hearthnet/services/llm/backends/hf_local.py

@@ -0,0 +1,118 @@
+"""Local HuggingFace Transformers backend."""
+from __future__ import annotations
+
+from hearthnet.services.llm.backends.base import BackendModel, ChatResult
+from hearthnet.services.llm.tokenizers import model_family
+
+
+def _family(model_name: str) -> str:
+    return model_family(model_name)
+
+
+class HfLocalBackend:
+    name = "hf_local"
+
+    def __init__(
+        self, model: str = "microsoft/DialoGPT-small", device: str = "auto"
+    ) -> None:
+        self._model_name = model
+        self._device = device
+        self._pipeline = None
+        self.models = [
+            BackendModel(
+                name=model,
+                family=_family(model),
+                context_length=2048,
+                requires_internet=False,
+            )
+        ]
+
+    def is_available(self) -> bool:
+        try:
+            import transformers
+
+            return True
+        except ImportError:
+            return False
+
+    async def warm(self) -> None:
+        if not self.is_available():
+            return
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._load)
+
+    def _load(self) -> None:
+        from transformers import pipeline
+
+        device = 0 if self._device == "cuda" else -1
+        if self._device == "auto":
+            try:
+                import torch
+
+                device = 0 if torch.cuda.is_available() else -1
+            except ImportError:
+                device = -1
+        self._pipeline = pipeline(
+            "text-generation", model=self._model_name, device=device
+        )
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str = "",
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 256,
+        **kwargs,
+    ):
+        import asyncio
+        import time
+
+        if self._pipeline is None:
+            await self.warm()
+        if self._pipeline is None:
+            raise RuntimeError("HF model not loaded")
+        t0 = time.monotonic()
+        prompt = (
+            "\n".join(f"{m['role']}: {m['content']}" for m in messages) + "\nassistant:"
+        )
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None,
+            lambda: self._pipeline(
+                prompt,
+                max_new_tokens=max_tokens,
+                temperature=temperature,
+                do_sample=True,
+                return_full_text=False,
+            ),
+        )
+        text = result[0]["generated_text"] if result else ""
+        ms = int((time.monotonic() - t0) * 1000)
+        return ChatResult(
+            text=text,
+            tokens_in=len(prompt.split()),
+            tokens_out=len(text.split()),
+            model=self._model_name,
+            ms=ms,
+        )
+
+    async def complete(
+        self, prompt: str, *, model: str = "", stream: bool = False, **kwargs
+    ):
+        return await self.chat(
+            [{"role": "user", "content": prompt}], model=model, stream=stream, **kwargs
+        )
+
+    async def close(self) -> None:
+        self._pipeline = None
+
+    def health(self) -> dict:
+        return {
+            "backend": "hf_local",
+            "model": self._model_name,
+            "loaded": self._pipeline is not None,
+        }

hearthnet/services/llm/backends/llama_cpp.py

@@ -0,0 +1,134 @@
+"""llama-cpp-python in-process backend."""
+from __future__ import annotations
+
+from hearthnet.services.llm.backends.base import BackendModel, ChatResult, Token
+from hearthnet.services.llm.tokenizers import model_family
+
+
+def _family(model_name: str) -> str:
+    return model_family(model_name)
+
+
+class LlamaCppBackend:
+    name = "llama_cpp"
+
+    def __init__(
+        self, model_path: str, n_ctx: int = 4096, n_gpu_layers: int = -1
+    ) -> None:
+        self._model_path = model_path
+        self._n_ctx = n_ctx
+        self._n_gpu_layers = n_gpu_layers
+        self._llm = None
+        model_name = model_path.split("/")[-1].split(".")[0]
+        self.models = [
+            BackendModel(
+                name=model_name,
+                family=_family(model_name),
+                context_length=n_ctx,
+                requires_internet=False,
+            )
+        ]
+
+    def is_available(self) -> bool:
+        try:
+            from pathlib import Path
+
+            import llama_cpp
+
+            return Path(self._model_path).exists()
+        except ImportError:
+            return False
+
+    async def warm(self) -> None:
+        if not self.is_available():
+            return
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._load_model)
+
+    def _load_model(self) -> None:
+        from llama_cpp import Llama
+
+        self._llm = Llama(
+            model_path=self._model_path,
+            n_ctx=self._n_ctx,
+            n_gpu_layers=self._n_gpu_layers,
+            verbose=False,
+        )
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str = "",
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs,
+    ):
+        import asyncio
+        import time
+
+        if self._llm is None:
+            await self.warm()
+        if self._llm is None:
+            raise RuntimeError("llama.cpp model not loaded")
+        t0 = time.monotonic()
+        loop = asyncio.get_event_loop()
+        if not stream:
+            result = await loop.run_in_executor(
+                None,
+                lambda: self._llm.create_chat_completion(
+                    messages=messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                ),
+            )
+            text = result["choices"][0]["message"]["content"]
+            ms = int((time.monotonic() - t0) * 1000)
+            return ChatResult(
+                text=text,
+                tokens_in=result["usage"]["prompt_tokens"],
+                tokens_out=result["usage"]["completion_tokens"],
+                model=self.models[0].name,
+                ms=ms,
+            )
+        else:
+            return self._stream_chat(messages, temperature, max_tokens)
+
+    async def _stream_chat(self, messages, temperature, max_tokens):
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None,
+            lambda: self._llm.create_chat_completion(
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                stream=True,
+            ),
+        )
+        for chunk in result:
+            delta = chunk["choices"][0].get("delta", {})
+            text = delta.get("content", "")
+            done = chunk["choices"][0]["finish_reason"] is not None
+            if text or done:
+                yield Token(text=text, stop=done)
+
+    async def complete(
+        self, prompt: str, *, model: str = "", stream: bool = False, **kwargs
+    ):
+        messages = [{"role": "user", "content": prompt}]
+        return await self.chat(messages, model=model, stream=stream, **kwargs)
+
+    async def close(self) -> None:
+        self._llm = None
+
+    def health(self) -> dict:
+        return {
+            "backend": "llama_cpp",
+            "model_path": self._model_path,
+            "loaded": self._llm is not None,
+        }

hearthnet/services/llm/backends/ollama.py

@@ -0,0 +1,127 @@
+"""Ollama HTTP backend: http://localhost:11434"""
+from __future__ import annotations
+
+from hearthnet.services.llm.backends.base import BackendModel, ChatResult, Token
+from hearthnet.services.llm.tokenizers import model_family
+
+
+def _family(model_name: str) -> str:
+    return model_family(model_name)
+
+
+class OllamaBackend:
+    name = "ollama"
+
+    def __init__(self, base_url: str = "http://localhost:11434", default_model: str = "") -> None:
+        self._base_url = base_url.rstrip("/")
+        self._default_model = default_model
+        self.models: list[BackendModel] = []
+
+    def is_available(self) -> bool:
+        try:
+            import httpx
+
+            resp = httpx.get(f"{self._base_url}/api/tags", timeout=3.0)
+            return resp.status_code == 200
+        except Exception:
+            return False
+
+    async def _list_models(self) -> list[str]:
+        try:
+            import httpx
+
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"{self._base_url}/api/tags", timeout=5.0)
+                data = resp.json()
+                return [m["name"] for m in data.get("models", [])]
+        except Exception:
+            return []
+
+    async def warm(self) -> None:
+        model_names = await self._list_models()
+        self.models = [
+            BackendModel(
+                name=m,
+                family=_family(m),
+                context_length=4096,
+                requires_internet=False,
+            )
+            for m in model_names
+        ]
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str,
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs,
+    ):
+        import time
+
+        import httpx
+
+        model = model or self._default_model
+        t0 = time.monotonic()
+
+        payload = {
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+            "options": {"temperature": temperature, "num_predict": max_tokens},
+        }
+
+        if not stream:
+            async with httpx.AsyncClient(timeout=120.0) as client:
+                resp = await client.post(f"{self._base_url}/api/chat", json=payload)
+                resp.raise_for_status()
+                data = resp.json()
+                text = data.get("message", {}).get("content", "")
+                ms = int((time.monotonic() - t0) * 1000)
+                return ChatResult(
+                    text=text,
+                    tokens_in=0,
+                    tokens_out=len(text.split()),
+                    model=model,
+                    ms=ms,
+                )
+        else:
+            return self._stream_chat(payload, t0)
+
+    async def _stream_chat(self, payload: dict, t0: float):
+        import json
+
+        import httpx
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            async with client.stream(
+                "POST", f"{self._base_url}/api/chat", json=payload
+            ) as resp:
+                async for line in resp.aiter_lines():
+                    if line:
+                        try:
+                            data = json.loads(line)
+                            text = data.get("message", {}).get("content", "")
+                            done = data.get("done", False)
+                            if text:
+                                yield Token(text=text, stop=done)
+                        except json.JSONDecodeError:
+                            pass
+
+    async def complete(
+        self, prompt: str, *, model: str, stream: bool = False, **kwargs
+    ):
+        messages = [{"role": "user", "content": prompt}]
+        return await self.chat(messages, model=model, stream=stream, **kwargs)
+
+    async def close(self) -> None:
+        pass
+
+    def health(self) -> dict:
+        return {
+            "backend": "ollama",
+            "available": self.is_available(),
+            "url": self._base_url,
+        }

hearthnet/services/llm/backends/openai_compat.py

@@ -0,0 +1,145 @@
+"""OpenAI-compatible HTTP backend. ONLINE ONLY — opt-in fallback."""
+from __future__ import annotations
+
+from hearthnet.services.llm.backends.base import BackendModel, ChatResult, Token
+from hearthnet.services.llm.tokenizers import model_family
+
+
+def _family(model_name: str) -> str:
+    return model_family(model_name)
+
+
+class OpenAICompatBackend:
+    """OpenAI-compatible HTTP backend. Only used when explicitly configured AND online.
+    Never the default local path."""
+
+    name = "openai_compat"
+
+    def __init__(
+        self,
+        base_url: str = "https://api.openai.com/v1",
+        api_key_env: str = "OPENAI_API_KEY",
+        model: str = "gpt-3.5-turbo",
+    ) -> None:
+        self._base_url = base_url
+        self._api_key_env = api_key_env
+        self._model = model
+        self.models = [
+            BackendModel(
+                name=model,
+                family="gpt",
+                context_length=16385,
+                requires_internet=True,
+            )
+        ]
+
+    def _get_key(self) -> str:
+        import os
+
+        key = os.environ.get(self._api_key_env, "")
+        if not key:
+            raise RuntimeError(f"API key env {self._api_key_env} not set")
+        return key
+
+    def is_available(self) -> bool:
+        import os
+
+        return bool(os.environ.get(self._api_key_env))
+
+    async def warm(self) -> None:
+        pass
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str = "",
+        stream: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs,
+    ):
+        import time
+
+        import httpx
+
+        model = model or self._model
+        t0 = time.monotonic()
+        payload = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "stream": stream,
+        }
+        headers = {
+            "Authorization": f"Bearer {self._get_key()}",
+            "Content-Type": "application/json",
+        }
+
+        if not stream:
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                resp = await client.post(
+                    f"{self._base_url}/chat/completions",
+                    json=payload,
+                    headers=headers,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                text = data["choices"][0]["message"]["content"]
+                ms = int((time.monotonic() - t0) * 1000)
+                usage = data.get("usage", {})
+                return ChatResult(
+                    text=text,
+                    tokens_in=usage.get("prompt_tokens", 0),
+                    tokens_out=usage.get("completion_tokens", 0),
+                    model=model,
+                    ms=ms,
+                )
+        else:
+            return self._stream_chat(payload, headers, model, t0)
+
+    async def _stream_chat(self, payload, headers, model, t0):
+        import json
+
+        import httpx
+
+        payload["stream"] = True
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            async with client.stream(
+                "POST",
+                f"{self._base_url}/chat/completions",
+                json=payload,
+                headers=headers,
+            ) as resp:
+                async for line in resp.aiter_lines():
+                    if line.startswith("data: "):
+                        raw = line[6:]
+                        if raw == "[DONE]":
+                            yield Token(text="", stop=True)
+                            return
+                        try:
+                            data = json.loads(raw)
+                            delta = data["choices"][0].get("delta", {})
+                            text = delta.get("content", "")
+                            if text:
+                                yield Token(text=text, stop=False)
+                        except Exception:
+                            pass
+
+    async def complete(
+        self, prompt: str, *, model: str = "", stream: bool = False, **kwargs
+    ):
+        return await self.chat(
+            [{"role": "user", "content": prompt}], model=model, stream=stream, **kwargs
+        )
+
+    async def close(self) -> None:
+        pass
+
+    def health(self) -> dict:
+        return {
+            "backend": "openai_compat",
+            "available": self.is_available(),
+            "url": self._base_url,
+        }