docs: propose M11.2 funded lives and atomic control contract
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (client) (push) Successful in 47s
Foundation / postgres-tools (push) Successful in 4s
Foundation / server-image (push) Successful in 4s
Foundation / image (push) Successful in 4s

This commit is contained in:
dingo
2026-10-09 18:06:23 -04:00
parent 93e1ab08ae
commit 7ee1c68a82
5 changed files with 243 additions and 1 deletions
+5 -1
View File
@@ -34,7 +34,11 @@ the maintainer chose directional rounding):
bud in 5, 10 and 15 minutes when feeding 100%, 50% and 33% of the time (ADR-0099).
11.1 is complete.
- **Next:** 11.2, primitive lives and persistent control. Server side only; client UI
parts of 11.x are deferred to the maintainer.
parts of 11.x are deferred to the maintainer. Its
[delivery plan](engineering/M11_2_DELIVERY_PLAN.md) and proposed
[ADR-0100](adr/0100-primitive-lives-and-persistent-control.md) identify the new
checkpoint and atomic biological publication contracts needed. Founder funding
remains a maintainer decision; implementation has not started.
Open from M10 (BACKLOG):
- the maintainer's native-client observation, moved to the later 2k drill;
@@ -0,0 +1,156 @@
# ADR-0100: Primitive lives and persistent control
## Status
Proposed for M11.2, 2026-10-09, following M11.1 commit `93e1ab0`.
Server side only; client UI remains deferred to the maintainer. No implementation
or gameplay rule is accepted by this proposal. Founder funding needs a maintainer
decision; ADR-0099 explicitly leaves it to 11.2.
## 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.
## Proposed 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: pending gameplay decision
Recommendation, not an accepted rule:
- 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 the same versioned reserve. Specify its amount and recheck
the first-bud target before implementation; "small reserve" is not a rule.
- 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.
Alternatives are local habitat withdrawal or an explicit 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.
Choosing a funding source alone does not select those other values.
### 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
Settle funding and this profile/publication resolution before enabling spawning.
The [delivery plan](../engineering/M11_2_DELIVERY_PLAN.md) lists acceptance evidence.
No golden, simulation version, schema or deployed world changes in this proposal.
+2
View File
@@ -1,5 +1,7 @@
# Architecture decision records
- [ADR-0100: Primitive lives and persistent control](0100-primitive-lives-and-persistent-control.md) - proposed M11.2 cellular checkpoint and atomic spawn publication; founder funding pending maintainer decision. No implementation yet.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
- [ADR-0057: Environmental interval scheduling](0057-environmental-interval-scheduling.md) - accepted M6.7 bounded explicit intervals and committed-prefix results.
+65
View File
@@ -0,0 +1,65 @@
# M11.2: Primitive lives and persistent control
2026-10-09. Server-side continuation of M11.1 at `93e1ab0`.
[ADR-0100](../adr/0100-primitive-lives-and-persistent-control.md) is proposed.
This plan does not close 11.2 or settle unaccepted game rules.
## Contract review
Reviewed PROJECT_VISION, ENGINEERING_CONSTITUTION, SYSTEM_OVERVIEW,
SIMULATION_ARCHITECTURE, PERSISTENCE_ARCHITECTURE, REGION_DURABILITY,
REPRODUCTION_MODEL, ENERGY_MODEL and ADRs 0062, 0091, 0092, 0098 and 0099.
Inspected founder, development/metabolism, lineage/archive, host, checkpoint,
batch and account-control headers and lineage-region/account-control tests.
`closure_is_required` in lineage_region_tests correctly rejects an extra living
organism outside the two fixture bindings. Migration 0011 / ADR-0092 permits
duplicate no-effect publications; biological effects need the losing checkpoint
rejected in full. ADR-0100 proposes explicit contract replacements for gameplay.
ADR-0099's full-grown founder analysis is an assumption, not funded creation.
## Delivery segments
Validate each segment, record evidence/limits in VALIDATION.md, then commit and
push its scoped changes. Gate completion needs all applicable rows; library
tests alone are not a durability proof.
| Segment | Modules | Acceptance |
|---|---|---|
| 11.2a: contract and funded creation | Biology budget helpers if needed; server lifecycle; accounting callers; docs/tests | Settle funding, growth/reserve, placement and ADR-0100; equal old/new-account starts; atomic source/body/reserve/heat/provenance; insufficient channels, allocation, placement and overflow leave state unchanged |
| 11.2b: recoverable cellular state | Cellular state owner; codecs; persistence profile; lineage closure | New profile/history declaration; exact timers/reservations/retries; hostile bounds/versions/bindings refused; old profile goldens unchanged; no synthetic actors adopted as wildlife |
| 11.2c: durable ownership | Migration/adapters; account control; publication; host | Real PostgreSQL concurrent spawn/takeover, stale generations/leases, exact/changed retries; one nonterminal life across regions; losing candidate never publishes inventory; uncertain commit reconciliation; no runtime-role bypass |
| 11.2d: server integration | Session/host; versioned protocol; headless probe; process tests | Explicit spawn; reconnect to existing life; route to owner; no marker as organism; no offline progress; kills before/after transaction and final answer; same result after restart; network callers/codecs updated |
11.3-11.7 add the biological action loop and complete death/logout behavior.
This plan adds no renderer, UI, deployment or dependency.
## Fault and equivalence matrix
- New and historical accounts get identical biological starts for identical rule
and habitat inputs; historical identities may differ.
- Competing requests in one/two regions publish at most one nonterminal life.
Different accounts cannot overdraw the same finite source.
- Exact retry resolves once; changed content conflicts; retry of an old successful
spawn after its death returns the old result, never a new life.
- Failed allocation/funding/placement spends nothing and publishes no ancestry.
Allocation gaps are allowed; identity reuse is not.
- Kill before upload, before transaction, after commit and after final answer.
Recover only the committed cut and exact result.
- Race refresh/takeover with publication; stale control cannot publish a body or
replace life ownership.
- Missing body/archive/source debit/provenance/binding prevents readiness.
- Timers/reserves remain exact across restart/offline intervals; terminal history
remains terminal, never resurrected by recreating a session.
- Run under NDEBUG, verify channel conservation and canonical round trips.
## Validation lanes
Use README commands/presets: Windows debug/release and affected network/QUIC;
Linux debug/release, ASan+UBSan, clang-tidy and format-check; real PostgreSQL
migration/ownership and process-kill checks when those segments exist. Run network
presets whenever a replicated type changes. Record unavailable environments.
Local checks do not close ADR-0097's reference-worker qualification.
This initial review changes documentation only. No spawn, migration, provisioning
or biological implementation has been performed.
+15
View File
@@ -5462,3 +5462,18 @@ Executed:
- WSL `network-clang` 65/65 and `quic-linux` 68/68.
- clang-tidy 19: clean.
- Windows `debug` 61/61, `quic` 5/5, `client-network` 15/15.
## 2026-10-09 — M11.2 contract review (documentation only)
Proposed ADR-0100 and M11_2_DELIVERY_PLAN document two incompatible reuse paths:
the two-actor checkpoint's exact living-set closure and the no-effect action
publication's first-result-wins semantics. They propose a new cellular profile and
atomic life/funding/result publication. Starting funding remains a maintainer
decision; no M11.2 implementation or gate completion is claimed.
Executed: `git diff --check`, plus whitespace and relative-link checks on both new
documents. Reviewed existing headers, migration 0011 and relevant tests as listed
in the delivery plan. No C++/SQL/wire code changed; builds, CTest, clang-format,
clang-tidy and sanitizers were not run for this documentation-only change.
No environment limitation was encountered during these documentation checks.
No deployment, world mutation or provisioning was performed.