feat: multi-network support with runtime network registration

[zippy]

Context

I admit that this is a too big AI generated PR. But I've been around the block with it a number of times and looked at it pretty carefully.

Note that it brings in one part of what the unyt fork was about, improving handling how to reconnect during a partial join. The second of that fork is addressed in the followup branch feat/worker-kv-parity.

For review I think the most important part is making sure that the API matches what's needed by the automation pipeline.

Description

---

Second half of #13 (with the allowed-agent registration PR): one joining service serves many networks, each identified by its happ_id. A pipeline registers a network — per-role DNA config, optional hApp metadata, and its progenitor — in one call:

curl -X POST https://join.example.com/v1/admin/networks \
  -H "Authorization: Bearer $JOINING_ADMIN_SECRET" \
  -d '{
    "happ_id": "acme-net",
    "happ": { "name": "Acme", "happ_bundle_url": "https://..." },
    "roles": { "main": { "dna_hash": "uhC0k...", "modifiers": { "network_seed": "..." } } },
    "allowed_agents": ["uhCAk...progenitor..."]
  }'

• Discovery routes by happ_id with no format change: .well-known/holo-joining already carries happ_id; JoiningClient.discover() now passes it through to join(), so an app on a registered network just hosts the standard document. GET /v1/info/<happ_id> serves per-network info; bare /v1/info (and /v1/info/<static happ id>) means the statically configured network.
• Purely-dynamic services are first-class: no config.roles needed — register networks at runtime only.
• Joins name a network via the network body field (a happ_id; the static id is equivalent to omitting it). Sessions are scoped per (agent, network): one key can join any number of networks; same-network re-joins 409. Non-empty allowed_agents gates a network (403 join_rejected for unlisted agents) — and gated networks do NOT expose their role modifiers via info; joiners get them at provision.
• Provision serves the session's network's roles, membrane proofs, and its own happ_bundle_url. dna_hash per role is required only when membrane proofs are enabled.
• Session recovery: POST /v1/reconnect accepts an optional network and returns the agent's session token for that scope, so an agent that crashes between joining and installing can recover instead of being permanently stuck behind 409 agent_already_joined. Recovery is keyed on the one thing the client durably holds first — its agent private key — via the existing signed-timestamp check; /v1/join is deliberately NOT made idempotent (that would turn any public agent key into a provisioning credential). JoiningClient gains reconnectAndProvision().
• New NetworkStore (memory / sqlite networks.db / Cloudflare KV) and network_registration.admin_secret config; admin middleware is path-scoped (three-way coexistence with linker and agent admin surfaces regression-tested).
• Cross-network dna_hash uniqueness is enforced at registration (409 duplicate_dna_hash, checked against other registered networks and the static roles) — duplicate hashes would let one agent be provisioned twice for the same cell, forking the chain. Best-effort on KV (eventual consistency), noted in docs.

Breaking / operational notes:

• Client behavior change: after discover(), join() defaults network to the document's happ_id. Verify an app domain's .well-known happ_id matches the service's static happ id (or a registered network) before deploying; pass network: null to suppress the default.
• Each network join re-recheks the key with hc-auth — deployments with hc_auth.required want the hc-auth client misreads /request-auth status codes #15 status-mapping fix first.
• Reconnect's replay window now has a larger blast radius: the signed payload is the timestamp alone (300s tolerance) and ready sessions never expire, so an observed reconnect body replayed within the window now yields a session token — i.e. network_config, the bundle URL, and a mintable membrane proof, where previously it yielded only public infra URLs. Deliberately unchanged here (changing the signed payload breaks existing signers); worth a follow-up to cover agent_key and a nonce.
• network_config (bootstrap/relay/auth-server URLs) remains service-wide.
• No sqlite migration ships, by design. The sessions table gains a network column and networks.db is new, but nothing upgrades an existing file — there is no deployed data to preserve at this stage. Anyone who ran an earlier build locally should delete sessions.db and networks.db before running this one. Sessions are ephemeral (pending ones expire on TTL), so there is nothing worth carrying across.

Stacks on the role-centric config PR (#18) and the allowed-agent registration PR (#17) — merge those first (this branch is based on both).

Followed by feat/worker-kv-parity, which brings the Cloudflare Worker entry point up to parity with Node. That work was split out of this branch: it touches only deploy/ and the auth-plugin construction shared by both entry points, and reviews independently.

---

Commits (7)

Commit	Concern
feat: NetworkStore with memory, sqlite, and KV backends	The store, happ_id-keyed, three backends
feat: multi-network registration with network-aware join and provision	Admin routes, app wiring, per-network info, conditional dna_hash
feat: enforce dna_hash uniqueness across registered networks	409 duplicate_dna_hash
feat: pass network through JoiningClient and provision CLI	Client + CLI
docs: network registration, happ_id identity, and network-aware joining	API + CLI docs; corrects CLI.md's single-network assumptions about where roles come from
feat: scope join sessions by agent and network, with reconnect recovery	Session scoping + reconnect token
docs: per-network session semantics and reconnect recovery

Diff vs base: 37 files, +3479/-103.

[ThetaSinner]

Yes, this is too big to review in a sensible amount of time. Accepting it as it is and I'll test it when it's made available downstream.