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.