From a4c61815407d9d96aef2e29440607f5be07580b0 Mon Sep 17 00:00:00 2001 From: dingo Date: Fri, 9 Oct 2026 12:50:54 -0400 Subject: [PATCH] M11.1: time-based rate conversion (ADR-0099, segment 1) Rates are stored per second in their integer base units and converted at the tick boundary with no carried state: costs round up, capacities down (maintainer decision), error below one unit per tick. per_second_from_per_tick is the migration's exact inverse (x20 at 50 ms) and refuses inexact values. New rate-contracts test. No biology uses it yet; genome v2, development v2 and process fields follow. Refresh the dev session window. Co-Authored-By: Claude Opus 5.5 --- CMakeLists.txt | 7 +- .../region/dev-session-route/listener.yaml | 2 +- docs/STATUS.md | 9 +- docs/adr/0099-time-based-biological-rates.md | 84 +++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/VALIDATION.md | 19 ++++ include/evo/accounting/rates.hpp | 30 ++++++ src/accounting/rates.cpp | 54 +++++++++++ tests/rate_tests.cpp | 91 +++++++++++++++++++ 9 files changed, 293 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0099-time-based-biological-rates.md create mode 100644 include/evo/accounting/rates.hpp create mode 100644 src/accounting/rates.cpp create mode 100644 tests/rate_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index ca75d73..52e6373 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -60,7 +60,7 @@ target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include target_compile_features(evo_world PUBLIC cxx_std_23) evo_owned_target(evo_world) -add_library(evo_accounting STATIC src/accounting/ledger.cpp) +add_library(evo_accounting STATIC src/accounting/ledger.cpp src/accounting/rates.cpp) add_library(evo::accounting ALIAS evo_accounting) target_include_directories(evo_accounting PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_compile_features(evo_accounting PUBLIC cxx_std_23) @@ -464,6 +464,11 @@ if(BUILD_TESTING) evo_owned_target(evo-ledger-tests) add_test(NAME ledger-contracts COMMAND evo-ledger-tests) set_tests_properties(ledger-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-rate-tests tests/rate_tests.cpp) + target_link_libraries(evo-rate-tests PRIVATE evo::accounting) + evo_owned_target(evo-rate-tests) + add_test(NAME rate-contracts COMMAND evo-rate-tests) + set_tests_properties(rate-contracts PROPERTIES TIMEOUT 60) add_executable(evo-tests tests/simulation_tests.cpp) target_link_libraries(evo-tests PRIVATE evo::simulation) evo_owned_target(evo-tests) diff --git a/deploy/kubernetes/region/dev-session-route/listener.yaml b/deploy/kubernetes/region/dev-session-route/listener.yaml index 772aba3..7ba83ae 100644 --- a/deploy/kubernetes/region/dev-session-route/listener.yaml +++ b/deploy/kubernetes/region/dev-session-route/listener.yaml @@ -12,7 +12,7 @@ spec: env: - {name: REGION_SESSION, value: "dev"} - {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"} - - {name: REGION_SESSION_WINDOW, value: "dev-20261009T163245-170:1791577965"} + - {name: REGION_SESSION_WINDOW, value: "dev-20261009T164435-675a:1791578075"} - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"} ports: # QUIC (ADR-0090): UDP only; nothing listens on TCP 7400. diff --git a/docs/STATUS.md b/docs/STATUS.md index e3eb9ee..a072151 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -15,8 +15,13 @@ ADR-0098 records the maintainer's decisions for the first playable cellular loop - **Birth cost:** a first bud fundable within a session (a tunable playtest target). - **Friend recognition:** deferred. -Next is 11.1's ratified engineering half: migrating biological rates from per-tick to -time-based units (ADR-0089). +11.1's ratified engineering half, time-based biological rates, is under way (ADR-0099; +the maintainer chose directional rounding): +- **Segment 1 (done):** `accounting/rates.hpp` converts a per-second rate to a per-tick + amount without saved state. Costs round up and capacities down, so rounding never + favours the organism. The migration's exact ×20 inverse refuses inexact values. +- **Segments 2–3 (next):** genome schema v2, development version 2, and the process and + checkpoint fields, with unchanged 50 ms goldens. Open from M10 (BACKLOG): - the maintainer's native-client observation, moved to the later 2k drill; diff --git a/docs/adr/0099-time-based-biological-rates.md b/docs/adr/0099-time-based-biological-rates.md new file mode 100644 index 0000000..098c12b --- /dev/null +++ b/docs/adr/0099-time-based-biological-rates.md @@ -0,0 +1,84 @@ +# ADR-0099: Time-based biological rates + +## Status +Accepted for M11.1 (2026-10-09). The maintainer ratified the direction on 2026-10-04 +(ADR-0089) and chose directional rounding on 2026-10-09. Segment 1 implements the +conversion. Segments 2 and 3 migrate the genome, development and process fields +listed below. + +## Context +Biological and environmental rates are stored per simulation tick: +- genome v1 `micrometres_per_tick` and `femtograms_per_tick`; +- development and metabolism maintenance, movement and intake per tick; +- the feeding decomposition limit; +- the environmental community's decay caps. + +The 50 ms tick therefore fixes biological speed in real time. ADR-0089 ratified rates +per unit time, converted deterministically at each tick, with an explicit precision +contract and a versioned migration that preserves 50 ms behaviour. + +## Decision +- **Unit.** A rate is an unsigned 64-bit integer **per second**, in its existing base + unit: pJ, fg or um. No fixed-point fraction is added. The base units are already + tiny (pJ, fg) relative to any organism's budget, so one base unit per second is + precision enough. +- **Conversion.** At the simulation tick, an amount is + `per_second * tick_microseconds / 1'000'000`, computed as whole seconds plus the + fractional part. No intermediate exceeds 64 bits, and overflow is an error, never a + wrap (`accounting::per_tick`). +- **Rounding** (maintainer decision): it never favours the organism. + - Capacities, limits, speeds and intake round **down**. + - Costs (maintenance, movement, construction) round **up**. + - No remainder is carried, so no new state is saved. The error is below one base + unit per tick per rate, and always against the organism. +- **Tick bounds.** 1 us to 1 s. +- **Exactness at 50 ms.** A per-tick value `v` migrates to `20 v` per second exactly + (`per_second_from_per_tick`). At 50 ms it converts back to `v` under either rounding, + so migrated behaviour is unchanged. The migration refuses any value that has no exact + per-second form at its recorded tick, and never rounds it. +- **Where conversion happens.** Only at the boundary where a rate becomes a per-tick + amount for the step being simulated: the metabolic budget, the consumer + configuration, the decomposition limit and the decay caps. Stored records hold + per-second values. + +### Migration (segments 2 and 3) +- **Genome.** Genome schema v2 declares `micrometres_per_second` and + `femtograms_per_second`. A v1 record is never rewritten: it stays as historical + provenance (GENOME_MODEL), and reading it converts at the recorded 50 ms quantum. +- **Development and processes.** Development version 2 and the process configurations + carry per-second rates. Their checkpoint formats take new versions, and older + versions are migrated at load at the checkpoint's own `tick_microseconds`. +- **Goldens.** Each goldened output must be bit-identical at 50 ms before and after. + Any golden that changes is a defect in the migration, never a reason to replace the + golden. +- **Dev world.** The upgrade uses the existing clone, migrate, compare and approve + procedure. World0 is not involved. + +## Alternatives considered +- **Carried remainders** (as `integrate_energy` does for incident energy, ADR-0050): + exact over time, but a saved remainder per organism per rate, with a larger + checkpoint migration. Rejected by the maintainer for M11. +- **Rates per millisecond, or a fixed-point fraction:** more precision than the base + units need, and more overflow surface. +- **Changing only the unit labels:** would leave the 50 ms coupling in place. + +## Benefits +- A tick change becomes a reviewable change of rounding, not a silent rescaling of + biology. +- No new saved state; conversion is deterministic and checked for overflow. +- Rounding never creates free energy or matter for an organism. + +## Costs and risks +- At a tick that does not divide a rate, an organism pays slightly more and takes in + slightly less than the exact rate, by under one unit per tick. Integer floors already + stop a very slow rate (below one unit per tick) from acting at all as a capacity. + For a cost, the same rate charges one unit per tick. Both are deliberate and bounded. +- The rate fields must be converted exactly once, at the boundary. Converting twice, + or not at all, would rescale biology. The goldens at 50 ms are the guard against + this. + +## Consequences +- Segment 1: `accounting/rates.hpp` (`per_tick`, `exact_per_tick`, + `per_second_from_per_tick`) and the `rate-contracts` test. +- Segments 2 and 3 migrate the fields above, with new versions and unchanged 50 ms + goldens. diff --git a/docs/adr/README.md b/docs/adr/README.md index f0a3c94..4974bdd 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -98,6 +98,7 @@ design. No unadopted candidate is a link dependency of the proof. - [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c). - [ADR-0090: M10 QUIC transport](0090-m10-quic-transport.md) - msquic 2.6.2 with OpenSSL 3.5.9 LTS (TLS 1.3 only) from pinned sources on Windows and Linux; DATAGRAM frames for superseding state, streams for reliable actions; M9 TLS/TCP kept as dev fallback; owned impairment relay; exact CA pinning due in 10.2b. +- [ADR-0099: Time-based biological rates](0099-time-based-biological-rates.md) - rates stored per second in their integer base units, converted at the tick boundary with no carried state; costs round up and capacities down (maintainer); exact x20 migration at 50 ms, inexact values refused; genome schema v2, development v2 and process formats follow. - [ADR-0098: M11 first cellular loop decisions](0098-m11-first-cellular-loop-decisions.md) - maintainer decisions for the first playable loop: budding (parent keeps control, one funded wildlife bud); funded in-life mutation from seeded candidates; exact-copy heredity with no NPC mutation in M11; logout lingers frozen but vulnerable, then suspends; resume in place or nearest valid spot within a bounded radius; absorption plus engulfment by contested size ratio; birth reachable within a session (tunable); friend recognition deferred. - [ADR-0097: M10 load and abuse qualification](0097-m10-load-and-abuse-qualification.md) - only evolution-dev reference-worker runs qualify; one multi-client evo-load tool with per-client distributions; a load governor over per-tick work (p95 window of 40 ticks) and tick debt refuses grant logins, then sheds replication radius and cadence in 3 levels with hysteresis (tickets still admitted); abuse suite of fuzz, floods, slow peers, storms and lease loss. - [ADR-0096: M10 probe handoff](0096-m10-probe-handoff.md) - EXPERIMENT durable probe records with one owning region and a conserved test inventory; fenced prepared/staged/committed/aborted transfers; signed single-use transfer tickets; protocol v4 offers, redirects and ghosts; recovery sweep (schema v14) and replay guard proven by a two-process fault matrix. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 5088aaa..b4aba55 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5353,3 +5353,22 @@ Executed: Not run: an RDP display-scale check. Under RDP the logical height drives the scale, the same as on a local display. + +## 2026-10-09 — M11.1 time-based rates, segment 1 (ADR-0099) + +`accounting::per_tick`, `exact_per_tick` and `per_second_from_per_tick` were added, +with a new `rate-contracts` test. The test covers: +- exact ×20 migration and round trip at 50 ms, under both roundings; +- directional rounding at an inexact tick, bracketing the exact amount one unit apart; +- sub-unit rates; +- tick bounds; +- the largest rate; +- overflow; +- refusal of an inexact migration. + +Executed: +- WSL `linux-debug` and `linux-asan`: `rate-contracts` and `ledger-contracts` passed. +- clang-tidy 19 (`linux-analysis`): clean. +- Windows `debug`: 61/61. + +No biology uses the conversion yet, so no golden is affected. diff --git a/include/evo/accounting/rates.hpp b/include/evo/accounting/rates.hpp new file mode 100644 index 0000000..26d4fbf --- /dev/null +++ b/include/evo/accounting/rates.hpp @@ -0,0 +1,30 @@ +#pragma once + +#include +#include + +// Time-based rates (ADR-0099, ratified direction ADR-0089). A biological or environmental +// rate is stored per second, in its integer base unit (pJ, fg, um), and converted to a +// per-tick amount at the fixed simulation tick. Conversion keeps no state: an amount that +// does not divide evenly is rounded in the direction that never favours the organism +// (costs up, capacities down), so the error is below one base unit per tick. +namespace evo::accounting { +inline constexpr std::uint64_t microseconds_per_second = 1'000'000; +inline constexpr std::uint64_t max_tick_microseconds = microseconds_per_second; +// down: a capacity, limit or speed (never more than the rate allows). +// up: a cost (never less than the rate demands). +enum class Rounding : std::uint8_t { down, up }; +enum class RateError : std::uint8_t { invalid_tick, overflow, inexact }; + +// per_second * tick_microseconds / 1 s, rounded as named. The tick is 1 us .. 1 s. +[[nodiscard]] std::expected +per_tick(std::uint64_t per_second, std::uint64_t tick_microseconds, Rounding rounding) noexcept; +// Whether per_tick needs no rounding at this tick. +[[nodiscard]] bool exact_per_tick(std::uint64_t per_second, + std::uint64_t tick_microseconds) noexcept; +// The migration's inverse: the per-second rate whose per-tick amount at this tick is +// exactly `per_tick_amount`. A value that has no exact per-second form is refused +// (`inexact`), never rounded: migrating must not change behaviour at the recorded tick. +[[nodiscard]] std::expected +per_second_from_per_tick(std::uint64_t per_tick_amount, std::uint64_t tick_microseconds) noexcept; +} // namespace evo::accounting diff --git a/src/accounting/rates.cpp b/src/accounting/rates.cpp new file mode 100644 index 0000000..79bfdd0 --- /dev/null +++ b/src/accounting/rates.cpp @@ -0,0 +1,54 @@ +#include "evo/accounting/rates.hpp" + +#include + +namespace evo::accounting { +namespace { +constexpr auto u64_max = std::numeric_limits::max(); +bool valid_tick(std::uint64_t tick_microseconds) noexcept { + return tick_microseconds != 0 && tick_microseconds <= max_tick_microseconds; +} +} // namespace + +std::expected +per_tick(std::uint64_t per_second, std::uint64_t tick_microseconds, Rounding rounding) noexcept { + if (!valid_tick(tick_microseconds)) + return std::unexpected(RateError::invalid_tick); + // Whole seconds and the fraction apart, so no intermediate exceeds 64 bits: the + // fraction's product is below 10^6 * 10^6. + const auto whole = per_second / microseconds_per_second; + const auto part = per_second % microseconds_per_second; + if (whole > u64_max / tick_microseconds) + return std::unexpected(RateError::overflow); + const auto scaled = part * tick_microseconds; + auto amount = whole * tick_microseconds; + const auto fraction = scaled / microseconds_per_second; + if (amount > u64_max - fraction) + return std::unexpected(RateError::overflow); + amount += fraction; + if (rounding == Rounding::up && scaled % microseconds_per_second != 0) { + if (amount == u64_max) + return std::unexpected(RateError::overflow); + ++amount; + } + return amount; +} + +bool exact_per_tick(std::uint64_t per_second, std::uint64_t tick_microseconds) noexcept { + return valid_tick(tick_microseconds) && + (per_second % microseconds_per_second) * tick_microseconds % microseconds_per_second == + 0; +} + +std::expected +per_second_from_per_tick(std::uint64_t per_tick_amount, std::uint64_t tick_microseconds) noexcept { + if (!valid_tick(tick_microseconds)) + return std::unexpected(RateError::invalid_tick); + if (per_tick_amount > u64_max / microseconds_per_second) + return std::unexpected(RateError::overflow); + const auto scaled = per_tick_amount * microseconds_per_second; + if (scaled % tick_microseconds != 0) + return std::unexpected(RateError::inexact); + return scaled / tick_microseconds; +} +} // namespace evo::accounting diff --git a/tests/rate_tests.cpp b/tests/rate_tests.cpp new file mode 100644 index 0000000..21e5ccb --- /dev/null +++ b/tests/rate_tests.cpp @@ -0,0 +1,91 @@ +#include "evo/accounting/rates.hpp" + +#include +#include +#include +#include + +namespace { +using namespace evo::accounting; + +void check(bool condition) { + if (!condition) + throw std::runtime_error("rate contract failed"); +} +#define CHECK(expression) check(static_cast(expression)) + +constexpr std::uint64_t tick_50ms = 50'000; +constexpr auto u64_max = std::numeric_limits::max(); + +bool is(const std::expected& r, std::uint64_t value) { + return r.has_value() && *r == value; +} +bool fails(const std::expected& r, RateError e) { + return !r.has_value() && r.error() == e; +} + +// At the ratified 50 ms tick, every per-tick value migrates exactly (x20) and converts +// back unchanged under either rounding: migration preserves behaviour. +void migration_is_exact_at_50ms() { + for (const std::uint64_t v : + {std::uint64_t{0}, std::uint64_t{1}, std::uint64_t{7}, std::uint64_t{100'000}, + std::uint64_t{1'000'000'000}, u64_max / 1'000'000}) { + const auto per_second = per_second_from_per_tick(v, tick_50ms); + CHECK(is(per_second, v * 20)); + CHECK(exact_per_tick(*per_second, tick_50ms)); + CHECK(is(per_tick(*per_second, tick_50ms, Rounding::down), v)); + CHECK(is(per_tick(*per_second, tick_50ms, Rounding::up), v)); + } +} + +// A tick that does not divide the rate rounds by direction, by less than one unit. +void directional_rounding() { + // 10 per second at 1/3 s: 3.33 per tick. + CHECK(!exact_per_tick(10, 333'333)); + CHECK(is(per_tick(10, 333'333, Rounding::down), 3)); + CHECK(is(per_tick(10, 333'333, Rounding::up), 4)); + // Below one unit per tick: a capacity rounds to nothing, a cost to one unit. + CHECK(is(per_tick(1, tick_50ms, Rounding::down), 0)); + CHECK(is(per_tick(1, tick_50ms, Rounding::up), 1)); + // Whole seconds and the fraction combine: 1'000'001 per second over 1 s and 0.5 s. + CHECK(is(per_tick(1'000'001, 1'000'000, Rounding::down), 1'000'001)); + CHECK(is(per_tick(1'000'001, 500'000, Rounding::down), 500'000)); + CHECK(is(per_tick(1'000'001, 500'000, Rounding::up), 500'001)); + // The two directions bracket the exact amount, one unit apart. + const std::uint64_t rate = 123'457, tick = 16'667; + const auto down = *per_tick(rate, tick, Rounding::down); + const auto up = *per_tick(rate, tick, Rounding::up); + const auto exact_millionths = rate * tick; + CHECK(down * 1'000'000 < exact_millionths && exact_millionths < up * 1'000'000); + CHECK(up - down == 1); +} + +void bounds() { + CHECK(fails(per_tick(1, 0, Rounding::down), RateError::invalid_tick)); + CHECK(fails(per_tick(1, max_tick_microseconds + 1, Rounding::up), RateError::invalid_tick)); + CHECK(fails(per_second_from_per_tick(1, 0), RateError::invalid_tick)); + CHECK(!exact_per_tick(0, 0)); + // A one-second tick passes the rate through; the largest rate still converts. + CHECK(is(per_tick(u64_max, max_tick_microseconds, Rounding::down), u64_max)); + CHECK(is(per_tick(u64_max, max_tick_microseconds, Rounding::up), u64_max)); + CHECK(is(per_tick(u64_max, tick_50ms, Rounding::down), u64_max / 20)); + CHECK(is(per_tick(u64_max, tick_50ms, Rounding::up), u64_max / 20 + 1)); + // The migration refuses what it cannot represent rather than rounding it. + CHECK(fails(per_second_from_per_tick(u64_max, tick_50ms), RateError::overflow)); + CHECK(fails(per_second_from_per_tick(1, 333'333), RateError::inexact)); + CHECK(is(per_second_from_per_tick(3, 3), 1'000'000)); +} +} // namespace + +int main() { + try { + migration_is_exact_at_50ms(); + directional_rounding(); + bounds(); + std::cout << "rate contracts passed\n"; + return 0; + } catch (const std::exception& e) { + std::cerr << e.what() << '\n'; + return 1; + } +}