docs/GLOSSARY.md

# HearthNet Glossary

Canonical names. Every spec uses these. Do not introduce synonyms.

---

## Identifiers

| Term | Form | Notes |
|------|------|-------|
| **NodeID** | `ed25519:XXXX-XXXX-XXXX-XXXX` | First 8 bytes of Ed25519 public key, base32, grouped by 4 |
| **NodeID (full)** | `ed25519:<base64-url-nopad>` of full pubkey | Used only in manifests; never displayed to users |
| **CommunityID** | `ed25519:<...>` of community root pubkey | Same format as full NodeID |
| **CapabilityName** | dotted lowercase: `llm.chat`, `rag.query` | Namespace allocation: see CONTRACT §3.1 |
| **Version** | `(major, minor)` tuple — wire form `"1.0"` | Patch component does not exist on the wire |
| **SchemaHash** | `blake3:<hex>` | BLAKE3 of canonical-JSON of capability schema |
| **CID** | `blake3:<hex>` | Content identifier for blobs |
| **EventID** | ULID (26 chars, monotonic, encodes wall-clock) | Globally unique per community in practice |
| **TraceID** | ULID | Identifies one logical request across hops |
| **Signature** | `ed25519:<base64-url-nopad>` | Always over canonical-JSON |
| **WallClock** | RFC 3339 UTC: `2026-05-26T08:14:22Z` | Display-only; never used for ordering |
| **Lamport** | `int >= 0` | Per-community monotonic logical counter |
| **Topic** | dotted lowercase: `marketplace.post.created` | Pub-sub topic name |

---

## Concepts

| Term | Definition |
|------|------------|
| **Anchor** | A node profile: always-on, GPU-equipped, primary capability provider |
| **Hearth** | A node profile: mid-tier, typically a laptop, runs some services |
| **Spark** | A node profile: thin client (Pi, mobile, browser); consumes capabilities |
| **Bridge** | A node profile: relay-only, no inference, federates communities (Phase 2) |
| **Profile** | One of `anchor` / `hearth` / `spark` / `bridge` — declared in node manifest |
| **Community** | A trust root: a group of nodes sharing one root key and one event log |
| **Federation** | Cross-community trust + capability access (Phase 2) |
| **Capability** | A named, versioned, schema-bound RPC offered by a node |
| **Capability descriptor** | The metadata for one capability: name, version, schema, params, guarantees |
| **Capability entry** | The bus's local record of one remote capability: descriptor + health |
| **Bus / capability bus** | The L3 routing component each service registers with |
| **Service** | An L4 module that provides one or more capabilities |
| **Node manifest** | A signed JSON document describing what a node is and offers; expires every 30s |
| **Community manifest** | A signed JSON document describing community membership and policy |
| **Event** | A signed, Lamport-stamped record in the community's append-only log |
| **Event log** | The community's full ordered history; one SQLite db per node |
| **Snapshot** | A signed materialised state at some Lamport |
| **Materialised view** | A derived index built by replaying events (member list, marketplace, etc.) |
| **Blob** | An immutable byte string identified by its CID |
| **Chunk** | A 256KB slice of a blob, itself CID-addressed |
| **TrustLevel** | One of `unknown` / `member` / `trusted` / `anchor` |
| **Stability** | One of `experimental` / `beta` / `stable` for a capability |
| **Emergency mode** | UI + behavioural state when the internet-detector reports offline |

---

## Errors (closed set — see CONTRACT §9)

| Code | Meaning |
|------|---------|
| `not_found` | No node offers the requested capability, or the requested resource is gone |
| `capacity_exceeded` | Node is at declared `max_concurrent`; retry with backoff or pick another |
| `schema_mismatch` | Request body does not match the declared schema for this capability/version |
| `unauthorized` | Caller is not a community member, or lacks the required trust level |
| `revoked` | Caller's NodeID is in the revoked set of the community |
| `internal_error` | Service crashed handling this request |
| `not_implemented` | Capability is declared but the handler is a stub |
| `timeout` | Operation exceeded its declared deadline |
| `partition` | Remote node is presumed unreachable (mDNS lost, repeated failures) |
| `invalid_signature` | Signature verification failed on a manifest, event, or request |
| `expired` | Manifest, token, or event TTL has passed |
| `rate_limited` | Caller exceeded the per-peer-per-capability rate budget |
| `bad_request` | Malformed JSON, missing required field, etc. |

---

## File paths (XDG-style; resolved via `platformdirs`)

| Path | Purpose |
|------|---------|
| `<DATA>/keys/device.ed25519` | Private key, 0600 |
| `<DATA>/keys/device.pub` | Public key |
| `<DATA>/communities/<community_id>/manifest.json` | Latest signed community manifest |
| `<DATA>/communities/<community_id>/events.sqlite` | Event log |
| `<DATA>/communities/<community_id>/snapshots/<lamport>.bin` | Signed snapshots |
| `<DATA>/blobs/<aa>/<bb...>` | CID-addressed blobs |
| `<CONFIG>/config.toml` | User configuration |
| `<CACHE>/embeddings/<corpus>` | Vector store on-disk files |
| `<LOG>/<date>.log` | Daily rotating logs |

`<DATA>` = `platformdirs.user_data_dir("hearthnet")` (Linux: `~/.local/share/hearthnet/`).

---

## Default ports

| Port | Purpose | Configurable? |
|------|---------|---------------|
| 7080 | Bus HTTP server | yes (`config.transport.port`) |
| 7860 | Gradio UI | yes (`config.ui.port`) |
| 42424 | UDP discovery multicast | no (interop) |
| 5353 | mDNS | no (system) |

---

## Defaults (numeric — central reference)

| Constant | Value | Where defined |
|----------|-------|---------------|
| `MANIFEST_TTL_SECONDS` | 30 | M01 |
| `MANIFEST_REPUBLISH_INTERVAL_SECONDS` | 20 | M01 |
| `DISCOVERY_UDP_INTERVAL_SECONDS` | 5 (active) / 30 (stable) | M02 |
| `EMERGENCY_PROBE_INTERVAL_SECONDS` | 10 (online) / 2 (offline) | M09 |
| `EMERGENCY_PROBE_TIMEOUT_SECONDS` | 2 | M09 |
| `EMERGENCY_TRANSITION_DEBOUNCE_SECONDS` | 30 | M09 |
| `CONNECTION_IDLE_SECONDS` | 60 | X01 |
| `RECONNECT_BACKOFF_CAP_SECONDS` | 30 | X01 |
| `STREAM_WINDOW_FRAMES` | 16 | X01 |
| `STREAM_ACK_INTERVAL_FRAMES` | 8 | X01 |
| `STREAM_ACK_TIMEOUT_SECONDS` | 5 | X01 |
| `RPC_DEFAULT_TIMEOUT_SECONDS` | 30 | X01 |
| `LLM_GENERATION_DEFAULT_TIMEOUT_SECONDS` | 120 | M04 |
| `CHUNK_SIZE_BYTES` | 262144 (256 KiB) | M07 |
| `BLOB_GC_DISK_THRESHOLD` | 0.80 | M07 |
| `RAG_CHUNK_TOKENS` | 1000 | M05 |
| `RAG_CHUNK_OVERLAP_TOKENS` | 200 | M05 |
| `RAG_DEFAULT_K` | 5 | M05 |
| `RAG_MAX_K` | 20 | M05 |
| `HEALTH_WINDOW_CALLS` | 100 | M03 |
| `HEALTH_QUARANTINE_THRESHOLD` | 0.5 | M03 |
| `HEALTH_QUARANTINE_SECONDS` | 60 | M03 |
| `RATE_LIMIT_SOFT_RPS_PER_CAP` | 10 | X01 |
| `RATE_LIMIT_HARD_RPS_PER_CAP` | 100 | X01 |
| `RATE_LIMIT_SOFT_RPS_TOTAL` | 100 | X01 |
| `RATE_LIMIT_HARD_RPS_TOTAL` | 1000 | X01 |
| `EVENT_LOG_RETENTION_DAYS` | 30 | X02 |
| `SNAPSHOT_LAG_LAMPORT` | 1000 | X02 |
| `TRACE_RING_BUFFER` | 10000 | X03 |
| `LOG_RETENTION_DAYS` | 14 | X03 |

Implementation hint: put these in `hearthnet/constants.py` and import everywhere. Do not hardcode in modules.