From 505c424750c460e31819f657574b455f9fd6d0b5 Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 11 Oct 2026 01:24:43 -0400 Subject: [PATCH] Define cellular life owner routing --- docs/adr/0116-cellular-life-owner-routing.md | 90 ++++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/M11_2_DELIVERY_PLAN.md | 14 ++- 3 files changed, 97 insertions(+), 8 deletions(-) create mode 100644 docs/adr/0116-cellular-life-owner-routing.md diff --git a/docs/adr/0116-cellular-life-owner-routing.md b/docs/adr/0116-cellular-life-owner-routing.md new file mode 100644 index 0000000..fa3d694 --- /dev/null +++ b/docs/adr/0116-cellular-life-owner-routing.md @@ -0,0 +1,90 @@ +# ADR-0116: Cellular life-owner routing + +## Status + +Accepted M11.2 engineering contract under the maintainer's standing +authorization to proceed with recommendations and revisit decisions after +implementation. It does not add organism migration or a gameplay rule. + +## Context + +ADR-0100 requires reconnect to preserve the account's one nonterminal life and +route control to the region that owns it. The durable reservation identifies +that region, but the login path currently claims account control locally before +resolving biological ownership. The session protocol already has a +server-to-client `SessionRedirect`, and the engineering client already follows +it using a region-scoped grant from its grant bundle. Existing M10 neighbor +addresses describe spatial probe handoff and are not a complete cellular route +catalog. + +## Decision + +- Resolve the account's active life reservation from durable world/account + state after verifying the signed grant and validating its world, region, + lifetime and serial, but before claiming durable account control. A query + failure fails closed. If no nonterminal reservation exists or its owner is + this region, login proceeds normally. If another region owns it, the session + sends the existing `SessionRedirect` followed by `Close(moved)` without + changing account control at the contacted region. +- Reuse the `SessionRedirect` message inherited by v5-v8. No life identity, + owner region or endpoint is added to the primitive-life outcome, and frozen + v5-v8 layouts remain unchanged. The client matches the redirected region to a + grant in its existing bundle and dials the supplied endpoint with that + region-scoped grant. If the bundle has no usable grant, it reports that the + bundle must be refreshed rather than falling back to the original region. +- Each cellular region process receives a complete operator-provisioned route + catalog for its world, mapping region identity to the client endpoint and TLS + server name. This catalog is separate from physical neighbors. The server + rejects duplicate, invalid, wrong-world or self-conflicting entries at + startup. It emits a redirect only when the durable owner is in this catalog; + a missing destination fails closed. A client-supplied endpoint is never + accepted as routing authority. +- The route address is authenticated by the existing QUIC TLS certificate-name + and CA checks. The source server's verified response is the only input to the + in-memory client route update. A destination grant is still independently + verified by that destination region. +- A provisioned but not yet published reservation is routed to its reservation + region as well. It is never treated as a live life. The owning region's + existing exact-request query/retry resolves its pending birth. Terminal-life + eligibility remains governed by the later death contract; 11.2 has no + terminal primitive-life transition. + +## Alternatives considered + +- **Add the owner region to a new protocol version:** unnecessary because + `SessionRedirect` already carries an owner address and is handled by the + current client. It would duplicate routing metadata and force new protocol + negotiation for a server-only lookup. +- **Use the neighbor list:** rejected because life ownership is not spatial + adjacency and arbitrary region owners need not be neighbors. +- **Trust a client endpoint or account-provided URL:** rejected because it + permits endpoint substitution and cannot establish region ownership. +- **Add an inter-region proxy:** deferred. It would move routing and session + lifetime into a new server service, while the existing client redirect path + already performs the required switch. +- **Move the organism when control changes:** rejected by ADR-0100; account + control changes do not transfer biological state. + +## Benefits + +The contacted region resolves owner state from the durable world/account +reservation, routes before taking control, and uses an already implemented +client switch. Existing session wire layouts and one-owner biological state +remain intact. + +## Costs and risks + +The operator must keep each cellular server's world route catalog synchronized +with deployment endpoints. A missing/stale entry causes a closed login or a +failed TLS connection, never an untrusted redirect. A runtime owner-lookup +outage makes login unavailable. Process-kill, lost-response and restart tests +must still prove the existing owner and request outcome survive failures. + +## Consequences + +Implementation requires a read-only durable world/account owner lookup, a +validated per-world route catalog in cellular session configuration, and a +QUIC/client regression covering redirect-before-control-claim plus destination +grant selection. M11.2 remains open until that implementation, process-kill +qualification and restart retry pass. M11.3's exploratory single-region probe +does not depend on multi-region routing. diff --git a/docs/adr/README.md b/docs/adr/README.md index 75efa49..2556b00 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -16,6 +16,7 @@ - [ADR-0113: Cellular replay trace](0113-cellular-replay-trace.md) - specifies bounded per-tick life intentions for deterministic profile-4 replay and durable action reconciliation. - [ADR-0114: First player life in cellular profile 4](0114-cellular-first-life-publication.md) - accepted M11.3 engineering direction: preserve empty genesis and add an allocator-backed, durable profile-4 birth operation so the 11.3e probe can start through the normal player path. - [ADR-0115: Owner-filtered cellular perception protocol v8](0115-cellular-owner-perception-v8.md) - carries the existing exact sensor view only to its authenticated owner without changing v1-v7 behavior. +- [ADR-0116: Cellular life-owner routing](0116-cellular-life-owner-routing.md) - reuses authenticated SessionRedirect with an operator-provisioned per-world region route catalog; owner lookup happens before account-control claim. - [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows. diff --git a/docs/engineering/M11_2_DELIVERY_PLAN.md b/docs/engineering/M11_2_DELIVERY_PLAN.md index b0cf437..9f599ba 100644 --- a/docs/engineering/M11_2_DELIVERY_PLAN.md +++ b/docs/engineering/M11_2_DELIVERY_PLAN.md @@ -131,15 +131,13 @@ Local checks do not close ADR-0097's reference-worker qualification. The Linux/PostgreSQL process suite now provisions an isolated primitive region, creates a life over v5, restarts the host and checks the same durable result; execution remains pending CI. -- Cross-region owner routing and reconnect-to-existing-life are not complete. - The accepted v5 outcome has no owner-region/address field, while the delivery - row requires routing. The host can identify a different reservation owner but - the wire contract cannot direct a client there. Resolve this contract before - implementing routing; do not claim 11.2 complete until owner routing, +- Cross-region owner routing and reconnect-to-existing-life remain unimplemented. + [ADR-0116](../adr/0116-cellular-life-owner-routing.md) resolves the contract: + resolve the durable world/account owner before claiming control, then reuse + the existing SessionRedirect and an operator-provisioned complete region route + catalog. Missing owner data or route fails closed; client endpoints are never + authoritative. Do not claim 11.2 complete until redirect/client switching, process-kill qualification and restart retry pass. - Proposed resolution for ADR review: define a v6 response that names the owning - region, plus an authoritative region-address resolution contract; alternatively, - specify a server-side router. Do not treat a client-provided endpoint as trusted. No deployed world has been provisioned or changed by this work.