diff --git a/docs/STATUS.md b/docs/STATUS.md index d1f1465..8c0144f 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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; diff --git a/docs/adr/0100-primitive-lives-and-persistent-control.md b/docs/adr/0100-primitive-lives-and-persistent-control.md new file mode 100644 index 0000000..86fbdd3 --- /dev/null +++ b/docs/adr/0100-primitive-lives-and-persistent-control.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 4974bdd..aa2dd2f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/M11_2_DELIVERY_PLAN.md b/docs/engineering/M11_2_DELIVERY_PLAN.md new file mode 100644 index 0000000..a66f545 --- /dev/null +++ b/docs/engineering/M11_2_DELIVERY_PLAN.md @@ -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. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 5e1e657..56bc23a 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.