feat!: absorb leaf-sync; an agent can be its site's NATS leaf node

[skeeeon]

The leaf-sync binary that lived in the platform repo is gone; its duties are agent capabilities now. A site that runs a NATS leaf node is an ordinary Thing whose agent has those capabilities turned on.

Pairs with stone-age-io/platform, which drops leaf_nodes and cmd/leaf-sync, and stone-age-io/platform-docs.

Four capabilities, each independently switchable

• agent -leaf-config — one-shot: authenticate as this agent's Thing, call GET /api/me/leaf-config, write nats-leaf.conf (0644) beside the creds (0600). It has to be separable from running: the usual edge shape is a separately supervised nats-server, and that server needs its config file before it starts — which is before the agent has anything to connect to.
• nats.server_config — host a nats-server in this process from that file. It points at any nats-server config, not only a generated one, so it is equally how you run a plain embedded broker on a box with no platform. Left empty, systemd or Docker supervises nats-server and the bus survives an agent restart, which is what you want when upgrading the agent on a live site.
• twin.enabled — relay this site's reported state up, mirror desired state down, so the site keeps deciding locally through a WAN outage.
• observability.addr — /ready and /metrics on the box. cmd.health travels over NATS, which is the link that breaks: the box you most need to ask is the one whose uplink is down, and that is exactly when it goes quiet.

There is no edge.enabled key, and no gateway flag on the platform either. "Gateway" is not a mode the config declares, it is the sum of the capabilities it turns on — edge.enabled: false beside twin.enabled: true has no correct behaviour. A gateway is just a Thing whose thing_type says so.

What did not come across

The config mirror. leaf-sync copied an organization's inventory collections into local KV and nothing ever read them. Dropping it is also what lets a gateway need no read grant across the inventory.

Its remains were dead code the compiler could not see: kvWriter and its per-collection bucket helper came across with the package, and Go does not flag unused types or methods — only unused locals and imports — so it built clean. Removed, and every other unexported symbol in edge and observe swept for the same shape.

Breaking: the platform relationship moved to a top-level platform: block

auth.type: "stone-age" becomes "platform". Three subsystems read this relationship — the NATS credential lifecycle, the Nebula config source, and the new leaf bootstrap — and buried under nats.auth the other two had to ask "is some other section's type field set to a particular string" instead of "is the block present".

tasks.creds_sync is gone, replaced by platform.sync_interval. Its enabled flag was not a state worth being able to express: an agent told to fetch credentials but not keep them current stops working in seven days.

One test that was not allowed to change

TestBuildLeafConfIsAcceptedByNATSServer moved unchanged apart from its imports. It runs the real generator's output through nats-server's own ProcessConfigFile + NewServer (no ports, no network), and it is the only thing that can catch the two operator-mode directives that were missing for months while substring assertions passed:

1. every leaf remote needs an account key naming the local account;
2. resolver_preload needs the $SYS account JWT as well as the org's — the operator JWT names a system account and resolver: MEMORY has nowhere to fetch it, so without it the server dies with error resolving system account: account missing before JetStream starts.

Preloading $SYS's account JWT is public trust material and grants nothing; connecting as $SYS needs a $SYS user credential, which is never served.

Duplicated on purpose

internal/health, internal/metrics and internal/natsd are copies of the platform repo's, not an extracted shared module. Two small copies that drift are cheaper to live with than a third repo to version and keep both consumers pinned to, and the two processes check genuinely different things — the Control Plane cannot answer anything about a site, and the agent cannot answer anything about the fleet. Noted in both CLAUDE.md files so the next person does not "fix" it.

Related: an islanded edge warns, it does not fail. Local NATS still works and devices keep publishing and subscribing locally; that autonomy is why a leaf node exists, so returning 503 would invert the design.

Documentation

New docs/leaf-node.md carries the reasoning that previously existed only in the platform repo's cmd/leaf-sync README — the $SYS preload, the two mandatory directives, one-writer-per-bucket with the number that made the case (~170k writes to a single key in 300ms when both ends wrote one bucket), the relay-vs-mirror asymmetry, and a "What went away" section including the publish-DENY trap.

CLAUDE.md, README.md, CHANGELOG.md, docs/credentials.md, docs/architecture.md, the three platform install guides, docs/nebula*.md and .goreleaser.yaml all follow the platform: block.

The docs pass also caught two user-visible strings that survived the package move: the generated nats-leaf.conf carried a header naming leaf-sync config, a command that no longer exists, on the file an operator reads when something breaks — and twin.go logged leaf-sync: on every warning, one of which told the reader to delete a bucket "to have leaf-sync recreate it".

Verification

Build and vet clean for linux/amd64, windows/amd64, freebsd/amd64 and linux/arm64. TestExampleConfigsParse passes for all three example configs. TestBuildLeafConfIsAcceptedByNATSServer passes.

internal/tasks fails on this Windows box (service-manager access denied, log-path allowlist); git status confirms that package is untouched by this work and the failures are environmental.

---

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

🤖 Generated with Claude Code