refactor!: an edge site is a Thing; drop leaf_nodes and leaf-sync

[skeeeon]

An edge site is a Thing. This drops the leaf_nodes auth collection, the cmd/leaf-sync binary and the config mirror, and replaces the site-connectivity view with a live query to NATS.

The agent that ran those leaf nodes now lives in stone-age-io/agent and absorbs the binary; the docs follow in stone-age-io/platform-docs.

Why each of the three went

• The mirror. leaf-sync copied an organization's inventory collections into the edge's local KV so devices could read them offline. Nothing consumed the mirrored rows — no rule-router rule, no firmware — so it was moving data nobody asked for, and it was the reason an edge identity needed read grants spread across the inventory. If a real consumer appears, the thing to build is that consumer's read path, not a general mirror.
• The collection. With the mirror gone, a leaf node was a Thing with a domain column and one provisioned NATS user. thing_types already says whether a device is a gateway, and a second marker is a second thing to get wrong. domain was a second copy of the code that could disagree with it — and when it did, the site simply stopped appearing.
• leaf_status. The heartbeat travelled over the very link whose failure it reported, so a missing beat could not distinguish "edge box down" from "WAN down" from "agent crashed". The Control Plane could not read it anyway: it holds the operator and $SYS, and no credential inside any tenant account.

What replaces them

GET /api/me/leaf-config (hooks/leaf_config_routes.go), bound to things, taking no record id. Ten named fields — everything a NATS leaf server needs to come up.

It gates on nothing, deliberately. Everything it serves is either public trust material (the operator, account and $SYS account JWTs, which every server in the network validates) or the caller's own credential, which it must already hold to connect at all. A Thing that will never run a leaf can ask and learns nothing it could not already read. A gate here would be a permission over data that is not secret — and it would need the marker field this change exists to avoid inventing.

The consequence worth keeping: a gateway needs no read grant on any nats_* or nebula_* collection. The edge's blast radius is a fixed list of named fields rather than a consequence of rules that change for unrelated reasons.

The JetStream domain is the Thing's code, computed and never stored. No edge- prefix and no org-code segment: JetStream is already inside the account, so the account is the namespace.

Site connectivity is asked of NATS, not stored. The console requests $SYS.REQ.ACCOUNT.PING.CONNZ over the browser's own in-account connection and matches kind: "Leafnode" entries by name to a Thing's code (ui/src/composables/useLeafConnections.ts). The hub always knows which leaves it is holding, so ask the hub.

It renders as one row in the Thing page's NATS card, not a separate screen. An "Edge Sites" list view was built during this change and deleted: a site is a Thing, it already has a list, and a second inventory list is a second list that can disagree with the first. The badge's empty state is neutral none, not error-red — the console cannot distinguish a down gateway from a Thing that will never run a leaf at all.

The $SYS asymmetry, pinned by a test

Each account carries its own $SYS subject space, so $SYS.REQ.ACCOUNT.PING.* answers for that organization and no other, while $SYS.REQ.SERVER.PING.* spans every tenant and is operator-only. internal/health/leaf_visibility_test.go asserts all three halves against a real hub with a real leaf attached, because fixtures cannot answer a question about the server's own trust decision:

1. a tenant can read CONNZ for its own account;
2. it cannot reach the operator-wide $SYS.REQ.SERVER endpoints;
3. a publish DENY beats a publish ALLOW.

The third is the trap. A nats_roles entry carrying $SYS.> in its publish deny list cannot reach the account endpoints no matter what its allow list says — and the symptom is a plain request timeout, with the real reason arriving asynchronously on the connection's error handler and never on the request. Deny $SYS.REQ.SERVER.> instead. internal/demoseed/contract.go says so at the one place that sets it.

Migrations

migrations/schema_update_drop_leaf_nodes.go re-imports schema.json and then deletes the collection — a re-import alone cannot remove one.

It deliberately leaves the orphaned nats_users and nebula_hosts rows working, and reports them. A leaf node's relations are all non-cascade, so deleting the collection strands two signed, live credentials. Revoking them here would have been the tidy thing to do and the wrong one: those credentials are what the edge boxes at real sites are connected with right now, and a migration that runs on deploy is not a place to take a fleet off the bus. Deactivate them from the console once each site runs against its Thing — deactivate, not delete, since revoking a Nebula certificate needs it in the database to fingerprint.

Two historical migrations were edited in place, which needs saying out loud:

• schema_update_device_active_flag.go ran a fatal UPDATE {{leaf_nodes}} backfill that breaks a fresh migrate up once the table is gone. Caught by the new migration test, not by the build.
• schema_update_unique_org_code.go listed the collection in a sweep that would log "table not present yet" about a table that is never coming.

The file names stay. The _migrations ledger and the schema_version readiness check key on them, so deleting the files would 503 every existing deployment. Both files carry a comment explaining the edit.

migrations/drop_leaf_nodes_test.go restores the pre-drop shape from testdata/ through the real importer first — a fresh database imports the already-thinned schema.json, so a removal migration tested by migrate up reaches nothing to remove and passes without touching anything. It also pins TestNothingRelatesIntoLeafNodes, since PocketBase refuses to delete a collection with relations still pointing at it.

Upgrade order

Agents first, Control Plane second. An older leaf-sync keeps running on its already-generated nats-leaf.conf — the bus does not drop — but it can no longer log in or re-fetch anything.

Verification

• go build / go vet / go test ./... pass; gofmt clean against git-stored content.
• vue-tsc && vite build clean; npm test 174 passed across 10 files.
• ./scripts/check-sort-fields.sh — 54 terms resolve.
• ./scripts/test-authz.sh — 194 passed, 0 failed (was 204: 11 leaf checks removed, the code-freeze pair moved to things, one added asserting a superuser gets 404 on leaf_nodes).

---

Merge with agent: stone-age-io/agent#4 and docs: stone-age-io/platform-docs#6 — the three land together.

🤖 Generated with Claude Code