16 KiB
ADR-0100: Primitive lives and persistent control
Status
Accepted direction for M11.2, 2026-10-09, following M11.1 commit 93e1ab0.
The maintainer authorized the recommendations and subsequent implementation
choices, with review after the fact and a commit/push between subsections.
Server side only; client UI remains deferred. Implementation progress and limits
are recorded below; acceptance of the design does not claim completed durability.
Context and architectural conflicts
primitive_founderfixes the schema-2/development-2 genome, not starting inventory or its source. The first-bud analysis assumes full growth.LineageRegioncloses over exactly the environmental fixture's producer and consumer. Adding a player to its archive alone correctly fails closure.- Checkpoint profile 2 declares history profile 1 and genome schema 1. It cannot silently acquire schema-2 player lives and a variable living set.
- ADR-0092 permits two regions to publish a duplicate no-effect action and retain the first result. For a spawn, retaining one result would not undo the other checkpoint's source debit and organism creation.
- ADR-0091 fences account control but does not bind a durable organism. Session takeover and reconnect must not be treated as new lives.
Per AGENTS.md, implementation must not expand through conflicting contracts. The proposed resolution is a new cellular profile and an atomic publication contract for biological actions. Existing fixture/probe contracts remain intact.
Decision
Identity and control
Keep account, life, organism and genome identities distinct. Account references belong to server orchestration and durable metadata, never biology or perceivable organism state. A world/account has at most one nonterminal life, including a suspended life. Reconnect resolves it; only an explicit new-life request can create one, and only when no nonterminal life exists.
The life record names its region and organism. Control requires the current region lease and account-control generation, after any takeover wait. Taking control does not move the organism. A login elsewhere routes to its owner; M10 probe handoff is not organism handoff. Terminal records remain historical.
World-scoped identities need durable allocation and exhaustion checks. Independent region-local counters cannot guarantee uniqueness. Failed reservations may leave gaps but never reuse issued identities or publish unfunded organisms.
Starting body and funding
Accepted for founder-life rules 1; numerical choices are tunable and versioned:
- Every account starts with the same fully grown, undamaged primitive founder.
- Derive body composition and construction energy from development version 2; do not duplicate biological constants in SQL or server code.
- Give every founder 30 seconds of full-speed demand as energy only: 7,824,000 pJ with development 2. No spare matter. Phosphorus still binds the first bud at 300, 600 and 901 seconds for the analyzed feeding shares; energy does not buy missing phosphorus.
- Transfer body material, construction energy and reserve from an explicit finite spawn inventory. Construction energy goes to heat, not usable reserve. Allocation, placement or funding failure spends nothing.
- Retain source and creation-event provenance. No automatic replenishment or account-age/ancestry bonus is implied.
Rejected for this version: local habitat withdrawal or external input per life. External input must appear in the conservation equation, never as a transfer from an empty source. These choices determine whether depletion blocks entry and whether repeated lives inject resources. Starting growth, reserve, placement and any replenishment must be recorded as rules/tunables, not inferred from fixtures. Placement uses a bounded, lexicographically ordered list of server-provisioned habitat sites in region/frame-local integer micrometres. Select the first free site; validate that 20 um founder squares do not overlap. This is an explicit initial nursery configuration, not a planet generation or organism movement rule. The pool has explicit provisioning provenance and no automatic refill. Each region owns a disjoint pool; inter-region funding is not implied.
Atomic publication and retries
The authenticated request supplies an action identity, not authoritative biology or position. Canonical content and the result are retained by world/account/action id. Exact retry returns that result; changed content conflicts. Retrying an old successful spawn returns its original life even after that life dies.
Publication atomically validates region authority, account control, expected life ownership and request uniqueness, then commits:
- The checkpoint with organism, source debit, reserve and heat.
- The genome, birth and retained player-origin provenance.
- Account-to-life and life-to-region/organism bindings.
- The immutable request/result and required history/outbox records.
Do not reuse no-effect probe conflict handling. If another spawn or takeover wins, the losing checkpoint must not publish. Its host discards speculative state and recovers/reconciles before continuing; changing only the reported result is insufficient. Extend the upgrade/region/account lock order consistently and test independent connections. Resolve retries before treating them as fresh debits.
Receipts remain provisional. Final creation requires the whole durable transaction. Unknown outcomes pause dependent work and resolve the original commit id and exact request, without assuming rollback. Refresh/takeover races must either preserve valid authorization or reject the entire candidate, never partially bind a life.
Cellular checkpoint closure
Use a separately versioned profile, not optional player sections in the fixture. Its bounded canonical codec must validate the following before admission:
| State | Closure |
|---|---|
| Organism/genome, archive and origin | Unique IDs, schema/development versions, birth/death agreement, retained provenance and allocation bounds |
| Body, reserve, reservations, source and heat | Per-channel conservation and exactly one inventory owner |
| Growth, damage, age and implemented timers | Exact values; no recovery defaults or elapsed-time biology |
| Position and region/frame | Valid placement, one owning representation |
| Active, suspend-pending, suspended or dead state | Agreement with durable metadata; dead terminal; offline biology cannot step |
| Implemented action state and randomness | Exact retry/replay state, versioned streams, no fresh retry draws |
| Rules, quantum and bounds | Explicit allowlist; counts/bytes checked before allocation |
Do not add placeholder disease, gestation or mutation state. Later systems must extend closure before activation. Sessions/grants are reacquired, never restored as valid authority. Recovery reconciles life/results and checkpoint before readiness; missing, conflicting or unsupported data quarantines the region.
The profile begins with no organisms; synthetic fixture actors are not adopted as player-origin wildlife. Provisioning is explicit; recovery never creates a fallback world. Existing dev-world conversion/deployment is separate. World0 is excluded.
Scope and compatibility
11.2 establishes creation, durable binding and recovery, with no autonomous biology on session loss. Locomotion/feeding, mutation, budding, complete death flow and timed logout/resume remain 11.3-11.7 under ADR-0098. Intermediate work must not claim a playable lifecycle before those paths are wired and qualified.
Protocol v4 and existing checkpoint profiles stay frozen. Life messages require an explicit new protocol version with updated headless callers, codecs and network tests. UI remains deferred; biological presentation gains no ownership labels.
Alternatives considered
- Widen the two-actor fixture: violates exact living-set closure.
- Persist a life separately after its checkpoint: creates crash windows with funding but no life, or a life without a recoverable body.
- Spawn on login: retries/takeovers can create extra lives.
- Reuse first-result-wins commits: duplicate biological effects survive.
- Store accounts in genomes: violates the orchestration boundary.
Benefits
Funding, ancestry, control and retry results describe one recoverable operation. Existing fixtures remain regression oracles; lives gain explicit state closure.
Costs and risks
A new profile, publication path and migration are substantial work. Losing speculative batches needs clear host recovery behavior. Finite funding can refuse entry; external funding can distort ecology. Archive/record limits need measured backpressure; history cannot be pruned to admit players. Organism migration is separate from the proven probe experiment.
Consequences
Only enable network spawning after the profile/publication integration is proven. The delivery plan lists acceptance evidence. Existing goldens, simulation versions, schemas and deployed worlds are unchanged.
11.2a: Funded creation
biology::primitive_endowment derives the full body, energy-only reserve and
435,200 pJ construction price. server::PrimitiveLives owns the finite pool,
heat, body/reserve pairs, genome archive, births and request/origin bindings.
It is a portable server orchestration target, independent of transport/database
and outside evo::simulation. A detached candidate is swapped only after every
fallible operation succeeds, including ledger and archive admission.
Capacity is 256 retained lives and provisioned sites (engineering bound). Exact successful retries return the original allocation before checking capacity or funding. Another action for the same living account is refused. The host supplies world-allocated identities, never the client. This layer checks local collisions; world-wide allocation and authorization are enforced in 11.2c/d. Refusals here are in-memory errors, not durable action outcomes. There are no live ticks or death/logout transitions yet, so this subsection is not deployable gameplay.
11.2b: Creation-state checkpoint codec
The separate primitive-lives-v1 envelope retains the explicit opening, sites, founding requests and identities, every inventory balance and the complete archive. Restore reconstructs a detached candidate, compares each saved record/balance/history and requires exact canonical re-encoding. It refuses unknown versions, mismatched region identity, duplicate life bindings and inconsistent funding. No biological timers exist in this creation-only version; introducing progression requires a new format first. Durable publication and session integration remain 11.2c/d.
11.2c-2c: Guarded atomic publication
Schema v16 admits primitive checkpoint profile 3 only through
publish_primitive_checkpoint. It validates the canonical batch trace and its
checkpoint scope, current lease and account-control generations, and each
reserved account/request/identity. It locks reservations in account UUID order,
then rechecks control after lock waits. A private immutable publication record,
life bindings and the existing fenced checkpoint/head publication commit in one
transaction. Generic profile-1/2 publishers cannot bypass this path; a matching
exact retry resolves to the committed receipt, while conflicting reuse, stale
control, changed bindings, malformed evidence or capacity overflow refuses.
The owner-only genesis path admits an empty primitive-life checkpoint. Runtime recovery can query immutable region life bindings, but object-store reconciliation and a primitive-capable region host/session protocol are still required before a region can serve this profile. This database gate therefore proves atomic durable admission and retry behavior, not end-to-end recoverability or deployable gameplay. Death, respawn, offline timers, biological tick integration and life transfer are outside 11.2 and remain governed by later gates.
11.2d request outcomes and control movement
Schema v17 closes the request contract without transferring a pending biological
operation between regions. A conflicting new request gets a durable
existing_life refusal row, so exact retry and query return the same final
result. The authenticated current controller can query by world/account/request
independently of the reservation's region; results include the owner and, after
publication, the immutable born tick and commit receipt. Missing rows resolve as
unknown, while a reserved row remains pending and is never called a birth.
When account control changes region or region epoch, the same fenced control
transaction marks unpublished reservations in the old region cancelled.
Published bindings are untouched. The cancelled request remains immutable and a
new request is required to try again. This avoids cross-region transfer of
speculative body state and prevents the old reservation becoming publishable
under a new controller. V5 now gives existing_life and cancelled durable
result values distinct from query-only pending and unknown.
Migration v17 and its typed query adapter implement this contract. Host/session execution, concurrent-process crash qualification and readiness integration are separate gates; v5 stays refused by the running server until those gates pass.
11.2c-2d: Object-store publication and recovery adapter
The C++ persistence adapter writes the canonical primitive payload and batch trace to the immutable object store, verifies each read-back, and only then calls the schema v16 publisher. Before upload it restores the verified predecessor payload, replays the batch and requires byte-identical candidate state. Unknown outcomes retain the exact manifest and trace for an exact retry. Recovery verifies the committed head, retained build/profile, payload closure, head trace replay and reconciliation between restored lives and immutable SQL bindings; it fails closed on absent/corrupt evidence and never substitutes an older head. This adapter does not add a serving host, request protocol or session routing for primitive lives.
11.2c-1: Durable identity reservations
Schema v15 adds life reservations: one pending request per world/account, world-wide durable identity allocation, exact retries and immutable refusal records. Reservations spend no resources and are never reported as organisms. The owner must provision an audited unused identity range; runtime cannot initialize it. Control/lease expiry is checked after lock waits. This precedes atomic body/checkpoint publication in 11.2c-2.
11.2c-2a: Creation replay evidence
The primitive-batch-v1 trace records funded births with world/region/frame, predecessor commit/digest, batch tick interval and control generations. Replay creates a detached candidate; any failed birth discards all changes. The owner retains the checkpoint tick in the manifest; empty creation batches advance that tick without advancing any biology. This does not introduce offline progress or reserve consumption. Publication must bind the trace to its predecessor and atomically validate reservations/control before recording life ownership. The portable trace alone does not provide durability.
New-life request IDs use a separate operation namespace from M10 no-effect probe actions. The future protocol must make that explicit rather than overloading the existing probe result lookup. This avoids silently changing deployed probe rules.
11.2d-3: Primitive region host
PrimitiveRegionHost is separate from the environmental/lineage tick host. It
acquires and renews the region lease, becomes ready only after profile-3 recovery,
and applies a new-life command as one creation-only checkpoint batch. Each birth
advances the checkpoint's committed tick by one without advancing biological
state; this is a durable operation boundary, not a simulation tick. The host
reserves under the authenticated account-control generation, constructs a
detached replay candidate, and returns a born result only after the atomic
checkpoint/reservation transaction confirms. Funding and placement refusals are
recorded durably. Exact retries query the stored outcome; an ambiguous publish
retains the exact prepared commit and pauses admission until reconciliation.
This first host slice is not connected to evo-server or the v5 session protocol.
Network admission, routing, process-kill qualification and readiness wiring remain
separate implementation gates.