3. Hearth

State

Partial. The wire spec is public (slash-builder/hearth; code Apache-2.0, spec CC-BY-4.0). The v0 subset (sessions, pub/sub, presence digest) is implemented in the hub, Fabric Kit and Message Kit. Sealed payloads (levels E0 and E1) are live in Courier. The Hearth conformance suite does not exist. The .proto package is still named quickring.v1, and the spec's status header is out of date (see Known problems).

Hearth is the wire contract between nodes. It is tier-agnostic and sells nothing: SlashBuilder stewards it as a peer project alongside BenixOS, and Quickring is the commercial layer built on it. BenixOS depends on Hearth; Hearth never depends on BenixOS.

Design discipline

Borrowed from Plan 9's 9P, in discipline rather than encoding:

T, R, D

Prefix Direction Semantics
T client to server A request. Carries a tag. The server must answer with exactly one matching R or RError.
R server to client The response, with the same tag.
D server to client An unsolicited push. tag = 0. The client does not reply.

"There is no fourth category."

Two layers

Layer Covers Implemented by
Base The envelope, tag correlation, the T/R/D grammar, RError, the addressing model Message Kit, on the device and in any client's transport core
Fabric Sessions, networked pub/sub, pairing, presence, offline catch-up, E2E encryption, the feed convention The hub (the Quickring daemon), and Fabric Kit as the client SDK

A message is one envelope end to end. Crossing the box boundary swaps only the transport: AF_UNIX SOCK_SEQPACKET on the device, WebSocket to the hub. The Quickring daemon registers with Message Kit's router as the remote-transport provider (ADR-0002, 5 June 2026).

Transport (hub)

Session lifecycle

  1. Version negotiation.
  2. Hello: authentication.
  3. Ready.
  4. Heartbeats keep it alive.

What the protocol covers

Area Content
Topics Naming convention; subscribe, unsubscribe, publish; DDeliver pushes the message to subscribers
Presence DPresence is advisory; DSessionRevoked ends a session
Offline catch-up A device that was away reads what it missed
Device pairing TPair/RPair, a pairing attestation, a displayed fingerprint, a conformance vector
Roster A device can read the household's roster, and a reader must verify the attestations in a fixed order
Sealing and E2E Sealed payloads and a capability-grant model; the design is in encryption.md
Errors, rate limits, versioning RError taxonomy; abuse limits; the break and major-bump rules

What the hub can and cannot do to the roster. The spec states this boundary itself.

Withholding and staleness are denial, not substitution. The spec names the missing piece, a transparency log, and leaves it out of v1.

How BenixOS uses Hearth

The node contract adds exactly one Hearth clause (§9): a node MUST speak Hearth v1, prove possession of its device key, verify the roster, and pass the conformance suite.

None of the node messages are built

Sealing of machine frames is not built (publish_encrypted is absent from the gateway). The Venue executor in the compose bundle talks plain HTTP to venued on loopback or an internal Docker network. Node-contract §9 is Draft.

The hub and local mode

The hub is the OSS reference server, operated by Quickring. Its local mode (_hearth._tcp discovery, roster cache, a listener so a household works with the WAN cut) is Planned: only the mDNS piece shipped, inside the gateway. The 2 November 2026 plan rehomes it to the hub binary. Milestone M5 ("works with the internet down") depends on it.

Known problems

Next

4. Kits