From 5b54ed87a9778e4261f0c7240e513726c06cddb0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 21:12:47 +1200
Subject: [PATCH 01/11] plan: grove

---
 docs/plans/grove.md | 244 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 244 insertions(+)
 create mode 100644 docs/plans/grove.md

diff --git a/docs/plans/grove.md b/docs/plans/grove.md
new file mode 100644
index 00000000..75a1fb1c
--- /dev/null
+++ b/docs/plans/grove.md
@@ -0,0 +1,244 @@
+# Grove (v0)
+
+## Context
+
+A "grove" is a group of seedling nodes — one leader, N followers — sharing a small set of leader-published settings. Every grove member eventually receives the leader's signed state, gossiped peer-to-peer over a new ALPN; no RAFT, no quorum, eventually consistent.
+
+This v0 ships the smallest useful slice: the leader publishes typed **grove params** (name → value) inside a signed payload; each follower can independently map any local app param to a grove param, so when the grove value changes (or a mapping is created) the app param is updated through the same pathway as an operator `set_param`, firing `on_change`. While a mapping exists, manual local set/unset of that app param is rejected.
+
+Out of scope for v0, but design must not foreclose:
+- Replicating whole app definitions/configurations (incl. backup-app pattern from the original ask).
+- Secret grove params with envelope encryption to per-member pubkeys.
+
+Explicitly rejected (do not architect extension points for these; the design space is closed, not deferred):
+- **Multi-grove membership per node.** The data model is single-row by design.
+- **Grove-wide leader election / RAFT / failover.** No quorum, no election. If RAFT enters the picture later, the user's stated direction is that it would live *inside* a leadership group within a grove node, not span the whole grove — which is a different feature, not a generalisation of this one. v0 leader loss is a documented limitation with an out-of-band recovery path (see "Documented v0 limitations" below).
+
+User-confirmed decisions:
+- One grove per node.
+- Reject local set on grove-mapped app params.
+- Reuse the existing OI Ed25519 identity (`data_dir/oi.key`) as the leader's signing key. New nodes can be onboarded via *any* current member; the leader fingerprint is supplied out-of-band so the joiner can verify the signature without having to talk to the leader directly.
+- Spec lives at `docs/spec/grove.md` with a new `g[...]` namespace, registered in `.config/tracey/config.styx`.
+- Common transport considerations (RPK TLS, fingerprint pinning, ALPN as hard-version-wall, JSON-line framing, abort semantics) are extracted into a new shared `docs/spec/transport.md` with a `t[...]` namespace, referenced from both `docs/spec/interface.md` (`bes.seedling/1`) and `docs/spec/grove.md` (`bes.grove/1`). Avoids duplicating the same prose across protocols and pre-pays the cost for any future ALPN.
+
+## Architecture
+
+### Code structure — extract a `transport` module first
+
+The code structure mirrors the spec split. Today `crates/core/src/oi/` holds both transport primitives (quinn endpoint construction, RPK TLS verifier, `TrustedKeys`, ALPN dispatch, JSON-line framing, per-connection state, fingerprint extraction) and OI-specific behaviour (port-forward, log streaming, event subscription, OI handlers). Grove would otherwise duplicate the transport half.
+
+Refactor (lands before any grove-specific code):
+- New `crates/core/src/transport/` module with `endpoint.rs` (quinn endpoint, listen + accept loop, ALPN-keyed handler registry), `auth.rs` (protocol-scoped trust sets — `OperatorTrust` and a registry of additional sets keyed by ALPN — and a verifier that consults the set matching the negotiated ALPN), `connection.rs` (per-connection registry, fingerprint extraction, abort frame), `framing.rs` (JSON-line read/write helpers, currently inline in `oi/server.rs`).
+- Stays in `crates/core` rather than promoting to a new `crates/transport` crate for v0; promotion is a follow-up if multiple crates ever need server-side transport. The wire-type half (ALPN constants, dial-side `OiClient`, identity keys) remains in `crates/protocol/`.
+- ALPN handlers register with `transport` on startup: OI registers `bes.seedling/1`, grove registers `bes.grove/1`. The existing `oi/server.rs::handle_connection` body splits — generic per-connection logic moves to `transport`, OI-specific stream dispatch stays in `oi/`.
+
+`OiState` splits along the same seam:
+- New `TransportState`: endpoint handle, connection registry, identity, protocol trust registry. Owned by a top-level `Daemon` struct (renamed/replacing the current top-level container that wires everything up).
+- `OiState` (slimmed): OI-specific session/handler state — port-forward maps, log subscribers, event broadcasters.
+- New `GroveState`: publish mutex, dial-loop handle, dirty-mappings set, signed-payload cache.
+- `Daemon` holds `TransportState` + `OiState` + `GroveState`. Handlers receive only what they need (operator handlers don't see grove state, grove handlers don't see OI session state).
+
+This refactor is pure restructuring — no behavioural change, OI tests stay green. It lands as commit 0 (split into 0a/0b if the diff is large; see phasing).
+
+### Wire protocol — `bes.grove/1`
+
+- New ALPN constant `GROVE_ALPN = b"bes.grove/1"` in `crates/protocol/src/lib.rs`.
+- Registered with the `transport` module's ALPN handler registry (see "Code structure" below). The transport endpoint advertises both `bes.seedling/1` and `bes.grove/1`; on accept, the negotiated ALPN selects the registered handler. No second port.
+- Trust-set is protocol-scoped (see "Trust-set reconciliation" below). The verifier consults `OperatorTrust` for `bes.seedling/1` and `GroveTrust` for `bes.grove/1`; a key authorised for both must be in both sets.
+- Transport tuning is shared; the existing 10s keepalive / 30s idle is acceptable for grove gossip.
+
+JSON-line framed bidi stream, using the framing helpers in `transport/framing.rs` (extracted in commit 0 from the existing `oi/server.rs::handle_bidi_stream` shape).
+
+Messages:
+- `hello`: `{type, grove_id, our_seq, our_payload_hash, our_role, our_fingerprint, protocol_version, nonce}`. `protocol_version` is independent of the ALPN (ALPN = hard wall, in-payload version = soft feature flag). `our_payload_hash` is sha-256 of the canonical signed bytes; same seq + different hash → fork → drop + emit `grove.payload-rejected`. Mismatched `grove_id` or unexpected leader → drop.
+- `version`: `{type, payload, signature}`. Sender is whoever holds higher seq. Receiver validates signature against its pinned `leader_fingerprint`, requires strict `seq` increase, and bounds the message at 256 KiB on `recv.read_to_end`. Lower bound is "smaller than OI's 4 MiB" — grove payloads stay tiny in v0. Leader publish path **pre-checks** the canonicalised payload size before signing; if `grove invite`, `grove revoke`, or `grove param set` would push the next payload over the cap (e.g. ≥ 240 KiB to leave headroom), the OI handler / CLI / web returns a structured error (`grove.publish-rejected { reason: "payload_too_large", current_bytes, cap_bytes }`) without bumping seq or persisting. Operators get the feedback at the point of mutation, not via a peer's `abort` after-the-fact.
+- `peers`: `{type, entries: [{fingerprint, addresses, last_seen}]}`. Address-hint gossip only — *not* membership. On receive: filter to `members` from latest signed payload (drop entries from non-members), cap entries (e.g. 64) and addresses-per-entry (e.g. 4), treat peer-supplied `last_seen` as a tie-breaker, never as authoritative liveness.
+- `abort`: `{type, reason}` where `reason ∈ {grove_mismatch, signature_invalid, seq_regression, leader_mismatch, version_too_old, payload_too_large, ...}`. Sent before close on protocol-level rejection so the operator gets a non-network reason via the event surface.
+
+Full-state-only for v0; revisit deltas when payloads might exceed a few MiB (i.e. when app definitions are replicated).
+
+### Signed payload
+
+Ed25519 signature over **JSON canonicalised with `serde_jcs`** (RFC 8785). JSON is idiomatic in this repo (used by OI, events, CLI), and a canonical JSON form keeps the schema flexible for an early-stage feature — adding or reordering fields in v1 doesn't break the wire encoding.
+
+Payload is a `serde`-derived struct serialising to canonical JSON:
+
+```jsonc
+{
+  "grove_id": "<uuidv4>",          // generated at `grove init`
+  "seq": 42,                        // u64, monotonic, leader-managed
+  "created_at": "2026-05-07T12:34:56Z",
+  "leader_fp": "<sha256-hex>",      // of leader SPKI
+  "members": [                      // sorted by fp at serialise time
+    { "fp": "<hex>", "label": "..." }
+  ],
+  "params": [                       // sorted by name at serialise time
+    { "name": "...", "kind": "text", "value": "..." }
+  ],
+  "secrets": []                     // v0: always empty. v1 adds envelope-encrypted entries; no schema break.
+}
+```
+
+Bytes actually signed are `domain_sep || canonical_json_bytes` where `domain_sep = b"bes.grove/sig/v1\0"`. Domain separation is non-negotiable — Ed25519 signatures without it get confused across protocols.
+
+Encoder, signer, and verifier live in a new `crates/protocol/src/grove.rs` (alongside `keys.rs`) so `seedling-ctl` can verify during `grove join` without depending on `core`. Add `serde_jcs` as a dependency on `crates/protocol`.
+
+`created_at` validation: receive-time skew check of ±5 minutes. Reject outside window with `version_too_old`. Don't include unvalidated fields inside a signed envelope.
+
+### Database — migration v53
+
+All five tables added in one migration block at the bottom of `crates/core/src/runtime/db.rs`. Never edit shipped migrations.
+
+- `grove_membership(id INTEGER PRIMARY KEY CHECK(id=1), grove_id BLOB NOT NULL, role TEXT NOT NULL CHECK(role IN ('leader','follower')), leader_fingerprint TEXT NOT NULL, current_seq INTEGER NOT NULL, current_payload BLOB NOT NULL, current_signature BLOB NOT NULL, joined_at TEXT NOT NULL)` — single-row.
+- `grove_peers(fingerprint TEXT PRIMARY KEY, label TEXT, addresses_json TEXT NOT NULL, last_seen_at TEXT, last_connected_at TEXT)`.
+- `grove_params(name TEXT PRIMARY KEY, kind TEXT NOT NULL, value TEXT NOT NULL, version_seq INTEGER NOT NULL)` — denormalised current params for query convenience.
+- `grove_param_mappings(app_name TEXT NOT NULL, app_param_name TEXT NOT NULL, grove_param_name TEXT NOT NULL, PRIMARY KEY(app_name, app_param_name))` — local-only, never replicated.
+- `grove_versions(seq INTEGER PRIMARY KEY, payload BLOB NOT NULL, signature BLOB NOT NULL, received_at TEXT NOT NULL)` — historical payloads for replay/debug. UNIQUE on `seq` makes duplicate-apply idempotent (`INSERT OR IGNORE` then check `changes()`).
+
+All mutations on the leader (publish path) wrap `(load current → mutate → bump seq → sign → persist payload + bump grove_membership)` in one `db.call` closure under a single `parking_lot::Mutex<()>` named `grove_publish_mutex` on `GroveState` (held by `Daemon`, see "Code structure").
+
+### Trust-set reconciliation (load-bearing)
+
+After commit 0 the trust-set machinery lives in `transport/auth.rs` as a protocol-scoped registry, keyed by ALPN. Two strictly-separate sets, neither merged into a global "anyone trusted":
+- **Operator-derived** (`OperatorTrust`): from `data_dir/authorized_keys` (loader stays in `oi/auth.rs`). Authorises *only* the OI ALPN (`bes.seedling/1`).
+- **Grove-derived** (`GroveTrust`): from the latest signed payload's `members`. Authorises *only* the grove ALPN (`bes.grove/1`). Reconciled on every payload-applied event — additions and revocations both.
+
+A key authorised for both surfaces must appear in *both* sets (operator key on the leader's machine, also a grove member: explicit on both sides). Grove membership grants no operator authority and vice versa.
+
+The verifier in `transport/auth.rs` takes the negotiated ALPN and checks only the corresponding set. Constant-time comparison still applies, but only over the set relevant to the protocol being negotiated.
+
+On revocation, iterate the per-connection registry on `TransportState` and close any grove connection with `client_fp == revoked_fp`. Operator connections from the same fingerprint (if the key is also in `OperatorTrust`) are *not* closed — operator authority is a distinct grant. Without per-protocol close, a revoked member retains an existing grove connection until idle-timeout and can keep gossiping.
+
+### Operations surface
+
+CLI, OI handler, web — all three for parity. CLI subcommand tree under `crates/ctl/src/grove.rs`:
+
+Leader-only mutations (handler rejects on follower with "not the leader; current leader is <fp>", regardless of which surface invoked it):
+- `grove init` — generate `grove_id`, persist self-only seq=1 payload.
+- `grove invite <fingerprint> <label>` — append to members, seq++, sign, publish.
+- `grove revoke <fingerprint>` — remove from members, seq++, sign, publish, close existing connections.
+- `grove param set <name> <kind> <value>` and `grove param unset <name>` — modify params, seq++.
+
+Any-node:
+- `grove status` — id, role, leader_fp, current_seq, member count, count of currently-connected peers.
+- `grove peers` — every known peer (members from latest payload + address-hint entries) with: fingerprint, label, currently-connected (yes/no), last_connected_at, last_seen_at, known addresses. CLI table form + OI structured response + web table. Backed by joining the per-connection registry on `OiState` against `grove_peers` rows.
+- `grove members`, `grove params`.
+- `grove join <inviter_addr> <inviter_fp> <leader_fp>` — dial inviter (need not be leader), pull latest payload via an inline `version` request, verify against `leader_fp`, persist. After persist, attempt to reach all members listed in the payload.
+- `grove map <app> <app_param> <grove_param>` — create local mapping. Validates: app + param exist, no existing mapping for `(app, app_param)`, grove param value passes app param's validator (string-coerce by app param's kind). On success, immediately apply current grove value via the synthetic-grove `set_param` path.
+- `grove unmap <app> <app_param>` — remove mapping; app param keeps current value (no automatic revert).
+
+### Reject-local-set + actuation pathway
+
+Refactor `crates/core/src/oi/handler/params.rs::set_param`/`unset_param`:
+- Extract internals into `set_param_inner(...args, source: ParamSource)` where `ParamSource = Operator | Grove { seq: u64 }`.
+- Public OI handler path: enforce mapping rejection (look up `grove_param_mappings`, return error if mapped). Actor remains the operator's.
+- Grove apply path (new helper `apply_grove_param_to_app(state, app, app_param, grove_value)`): synthesises an actor with `kind = Some("grove")`, `id = Some(grove_id_str)`, `display = Some("grove:<seq>")`. Calls `set_param_inner` with `source = Grove { seq }`, bypassing the rejection check.
+
+The barrier/replay system stays grove-unaware; from its point of view a grove-driven `param_set` is identical to an operator one. The actor `kind = "grove"` differentiates in audit/event surfaces.
+
+### Diff application
+
+When a new payload is persisted (idempotent on `grove_versions` UNIQUE):
+- Compute `(prev_params, new_params)` diff.
+- For each grove param G that changed or was added: look up `grove_param_mappings WHERE grove_param_name = G`; for each `(app, app_param)`, call `apply_grove_param_to_app`.
+- For each grove param G removed: same lookup, call `unset_param_inner` with grove source — app param reverts to its declared default through the standard pathway. (`set_param`'s existing "identical-value → not_scheduled" behaviour applies here naturally; `on_change` won't fire if the mapped app already had that value.)
+
+In-flight-op handling: `set_param_inner` already returns `OperationInProgress` when an app is e.g. installing. v0 mirrors operator semantics — the diff application logs the failure as a `grove.param-deferred` event and adds `(app, app_param)` to a `dirty_grove_mappings: HashSet<(AppName, ParamName)>` on `OiState`, drained by an existing reconcile pass when the app phase becomes `Installed`. (Also drained on next `version`-applied for the same grove param.) This handles the case without a heavy queue or pending-state machine.
+
+`grove map` mid-operation: rejects with `OperationInProgress`, mirrors operator semantics. Mapping is *not* persisted; operator retries.
+
+### Connect loop
+
+Single actor on `GroveState`: wakes every ~30s, picks K=4 peers (all stale `last_connected_at` first, then random), dials each over `bes.grove/1`, runs HELLO → optional VERSION (whichever side has lower seq receives) → PEERS → close. Inbound piggybacks on the OI accept loop, dispatched by negotiated ALPN.
+
+### Event surface
+
+New family in `crates/protocol/src/events.rs` (or a sibling `grove_events.rs`):
+- `grove.payload-received { peer_fp, seq }`
+- `grove.payload-applied { seq, params_changed, members_changed }`
+- `grove.payload-rejected { peer_fp, reason }`
+- `grove.publish-rejected { reason, current_bytes?, cap_bytes? }` — leader-side, before bumping seq
+- `grove.peer-connected { fp }`, `grove.peer-disconnected { fp }`
+- `grove.member-revoked { fp }`
+- `grove.mapping-created { app, app_param, grove_param }`
+- `grove.mapping-removed { app, app_param }`
+- `grove.param-applied { app, app_param, grove_param, source: "grove", seq }`
+- `grove.param-deferred { app, app_param, reason: "operation_in_progress" }`
+
+Without these the web UI is unusable; plan them up front in the spec commit.
+
+### Documented v0 limitations
+
+In `docs/spec/grove.md` "Known limitations" section:
+- **Lost leader key bricks the grove.** No quorum, no election. Recovery path (not implemented in v0): any follower runs `grove fork-leader --force --new-leader-key=<fp>` to write a new self-only payload and break the chain, all other followers re-join. Document the recovery shape so users don't lose data.
+- **No secret grove params.** `grove param set --secret` is rejected at v0 definition time. Wire format already reserves a `secrets` field for v1 envelope encryption (Ed25519 → X25519 via `ed25519-dalek` for ECIES per member), so v1 adoption needs no payload-version bump.
+- **No multi-grove.** Schema asserts single-row `grove_membership`. Multi-grove would change the schema and most table PKs.
+
+## Critical files
+
+To modify:
+- `crates/protocol/src/lib.rs` — add `GROVE_ALPN`.
+- `crates/protocol/src/keys.rs` — Ed25519 sign/verify already there; reused.
+- `crates/protocol/src/grove.rs` — *new*. Payload + message types (serde-derived), `serde_jcs` canonical encoder, Ed25519 sign/verify with domain separation. Add `serde_jcs` to `crates/protocol/Cargo.toml`.
+- `crates/protocol/src/events.rs` — extend with grove events.
+- `crates/core/src/runtime/db.rs` — add v53 migration block at the bottom; never edit existing.
+- `crates/core/src/transport/` — *new* module (commit 0). `endpoint.rs`, `auth.rs`, `connection.rs`, `framing.rs`. Holds quinn endpoint, ALPN handler registry, protocol-scoped trust registry, JSON-line framing. Replaces transport-level code currently inlined in `oi/server.rs` and `oi/auth.rs`.
+- `crates/core/src/oi/server.rs` — slimmed to OI-specific stream dispatch (port-forward, log streaming, event subscription, handler routing). Generic per-connection logic moves to `transport/`.
+- `crates/core/src/oi/auth.rs` — bootstrap-file loader stays here; trust-set machinery moves to `transport/auth.rs` as protocol-scoped sets (`OperatorTrust` for OI, `GroveTrust` for grove, registered against their ALPNs).
+- `crates/core/src/grove/` — *new* module. `state.rs` (`GroveState`: publish mutex, dial loop, dirty-mappings, signed-payload cache), `dial.rs` (connect loop), `apply.rs` (payload-apply pipeline + diff), `handler.rs` (registers `bes.grove/1` handler with transport, runs HELLO/VERSION/PEERS/abort exchange).
+- `crates/core/src/daemon.rs` (or wherever the top-level container lives — renamed/restructured if needed) — holds `TransportState` + `OiState` + `GroveState`. Handlers receive only the slice they need.
+- `crates/core/src/oi/handler/params.rs` — extract `set_param_inner(... ParamSource)`, add `apply_grove_param_to_app` helper, rejection check on operator path.
+- `crates/core/src/oi/handler/grove.rs` — *new*. OI handlers for all `grove …` operations.
+- `crates/ctl/src/grove.rs` — *new*. CLI subcommand.
+- `crates/ctl/src/main.rs` — register `grove` subcommand.
+- `crates/web/frontend/src/routes/Grove.tsx` and friends — *new*. Status, members, params, mappings UI.
+- `crates/web/src/api/grove.rs` (or wherever the web API surface lives) — corresponding endpoints.
+- `docs/spec/transport.md` — *new*. `t[...]` items: RPK TLS handshake, fingerprint pinning, ALPN as hard-version-wall, JSON-line stream framing, abort/error semantics, message-size caps. Extracted from interface-spec content that currently describes these for `bes.seedling/1`.
+- `docs/spec/interface.md` — replace duplicated transport prose with references to `t[...]` items; keep OI-specific behaviour (handler routing, port-forward, event subscription, log streaming) under `i[...]`.
+- `docs/spec/grove.md` — *new*. `g[...]` items, referencing `t[...]` for transport-shared bits.
+- `.config/tracey/config.styx` — register `transport/main` and `grove/main`.
+
+To reuse (don't reinvent):
+- `quinn::Endpoint` + RPK TLS — after commit 0, owned by the `transport` module; both OI and grove register handlers, never a second port.
+- `SeedlingClientVerifier` and the trust sets — extracted in commit 0 to protocol-scoped form; grove registers `GroveTrust` against `bes.grove/1`, doesn't fork the verifier.
+- Ed25519 from `crates/protocol/src/keys.rs` — reuse the OI identity for grove signing.
+- `ClientAuth::Fingerprint` + `OiClient::connect` (`crates/protocol/src/client.rs`) — model grove dial on the same shape; consider extracting common dial logic to `transport/dial.rs` if both call sites converge enough.
+- Generation + barrier/replay (`crates/core/src/runtime/generations.rs`, `runtime/apps/replay.rs`) — grove apply flows through the *unchanged* operator pathway. Barrier doesn't learn about grove.
+- `Actor` struct already supports a free-form `kind` string; introduce `"grove"` without a new enum variant.
+
+## Phasing — stacked commits
+
+Each independently shippable, each with its own spec sections + tracey annotations. jj-friendly granularity.
+
+0. **Code restructure: extract `transport` module.** Pure refactor, no behavioural change, OI tests stay green. New `crates/core/src/transport/` (`endpoint`, `auth`, `connection`, `framing`); slim `oi/server.rs` and `oi/auth.rs` to OI-specific bits; split `OiState` into `TransportState` + `OiState`; introduce `Daemon` top-level container; OI registers itself as the `bes.seedling/1` ALPN handler through the new transport interface. Trust-set machinery becomes protocol-scoped (registry keyed by ALPN) but only `OperatorTrust` is registered at this point. Split into 0a (file moves + transport extraction) and 0b (state split) if the combined diff is unwieldy (~>600 lines).
+
+1. **Spec + tracey wiring.** Extract shared transport prose from `docs/spec/interface.md` into a new `docs/spec/transport.md` (`t[...]` namespace) covering RPK TLS, fingerprint pinning, ALPN as hard-version-wall, JSON-line framing, abort/error semantics, message-size caps. Update `interface.md` to reference `t[...]` for those items. Re-annotate the (now-moved) transport code from commit 0 with `t[impl ...]` instead of `i[impl ...]`. Add `docs/spec/grove.md` skeleton with all `g[...]` items including event names and "Known limitations", referencing `t[...]` for transport. Register `transport/main` and `grove/main` in `.config/tracey/config.styx`. `tracey query status` clean with stubbed requirements.
+2. **DB v53 migration.** All five tables, no consumers yet. Test: migration applies cleanly on a v52 DB.
+3. **Signing primitives.** `crates/protocol/src/grove.rs` — payload + message types, `serde_jcs` canonical JSON encoder, Ed25519 sign/verify with `bes.grove/sig/v1` domain separation. Pure functions. Heavy KAT tests, including domain-separation regressions and JCS canonicalisation determinism (round-trip, key ordering, whitespace).
+4. **Leader-side state machine, OI surface only.** `grove init`, `grove invite`, `grove revoke`, `grove param set`/`unset` writing the signed payload to v53 tables. Pre-publish payload-size cap check returning structured `publish-rejected` errors before bumping seq. No networking. Tests: seq monotonicity, signature roundtrip, single-writer mutex under concurrent writes, rejection on follower role, size-cap enforcement.
+5. **Grove ALPN registration + protocol exchange.** Register `bes.grove/1` against the transport handler registry from commit 0. HELLO/VERSION/PEERS/abort exchange, outbound dial loop, inbound handler. Add `GroveTrust` to the protocol trust registry (alongside `OperatorTrust` from commit 0). Persist payloads, verify signatures, reconcile `GroveTrust` on payload-applied. No param actuation yet.
+6. **Onboarding.** `grove join` end-to-end. Test with two ephemeral daemons in-process.
+7. **Mapping + actuation.** `grove_param_mappings`, `grove map`/`unmap`, reject-local-set, `set_param_inner` refactor, `apply_grove_param_to_app`, removal-→-unset, `dirty_grove_mappings` drain on app-idle. Tests: mapping creates apply current value, grove updates fire `on_change`, local set is rejected when mapped, grove-removal unsets mapped param, in-flight ops defer correctly.
+8. **Web + CLI parity, event surface.** `crates/ctl/src/grove.rs` subcommand, web pages and API endpoints, all event variants emitted. Tracey coverage closing.
+
+## Verification
+
+End-to-end test plan, executed manually after commit 8 lands and re-run on changes:
+
+1. Two daemons (leader L, follower F) in `cargo run -p seedling-cli` on different data dirs, behind `tracey query status` clean before starting.
+2. On L: `grove init`. Verify `grove status` shows `role=leader, seq=1, members=1`.
+3. Manual fingerprint exchange: capture `oi.key` fingerprints on both nodes (existing OI tooling).
+4. On L: `grove invite <F_fp> "node-f"`. Verify `seq=2`, members=2.
+5. On F: `grove join <L_addr> <L_fp> <L_fp>`. Verify F's `grove status` shows `role=follower, leader=<L_fp>, seq=2`.
+6. On L: `grove param set greeting text "hello"`. Verify `seq=3` on L, then within ~30s on F.
+7. On F: register a small BSL app with a param `welcome` that has an `on_change` handler logging via `tracing::info!`. Then `grove map <app> welcome greeting`. Verify F's `apps param get <app> welcome` returns "hello", and the `on_change` log line fired.
+8. On F: `apps param set <app> welcome "boom"` — assert error "param is grove-managed".
+9. On L: `grove param set greeting text "kia ora"`. Within ~30s, verify F's `apps param get <app> welcome` is "kia ora" and `on_change` re-fired.
+10. On L: `grove param unset greeting`. Verify F's app param reverts to its declared default and `on_change` re-fired.
+11. On F: `grove unmap <app> welcome`. Then `apps param set <app> welcome "manual"` — should now succeed.
+12. On L and F: `grove peers` — verify each shows the other as currently-connected with a recent `last_connected_at`. Stop F's daemon, wait, re-run `grove peers` on L: F appears as not-connected with the previous `last_connected_at`.
+13. Restart F. On L: try `grove param set` with a value chosen to push the canonical payload past the cap. Verify the OI/CLI rejects with `payload_too_large` and the seq did not advance.
+14. On L: `grove revoke <F_fp>`. Verify L's connection registry shows the F-fp grove connection severed; F's subsequent grove dials get TLS-rejected. If F's fingerprint is *also* in `OperatorTrust`, OI access from F is *not* affected.
+15. `tracey query status` still clean, all `g[...]` items covered.
+
+Run: `just test` for the unit/integration tier; `cargo clippy --all-targets`, `cargo fmt --check`, `tracey query status` before each commit.

From 2e9feb3778ee2fba50389958fe67a6d5dacad813 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 21:41:41 +1200
Subject: [PATCH 02/11] refactor(transport): extract shared QUIC endpoint, ALPN
 dispatch, and protocol-scoped trust
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pulls the transport primitives currently living in oi/server.rs and oi/auth.rs
into a new crates/core/src/transport/ module, in preparation for a second
ALPN (bes.grove/1) sharing the same endpoint.

- transport/auth.rs holds TrustedKeys, the ring TLS verifier helpers, and a
  new ProtocolTrustRegistry keyed by ALPN. The verifier admits any key
  trusted by any registered protocol at handshake time (rustls's API can't
  see the negotiated ALPN there); the post-handshake gate then enforces
  per-protocol authorisation against the negotiated ALPN.
- transport/endpoint.rs holds build_tls_config, the accept loop,
  extract_client_fp, read_json_line, and a small ALPN handler registry.
  Each protocol registers a connection handler against an ALPN; on accept,
  the negotiated ALPN selects the handler.
- oi/auth.rs slims to bootstrap-file and DB CRUD; oi/server.rs's run() now
  registers the OI handler with transport and delegates endpoint setup.
- DEFAULT_PORT moves to transport/endpoint (it's the shared listen port).
  DEFAULT_MAX_STREAMS stays in oi/server (per-protocol concurrency cap).

Pure refactor — OI behaviour unchanged.
---
 crates/core/src/lib.rs                |   1 +
 crates/core/src/oi.rs                 |   2 +-
 crates/core/src/oi/auth.rs            | 119 +---------
 crates/core/src/oi/server.rs          | 201 ++++-------------
 crates/core/src/transport.rs          |   2 +
 crates/core/src/transport/auth.rs     | 254 +++++++++++++++++++++
 crates/core/src/transport/endpoint.rs | 306 ++++++++++++++++++++++++++
 crates/daemon/src/main.rs             |   4 +-
 8 files changed, 615 insertions(+), 274 deletions(-)
 create mode 100644 crates/core/src/transport.rs
 create mode 100644 crates/core/src/transport/auth.rs
 create mode 100644 crates/core/src/transport/endpoint.rs

diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index cccc8c85..64ff0eb7 100644
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -5,6 +5,7 @@ pub mod oi;
 pub mod runtime;
 pub mod sysconst;
 pub mod system;
+pub mod transport;
 
 #[cfg(test)]
 mod tests;
diff --git a/crates/core/src/oi.rs b/crates/core/src/oi.rs
index 02468ab8..a146b834 100644
--- a/crates/core/src/oi.rs
+++ b/crates/core/src/oi.rs
@@ -6,4 +6,4 @@ pub mod server;
 pub mod shells;
 pub mod state;
 
-pub use server::{DEFAULT_PORT, run};
+pub use server::run;
diff --git a/crates/core/src/oi/auth.rs b/crates/core/src/oi/auth.rs
index 986ada89..21892b1f 100644
--- a/crates/core/src/oi/auth.rs
+++ b/crates/core/src/oi/auth.rs
@@ -1,34 +1,11 @@
 use std::{
-    collections::HashSet,
     io,
     path::Path,
-    sync::Arc,
     time::{SystemTime, UNIX_EPOCH},
 };
 
-use parking_lot::RwLock;
-use rustls::{
-    DigitallySignedStruct, DistinguishedName, SignatureScheme,
-    client::danger::HandshakeSignatureValid,
-    server::danger::{ClientCertVerified, ClientCertVerifier},
-};
-use rustls_pki_types::{CertificateDer, SubjectPublicKeyInfoDer, UnixTime};
-use subtle::ConstantTimeEq;
-
 use crate::runtime::db::Db;
-
-use seedling_protocol::keys;
-
-// ---------------------------------------------------------------------------
-// In-memory trusted key set
-// ---------------------------------------------------------------------------
-
-/// Thread-safe in-memory set of trusted client SPKI fingerprints.
-pub type TrustedKeys = Arc<RwLock<HashSet<String>>>;
-
-pub fn new_trusted_keys() -> TrustedKeys {
-    Arc::new(RwLock::new(HashSet::new()))
-}
+use crate::transport::auth::TrustedKeys;
 
 // ---------------------------------------------------------------------------
 // DB helpers
@@ -164,102 +141,10 @@ pub fn revoke_key(db: &Db, trusted: &TrustedKeys, fp: &str) -> rusqlite::Result<
     }
 }
 
-// ---------------------------------------------------------------------------
-// Client certificate verifier
-// ---------------------------------------------------------------------------
-
-fn ring_verify_tls12(
-    message: &[u8],
-    cert: &CertificateDer<'_>,
-    dss: &DigitallySignedStruct,
-) -> Result<HandshakeSignatureValid, rustls::Error> {
-    rustls::crypto::verify_tls12_signature(
-        message,
-        cert,
-        dss,
-        &rustls::crypto::ring::default_provider().signature_verification_algorithms,
-    )
-}
-
-fn ring_verify_tls13_rpk(
-    message: &[u8],
-    cert: &CertificateDer<'_>,
-    dss: &DigitallySignedStruct,
-) -> Result<HandshakeSignatureValid, rustls::Error> {
-    rustls::crypto::verify_tls13_signature_with_raw_key(
-        message,
-        &SubjectPublicKeyInfoDer::from(cert.as_ref()),
-        dss,
-        &rustls::crypto::ring::default_provider().signature_verification_algorithms,
-    )
-}
-
-fn ring_schemes() -> Vec<SignatureScheme> {
-    rustls::crypto::ring::default_provider()
-        .signature_verification_algorithms
-        .supported_schemes()
-}
-
-#[derive(Debug)]
-pub struct SeedlingClientVerifier {
-    pub trusted: TrustedKeys,
-}
-
-impl ClientCertVerifier for SeedlingClientVerifier {
-    fn root_hint_subjects(&self) -> &[DistinguishedName] {
-        &[]
-    }
-
-    fn verify_client_cert(
-        &self,
-        end_entity: &CertificateDer<'_>,
-        _intermediates: &[CertificateDer<'_>],
-        _now: UnixTime,
-    ) -> Result<ClientCertVerified, rustls::Error> {
-        let fp = keys::fingerprint(end_entity.as_ref());
-        let fp_bytes = fp.as_bytes();
-        let trusted = self.trusted.read();
-        let found = trusted.iter().any(|t| t.as_bytes().ct_eq(fp_bytes).into());
-        if found {
-            Ok(ClientCertVerified::assertion())
-        } else {
-            tracing::warn!(fingerprint = %fp, "rejected client with unrecognized key");
-            Err(rustls::Error::InvalidCertificate(
-                rustls::CertificateError::ApplicationVerificationFailure,
-            ))
-        }
-    }
-
-    fn verify_tls12_signature(
-        &self,
-        message: &[u8],
-        cert: &CertificateDer<'_>,
-        dss: &DigitallySignedStruct,
-    ) -> Result<HandshakeSignatureValid, rustls::Error> {
-        ring_verify_tls12(message, cert, dss)
-    }
-
-    fn verify_tls13_signature(
-        &self,
-        message: &[u8],
-        cert: &CertificateDer<'_>,
-        dss: &DigitallySignedStruct,
-    ) -> Result<HandshakeSignatureValid, rustls::Error> {
-        ring_verify_tls13_rpk(message, cert, dss)
-    }
-
-    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
-        ring_schemes()
-    }
-
-    fn requires_raw_public_keys(&self) -> bool {
-        true
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::transport::auth::new_trusted_keys;
 
     // i[verify key.list]
     #[test]
diff --git a/crates/core/src/oi/server.rs b/crates/core/src/oi/server.rs
index 80765778..0b2655c2 100644
--- a/crates/core/src/oi/server.rs
+++ b/crates/core/src/oi/server.rs
@@ -1,71 +1,33 @@
-use std::{net::SocketAddr, path::Path, sync::Arc, time::Duration};
+use std::{net::SocketAddr, path::Path, sync::Arc};
 
 use quinn::Endpoint;
-use rustls::ServerConfig as TlsServerConfig;
 use serde_json::json;
 use tokio::sync::{Semaphore, mpsc};
 use tracing::Instrument;
 
-use seedling_protocol::{OI_ALPN, actor::Actor, events::EventSenderWithActor, keys};
+use seedling_protocol::{OI_ALPN, actor::Actor, events::EventSenderWithActor};
 
 use super::{
-    auth::{SeedlingClientVerifier, TrustedKeys},
     forwards::session::{forward_port_session, handle_forward_stream},
     handler::{RequestCtx, dispatch},
     shells::{open_shell_session, open_volume_shell_session},
     state::OiState,
 };
+use crate::transport::{
+    auth::ProtocolTrustRegistry,
+    endpoint::{
+        AlpnHandlers, ConnectionContext, ConnectionFuture, ConnectionHandler, EndpointConfig,
+        LabelLookup, extract_client_fp, read_json_line,
+    },
+};
 
-/// Default maximum number of concurrently active bidirectional streams.
+/// Default maximum number of concurrently active OI bidirectional streams
+/// per connection. Per-protocol; grove will set its own.
 pub const DEFAULT_MAX_STREAMS: usize = 64;
 
 /// Maximum size of a request body read (4 MiB).
 const MAX_REQUEST_SIZE: usize = 4 * 1024 * 1024;
 
-/// Default OI listen port.
-pub const DEFAULT_PORT: u16 = 7891;
-
-fn build_tls_config(
-    key: &ed25519_dalek::SigningKey,
-    spki: Vec<u8>,
-    trusted: TrustedKeys,
-) -> Result<TlsServerConfig, Box<dyn std::error::Error + Send + Sync>> {
-    use ed25519_dalek::pkcs8::EncodePrivateKey;
-    use rustls::{server::AlwaysResolvesServerRawPublicKeys, sign::CertifiedKey};
-    use rustls_pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer};
-
-    let pkcs8 = key
-        .to_pkcs8_der()
-        .map_err(|e| format!("key encoding: {e}"))?;
-    let private_key = PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(pkcs8.as_bytes().to_vec()));
-    let signing_key = rustls::crypto::ring::sign::any_supported_type(&private_key)
-        .map_err(|e| format!("signing key: {e}"))?;
-
-    let cert = CertificateDer::from(spki);
-    let certified_key = Arc::new(CertifiedKey::new(vec![cert], signing_key));
-    let resolver = Arc::new(AlwaysResolvesServerRawPublicKeys::new(certified_key));
-
-    let client_verifier = Arc::new(SeedlingClientVerifier { trusted });
-
-    let mut tls_config = TlsServerConfig::builder()
-        .with_client_cert_verifier(client_verifier)
-        .with_cert_resolver(resolver);
-
-    tls_config.key_log = Arc::new(rustls::KeyLogFile::new());
-    // i[transport.alpn]
-    tls_config.alpn_protocols = vec![OI_ALPN.to_vec()];
-
-    Ok(tls_config)
-}
-
-fn extract_client_fp(conn: &quinn::Connection) -> Option<String> {
-    let id = conn.peer_identity()?;
-    let certs = id
-        .downcast::<Vec<rustls_pki_types::CertificateDer<'static>>>()
-        .ok()?;
-    certs.first().map(|c| keys::fingerprint(c.as_ref()))
-}
-
 // i[wire.actor]
 fn synthesise_actor(state: &OiState, fp: Option<&str>) -> Arc<Actor> {
     let id = fp.map(str::to_owned);
@@ -85,24 +47,12 @@ fn synthesise_actor(state: &OiState, fp: Option<&str>) -> Arc<Actor> {
     })
 }
 
-// i[transport.quic]
-// i[transport.server-identity]
-// i[transport.client-auth]
-// i[transport.listen]
 pub async fn run(
     state: Arc<OiState>,
     addrs: &[SocketAddr],
     data_dir: &Path,
     max_streams: usize,
 ) -> Result<(String, Vec<Endpoint>), Box<dyn std::error::Error + Send + Sync>> {
-    let key_path = data_dir.join("oi.key");
-    let key = keys::load_or_generate(&key_path)?;
-    let spki = keys::spki_der(&key);
-    let fingerprint = keys::fingerprint(&spki);
-
-    tracing::info!("OI SPKI fingerprint: {fingerprint}");
-    state.spki_fingerprint.set(fingerprint.clone()).ok();
-
     {
         let trusted_keys = Arc::clone(&state.trusted_keys);
         state
@@ -124,63 +74,46 @@ pub async fn run(
         );
     }
 
-    let tls_config = build_tls_config(&key, spki, Arc::clone(&state.trusted_keys))?;
-    let quic_config = quinn::crypto::rustls::QuicServerConfig::try_from(tls_config)?;
-    let mut transport = quinn::TransportConfig::default();
-    // Send PING frames every 10 s so idle connections do not trip the idle
-    // timeout.  As long as seedling-ctl is alive and the network is healthy,
-    // PINGs reset the idle timer and the connection stays open indefinitely.
-    transport.keep_alive_interval(Some(Duration::from_secs(10)));
-    // 30 s: long enough that a single missed PING does not drop the
-    // connection, short enough that a genuinely dead connection is detected
-    // and cleaned up promptly.
-    transport.max_idle_timeout(Some(
-        quinn::VarInt::from_u32(30_000).into(), // 30 s in ms
-    ));
-    // Enable QUIC datagrams for UDP port-forward relay.
-    transport.datagram_receive_buffer_size(Some(65536));
-    let transport = Arc::new(transport);
-    // Build one server config and clone it per endpoint (cheap: all heavy
-    // state is behind Arcs inside quinn::ServerConfig).
-    let mut base_server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_config));
-    base_server_config.transport_config(Arc::clone(&transport));
-
-    if std::env::var_os("SSLKEYLOGFILE").is_some() {
-        tracing::warn!("SSLKEYLOGFILE is set — TLS session keys are being logged to disk");
-    }
+    let trust = ProtocolTrustRegistry::new();
+    trust.register(OI_ALPN, Arc::clone(&state.trusted_keys));
 
+    let handlers = AlpnHandlers::new();
     let stream_semaphore = Arc::new(Semaphore::new(max_streams));
+    let oi_handler: ConnectionHandler = {
+        let state = Arc::clone(&state);
+        Arc::new(move |conn, ctx| -> ConnectionFuture {
+            let state = Arc::clone(&state);
+            let stream_semaphore = Arc::clone(&stream_semaphore);
+            Box::pin(handle_connection(conn, ctx, state, stream_semaphore))
+        })
+    };
+    handlers.register(OI_ALPN, oi_handler);
+
+    let label_lookup: LabelLookup = {
+        let state = Arc::clone(&state);
+        Arc::new(move |fp: &str| {
+            let fp = fp.to_owned();
+            state
+                .db
+                .call(move |db| super::auth::get_label(db, &fp).ok().flatten())
+        })
+    };
+
     tracing::info!(max_streams, "OI concurrency limit configured");
 
-    let mut endpoints = Vec::with_capacity(addrs.len());
-    for addr in addrs {
-        let endpoint = Endpoint::server(base_server_config.clone(), *addr)?;
-        tracing::info!("OI listening on {}", endpoint.local_addr()?);
-        let ep_clone = endpoint.clone();
-        tokio::spawn(accept_loop(
-            endpoint,
-            Arc::clone(&state),
-            Arc::clone(&stream_semaphore),
-        ));
-        endpoints.push(ep_clone);
-    }
+    let (fingerprint, endpoints) = crate::transport::endpoint::run(EndpointConfig {
+        key_path: data_dir.join("oi.key"),
+        addrs: addrs.to_vec(),
+        trust: Arc::clone(&trust),
+        handlers: Arc::clone(&handlers),
+        label_lookup: Some(label_lookup),
+    })
+    .await?;
 
-    Ok((fingerprint, endpoints))
-}
+    tracing::info!("OI SPKI fingerprint: {fingerprint}");
+    state.spki_fingerprint.set(fingerprint.clone()).ok();
 
-async fn accept_loop(endpoint: Endpoint, state: Arc<OiState>, stream_semaphore: Arc<Semaphore>) {
-    while let Some(incoming) = endpoint.accept().await {
-        let state = Arc::clone(&state);
-        let stream_semaphore = Arc::clone(&stream_semaphore);
-        tokio::spawn(async move {
-            match incoming.await {
-                Ok(conn) => {
-                    handle_connection(conn, state, stream_semaphore).await;
-                }
-                Err(e) => tracing::warn!("incoming connection failed: {e}"),
-            }
-        });
-    }
+    Ok((fingerprint, endpoints))
 }
 
 // i[stream.control]
@@ -189,23 +122,13 @@ async fn accept_loop(endpoint: Endpoint, state: Arc<OiState>, stream_semaphore:
 // i[datagram.forward]
 async fn handle_connection(
     conn: quinn::Connection,
+    ctx: ConnectionContext,
     state: Arc<OiState>,
     stream_semaphore: Arc<Semaphore>,
 ) {
     let conn_id = conn.stable_id();
     let peer = conn.remote_address();
-    let client_fp = extract_client_fp(&conn);
-
-    let client: String = client_fp
-        .as_deref()
-        .and_then(|fp| {
-            let fp = fp.to_owned();
-            state
-                .db
-                .call(move |db| super::auth::get_label(db, &fp).ok().flatten())
-        })
-        .or_else(|| client_fp.clone())
-        .unwrap_or_else(|| "unauthenticated".to_owned());
+    let client = ctx.client_label;
 
     loop {
         tokio::select! {
@@ -483,36 +406,6 @@ async fn handle_bidi_stream(
     let _ = send.finish();
 }
 
-/// Reads bytes from `recv` until a `\n` is found or `max_len` is reached.
-///
-/// Returns `(line_including_newline, leftover_bytes_after_newline)`.
-/// On stream close before any data, returns `([], [])`.
-async fn read_json_line(
-    recv: &mut quinn::RecvStream,
-    max_len: usize,
-) -> Result<(Vec<u8>, Vec<u8>), quinn::ReadError> {
-    let mut buf = vec![0u8; max_len.min(65536)];
-    let mut total = 0usize;
-    loop {
-        let chunk_size = (max_len - total).min(1024);
-        if chunk_size == 0 {
-            break;
-        }
-        match recv.read(&mut buf[total..total + chunk_size]).await? {
-            Some(0) | None => break,
-            Some(n) => {
-                total += n;
-                if let Some(pos) = buf[..total].iter().position(|&b| b == b'\n') {
-                    let line = buf[..=pos].to_vec();
-                    let leftover = buf[pos + 1..total].to_vec();
-                    return Ok((line, leftover));
-                }
-            }
-        }
-    }
-    Ok((buf[..total].to_vec(), Vec::new()))
-}
-
 // i[stream.events]
 // i[event.ordering]
 async fn event_stream_task(
diff --git a/crates/core/src/transport.rs b/crates/core/src/transport.rs
new file mode 100644
index 00000000..e3fad590
--- /dev/null
+++ b/crates/core/src/transport.rs
@@ -0,0 +1,2 @@
+pub mod auth;
+pub mod endpoint;
diff --git a/crates/core/src/transport/auth.rs b/crates/core/src/transport/auth.rs
new file mode 100644
index 00000000..61d476e5
--- /dev/null
+++ b/crates/core/src/transport/auth.rs
@@ -0,0 +1,254 @@
+//! Transport-layer authentication: the trust-set machinery used by the
+//! TLS client certificate verifier across all ALPNs registered on the
+//! shared QUIC endpoint.
+//!
+//! Trust is **protocol-scoped**: each ALPN registers its own trusted-keys
+//! set with [`ProtocolTrustRegistry`]. A key authorised for one ALPN does
+//! not authorise others — the post-handshake gate in
+//! [`crate::transport::endpoint`] enforces this against the negotiated
+//! ALPN before the registered handler is invoked.
+//!
+//! At TLS handshake time the verifier accepts any key trusted by **any**
+//! registered protocol, because rustls's `ClientCertVerifier` API does
+//! not expose the negotiated ALPN at cert-verification time. Per-protocol
+//! authorisation is then enforced post-handshake.
+
+use std::{collections::HashSet, sync::Arc};
+
+use parking_lot::RwLock;
+use rustls::{
+    DigitallySignedStruct, DistinguishedName, SignatureScheme,
+    client::danger::HandshakeSignatureValid,
+    server::danger::{ClientCertVerified, ClientCertVerifier},
+};
+use rustls_pki_types::{CertificateDer, SubjectPublicKeyInfoDer, UnixTime};
+use subtle::ConstantTimeEq;
+
+use seedling_protocol::keys;
+
+/// Thread-safe in-memory set of trusted SPKI fingerprints for one protocol.
+///
+/// Mutations are reflected in subsequent TLS handshakes immediately.
+pub type TrustedKeys = Arc<RwLock<HashSet<String>>>;
+
+pub fn new_trusted_keys() -> TrustedKeys {
+    Arc::new(RwLock::new(HashSet::new()))
+}
+
+/// Registry mapping each registered ALPN to its trusted-keys set.
+///
+/// Built once at daemon startup. Shared with the TLS verifier (which
+/// consults the union for handshake admission) and with the post-handshake
+/// gate (which checks the negotiated ALPN's set).
+#[derive(Debug, Default)]
+pub struct ProtocolTrustRegistry {
+    inner: RwLock<Vec<(Vec<u8>, TrustedKeys)>>,
+}
+
+impl ProtocolTrustRegistry {
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self::default())
+    }
+
+    /// Register `trust` as the trusted-keys set for `alpn`. Replaces any
+    /// existing registration for the same ALPN.
+    pub fn register(&self, alpn: &[u8], trust: TrustedKeys) {
+        let mut inner = self.inner.write();
+        if let Some(slot) = inner.iter_mut().find(|(a, _)| a == alpn) {
+            slot.1 = trust;
+        } else {
+            inner.push((alpn.to_vec(), trust));
+        }
+    }
+
+    /// True if `fp` is trusted for the given negotiated ALPN.
+    pub fn is_trusted_for(&self, alpn: &[u8], fp: &str) -> bool {
+        let inner = self.inner.read();
+        let fp_bytes = fp.as_bytes();
+        inner.iter().any(|(a, t)| {
+            a == alpn
+                && t.read()
+                    .iter()
+                    .any(|trusted| trusted.as_bytes().ct_eq(fp_bytes).into())
+        })
+    }
+
+    /// True if `fp` is trusted by any registered protocol. Used at TLS
+    /// handshake time when the negotiated ALPN is not yet visible to
+    /// rustls's `ClientCertVerifier`.
+    pub fn is_trusted_any(&self, fp: &str) -> bool {
+        let inner = self.inner.read();
+        let fp_bytes = fp.as_bytes();
+        inner.iter().any(|(_, t)| {
+            t.read()
+                .iter()
+                .any(|trusted| trusted.as_bytes().ct_eq(fp_bytes).into())
+        })
+    }
+
+    /// ALPN identifiers in registration order, suitable for
+    /// `tls_config.alpn_protocols`.
+    pub fn alpn_list(&self) -> Vec<Vec<u8>> {
+        self.inner.read().iter().map(|(a, _)| a.clone()).collect()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// rustls signature verification helpers
+// ---------------------------------------------------------------------------
+
+fn ring_verify_tls12(
+    message: &[u8],
+    cert: &CertificateDer<'_>,
+    dss: &DigitallySignedStruct,
+) -> Result<HandshakeSignatureValid, rustls::Error> {
+    rustls::crypto::verify_tls12_signature(
+        message,
+        cert,
+        dss,
+        &rustls::crypto::ring::default_provider().signature_verification_algorithms,
+    )
+}
+
+fn ring_verify_tls13_rpk(
+    message: &[u8],
+    cert: &CertificateDer<'_>,
+    dss: &DigitallySignedStruct,
+) -> Result<HandshakeSignatureValid, rustls::Error> {
+    rustls::crypto::verify_tls13_signature_with_raw_key(
+        message,
+        &SubjectPublicKeyInfoDer::from(cert.as_ref()),
+        dss,
+        &rustls::crypto::ring::default_provider().signature_verification_algorithms,
+    )
+}
+
+fn ring_schemes() -> Vec<SignatureScheme> {
+    rustls::crypto::ring::default_provider()
+        .signature_verification_algorithms
+        .supported_schemes()
+}
+
+// ---------------------------------------------------------------------------
+// Client certificate verifier
+// ---------------------------------------------------------------------------
+
+#[derive(Debug)]
+pub struct SeedlingClientVerifier {
+    pub registry: Arc<ProtocolTrustRegistry>,
+}
+
+impl ClientCertVerifier for SeedlingClientVerifier {
+    fn root_hint_subjects(&self) -> &[DistinguishedName] {
+        &[]
+    }
+
+    fn verify_client_cert(
+        &self,
+        end_entity: &CertificateDer<'_>,
+        _intermediates: &[CertificateDer<'_>],
+        _now: UnixTime,
+    ) -> Result<ClientCertVerified, rustls::Error> {
+        let fp = keys::fingerprint(end_entity.as_ref());
+        if self.registry.is_trusted_any(&fp) {
+            Ok(ClientCertVerified::assertion())
+        } else {
+            tracing::warn!(fingerprint = %fp, "rejected client with unrecognized key");
+            Err(rustls::Error::InvalidCertificate(
+                rustls::CertificateError::ApplicationVerificationFailure,
+            ))
+        }
+    }
+
+    fn verify_tls12_signature(
+        &self,
+        message: &[u8],
+        cert: &CertificateDer<'_>,
+        dss: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        ring_verify_tls12(message, cert, dss)
+    }
+
+    fn verify_tls13_signature(
+        &self,
+        message: &[u8],
+        cert: &CertificateDer<'_>,
+        dss: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        ring_verify_tls13_rpk(message, cert, dss)
+    }
+
+    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
+        ring_schemes()
+    }
+
+    fn requires_raw_public_keys(&self) -> bool {
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fps(reg: &ProtocolTrustRegistry, alpn: &[u8]) -> bool {
+        reg.is_trusted_for(alpn, "fp-1")
+    }
+
+    #[test]
+    fn register_and_lookup_per_alpn() {
+        let reg = ProtocolTrustRegistry::default();
+        let oi = new_trusted_keys();
+        oi.write().insert("fp-1".to_owned());
+        reg.register(b"oi/1", oi);
+        assert!(fps(&reg, b"oi/1"));
+        assert!(!fps(&reg, b"grove/1"));
+        assert!(reg.is_trusted_any("fp-1"));
+        assert!(!reg.is_trusted_any("fp-other"));
+    }
+
+    #[test]
+    fn registering_same_alpn_replaces() {
+        let reg = ProtocolTrustRegistry::default();
+        let first = new_trusted_keys();
+        first.write().insert("fp-old".to_owned());
+        reg.register(b"oi/1", first);
+
+        let second = new_trusted_keys();
+        second.write().insert("fp-new".to_owned());
+        reg.register(b"oi/1", second);
+
+        assert!(reg.is_trusted_for(b"oi/1", "fp-new"));
+        assert!(!reg.is_trusted_for(b"oi/1", "fp-old"));
+        assert_eq!(reg.alpn_list(), vec![b"oi/1".to_vec()]);
+    }
+
+    #[test]
+    fn alpn_list_preserves_registration_order() {
+        let reg = ProtocolTrustRegistry::default();
+        reg.register(b"oi/1", new_trusted_keys());
+        reg.register(b"grove/1", new_trusted_keys());
+        assert_eq!(reg.alpn_list(), vec![b"oi/1".to_vec(), b"grove/1".to_vec()]);
+    }
+
+    #[test]
+    fn protocol_scoped_keys_do_not_leak_across_alpns() {
+        let reg = ProtocolTrustRegistry::default();
+        let oi = new_trusted_keys();
+        oi.write().insert("operator-fp".to_owned());
+        reg.register(b"oi/1", oi);
+
+        let grove = new_trusted_keys();
+        grove.write().insert("grove-member-fp".to_owned());
+        reg.register(b"grove/1", grove);
+
+        assert!(reg.is_trusted_for(b"oi/1", "operator-fp"));
+        assert!(!reg.is_trusted_for(b"grove/1", "operator-fp"));
+        assert!(reg.is_trusted_for(b"grove/1", "grove-member-fp"));
+        assert!(!reg.is_trusted_for(b"oi/1", "grove-member-fp"));
+        // But the handshake-time check accepts either, since rustls cannot
+        // see the negotiated ALPN when verify_client_cert runs.
+        assert!(reg.is_trusted_any("operator-fp"));
+        assert!(reg.is_trusted_any("grove-member-fp"));
+    }
+}
diff --git a/crates/core/src/transport/endpoint.rs b/crates/core/src/transport/endpoint.rs
new file mode 100644
index 00000000..4d0c91a3
--- /dev/null
+++ b/crates/core/src/transport/endpoint.rs
@@ -0,0 +1,306 @@
+//! Shared QUIC endpoint, accept loop, and ALPN dispatch.
+//!
+//! The endpoint advertises every ALPN registered with [`AlpnHandlers`]; on
+//! accept, the negotiated ALPN selects the registered handler, after the
+//! per-protocol trust gate (in [`crate::transport::auth`]) has approved
+//! the client's fingerprint.
+
+use std::{net::SocketAddr, path::PathBuf, pin::Pin, sync::Arc, time::Duration};
+
+use parking_lot::RwLock;
+use quinn::Endpoint;
+use rustls::ServerConfig as TlsServerConfig;
+
+use seedling_protocol::keys;
+
+use crate::transport::auth::{ProtocolTrustRegistry, SeedlingClientVerifier};
+
+/// Default listen port. The shared endpoint is one TCP/UDP port for all
+/// registered ALPNs.
+pub const DEFAULT_PORT: u16 = 7891;
+
+/// Per-connection context passed to the registered ALPN handler.
+pub struct ConnectionContext {
+    /// Client's SPKI SHA-256 fingerprint, or `None` if no client cert was
+    /// presented (currently impossible since RPK mTLS is required).
+    pub client_fp: Option<String>,
+    /// Human-readable label for log spans, derived from `client_fp` via the
+    /// [`LabelLookup`] callback. Falls back to the fingerprint, then
+    /// `"unauthenticated"`.
+    pub client_label: String,
+    /// ALPN identifier negotiated for this connection.
+    pub negotiated_alpn: Vec<u8>,
+}
+
+/// Future returned by a registered handler. The transport layer awaits it
+/// to keep the per-connection task alive for the lifetime of the
+/// connection.
+pub type ConnectionFuture = Pin<Box<dyn Future<Output = ()> + Send>>;
+
+/// Handler invoked once per accepted connection, after the post-handshake
+/// trust gate has approved the negotiated ALPN.
+pub type ConnectionHandler =
+    Arc<dyn Fn(quinn::Connection, ConnectionContext) -> ConnectionFuture + Send + Sync>;
+
+/// Registry of ALPN → handler mappings. Each protocol (OI, grove, …)
+/// registers its handler before [`run`] is called.
+#[derive(Default)]
+pub struct AlpnHandlers {
+    inner: RwLock<Vec<(Vec<u8>, ConnectionHandler)>>,
+}
+
+impl AlpnHandlers {
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self::default())
+    }
+
+    pub fn register(&self, alpn: &[u8], handler: ConnectionHandler) {
+        let mut inner = self.inner.write();
+        if let Some(slot) = inner.iter_mut().find(|(a, _)| a == alpn) {
+            slot.1 = handler;
+        } else {
+            inner.push((alpn.to_vec(), handler));
+        }
+    }
+
+    pub fn lookup(&self, alpn: &[u8]) -> Option<ConnectionHandler> {
+        self.inner
+            .read()
+            .iter()
+            .find(|(a, _)| a == alpn)
+            .map(|(_, h)| Arc::clone(h))
+    }
+
+    pub fn alpn_list(&self) -> Vec<Vec<u8>> {
+        self.inner.read().iter().map(|(a, _)| a.clone()).collect()
+    }
+}
+
+/// Optional fingerprint → label resolver, used to decorate per-connection
+/// log spans with human-readable peer names.
+pub type LabelLookup = Arc<dyn Fn(&str) -> Option<String> + Send + Sync>;
+
+pub struct EndpointConfig {
+    pub key_path: PathBuf,
+    pub addrs: Vec<SocketAddr>,
+    pub trust: Arc<ProtocolTrustRegistry>,
+    pub handlers: Arc<AlpnHandlers>,
+    pub label_lookup: Option<LabelLookup>,
+}
+
+fn build_tls_config(
+    key: &ed25519_dalek::SigningKey,
+    spki: Vec<u8>,
+    trust: Arc<ProtocolTrustRegistry>,
+    alpn_list: Vec<Vec<u8>>,
+) -> Result<TlsServerConfig, Box<dyn std::error::Error + Send + Sync>> {
+    use ed25519_dalek::pkcs8::EncodePrivateKey;
+    use rustls::{server::AlwaysResolvesServerRawPublicKeys, sign::CertifiedKey};
+    use rustls_pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer};
+
+    let pkcs8 = key
+        .to_pkcs8_der()
+        .map_err(|e| format!("key encoding: {e}"))?;
+    let private_key = PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(pkcs8.as_bytes().to_vec()));
+    let signing_key = rustls::crypto::ring::sign::any_supported_type(&private_key)
+        .map_err(|e| format!("signing key: {e}"))?;
+
+    let cert = CertificateDer::from(spki);
+    let certified_key = Arc::new(CertifiedKey::new(vec![cert], signing_key));
+    let resolver = Arc::new(AlwaysResolvesServerRawPublicKeys::new(certified_key));
+
+    let client_verifier = Arc::new(SeedlingClientVerifier { registry: trust });
+
+    let mut tls_config = TlsServerConfig::builder()
+        .with_client_cert_verifier(client_verifier)
+        .with_cert_resolver(resolver);
+
+    tls_config.key_log = Arc::new(rustls::KeyLogFile::new());
+    // i[transport.alpn]
+    tls_config.alpn_protocols = alpn_list;
+
+    Ok(tls_config)
+}
+
+/// Extract the client's SPKI SHA-256 fingerprint from a connected peer's
+/// certificate, when present.
+pub fn extract_client_fp(conn: &quinn::Connection) -> Option<String> {
+    let id = conn.peer_identity()?;
+    let certs = id
+        .downcast::<Vec<rustls_pki_types::CertificateDer<'static>>>()
+        .ok()?;
+    certs.first().map(|c| keys::fingerprint(c.as_ref()))
+}
+
+fn extract_negotiated_alpn(conn: &quinn::Connection) -> Option<Vec<u8>> {
+    let hd = conn.handshake_data()?;
+    let hd = hd.downcast::<quinn::crypto::rustls::HandshakeData>().ok()?;
+    hd.protocol
+}
+
+// i[transport.quic]
+// i[transport.server-identity]
+// i[transport.client-auth]
+// i[transport.listen]
+pub async fn run(
+    config: EndpointConfig,
+) -> Result<(String, Vec<Endpoint>), Box<dyn std::error::Error + Send + Sync>> {
+    let key = keys::load_or_generate(&config.key_path)?;
+    let spki = keys::spki_der(&key);
+    let fingerprint = keys::fingerprint(&spki);
+
+    tracing::info!("transport SPKI fingerprint: {fingerprint}");
+
+    let alpn_list = config.handlers.alpn_list();
+    if alpn_list.is_empty() {
+        return Err("no ALPN handlers registered".into());
+    }
+
+    let tls_config = build_tls_config(&key, spki, Arc::clone(&config.trust), alpn_list)?;
+    let quic_config = quinn::crypto::rustls::QuicServerConfig::try_from(tls_config)?;
+    let mut transport = quinn::TransportConfig::default();
+    // Send PING frames every 10 s so idle connections do not trip the idle
+    // timeout. As long as a peer (e.g. seedling-ctl, or a grove peer) is alive
+    // and the network is healthy, PINGs reset the idle timer and the
+    // connection stays open indefinitely.
+    transport.keep_alive_interval(Some(Duration::from_secs(10)));
+    // 30 s: long enough that a single missed PING does not drop the
+    // connection, short enough that a genuinely dead connection is detected
+    // and cleaned up promptly.
+    transport.max_idle_timeout(Some(quinn::VarInt::from_u32(30_000).into()));
+    // Enable QUIC datagrams for UDP port-forward relay.
+    transport.datagram_receive_buffer_size(Some(65536));
+    let transport_cfg = Arc::new(transport);
+
+    // Build one server config and clone it per endpoint (cheap: all heavy
+    // state is behind Arcs inside quinn::ServerConfig).
+    let mut base_server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_config));
+    base_server_config.transport_config(Arc::clone(&transport_cfg));
+
+    if std::env::var_os("SSLKEYLOGFILE").is_some() {
+        tracing::warn!("SSLKEYLOGFILE is set — TLS session keys are being logged to disk");
+    }
+
+    let mut endpoints = Vec::with_capacity(config.addrs.len());
+    for addr in &config.addrs {
+        let endpoint = Endpoint::server(base_server_config.clone(), *addr)?;
+        tracing::info!("transport listening on {}", endpoint.local_addr()?);
+        let ep_clone = endpoint.clone();
+        tokio::spawn(accept_loop(
+            endpoint,
+            Arc::clone(&config.handlers),
+            Arc::clone(&config.trust),
+            config.label_lookup.clone(),
+        ));
+        endpoints.push(ep_clone);
+    }
+
+    Ok((fingerprint, endpoints))
+}
+
+async fn accept_loop(
+    endpoint: Endpoint,
+    handlers: Arc<AlpnHandlers>,
+    trust: Arc<ProtocolTrustRegistry>,
+    label_lookup: Option<LabelLookup>,
+) {
+    while let Some(incoming) = endpoint.accept().await {
+        let handlers = Arc::clone(&handlers);
+        let trust = Arc::clone(&trust);
+        let label_lookup = label_lookup.clone();
+        tokio::spawn(async move {
+            match incoming.await {
+                Ok(conn) => dispatch_connection(conn, handlers, trust, label_lookup).await,
+                Err(e) => tracing::warn!("incoming connection failed: {e}"),
+            }
+        });
+    }
+}
+
+async fn dispatch_connection(
+    conn: quinn::Connection,
+    handlers: Arc<AlpnHandlers>,
+    trust: Arc<ProtocolTrustRegistry>,
+    label_lookup: Option<LabelLookup>,
+) {
+    let alpn = match extract_negotiated_alpn(&conn) {
+        Some(a) => a,
+        None => {
+            tracing::warn!(
+                peer = %conn.remote_address(),
+                "connection without ALPN data; closing"
+            );
+            conn.close(quinn::VarInt::from_u32(0), b"missing alpn");
+            return;
+        }
+    };
+
+    let client_fp = extract_client_fp(&conn);
+
+    if let Some(fp) = client_fp.as_deref()
+        && !trust.is_trusted_for(&alpn, fp)
+    {
+        tracing::warn!(
+            fingerprint = %fp,
+            alpn = %String::from_utf8_lossy(&alpn),
+            "client fingerprint not authorised for negotiated ALPN; closing"
+        );
+        conn.close(quinn::VarInt::from_u32(0), b"alpn not authorised");
+        return;
+    }
+
+    let handler = match handlers.lookup(&alpn) {
+        Some(h) => h,
+        None => {
+            tracing::warn!(
+                alpn = %String::from_utf8_lossy(&alpn),
+                "no registered handler for negotiated ALPN; closing"
+            );
+            conn.close(quinn::VarInt::from_u32(0), b"alpn unhandled");
+            return;
+        }
+    };
+
+    let client_label = client_fp
+        .as_deref()
+        .and_then(|fp| label_lookup.as_ref().and_then(|f| f(fp)))
+        .or_else(|| client_fp.clone())
+        .unwrap_or_else(|| "unauthenticated".to_owned());
+
+    let ctx = ConnectionContext {
+        client_fp,
+        client_label,
+        negotiated_alpn: alpn,
+    };
+
+    handler(conn, ctx).await;
+}
+
+/// Read bytes from `recv` until a `\n` is found or `max_len` is reached.
+/// Returns `(line_including_newline, leftover_bytes_after_newline)`. On
+/// stream close before any data, returns `([], [])`.
+pub async fn read_json_line(
+    recv: &mut quinn::RecvStream,
+    max_len: usize,
+) -> Result<(Vec<u8>, Vec<u8>), quinn::ReadError> {
+    let mut buf = vec![0u8; max_len.min(65536)];
+    let mut total = 0usize;
+    loop {
+        let chunk_size = (max_len - total).min(1024);
+        if chunk_size == 0 {
+            break;
+        }
+        match recv.read(&mut buf[total..total + chunk_size]).await? {
+            Some(0) | None => break,
+            Some(n) => {
+                total += n;
+                if let Some(pos) = buf[..total].iter().position(|&b| b == b'\n') {
+                    let line = buf[..=pos].to_vec();
+                    let leftover = buf[pos + 1..total].to_vec();
+                    return Ok((line, leftover));
+                }
+            }
+        }
+    }
+    Ok((buf[..total].to_vec(), Vec::new()))
+}
diff --git a/crates/daemon/src/main.rs b/crates/daemon/src/main.rs
index 21c410ab..4d2df408 100644
--- a/crates/daemon/src/main.rs
+++ b/crates/daemon/src/main.rs
@@ -83,7 +83,7 @@ struct Args {
     listen: Vec<std::net::SocketAddr>,
 
     /// OI listen port, used with --interface. Conflicts with --listen.
-    #[arg(long, default_value_t = oi::DEFAULT_PORT, conflicts_with = "listen")]
+    #[arg(long, default_value_t = seedling_core::transport::endpoint::DEFAULT_PORT, conflicts_with = "listen")]
     port: u16,
 
     /// Upstream DNS servers for the in-pod CoreDNS resolver
@@ -1041,7 +1041,7 @@ async fn main() {
         scheduler: Arc::clone(&scheduler),
         tick_notify: Arc::clone(&tick_notify),
         db_path: db_path.clone(),
-        trusted_keys: seedling_core::oi::auth::new_trusted_keys(),
+        trusted_keys: seedling_core::transport::auth::new_trusted_keys(),
         shells,
         forwards: seedling_core::oi::forwards::ForwardRegistry::new(),
         container_runtime: Arc::clone(&driver.container),

From 87376ae15e9140bd83685099f3e9f1b03840af45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 21:43:07 +1200
Subject: [PATCH 03/11] plan: drop the OiState carve-out from commit 0

22-field OiState is mostly node-wide runtime state, not transport- or
OI-session-specific. The originally-planned TransportState/OiState/Daemon
restructure would touch every OI handler signature for limited cleanup
value. Grove lands GroveState as a sibling struct in commit 5 instead;
that gives the same handler-scoping property without the churn.

Also notes commit 0a as completed.
---
 docs/plans/grove.md | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/docs/plans/grove.md b/docs/plans/grove.md
index 75a1fb1c..8fc956cb 100644
--- a/docs/plans/grove.md
+++ b/docs/plans/grove.md
@@ -32,13 +32,9 @@ Refactor (lands before any grove-specific code):
 - Stays in `crates/core` rather than promoting to a new `crates/transport` crate for v0; promotion is a follow-up if multiple crates ever need server-side transport. The wire-type half (ALPN constants, dial-side `OiClient`, identity keys) remains in `crates/protocol/`.
 - ALPN handlers register with `transport` on startup: OI registers `bes.seedling/1`, grove registers `bes.grove/1`. The existing `oi/server.rs::handle_connection` body splits — generic per-connection logic moves to `transport`, OI-specific stream dispatch stays in `oi/`.
 
-`OiState` splits along the same seam:
-- New `TransportState`: endpoint handle, connection registry, identity, protocol trust registry. Owned by a top-level `Daemon` struct (renamed/replacing the current top-level container that wires everything up).
-- `OiState` (slimmed): OI-specific session/handler state — port-forward maps, log subscribers, event broadcasters.
-- New `GroveState`: publish mutex, dial-loop handle, dirty-mappings set, signed-payload cache.
-- `Daemon` holds `TransportState` + `OiState` + `GroveState`. Handlers receive only what they need (operator handlers don't see grove state, grove handlers don't see OI session state).
+For state, the smallest workable shape is to leave `OiState` alone and add `GroveState` as a sibling struct when grove lands (commit 5). The trust-set and fingerprint fields stay where they are: `OiState` owns the OI trust set, `GroveState` owns the grove trust set, and the `ProtocolTrustRegistry` (constructed at daemon startup and shared with both) is what couples them. Grove handlers capture `Arc<GroveState>` only; OI handlers continue capturing `Arc<OiState>`. The originally-planned `TransportState` / `OiState` carve-out + `Daemon` top-level container is **deferred** — it would touch every OI handler signature for limited cleanup value, and the sibling-struct approach gives the same handler-scoping property (operator handlers don't see grove state and vice versa) without the mechanical churn.
 
-This refactor is pure restructuring — no behavioural change, OI tests stay green. It lands as commit 0 (split into 0a/0b if the diff is large; see phasing).
+This refactor is pure restructuring — no behavioural change, OI tests stay green.
 
 ### Wire protocol — `bes.grove/1`
 
@@ -185,8 +181,8 @@ To modify:
 - `crates/core/src/transport/` — *new* module (commit 0). `endpoint.rs`, `auth.rs`, `connection.rs`, `framing.rs`. Holds quinn endpoint, ALPN handler registry, protocol-scoped trust registry, JSON-line framing. Replaces transport-level code currently inlined in `oi/server.rs` and `oi/auth.rs`.
 - `crates/core/src/oi/server.rs` — slimmed to OI-specific stream dispatch (port-forward, log streaming, event subscription, handler routing). Generic per-connection logic moves to `transport/`.
 - `crates/core/src/oi/auth.rs` — bootstrap-file loader stays here; trust-set machinery moves to `transport/auth.rs` as protocol-scoped sets (`OperatorTrust` for OI, `GroveTrust` for grove, registered against their ALPNs).
-- `crates/core/src/grove/` — *new* module. `state.rs` (`GroveState`: publish mutex, dial loop, dirty-mappings, signed-payload cache), `dial.rs` (connect loop), `apply.rs` (payload-apply pipeline + diff), `handler.rs` (registers `bes.grove/1` handler with transport, runs HELLO/VERSION/PEERS/abort exchange).
-- `crates/core/src/daemon.rs` (or wherever the top-level container lives — renamed/restructured if needed) — holds `TransportState` + `OiState` + `GroveState`. Handlers receive only the slice they need.
+- `crates/core/src/grove/` — *new* module. `state.rs` (`GroveState`: publish mutex, dial loop, dirty-mappings, signed-payload cache, grove trust set), `dial.rs` (connect loop), `apply.rs` (payload-apply pipeline + diff), `handler.rs` (registers `bes.grove/1` handler with transport, runs HELLO/VERSION/PEERS/abort exchange).
+- `crates/daemon/src/main.rs` — at startup, construct the shared `ProtocolTrustRegistry` and `AlpnHandlers`, then call `oi::register` and `grove::register` against them before `transport::endpoint::run`. No new top-level container struct; both states are held as `Arc<OiState>` and `Arc<GroveState>` siblings, captured into their respective handler closures.
 - `crates/core/src/oi/handler/params.rs` — extract `set_param_inner(... ParamSource)`, add `apply_grove_param_to_app` helper, rejection check on operator path.
 - `crates/core/src/oi/handler/grove.rs` — *new*. OI handlers for all `grove …` operations.
 - `crates/ctl/src/grove.rs` — *new*. CLI subcommand.
@@ -210,7 +206,7 @@ To reuse (don't reinvent):
 
 Each independently shippable, each with its own spec sections + tracey annotations. jj-friendly granularity.
 
-0. **Code restructure: extract `transport` module.** Pure refactor, no behavioural change, OI tests stay green. New `crates/core/src/transport/` (`endpoint`, `auth`, `connection`, `framing`); slim `oi/server.rs` and `oi/auth.rs` to OI-specific bits; split `OiState` into `TransportState` + `OiState`; introduce `Daemon` top-level container; OI registers itself as the `bes.seedling/1` ALPN handler through the new transport interface. Trust-set machinery becomes protocol-scoped (registry keyed by ALPN) but only `OperatorTrust` is registered at this point. Split into 0a (file moves + transport extraction) and 0b (state split) if the combined diff is unwieldy (~>600 lines).
+0. **Code restructure: extract `transport` module.** Pure refactor, no behavioural change, OI tests stay green. New `crates/core/src/transport/` (`endpoint`, `auth`); slim `oi/server.rs` and `oi/auth.rs` to OI-specific bits; OI registers itself as the `bes.seedling/1` ALPN handler through the new transport interface. Trust-set machinery becomes protocol-scoped (`ProtocolTrustRegistry` keyed by ALPN) but only OI is registered at this point. `OiState` is left alone — `GroveState` will land as a sibling in commit 5 rather than via a carve-out. *Done in `refactor(transport): extract shared QUIC endpoint, ALPN dispatch, and protocol-scoped trust`.*
 
 1. **Spec + tracey wiring.** Extract shared transport prose from `docs/spec/interface.md` into a new `docs/spec/transport.md` (`t[...]` namespace) covering RPK TLS, fingerprint pinning, ALPN as hard-version-wall, JSON-line framing, abort/error semantics, message-size caps. Update `interface.md` to reference `t[...]` for those items. Re-annotate the (now-moved) transport code from commit 0 with `t[impl ...]` instead of `i[impl ...]`. Add `docs/spec/grove.md` skeleton with all `g[...]` items including event names and "Known limitations", referencing `t[...]` for transport. Register `transport/main` and `grove/main` in `.config/tracey/config.styx`. `tracey query status` clean with stubbed requirements.
 2. **DB v53 migration.** All five tables, no consumers yet. Test: migration applies cleanly on a v52 DB.

From f8799e77bed6431e0cdcfdfb78cdf85eea78694c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 21:48:38 +1200
Subject: [PATCH 04/11] spec(transport, grove): split shared transport spec;
 add grove skeleton

- New docs/spec/transport.md (t[...] namespace) holds what is common to
  every application protocol on the shared QUIC endpoint: handshake,
  ALPN negotiation, server identity, raw-public-key client auth (now
  protocol-scoped), listen addresses, fingerprint probing.
- docs/spec/interface.md drops those items (now linked from transport.md)
  and gains a smaller i[trust.bootstrap] item describing the OI-specific
  bootstrap-file rule that was previously embedded in transport.client-auth.
- New docs/spec/grove.md is a skeleton of g[...] requirements covering
  identity, signed-payload versioning, membership, trust, wire protocol,
  onboarding, parameters, mappings, events, operator surface, and a
  Known limitations section. Code annotations land in later commits;
  for now grove items are uncovered, which tracey reports without error.
- .config/tracey/config.styx registers transport/main and grove/main.
- Existing transport-related code annotations move from i[transport.*]
  to t[*]: transport/endpoint.rs, protocol/lib.rs, protocol/client.rs,
  daemon/main.rs.
- import_bootstrap_file gains an i[impl trust.bootstrap] annotation.
---
 .config/tracey/config.styx            |  28 +++++
 crates/core/src/oi/auth.rs            |   1 +
 crates/core/src/transport/endpoint.rs |  10 +-
 crates/daemon/src/main.rs             |   6 +-
 crates/protocol/src/client.rs         |   6 +-
 crates/protocol/src/lib.rs            |   2 +-
 docs/spec/grove.md                    | 141 ++++++++++++++++++++++++++
 docs/spec/interface.md                |  46 ++-------
 docs/spec/transport.md                |  36 +++++++
 9 files changed, 224 insertions(+), 52 deletions(-)
 create mode 100644 docs/spec/grove.md
 create mode 100644 docs/spec/transport.md

diff --git a/.config/tracey/config.styx b/.config/tracey/config.styx
index 45c2f46b..e5d1b9f4 100644
--- a/.config/tracey/config.styx
+++ b/.config/tracey/config.styx
@@ -43,6 +43,34 @@ specs (
             }
         )
     }
+    {
+        name transport
+        source_url https://github.com/beyondessential/seedling
+        include (docs/spec/transport.md)
+        impls (
+            {
+                name main
+                include (
+                    crates/*/src/*.rs
+                    crates/*/src/**/*.rs
+                )
+            }
+        )
+    }
+    {
+        name grove
+        source_url https://github.com/beyondessential/seedling
+        include (docs/spec/grove.md)
+        impls (
+            {
+                name main
+                include (
+                    crates/*/src/*.rs
+                    crates/*/src/**/*.rs
+                )
+            }
+        )
+    }
     {
         name web
         source_url https://github.com/beyondessential/seedling
diff --git a/crates/core/src/oi/auth.rs b/crates/core/src/oi/auth.rs
index 21892b1f..f220d34c 100644
--- a/crates/core/src/oi/auth.rs
+++ b/crates/core/src/oi/auth.rs
@@ -27,6 +27,7 @@ pub fn load_from_db(db: &Db, trusted: &TrustedKeys) -> rusqlite::Result<()> {
 /// Read `$data_dir/authorized_keys` and import any entries not already in
 /// the DB. Lines have the form `<fingerprint> <label>`; `#` and blank lines
 /// are ignored.
+// i[impl trust.bootstrap]
 pub fn import_bootstrap_file(data_dir: &Path, db: &Db, trusted: &TrustedKeys) -> io::Result<()> {
     let path = data_dir.join("authorized_keys");
     if !path.exists() {
diff --git a/crates/core/src/transport/endpoint.rs b/crates/core/src/transport/endpoint.rs
index 4d0c91a3..36b103d6 100644
--- a/crates/core/src/transport/endpoint.rs
+++ b/crates/core/src/transport/endpoint.rs
@@ -116,7 +116,7 @@ fn build_tls_config(
         .with_cert_resolver(resolver);
 
     tls_config.key_log = Arc::new(rustls::KeyLogFile::new());
-    // i[transport.alpn]
+    // t[impl alpn]
     tls_config.alpn_protocols = alpn_list;
 
     Ok(tls_config)
@@ -138,10 +138,10 @@ fn extract_negotiated_alpn(conn: &quinn::Connection) -> Option<Vec<u8>> {
     hd.protocol
 }
 
-// i[transport.quic]
-// i[transport.server-identity]
-// i[transport.client-auth]
-// i[transport.listen]
+// t[impl quic]
+// t[impl server-identity]
+// t[impl client-auth]
+// t[impl listen]
 pub async fn run(
     config: EndpointConfig,
 ) -> Result<(String, Vec<Endpoint>), Box<dyn std::error::Error + Send + Sync>> {
diff --git a/crates/daemon/src/main.rs b/crates/daemon/src/main.rs
index 4d2df408..df81f2e3 100644
--- a/crates/daemon/src/main.rs
+++ b/crates/daemon/src/main.rs
@@ -71,7 +71,7 @@ struct Args {
     #[arg(long)]
     stub_backends: bool,
 
-    // i[transport.listen]
+    // t[impl listen]
     /// Network interface(s) to bind the OI on (comma-separated names).
     /// All IPv4 and IPv6 addresses of each interface are used.
     /// Failure to resolve a named interface is fatal.
@@ -1290,7 +1290,7 @@ async fn main() {
         });
     }
 
-    // i[transport.listen]
+    // t[impl listen]
     let oi_addrs = resolve_oi_addrs(&args.interface, &args.listen, args.port);
     let (_fingerprint, oi_endpoints) = oi::run(
         Arc::clone(&oi_state),
@@ -1558,7 +1558,7 @@ fn revert_install_and_fault(state: &Arc<OiState>, app_name: &AppName) {
     }
 }
 
-// i[transport.listen]
+// t[impl listen]
 fn resolve_oi_addrs(
     interfaces: &[String],
     explicit: &[std::net::SocketAddr],
diff --git a/crates/protocol/src/client.rs b/crates/protocol/src/client.rs
index 8765aa53..ff4c6f1b 100644
--- a/crates/protocol/src/client.rs
+++ b/crates/protocol/src/client.rs
@@ -276,7 +276,7 @@ impl OiClient {
             .with_custom_certificate_verifier(verifier)
             .with_client_cert_resolver(build_client_cert_resolver(identity)?);
         tls_config.key_log = Arc::new(rustls::KeyLogFile::new());
-        // i[transport.alpn]
+        // t[impl alpn]
         tls_config.alpn_protocols = vec![OI_ALPN.to_vec()];
 
         let quic_config = quinn::crypto::rustls::QuicClientConfig::try_from(tls_config)
@@ -458,14 +458,14 @@ impl OiClient {
             cell: Arc::clone(&cell),
         });
 
-        // i[transport.fingerprint-probe]
+        // t[impl fingerprint-probe]
         let ephemeral = super::keys::ClientIdentity::ephemeral();
         let mut tls_config = TlsClientConfig::builder()
             .dangerous()
             .with_custom_certificate_verifier(verifier)
             .with_client_cert_resolver(build_client_cert_resolver(&ephemeral)?);
         tls_config.key_log = Arc::new(rustls::KeyLogFile::new());
-        // i[transport.alpn] — probe must be indistinguishable from a real connection.
+        // t[impl alpn] — probe must be indistinguishable from a real connection.
         tls_config.alpn_protocols = vec![OI_ALPN.to_vec()];
 
         let quic_config = quinn::crypto::rustls::QuicClientConfig::try_from(tls_config)
diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rs
index 15036515..41646200 100644
--- a/crates/protocol/src/lib.rs
+++ b/crates/protocol/src/lib.rs
@@ -7,7 +7,7 @@ pub mod events;
 pub mod keys;
 pub mod names;
 
-// i[transport.alpn]
+// t[impl alpn]
 /// ALPN identifier negotiated for OI QUIC connections.
 ///
 /// Bumping this string is the lever for incompatible protocol revisions —
diff --git a/docs/spec/grove.md b/docs/spec/grove.md
new file mode 100644
index 00000000..ab87c317
--- /dev/null
+++ b/docs/spec/grove.md
@@ -0,0 +1,141 @@
+A **grove** is a group of seedling nodes that share a small set of leader-published settings. One node is designated leader; the rest are followers. The leader publishes a signed payload describing membership and grove-wide parameters; every member eventually receives the latest payload through peer-to-peer gossip over the shared transport. There is no quorum and no leader election: the leader is statically configured.
+
+The smallest useful grove behaviour is **grove parameters**: typed name/value pairs published by the leader. On each follower (and on the leader itself), an operator can independently bind any local app param to a grove param. When the bound grove param's value changes, the app param is updated as if an operator had set it locally — through the existing param-set pathway, including `on_change` execution. While such a binding exists, manual operator set or unset of that app param is rejected.
+
+The grove protocol shares the seedling transport (see [transport.md](transport.md)). The grove ALPN identifier is `bes.grove/1`. Grove membership is a separate trust grant from operator interface access (per [t[client-auth]](transport.md)): a grove member key does not authorise the OI, and an operator key does not authorise grove gossip, unless the same fingerprint is independently registered with both.
+
+# Identity
+
+> g[identity]
+> Each seedling node is a member of at most one grove at a time. The grove is identified by a stable 16-byte `grove_id` generated by the leader at grove-init time.
+> A node's role within the grove is either *leader* or *follower*; this is static configuration, not negotiated.
+> Each node persists the grove id, its own role, and the leader's SPKI fingerprint. Followers reject any signed payload not signed by the pinned leader fingerprint.
+
+# Versioning and signed payloads
+
+> g[versioning.seq]
+> Every published grove payload carries a strictly increasing 64-bit sequence number. Followers reject any payload with sequence ≤ their currently-applied sequence. The leader is the sole publisher; followers never originate payloads.
+
+> g[versioning.signature]
+> Each published payload is signed by the leader's transport identity key (Ed25519). The signature covers a domain-separated canonical encoding of the payload (canonical JSON per RFC 8785, prefixed with `bes.grove/sig/v1\0`). Followers verify the signature against the pinned leader fingerprint before applying.
+
+> g[versioning.payload-fields]
+> A grove payload contains: the grove id, sequence number, creation timestamp, leader fingerprint, an ordered membership list, an ordered grove-parameter list, and a (currently always empty) secrets list reserved for future envelope-encrypted secret parameters. The encoding is full-state — there is no incremental delta format in this version.
+
+> g[versioning.size-cap]
+> The on-wire signed payload has a hard upper bound (256 KiB). Leader mutations (membership change, grove-parameter set) that would push the next payload over this bound are rejected at the point of mutation, before sequence number is bumped or signature is computed. Followers reject inbound payloads that exceed this bound.
+
+> g[versioning.timestamp-skew]
+> Followers reject inbound payloads whose `created_at` lies outside ±5 minutes of the receiver's clock. The grove sequence number is the authoritative ordering; the timestamp exists only to bound payload age and prevent indefinite replay of stale-but-valid signed payloads.
+
+# Membership
+
+> g[membership.canonical]
+> The leader's signed payload is the canonical source of grove membership. Any change to membership (invite, revoke) is published as a new signed payload with an incremented sequence number.
+
+> g[membership.invite]
+> Only the leader may add a node to the grove. The leader records the new member's SPKI fingerprint and a human label, signs the new payload, and publishes.
+> Once added, the new member is authoritatively part of the grove only after some current member receives the signed payload that includes them. New nodes do not need a direct connection to the leader to join (see [g[bootstrap.join]](#g--bootstrap.join)).
+
+> g[membership.revoke]
+> Only the leader may remove a node from the grove. After revocation, peers who have applied the new payload close any open grove connections to the revoked fingerprint and reject new ones.
+> Revocation removes only grove authority; the revoked node's transport identity is otherwise unaffected, and access to other application protocols (e.g. the OI) is independent.
+
+> g[membership.bootstrap]
+> Initially, a grove has exactly one member: the leader, set up via grove init. The leader publishes its first payload (sequence = 1) immediately on init.
+
+# Trust
+
+> g[trust]
+> Each grove member maintains a `bes.grove/1` authorised-keys set derived from the latest applied signed payload's membership list. The set is reconciled on every payload-applied event: members added in the new payload are added, members removed are removed.
+> The grove trust set is independent of the OI authorised-keys set (per [t[client-auth]](transport.md)).
+
+# Wire protocol
+
+> g[wire.alpn]
+> Grove gossip uses the ALPN identifier `bes.grove/1` on the shared transport.
+
+> g[wire.framing]
+> Each grove connection uses one client-initiated bidirectional QUIC stream carrying newline-delimited JSON messages.
+
+> g[wire.hello]
+> Both sides of a grove connection send a `hello` message immediately upon stream open. The message includes the sender's grove id, currently-applied sequence number, hash of the currently-applied payload, role, sender fingerprint, an in-payload protocol version, and a random nonce.
+> If grove ids differ, the receiver aborts. If sequence numbers match but payload hashes differ, the receiver aborts (the leader is publishing inconsistent payloads under the same sequence — a fault).
+
+> g[wire.version]
+> If the two peers report different sequence numbers in their `hello`, the side holding the higher sequence sends a `version` message containing the full signed payload. The receiver validates signature, sequence-strict-greater, payload-size, and timestamp-skew, then persists and applies the payload. Receivers bound the inbound message at the published payload-size cap.
+
+> g[wire.peers]
+> Each side may send a `peers` message containing address-hint entries for known grove members: SPKI fingerprint, observed addresses, and a sender-supplied last-seen timestamp. Membership itself is not learned this way — entries whose fingerprint is not in the receiver's current membership list are dropped.
+> Address gossip is bounded: receivers cap the number of entries and the number of addresses per entry, and treat the sender-supplied last-seen as a hint, not as authoritative liveness.
+
+> g[wire.abort]
+> Either peer may send an `abort` message to signal a protocol-level rejection before closing the connection. The reason is one of: `grove_mismatch`, `signature_invalid`, `seq_regression`, `leader_mismatch`, `version_too_old`, `payload_too_large`, or other documented codes.
+
+# Connect loop
+
+> g[peers.dial]
+> Each grove member periodically attempts grove connections to a small subset of known peers, prioritising those with stale or unknown last-connected timestamps. Inbound connections are accepted on the shared listener and dispatched by negotiated ALPN.
+> The dial loop persists the last-connected timestamp per peer; this is what `grove peers` surfaces.
+
+# Onboarding
+
+> g[bootstrap.init]
+> The grove is created on the designated leader by an operator-issued init action. Init generates the grove id and persists the initial signed payload (sequence = 1, members = [self]).
+
+> g[bootstrap.invite-flow]
+> Adding a member is a two-step coordination: (1) the operator on the leader runs an invite action with the new member's fingerprint and label, which appends the member to the canonical list and publishes a new payload; (2) the operator on the new node runs a join action with one current member's address and fingerprint, plus the leader's fingerprint, all supplied out-of-band.
+
+> g[bootstrap.join]
+> The new node connects to the supplied current member (which need not be the leader), receives the latest signed payload, validates the signature against the supplied leader fingerprint, and persists. Once joined, the new node attempts to reach all other members listed in the payload.
+
+# Grove parameters
+
+> g[params.kind]
+> A grove parameter is a typed name/value pair. The set of supported types matches the app-param schema language sufficiently to allow lossless mapping onto any compatible app param.
+
+> g[params.set]
+> Only the leader may set or unset grove parameters. A set or unset is published as a new signed payload with an incremented sequence number.
+
+> g[params.no-secrets]
+> Grove parameters in this version may not be marked secret. An attempt to publish a secret grove parameter is rejected at the point of mutation. (Future versions will support per-member envelope encryption via the reserved `secrets` payload field.)
+
+# Mapping
+
+> g[mapping]
+> An operator on any grove member may bind any local app param to any grove parameter. The binding is local to that node — bindings are not replicated through the grove.
+> Creating a binding is rejected if the app, app param, or grove parameter does not exist; if the same app param is already bound; if the grove parameter's current value cannot be coerced to the app param's declared type; or if a lifecycle operation is in progress on the app.
+> Removing a binding leaves the app param at its current value (no automatic revert).
+
+> g[mapping.reject-local-set]
+> While an app param has an active grove binding, manual operator set or unset of that app param is rejected with a structured error. The grove value (or its absence) is the only authoritative source.
+
+> g[mapping.actuate]
+> When a grove parameter changes — at binding-creation time, when a new payload is applied, or when the parameter is removed — every node with a matching binding applies the change to the bound app param through the same internal pathway as an operator-initiated set or unset. The app's `on_change` handler runs as it would for an operator-initiated change. The actor recorded for the change identifies the grove and the publishing sequence number.
+
+> g[mapping.deferred]
+> If actuation cannot proceed because the app is in a lifecycle operation, the grove value is recorded as pending and applied as soon as the app returns to an idle state.
+
+# Events
+
+> g[events]
+> Grove activity is surfaced through events with stable names: `grove.payload-received`, `grove.payload-applied`, `grove.payload-rejected`, `grove.publish-rejected`, `grove.peer-connected`, `grove.peer-disconnected`, `grove.member-revoked`, `grove.mapping-created`, `grove.mapping-removed`, `grove.param-applied`, `grove.param-deferred`. Operators rely on this stream to observe propagation and audit grove-driven changes to app params.
+
+# Operator surface
+
+> g[surface.parity]
+> Every grove operator action is available on all three operator surfaces: CLI (`seedling-ctl grove …`), OI handler endpoints, and the web UI. This includes status, member list, parameter list, peer connectivity (currently-connected vs last-connected for known-but-not-connected peers), mapping list, and all leader-only mutations.
+
+> g[surface.role-gate]
+> Leader-only actions are rejected on followers regardless of which surface invoked them, with a structured error identifying the current leader fingerprint.
+
+# Known limitations
+
+> g[limitation.lost-leader-key]
+> If the leader's transport identity key becomes unavailable, the grove cannot publish further valid payloads and existing payloads become the permanent state. Recovery requires an out-of-band fork: any follower may be promoted to a new self-only leader, and the remaining members re-join. This recovery path is not implemented in this version.
+
+> g[limitation.no-secrets]
+> Secret grove parameters are not supported. The signed-payload encoding reserves a `secrets` field so a future version can add per-member envelope encryption without a schema break.
+
+> g[limitation.no-multi-grove]
+> A node belongs to at most one grove. Schema and protocol assume single-grove membership; multi-grove membership is not a future extension of this design.
diff --git a/docs/spec/interface.md b/docs/spec/interface.md
index fbf9ab02..14cd67cd 100644
--- a/docs/spec/interface.md
+++ b/docs/spec/interface.md
@@ -7,49 +7,15 @@ Absent specification bugs, anything that is not defined here is either defined i
 
 # Transport
 
-> i[transport.quic]
-> The OI uses QUIC as its wire transport protocol.
-
-> i[transport.alpn]
-> The TLS handshake negotiates an Application-Layer Protocol Negotiation (ALPN) identifier.
-> Both client and server must offer the same identifier; a connection where the peer does not offer the expected identifier is rejected at the TLS layer.
-> The current identifier is `bes.seedling/1`. Future incompatible protocol revisions are introduced by adding a new identifier; the negotiation result selects the variant.
-
-> i[transport.server-identity]
-> The server authenticates using an RFC 7250 raw public key (SPKI).
-> The server's key pair is generated at first startup and persisted to the data directory so that clients can pin the SPKI fingerprint across restarts.
-> Clients verify the server by its SPKI fingerprint; certificate chain validation is not used.
-
-> i[transport.listen]
-> The server may be configured to listen on one or more addresses at startup.
-> All configured addresses share the same server identity (key pair and SPKI fingerprint) and the same authorized key set.
-> When no addresses are explicitly configured, the server listens on a single loopback address on the default port.
-
-> i[transport.fingerprint-probe]
-> When a client connects to a server whose fingerprint is not yet in its known-hosts store, it must
-> first capture the server's SPKI fingerprint without revealing its real identity to the server.
-> The probe connection must present a raw public key as its mTLS client certificate, but the key
-> used must be a freshly-generated, single-use key that is discarded immediately after the probe.
-> The server will reject the probe connection (the ephemeral key is not authorised), but the
-> server's SPKI fingerprint is captured during the TLS handshake before that rejection occurs.
-> After capturing the fingerprint the client must confirm it with the user before proceeding with
-> an authenticated connection using the real client identity.
-> The probe connection must be structurally indistinguishable from a normal authenticated
-> connection: a network observer or the server itself cannot determine whether a given connection
-> is a probe or a real session.
-
-> i[transport.client-auth]
-> Every client connection must present a raw public key (RFC 7250 SPKI) as its mTLS certificate.
-> The server maintains a set of authorized client SPKI fingerprints in persistent storage.
-> A connection whose client certificate fingerprint is not in the authorized set is rejected at the TLS layer.
->
-> On startup the server reads `$data_dir/authorized_keys` and imports any entries not already in
-> persistent storage. Each non-comment line in that file has the form:
+The OI runs over the shared seedling transport (see [transport.md](transport.md)) for the QUIC handshake, ALPN negotiation, server identity, client authentication, listen addresses, and fingerprint probing. The OI's ALPN identifier is `bes.seedling/1`.
+
+> i[trust.bootstrap]
+> On startup the server reads `$data_dir/authorized_keys` and imports any entries not already in persistent storage. Each non-comment line in that file has the form:
 > ```
 > <sha256-hex-fingerprint> <label>
 > ```
-> This file is the initial bootstrap mechanism: an operator with write access to the data directory
-> can authorize a client key without requiring a prior authenticated connection.
+> This file is the initial bootstrap mechanism for the OI authorised-keys set: an operator with write access to the data directory can authorise a client key without requiring a prior authenticated connection.
+> The OI authorised-keys set is OI-specific (per [t[client-auth]](transport.md)); membership in this set does not grant access to other application protocols on the shared transport.
 
 # Streams
 
diff --git a/docs/spec/transport.md b/docs/spec/transport.md
new file mode 100644
index 00000000..cd472974
--- /dev/null
+++ b/docs/spec/transport.md
@@ -0,0 +1,36 @@
+The shared seedling transport is a QUIC-based duplex channel that carries one or more application-layer protocols, each identified by a distinct ALPN value. Different protocols (operator interface, grove, …) share the same listener, server identity, and TLS handshake; they differ in the ALPN they negotiate and the per-stream framing they use after the handshake completes.
+
+Each application protocol defines its own spec. The items below describe what is common to all of them.
+
+# Handshake
+
+> t[quic]
+> The shared transport uses QUIC as its wire protocol.
+
+> t[alpn]
+> The TLS handshake negotiates an Application-Layer Protocol Negotiation (ALPN) identifier.
+> Both client and server must offer the same identifier; a connection where the peer does not offer an expected identifier is rejected at the TLS layer.
+> Each application protocol on the shared transport defines its own ALPN identifier. Future incompatible revisions of a protocol are introduced by adding a new identifier; the negotiation result selects the variant.
+
+> t[server-identity]
+> The server authenticates using an RFC 7250 raw public key (SPKI).
+> The server's key pair is generated at first startup and persisted to the data directory so that clients can pin the SPKI fingerprint across restarts. The same key pair is used for every ALPN registered on the transport.
+> Clients verify the server by its SPKI fingerprint; certificate chain validation is not used.
+
+> t[client-auth]
+> Every client connection must present a raw public key (RFC 7250 SPKI) as its mTLS certificate.
+> The server maintains a per-protocol authorised-keys set: each ALPN registers its own set of authorised client SPKI fingerprints. A client fingerprint may appear in zero, one, or more such sets — protocols are independent trust grants.
+> Per-protocol authorisation is enforced after the TLS handshake completes, against the negotiated ALPN: a connection whose client certificate fingerprint is not in the trust set for the negotiated ALPN is rejected immediately, before any application data is exchanged.
+> At TLS handshake time the verifier accepts any fingerprint trusted by any registered protocol. (TLS client-cert verification runs before the negotiated ALPN is observable to the verifier; the per-ALPN gate is therefore enforced post-handshake.)
+
+> t[fingerprint-probe]
+> When a client connects to a server whose fingerprint is not yet in its known-hosts store, it must first capture the server's SPKI fingerprint without revealing its real identity to the server.
+> The probe connection must present a raw public key as its mTLS client certificate, but the key used must be a freshly-generated, single-use key that is discarded immediately after the probe.
+> The server will reject the probe connection (the ephemeral key is not authorised for any registered protocol), but the server's SPKI fingerprint is captured during the TLS handshake before that rejection occurs.
+> After capturing the fingerprint the client must confirm it with the user before proceeding with an authenticated connection using the real client identity.
+> The probe connection must be structurally indistinguishable from a normal authenticated connection: a network observer or the server itself cannot determine whether a given connection is a probe or a real session.
+
+> t[listen]
+> The server may be configured to listen on one or more addresses at startup.
+> All configured addresses share the same server identity (key pair and SPKI fingerprint), the same set of registered ALPNs, and the same per-ALPN authorised-keys sets.
+> When no addresses are explicitly configured, the server listens on a single loopback address on the default port.

From 265853ae3a88b7ceade417a2a6af170b2bb3603a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 21:54:00 +1200
Subject: [PATCH 05/11] feat(db): add v53 migration with grove tables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds five tables under v53.sql, no consumers yet — they land alongside
the protocol implementation in later commits.

- grove_membership (single-row, id CHECK = 1): the grove this node
  belongs to, the role, the pinned leader fingerprint, and the verbatim
  signed payload + signature for the currently-applied sequence.
- grove_peers: per-fingerprint hint cache for the dial loop and the
  'grove peers' surface (label, addresses, last-seen, last-connected).
- grove_params: denormalised projection of the latest payload's grove
  parameters, for query convenience. The signed payload remains the
  canonical source.
- grove_param_mappings: local-only bindings between local app params
  and grove parameter names. Never replicated.
- grove_versions: history of all applied signed payloads keyed by seq,
  with INSERT OR IGNORE making duplicate apply idempotent.

Tests verify the tables exist after migration and that the single-row
constraint on grove_membership is enforced. The version-cap assertions
in existing migration tests bump 52 → 53.
---
 crates/core/src/runtime/db.rs                 | 15 +++++
 crates/core/src/runtime/db/migrations/v53.sql | 63 +++++++++++++++++++
 crates/core/src/runtime/db/tests.rs           | 50 ++++++++++++++-
 3 files changed, 126 insertions(+), 2 deletions(-)
 create mode 100644 crates/core/src/runtime/db/migrations/v53.sql

diff --git a/crates/core/src/runtime/db.rs b/crates/core/src/runtime/db.rs
index a3f1cd17..fb16741a 100644
--- a/crates/core/src/runtime/db.rs
+++ b/crates/core/src/runtime/db.rs
@@ -126,6 +126,16 @@ const SQL_V50: &str = include_str!("db/migrations/v50.sql");
 const SQL_V51: &str = include_str!("db/migrations/v51.sql");
 // r[impl infra.proxy.upgrade.cache]
 const SQL_V52: &str = include_str!("db/migrations/v52.sql");
+// g[impl identity]
+// g[impl membership.canonical]
+// g[impl versioning.seq]
+// g[impl versioning.payload-fields]
+// g[impl peers.dial]
+// g[impl params.kind]
+// g[impl params.set]
+// g[impl mapping]
+// g[impl mapping.reject-local-set]
+const SQL_V53: &str = include_str!("db/migrations/v53.sql");
 
 const MIGRATIONS: &[Migration] = &[
     Migration {
@@ -383,6 +393,11 @@ const MIGRATIONS: &[Migration] = &[
         sql: SQL_V52,
         custom_run: None,
     },
+    Migration {
+        version: 53,
+        sql: SQL_V53,
+        custom_run: None,
+    },
 ];
 
 fn migration_hash(sql: &str) -> String {
diff --git a/crates/core/src/runtime/db/migrations/v53.sql b/crates/core/src/runtime/db/migrations/v53.sql
new file mode 100644
index 00000000..217f9a3a
--- /dev/null
+++ b/crates/core/src/runtime/db/migrations/v53.sql
@@ -0,0 +1,63 @@
+-- g[impl identity]
+-- g[impl membership.canonical]
+-- g[impl versioning.seq]
+-- g[impl versioning.payload-fields]
+-- The grove this node belongs to. Single-row table (id is constrained to 1):
+-- a node belongs to at most one grove at a time. The currently-applied
+-- signed payload is stored verbatim so it can be re-applied (idempotent),
+-- re-served to peers, and re-verified against the pinned leader key.
+CREATE TABLE grove_membership (
+    id                  INTEGER PRIMARY KEY CHECK (id = 1),
+    grove_id            BLOB    NOT NULL,
+    role                TEXT    NOT NULL CHECK (role IN ('leader', 'follower')),
+    leader_fingerprint  TEXT    NOT NULL,
+    current_seq         INTEGER NOT NULL,
+    current_payload     BLOB    NOT NULL,
+    current_signature   BLOB    NOT NULL,
+    joined_at           TEXT    NOT NULL
+);
+
+-- g[impl peers.dial]
+-- Hint cache for the dial loop and the `grove peers` operator surface.
+-- Membership itself is derived from the currently-applied signed payload
+-- in grove_membership; this table only caches connection metadata.
+CREATE TABLE grove_peers (
+    fingerprint         TEXT PRIMARY KEY,
+    label               TEXT,
+    addresses_json      TEXT NOT NULL,
+    last_seen_at        TEXT,
+    last_connected_at   TEXT
+);
+
+-- g[impl params.kind]
+-- g[impl params.set]
+-- Denormalised projection of the latest signed payload's grove parameters.
+-- The signed payload in grove_membership remains canonical; if the two
+-- ever disagree, the payload wins.
+CREATE TABLE grove_params (
+    name                TEXT PRIMARY KEY,
+    kind                TEXT    NOT NULL,
+    value               TEXT    NOT NULL,
+    version_seq         INTEGER NOT NULL
+);
+
+-- g[impl mapping]
+-- g[impl mapping.reject-local-set]
+-- Local-only bindings between local app params and grove parameter names.
+-- Never replicated; each node maintains its own mappings.
+CREATE TABLE grove_param_mappings (
+    app_name            TEXT NOT NULL,
+    app_param_name      TEXT NOT NULL,
+    grove_param_name    TEXT NOT NULL,
+    PRIMARY KEY (app_name, app_param_name)
+);
+
+-- History of all applied signed payloads, for replay and debug. Idempotent
+-- apply uses INSERT OR IGNORE on the primary key to no-op a duplicate
+-- delivery of the same sequence number.
+CREATE TABLE grove_versions (
+    seq                 INTEGER PRIMARY KEY,
+    payload             BLOB NOT NULL,
+    signature           BLOB NOT NULL,
+    received_at         TEXT NOT NULL
+);
diff --git a/crates/core/src/runtime/db/tests.rs b/crates/core/src/runtime/db/tests.rs
index 3f7deb48..80bf133b 100644
--- a/crates/core/src/runtime/db/tests.rs
+++ b/crates/core/src/runtime/db/tests.rs
@@ -13,7 +13,7 @@ fn open_in_memory_succeeds() {
             |r| r.get(0),
         )
         .expect("schema_version should exist");
-    assert_eq!(version, 52);
+    assert_eq!(version, 53);
 }
 
 // r[verify history.persistence]
@@ -45,7 +45,7 @@ fn params_table_exists() {
             |r| r.get(0),
         )
         .expect("schema_version should exist");
-    assert_eq!(version, 52);
+    assert_eq!(version, 53);
 }
 
 // i[verify app.persist]
@@ -66,6 +66,52 @@ fn registered_apps_table_exists() {
     );
 }
 
+// g[verify identity]
+// g[verify membership.canonical]
+// g[verify mapping]
+// g[verify peers.dial]
+#[test]
+fn grove_tables_exist_after_migration() {
+    let db = Db::open_in_memory().expect("open");
+    let tables = [
+        "grove_membership",
+        "grove_peers",
+        "grove_params",
+        "grove_param_mappings",
+        "grove_versions",
+    ];
+    for table in &tables {
+        let count: i64 = db
+            .conn
+            .query_row(
+                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
+                [table],
+                |r| r.get(0),
+            )
+            .unwrap_or(0);
+        assert_eq!(count, 1, "table '{}' should exist", table);
+    }
+}
+
+// g[verify identity]
+#[test]
+fn grove_membership_id_is_constrained_to_one_row() {
+    let db = Db::open_in_memory().expect("open");
+    db.conn
+        .execute(
+            "INSERT INTO grove_membership (id, grove_id, role, leader_fingerprint, current_seq, current_payload, current_signature, joined_at) \
+             VALUES (1, x'00', 'leader', 'fp', 1, x'00', x'00', '2026-01-01T00:00:00Z')",
+            [],
+        )
+        .expect("first row should insert");
+    let res = db.conn.execute(
+        "INSERT INTO grove_membership (id, grove_id, role, leader_fingerprint, current_seq, current_payload, current_signature, joined_at) \
+         VALUES (2, x'00', 'leader', 'fp', 1, x'00', x'00', '2026-01-01T00:00:00Z')",
+        [],
+    );
+    assert!(res.is_err(), "id != 1 must be rejected by CHECK constraint");
+}
+
 // r[verify history.world.entries]
 // r[verify history.operations.entries]
 // r[verify history.action-log.entries]

From 4b231edb300e010e5c8bec6907a6bcb222d07f85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 22:00:17 +1200
Subject: [PATCH 06/11] feat(protocol/grove): payload, message types, JCS
 sign/verify

A pure-types module: no transport, DB, or filesystem dependency, so both
the daemon and seedling-ctl can sign and verify payloads independently.

- Payload struct mirrors the spec's payload field list (grove_id, seq,
  created_at, leader_fp, members, params, secrets). canonicalise() sorts
  members by fingerprint and params by name; canonical_json() produces
  JCS bytes (RFC 8785); signing_bytes() prepends the bes.grove/sig/v1
  domain separator.
- Payload::sign canonicalises before signing, so callers do not need to.
- SignedPayload pairs payload + Ed25519 signature; signature is a hex
  string on the JSON wire. SignedPayload::verify checks the signature
  against a leader VerifyingKey.
- Message tagged union covers hello/version/peers/abort. Hello includes
  a payload_hash so peers reporting the same seq can detect leader-side
  forks.
- Tests: round-trip sign/verify, verify-fails-under-wrong-key,
  verify-fails-after-mutation, signing-bytes-starts-with-domain-separator,
  canonicalise sorts, signed bytes invariant under input ordering,
  Message JSON round-trip, payload_hash is order-stable.

Adds serde_jcs 0.2.0 and hex 0.4.3 (with serde feature) to
crates/protocol/Cargo.toml.
---
 Cargo.lock                   |  22 ++
 crates/protocol/Cargo.toml   |   2 +
 crates/protocol/src/grove.rs | 406 +++++++++++++++++++++++++++++++++++
 crates/protocol/src/lib.rs   |   1 +
 4 files changed, 431 insertions(+)
 create mode 100644 crates/protocol/src/grove.rs

diff --git a/Cargo.lock b/Cargo.lock
index 864bf0c1..dab99d1f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2226,6 +2226,9 @@ name = "hex"
 version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+dependencies = [
+ "serde",
+]
 
 [[package]]
 name = "hex-literal"
@@ -4423,6 +4426,12 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
+[[package]]
+name = "ryu-js"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6518fc26bced4d53678a22d6e423e9d8716377def84545fe328236e3af070e7f"
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -4628,6 +4637,7 @@ dependencies = [
  "dirs 6.0.0",
  "ed25519-dalek",
  "futures-util",
+ "hex",
  "jiff",
  "quinn",
  "rand_core 0.6.4",
@@ -4635,6 +4645,7 @@ dependencies = [
  "rustls 0.23.40",
  "rustls-pki-types",
  "serde",
+ "serde_jcs",
  "serde_json",
  "sha2 0.11.0",
  "subtle",
@@ -4719,6 +4730,17 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_jcs"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3a60f3fda61525e439ef6d67422118f11e986566997d9021c56867ad814a0aa"
+dependencies = [
+ "ryu-js",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "serde_json"
 version = "1.0.150"
diff --git a/crates/protocol/Cargo.toml b/crates/protocol/Cargo.toml
index 1969326a..9ab45576 100644
--- a/crates/protocol/Cargo.toml
+++ b/crates/protocol/Cargo.toml
@@ -9,6 +9,7 @@ compact_str = { version = "0.9.1", features = ["serde"] }
 dirs.workspace = true
 ed25519-dalek.workspace = true
 futures-util.workspace = true
+hex = { version = "0.4.3", features = ["serde"] }
 jiff.workspace = true
 quinn.workspace = true
 rand_core.workspace = true
@@ -16,6 +17,7 @@ rusqlite = { version = "0.39.0", features = ["bundled"], optional = true }
 rustls.workspace = true
 rustls-pki-types.workspace = true
 serde.workspace = true
+serde_jcs = "0.2.0"
 serde_json.workspace = true
 sha2.workspace = true
 subtle.workspace = true
diff --git a/crates/protocol/src/grove.rs b/crates/protocol/src/grove.rs
new file mode 100644
index 00000000..7cc33e81
--- /dev/null
+++ b/crates/protocol/src/grove.rs
@@ -0,0 +1,406 @@
+//! Grove signed payload, wire messages, and signing primitives.
+//!
+//! Canonical encoding: [serde_jcs] (RFC 8785) over the serde representation
+//! of [`Payload`], with a `bes.grove/sig/v1\0` domain-separator prefix on
+//! the bytes that are actually signed. Signatures are Ed25519 over those
+//! bytes, using the leader's transport identity key (see [`super::keys`]).
+//!
+//! No transport, DB, or filesystem dependency: this module is pure types
+//! and pure functions, depended on by both the daemon (commit-4 onward)
+//! and `seedling-ctl` (commit-6) so each side can independently sign and
+//! verify without going through the core crate.
+
+use std::fmt;
+
+use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
+use jiff::Timestamp;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use uuid::Uuid;
+
+/// Domain separator prefix prepended to canonical-JSON payload bytes
+/// before signing or verifying. Bumping the trailing version requires a
+/// new ALPN.
+pub const SIG_DOMAIN_V1: &[u8] = b"bes.grove/sig/v1\0";
+
+/// ALPN identifier negotiated for grove gossip on the shared transport.
+// g[impl wire.alpn]
+pub const GROVE_ALPN: &[u8] = b"bes.grove/1";
+
+/// In-payload wire-protocol version, independent of the ALPN. Bumped for
+/// soft (backwards-compatible) feature flags; a hard break uses a new ALPN.
+pub const PROTOCOL_VERSION: u16 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Member {
+    pub fp: String,
+    pub label: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Param {
+    pub name: String,
+    pub kind: String,
+    pub value: String,
+}
+
+/// Reserved for future per-member envelope-encrypted secret parameters.
+/// Always empty on the wire in this protocol version.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SecretEntry {
+    pub name: String,
+}
+
+/// Canonical body of a published grove version.
+///
+/// Fields are serialised in declaration order; collections are sorted by
+/// the relevant key inside [`Self::canonicalise`] so the JCS encoding is
+/// deterministic regardless of insertion order.
+// g[impl versioning.payload-fields]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Payload {
+    pub grove_id: Uuid,
+    pub seq: u64,
+    pub created_at: Timestamp,
+    pub leader_fp: String,
+    pub members: Vec<Member>,
+    pub params: Vec<Param>,
+    /// Always empty on the wire in this protocol version.
+    pub secrets: Vec<SecretEntry>,
+}
+
+impl Payload {
+    /// Sort members by `fp` and params by `name` so that the canonical
+    /// encoding is invariant under insertion order.
+    pub fn canonicalise(&mut self) {
+        self.members.sort_by(|a, b| a.fp.cmp(&b.fp));
+        self.params.sort_by(|a, b| a.name.cmp(&b.name));
+    }
+
+    /// Produce the canonical-JSON bytes (RFC 8785) of this payload.
+    pub fn canonical_json(&self) -> Result<Vec<u8>, GroveError> {
+        serde_jcs::to_vec(self).map_err(GroveError::Encode)
+    }
+
+    /// Bytes that are actually signed: domain separator || canonical JSON.
+    // g[impl versioning.signature]
+    pub fn signing_bytes(&self) -> Result<Vec<u8>, GroveError> {
+        let mut buf = SIG_DOMAIN_V1.to_vec();
+        buf.extend_from_slice(&self.canonical_json()?);
+        Ok(buf)
+    }
+
+    /// Sign the payload with the leader's signing key.
+    ///
+    /// Canonicalises first, so callers do not need to remember to.
+    // g[impl versioning.signature]
+    pub fn sign(mut self, key: &SigningKey) -> Result<SignedPayload, GroveError> {
+        self.canonicalise();
+        let bytes = self.signing_bytes()?;
+        let sig = key.sign(&bytes);
+        Ok(SignedPayload {
+            payload: self,
+            signature: sig.to_bytes().to_vec(),
+        })
+    }
+}
+
+/// A grove payload paired with its Ed25519 signature.
+///
+/// On the wire, the signature is encoded as a lowercase hex string.
+// g[impl wire.version]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SignedPayload {
+    pub payload: Payload,
+    #[serde(with = "hex::serde")]
+    pub signature: Vec<u8>,
+}
+
+impl SignedPayload {
+    /// Verify the signature against the leader's verifying key.
+    // g[impl versioning.signature]
+    pub fn verify(&self, leader: &VerifyingKey) -> Result<(), GroveError> {
+        let sig = Signature::try_from(self.signature.as_slice())
+            .map_err(|e| GroveError::Signature(format!("malformed signature: {e}")))?;
+        let bytes = self.payload.signing_bytes()?;
+        leader
+            .verify(&bytes, &sig)
+            .map_err(|e| GroveError::Signature(format!("verification failed: {e}")))
+    }
+
+    /// SHA-256 of the canonical signing bytes, hex-encoded. Used as the
+    /// `our_payload_hash` field of a [`Hello`] so that two peers reporting
+    /// the same `seq` can detect a leader-side fork.
+    pub fn payload_hash(&self) -> Result<String, GroveError> {
+        let bytes = self.payload.signing_bytes()?;
+        let mut s = String::with_capacity(64);
+        for b in Sha256::digest(&bytes) {
+            use std::fmt::Write as _;
+            write!(s, "{b:02x}").expect("hex write");
+        }
+        Ok(s)
+    }
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+    Leader,
+    Follower,
+}
+
+/// First message exchanged on a fresh grove connection by both sides.
+// g[impl wire.hello]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Hello {
+    pub grove_id: Uuid,
+    pub our_seq: u64,
+    pub our_payload_hash: String,
+    pub our_role: Role,
+    pub our_fingerprint: String,
+    pub protocol_version: u16,
+    pub nonce: u64,
+}
+
+/// Address-hint gossip entry. `last_seen` is sender-supplied and treated
+/// as a tie-breaking hint, not as authoritative liveness.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PeerHint {
+    pub fingerprint: String,
+    pub addresses: Vec<String>,
+    pub last_seen: Option<Timestamp>,
+}
+
+// g[impl wire.peers]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PeersGossip {
+    pub entries: Vec<PeerHint>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum AbortReason {
+    GroveMismatch,
+    SignatureInvalid,
+    SeqRegression,
+    LeaderMismatch,
+    VersionTooOld,
+    PayloadTooLarge,
+    /// Free-form code for documented reasons not yet enumerated; kept open
+    /// so the wire format does not need a bump for new reason codes.
+    Other(String),
+}
+
+// g[impl wire.abort]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Abort {
+    pub reason: AbortReason,
+}
+
+/// Tagged union for grove gossip messages. The `type` discriminant uses
+/// snake-case names: `hello`, `version`, `peers`, `abort`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Message {
+    Hello(Hello),
+    Version(SignedPayload),
+    Peers(PeersGossip),
+    Abort(Abort),
+}
+
+#[derive(Debug)]
+pub enum GroveError {
+    Encode(serde_json::Error),
+    Signature(String),
+}
+
+impl fmt::Display for GroveError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Encode(e) => write!(f, "canonical encoding: {e}"),
+            Self::Signature(e) => write!(f, "signature: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for GroveError {}
+
+#[cfg(test)]
+mod tests {
+    use ed25519_dalek::SigningKey;
+    use jiff::Timestamp;
+    use rand_core::OsRng;
+    use uuid::Uuid;
+
+    use super::*;
+
+    fn sample_payload(seq: u64) -> Payload {
+        Payload {
+            grove_id: Uuid::from_u128(0x0123_4567_89ab_cdef_0123_4567_89ab_cdef),
+            seq,
+            created_at: Timestamp::from_second(1_700_000_000).unwrap(),
+            leader_fp: "fp-leader".into(),
+            members: vec![
+                Member {
+                    fp: "fp-z".into(),
+                    label: "z".into(),
+                },
+                Member {
+                    fp: "fp-a".into(),
+                    label: "a".into(),
+                },
+            ],
+            params: vec![
+                Param {
+                    name: "z-param".into(),
+                    kind: "text".into(),
+                    value: "z-val".into(),
+                },
+                Param {
+                    name: "a-param".into(),
+                    kind: "text".into(),
+                    value: "a-val".into(),
+                },
+            ],
+            secrets: vec![],
+        }
+    }
+
+    // g[verify versioning.signature]
+    #[test]
+    fn sign_and_verify_round_trip() {
+        let key = SigningKey::generate(&mut OsRng);
+        let signed = sample_payload(1).sign(&key).expect("sign");
+        signed.verify(&key.verifying_key()).expect("verify");
+    }
+
+    // g[verify versioning.signature]
+    #[test]
+    fn verify_fails_under_wrong_key() {
+        let leader = SigningKey::generate(&mut OsRng);
+        let other = SigningKey::generate(&mut OsRng);
+        let signed = sample_payload(1).sign(&leader).expect("sign");
+        let err = signed
+            .verify(&other.verifying_key())
+            .expect_err("must fail");
+        assert!(matches!(err, GroveError::Signature(_)), "got {err:?}");
+    }
+
+    // g[verify versioning.signature]
+    #[test]
+    fn verify_fails_after_payload_mutation() {
+        let key = SigningKey::generate(&mut OsRng);
+        let mut signed = sample_payload(1).sign(&key).expect("sign");
+        signed.payload.seq = 2;
+        let err = signed.verify(&key.verifying_key()).expect_err("must fail");
+        assert!(matches!(err, GroveError::Signature(_)), "got {err:?}");
+    }
+
+    // g[verify versioning.signature]
+    #[test]
+    fn signing_bytes_starts_with_domain_separator() {
+        let payload = sample_payload(1);
+        let bytes = payload.signing_bytes().expect("bytes");
+        assert!(
+            bytes.starts_with(SIG_DOMAIN_V1),
+            "signing bytes must start with the domain separator prefix"
+        );
+    }
+
+    #[test]
+    fn canonicalise_sorts_members_and_params() {
+        let mut p = sample_payload(1);
+        p.canonicalise();
+        assert_eq!(
+            p.members.iter().map(|m| &m.fp).collect::<Vec<_>>(),
+            vec!["fp-a", "fp-z"]
+        );
+        assert_eq!(
+            p.params.iter().map(|q| &q.name).collect::<Vec<_>>(),
+            vec!["a-param", "z-param"]
+        );
+    }
+
+    #[test]
+    fn signing_bytes_invariant_under_insertion_order() {
+        let key = SigningKey::generate(&mut OsRng);
+
+        let p1 = sample_payload(1);
+        let mut p2 = p1.clone();
+        p2.members.reverse();
+        p2.params.reverse();
+
+        let s1 = p1.sign(&key).expect("sign 1");
+        let s2 = p2.sign(&key).expect("sign 2");
+
+        assert_eq!(
+            s1.signature, s2.signature,
+            "reordering input collections must not change the signed bytes"
+        );
+    }
+
+    #[test]
+    fn sign_already_canonicalises_so_caller_need_not() {
+        let key = SigningKey::generate(&mut OsRng);
+        let p = sample_payload(1);
+        let signed = p.sign(&key).expect("sign");
+        // The members in the signed payload are sorted ("fp-a" before "fp-z").
+        assert_eq!(signed.payload.members[0].fp, "fp-a");
+        assert_eq!(signed.payload.members[1].fp, "fp-z");
+    }
+
+    // g[verify wire.hello]
+    // g[verify wire.version]
+    // g[verify wire.peers]
+    // g[verify wire.abort]
+    #[test]
+    fn message_round_trips_through_json() {
+        let key = SigningKey::generate(&mut OsRng);
+        let signed = sample_payload(7).sign(&key).expect("sign");
+
+        let messages = [
+            Message::Hello(Hello {
+                grove_id: Uuid::from_u128(1),
+                our_seq: 7,
+                our_payload_hash: "deadbeef".into(),
+                our_role: Role::Follower,
+                our_fingerprint: "fp-follower".into(),
+                protocol_version: PROTOCOL_VERSION,
+                nonce: 42,
+            }),
+            Message::Version(signed),
+            Message::Peers(PeersGossip {
+                entries: vec![PeerHint {
+                    fingerprint: "fp-x".into(),
+                    addresses: vec!["[::1]:7891".into()],
+                    last_seen: None,
+                }],
+            }),
+            Message::Abort(Abort {
+                reason: AbortReason::SeqRegression,
+            }),
+        ];
+
+        for m in &messages {
+            let json = serde_json::to_string(m).expect("encode");
+            let back: Message = serde_json::from_str(&json).expect("decode");
+            assert_eq!(*m, back, "round-trip");
+        }
+    }
+
+    #[test]
+    fn payload_hash_is_stable_under_field_reorder() {
+        let key = SigningKey::generate(&mut OsRng);
+        let p1 = sample_payload(3);
+        let mut p2 = p1.clone();
+        p2.members.reverse();
+
+        let s1 = p1.sign(&key).expect("sign 1");
+        let s2 = p2.sign(&key).expect("sign 2");
+        assert_eq!(
+            s1.payload_hash().unwrap(),
+            s2.payload_hash().unwrap(),
+            "payload_hash must depend only on canonical content"
+        );
+    }
+}
diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rs
index 41646200..cd67bf73 100644
--- a/crates/protocol/src/lib.rs
+++ b/crates/protocol/src/lib.rs
@@ -4,6 +4,7 @@ pub mod client;
 pub mod env;
 pub mod error;
 pub mod events;
+pub mod grove;
 pub mod keys;
 pub mod names;
 

From b707fcdf0d1a6dca90c9ee5c0609dd67f5131da7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 22:24:05 +1200
Subject: [PATCH 07/11] plan: bring back state split via
 build-from-TransportState

Previous adjustment dropped the OiState restructure entirely. That was
overcautious: the user's actual ask was to split state cleanly, but
without forcing every existing handler signature to change.

Updated approach: introduce TransportState as the canonical owner of
node-wide transport state (spki_fingerprint, ProtocolTrustRegistry,
AlpnHandlers). Build OiState from it by Arc-cloning the relevant
fields, so handlers stay on state.trusted_keys / state.spki_fingerprint
unchanged. GroveState in commit 5 is built the same way and registers
its trust set + ALPN handler against the shared registry. Daemon main
becomes the orchestrator: build TransportState, build OiState/GroveState
from it, register, then run the transport endpoint once.

Schedules this as commit 0c (numbered separately to avoid implying a
deferred split).
---
 docs/plans/grove.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/plans/grove.md b/docs/plans/grove.md
index 8fc956cb..f8b2e166 100644
--- a/docs/plans/grove.md
+++ b/docs/plans/grove.md
@@ -32,7 +32,9 @@ Refactor (lands before any grove-specific code):
 - Stays in `crates/core` rather than promoting to a new `crates/transport` crate for v0; promotion is a follow-up if multiple crates ever need server-side transport. The wire-type half (ALPN constants, dial-side `OiClient`, identity keys) remains in `crates/protocol/`.
 - ALPN handlers register with `transport` on startup: OI registers `bes.seedling/1`, grove registers `bes.grove/1`. The existing `oi/server.rs::handle_connection` body splits — generic per-connection logic moves to `transport`, OI-specific stream dispatch stays in `oi/`.
 
-For state, the smallest workable shape is to leave `OiState` alone and add `GroveState` as a sibling struct when grove lands (commit 5). The trust-set and fingerprint fields stay where they are: `OiState` owns the OI trust set, `GroveState` owns the grove trust set, and the `ProtocolTrustRegistry` (constructed at daemon startup and shared with both) is what couples them. Grove handlers capture `Arc<GroveState>` only; OI handlers continue capturing `Arc<OiState>`. The originally-planned `TransportState` / `OiState` carve-out + `Daemon` top-level container is **deferred** — it would touch every OI handler signature for limited cleanup value, and the sibling-struct approach gives the same handler-scoping property (operator handlers don't see grove state and vice versa) without the mechanical churn.
+For state, introduce a `TransportState` struct as the canonical owner of node-wide transport-level state (`spki_fingerprint`, `ProtocolTrustRegistry`, `AlpnHandlers`) and **build `OiState` from it**: `OiState` holds `Arc<TransportState>` plus Arc-cloned references to the relevant transport fields (`trusted_keys`, `spki_fingerprint` wrapped in `Arc<OnceLock<…>>`). Existing OI handlers continue to access `state.trusted_keys` / `state.spki_fingerprint` unchanged — the Arc-sharing means both views see the same value. When `GroveState` lands in commit 5, it is built from the same `TransportState` and registers `GroveTrust` against the shared trust registry. The original "split every handler signature into a narrower view" plan is dropped in favour of this build-from-shared-state pattern, which gives the layering benefit without forcing any handler change.
+
+Daemon main wires it: build `TransportState` first; build `OiState` (and later `GroveState`) from it; have each protocol's `register` function attach its trust set + ALPN handler; call `transport::endpoint::run` once after both have registered.
 
 This refactor is pure restructuring — no behavioural change, OI tests stay green.
 
@@ -181,8 +183,9 @@ To modify:
 - `crates/core/src/transport/` — *new* module (commit 0). `endpoint.rs`, `auth.rs`, `connection.rs`, `framing.rs`. Holds quinn endpoint, ALPN handler registry, protocol-scoped trust registry, JSON-line framing. Replaces transport-level code currently inlined in `oi/server.rs` and `oi/auth.rs`.
 - `crates/core/src/oi/server.rs` — slimmed to OI-specific stream dispatch (port-forward, log streaming, event subscription, handler routing). Generic per-connection logic moves to `transport/`.
 - `crates/core/src/oi/auth.rs` — bootstrap-file loader stays here; trust-set machinery moves to `transport/auth.rs` as protocol-scoped sets (`OperatorTrust` for OI, `GroveTrust` for grove, registered against their ALPNs).
-- `crates/core/src/grove/` — *new* module. `state.rs` (`GroveState`: publish mutex, dial loop, dirty-mappings, signed-payload cache, grove trust set), `dial.rs` (connect loop), `apply.rs` (payload-apply pipeline + diff), `handler.rs` (registers `bes.grove/1` handler with transport, runs HELLO/VERSION/PEERS/abort exchange).
-- `crates/daemon/src/main.rs` — at startup, construct the shared `ProtocolTrustRegistry` and `AlpnHandlers`, then call `oi::register` and `grove::register` against them before `transport::endpoint::run`. No new top-level container struct; both states are held as `Arc<OiState>` and `Arc<GroveState>` siblings, captured into their respective handler closures.
+- `crates/core/src/transport/state.rs` — *new* (commit 0c). `TransportState`: `key_path`, `Arc<OnceLock<String>>` fingerprint, `Arc<ProtocolTrustRegistry>`, `Arc<AlpnHandlers>`. Constructed once at daemon startup; both `OiState` and (later) `GroveState` are built from it.
+- `crates/core/src/grove/` — *new* module (commits 4a–8). `state.rs` (`GroveState`: built from `TransportState`; publish mutex, dial loop, dirty-mappings, signed-payload cache, grove trust set), `dial.rs` (connect loop), `apply.rs` (payload-apply pipeline + diff), `handler.rs` (registers `bes.grove/1` handler with transport, runs HELLO/VERSION/PEERS/abort exchange), `db.rs` (read/write helpers for the v53 tables).
+- `crates/daemon/src/main.rs` — at startup, construct `TransportState` first, then build `OiState` (and later `GroveState`) from it, call `oi::register`/`grove::register` (sync, attach trust + handler), then `transport::endpoint::run`. Both states are held as `Arc<OiState>` and `Arc<GroveState>` siblings, captured into their respective handler closures.
 - `crates/core/src/oi/handler/params.rs` — extract `set_param_inner(... ParamSource)`, add `apply_grove_param_to_app` helper, rejection check on operator path.
 - `crates/core/src/oi/handler/grove.rs` — *new*. OI handlers for all `grove …` operations.
 - `crates/ctl/src/grove.rs` — *new*. CLI subcommand.
@@ -206,7 +209,9 @@ To reuse (don't reinvent):
 
 Each independently shippable, each with its own spec sections + tracey annotations. jj-friendly granularity.
 
-0. **Code restructure: extract `transport` module.** Pure refactor, no behavioural change, OI tests stay green. New `crates/core/src/transport/` (`endpoint`, `auth`); slim `oi/server.rs` and `oi/auth.rs` to OI-specific bits; OI registers itself as the `bes.seedling/1` ALPN handler through the new transport interface. Trust-set machinery becomes protocol-scoped (`ProtocolTrustRegistry` keyed by ALPN) but only OI is registered at this point. `OiState` is left alone — `GroveState` will land as a sibling in commit 5 rather than via a carve-out. *Done in `refactor(transport): extract shared QUIC endpoint, ALPN dispatch, and protocol-scoped trust`.*
+0. **Code restructure: extract `transport` module.** Pure refactor, no behavioural change, OI tests stay green.
+   - **0a (done):** New `crates/core/src/transport/` (`endpoint`, `auth`); slim `oi/server.rs` and `oi/auth.rs` to OI-specific bits; OI registers itself as the `bes.seedling/1` ALPN handler through the new transport interface. Trust-set machinery becomes protocol-scoped (`ProtocolTrustRegistry` keyed by ALPN) but only OI is registered at this point. *Landed as `refactor(transport): extract shared QUIC endpoint, ALPN dispatch, and protocol-scoped trust`.*
+   - **0c:** Introduce `TransportState` as the canonical owner of `spki_fingerprint`, `ProtocolTrustRegistry`, and `AlpnHandlers`. `OiState` gains `transport: Arc<TransportState>` and shares `trusted_keys`/`spki_fingerprint` via Arc-cloning so existing handlers stay on `state.trusted_keys` / `state.spki_fingerprint` unchanged. Daemon main constructs `TransportState` first; `oi::register` becomes a sync function that loads keys, registers OI's trust set + handler, then daemon main calls `transport::endpoint::run` once. (Numbered 0c rather than 0b to avoid implying a deferred split.)
 
 1. **Spec + tracey wiring.** Extract shared transport prose from `docs/spec/interface.md` into a new `docs/spec/transport.md` (`t[...]` namespace) covering RPK TLS, fingerprint pinning, ALPN as hard-version-wall, JSON-line framing, abort/error semantics, message-size caps. Update `interface.md` to reference `t[...]` for those items. Re-annotate the (now-moved) transport code from commit 0 with `t[impl ...]` instead of `i[impl ...]`. Add `docs/spec/grove.md` skeleton with all `g[...]` items including event names and "Known limitations", referencing `t[...]` for transport. Register `transport/main` and `grove/main` in `.config/tracey/config.styx`. `tracey query status` clean with stubbed requirements.
 2. **DB v53 migration.** All five tables, no consumers yet. Test: migration applies cleanly on a v52 DB.

From 487b38c93a0bf4fd53e29e707a9f1de0183586af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 22:29:34 +1200
Subject: [PATCH 08/11] refactor(transport): introduce TransportState, build
 OiState from it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new TransportState struct as the canonical owner of the node-wide
transport-level state: key path, SPKI fingerprint (Arc<OnceLock>), trust
registry, ALPN handler dispatch, and the per-connection log-label
resolver. Built once at daemon startup; per-protocol state structs (now
OiState; soon GroveState) are built on top of it.

OiState gains an Arc<TransportState> field plus an Arc<OnceLock<String>>
for spki_fingerprint that shares the same OnceLock as TransportState.
Existing OI handlers continue to access state.trusted_keys and
state.spki_fingerprint with no change — the Arcs make a set in one view
visible in the other.

oi::run is renamed to oi::register and becomes synchronous: it loads the
authorised-keys set, registers OI's trust set + ALPN handler + label
resolver against TransportState, and returns. The QUIC endpoint is now
started by daemon main calling transport::endpoint::run separately, so
future protocols (grove) can register before the endpoint comes up.

EndpointConfig narrows to { state: Arc<TransportState>, addrs }; key
path, trust registry, handlers, and label lookup all come from the
shared state. transport::endpoint::run sets the SPKI fingerprint on
TransportState; OiState sees it through the shared Arc.
---
 crates/core/src/oi.rs                 |  2 +-
 crates/core/src/oi/server.rs          | 53 ++++++++++++---------------
 crates/core/src/oi/state.rs           | 14 ++++++-
 crates/core/src/transport.rs          |  3 ++
 crates/core/src/transport/endpoint.rs | 32 +++++++++-------
 crates/core/src/transport/state.rs    | 49 +++++++++++++++++++++++++
 crates/daemon/src/main.rs             | 23 ++++++++----
 7 files changed, 123 insertions(+), 53 deletions(-)
 create mode 100644 crates/core/src/transport/state.rs

diff --git a/crates/core/src/oi.rs b/crates/core/src/oi.rs
index a146b834..d1923654 100644
--- a/crates/core/src/oi.rs
+++ b/crates/core/src/oi.rs
@@ -6,4 +6,4 @@ pub mod server;
 pub mod shells;
 pub mod state;
 
-pub use server::run;
+pub use server::register;
diff --git a/crates/core/src/oi/server.rs b/crates/core/src/oi/server.rs
index 0b2655c2..af3e1c52 100644
--- a/crates/core/src/oi/server.rs
+++ b/crates/core/src/oi/server.rs
@@ -1,6 +1,5 @@
-use std::{net::SocketAddr, path::Path, sync::Arc};
+use std::{path::Path, sync::Arc};
 
-use quinn::Endpoint;
 use serde_json::json;
 use tokio::sync::{Semaphore, mpsc};
 use tracing::Instrument;
@@ -14,10 +13,10 @@ use super::{
     state::OiState,
 };
 use crate::transport::{
-    auth::ProtocolTrustRegistry,
+    TransportState,
     endpoint::{
-        AlpnHandlers, ConnectionContext, ConnectionFuture, ConnectionHandler, EndpointConfig,
-        LabelLookup, extract_client_fp, read_json_line,
+        ConnectionContext, ConnectionFuture, ConnectionHandler, LabelLookup, extract_client_fp,
+        read_json_line,
     },
 };
 
@@ -47,12 +46,20 @@ fn synthesise_actor(state: &OiState, fp: Option<&str>) -> Arc<Actor> {
     })
 }
 
-pub async fn run(
-    state: Arc<OiState>,
-    addrs: &[SocketAddr],
+/// Register the OI as the `bes.seedling/1` ALPN handler against the shared
+/// transport state. Loads the authorised-keys set from the DB (and the
+/// bootstrap file), installs the per-connection log-label resolver,
+/// builds the OI connection handler, and registers both with
+/// [`TransportState`].
+///
+/// The actual QUIC endpoint is started by
+/// [`crate::transport::endpoint::run`] after every protocol has registered.
+pub fn register(
+    transport: &Arc<TransportState>,
+    state: &Arc<OiState>,
     data_dir: &Path,
     max_streams: usize,
-) -> Result<(String, Vec<Endpoint>), Box<dyn std::error::Error + Send + Sync>> {
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     {
         let trusted_keys = Arc::clone(&state.trusted_keys);
         state
@@ -74,23 +81,23 @@ pub async fn run(
         );
     }
 
-    let trust = ProtocolTrustRegistry::new();
-    trust.register(OI_ALPN, Arc::clone(&state.trusted_keys));
+    transport
+        .trust_registry
+        .register(OI_ALPN, Arc::clone(&state.trusted_keys));
 
-    let handlers = AlpnHandlers::new();
     let stream_semaphore = Arc::new(Semaphore::new(max_streams));
     let oi_handler: ConnectionHandler = {
-        let state = Arc::clone(&state);
+        let state = Arc::clone(state);
         Arc::new(move |conn, ctx| -> ConnectionFuture {
             let state = Arc::clone(&state);
             let stream_semaphore = Arc::clone(&stream_semaphore);
             Box::pin(handle_connection(conn, ctx, state, stream_semaphore))
         })
     };
-    handlers.register(OI_ALPN, oi_handler);
+    transport.handlers.register(OI_ALPN, oi_handler);
 
     let label_lookup: LabelLookup = {
-        let state = Arc::clone(&state);
+        let state = Arc::clone(state);
         Arc::new(move |fp: &str| {
             let fp = fp.to_owned();
             state
@@ -98,22 +105,10 @@ pub async fn run(
                 .call(move |db| super::auth::get_label(db, &fp).ok().flatten())
         })
     };
+    *transport.label_lookup.write() = Some(label_lookup);
 
     tracing::info!(max_streams, "OI concurrency limit configured");
-
-    let (fingerprint, endpoints) = crate::transport::endpoint::run(EndpointConfig {
-        key_path: data_dir.join("oi.key"),
-        addrs: addrs.to_vec(),
-        trust: Arc::clone(&trust),
-        handlers: Arc::clone(&handlers),
-        label_lookup: Some(label_lookup),
-    })
-    .await?;
-
-    tracing::info!("OI SPKI fingerprint: {fingerprint}");
-    state.spki_fingerprint.set(fingerprint.clone()).ok();
-
-    Ok((fingerprint, endpoints))
+    Ok(())
 }
 
 // i[stream.control]
diff --git a/crates/core/src/oi/state.rs b/crates/core/src/oi/state.rs
index d2a45231..782805d9 100644
--- a/crates/core/src/oi/state.rs
+++ b/crates/core/src/oi/state.rs
@@ -8,14 +8,24 @@ use std::{
 use parking_lot::RwLock;
 
 use crate::runtime::apps::AppRegistry;
+use crate::transport::TransportState;
 
 use super::forwards::ForwardRegistry;
 
 /// Shared state for all OI request handlers.
 pub struct OiState {
+    /// Node-wide transport state. Owns the canonical SPKI fingerprint,
+    /// the per-ALPN trust registry, and the ALPN handler dispatch table;
+    /// the relevant fields are also Arc-shared into this struct's
+    /// `spki_fingerprint` and `trusted_keys` so existing handler code can
+    /// continue to access them without indirection.
+    pub transport: Arc<TransportState>,
     pub registry: Arc<RwLock<AppRegistry>>,
-    /// Set once by the server after key generation; never changes after that.
-    pub spki_fingerprint: OnceLock<String>,
+    /// Server SPKI SHA-256 fingerprint. Set once by the transport endpoint
+    /// after key generation; never changes after that. Arc-shared with
+    /// [`TransportState::spki_fingerprint`] so a set in one is visible to
+    /// the other.
+    pub spki_fingerprint: Arc<OnceLock<String>>,
     pub start_time: Instant,
     pub db: crate::runtime::db::DbHandle,
     pub scheduler: Arc<parking_lot::Mutex<crate::runtime::Scheduler>>,
diff --git a/crates/core/src/transport.rs b/crates/core/src/transport.rs
index e3fad590..2ad1071b 100644
--- a/crates/core/src/transport.rs
+++ b/crates/core/src/transport.rs
@@ -1,2 +1,5 @@
 pub mod auth;
 pub mod endpoint;
+pub mod state;
+
+pub use state::TransportState;
diff --git a/crates/core/src/transport/endpoint.rs b/crates/core/src/transport/endpoint.rs
index 36b103d6..9a1484e4 100644
--- a/crates/core/src/transport/endpoint.rs
+++ b/crates/core/src/transport/endpoint.rs
@@ -5,7 +5,7 @@
 //! per-protocol trust gate (in [`crate::transport::auth`]) has approved
 //! the client's fingerprint.
 
-use std::{net::SocketAddr, path::PathBuf, pin::Pin, sync::Arc, time::Duration};
+use std::{net::SocketAddr, pin::Pin, sync::Arc, time::Duration};
 
 use parking_lot::RwLock;
 use quinn::Endpoint;
@@ -14,6 +14,7 @@ use rustls::ServerConfig as TlsServerConfig;
 use seedling_protocol::keys;
 
 use crate::transport::auth::{ProtocolTrustRegistry, SeedlingClientVerifier};
+use crate::transport::state::TransportState;
 
 /// Default listen port. The shared endpoint is one TCP/UDP port for all
 /// registered ALPNs.
@@ -81,11 +82,8 @@ impl AlpnHandlers {
 pub type LabelLookup = Arc<dyn Fn(&str) -> Option<String> + Send + Sync>;
 
 pub struct EndpointConfig {
-    pub key_path: PathBuf,
+    pub state: Arc<TransportState>,
     pub addrs: Vec<SocketAddr>,
-    pub trust: Arc<ProtocolTrustRegistry>,
-    pub handlers: Arc<AlpnHandlers>,
-    pub label_lookup: Option<LabelLookup>,
 }
 
 fn build_tls_config(
@@ -144,19 +142,25 @@ fn extract_negotiated_alpn(conn: &quinn::Connection) -> Option<Vec<u8>> {
 // t[impl listen]
 pub async fn run(
     config: EndpointConfig,
-) -> Result<(String, Vec<Endpoint>), Box<dyn std::error::Error + Send + Sync>> {
-    let key = keys::load_or_generate(&config.key_path)?;
+) -> Result<Vec<Endpoint>, Box<dyn std::error::Error + Send + Sync>> {
+    let key = keys::load_or_generate(&config.state.key_path)?;
     let spki = keys::spki_der(&key);
     let fingerprint = keys::fingerprint(&spki);
+    config.state.spki_fingerprint.set(fingerprint.clone()).ok();
 
     tracing::info!("transport SPKI fingerprint: {fingerprint}");
 
-    let alpn_list = config.handlers.alpn_list();
+    let alpn_list = config.state.handlers.alpn_list();
     if alpn_list.is_empty() {
         return Err("no ALPN handlers registered".into());
     }
 
-    let tls_config = build_tls_config(&key, spki, Arc::clone(&config.trust), alpn_list)?;
+    let tls_config = build_tls_config(
+        &key,
+        spki,
+        Arc::clone(&config.state.trust_registry),
+        alpn_list,
+    )?;
     let quic_config = quinn::crypto::rustls::QuicServerConfig::try_from(tls_config)?;
     let mut transport = quinn::TransportConfig::default();
     // Send PING frames every 10 s so idle connections do not trip the idle
@@ -181,6 +185,8 @@ pub async fn run(
         tracing::warn!("SSLKEYLOGFILE is set — TLS session keys are being logged to disk");
     }
 
+    let label_lookup = config.state.label_lookup.read().clone();
+
     let mut endpoints = Vec::with_capacity(config.addrs.len());
     for addr in &config.addrs {
         let endpoint = Endpoint::server(base_server_config.clone(), *addr)?;
@@ -188,14 +194,14 @@ pub async fn run(
         let ep_clone = endpoint.clone();
         tokio::spawn(accept_loop(
             endpoint,
-            Arc::clone(&config.handlers),
-            Arc::clone(&config.trust),
-            config.label_lookup.clone(),
+            Arc::clone(&config.state.handlers),
+            Arc::clone(&config.state.trust_registry),
+            label_lookup.clone(),
         ));
         endpoints.push(ep_clone);
     }
 
-    Ok((fingerprint, endpoints))
+    Ok(endpoints)
 }
 
 async fn accept_loop(
diff --git a/crates/core/src/transport/state.rs b/crates/core/src/transport/state.rs
new file mode 100644
index 00000000..f0b216ac
--- /dev/null
+++ b/crates/core/src/transport/state.rs
@@ -0,0 +1,49 @@
+//! Node-wide transport state shared across all registered application
+//! protocols.
+//!
+//! Built once at daemon startup. Each protocol's own state struct
+//! (`OiState`, `GroveState`, …) is constructed with an `Arc<TransportState>`
+//! and Arc-clones the fields it surfaces directly so its own handlers
+//! continue to access them without indirection.
+
+use std::{path::PathBuf, sync::Arc};
+
+use parking_lot::RwLock;
+
+use crate::transport::{auth::ProtocolTrustRegistry, endpoint::AlpnHandlers};
+
+pub struct TransportState {
+    /// Filesystem path of the server's transport identity key (PKCS#8
+    /// Ed25519). The key is loaded by [`crate::transport::endpoint::run`]
+    /// at startup and used as the server identity for every registered
+    /// ALPN.
+    pub key_path: PathBuf,
+    /// Server SPKI SHA-256 fingerprint. Set once by
+    /// [`crate::transport::endpoint::run`] after the key is loaded; visible
+    /// thereafter to every state struct that holds an Arc clone.
+    pub spki_fingerprint: Arc<std::sync::OnceLock<String>>,
+    /// Per-ALPN trusted-keys registry. Each protocol calls
+    /// [`ProtocolTrustRegistry::register`] with its own set during the
+    /// protocol's `register` call.
+    pub trust_registry: Arc<ProtocolTrustRegistry>,
+    /// ALPN → handler dispatch table. Each protocol registers its
+    /// connection handler here during its `register` call.
+    pub handlers: Arc<AlpnHandlers>,
+    /// Optional fingerprint → label resolver, used to decorate
+    /// per-connection log spans with human-readable peer names. When
+    /// multiple protocols are registered, each may install its own; for
+    /// now there is at most one (set by OI).
+    pub label_lookup: RwLock<Option<crate::transport::endpoint::LabelLookup>>,
+}
+
+impl TransportState {
+    pub fn new(key_path: PathBuf) -> Arc<Self> {
+        Arc::new(Self {
+            key_path,
+            spki_fingerprint: Arc::new(std::sync::OnceLock::new()),
+            trust_registry: ProtocolTrustRegistry::new(),
+            handlers: AlpnHandlers::new(),
+            label_lookup: RwLock::new(None),
+        })
+    }
+}
diff --git a/crates/daemon/src/main.rs b/crates/daemon/src/main.rs
index df81f2e3..6c901175 100644
--- a/crates/daemon/src/main.rs
+++ b/crates/daemon/src/main.rs
@@ -25,6 +25,7 @@ use seedling_core::{
         reconcile::Reconciler,
         resolver::{resolver_addr, resolver_gateway_addr, spawn_dns_forwarder},
     },
+    transport::{TransportState, endpoint::EndpointConfig},
 };
 use seedling_protocol::names::AppName;
 use tokio::sync::Notify;
@@ -1033,9 +1034,12 @@ async fn main() {
     // OI server
     // ---------------------------------------------------------------------------
 
+    let transport_state = TransportState::new(data_dir.join("oi.key"));
+
     let oi_state = Arc::new(OiState {
+        transport: Arc::clone(&transport_state),
         registry: Arc::clone(&registry),
-        spki_fingerprint: std::sync::OnceLock::new(),
+        spki_fingerprint: Arc::clone(&transport_state.spki_fingerprint),
         start_time: Instant::now(),
         db: db.clone(),
         scheduler: Arc::clone(&scheduler),
@@ -1290,17 +1294,20 @@ async fn main() {
         });
     }
 
+    oi::register(&transport_state, &oi_state, &data_dir, args.max_streams).unwrap_or_else(|e| {
+        tracing::error!("OI registration failed: {e}");
+        std::process::exit(1);
+    });
+
     // t[impl listen]
     let oi_addrs = resolve_oi_addrs(&args.interface, &args.listen, args.port);
-    let (_fingerprint, oi_endpoints) = oi::run(
-        Arc::clone(&oi_state),
-        &oi_addrs,
-        &data_dir,
-        args.max_streams,
-    )
+    let oi_endpoints = seedling_core::transport::endpoint::run(EndpointConfig {
+        state: Arc::clone(&transport_state),
+        addrs: oi_addrs,
+    })
     .await
     .unwrap_or_else(|e| {
-        tracing::error!("OI server failed to start: {e}");
+        tracing::error!("transport failed to start: {e}");
         std::process::exit(1);
     });
 

From bf751a72a36015fd030e1332c279834c7ec80539 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 22:50:28 +1200
Subject: [PATCH 09/11] feat(grove): module skeleton with GroveState and v53 DB
 helpers

Lays down the per-node grove state and the typed DB layer that the
publish operation (next commit) and the wire handler (commit 5) build
on. No transport handler yet; no publish operation yet.

- GroveState: built from TransportState (held as an Arc), owns the
  grove trust set, the publish mutex, and the in-memory cache of the
  latest applied SignedPayload. ::load constructs from DB and seeds
  the trust set from the persisted membership list, so a daemon
  restart preserves grove authorisation without waiting for a peer.
- grove::db: typed read/write helpers over the v53 tables. Includes
  Membership row decode, write_membership (upsert into the single-row
  grove_membership table), insert_version (idempotent on seq via
  INSERT OR IGNORE), and replace_params (denormalised projection of
  the latest payload's grove parameters).

Tests: round-trip membership write/load, single-row replacement,
insert_version idempotence, replace_params overwrite, GroveState load
returning none on a fresh DB and seeding the trust set from a
persisted membership.
---
 crates/core/src/grove.rs       |   4 +
 crates/core/src/grove/db.rs    | 338 +++++++++++++++++++++++++++++++++
 crates/core/src/grove/state.rs | 162 ++++++++++++++++
 crates/core/src/lib.rs         |   1 +
 4 files changed, 505 insertions(+)
 create mode 100644 crates/core/src/grove.rs
 create mode 100644 crates/core/src/grove/db.rs
 create mode 100644 crates/core/src/grove/state.rs

diff --git a/crates/core/src/grove.rs b/crates/core/src/grove.rs
new file mode 100644
index 00000000..6b918818
--- /dev/null
+++ b/crates/core/src/grove.rs
@@ -0,0 +1,4 @@
+pub mod db;
+pub mod state;
+
+pub use state::GroveState;
diff --git a/crates/core/src/grove/db.rs b/crates/core/src/grove/db.rs
new file mode 100644
index 00000000..163c8a70
--- /dev/null
+++ b/crates/core/src/grove/db.rs
@@ -0,0 +1,338 @@
+//! Read/write helpers over the v53 grove tables.
+//!
+//! All functions take a [`crate::runtime::db::Db`] reference and run inline
+//! on the DB thread, mirroring the pattern in `oi/auth.rs`. Callers wrap
+//! them in `state.db.call(...)` to dispatch onto the DB actor.
+
+use jiff::Timestamp;
+use rusqlite::{OptionalExtension, params};
+use uuid::Uuid;
+
+use seedling_protocol::grove::{Param, Payload, Role, SignedPayload};
+
+use crate::runtime::db::Db;
+
+/// One row of `grove_membership` (id is implicitly 1) decoded into a
+/// typed [`SignedPayload`] plus the metadata captured when this node
+/// joined the grove.
+#[derive(Debug, Clone)]
+pub struct Membership {
+    pub grove_id: Uuid,
+    pub role: Role,
+    pub leader_fingerprint: String,
+    pub joined_at: Timestamp,
+    pub current: SignedPayload,
+}
+
+#[derive(Debug)]
+pub enum LoadError {
+    Sql(rusqlite::Error),
+    UuidLength(usize),
+    UnknownRole(String),
+    PayloadDecode(serde_json::Error),
+    TimestampDecode(jiff::Error),
+}
+
+impl std::fmt::Display for LoadError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Sql(e) => write!(f, "sql: {e}"),
+            Self::UuidLength(n) => write!(f, "grove_id is {n} bytes, expected 16"),
+            Self::UnknownRole(s) => write!(f, "unknown role: {s:?}"),
+            Self::PayloadDecode(e) => write!(f, "payload decode: {e}"),
+            Self::TimestampDecode(e) => write!(f, "timestamp decode: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for LoadError {}
+
+impl From<rusqlite::Error> for LoadError {
+    fn from(e: rusqlite::Error) -> Self {
+        Self::Sql(e)
+    }
+}
+
+/// Load this node's grove membership, or `None` if it is not in any grove.
+// g[impl identity]
+pub fn load_membership(db: &Db) -> Result<Option<Membership>, LoadError> {
+    let row = db
+        .conn
+        .query_row(
+            "SELECT grove_id, role, leader_fingerprint, current_payload, current_signature, joined_at \
+             FROM grove_membership WHERE id = 1",
+            [],
+            |r| {
+                Ok((
+                    r.get::<_, Vec<u8>>(0)?,
+                    r.get::<_, String>(1)?,
+                    r.get::<_, String>(2)?,
+                    r.get::<_, Vec<u8>>(3)?,
+                    r.get::<_, Vec<u8>>(4)?,
+                    r.get::<_, String>(5)?,
+                ))
+            },
+        )
+        .optional()?;
+
+    let Some((grove_id_bytes, role_s, leader_fp, payload_bytes, sig_bytes, joined_at_s)) = row
+    else {
+        return Ok(None);
+    };
+
+    let grove_id = match grove_id_bytes.len() {
+        16 => Uuid::from_bytes(grove_id_bytes.as_slice().try_into().unwrap()),
+        n => return Err(LoadError::UuidLength(n)),
+    };
+    let role = match role_s.as_str() {
+        "leader" => Role::Leader,
+        "follower" => Role::Follower,
+        _ => return Err(LoadError::UnknownRole(role_s)),
+    };
+    let payload: Payload =
+        serde_json::from_slice(&payload_bytes).map_err(LoadError::PayloadDecode)?;
+    let joined_at = joined_at_s
+        .parse::<Timestamp>()
+        .map_err(LoadError::TimestampDecode)?;
+
+    Ok(Some(Membership {
+        grove_id,
+        role,
+        leader_fingerprint: leader_fp,
+        joined_at,
+        current: SignedPayload {
+            payload,
+            signature: sig_bytes,
+        },
+    }))
+}
+
+/// Persist this node's grove membership and the currently-applied signed
+/// payload. Used by both `grove init` (initial membership row) and
+/// payload-apply (subsequent updates to the same row). Always runs on
+/// `id = 1`; the table's CHECK constraint enforces the single-row invariant.
+// g[impl identity]
+// g[impl membership.canonical]
+pub fn write_membership(db: &Db, m: &Membership) -> Result<(), LoadError> {
+    let payload_bytes = serde_json::to_vec(&m.current.payload).map_err(LoadError::PayloadDecode)?;
+    db.conn.execute(
+        "INSERT INTO grove_membership \
+            (id, grove_id, role, leader_fingerprint, current_seq, current_payload, current_signature, joined_at) \
+         VALUES (1, ?1, ?2, ?3, ?4, ?5, ?6, ?7) \
+         ON CONFLICT(id) DO UPDATE SET \
+             grove_id           = excluded.grove_id, \
+             role               = excluded.role, \
+             leader_fingerprint = excluded.leader_fingerprint, \
+             current_seq        = excluded.current_seq, \
+             current_payload    = excluded.current_payload, \
+             current_signature  = excluded.current_signature",
+        params![
+            m.grove_id.as_bytes().to_vec(),
+            match m.role {
+                Role::Leader => "leader",
+                Role::Follower => "follower",
+            },
+            m.leader_fingerprint,
+            m.current.payload.seq as i64,
+            payload_bytes,
+            m.current.signature,
+            m.joined_at.to_string(),
+        ],
+    )?;
+    Ok(())
+}
+
+/// Insert a payload into the audit history, idempotent on `seq`. Returns
+/// `true` if a row was inserted, `false` if the seq was already present.
+pub fn insert_version(
+    db: &Db,
+    signed: &SignedPayload,
+    received_at: Timestamp,
+) -> Result<bool, LoadError> {
+    let payload_bytes = serde_json::to_vec(&signed.payload).map_err(LoadError::PayloadDecode)?;
+    let rows = db.conn.execute(
+        "INSERT OR IGNORE INTO grove_versions (seq, payload, signature, received_at) \
+         VALUES (?1, ?2, ?3, ?4)",
+        params![
+            signed.payload.seq as i64,
+            payload_bytes,
+            signed.signature,
+            received_at.to_string(),
+        ],
+    )?;
+    Ok(rows == 1)
+}
+
+/// Replace the denormalised `grove_params` projection to match the given
+/// payload's parameter list. Atomic with respect to other DB writes by
+/// virtue of the DB actor's serialisation; callers wanting transactional
+/// atomicity with a `write_membership` in the same closure must wrap both
+/// in a `Db::conn::unchecked_transaction`.
+// g[impl params.set]
+pub fn replace_params(db: &Db, version_seq: u64, params_list: &[Param]) -> Result<(), LoadError> {
+    db.conn.execute("DELETE FROM grove_params", [])?;
+    let mut stmt = db.conn.prepare(
+        "INSERT INTO grove_params (name, kind, value, version_seq) VALUES (?1, ?2, ?3, ?4)",
+    )?;
+    for p in params_list {
+        stmt.execute(params![p.name, p.kind, p.value, version_seq as i64])?;
+    }
+    Ok(())
+}
+
+/// Read back the denormalised grove parameters in name order.
+pub fn list_params(db: &Db) -> Result<Vec<(Param, u64)>, LoadError> {
+    let mut stmt = db
+        .conn
+        .prepare("SELECT name, kind, value, version_seq FROM grove_params ORDER BY name ASC")?;
+    let rows = stmt.query_map([], |r| {
+        Ok((
+            Param {
+                name: r.get(0)?,
+                kind: r.get(1)?,
+                value: r.get(2)?,
+            },
+            r.get::<_, i64>(3)? as u64,
+        ))
+    })?;
+    let mut out = Vec::new();
+    for row in rows {
+        out.push(row?);
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use ed25519_dalek::SigningKey;
+    use jiff::Timestamp;
+    use rand_core::OsRng;
+    use seedling_protocol::grove::{Member, Param, Payload};
+    use uuid::Uuid;
+
+    use super::*;
+
+    fn fresh_db() -> Db {
+        Db::open_in_memory().expect("in-memory db")
+    }
+
+    fn sample_signed(seq: u64) -> SignedPayload {
+        let key = SigningKey::generate(&mut OsRng);
+        Payload {
+            grove_id: Uuid::from_u128(0xfeed_face_cafe_babe_dead_beef_0000_0001),
+            seq,
+            created_at: Timestamp::from_second(1_700_000_000).unwrap(),
+            leader_fp: "fp-leader".into(),
+            members: vec![Member {
+                fp: "fp-leader".into(),
+                label: "leader".into(),
+            }],
+            params: vec![Param {
+                name: "greeting".into(),
+                kind: "text".into(),
+                value: "hello".into(),
+            }],
+            secrets: vec![],
+        }
+        .sign(&key)
+        .expect("sign")
+    }
+
+    fn sample_membership(seq: u64) -> Membership {
+        let signed = sample_signed(seq);
+        Membership {
+            grove_id: signed.payload.grove_id,
+            role: Role::Leader,
+            leader_fingerprint: signed.payload.leader_fp.clone(),
+            joined_at: Timestamp::from_second(1_700_000_000).unwrap(),
+            current: signed,
+        }
+    }
+
+    // g[verify identity]
+    #[test]
+    fn load_membership_returns_none_on_fresh_db() {
+        let db = fresh_db();
+        assert!(load_membership(&db).unwrap().is_none());
+    }
+
+    // g[verify identity]
+    // g[verify membership.canonical]
+    #[test]
+    fn write_then_load_membership_round_trips() {
+        let db = fresh_db();
+        let m = sample_membership(1);
+        write_membership(&db, &m).expect("write");
+        let loaded = load_membership(&db).expect("load").expect("present");
+        assert_eq!(loaded.grove_id, m.grove_id);
+        assert_eq!(loaded.role, m.role);
+        assert_eq!(loaded.leader_fingerprint, m.leader_fingerprint);
+        assert_eq!(loaded.joined_at, m.joined_at);
+        assert_eq!(loaded.current.payload.seq, m.current.payload.seq);
+        assert_eq!(loaded.current.signature, m.current.signature);
+    }
+
+    #[test]
+    fn write_membership_replaces_existing_row() {
+        let db = fresh_db();
+        write_membership(&db, &sample_membership(1)).unwrap();
+        write_membership(&db, &sample_membership(2)).unwrap();
+        let loaded = load_membership(&db).unwrap().unwrap();
+        assert_eq!(loaded.current.payload.seq, 2);
+    }
+
+    #[test]
+    fn insert_version_is_idempotent_on_seq() {
+        let db = fresh_db();
+        let s1 = sample_signed(1);
+        let inserted_first = insert_version(&db, &s1, Timestamp::now()).unwrap();
+        let inserted_second = insert_version(&db, &s1, Timestamp::now()).unwrap();
+        assert!(inserted_first);
+        assert!(!inserted_second);
+        let count: i64 = db
+            .conn
+            .query_row("SELECT COUNT(*) FROM grove_versions", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(count, 1);
+    }
+
+    // g[verify params.set]
+    #[test]
+    fn replace_params_overwrites_previous_set() {
+        let db = fresh_db();
+        replace_params(
+            &db,
+            1,
+            &[Param {
+                name: "a".into(),
+                kind: "text".into(),
+                value: "first".into(),
+            }],
+        )
+        .unwrap();
+        replace_params(
+            &db,
+            2,
+            &[
+                Param {
+                    name: "b".into(),
+                    kind: "text".into(),
+                    value: "second".into(),
+                },
+                Param {
+                    name: "a".into(),
+                    kind: "text".into(),
+                    value: "first-updated".into(),
+                },
+            ],
+        )
+        .unwrap();
+        let loaded = list_params(&db).unwrap();
+        assert_eq!(loaded.len(), 2);
+        assert_eq!(loaded[0].0.name, "a");
+        assert_eq!(loaded[0].0.value, "first-updated");
+        assert_eq!(loaded[0].1, 2);
+        assert_eq!(loaded[1].0.name, "b");
+        assert_eq!(loaded[1].1, 2);
+    }
+}
diff --git a/crates/core/src/grove/state.rs b/crates/core/src/grove/state.rs
new file mode 100644
index 00000000..25538199
--- /dev/null
+++ b/crates/core/src/grove/state.rs
@@ -0,0 +1,162 @@
+//! Per-node grove state.
+//!
+//! Built on top of [`crate::transport::TransportState`]. One [`GroveState`]
+//! per node; the publish mutex serialises leader-side mutation, and the
+//! cached signed payload provides the in-memory view of "current grove"
+//! that handlers and the dial loop read.
+
+use std::sync::Arc;
+
+use parking_lot::{Mutex, RwLock};
+
+use seedling_protocol::grove::SignedPayload;
+
+use crate::grove::db::{self, Membership};
+use crate::runtime::db::DbHandle;
+use crate::transport::TransportState;
+use crate::transport::auth::{TrustedKeys, new_trusted_keys};
+
+pub struct GroveState {
+    pub transport: Arc<TransportState>,
+    pub db: DbHandle,
+    /// Grove trust set: SPKI fingerprints of the current grove's members.
+    /// Reconciled by the apply pipeline (lands in commit 5) on every
+    /// payload-applied event. Registered against the shared trust registry
+    /// in [`Self::register`].
+    pub trust: TrustedKeys,
+    /// Single-writer lock for the leader publish pathway. Serialises
+    /// (load current → mutate → bump seq → sign → persist) so the
+    /// monotonic-seq invariant holds under concurrent operator-driven
+    /// mutations.
+    // g[impl versioning.seq]
+    pub publish_mutex: Mutex<()>,
+    /// In-memory cache of the latest applied signed payload, or `None` if
+    /// this node is not yet in any grove. Refreshed on construction and
+    /// on every payload-applied.
+    pub current: RwLock<Option<SignedPayload>>,
+}
+
+#[derive(Debug)]
+pub enum LoadError {
+    Db(db::LoadError),
+}
+
+impl std::fmt::Display for LoadError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Db(e) => write!(f, "{e}"),
+        }
+    }
+}
+
+impl std::error::Error for LoadError {}
+
+impl From<db::LoadError> for LoadError {
+    fn from(e: db::LoadError) -> Self {
+        Self::Db(e)
+    }
+}
+
+impl GroveState {
+    /// Construct a [`GroveState`] and populate the in-memory cache from the
+    /// DB. The grove trust set is also seeded from the latest signed
+    /// payload's membership list, so a daemon restart preserves grove
+    /// authorisation without waiting for a peer connection.
+    pub fn load(transport: Arc<TransportState>, db: DbHandle) -> Result<Arc<Self>, LoadError> {
+        let trust = new_trusted_keys();
+        let membership: Option<Membership> = db.call(db::load_membership)?;
+
+        if let Some(m) = &membership {
+            let mut t = trust.write();
+            for member in &m.current.payload.members {
+                t.insert(member.fp.clone());
+            }
+        }
+
+        Ok(Arc::new(Self {
+            transport,
+            db,
+            trust,
+            publish_mutex: Mutex::new(()),
+            current: RwLock::new(membership.map(|m| m.current)),
+        }))
+    }
+
+    /// Whether this node currently belongs to a grove.
+    pub fn is_member(&self) -> bool {
+        self.current.read().is_some()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use ed25519_dalek::SigningKey;
+    use jiff::Timestamp;
+    use rand_core::OsRng;
+    use uuid::Uuid;
+
+    use seedling_protocol::grove::{Member, Param, Payload, Role, SignedPayload};
+
+    use super::*;
+
+    fn fresh_transport() -> Arc<TransportState> {
+        TransportState::new(PathBuf::from("/tmp/seedling-grove-test-key"))
+    }
+
+    fn signed_payload_with_members(members: Vec<&str>) -> SignedPayload {
+        let key = SigningKey::generate(&mut OsRng);
+        Payload {
+            grove_id: Uuid::from_u128(1),
+            seq: 1,
+            created_at: Timestamp::from_second(1_700_000_000).unwrap(),
+            leader_fp: members.first().copied().unwrap_or("fp-leader").into(),
+            members: members
+                .into_iter()
+                .map(|fp| Member {
+                    fp: fp.into(),
+                    label: fp.into(),
+                })
+                .collect(),
+            params: vec![Param {
+                name: "p".into(),
+                kind: "text".into(),
+                value: "v".into(),
+            }],
+            secrets: vec![],
+        }
+        .sign(&key)
+        .expect("sign")
+    }
+
+    #[test]
+    fn load_returns_state_without_membership_on_fresh_db() {
+        let db = DbHandle::open_in_memory().expect("db");
+        let state = GroveState::load(fresh_transport(), db).expect("load");
+        assert!(!state.is_member());
+        assert!(state.trust.read().is_empty());
+    }
+
+    // g[verify trust]
+    #[test]
+    fn load_seeds_trust_set_from_persisted_membership() {
+        let db = DbHandle::open_in_memory().expect("db");
+        let signed = signed_payload_with_members(vec!["fp-a", "fp-b"]);
+        let m = Membership {
+            grove_id: signed.payload.grove_id,
+            role: Role::Leader,
+            leader_fingerprint: signed.payload.leader_fp.clone(),
+            joined_at: Timestamp::from_second(1_700_000_000).unwrap(),
+            current: signed,
+        };
+        db.call(move |db| db::write_membership(db, &m).expect("write"));
+
+        let state = GroveState::load(fresh_transport(), db).expect("load");
+        assert!(state.is_member());
+        let trusted = state.trust.read();
+        assert!(trusted.contains("fp-a"));
+        assert!(trusted.contains("fp-b"));
+        assert_eq!(trusted.len(), 2);
+    }
+}
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index 64ff0eb7..a9ef1d98 100644
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -1,6 +1,7 @@
 use rhai::{Engine, Scope};
 
 pub mod defs;
+pub mod grove;
 pub mod oi;
 pub mod runtime;
 pub mod sysconst;

From bfbf931d3883fe7842f12eaa748caa8d9b495dc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 22:56:01 +1200
Subject: [PATCH 10/11] feat(grove): leader publish operation with monotonic
 seq + size cap

Adds the canonical write-side primitives that grove init / invite /
revoke / param-set will all flow through. Both entry points serialise
on the publish mutex established in commit 4a, so seq is monotonic and
the on-disk membership row stays consistent with the latest signed
payload.

- GroveState::init: generates a fresh grove_id, builds a seq=1
  self-only payload, signs with the leader's transport key, persists.
  Rejects with AlreadyMember if the node already belongs to a grove.
- GroveState::publish: under the mutex, re-loads membership from DB to
  avoid acting on a stale cache, gates on role == leader, verifies the
  passed-in leader key matches the pinned leader_fingerprint, then
  applies a caller-supplied mutate closure to a PendingPayload (only
  members + params are mutable; seq, created_at, grove_id, leader_fp,
  secrets are managed). Bumps seq, canonicalises, size-checks, signs.
- finalise_publish: shared tail. Pre-publish size check rejects
  PayloadTooLarge before bumping seq or computing the signature
  (per the versioning.size-cap spec item). Persists membership +
  audit row + denormalised params projection in one transaction.
  Refreshes the in-memory cache and the grove trust set.
- Constants: PAYLOAD_SIZE_CAP_BYTES = 256 KiB, headroom = 16 KiB,
  effective publish cap = 240 KiB.

Adds Payload::canonical_size to seedling-protocol so core can size-check
without depending on serde_jcs directly.

Tests cover seq=1 invariant on init, seq bump on subsequent publish,
trust-set update, NotMember/AlreadyMember/NotLeader/LeaderKeyMismatch
errors, oversize rejection (and that seq does not advance on rejection),
signature verifies against the leader key, params projection picks up
the new value.
---
 crates/core/src/grove.rs         |   1 +
 crates/core/src/grove/publish.rs | 419 +++++++++++++++++++++++++++++++
 crates/protocol/src/grove.rs     |   7 +
 3 files changed, 427 insertions(+)
 create mode 100644 crates/core/src/grove/publish.rs

diff --git a/crates/core/src/grove.rs b/crates/core/src/grove.rs
index 6b918818..ebe79718 100644
--- a/crates/core/src/grove.rs
+++ b/crates/core/src/grove.rs
@@ -1,4 +1,5 @@
 pub mod db;
+pub mod publish;
 pub mod state;
 
 pub use state::GroveState;
diff --git a/crates/core/src/grove/publish.rs b/crates/core/src/grove/publish.rs
new file mode 100644
index 00000000..a0295668
--- /dev/null
+++ b/crates/core/src/grove/publish.rs
@@ -0,0 +1,419 @@
+//! Leader-side publish operations.
+//!
+//! All mutating leader actions (`grove init`, `grove invite`, `grove
+//! revoke`, `grove param set`/`unset`) flow through one of two entry
+//! points: [`GroveState::init`] (no current membership) or
+//! [`GroveState::publish`] (current membership exists). Both serialise on
+//! [`GroveState::publish_mutex`] so the seq is monotonic and the on-disk
+//! membership row is always consistent with the latest signed payload.
+
+use ed25519_dalek::SigningKey;
+use jiff::Timestamp;
+use uuid::Uuid;
+
+use seedling_protocol::grove::{
+    GroveError as ProtoError, Member, Param, Payload, Role, SignedPayload,
+};
+use seedling_protocol::keys;
+
+use crate::grove::db::{self, Membership};
+use crate::grove::state::GroveState;
+
+/// Hard maximum on the canonical-JSON byte length of a published payload.
+/// Receivers reject anything larger; the leader's pre-publish check
+/// reserves headroom below this.
+// g[impl versioning.size-cap]
+pub const PAYLOAD_SIZE_CAP_BYTES: usize = 256 * 1024;
+
+/// Reservation kept below [`PAYLOAD_SIZE_CAP_BYTES`]. Leader mutations
+/// that would push the next payload past `cap - headroom` are rejected
+/// at the point of mutation, before seq is bumped or the signature is
+/// computed.
+pub const PAYLOAD_SIZE_HEADROOM_BYTES: usize = 16 * 1024;
+
+/// Effective leader cap after subtracting the headroom reservation.
+pub const PAYLOAD_PUBLISH_CAP_BYTES: usize = PAYLOAD_SIZE_CAP_BYTES - PAYLOAD_SIZE_HEADROOM_BYTES;
+
+#[derive(Debug)]
+pub enum PublishError {
+    /// This node is not a member of any grove. Use [`GroveState::init`] first.
+    NotMember,
+    /// This node is a member but is a follower; only the leader may publish.
+    NotLeader,
+    /// `init` was called on a node that is already a member.
+    AlreadyMember,
+    /// The supplied signing key's SPKI fingerprint does not match the grove's
+    /// pinned `leader_fingerprint`. Almost always a configuration error.
+    LeaderKeyMismatch {
+        expected: String,
+        actual: String,
+    },
+    /// The candidate payload's canonical-JSON encoding exceeds the leader
+    /// publish cap. Operators must shrink the change set before retrying.
+    // g[impl versioning.size-cap]
+    PayloadTooLarge {
+        current_bytes: usize,
+        cap_bytes: usize,
+    },
+    /// In-version v0, secret grove parameters are rejected at the publish
+    /// boundary. The signed-payload `secrets` field is reserved but
+    /// always-empty in this version.
+    // g[impl params.no-secrets]
+    SecretsNotSupported,
+    Sign(ProtoError),
+    Db(db::LoadError),
+}
+
+impl std::fmt::Display for PublishError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NotMember => write!(f, "not a member of any grove"),
+            Self::NotLeader => write!(f, "publish requires the leader role"),
+            Self::AlreadyMember => write!(f, "node is already a member of a grove"),
+            Self::LeaderKeyMismatch { expected, actual } => write!(
+                f,
+                "leader key fingerprint {actual} does not match pinned leader {expected}"
+            ),
+            Self::PayloadTooLarge {
+                current_bytes,
+                cap_bytes,
+            } => write!(
+                f,
+                "next payload would be {current_bytes} bytes, exceeding the {cap_bytes}-byte publish cap"
+            ),
+            Self::SecretsNotSupported => write!(
+                f,
+                "secret grove params are not supported in this protocol version"
+            ),
+            Self::Sign(e) => write!(f, "sign: {e}"),
+            Self::Db(e) => write!(f, "db: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for PublishError {}
+
+/// View of the payload fields a leader operation may mutate. Other
+/// fields (`grove_id`, `seq`, `created_at`, `leader_fp`, `secrets`) are
+/// managed by [`GroveState::publish`] itself.
+pub struct PendingPayload {
+    pub members: Vec<Member>,
+    pub params: Vec<Param>,
+}
+
+impl GroveState {
+    /// Initialise a new grove with this node as leader. Generates a fresh
+    /// `grove_id`, creates a seq=1 self-only signed payload, persists,
+    /// and returns the signed payload.
+    ///
+    /// Fails with [`PublishError::AlreadyMember`] if this node is already
+    /// in a grove.
+    // g[impl bootstrap.init]
+    // g[impl membership.bootstrap]
+    pub fn init(
+        &self,
+        leader_key: &SigningKey,
+        leader_label: String,
+    ) -> Result<SignedPayload, PublishError> {
+        let _guard = self.publish_mutex.lock();
+        let existing: Option<Membership> = self
+            .db
+            .call(db::load_membership)
+            .map_err(PublishError::Db)?;
+        if existing.is_some() {
+            return Err(PublishError::AlreadyMember);
+        }
+
+        let leader_fp = keys::fingerprint(&keys::spki_der(leader_key));
+        let now = Timestamp::now();
+
+        let payload = Payload {
+            grove_id: Uuid::new_v4(),
+            seq: 1,
+            created_at: now,
+            leader_fp: leader_fp.clone(),
+            members: vec![Member {
+                fp: leader_fp.clone(),
+                label: leader_label,
+            }],
+            params: Vec::new(),
+            secrets: Vec::new(),
+        };
+
+        self.finalise_publish(payload, leader_key, Role::Leader, leader_fp, now)
+    }
+
+    /// Run a leader-side publish operation. Acquires the publish mutex,
+    /// loads the current membership from the DB inside the lock, applies
+    /// `mutate` to a clone of the current members + params, bumps seq,
+    /// canonicalises, size-checks, signs, and persists atomically.
+    // g[impl versioning.seq]
+    // g[impl membership.invite]
+    // g[impl membership.revoke]
+    // g[impl params.set]
+    // g[impl surface.role-gate]
+    pub fn publish<F>(
+        &self,
+        leader_key: &SigningKey,
+        mutate: F,
+    ) -> Result<SignedPayload, PublishError>
+    where
+        F: FnOnce(&mut PendingPayload),
+    {
+        let _guard = self.publish_mutex.lock();
+        let m: Membership = self
+            .db
+            .call(db::load_membership)
+            .map_err(PublishError::Db)?
+            .ok_or(PublishError::NotMember)?;
+        if m.role != Role::Leader {
+            return Err(PublishError::NotLeader);
+        }
+
+        let leader_fp = keys::fingerprint(&keys::spki_der(leader_key));
+        if leader_fp != m.leader_fingerprint {
+            return Err(PublishError::LeaderKeyMismatch {
+                expected: m.leader_fingerprint.clone(),
+                actual: leader_fp,
+            });
+        }
+
+        let mut pending = PendingPayload {
+            members: m.current.payload.members.clone(),
+            params: m.current.payload.params.clone(),
+        };
+        mutate(&mut pending);
+
+        let now = Timestamp::now();
+        let payload = Payload {
+            grove_id: m.current.payload.grove_id,
+            seq: m.current.payload.seq + 1,
+            created_at: now,
+            leader_fp: leader_fp.clone(),
+            members: pending.members,
+            params: pending.params,
+            secrets: Vec::new(),
+        };
+
+        self.finalise_publish(payload, leader_key, Role::Leader, leader_fp, m.joined_at)
+    }
+
+    fn finalise_publish(
+        &self,
+        mut payload: Payload,
+        leader_key: &SigningKey,
+        role: Role,
+        leader_fp: String,
+        joined_at: Timestamp,
+    ) -> Result<SignedPayload, PublishError> {
+        // g[impl params.no-secrets]
+        if !payload.secrets.is_empty() {
+            return Err(PublishError::SecretsNotSupported);
+        }
+        payload.canonicalise();
+        let size = payload.canonical_size().map_err(PublishError::Sign)?;
+        if size > PAYLOAD_PUBLISH_CAP_BYTES {
+            return Err(PublishError::PayloadTooLarge {
+                current_bytes: size,
+                cap_bytes: PAYLOAD_PUBLISH_CAP_BYTES,
+            });
+        }
+        let signed = payload.sign(leader_key).map_err(PublishError::Sign)?;
+
+        let m = Membership {
+            grove_id: signed.payload.grove_id,
+            role,
+            leader_fingerprint: leader_fp,
+            joined_at,
+            current: signed.clone(),
+        };
+        let signed_for_history = signed.clone();
+        let received_at = Timestamp::now();
+        let params_list = signed.payload.params.clone();
+        let new_seq = signed.payload.seq;
+
+        self.db
+            .call(move |db| -> Result<(), db::LoadError> {
+                let tx = db.conn.unchecked_transaction()?;
+                db::write_membership(db, &m)?;
+                db::insert_version(db, &signed_for_history, received_at)?;
+                db::replace_params(db, new_seq, &params_list)?;
+                tx.commit()?;
+                Ok(())
+            })
+            .map_err(PublishError::Db)?;
+
+        // g[impl trust]
+        *self.current.write() = Some(signed.clone());
+        let mut trust = self.trust.write();
+        trust.clear();
+        for member in &signed.payload.members {
+            trust.insert(member.fp.clone());
+        }
+
+        Ok(signed)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+    use std::sync::Arc;
+
+    use ed25519_dalek::SigningKey;
+    use rand_core::OsRng;
+
+    use seedling_protocol::keys;
+
+    use super::*;
+    use crate::runtime::db::DbHandle;
+    use crate::transport::TransportState;
+
+    fn fresh_state() -> (Arc<GroveState>, SigningKey) {
+        let db = DbHandle::open_in_memory().expect("db");
+        let transport = TransportState::new(PathBuf::from("/tmp/grove-publish-test-key"));
+        let state = GroveState::load(transport, db).expect("state");
+        (state, SigningKey::generate(&mut OsRng))
+    }
+
+    // g[verify bootstrap.init]
+    // g[verify membership.bootstrap]
+    #[test]
+    fn init_creates_seq_one_self_only_payload() {
+        let (state, key) = fresh_state();
+        let signed = state.init(&key, "leader".into()).expect("init");
+        assert_eq!(signed.payload.seq, 1);
+        assert_eq!(signed.payload.members.len(), 1);
+        let leader_fp = keys::fingerprint(&keys::spki_der(&key));
+        assert_eq!(signed.payload.members[0].fp, leader_fp);
+        assert_eq!(signed.payload.leader_fp, leader_fp);
+        assert!(state.is_member());
+        assert!(state.trust.read().contains(&leader_fp));
+    }
+
+    #[test]
+    fn init_fails_if_already_a_member() {
+        let (state, key) = fresh_state();
+        state.init(&key, "leader".into()).unwrap();
+        let err = state
+            .init(&key, "leader".into())
+            .expect_err("second init must fail");
+        assert!(matches!(err, PublishError::AlreadyMember));
+    }
+
+    // g[verify versioning.seq]
+    // g[verify membership.invite]
+    #[test]
+    fn publish_after_init_invite_bumps_seq_and_extends_membership() {
+        let (state, key) = fresh_state();
+        state.init(&key, "leader".into()).unwrap();
+        let signed = state
+            .publish(&key, |p| {
+                p.members.push(Member {
+                    fp: "fp-new".into(),
+                    label: "n".into(),
+                });
+            })
+            .expect("invite");
+        assert_eq!(signed.payload.seq, 2);
+        assert_eq!(signed.payload.members.len(), 2);
+        // canonicalise sorts alphabetically by fp; "fp-new" precedes the
+        // leader fingerprint only if it sorts that way, so just check both
+        // are present.
+        let fps: Vec<&str> = signed
+            .payload
+            .members
+            .iter()
+            .map(|m| m.fp.as_str())
+            .collect();
+        assert!(fps.contains(&"fp-new"));
+        let trust = state.trust.read();
+        assert_eq!(trust.len(), 2);
+        assert!(trust.contains("fp-new"));
+    }
+
+    // g[verify params.set]
+    #[test]
+    fn publish_param_set_appears_in_grove_params_table() {
+        let (state, key) = fresh_state();
+        state.init(&key, "leader".into()).unwrap();
+        state
+            .publish(&key, |p| {
+                p.params.push(Param {
+                    name: "greeting".into(),
+                    kind: "text".into(),
+                    value: "hello".into(),
+                });
+            })
+            .unwrap();
+        let listed = state.db.call(db::list_params).expect("list");
+        assert_eq!(listed.len(), 1);
+        assert_eq!(listed[0].0.name, "greeting");
+        assert_eq!(listed[0].0.value, "hello");
+        assert_eq!(listed[0].1, 2);
+    }
+
+    // g[verify surface.role-gate]
+    #[test]
+    fn publish_fails_on_non_member() {
+        let (state, key) = fresh_state();
+        let err = state.publish(&key, |_| {}).expect_err("must fail");
+        assert!(matches!(err, PublishError::NotMember));
+    }
+
+    // g[verify versioning.size-cap]
+    #[test]
+    fn publish_rejects_oversize_payload() {
+        let (state, key) = fresh_state();
+        state.init(&key, "leader".into()).unwrap();
+        let err = state
+            .publish(&key, |p| {
+                // Push enough members to blow past the publish cap.
+                let big_label = "x".repeat(1024);
+                for i in 0..1024 {
+                    p.members.push(Member {
+                        fp: format!("fp-padding-{i:08}"),
+                        label: big_label.clone(),
+                    });
+                }
+            })
+            .expect_err("must reject");
+        match err {
+            PublishError::PayloadTooLarge {
+                current_bytes,
+                cap_bytes,
+            } => {
+                assert!(
+                    current_bytes > cap_bytes,
+                    "got {current_bytes} <= cap {cap_bytes}"
+                );
+            }
+            other => panic!("expected PayloadTooLarge, got {other:?}"),
+        }
+        // Seq did not advance.
+        let m = state
+            .db
+            .call(db::load_membership)
+            .unwrap()
+            .expect("present");
+        assert_eq!(m.current.payload.seq, 1);
+    }
+
+    #[test]
+    fn publish_rejects_wrong_leader_key() {
+        let (state, leader_key) = fresh_state();
+        state.init(&leader_key, "leader".into()).unwrap();
+        let other_key = SigningKey::generate(&mut OsRng);
+        let err = state.publish(&other_key, |_| {}).expect_err("must reject");
+        assert!(matches!(err, PublishError::LeaderKeyMismatch { .. }));
+    }
+
+    #[test]
+    fn publish_signature_is_verifiable_against_leader_key() {
+        let (state, key) = fresh_state();
+        let signed = state.init(&key, "leader".into()).unwrap();
+        signed
+            .verify(&key.verifying_key())
+            .expect("signature must verify against leader key");
+    }
+}
diff --git a/crates/protocol/src/grove.rs b/crates/protocol/src/grove.rs
index 7cc33e81..c97ca0d9 100644
--- a/crates/protocol/src/grove.rs
+++ b/crates/protocol/src/grove.rs
@@ -90,6 +90,13 @@ impl Payload {
         Ok(buf)
     }
 
+    /// Length in bytes of [`Self::canonical_json`]. Used by the leader
+    /// publish path to enforce the wire-format size cap before bumping
+    /// seq or computing the signature.
+    pub fn canonical_size(&self) -> Result<usize, GroveError> {
+        Ok(self.canonical_json()?.len())
+    }
+
     /// Sign the payload with the leader's signing key.
     ///
     /// Canonicalises first, so callers do not need to remember to.

From 8bcdd71751c00fb6ff24c8c72cb6e8a1db85fe5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= <felix@bes.au>
Date: Thu, 7 May 2026 23:00:19 +1200
Subject: [PATCH 11/11] feat(oi): grove init / invite / revoke / params
 handlers

Wires the leader publish operation from commit 4b through the OI surface.
Adds eight dispatch entries under /grove/*: init, invite, revoke,
params/set, params/unset, status, members, params.

- OiState gains an OnceLock<Arc<GroveState>> 'grove' field. Daemon main
  loads GroveState from TransportState + DbHandle after OiState is built
  and attaches it via .set(). Handlers reach it through state.grove and
  return ServerBusy if it has not been attached.
- New oi/handler/grove.rs holds the handlers. Mutating handlers load the
  leader signing key on each call (via transport.key_path); not caching
  the key keeps long-lived signing material out of GroveState.
- PublishError variants map to OiError codes: AlreadyMember and
  duplicate-invite -> AlreadyInstalled; NotMember and unknown-fp ->
  NotFound; NotLeader, oversize, secret-rejected, leader-self-revoke ->
  RequirementsInvalid; Sign / Db / KeyMismatch -> Internal.
- invite checks for duplicate fingerprints before publishing; revoke
  refuses to remove the leader's own fp; param_set updates an existing
  entry in place rather than appending a duplicate.

No CLI yet (commit 8) and no event emission yet (commit 8). The
handlers return enough structured info that the response is useful on
its own.
---
 crates/core/src/oi/handler.rs       |  15 ++
 crates/core/src/oi/handler/grove.rs | 289 ++++++++++++++++++++++++++++
 crates/core/src/oi/state.rs         |   4 +
 crates/daemon/src/main.rs           |  12 ++
 4 files changed, 320 insertions(+)
 create mode 100644 crates/core/src/oi/handler/grove.rs

diff --git a/crates/core/src/oi/handler.rs b/crates/core/src/oi/handler.rs
index 1573b83d..33196dbb 100644
--- a/crates/core/src/oi/handler.rs
+++ b/crates/core/src/oi/handler.rs
@@ -15,6 +15,7 @@ mod appdef_json;
 mod apps;
 pub mod backups;
 mod faults;
+mod grove;
 mod images;
 mod ingresses;
 mod key_mgmt;
@@ -117,6 +118,20 @@ fn parse_and_dispatch(state: &Arc<OiState>, buf: &[u8], ctx: &RequestCtx) -> Han
         "/keys/authorise" => key_mgmt::authorize_key(state, parse_params(req.params)?),
         // i[key.revoke]
         "/keys/revoke" => key_mgmt::revoke_key(state, parse_params(req.params)?),
+        // g[impl bootstrap.init]
+        "/grove/init" => grove::init(state, parse_params(req.params)?),
+        // g[impl membership.invite]
+        "/grove/invite" => grove::invite(state, parse_params(req.params)?),
+        // g[impl membership.revoke]
+        "/grove/revoke" => grove::revoke(state, parse_params(req.params)?),
+        // g[impl params.set]
+        "/grove/params/set" => grove::param_set(state, parse_params(req.params)?),
+        // g[impl params.set]
+        "/grove/params/unset" => grove::param_unset(state, parse_params(req.params)?),
+        // g[impl identity]
+        "/grove/status" => grove::status(state),
+        "/grove/members" => grove::members(state),
+        "/grove/params" => grove::params(state),
         // i[shell.resize]
         "/shells/resize" => super::shells::resize_shell(state, parse_params(req.params)?),
         // i[shell.list]
diff --git a/crates/core/src/oi/handler/grove.rs b/crates/core/src/oi/handler/grove.rs
new file mode 100644
index 00000000..1fe0d335
--- /dev/null
+++ b/crates/core/src/oi/handler/grove.rs
@@ -0,0 +1,289 @@
+//! OI handlers for leader-side grove operations and read-only status.
+//!
+//! All mutating handlers load the leader signing key from the transport
+//! key path on every call (the key is small, file IO is cheap, and not
+//! caching it keeps the live grove state free of long-lived signing
+//! material). Mutations route through [`crate::grove::GroveState::publish`]
+//! or `init`; structural errors (not-leader, payload-too-large, etc.)
+//! map to typed [`ErrorCode`] values so the CLI and web surfaces can
+//! present them.
+
+use serde::Deserialize;
+use serde_json::{Value, json};
+
+use seedling_protocol::error::{ErrorCode, OiError};
+use seedling_protocol::grove::{Member, Param};
+use seedling_protocol::keys;
+
+use crate::grove::publish::PublishError;
+use crate::oi::state::OiState;
+
+use super::HandlerResult;
+
+#[derive(Deserialize)]
+pub(crate) struct InitParams {
+    /// Human-readable label for the leader's own membership entry.
+    /// Defaults to `"leader"` if omitted.
+    #[serde(default = "default_leader_label")]
+    pub label: String,
+}
+
+fn default_leader_label() -> String {
+    "leader".to_owned()
+}
+
+#[derive(Deserialize)]
+pub(crate) struct InviteParams {
+    pub fingerprint: String,
+    pub label: String,
+}
+
+#[derive(Deserialize)]
+pub(crate) struct RevokeParams {
+    pub fingerprint: String,
+}
+
+#[derive(Deserialize)]
+pub(crate) struct ParamSetParams {
+    pub name: String,
+    pub kind: String,
+    pub value: String,
+    /// Reserved for future versions; setting `secret = true` is rejected
+    /// with [`ErrorCode::RequirementsInvalid`] in this protocol version.
+    #[serde(default)]
+    pub secret: bool,
+}
+
+#[derive(Deserialize)]
+pub(crate) struct ParamUnsetParams {
+    pub name: String,
+}
+
+fn grove(state: &OiState) -> Result<&crate::grove::GroveState, OiError> {
+    state
+        .grove
+        .get()
+        .map(|arc| arc.as_ref())
+        .ok_or_else(|| OiError::new(ErrorCode::ServerBusy, "grove state not yet initialised"))
+}
+
+fn load_leader_key(state: &OiState) -> Result<ed25519_dalek::SigningKey, OiError> {
+    keys::load_or_generate(&state.transport.key_path).map_err(|e| {
+        OiError::new(
+            ErrorCode::Internal,
+            format!("loading leader signing key: {e}"),
+        )
+    })
+}
+
+fn publish_error_to_oi(e: PublishError) -> OiError {
+    let (code, msg) = match e {
+        PublishError::NotMember => (
+            ErrorCode::NotFound,
+            "node is not a member of any grove".to_owned(),
+        ),
+        PublishError::NotLeader => (
+            ErrorCode::RequirementsInvalid,
+            "this operation requires the leader role".to_owned(),
+        ),
+        PublishError::AlreadyMember => (
+            ErrorCode::AlreadyInstalled,
+            "node is already a member of a grove".to_owned(),
+        ),
+        PublishError::LeaderKeyMismatch { expected, actual } => (
+            ErrorCode::Internal,
+            format!("leader key fingerprint {actual} does not match pinned leader {expected}"),
+        ),
+        PublishError::PayloadTooLarge {
+            current_bytes,
+            cap_bytes,
+        } => (
+            ErrorCode::RequirementsInvalid,
+            format!(
+                "next payload would be {current_bytes} bytes, exceeding the {cap_bytes}-byte publish cap"
+            ),
+        ),
+        PublishError::SecretsNotSupported => (
+            ErrorCode::RequirementsInvalid,
+            "secret grove parameters are not supported in this protocol version".to_owned(),
+        ),
+        PublishError::Sign(e) => (ErrorCode::Internal, format!("payload sign: {e}")),
+        PublishError::Db(e) => (ErrorCode::Internal, format!("grove db: {e}")),
+    };
+    OiError::new(code, msg)
+}
+
+// g[impl bootstrap.init]
+pub(crate) fn init(state: &OiState, params: InitParams) -> HandlerResult {
+    let key = load_leader_key(state)?;
+    let signed = grove(state)?
+        .init(&key, params.label)
+        .map_err(publish_error_to_oi)?;
+    Ok(json!({
+        "grove_id": signed.payload.grove_id,
+        "seq": signed.payload.seq,
+        "leader_fp": signed.payload.leader_fp,
+    }))
+}
+
+// g[impl membership.invite]
+pub(crate) fn invite(state: &OiState, params: InviteParams) -> HandlerResult {
+    let key = load_leader_key(state)?;
+    let g = grove(state)?;
+    let fingerprint = params.fingerprint.clone();
+    let label = params.label.clone();
+
+    {
+        // Reject obvious duplicates with a clean error rather than letting
+        // the publish go through with a duplicate member entry.
+        let cur = g.current.read();
+        if let Some(s) = cur.as_ref()
+            && s.payload.members.iter().any(|m| m.fp == fingerprint)
+        {
+            return Err(OiError::new(
+                ErrorCode::AlreadyInstalled,
+                format!("fingerprint already a member: {fingerprint}"),
+            ));
+        }
+    }
+
+    let signed = g
+        .publish(&key, |p| {
+            p.members.push(Member {
+                fp: fingerprint,
+                label,
+            });
+        })
+        .map_err(publish_error_to_oi)?;
+    Ok(json!({
+        "seq": signed.payload.seq,
+        "members_count": signed.payload.members.len(),
+    }))
+}
+
+// g[impl membership.revoke]
+pub(crate) fn revoke(state: &OiState, params: RevokeParams) -> HandlerResult {
+    let key = load_leader_key(state)?;
+    let g = grove(state)?;
+    let fingerprint = params.fingerprint.clone();
+
+    {
+        let cur = g.current.read();
+        let s = cur.as_ref().ok_or_else(|| {
+            OiError::new(ErrorCode::NotFound, "node is not a member of any grove")
+        })?;
+        if !s.payload.members.iter().any(|m| m.fp == fingerprint) {
+            return Err(OiError::not_found(format!("not a member: {fingerprint}")));
+        }
+        if fingerprint == s.payload.leader_fp {
+            return Err(OiError::new(
+                ErrorCode::RequirementsInvalid,
+                "cannot revoke the leader's own membership",
+            ));
+        }
+    }
+
+    let signed = g
+        .publish(&key, |p| {
+            p.members.retain(|m| m.fp != fingerprint);
+        })
+        .map_err(publish_error_to_oi)?;
+    Ok(json!({
+        "seq": signed.payload.seq,
+        "members_count": signed.payload.members.len(),
+    }))
+}
+
+// g[impl params.set]
+pub(crate) fn param_set(state: &OiState, params: ParamSetParams) -> HandlerResult {
+    if params.secret {
+        return Err(OiError::new(
+            ErrorCode::RequirementsInvalid,
+            "secret grove parameters are not supported in this protocol version",
+        ));
+    }
+    let key = load_leader_key(state)?;
+    let name = params.name.clone();
+    let kind = params.kind.clone();
+    let value = params.value.clone();
+    let signed = grove(state)?
+        .publish(&key, |p| {
+            if let Some(existing) = p.params.iter_mut().find(|q| q.name == name) {
+                existing.kind = kind;
+                existing.value = value;
+            } else {
+                p.params.push(Param { name, kind, value });
+            }
+        })
+        .map_err(publish_error_to_oi)?;
+    Ok(json!({ "seq": signed.payload.seq }))
+}
+
+// g[impl params.set]
+pub(crate) fn param_unset(state: &OiState, params: ParamUnsetParams) -> HandlerResult {
+    let key = load_leader_key(state)?;
+    let g = grove(state)?;
+    let name = params.name.clone();
+    {
+        let cur = g.current.read();
+        let s = cur.as_ref().ok_or_else(|| {
+            OiError::new(ErrorCode::NotFound, "node is not a member of any grove")
+        })?;
+        if !s.payload.params.iter().any(|q| q.name == name) {
+            return Err(OiError::not_found(format!("grove param not set: {name}")));
+        }
+    }
+    let signed = g
+        .publish(&key, |p| {
+            p.params.retain(|q| q.name != name);
+        })
+        .map_err(publish_error_to_oi)?;
+    Ok(json!({ "seq": signed.payload.seq }))
+}
+
+// g[impl identity]
+pub(crate) fn status(state: &OiState) -> HandlerResult {
+    let g = grove(state)?;
+    let cur = g.current.read();
+    Ok(match cur.as_ref() {
+        None => json!({ "is_member": false }),
+        Some(s) => json!({
+            "is_member": true,
+            "grove_id": s.payload.grove_id,
+            "leader_fp": s.payload.leader_fp,
+            "current_seq": s.payload.seq,
+            "members_count": s.payload.members.len(),
+            "params_count": s.payload.params.len(),
+        }),
+    })
+}
+
+pub(crate) fn members(state: &OiState) -> HandlerResult {
+    let g = grove(state)?;
+    let cur = g.current.read();
+    let list: Vec<Value> = match cur.as_ref() {
+        None => Vec::new(),
+        Some(s) => s
+            .payload
+            .members
+            .iter()
+            .map(|m| json!({ "fingerprint": m.fp, "label": m.label }))
+            .collect(),
+    };
+    Ok(json!(list))
+}
+
+pub(crate) fn params(state: &OiState) -> HandlerResult {
+    let g = grove(state)?;
+    let cur = g.current.read();
+    let list: Vec<Value> = match cur.as_ref() {
+        None => Vec::new(),
+        Some(s) => s
+            .payload
+            .params
+            .iter()
+            .map(|p| json!({ "name": p.name, "kind": p.kind, "value": p.value }))
+            .collect(),
+    };
+    Ok(json!(list))
+}
diff --git a/crates/core/src/oi/state.rs b/crates/core/src/oi/state.rs
index 782805d9..5ae29e20 100644
--- a/crates/core/src/oi/state.rs
+++ b/crates/core/src/oi/state.rs
@@ -20,6 +20,10 @@ pub struct OiState {
     /// `spki_fingerprint` and `trusted_keys` so existing handler code can
     /// continue to access them without indirection.
     pub transport: Arc<TransportState>,
+    /// Sibling grove state, attached after construction so its handler
+    /// closures can reach it. Set once at daemon startup, after both
+    /// `OiState` and `GroveState` have been built; never changes after.
+    pub grove: OnceLock<Arc<crate::grove::GroveState>>,
     pub registry: Arc<RwLock<AppRegistry>>,
     /// Server SPKI SHA-256 fingerprint. Set once by the transport endpoint
     /// after key generation; never changes after that. Arc-shared with
diff --git a/crates/daemon/src/main.rs b/crates/daemon/src/main.rs
index 6c901175..50f91669 100644
--- a/crates/daemon/src/main.rs
+++ b/crates/daemon/src/main.rs
@@ -1038,6 +1038,7 @@ async fn main() {
 
     let oi_state = Arc::new(OiState {
         transport: Arc::clone(&transport_state),
+        grove: std::sync::OnceLock::new(),
         registry: Arc::clone(&registry),
         spki_fingerprint: Arc::clone(&transport_state.spki_fingerprint),
         start_time: Instant::now(),
@@ -1294,6 +1295,17 @@ async fn main() {
         });
     }
 
+    let grove_state =
+        seedling_core::grove::GroveState::load(Arc::clone(&transport_state), db.clone())
+            .unwrap_or_else(|e| {
+                tracing::error!("loading grove state failed: {e}");
+                std::process::exit(1);
+            });
+    oi_state
+        .grove
+        .set(Arc::clone(&grove_state))
+        .unwrap_or_else(|_| panic!("OiState.grove was already set"));
+
     oi::register(&transport_state, &oi_state, &data_dir, args.max_streams).unwrap_or_else(|e| {
         tracing::error!("OI registration failed: {e}");
         std::process::exit(1);