feat(biology): liquid-relative cellular kinematics and the Git tuning file
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 27s
Foundation / server-image (push) Successful in 4m5s
Foundation / image (push) Successful in 4m17s

Phase 1 of the region and movement plan. Adds the shared integer motion step:
Q10 velocity relative to the liquid, a 16-bit heading with a rate-limited turn,
funded forward/reverse thrust (unfunded thrust coasts), braking, separate forward
and lateral drag that decays to exactly zero, local flow, and a sub-micrometre
carry with no rounding drift. A golden trajectory digest matches across g++-14,
clang-19 and MSVC, so the server and client predictor agree exactly.

Adds deploy/kubernetes/region/dev/tuning/cellular.tuning with every v0 trial value
and a strict parser (unknown, missing, duplicate, out-of-range and inconsistent
values are refused) plus founder handling derived from it. Refreshes the DEV
session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-21 16:30:51 -04:00
co-authored by Claude Opus 5.5
parent 816c83d68f
commit ab5df35c3f
9 changed files with 1242 additions and 2 deletions
+278
View File
@@ -0,0 +1,278 @@
#include "evo/biology/cellular_kinematics.hpp"
#include <cstdint>
#include <cstdio>
#include <cstdlib>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
using namespace evo::biology;
void check(bool value, std::source_location at = std::source_location::current()) {
if (!value)
throw std::runtime_error("cellular kinematics line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
constexpr CellularArea area{60'000, 60'000};
constexpr CellularPosition middle{30'000, 30'000};
constexpr std::uint32_t extent = 20;
constexpr evo::accounting::Picojoules plenty{1'000'000'000};
constexpr std::int32_t um_per_s = 1'024; // Q10 velocity of 1 um/s.
// v0 founder handling: 400 um/s^2 thrust, k = 2 /s drag, one turn per second.
CellularHandling founder() {
return {.thrust_q10 = 400 * um_per_s / 20,
.reverse_thrust_q10 = 400 * um_per_s / 20,
.forward_drag_ppm = 95'163,
.lateral_drag_ppm = 95'163,
.turn = 3'277,
.thrust_cost = {1'000},
.reverse_cost = {1'000}};
}
CellularKinematicsResult step(CellularPosition position, const CellularMotionState& state,
CellularPropulsion propulsion, const CellularHandling& handling,
CellularFlowSample flow = {},
evo::accounting::Picojoules energy = plenty) {
const auto result =
step_cellular_kinematics(area, position, extent, state, propulsion, handling, flow, energy);
check(result.has_value());
return *result;
}
std::int64_t heading_error(std::uint16_t a, std::uint16_t b) {
const auto difference = static_cast<std::int16_t>(static_cast<std::uint16_t>(a - b));
return std::abs(static_cast<std::int64_t>(difference));
}
void trigonometry() {
CHECK(cellular_cos_q14(0) == 16'384 && cellular_sin_q14(0) == 0);
CHECK(cellular_sin_q14(16'384) == 16'384 && cellular_cos_q14(16'384) == 0);
CHECK(cellular_cos_q14(32'768) == -16'384 && cellular_sin_q14(32'768) == 0);
CHECK(cellular_sin_q14(49'152) == -16'384);
CHECK(cellular_sin_q14(8'192) == 11'585 && cellular_cos_q14(8'192) == 11'585);
for (std::uint32_t h = 1; h < cellular_heading_turn; ++h) {
const auto heading = static_cast<std::uint16_t>(h);
const std::int64_t s = cellular_sin_q14(heading), c = cellular_cos_q14(heading);
CHECK(std::abs(s * s + c * c - std::int64_t{16'384} * 16'384) <= std::int64_t{4} * 16'384);
CHECK(cellular_sin_q14(static_cast<std::uint16_t>(cellular_heading_turn - h)) == -s);
}
}
void headings() {
CHECK(cellular_heading_of(0, 0) == 0);
CHECK(heading_error(cellular_heading_of(1, 0), 0) <= 1);
CHECK(heading_error(cellular_heading_of(0, 1), 16'384) <= 1);
CHECK(heading_error(cellular_heading_of(-1, 0), 32'768) <= 1);
CHECK(heading_error(cellular_heading_of(0, -1), 49'152) <= 1);
CHECK(heading_error(cellular_heading_of(1'000, 1'000), 8'192) <= 1);
for (std::uint32_t h = 0; h < cellular_heading_turn; h += 7) {
const auto heading = static_cast<std::uint16_t>(h);
CHECK(
heading_error(cellular_heading_of(cellular_cos_q14(heading), cellular_sin_q14(heading)),
heading) <= 3);
}
}
void acceleration_reaches_steady_speed() {
CellularMotionState state{};
auto position = middle;
std::int32_t previous{};
for (int tick = 0; tick < 120; ++tick) {
const auto next = step(position, state, {{1'000, 0}, false}, founder());
CHECK(next.thrust == CellularThrustStatus::applied && next.cost.value == 1'000);
CHECK(next.state.velocity_x_q10 >= previous && next.state.velocity_y_q10 == 0);
previous = next.state.velocity_x_q10;
position = next.position;
state = next.state;
}
// Thrust then drag settle near 190 um/s for the v0 founder.
CHECK(state.velocity_x_q10 > 189 * um_per_s && state.velocity_x_q10 < 191 * um_per_s);
CHECK(position.x_um > middle.x_um + 1'000);
}
CellularMotionState moving_east(std::int32_t speed_um_s) {
return {.velocity_x_q10 = speed_um_s * um_per_s};
}
void coasting_stops_exactly() {
auto state = moving_east(200);
auto position = middle;
int ticks{};
while (state.velocity_x_q10 != 0) {
const auto next = step(position, state, {}, founder());
CHECK(next.thrust == CellularThrustStatus::idle && next.cost.value == 0);
CHECK(next.state.velocity_x_q10 < state.velocity_x_q10 && next.state.velocity_x_q10 >= 0);
position = next.position;
state = next.state;
CHECK(++ticks < 400);
}
// About 100 um of coasting from 200 um/s with a 0.5 s time constant.
CHECK(position.x_um > middle.x_um + 80 && position.x_um < middle.x_um + 110);
}
void braking_stops_sooner_without_reversing() {
auto state = moving_east(200);
int ticks{};
while (state.velocity_x_q10 != 0) {
const auto next = step(middle, state, {{}, true}, founder());
CHECK(next.state.velocity_x_q10 >= 0 && next.thrust == CellularThrustStatus::applied);
state = next.state;
CHECK(++ticks < 20);
}
const auto stopped = step(middle, state, {{}, true}, founder());
CHECK(stopped.thrust == CellularThrustStatus::idle && stopped.cost.value == 0);
}
void reversing_uses_reverse_thrust() {
auto state = moving_east(150);
auto position = middle;
for (int tick = 0; tick < 30; ++tick) {
const auto next = step(position, state, {{-1'000, 0}, false}, founder());
position = next.position;
state = next.state;
}
CHECK(state.velocity_x_q10 < 0);
// The heading turned toward the command as well.
CHECK(heading_error(state.heading, 32'768) <= 1);
}
void turning_is_rate_limited() {
const auto turned = step(middle, {}, {{0, 1'000}, false}, founder());
CHECK(turned.state.heading == 3'277);
// Perpendicular remains mostly sideways: thrust follows the body axis.
CHECK(turned.state.velocity_x_q10 > turned.state.velocity_y_q10);
}
void flow_drift_is_exact() {
CellularMotionState state{};
auto position = middle;
for (int tick = 0; tick < 20; ++tick) {
const auto next = step(position, state, {}, founder(), {100 * um_per_s, 0});
position = next.position;
state = next.state;
}
CHECK(position == CellularPosition{middle.x_um + 100, middle.y_um});
CHECK(state == CellularMotionState{});
// Against a current faster than the founder's swimming, progress is negative.
state = moving_east(190);
const auto upstream = step(middle, state, {{1'000, 0}, false}, founder(), {-300 * um_per_s, 0});
CHECK(upstream.position.x_um < middle.x_um);
}
void fractional_travel_carries() {
auto handling = founder();
handling.forward_drag_ppm = handling.lateral_drag_ppm = 0;
auto state = moving_east(7);
auto position = middle;
for (int tick = 0; tick < 20; ++tick) {
const auto next = step(position, state, {}, handling);
position = next.position;
state = next.state;
}
CHECK(position.x_um == middle.x_um + 7 && state.remainder_x == 0);
// Slow negative drift carries too.
state = {.velocity_y_q10 = -um_per_s / 2};
position = middle;
for (int tick = 0; tick < 40; ++tick) {
const auto next = step(position, state, {}, handling);
position = next.position;
state = next.state;
}
CHECK(position.y_um == middle.y_um - 1 && state.remainder_y == 0);
}
void unfunded_thrust_coasts() {
const auto state = moving_east(100);
const auto coast = step(middle, state, {}, founder());
const auto broke = step(middle, state, {{1'000, 0}, false}, founder(), {}, {999});
CHECK(broke.thrust == CellularThrustStatus::unfunded && broke.cost.value == 0);
CHECK(broke.state == coast.state && broke.position == coast.position);
const auto half = step(middle, {}, {{500, 0}, false}, founder());
CHECK(half.cost.value == 500 && half.state.velocity_x_q10 > 0);
}
void edges_stop_motion() {
const CellularPosition edge{area.width_um - extent, 100};
const auto blocked = step(edge, moving_east(150), {{1'000, 0}, false}, founder());
CHECK(blocked.position == edge && blocked.state.velocity_x_q10 == 0);
CHECK(blocked.state.remainder_x == 0 && blocked.path_um == 0);
}
void lateral_drag_is_separate() {
auto handling = founder();
handling.forward_drag_ppm = 0;
handling.lateral_drag_ppm = 500'000;
const auto sideways = step(middle, {.velocity_y_q10 = 100 * um_per_s}, {}, handling);
CHECK(std::abs(sideways.state.velocity_y_q10 - 50 * um_per_s) <= 2);
const auto forward = step(middle, moving_east(100), {}, handling);
CHECK(std::abs(forward.state.velocity_x_q10 - 100 * um_per_s) <= 2);
}
void invalid_inputs() {
CHECK(!step_cellular_kinematics({0, 10}, {}, 1, {}, {}, founder(), {}, plenty));
CHECK(
!step_cellular_kinematics(area, {area.width_um, 0}, extent, {}, {}, founder(), {}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {{1'000, 1'000}, false}, founder(),
{}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent,
{.remainder_x = std::int64_t{1'024} * 1'000'000}, {}, founder(),
{}, plenty));
auto bad = founder();
bad.forward_drag_ppm = 1'000'000;
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {}, bad, {}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {}, founder(),
{cellular_velocity_limit_q10 + 1, 0}, plenty));
}
// Golden trajectory: any change to this value changes shared server/client motion.
void golden_trajectory() {
CellularMotionState state{};
auto position = middle;
std::uint64_t digest = 1'469'598'103'934'665'603ULL;
const auto mix = [&digest](std::uint64_t value) {
digest = (digest ^ value) * 1'099'511'628'211ULL;
};
for (int tick = 0; tick < 200; ++tick) {
const CellularIntent intent{static_cast<std::int16_t>((tick % 50) * 20 - 500),
static_cast<std::int16_t>(tick < 100 ? 600 : -600)};
const CellularFlowSample flow{(tick % 7) * 9'000 - 20'000, 15'000};
const auto next = step(position, state, {intent, tick % 37 == 0}, founder(), flow);
position = next.position;
state = next.state;
mix(position.x_um);
mix(position.y_um);
mix(static_cast<std::uint32_t>(state.velocity_x_q10));
mix(static_cast<std::uint32_t>(state.velocity_y_q10));
mix(state.heading);
}
std::printf("golden trajectory digest %llu\n", static_cast<unsigned long long>(digest));
CHECK(digest == 8'485'405'051'858'728'694ULL);
}
} // namespace
int main() {
try {
trigonometry();
headings();
acceleration_reaches_steady_speed();
coasting_stops_exactly();
braking_stops_sooner_without_reversing();
reversing_uses_reverse_thrust();
turning_is_rate_limited();
flow_drift_is_exact();
fractional_travel_carries();
unfunded_thrust_coasts();
edges_stop_motion();
lateral_drag_is_separate();
invalid_inputs();
golden_trajectory();
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
std::puts("cellular kinematics contracts passed");
return 0;
}
+156
View File
@@ -0,0 +1,156 @@
#include "evo/biology/cellular_tuning.hpp"
#include <cstdio>
#include <fstream>
#include <iterator>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
using namespace evo::biology;
void check(bool value, std::source_location at = std::source_location::current()) {
if (!value)
throw std::runtime_error("cellular tuning line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
CellularTuning v0() {
return {.version = 1,
.region_width_um = 60'000,
.region_height_um = 60'000,
.region_organism_cap = 2'000,
.region_deposit_limit = 8'192,
.region_perception_radius_um = 5'000,
.founder_thrust_um_per_s2 = 400,
.founder_reverse_thrust_um_per_s2 = 400,
.founder_drag_ppm_per_tick = 95'163,
.founder_lateral_drag_ppm_per_tick = 95'163,
.founder_turn_heading_per_s = 65'536,
.currents_min_count = 2,
.currents_max_count = 4,
.currents_min_width_um = 3'000,
.currents_max_width_um = 6'000,
.currents_min_speed_um_per_s = 60,
.currents_max_speed_um_per_s = 300,
.currents_grid_pitch_um = 250,
.food_merged_bubble_cap_multiple = 8,
.food_visible_moving_bubbles = 256,
.food_induced_drift_radius_um = 200,
.food_induced_drift_max_um_per_s = 100,
.food_induced_drift_decay_ppm_per_tick = 95'163,
.thermal_ambient_min_mk = 278'150,
.thermal_ambient_max_mk = 313'150,
.founder_preferred_mk = 293'150,
.founder_comfort_band_mk = 5'000,
.founder_body_tau_ms = 20'000,
.founder_lethal_cold_mk = 273'150,
.founder_lethal_heat_mk = 318'150,
.thermal_off_preference_per_mille_per_k = 80,
.thermal_transition_per_mille_per_k = 40,
.thermal_multiplier_cap_per_mille = 8'000,
.lifecycle_logout_delay_ms = 10'000,
.mutation_step_points = 5,
.mutation_paired_points = 2,
.mutation_recovery_floor_per_mille = 100,
.mutation_offer_interval_ms = 25'000,
.mutation_offer_options = 3};
}
// Replaces the first `key = ...` line of canonical text.
std::string with(std::string text, const std::string& key, const std::string& value) {
const auto at = text.find(key + " = ");
check(at != std::string::npos);
const auto end = text.find('\n', at);
return text.replace(at, end - at, key + " = " + value);
}
CellularTuningErrorKind error_of(const std::string& text) {
const auto parsed = parse_cellular_tuning(text);
check(!parsed.has_value());
return parsed.error().kind;
}
void canonical_round_trip() {
const auto text = encode_cellular_tuning(v0());
const auto parsed = parse_cellular_tuning(text);
CHECK(parsed && *parsed == v0());
CHECK(encode_cellular_tuning(*parsed) == text);
}
void comments_separators_and_whitespace() {
auto text = "# heading\n\n" + encode_cellular_tuning(v0());
text = with(text, "region.width_um", "60_000 # trailing comment\r");
text = with(text, "region.height_um", "\t60000");
const auto parsed = parse_cellular_tuning(text);
CHECK(parsed && *parsed == v0());
}
void refusals() {
const auto base = encode_cellular_tuning(v0());
CHECK(error_of(base + "unknown.key = 1\n") == CellularTuningErrorKind::unknown_key);
CHECK(error_of(base + "region.width_um = 60000\n") == CellularTuningErrorKind::duplicate_key);
CHECK(error_of(base + "no equals sign\n") == CellularTuningErrorKind::syntax);
CHECK(error_of(base + "Region.Width = 1\n") == CellularTuningErrorKind::syntax);
CHECK(error_of(with(base, "region.width_um", "60k")) == CellularTuningErrorKind::invalid_value);
CHECK(error_of(with(base, "region.width_um", "60__000")) ==
CellularTuningErrorKind::invalid_value);
CHECK(error_of(with(base, "region.width_um", "")) == CellularTuningErrorKind::invalid_value);
CHECK(error_of(with(base, "region.width_um", "999")) == CellularTuningErrorKind::out_of_range);
CHECK(error_of(with(base, "founder.drag_ppm_per_tick", "1000000")) ==
CellularTuningErrorKind::out_of_range);
CHECK(error_of(with(base, "region.width_um", "# missing")) ==
CellularTuningErrorKind::invalid_value);
CHECK(error_of(with(base, "currents.min_count", "5")) == CellularTuningErrorKind::inconsistent);
CHECK(error_of(with(base, "founder.preferred_mk", "320000")) ==
CellularTuningErrorKind::inconsistent);
CHECK(error_of(with(base, "tuning.version", "2")) ==
CellularTuningErrorKind::unsupported_version);
auto missing = base;
missing.erase(missing.find("mutation.offer_options"));
const auto parsed = parse_cellular_tuning(missing);
CHECK(!parsed && parsed.error().kind == CellularTuningErrorKind::missing_key &&
parsed.error().key == "mutation.offer_options");
const auto line = parse_cellular_tuning(base + "\nbad\n");
CHECK(!line && line.error().line == 41);
CHECK(error_of(std::string(max_cellular_tuning_bytes + 1, '#')) ==
CellularTuningErrorKind::too_large);
}
void founder_handling() {
const auto handling = founder_cellular_handling(v0(), {1'000}, {900});
CHECK(handling.thrust_q10 == 20'480 && handling.reverse_thrust_q10 == 20'480);
CHECK(handling.forward_drag_ppm == 95'163 && handling.lateral_drag_ppm == 95'163);
CHECK(handling.turn == 3'276);
CHECK(handling.thrust_cost.value == 1'000 && handling.reverse_cost.value == 900);
}
// The checked-in DEV tuning file must parse; CTest passes its path when it is present.
void repository_file(const char* path) {
std::ifstream file(path, std::ios::binary);
CHECK(file.good());
const std::string text{std::istreambuf_iterator<char>(file), std::istreambuf_iterator<char>()};
const auto parsed = parse_cellular_tuning(text);
if (!parsed)
std::fprintf(stderr, "%s: line %zu %s: %s\n", path, parsed.error().line,
parsed.error().key.c_str(),
std::string{describe(parsed.error().kind)}.c_str());
CHECK(parsed && *parsed == v0());
}
} // namespace
int main(int argc, char** argv) {
try {
canonical_round_trip();
comments_separators_and_whitespace();
refusals();
founder_handling();
if (argc > 1)
repository_file(argv[1]);
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
std::puts("cellular tuning contracts passed");
return 0;
}