Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m57s
Foundation / checks (checks) (push) Failing after 3m43s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 3m2s
Foundation / checks (network) (push) Canceled after 4m39s
Foundation / checks (client) (push) Canceled after 6m48s
288 lines
16 KiB
Markdown
288 lines
16 KiB
Markdown
# 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_founder` fixes the schema-2/development-2 genome, not starting
|
|
inventory or its source. The first-bud analysis assumes full growth.
|
|
- `LineageRegion` closes 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:
|
|
|
|
1. The checkpoint with organism, source debit, reserve and heat.
|
|
2. The genome, birth and retained player-origin provenance.
|
|
3. Account-to-life and life-to-region/organism bindings.
|
|
4. 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](../engineering/M11_2_DELIVERY_PLAN.md) 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](../../schemas/primitive-lives-v1.md) 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](../../schemas/life-reservations-v1.md):
|
|
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](../../schemas/primitive-batch-v1.md) 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.
|