Keep a distribution, because a mean cannot say who survives
M4.1 defines the tier 2 record and who may act on it, and nothing else: no collapse transaction, no population advance, no materialization, no habitat geometry. Those are M4.2 to M4.4 and each needs its own decision. The named risk for this step is that population averages hide viable outliers, which is a property of the record rather than of the maths applied to it later, so it is answered here. Age classes each carry their own count and their own reserve. A count with a mean reserve cannot tell a provisioned cohort from one where half the members hold nothing, and nothing downstream can recover what that discarded. Within a class members are indistinguishable; that is the declared resolution and a stated loss. No accessor returns a mean, because an average that is easy to reach becomes the authority. Totals are summed from the classes rather than stored beside them, following the archive's rule that a second tally is a thing that can disagree. Lineage is not a field at all: ancestry is resolved from the genome through the archive, so a cohort cannot contradict it or invent parentage from membership. Residuals are integer numerators strictly below one member and are never added to a count. Ownership is enforced rather than described. One record per habitat and genome makes no-inventory-spendable-in-two-tiers unrepresentable instead of forbidden, and replacement is refused under a different worker or an older epoch. That is a single-process invariant; fencing between workers is M7 and M10. The approximation bound is carried and never computed, since carrying a bound is not meeting one. All nine guards were confirmed load-bearing by removing each and rerunning. An earlier sweep reporting none of them load-bearing was wrong and discarded: it wrote to /tmp, which Git Bash and PowerShell resolve differently, so nothing was ever mutated. Release 34/34, analysis, ASan 34/34 and clang-format all ran and passed here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,173 @@
|
||||
#pragma once
|
||||
|
||||
#include "evo/accounting/ledger.hpp"
|
||||
#include "evo/core/types.hpp"
|
||||
|
||||
#include <expected>
|
||||
#include <span>
|
||||
#include <vector>
|
||||
|
||||
namespace evo::ecology {
|
||||
// Where a cohort lives. M4.1 defines no geometry, extent or neighbourhood: this
|
||||
// is an identity a later milestone gives dimensions to.
|
||||
struct HabitatId {
|
||||
std::uint64_t value{};
|
||||
auto operator<=>(const HabitatId&) const = default;
|
||||
};
|
||||
// Who integrates this cohort, and for which epoch. ECOLOGY_MODEL locks that no
|
||||
// inventory is spendable in two tiers, so a cohort has exactly one owner and a
|
||||
// writer holding an older epoch is refused rather than merged.
|
||||
struct Owner {
|
||||
std::uint64_t worker{};
|
||||
std::uint64_t epoch{};
|
||||
auto operator<=>(const Owner&) const = default;
|
||||
};
|
||||
|
||||
// Fractional members are carried as a numerator over this scale. Integer only:
|
||||
// no quantity in this project is a float. A residual is strictly less than one
|
||||
// member, because at one member it is a member.
|
||||
inline constexpr std::uint64_t residual_scale = 1'000'000;
|
||||
|
||||
// One age class, holding its own count and its own reserve. The record keeps a
|
||||
// distribution rather than a mean, because a mean cannot say whether anyone in
|
||||
// the class would survive. Within a class members are indistinguishable; that is
|
||||
// the declared resolution, and a caller needing finer structure declares
|
||||
// narrower classes rather than dividing a total afterwards.
|
||||
struct AgeClass {
|
||||
std::uint64_t age_low{}; // ticks, inclusive
|
||||
std::uint64_t age_high{}; // ticks, exclusive; must exceed age_low
|
||||
std::uint64_t count{};
|
||||
// Held by this class in total, not per member. Dividing it would produce the
|
||||
// average this record exists to avoid.
|
||||
accounting::Inventory reserve{};
|
||||
// Owed to this class and not yet present, in units of residual_scale. It is
|
||||
// not a count and is never added to one.
|
||||
std::uint64_t residual{};
|
||||
auto operator<=>(const AgeClass&) const = default;
|
||||
};
|
||||
|
||||
// How far this representation may differ from simulating the same members
|
||||
// individually. Declared by whoever built the cohort and never computed here:
|
||||
// M4.5 measures resolution equivalence, and a bound this type derived for itself
|
||||
// would be a claim it has no basis for. Carrying a bound is not meeting one.
|
||||
struct ApproximationBound {
|
||||
std::uint64_t count{};
|
||||
accounting::Inventory inventory{};
|
||||
auto operator<=>(const ApproximationBound&) const = default;
|
||||
};
|
||||
|
||||
struct CohortDraft {
|
||||
std::uint32_t representation_version{};
|
||||
HabitatId habitat{};
|
||||
// The genome every member carries. Distinct genomes are never averaged into
|
||||
// one, so a cohort is per genome. Lineage is deliberately absent: it is the
|
||||
// archive's answer, resolved from this identity.
|
||||
std::uint64_t genome{};
|
||||
Owner owner{};
|
||||
// The last interval boundary this cohort was integrated to.
|
||||
Tick last_tick{};
|
||||
// The conversion that produced this record, kept as provenance.
|
||||
std::uint64_t conversion{};
|
||||
std::vector<AgeClass> classes;
|
||||
ApproximationBound bound{};
|
||||
};
|
||||
|
||||
enum class CohortError : std::uint8_t {
|
||||
unsupported_version,
|
||||
invalid_identity,
|
||||
no_age_classes,
|
||||
unordered_age_classes,
|
||||
empty_age_class,
|
||||
unowned_reserve,
|
||||
residual_out_of_range,
|
||||
overflow,
|
||||
duplicate_cohort,
|
||||
unknown_cohort,
|
||||
wrong_owner,
|
||||
stale_epoch,
|
||||
registry_full
|
||||
};
|
||||
|
||||
inline constexpr std::uint32_t cohort_representation_version = 1;
|
||||
inline constexpr std::size_t max_age_classes = 64;
|
||||
inline constexpr std::size_t max_cohorts = 4'096;
|
||||
|
||||
// A validated tier 2 record. Every invariant holds for as long as the value does:
|
||||
// there is no field-by-field assembly and no mutation after construction.
|
||||
class Cohort {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<Cohort, CohortError> create(CohortDraft draft);
|
||||
|
||||
[[nodiscard]] std::uint32_t representation_version() const noexcept {
|
||||
return version_;
|
||||
}
|
||||
[[nodiscard]] HabitatId habitat() const noexcept {
|
||||
return habitat_;
|
||||
}
|
||||
[[nodiscard]] std::uint64_t genome() const noexcept {
|
||||
return genome_;
|
||||
}
|
||||
[[nodiscard]] Owner owner() const noexcept {
|
||||
return owner_;
|
||||
}
|
||||
[[nodiscard]] Tick last_tick() const noexcept {
|
||||
return last_tick_;
|
||||
}
|
||||
[[nodiscard]] std::uint64_t conversion() const noexcept {
|
||||
return conversion_;
|
||||
}
|
||||
[[nodiscard]] std::span<const AgeClass> classes() const noexcept {
|
||||
return classes_;
|
||||
}
|
||||
[[nodiscard]] ApproximationBound bound() const noexcept {
|
||||
return bound_;
|
||||
}
|
||||
|
||||
// Derived by summing the classes rather than stored beside them, so no two
|
||||
// fields of a cohort can disagree. Both reject overflow at construction, so
|
||||
// these cannot fail afterwards.
|
||||
[[nodiscard]] std::uint64_t count() const noexcept;
|
||||
[[nodiscard]] accounting::Inventory reserve() const noexcept;
|
||||
// Total owed fraction, in units of residual_scale. May exceed one member once
|
||||
// summed across classes; the per-class bound is what is invariant.
|
||||
[[nodiscard]] std::uint64_t residual() const noexcept;
|
||||
// Deliberately no mean age and no per-member reserve. An average that is easy
|
||||
// to reach is an average that gets used as the authority.
|
||||
|
||||
auto operator<=>(const Cohort&) const = default;
|
||||
|
||||
private:
|
||||
Cohort() = default;
|
||||
std::uint32_t version_{};
|
||||
HabitatId habitat_{};
|
||||
std::uint64_t genome_{};
|
||||
Owner owner_{};
|
||||
Tick last_tick_{};
|
||||
std::uint64_t conversion_{};
|
||||
std::vector<AgeClass> classes_;
|
||||
ApproximationBound bound_{};
|
||||
};
|
||||
|
||||
// Holds at most one cohort per habitat and genome. Two records of one genome in
|
||||
// one habitat would be two places the same biomass could be spent, which is the
|
||||
// invariant ECOLOGY_MODEL locks; here it is unrepresentable rather than
|
||||
// forbidden. Nothing is serialized and no cross-worker protocol is implied.
|
||||
class CohortRegistry {
|
||||
public:
|
||||
[[nodiscard]] std::expected<void, CohortError> install(const Cohort& cohort);
|
||||
// Refused unless it comes from the recorded owner under the recorded epoch and
|
||||
// leaves habitat and genome unchanged, so a writer holding an older view fails
|
||||
// rather than overwriting a newer one.
|
||||
[[nodiscard]] std::expected<void, CohortError> replace(const Cohort& cohort);
|
||||
[[nodiscard]] std::expected<Cohort, CohortError> find(HabitatId habitat,
|
||||
std::uint64_t genome) const;
|
||||
[[nodiscard]] std::size_t size() const noexcept {
|
||||
return cohorts_.size();
|
||||
}
|
||||
|
||||
private:
|
||||
// Sorted by habitat then genome, so a lookup is a binary search and there is
|
||||
// one record of each thing with no index that could disagree with it.
|
||||
std::vector<Cohort> cohorts_;
|
||||
};
|
||||
} // namespace evo::ecology
|
||||
Reference in New Issue
Block a user