diff --git a/CMakeLists.txt b/CMakeLists.txt index 3c3e426..252a46c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -81,7 +81,8 @@ evo_owned_target(evo_biology) # M11.2 portable lifecycle orchestration; no dependency from the foundation proof. add_library(evo_lifecycle STATIC src/server/lifecycle/primitive_lives.cpp src/server/lifecycle/primitive_batch.cpp src/server/lifecycle/cellular_lives.cpp - src/server/lifecycle/cellular_batch.cpp src/server/lifecycle/wildlife_controller.cpp) + src/server/lifecycle/cellular_batch.cpp src/server/lifecycle/wildlife_controller.cpp + src/server/lifecycle/cellular_play_summary.cpp) add_library(evo::lifecycle ALIAS evo_lifecycle) target_link_libraries(evo_lifecycle PUBLIC evo::biology) evo_owned_target(evo_lifecycle) diff --git a/apps/evo-world-clone/main.cpp b/apps/evo-world-clone/main.cpp index f6f7d72..41d37c1 100644 --- a/apps/evo-world-clone/main.cpp +++ b/apps/evo-world-clone/main.cpp @@ -68,6 +68,7 @@ #include "evo/persistence/sha256.hpp" #include "evo/processes/development_opening.hpp" #include "evo/server/lifecycle/cellular_lives.hpp" +#include "evo/server/lifecycle/cellular_play_summary.hpp" #include "evo/server/lifecycle/primitive_lives.hpp" #include @@ -226,7 +227,7 @@ std::optional parse(int argc, char** argv) { Options o; o.command = argv[1]; if (o.command != "clone" && o.command != "audit" && o.command != "check-store" && - o.command != "provision" && o.command != "compare") + o.command != "provision" && o.command != "compare" && o.command != "summary") return std::nullopt; const bool clone = o.command == "clone"; for (int i = 2; i < argc; ++i) { @@ -329,7 +330,8 @@ std::optional parse(int argc, char** argv) { if (o.target.objects.empty()) o.target.objects = o.source.objects; } - const bool needs_builds = o.command != "check-store" && o.command != "provision"; + const bool needs_builds = + o.command != "check-store" && o.command != "provision" && o.command != "summary"; if (o.command == "provision") { if (o.opening.empty() || !o.build) return std::nullopt; @@ -743,6 +745,63 @@ int check_store(const Options& o) { return denied && reachable ? 0 : 3; } +// M11.9 (ADR-0130): read-only, account-free play aggregates of a cellular region's +// committed head, for playtest review. Nothing is written. +int summary(const Options& o) { + auto db = connect(o.source); + auto objects = open_objects(o.source, server::max_cellular_lives_bytes); + if (!db || !objects) { + std::fputs("summary failed store\n", stderr); + return 3; + } + const auto head = persistence::load_region_checkpoint(*db, o.source.key, timeout); + const auto manifest = + head ? persistence::decode_manifest(head->manifest) + : std::expected{ + std::unexpected{persistence::CheckpointError::format}}; + if (!manifest || manifest->profile != persistence::CheckpointProfile::cellular_lives_v1) { + std::fputs("summary failed head\n", stderr); + return 3; + } + const auto payload = objects->get({manifest->payload_sha256, manifest->payload_bytes}); + auto state = payload ? persistence::restore_cellular_payload(*payload, *manifest) + : std::unexpected{persistence::CheckpointError::payload}; + const auto play = state ? server::summarize_cellular_play(**state) + : std::unexpected{server::CellularLivesError::format}; + if (!play) { + std::fputs("summary failed state\n", stderr); + return 3; + } + std::printf("cellular summary world=%llu region=%llu sequence=%llu tick=%llu\n", + static_cast(o.source.key.world), + static_cast(o.source.key.region), + static_cast(manifest->sequence), + static_cast(play->tick)); + std::printf("living owned=%llu wildlife=%llu lingering=%llu suspended=%llu\n", + static_cast(play->owned), + static_cast(play->wildlife), + static_cast(play->lingering), + static_cast(play->suspended)); + std::printf("deaths total=%llu starved=%llu engulfed=%llu unrecorded=%llu owned=%llu " + "wildlife=%llu\n", + static_cast(play->deaths), + static_cast(play->starved), + static_cast(play->engulfed), + static_cast(play->unrecorded), + static_cast(play->owned_deaths), + static_cast(play->wildlife_deaths)); + std::printf("lifespan_ticks min=%llu median=%llu max=%llu\n", + static_cast(play->lifespan_min), + static_cast(play->lifespan_median), + static_cast(play->lifespan_max)); + std::printf("evolution buds=%llu mutations=%llu living_genomes=%llu deepest_lineage=%llu\n", + static_cast(play->buds), + static_cast(play->mutations), + static_cast(play->living_genomes), + static_cast(play->deepest_lineage)); + return 0; +} + int audit(const Options& o) { auto db = connect(o.source); auto objects = open_objects(o.source); @@ -882,7 +941,7 @@ int clone(const Options& o) { int main(int argc, char** argv) { const auto options = parse(argc, argv); if (!options) { - std::fputs("usage: evo-world-clone clone|audit|check-store|provision|compare ... " + std::fputs("usage: evo-world-clone clone|audit|check-store|provision|compare|summary ... " "(see apps/evo-world-clone/main.cpp)\n", stderr); return 2; @@ -893,5 +952,7 @@ int main(int argc, char** argv) { return provision(*options); if (options->command == "compare") return compare(*options); + if (options->command == "summary") + return summary(*options); return options->command == "clone" ? clone(*options) : audit(*options); } diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index cb63bdf..004e92a 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -608,13 +608,17 @@ Status: exploratory probe ran on 2026-10-13 in DEV region 100/3 (ADR-0123); notes are in [the probe notes](playtests/M11_3_PROBE_NOTES_2026-10-13.md). Steering and feeding work end to end, but there is not yet enough game to judge fun. - Engulfment and corpse absorption (the predation part of 11.3) remain. -- 11.4a and 11.4b are implemented. The 11.4c reservation gate is green in CI - runs 274 and 275, but durable selection publication and restart recovery are - still outstanding. The mutation-choice playtest becomes possible in 11.4d, - after the client choice/review flow is connected; this remains within M11. -- 11.5 through 11.9 remain after 11.4. In particular, repeated-life playtesting - in 11.9 assesses descendants, permanent death, and variety across lives. + Engulfment and detritus are implemented (ADR-0124, rules 3). +- As of 2026-10-14 the server, biology, persistence and protocol halves of 11.4 + through 11.9 are implemented and tracked in their ADRs and delivery plans: + durable mutation choice and offer replication (ADR-0121, 11.4c/d), budding + wildlife with a deterministic controller (ADR-0125, 11.5), permadeath and + restart (ADR-0127, 11.6), offline freeze, linger and resume (ADR-0128, 11.7), + readable play signals (ADR-0129, 11.8) and the playtest plan and telemetry + (ADR-0130, 11.9). The client screens (offer chooser, bud control, death and + restart, presentation) are the maintainer's, and the repeated-life playtests + in 11.9 still decide whether the loop is fun. Each step's CI evidence is in + the validation log. - M10's exit evidence for native-client responsiveness is open (BACKLOG): the maintainer's observation moves to the later 2k drill. diff --git a/docs/adr/0130-cellular-playtest-telemetry-boundary.md b/docs/adr/0130-cellular-playtest-telemetry-boundary.md new file mode 100644 index 0000000..568a8b3 --- /dev/null +++ b/docs/adr/0130-cellular-playtest-telemetry-boundary.md @@ -0,0 +1,43 @@ +# ADR-0130: Cellular playtest telemetry boundary + +## Status + +Accepted (2026-10-14) for the M11.9 repeated-life playtests. Revisit before any +telemetry leaves the development environment. + +## Context + +M11.9 must assess movement, food decisions, predation, tradeoffs, descendants and +variety over multiple lives, using human feedback plus bounded, consent-aware +telemetry. The durable checkpoint already holds everything needed to count what +happened in a region (lives, corpses with causes, the lineage archive with births, +deaths and genome revisions, the bud sequence). It also holds account identities, +which are not needed for these questions. + +## Decision + +- Playtest telemetry is derived offline from a region's committed head by + `evo-world-clone summary` (read-only; owner connection; nothing written). It + reports only aggregates: the living population by kind and presence; deaths by + cause and by kind; minimum, median and maximum lifespan in ticks; buds; applied + mutations; distinct living genomes and the deepest living lineage. +- No account, session, grant, position, IP address, timing of individual inputs or + per-player history is collected, printed or stored by this tool. Linking results + to a participant happens only in the human notes the participant agrees to. +- The tool runs on demand by the maintainer, in DEV only. There is no background + collection and no new table. +- Per-player questions (did you understand why you died, did a mutation choice + matter) are asked in the playtest notes, not inferred from telemetry. + +## Alternatives + +- **Server-side event logging per action:** rejected for M11.9; it would collect + per-player behaviour without a consent flow and add a retention problem. +- **Replay-based full-trace analysis:** possible later for crash regression; it + needs no new data, only the existing history audit. + +## Consequences + +Playtest sessions can be compared by region-level outcomes (death causes, variety, +descendants) while participants stay anonymous in the data. Finer behaviour +questions remain qualitative. diff --git a/docs/adr/README.md b/docs/adr/README.md index 1f5ef7c..209e3e0 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -30,6 +30,7 @@ - [ADR-0127: Cellular permadeath and restart](0127-cellular-permadeath-and-restart.md) - M11.6: schema v37 marks a published life ended once (`end_cellular_lives`, recorded by the host after the death and again on recovery); one active life per account replaces one life per account, so a dead player starts a new primitive founder; a dead account's stale action no longer refuses the whole tick. - [ADR-0128: Cellular offline freeze, linger and resume](0128-cellular-offline-freeze-and-resume.md) - M11.7: a frozen step intent (set for owned lives without a session) freezes biology; owner format 6 / rules 5 track presence: lingering for 200 ticks (10 s, trial) perceivable and vulnerable, then suspended out of the world without aging; an unfrozen intent resumes in place or at the nearest clear spot within three extents; bundle v6, schema v38. - [ADR-0129: Cellular readable play signals](0129-cellular-readable-play-signals.md) - M11.8 server half: v10 diagnostics report engulf and bud results in two reserved bytes, and v10 type 27 tells the owner its life ended and why (starved or engulfed); presentation stays with the maintainer. +- [ADR-0130: Cellular playtest telemetry boundary](0130-cellular-playtest-telemetry-boundary.md) - M11.9: playtest telemetry is an offline, read-only `evo-world-clone summary` of a region head with account-free aggregates only (population, death causes, lifespans, buds, mutations, variety); per-player questions stay in consented notes. - [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_9_DELIVERY_PLAN.md b/docs/engineering/M11_9_DELIVERY_PLAN.md new file mode 100644 index 0000000..4915f97 --- /dev/null +++ b/docs/engineering/M11_9_DELIVERY_PLAN.md @@ -0,0 +1,22 @@ +# M11.9: Run repeated-life playtests and close the loop + +The playtests themselves are human work for the maintainer and participants. This +plan tracks what engineering provides for them: the predeclared plan +([M11_9_REPEATED_LIFE_PLAYTEST](../playtests/M11_9_REPEATED_LIFE_PLAYTEST.md)), +the bounded telemetry boundary +([ADR-0130](../adr/0130-cellular-playtest-telemetry-boundary.md)) and a DEV region +running the complete M11 rules. + +## Segments + +| Segment | Owner | Acceptance evidence | +|---|---|---| +| 11.9a: plan and telemetry | Engineering | Predeclared questions, sample and recording; `evo-world-clone summary` reports account-free aggregates; tests on owner states and a provisioned region | +| 11.9b: DEV region | Engineering, maintainer approval for the Argo sync | A `cellular-v4` region on a CI-built server image and postgres-tools with schema v38 | +| 11.9c: sessions and results | Maintainer and participants | Notes per the plan; answers per question; retested changes | + +## Progress + +- 2026-10-14: 11.9a implemented. `summarize_cellular_play` and + `evo-world-clone summary`; owner tests check death and bud aggregates, and the + PostgreSQL store test runs the command on a provisioned `cellular-v4` region. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index df74e64..bba515f 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -7458,3 +7458,16 @@ type 27 bounds); `quic-sessions` delivers type 27 to a v10 owner only. Executed locally: MSVC Debug 69/69, network 75/75, client-network 89/89; g++-14 `-Werror -Wshadow` and clang-tidy-19 on the protocol, sessions, client, tests and server main (with the bridge); clang-format 19.1.5. + +## 2026-10-14 — M11.9a playtest plan and telemetry (CI pending) + +The M11.9 playtest plan predeclares questions, sample and recording. +`summarize_cellular_play` derives account-free aggregates from a committed +cellular state and `evo-world-clone summary` prints them for a region head +(ADR-0130). `cellular-lives-owner` checks the aggregates after two starvations +and after a bud; `region-store` runs the command on a provisioned `cellular-v4` +region. + +Executed locally: `postgres-check.sh --full` (WSL g++-14 Release, 490 s) passes, with the +summary command test; MSVC Debug `cellular-lives-owner`; g++-14 `-Werror -Wshadow` and +clang-tidy-19 on the summary, provisioner and tests; clang-format 19.1.5. diff --git a/docs/playtests/M11_9_REPEATED_LIFE_PLAYTEST.md b/docs/playtests/M11_9_REPEATED_LIFE_PLAYTEST.md new file mode 100644 index 0000000..127062f --- /dev/null +++ b/docs/playtests/M11_9_REPEATED_LIFE_PLAYTEST.md @@ -0,0 +1,64 @@ +# M11.9 repeated-life playtest plan + +This plan predeclares what the M11.9 playtests try to learn, who plays, how sessions +run and what is recorded. It is written before any session so that results are not +read into after the fact. It is not a balance sign-off; every value it touches is a +trial value (ADR-0098, ADR-0120, ADR-0124, ADR-0125, ADR-0128). + +## Preconditions + +- A DEV region provisioned with the `cellular-v4` opening (rules 5: engulfment, + detritus, budding wildlife, offline freeze) on a server image that passed CI. +- An engineering client with the v10 path: movement, feeding, engulf, bud, the + mutation offer and chooser, and the death and restart flow. Those screens are the + maintainer's (M11.8 client half); a session without them tests less, and the + notes must say which were present. +- A fresh grant bundle per participant (`renew-dev-m10.sh` output) and a three-hour + session window. + +## Questions (fixed before the first session) + +1. **Movement and food.** Can a new player find and keep feeding within two + minutes without help? How long until their first mutation offer? +2. **Tradeoffs.** When an offer appears, can the player say what each candidate + costs and gives? Does the chosen candidate change how they play afterwards? +3. **Predation.** Do players notice engulfment, both as hunter and prey? Do they + understand why an engulf attempt failed (size, membrane)? +4. **Descendants.** Do players bud on purpose? Do they recognize their wildlife + descendants as competitors, and does that matter to them? +5. **Death and restart.** Is the cause of death clear? After dying, do players start + again, and does their second life go differently from the first? +6. **Offline.** Does the 10 s linger feel fair, both when leaving and when finding a + lingering cell? +7. **Variety.** Across lives and players, do different genomes and play styles + appear, or does everyone converge on one build? +8. **Fun.** Would the player come back to the cellular stage? What made them want to + stop? + +## Sample and sessions + +- At least three participants, including at least one who has not seen the probe, + and ideally sessions with two players in the region at once. +- Each participant plays at least three lives (or 45 minutes), across at least two + sessions on different days, so that repeated lives and returning are observed. +- Sessions are recorded only as the participant agrees: notes always, screen + recording only with explicit consent. + +## What to record + +- Per session: date, region, server image digest, client build, which client + screens existed, participants (by a pseudonym chosen for the notes), and the + `evo-world-clone summary` output at the start and the end (ADR-0130). +- Per life: how it ended (cause as the player understood it, compared with the + summary's counts), what the player tried, and quotes about confusion or delight. +- Issues: anything that broke, felt unfair or was unreadable, with the tick if + known. File each as an issue with a proposed change. + +## After the sessions + +- Answer each question above with the evidence for and against; do not tune to one + seed or one participant. +- Propose changes to trial values only with the observations that motivate them, + and retest the change in a later session before treating it as settled. +- Record results in `docs/playtests/` with the date, and summarize the decisions in + the roadmap. Engineering success is not evidence of fun. diff --git a/include/evo/server/lifecycle/cellular_play_summary.hpp b/include/evo/server/lifecycle/cellular_play_summary.hpp new file mode 100644 index 0000000..9905c75 --- /dev/null +++ b/include/evo/server/lifecycle/cellular_play_summary.hpp @@ -0,0 +1,28 @@ +#pragma once + +#include "evo/server/lifecycle/cellular_lives.hpp" + +#include +#include + +// M11.9 (ADR-0130): bounded, account-free play telemetry from one committed cellular state. +// It reads only what the checkpoint already holds and reports aggregates: no account, +// session, position or per-player history leaves the region. +namespace evo::server { +struct CellularPlaySummary { + std::uint64_t tick{}; + // The living population by kind and presence (presence is rules 5). + std::uint64_t owned{}, wildlife{}, lingering{}, suspended{}; + // Every death so far, by recorded cause (unrecorded below rules 3) and by kind. + std::uint64_t deaths{}, starved{}, engulfed{}, unrecorded{}; + std::uint64_t owned_deaths{}, wildlife_deaths{}; + // Lifespans in ticks of the dead (born to death), from the archive. + std::uint64_t lifespan_min{}, lifespan_median{}, lifespan_max{}; + // Reproduction and evolution: buds so far, mutations applied, living variety. + std::uint64_t buds{}, mutations{}, living_genomes{}, deepest_lineage{}; + friend bool operator==(const CellularPlaySummary&, const CellularPlaySummary&) = default; +}; + +[[nodiscard]] std::expected +summarize_cellular_play(const CellularLives& state); +} // namespace evo::server diff --git a/src/server/lifecycle/cellular_play_summary.cpp b/src/server/lifecycle/cellular_play_summary.cpp new file mode 100644 index 0000000..9229aa6 --- /dev/null +++ b/src/server/lifecycle/cellular_play_summary.cpp @@ -0,0 +1,61 @@ +#include "evo/server/lifecycle/cellular_play_summary.hpp" + +#include +#include + +namespace evo::server { +std::expected +summarize_cellular_play(const CellularLives& state) { + CellularPlaySummary summary; + summary.tick = state.tick(); + const auto& archive = state.archive(); + std::vector genomes; + for (const auto& life : state.lives()) { + (life.account == LifeAccount{} ? summary.wildlife : summary.owned) += 1; + summary.lingering += life.presence == CellularPresence::lingering ? 1 : 0; + summary.suspended += life.presence == CellularPresence::suspended ? 1 : 0; + genomes.push_back(life.identity.genome); + } + std::ranges::sort(genomes); + const auto distinct = std::ranges::unique(genomes); + genomes.erase(distinct.begin(), distinct.end()); + summary.living_genomes = genomes.size(); + for (const auto genome : genomes) { + const auto ancestry = archive.ancestry(genome); + if (!ancestry) + return std::unexpected{CellularLivesError::archive}; + summary.deepest_lineage = + std::max(summary.deepest_lineage, ancestry->size()); + } + + std::vector lifespans; + for (const auto& corpse : state.corpses()) { + ++summary.deaths; + switch (corpse.cause) { + case biology::CellularDeathCause::starved: + ++summary.starved; + break; + case biology::CellularDeathCause::engulfed: + ++summary.engulfed; + break; + case biology::CellularDeathCause::unrecorded: + ++summary.unrecorded; + break; + } + (corpse.parent_life == 0 ? summary.owned_deaths : summary.wildlife_deaths) += 1; + const auto record = archive.organism(corpse.organism); + if (!record || record->alive || record->died.value < record->born.value) + return std::unexpected{CellularLivesError::archive}; + lifespans.push_back(record->died.value - record->born.value); + } + if (!lifespans.empty()) { + std::ranges::sort(lifespans); + summary.lifespan_min = lifespans.front(); + summary.lifespan_median = lifespans[lifespans.size() / 2]; + summary.lifespan_max = lifespans.back(); + } + summary.buds = state.next_bud_sequence() - 1; + summary.mutations = archive.revisions().size(); + return summary; +} +} // namespace evo::server diff --git a/tests/cellular_lives_tests.cpp b/tests/cellular_lives_tests.cpp index 17724c4..2b642fc 100644 --- a/tests/cellular_lives_tests.cpp +++ b/tests/cellular_lives_tests.cpp @@ -1,5 +1,6 @@ #include "evo/server/lifecycle/cellular_batch.hpp" #include "evo/server/lifecycle/cellular_lives.hpp" +#include "evo/server/lifecycle/cellular_play_summary.hpp" #include "evo/server/lifecycle/wildlife_controller.hpp" #include @@ -610,6 +611,13 @@ void rules_three_owner_resolves_engulf_and_detritus() { ++steps; } CHECK(owner.lives().empty() && owner.corpses().size() == 2); + // 11.9 telemetry (ADR-0130): account-free aggregates from the state alone. + const auto ended = summarize_cellular_play(owner); + CHECK(ended && ended->owned == 0 && ended->deaths == 2 && ended->starved == 2 && + ended->engulfed == 0 && ended->owned_deaths == 2 && ended->lifespan_min > 0 && + ended->lifespan_min <= ended->lifespan_median && + ended->lifespan_median <= ended->lifespan_max && ended->buds == 0 && + ended->living_genomes == 0); for (const auto& corpse : owner.corpses()) CHECK(corpse.cause == evo::biology::CellularDeathCause::starved && corpse.predator_life == 0 && corpse.inventory == Inventory{}); @@ -710,6 +718,9 @@ void rules_four_owner_buds_wildlife() { child.mutation == CellularMutationProgress{}); CHECK(child.growth.realized_per_thousand < 1000 && child.reserve.energy.value > 0); CHECK(owner.archive().living_carriers(parent_genome).value_or(0) == 2); + const auto counted = summarize_cellular_play(owner); + CHECK(counted && counted->owned == 1 && counted->wildlife == 1 && counted->buds == 1 && + counted->living_genomes == 1 && counted->deepest_lineage == 1 && counted->deaths == 0); CHECK(owner.last_tick_feedback().front().bud == CellularBudResult::budded && owner.last_tick_feedback().front().bud_life == identity); CHECK(owner.current_total() == owner.opening_total()); diff --git a/tests/region_store_tests.cpp b/tests/region_store_tests.cpp index ff1cded..41fa280 100644 --- a/tests/region_store_tests.cpp +++ b/tests/region_store_tests.cpp @@ -552,6 +552,16 @@ void cellular_v4_provisioning_uses_the_presence_bundle() { const auto manifest = decode_manifest(head->manifest); CHECK(manifest && manifest->cellular_versions == cellular_v6_versions && manifest->history_profile == cellular_revision_history_profile); + // 11.9 (ADR-0130): the read-only summary reports account-free aggregates of the head. + Child summary{{env("EVO_WORLD_CLONE_BIN"), "summary", "--world", "9769", "--region", "1", + "--pg-host", env("PGHOST"), "--pg-port", env("PGPORT"), "--pg-database", + env("PGDATABASE"), "--pg-user", env("PGUSER"), "--objects", r.root.string()}}; + CHECK(summary.wait_exit(30s) == 0); + const auto lines = summary.lines(); + CHECK(has(lines, "cellular summary world=9769 region=1 sequence=0 tick=0") && + has(lines, "living owned=0 wildlife=0 lingering=0 suspended=0") && + has(lines, "deaths total=0 starved=0 engulfed=0 unrecorded=0 owned=0 wildlife=0") && + has(lines, "evolution buds=0 mutations=0 living_genomes=0 deepest_lineage=0")); } void cellular_provisioning_survives_a_build_promotion() {