Files
aevolution/include/evo/server/lifecycle/cellular_lives.hpp
T
dingoandClaude Opus 5.5 e74bdf286b
Foundation / checks (ecs) (push) Successful in 2m15s
Foundation / checks (deploy) (push) Successful in 3m53s
Foundation / checks (tsan) (push) Successful in 9m46s
Foundation / checks (client) (push) Failing after 13m47s
Foundation / checks (network) (push) Successful in 19m5s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 19m34s
Foundation / checks (postgres) (push) Canceled after 19m28s
Freeze offline cells, linger, suspend and resume them
M11.7 (ADR-0128): a frozen step intent, set by the server for every owned life
whose account holds no session, leaves the cell unchanged but engulfable. Owner
format 6 / rules 5 track presence: lingering for 200 ticks, then suspended out of
the world without aging; an unfrozen intent resumes it in place or at the nearest
clear spot within three extents. Bundle v6, schema v38 and the cellular-v4
opening carry it. The server refuses an offline account's carried actions, ticks
while anyone lingers, and skips suspended cells in replication and perception.

Also fixes the TSan failure of CI run 374: the rules-4 owner test read the bud
through a reference into a replaced state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 07:50:45 -04:00

251 lines
12 KiB
C++

#pragma once
#include "evo/biology/cellular_region_step.hpp"
#include "evo/biology/mutation.hpp"
#include "evo/server/lifecycle/primitive_lives.hpp"
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <span>
#include <vector>
namespace evo::server {
inline constexpr std::uint32_t cellular_lives_legacy_format = 1;
inline constexpr std::uint32_t cellular_lives_format = 2;
inline constexpr std::uint32_t cellular_lives_revision_format = 3;
inline constexpr std::uint32_t cellular_lives_rules = 2;
// ADR-0124: format 4 adds each corpse's cause and predator; rules 3 add engulfment and
// corpse detritus. They are used together, with the revision-format archive.
inline constexpr std::uint32_t cellular_lives_engulf_format = 4;
inline constexpr std::uint32_t cellular_lives_engulf_rules = 3;
// ADR-0125: format 5 adds the region's bud sequence and each life's and corpse's parent
// life; rules 4 add funded budding of unowned wildlife on top of rules 3.
inline constexpr std::uint32_t cellular_lives_bud_format = 5;
inline constexpr std::uint32_t cellular_lives_bud_rules = 4;
// ADR-0128: format 6 adds each life's presence and freeze tick; rules 5 are rules 4 plus
// the offline freeze, linger, suspension and resume.
inline constexpr std::uint32_t cellular_lives_presence_format = 6;
inline constexpr std::uint32_t cellular_lives_presence_rules = 5;
// Trial values (ADR-0128): ticks a frozen life lingers in the world (10 s at 50 ms), and
// how many of its own extents away a resume may look for a clear spot.
inline constexpr std::uint64_t cellular_linger_ticks = 200;
inline constexpr std::uint32_t cellular_resume_extents = 3;
enum class CellularPresence : std::uint8_t {
active,
lingering,
suspended
}; // A bud's life, organism and event identity: 2^63 + region * 2^32 + sequence. A rules-4
// owner refuses an allocated identity at or above 2^63, so the namespaces never meet.
inline constexpr std::uint64_t cellular_bud_namespace = std::uint64_t{1} << 63U;
inline constexpr std::uint64_t cellular_bud_max_region = (std::uint64_t{1} << 31U) - 1;
[[nodiscard]] constexpr std::uint64_t cellular_bud_identity(std::uint64_t region,
std::uint64_t sequence) noexcept {
return region == 0 || region > cellular_bud_max_region || sequence == 0 ||
sequence > 0xFFFF'FFFFULL
? 0
: cellular_bud_namespace + (region << 32U) + sequence;
}
inline constexpr std::size_t max_cellular_lives_bytes = std::size_t{16} * 1024 * 1024;
inline constexpr std::uint64_t cellular_mutation_surplus_seconds = 60;
inline constexpr std::uint16_t cellular_mutation_candidate_count = 3;
inline constexpr std::uint32_t cellular_mutation_stream = 0x4D555431U; // "MUT1"
struct CellularMutationProgress {
std::uint64_t fed_energy_credit_pj{};
std::uint64_t event_index{};
std::uint64_t offer_tick{};
std::optional<biology::MutationOffer> offer;
auto operator<=>(const CellularMutationProgress&) const = default;
};
struct CellularOwnedLife {
LifeAccount account{};
LifeAllocation identity{};
std::uint64_t source{};
biology::GrowthState growth{};
biology::CellularPosition position{};
accounting::Inventory body{};
accounting::Inventory reserve{};
CellularMutationProgress mutation{};
std::uint64_t parent_life{}; // Format 5: the budding parent; zero for a founder.
// Format 6 (ADR-0128): presence and the tick its freeze began (zero while active).
CellularPresence presence{CellularPresence::active};
std::uint64_t frozen_since{};
auto operator<=>(const CellularOwnedLife&) const = default;
};
struct CellularOwnedCorpse {
std::uint64_t life_id{};
std::uint64_t organism{};
std::uint64_t source{};
std::uint64_t died_tick{};
biology::CellularPosition position{};
biology::GrowthState growth{};
std::uint32_t extent_um{};
accounting::Inventory inventory{}; // Empty under rules 3: it became detritus.
biology::CellularDeathCause cause{biology::CellularDeathCause::unrecorded};
std::uint64_t predator_life{}; // Engulfed only.
std::uint64_t parent_life{}; // Format 5: kept after death.
auto operator<=>(const CellularOwnedCorpse&) const = default;
};
struct CellularLifeIntent {
std::uint64_t life_id{};
biology::CellularStepIntent intent{};
auto operator<=>(const CellularLifeIntent&) const = default;
};
struct CellularMutationSelection {
std::uint64_t life_id{}, event_index{}, offer_tick{}, successor_id{};
std::uint16_t operator_id{};
auto operator<=>(const CellularMutationSelection&) const = default;
};
enum class CellularMutationResult : std::uint8_t { applied, life_died, insufficient_funding };
struct CellularMutationExecution {
std::uint64_t life_id{}, successor_id{};
CellularMutationResult result{};
auto operator<=>(const CellularMutationExecution&) const = default;
};
enum class CellularBudResult : std::uint8_t {
budded,
life_died, // The parent died earlier in the tick.
not_able, // No reproduction capability, not fully grown, or damaged.
insufficient_funding, // Some channel of investment plus provision is missing.
no_placement // No free spot touching the parent, or no identity left.
};
struct CellularBudExecution {
std::uint64_t parent_life{}, bud_life{}; // bud_life is zero unless budded.
CellularBudResult result{};
auto operator<=>(const CellularBudExecution&) const = default;
};
struct CellularTickExecution {
biology::CellularRegionStepCandidate step;
std::vector<CellularMutationExecution> mutations;
std::vector<CellularBudExecution> buds; // Rules 4, in parent life order.
};
struct CellularLifeTickFeedback {
std::uint64_t life_id{}, tick{};
accounting::Inventory reserve;
accounting::Picojoules maintenance_cost{}, movement_cost{};
biology::CellularMovementStatus movement{biology::CellularMovementStatus::not_requested};
biology::CellularIntakeStatus intake{biology::CellularIntakeStatus::not_requested};
biology::CellularEngulfStatus engulf{biology::CellularEngulfStatus::not_requested};
std::uint64_t prey_life{};
std::optional<CellularBudResult> bud; // Rules 4, when this life asked to bud.
std::uint64_t bud_life{};
// Rules 5: presence after the tick, and whether a requested resume found no clear spot.
CellularPresence presence{CellularPresence::active};
bool resume_blocked{};
auto operator<=>(const CellularLifeTickFeedback&) const = default;
};
// Which owner version a new region starts on. Offers: format 2, rules 2 (the M11.3/11.4
// trial, upgraded by the no-tick migrations). Engulf: format 4, rules 3 (ADR-0124).
// Budding: format 5, rules 4 (ADR-0125). Presence: format 6, rules 5 (ADR-0128).
enum class CellularLivesProfile : std::uint8_t { offers, engulf, budding, presence };
struct CellularLivesConfig {
biology::CellularArea area{};
std::uint64_t tick{};
std::uint32_t ambient_temperature_millikelvin{};
};
enum class CellularLivesError : std::uint8_t {
identity,
invalid_config,
invalid_life,
life_exists,
no_placement,
insufficient_funding,
duplicate_life,
invalid_tick,
invalid_intents,
biology,
region_step,
mutation,
archive,
habitat,
overflow,
conservation,
format,
version,
checksum,
noncanonical
};
// In-memory authoritative cellular owner. It consumes funded profile-3 opening
// state but never mutates or reinterprets that checkpoint. Each tick is applied
// to a detached candidate and swapped only after life, corpse, heat, habitat and
// archive closure all validate. Durable profile-4 publication remains external.
class CellularLives {
public:
[[nodiscard]] static std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
create(const PrimitiveLives& opening, std::unique_ptr<biology::CellularHabitat> habitat,
CellularLivesConfig config, CellularLivesProfile profile = CellularLivesProfile::offers);
CellularLives(const CellularLives&) = delete;
CellularLives& operator=(const CellularLives&) = delete;
~CellularLives();
[[nodiscard]] std::uint64_t world() const noexcept;
[[nodiscard]] std::uint64_t region() const noexcept;
[[nodiscard]] std::uint64_t frame() const noexcept;
[[nodiscard]] std::uint64_t tick() const noexcept;
[[nodiscard]] std::uint32_t format_version() const noexcept;
[[nodiscard]] std::uint32_t rules_version() const noexcept;
// Format 5: the sequence the next bud's identity will use (ADR-0125).
[[nodiscard]] std::uint64_t next_bud_sequence() const noexcept;
[[nodiscard]] std::uint32_t ambient_temperature_millikelvin() const noexcept;
[[nodiscard]] biology::CellularArea area() const noexcept;
[[nodiscard]] std::span<const CellularOwnedLife> lives() const noexcept;
[[nodiscard]] std::span<const CellularOwnedCorpse> corpses() const noexcept;
[[nodiscard]] const biology::CellularHabitat& habitat() const noexcept;
[[nodiscard]] const biology::LineageArchive& archive() const noexcept;
[[nodiscard]] accounting::Inventory nursery() const noexcept;
[[nodiscard]] accounting::Inventory heat() const noexcept;
[[nodiscard]] accounting::Inventory opening_total() const noexcept;
[[nodiscard]] accounting::Inventory current_total() const noexcept;
// Latest successful in-memory step report; omitted from snapshots and empty after restore.
[[nodiscard]] std::span<const CellularLifeTickFeedback> last_tick_feedback() const noexcept;
[[nodiscard]] std::vector<std::uint8_t> snapshot() const;
// Exact stock view for one live cell, filtered by its authoritative footprint and the
// M11.3 perception radius. Patch provenance and out-of-range stock are never returned.
[[nodiscard]] std::expected<std::vector<biology::CellularPatchPerception>, CellularLivesError>
perceive(std::uint64_t life_id) const;
// Stable unranked offer for the owning life; an absent offer is legitimate.
[[nodiscard]] std::expected<std::optional<biology::MutationOffer>, CellularLivesError>
mutation_offer(std::uint64_t life_id) const;
// Detached no-tick representation upgrade. Only a fully restored v1 owner can migrate.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
migrate_to_v2() const;
// Detached no-tick v2-to-v3 profile upgrade enabling genome revisions.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
migrate_to_v3() const;
// Returns a detached post-birth candidate for an allocator-reserved request.
// The caller supplies the durable identity; the owner derives founder biology,
// funding, source and the first unoccupied provisioned site. Birth must occur
// at the current checkpoint tick, after that tick's existing-life step.
[[nodiscard]] std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
birth_candidate(LifeRequest request, LifeAllocation allocation) const;
[[nodiscard]] static std::expected<std::unique_ptr<CellularLives>, CellularLivesError>
restore(std::span<const std::uint8_t> bytes, std::uint64_t world, std::uint64_t region,
std::uint64_t frame, std::uint64_t tick);
// Advances every living cell exactly one 50 ms tick. Intentions are keyed by
// stable life ID and must cover the living set exactly. Any refusal leaves
// this owner byte-for-byte unchanged.
[[nodiscard]] std::expected<biology::CellularRegionStepCandidate, CellularLivesError>
advance_tick(std::span<const CellularLifeIntent> intents);
// Mutation selections are validated against the predecessor offer, then applied
// after the normal life step and before births on the same advancing tick.
[[nodiscard]] std::expected<CellularTickExecution, CellularLivesError>
advance_tick_with_mutations(std::span<const CellularLifeIntent> intents,
std::span<const CellularMutationSelection> selections);
private:
struct State;
explicit CellularLives(std::unique_ptr<State> state);
std::unique_ptr<State> state_;
std::vector<CellularLifeTickFeedback> last_tick_feedback_;
};
} // namespace evo::server