M11.1: time-based rate conversion (ADR-0099, segment 1)
Foundation / checks (deploy) (push) Successful in 3m27s
Foundation / checks (ecs) (push) Successful in 1m51s
Foundation / checks (client) (push) Successful in 12m31s
Foundation / checks (network) (push) Successful in 13m30s
Foundation / checks (tsan) (push) Canceled after 8m42s
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 27m37s
Foundation / checks (postgres) (push) Canceled after 15m9s

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 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-09 12:50:54 -04:00
co-authored by Claude Opus 5.5
parent 961b3e3c2f
commit a4c6181540
9 changed files with 293 additions and 4 deletions
+6 -1
View File
@@ -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)
@@ -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.
+7 -2
View File
@@ -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;
@@ -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.
+1
View File
@@ -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.
+19
View File
@@ -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.
+30
View File
@@ -0,0 +1,30 @@
#pragma once
#include <cstdint>
#include <expected>
// 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<std::uint64_t, RateError>
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<std::uint64_t, RateError>
per_second_from_per_tick(std::uint64_t per_tick_amount, std::uint64_t tick_microseconds) noexcept;
} // namespace evo::accounting
+54
View File
@@ -0,0 +1,54 @@
#include "evo/accounting/rates.hpp"
#include <limits>
namespace evo::accounting {
namespace {
constexpr auto u64_max = std::numeric_limits<std::uint64_t>::max();
bool valid_tick(std::uint64_t tick_microseconds) noexcept {
return tick_microseconds != 0 && tick_microseconds <= max_tick_microseconds;
}
} // namespace
std::expected<std::uint64_t, RateError>
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<std::uint64_t, RateError>
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
+91
View File
@@ -0,0 +1,91 @@
#include "evo/accounting/rates.hpp"
#include <cstdint>
#include <iostream>
#include <limits>
#include <stdexcept>
namespace {
using namespace evo::accounting;
void check(bool condition) {
if (!condition)
throw std::runtime_error("rate contract failed");
}
#define CHECK(expression) check(static_cast<bool>(expression))
constexpr std::uint64_t tick_50ms = 50'000;
constexpr auto u64_max = std::numeric_limits<std::uint64_t>::max();
bool is(const std::expected<std::uint64_t, RateError>& r, std::uint64_t value) {
return r.has_value() && *r == value;
}
bool fails(const std::expected<std::uint64_t, RateError>& 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;
}
}