Ratify M10.1 timing and workload budgets with session traces
Foundation / checks (deploy) (push) Successful in 1m0s
Foundation / checks (ecs) (push) Successful in 3m34s
Foundation / checks (network) (push) Successful in 8m8s
Foundation / checks (client) (push) Successful in 14m49s
Foundation / checks (tsan) (push) Successful in 7m35s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 16m18s
Foundation / checks (checks) (push) Canceled after 29m27s

ADR-0089 records the maintainer-ratified 50 ms tick, 1 s flush with final
outcomes p95 <= 1.5 s, responsiveness targets and reference hardware, plus
derived scheduling, sequence, identity, baseline, queue/byte/work budgets and the
exact/tolerant determinism contract (schemas/network/m10-budgets-v1.md). Adds
SessionClient traffic counters, `evo-dev-session trace` and a reproducible trace
script; development-reference results are in M10_TIMING_TRACES. Records that
genome v1 and metabolism rates are per tick, so the quantum fixes biology rates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-03 12:29:58 -04:00
co-authored by Claude Opus 5.5
parent 6152d58fa6
commit 819137c1df
15 changed files with 557 additions and 12 deletions
+207 -8
View File
@@ -15,11 +15,21 @@
// "probe awaiting-restart") for the connection to be lost and re-established at a
// newer epoch with a fresh baseline, and repeats the acknowledgement check.
// Prints "probe passed" on success. Used by tools/ops/session-drill.sh.
// evo-dev-session trace --connect HOST:PORT --server-name NAME --ca FILE --grants FILE
// [--intents 1..1000] [--interval-ms 50..10000] [--out FILE.csv] [--timeout 10..600]
// M10.1 timing experiment: after a fresh baseline, sends one intention per interval
// and records, on the client's monotonic clock, send -> IntentResult (admission
// round trip) and send -> IntentOutcome (durable), the outcome tick against the view
// tick at send, view inter-arrival times and received bytes. Prints nearest-rank
// percentiles ("trace ..." lines); --out writes every sample as CSV. Fails on any
// loss or rejection, so a run measures one uninterrupted session.
// Exit: 0 written/passed, 1 failure, 2 usage.
#include "evo/network/dev_credentials.hpp"
#include "evo/network/session_client.hpp"
#include <algorithm>
#include <charconv>
#include <chrono>
#include <cmath>
#include <cstdio>
#include <filesystem>
#include <fstream>
@@ -257,6 +267,191 @@ int probe(const Args& a, bool expect_restart) {
std::puts("probe passed");
return 0;
}
// Nearest-rank percentile of a non-empty sample (sorted copy).
double percentile(std::vector<double> v, double p) {
std::sort(v.begin(), v.end());
const auto rank =
static_cast<std::size_t>(std::ceil(p / 100.0 * static_cast<double>(v.size())));
return v[std::clamp<std::size_t>(rank, 1, v.size()) - 1];
}
void report(const char* name, const std::vector<double>& v) {
if (v.empty()) {
std::printf("trace %s n=0\n", name);
return;
}
std::printf("trace %s n=%zu p50=%.1f p95=%.1f p99=%.1f max=%.1f\n", name, v.size(),
percentile(v, 50), percentile(v, 95), percentile(v, 99),
*std::max_element(v.begin(), v.end()));
}
int trace(const Args& a) {
const auto connect = a.get("--connect");
const auto name = a.get("--server-name");
const auto ca = a.get("--ca");
const auto bundle_path = a.get("--grants");
const auto timeout = number(a.get("--timeout").value_or("300"));
const auto intents = number(a.get("--intents").value_or("120"));
const auto interval = number(a.get("--interval-ms").value_or("250"));
if (!connect || !name || !ca || !bundle_path || !timeout || *timeout < 10 || *timeout > 600 ||
!intents || *intents < 1 || *intents > 1000 || !interval || *interval < 50 ||
*interval > 10000)
return 2;
const auto colon = connect->rfind(':');
if (colon == std::string_view::npos || colon == 0)
return 2;
const std::uint64_t port = number(connect->substr(colon + 1)).value_or(0);
const auto bundle = read_file(*bundle_path);
if (port == 0 || port > 65535 || bundle.empty() || bundle.size() % dev_grant_bytes != 0)
return 2;
SessionClientConfig config;
config.host = std::string{connect->substr(0, colon)};
config.port = static_cast<std::uint16_t>(port);
const auto pem = read_file(*ca);
config.trust = {{pem.begin(), pem.end()}, std::string{*name}};
for (std::size_t at = 0; at < bundle.size(); at += dev_grant_bytes) {
DevGrant grant{};
std::copy_n(bundle.begin() + static_cast<std::ptrdiff_t>(at), grant.size(), grant.begin());
config.grants.push_back(grant);
}
auto made = SessionClient::create(std::move(config));
if (!made)
return 2;
auto& c = **made;
using Clock = std::chrono::steady_clock;
const auto start = Clock::now();
const auto ms = [&](Clock::time_point t) {
return std::chrono::duration<double, std::milli>(t - start).count();
};
const auto deadline = start + std::chrono::seconds{*timeout};
struct Sample {
double sent{}, result{-1}, outcome{-1};
std::uint64_t tick_at_send{}, outcome_tick{}, commit{};
int status{-1};
};
std::vector<Sample> samples;
std::vector<double> view_at;
std::vector<std::uint64_t> view_tick;
std::vector<double> view_bytes;
std::optional<std::uint64_t> last_tick;
ClientTraffic seen{};
std::uint64_t sequence = 0, resolved = 0;
std::optional<Clock::time_point> next_send;
const auto failed = [](const char* why) {
std::printf("trace failed: %s\n", why);
return 1;
};
while (resolved < *intents) {
const auto now = Clock::now();
if (now >= deadline)
return failed("timeout");
c.poll(now);
for (const auto& e : c.take_events()) {
using Kind = ClientEvent::Kind;
if (e.kind == Kind::lost || e.kind == Kind::closed || e.kind == Kind::unknown ||
e.kind == Kind::exhausted || e.kind == Kind::backpressure)
return failed("session interrupted (a trace must be one uninterrupted session)");
if ((e.kind == Kind::result || e.kind == Kind::outcome) &&
(e.sequence == 0 || e.sequence > samples.size()))
return failed("unexpected sequence");
if (e.kind == Kind::result) {
auto& sample = samples[e.sequence - 1];
sample.result = ms(now);
sample.status = static_cast<int>(e.result.status);
if (e.result.status != IntentStatus::admitted) {
++resolved;
std::printf("trace rejected sequence=%llu status=%u\n",
static_cast<unsigned long long>(e.sequence),
static_cast<unsigned>(e.result.status));
}
} else if (e.kind == Kind::outcome) {
auto& sample = samples[e.sequence - 1];
sample.outcome = ms(now);
sample.outcome_tick = e.outcome.tick;
sample.commit = e.outcome.commit_sequence;
++resolved;
}
}
const auto traffic = c.traffic();
if (const auto v = c.latest_view(); v && (!last_tick || *last_tick != v->server_tick)) {
last_tick = v->server_tick;
view_at.push_back(ms(now));
view_tick.push_back(v->server_tick);
const auto views = traffic.environment_views - seen.environment_views;
if (views > 0)
view_bytes.push_back(static_cast<double>(traffic.environment_view_bytes -
seen.environment_view_bytes) /
static_cast<double>(views));
seen = traffic;
}
// Start after a fresh, current baseline; then one intention per interval.
if (samples.size() < *intents && c.latest_view() &&
c.environment().freshness() == evo::client::Freshness::current) {
if (!next_send)
next_send = now;
if (now >= *next_send) {
const auto x = static_cast<std::int16_t>(sequence % 2 == 0 ? 1000 : -1000);
if (c.send({sequence + 1, 0, x, 0})) {
++sequence;
samples.push_back({ms(now), -1, -1, c.latest_view()->server_tick, 0, 0, -1});
*next_send += std::chrono::milliseconds{*interval};
}
}
}
// Poll continuously: a 1 ms sleep is about one 15.6 ms timer tick on Windows and
// would dominate the measured round trips. Costs one core for the run.
std::this_thread::yield();
}
std::vector<double> admission, durable, lead, intervals;
std::uint64_t admitted = 0, durable_count = 0;
for (const auto& s : samples) {
if (s.status == static_cast<int>(IntentStatus::admitted)) {
++admitted;
admission.push_back(s.result - s.sent);
}
if (s.outcome >= 0) {
++durable_count;
durable.push_back(s.outcome - s.sent);
lead.push_back(static_cast<double>(s.outcome_tick) -
static_cast<double>(s.tick_at_send));
}
}
for (std::size_t i = 1; i < view_at.size(); ++i)
intervals.push_back(view_at[i] - view_at[i - 1]);
const double seconds = ms(Clock::now()) / 1000.0;
std::printf("trace intents=%zu admitted=%llu outcomes=%llu interval_ms=%llu\n", samples.size(),
static_cast<unsigned long long>(admitted),
static_cast<unsigned long long>(durable_count),
static_cast<unsigned long long>(*interval));
report("admission_ms", admission);
report("durable_ms", durable);
report("outcome_tick_lead", lead);
report("view_interval_ms", intervals);
report("environment_view_bytes", view_bytes);
const auto total = c.traffic();
std::printf("trace views=%zu ticks=%llu seconds=%.1f received_bytes_per_s=%.0f frames=%llu\n",
view_at.size(),
static_cast<unsigned long long>(
view_tick.empty() ? 0 : view_tick.back() - view_tick.front()),
seconds, static_cast<double>(total.bytes) / seconds,
static_cast<unsigned long long>(total.frames));
if (const auto out = a.get("--out")) {
std::ofstream csv{std::string{*out}, std::ios::trunc};
csv << "kind,sequence,sent_ms,tick_at_send,result_ms,status,outcome_ms,outcome_tick,"
"commit\n";
for (std::size_t i = 0; i < samples.size(); ++i) {
const auto& s = samples[i];
csv << "intent," << i + 1 << ',' << s.sent << ',' << s.tick_at_send << ',' << s.result
<< ',' << s.status << ',' << s.outcome << ',' << s.outcome_tick << ',' << s.commit
<< '\n';
}
for (std::size_t i = 0; i < view_at.size(); ++i)
csv << "view,," << view_at[i] << ',' << view_tick[i] << ",,,,,\n";
if (!csv)
return failed("cannot write --out");
}
std::puts("trace passed");
return 0;
}
} // namespace
int main(int argc, char** argv) {
@@ -275,14 +470,18 @@ int main(int argc, char** argv) {
}) > 0;
const auto probe_args = parse(static_cast<int>(rest.size()), rest.data());
code = probe_args ? probe(*probe_args, restart) : 2;
}
} else if (args && command == "trace")
code = trace(*args);
if (code == 2)
std::fputs("usage: evo-dev-session credentials --environment dev --server-name NAME "
"--out DIR [--days N]\n"
" evo-dev-session grants --environment dev --key FILE --world N "
"--frame N --region N --subject N --out FILE [--count N] [--lifetime S]\n"
" evo-dev-session probe --connect HOST:PORT --server-name NAME --ca FILE "
"--grants FILE [--expect-restart] [--timeout S]\n",
stderr);
std::fputs(
"usage: evo-dev-session credentials --environment dev --server-name NAME "
"--out DIR [--days N]\n"
" evo-dev-session grants --environment dev --key FILE --world N "
"--frame N --region N --subject N --out FILE [--count N] [--lifetime S]\n"
" evo-dev-session probe --connect HOST:PORT --server-name NAME --ca FILE "
"--grants FILE [--expect-restart] [--timeout S]\n"
" evo-dev-session trace --connect HOST:PORT --server-name NAME --ca FILE "
"--grants FILE [--intents N] [--interval-ms MS] [--out FILE.csv] [--timeout S]\n",
stderr);
return code;
}
+4
View File
@@ -514,6 +514,10 @@ not a commitment to every body plan, planetary solver or locomotion mode.
**Goal:** responsive, authenticated, server-authoritative cellular sessions with
bounded replication and recovery under loss, overload and region transfer.
**Status (2026-10-03):** 10.1 ratified (ADR-0089, schemas/network/m10-budgets-v1.md,
networking/M10_TIMING_TRACES.md); targets are not yet qualified on the reference
hardware (10.9). 10.2-10.9 planned.
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
not automatically the production selection; proof tick and region sizes remain
+12 -1
View File
@@ -1,6 +1,17 @@
# Project status and next steps
## Current gate - 2026-10-02
## Current gate - 2026-10-03
M10.1 ratifies M10 timing and workload budgets (ADR-0089,
schemas/network/m10-budgets-v1.md): 50 ms tick, 1 s commit flush with final outcomes
p95 <= 1.5 s, responsiveness LAN p95 <= 150 ms and 100 ms RTT p95 <= 250 ms, server
budgets on one RKE2 worker and client budgets on the low-spec VM. Development-reference
traces (`evo-dev-session trace`, networking/M10_TIMING_TRACES.md) measured admission
p99 <= 5.2 ms, durable p95 about 1.4 s and 50 ms view cadence. Finding: genome v1 and
metabolism use per-tick rates, so the quantum fixes biological rates until M11.1
converts or ratifies them. Next: M10.2 transport selection against these budgets.
## Previous gate - 2026-10-02
M9.8a: Dear ImGui 1.92.9b is pinned and qualified in an isolated Windows/Linux
SDL3 probe (ADR-0084). M9.8b adds bounded notification/dialog state, protected
+99
View File
@@ -0,0 +1,99 @@
# ADR-0089: M10 protocol timing and workload budgets
## Status
Accepted for M10 (2026-10-03). Ratified by the maintainer: tick quantum, durable-outcome
target, responsiveness target and reference hardware. The remaining values are
engineering budgets derived from those and from the M10.1 traces; later M10 segments
may change them only with measurements and an amendment here. None of these values is
a game rule (see "Not game rules").
## Context
Open question #1 kept the 50 ms tick as a proof value "before M7/M10". M9 delivered a
TLS 1.3 dev session (ADR-0082/0083) whose constants (8-tick intent window, one intention
per tick, 1 s heartbeat, 256 KiB frames) were chosen for one engineering client. M10
needs explicit, measured budgets before transport selection (10.2), admission (10.4),
replication (10.5) and prediction (10.6) build on them. Traces:
[M10_TIMING_TRACES](../networking/M10_TIMING_TRACES.md); normative table:
[m10-budgets-v1](../../schemas/network/m10-budgets-v1.md).
## Decision — ratified (maintainer, 2026-10-03)
- **Authoritative tick: 50 ms (20 Hz)** for M10 work. Measured: tick debt 0, view
interval p50 50.1 ms, p99 <= 60 ms, server about 1 % CPU for one region and client.
- **Final outcomes** (death, reproduction, durable acknowledgements): commit flush stays
**1 s**; delivery p95 <= **1.5 s** after admission in dev/stage under nominal network.
Measured p95 1.37-1.41 s. Realtime feel comes from snapshots and prediction, never from
durable acknowledgements.
- **Responsiveness:** input to the first authoritative snapshot that reflects it, before
client smoothing: **LAN p95 <= 150 ms; emulated 100 ms RTT p95 <= 250 ms**.
- **Reference hardware:** server budgets per region host on one RKE2 worker (8 vCPU,
31.3 GiB; INVENTORY.md); client budgets on the low-spec VM once specified (M9.8g). The
AMD Ryzen 7 9800X3D / 61.6 GB Windows 11 workstation (WSL2 server) is the development
reference only; its traces do not qualify the targets.
## Decision — engineering budgets (derived; amend with evidence)
- **Input scheduling window:** an intention names its tick `t` with
`server_tick + 1 <= t <= server_tick + 8` (<= 400 ms ahead). Late inputs are rejected,
never rewound. The client lead adapts: `ceil((rtt/2 + jitter) / 50 ms) + 1`, clamped to
2..8 ticks. (The M9 client's fixed lead of 4 and the synthetic carrier's ~9-tick delay
are M9 artefacts; they cannot meet the LAN target and are not the M10 path.)
- **Snapshots:** every tick for entities in interest; fresh baseline on join, epoch change
and loss; lower-rate tiers for distant interest are defined in 10.5.
- **Sequences and identity:** intention sequence u64 per session, strictly increasing from
1, never wraps (exhaustion closes the session). Ticks and baseline ids u64, never wrap.
Realtime packet sequences (10.2) use serial-number arithmetic (RFC 1982) of at least
16 bits with an acceptance window below half the space. Session ids u64, server
assigned, bound to the authenticated connection; every message carries the region
ownership epoch; a stale epoch closes the session; reconnect is a new grant, a new
session and a fresh baseline; sessions never survive an epoch change.
- **Baselines:** the server keeps at most 4 per session, each at most 2 s (40 ticks) old;
a delta against an unknown or expired baseline is replaced by a fresh baseline. The
client keeps at most 2.
- **Per-session limits:** at most one intention per tick (8 per 8-tick window, every
attempt counted); at most 256 unresolved intentions; realtime datagram payload at most
1200 bytes (10.2); reliable frames at most 64 KiB in M10 (the M9 stream allows 256 KiB);
outbound replication at most 16 KiB per tick per session (about 2.6 Mbit/s), beyond
which interest degrades rather than queueing; client event queue 1024. Heartbeat 1 s,
liveness 5 s, hello/handshake deadline 5 s.
- **Per-region work:** at least 20 sessions (M10 exit), 32 by default; per-tick work
including session handling at most 25 ms p99 (half the quantum) on the reference worker;
session handling at most 0.5 ms per session per tick; queued host inputs at most 64 and
64 KiB (unchanged). Overload sheds interest and refuses new sessions before tick debt.
## Determinism contract
- **Exact:** authoritative state is a pure function of the checkpoint and the committed
per-tick inputs in commit order: byte-identical across runs and supported platforms
(existing goldens, recovery and replay use committed inputs only). Admission decisions
need not be reproducible; their admitted results are durable.
- **Tolerant:** wall-clock pacing and jitter, delivery timing, client prediction,
interpolation, smoothing and presentation floats. Their tolerances are presentation
error budgets defined in 10.6/10.7. Nothing network- or clock-derived enters
authoritative state except through committed inputs.
## Not game rules — and an existing coupling
Network limits bound work and fairness; they never encode movement speed, perception
range, feeding or any biological outcome.
The tick quantum, however, is **already coupled to biology**: genome v1 capabilities use
`micrometres_per_tick` and `femtograms_per_tick`, metabolism and development express
maintenance and movement cost in picojoules per tick, and decomposition has a per-tick
limit. Checkpoints record `tick_microseconds` (50,000), but the biological values are
per tick, so the 50 ms value currently fixes real-time biological rates. Consequently:
- M10 must not change the quantum. Any change is a versioned rules/genome migration
(convert per-tick to per-time units or rescale), with new goldens and a decision record.
- Ratifying 50 ms here ratifies an engineering budget, not those biological rates. The
per-tick units remain M3/M11 biology decisions (OPEN_QUESTIONS #1, M11.1 rules review),
which should either move to time-based units or explicitly ratify them at 50 ms.
## Alternatives considered
- 30 or 40 Hz ticks: smoother but 1.5-2x tick work and bandwidth, re-validation of tick
proofs; deferred until 10.6 prediction measurements show a need.
- 500 ms or 250 ms flush: faster final outcomes at 2-4x commit volume; deferred to 10.9
commit-cost measurements.
- Rewinding late inputs: complicates authority and replay; rejected for M10.
## Consequences
10.2 must meet the MTU, sequence and timeout budgets; 10.4 implements the scheduling
window and adaptive lead; 10.5 the baseline and per-tick byte limits; 10.9 measures the
targets on the reference hardware with 20+ clients and emulated RTT/loss. Measured
values in this ADR come from one dev region and one client; they do not qualify the
targets on the reference hardware.
+1
View File
@@ -97,6 +97,7 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [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-0089: M10 timing and budgets](0089-m10-timing-and-budgets.md) - ratified 50 ms tick, 1 s flush with final outcomes p95 <= 1.5 s, responsiveness LAN p95 <= 150 ms / 100 ms RTT <= 250 ms, reference hardware; derived scheduling, sequence, baseline, queue/byte/work budgets and the exact/tolerant determinism contract; records the per-tick biology coupling.
- [ADR-0088: Rendered deployment policy](0088-rendered-deployment-policy.md) - the deploy policy check renders every overlay with pinned kustomize v5.8.1 (checksum-verified, explicit preparation) and validates effective objects; unsupported kustomize features refused.
- [ADR-0087: Dev session route](0087-dev-session-route.md) - evolution-dev only: void.aeternalisgames.com:7400 via a dedicated internal MetalLB VIP to the region pod, TLS end to end, CIDR-limited, operator-opened windows enforced by evo-server; committed disabled with fail-closed policy tests.
- [ADR-0086: Windows client package](0086-windows-client-package.md) - static-runtime Windows x64 ZIP with explicit allowlist, licence texts, build identity, SHA256 manifest, credential guards and deterministic layout; local packaging until a Windows runner exists.
+2 -1
View File
@@ -1,7 +1,8 @@
# Authoritative network architecture
Status: locked server authority and untrusted clients; transport/reliability are
proposals for M10. The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
proposals for M10. M10 timing and workload budgets: ADR-0089 and
[m10-budgets-v1](../../schemas/network/m10-budgets-v1.md). The scoped M9 dev session (TLS 1.3, protocol v1, dev-only grants)
is specified in [DEV_SESSION_PROTOCOL](../networking/DEV_SESSION_PROTOCOL.md) and
ADR-0082. M0 has no networking. Steam distribution follows later through
an identity-provider adapter; core account IDs are independent of Steam IDs.
+1 -1
View File
@@ -6,7 +6,7 @@ person. ADR indexes distinguish scoped proof choices from production proposals.
| # | Open question | Current position / experiment | Owner; gate |
|---|---|---|---|
| 1 | Tick frequency | 20Hz proof only; measure latency, CPU, stiff biology | Simulation/network; before M7/M10 |
| 1 | Tick frequency | 50 ms (20 Hz) ratified as the M10 engineering budget (ADR-0089, traces in M10_TIMING_TRACES). Genome v1/metabolism rates are per tick, so the quantum fixes biological rates: convert to time units or ratify at 50 ms in M11.1 | Biology/design; M11.1 (network budget closed in M10.1) |
| 2 | Fixed/variable boundaries | Fixed authoritative ticks, host wall-clock pacing; ecology integer multiples | Simulation; M1 |
| 3 | ECS | Row/EnTT4 experiment in ADR-0021; retain bounded rows for proof, production choice awaits richer workloads (Flecs remains an alternative) | Engine; M1 and biological component gate |
| 4 | Dependency manager | Evaluate vcpkg manifest vs Conan; no runtime dependency for proof | Build; first dependency |
+29
View File
@@ -3982,3 +3982,32 @@ selector, a port-less entry, and rendered route patches of the selector, VIP and
range; the reviewer's m98f-8a1e5ef-repro.py now exits 1 with default-deny and
session-port failures in platform/dev and platform/cluster. No cluster action. M9.8f
remains open.
## 2026-10-03 — M10.1 protocol timing and workload budgets (ADR-0089)
Maintainer ratified: 50 ms tick, 1 s flush with final outcomes p95 <= 1.5 s,
responsiveness LAN p95 <= 150 ms / 100 ms RTT p95 <= 250 ms, server budgets on one RKE2
worker and client budgets on the low-spec VM. Derived budgets and the exact/tolerant
determinism contract are in ADR-0089 and schemas/network/m10-budgets-v1.md.
Implemented: `SessionClient::traffic()` received-frame counters (additive API, checked
in network_session); `evo-dev-session trace` (continuous polling, nearest-rank
percentiles, CSV); `tools/network/session-trace.sh` (throwaway PostgreSQL, development-v1
region, evo-server with sessions and ops metrics, three loopback runs, cross-host pause).
Traces (development reference: Ryzen 7 9800X3D, 61.6 GB, Windows 11; WSL2 server):
committed-script run with Linux loopback at 250/100/1000 ms and Windows -> WSL2 at
250 ms: admission p50 0.9-1.4 ms, p99 <= 5.2 ms; durable p50 0.92-1.06 s, p95
1.37-1.41 s, max 1.46 s; outcome lead 9 ticks; view interval p50 50.1 ms, p99 <= 60 ms;
267-byte views, about 7.5 KB/s; tick debt max 0, server about 1 % CPU, 10.5 MB RSS. Two
earlier runs matched within about 1 ms. A 1 ms-sleep Windows client measured about
31 ms admission (Windows timer granularity); the trace now polls continuously.
Finding recorded in ADR-0089: genome v1 and metabolism rates are per tick, so the
quantum fixes biological rates; changing it needs a versioned rules migration (M11.1).
Executed checks: Windows MSVC network preset 1/1 (twice, after each change); Linux GCC 14
network tests and evo-dev-session build; Clang ASan/UBSan network tests; clang-tidy on
the session client, evo-dev-session and network_session tests; format check.
Not covered: emulated RTT/loss, multiple clients, the reference worker and low-spec VM,
movement/prediction; the targets are therefore not yet qualified (10.9).
+3 -1
View File
@@ -95,5 +95,7 @@ re-encoding; dev grant environment refusal, bit-flip tag failures and key misuse
admission scope/lifetime/reuse/duplicate/capacity rules and every intent status;
TLS 1.3 loopback with suite/version checks, 100 kB transfer, close_notify,
untrusted CA, wrong name, mismatched key, record tampering, transport failure and
plaintext rejection. `evo-dev-session-fuzz` is the libFuzzer target
plaintext rejection. `evo-dev-session trace` (M10.1) measures admission and durable round trips, view cadence
and bytes against a running region (`tools/network/session-trace.sh`,
[M10_TIMING_TRACES](M10_TIMING_TRACES.md)). `evo-dev-session-fuzz` is the libFuzzer target
(`EVO_BUILD_FUZZER`, Linux Clang). Results: engineering/VALIDATION.md.
+47
View File
@@ -0,0 +1,47 @@
# M10.1 timing traces
Supports [ADR-0089](../adr/0089-m10-timing-and-budgets.md). These are development-reference
measurements of the M9 dev session path, not qualification on the reference hardware.
## Method
`tools/network/session-trace.sh <out-dir>` (Linux/WSL2, PostgreSQL prepared) provisions
the development-v1 region (world 100, region 1, frame 9) in a throwaway database, runs
`evo-server` (lineage profile, 50 ms quantum, 1 s flush, synthetic inputs, dev sessions,
ops metrics) and `evo-dev-session trace` at 250, 100 and 1000 ms intention intervals,
then waits for a client on another host (here Windows to WSL2). The trace client polls
continuously, sends one intention per interval after a fresh baseline, and records on
its monotonic clock: send to IntentResult (admission round trip), send to IntentOutcome
(durable), outcome tick minus the view tick at send, view inter-arrival and bytes.
Percentiles are nearest-rank. A run fails on any loss, rejection or reconnect.
Hardware: AMD Ryzen 7 9800X3D (8 cores/16 threads), 61.6 GB, Windows 11 Pro; server in
WSL2 (kernel 5.15.167.4, 16 vCPU, 30.1 GiB visible); one region, one client at a time,
no emulated loss or delay.
## Results (2026-10-03, committed script)
| Run | Intents | Admission ms p50/p95/p99/max | Durable ms p50/p95/max | Outcome lead (ticks) | View interval ms p50/p99/max |
|---|---|---|---|---|---|
| Linux loopback, 250 ms | 120 | 0.9 / 1.9 / 2.1 / 2.1 | 943 / 1398 / 1446 | 9 | 50.1 / 59.9 / 63.1 |
| Linux loopback, 100 ms | 200 | 1.1 / 2.1 / 4.2 / 4.9 | 953 / 1405 / 1455 | 9 | 50.1 / 59.5 / 60.6 |
| Linux loopback, 1000 ms | 30 | 1.0 / 4.8 / 5.2 / 5.2 | 1057 / 1406 / 1455 | 9 | 50.1 / 57.9 / 60.4 |
| Windows -> WSL2, 250 ms | 120 | 1.4 / 2.1 / 2.3 / 2.5 | 917 / 1368 / 1418 | 9 | 50.1 / 59.4 / 60.7 |
Every view was 267 bytes (one habitat); about 7.3-7.9 KB/s received including
heartbeats and results. Server: tick debt maximum 0, about 1 % CPU, at most 10.5 MB RSS.
Two earlier runs with the same build gave the same distributions within about 1 ms.
## Interpretation
- Durable latency = the carrier delay (about 9 ticks, 450 ms) plus waiting for the next
1 s commit flush, plus a small commit cost: observed 0.45-1.46 s. Meeting p95 <= 1.5 s
leaves little margin under load; 10.9 must measure commit cost with 20+ clients.
- The 9-tick outcome lead is the M9 synthetic-carrier path (ADR-0083), not M10 admission.
- Admission round trips are bounded by the server loop's 2 ms sleep, not the network.
- Measurement pitfall: with a 1 ms sleep per poll, the Windows client measured about
31 ms admission and 47 ms median view interval, because Windows sleeps in about
15.6 ms timer ticks. The trace polls continuously; frame-paced clients add their own
frame period to perceived latency, which 10.6 must budget.
## Not covered
Emulated RTT/loss (needs netem or a lossy relay; 10.2/10.9), multiple clients, the
reference worker and low-spec VM, real movement and prediction, larger views.
+8
View File
@@ -50,6 +50,13 @@ struct ClientEvent {
IntentOutcome outcome{};
std::uint64_t sequence{};
};
// Received-frame counters for timing and bandwidth experiments (M10.1); bytes include
// the frame header. Monotonic for the client's lifetime, across reconnects.
struct ClientTraffic {
std::uint64_t frames{}, bytes{};
std::uint64_t environment_views{}, environment_view_bytes{};
std::uint64_t organism_views{}, organism_view_bytes{};
};
enum class SessionClientError : std::uint8_t { configuration };
class SessionClient {
public:
@@ -73,6 +80,7 @@ class SessionClient {
// Attempts that failed before any session event (TCP connect or TLS handshake), so a
// caller can bound "unreachable" without an event per retry. Never reset.
[[nodiscard]] std::uint64_t unreachable_attempts() const noexcept;
[[nodiscard]] ClientTraffic traffic() const noexcept;
// Drains at most max_events and resumes reconnect after local backpressure.
[[nodiscard]] std::vector<ClientEvent> take_events();
+42
View File
@@ -0,0 +1,42 @@
# M10 timing and workload budgets, version 1
Normative table for ADR-0089. "Ratified" values were decided by the maintainer
(2026-10-03); "budget" values are engineering limits derived from them and from the
M10.1 traces and change only with measurements and an ADR-0089 amendment. Version 1
applies to all M10 segments; a change bumps the version and lists affected tests.
None of these values is a biological or game rule. Exception to note: genome v1 and
metabolism express rates per tick, so the tick quantum currently fixes biological rates
in real time; changing it requires a versioned rules migration (ADR-0089).
| Item | Value | Kind | Enforced/tested in |
|---|---|---|---|
| Authoritative tick quantum | 50,000 us (20 Hz) | ratified | checkpoints (`tick_microseconds`), region host |
| Commit flush | 1,000 ms | ratified | region host `flush_interval` |
| Final outcome delivery | p95 <= 1.5 s after admission (dev/stage, nominal network) | ratified | 10.4, 10.9 |
| Responsiveness (input -> first reflecting snapshot) | LAN p95 <= 150 ms; 100 ms RTT p95 <= 250 ms | ratified | 10.6, 10.9 |
| Reference hardware | server: one RKE2 worker (8 vCPU, 31.3 GiB) per region host; client: low-spec VM (M9.8g) | ratified | 10.9 |
| Input scheduling window | server_tick + 1 ..= server_tick + 8 ticks | budget | 10.4 admission |
| Client input lead | ceil((rtt/2 + jitter)/50 ms) + 1, clamped 2..8 ticks | budget | 10.4, 10.6 |
| Late input | rejected, never rewound | budget | 10.4 |
| Snapshot cadence (in interest) | every tick | budget | 10.5 |
| Baselines retained | server <= 4 per session, each <= 40 ticks old; client <= 2 | budget | 10.5 |
| Intention sequence | u64 per session, from 1, strictly increasing, no wrap | budget | 10.4 |
| Tick, baseline id | u64, no wrap | budget | 10.4, 10.5 |
| Realtime packet sequence | serial-number arithmetic >= 16 bits, window < half space | budget | 10.2 |
| Session id / epoch | u64 server-assigned, bound to connection; epoch on every message; stale closes | budget | 10.3, 10.4 |
| Intentions per session | 1 per tick (8 per 8-tick window, every attempt counted) | budget | 10.4 |
| Unresolved intentions per session | 256 | budget | 10.4 |
| Realtime datagram payload | <= 1,200 bytes | budget | 10.2 |
| Reliable frame | <= 64 KiB | budget | 10.2 |
| Replication per session | <= 16 KiB per tick | budget | 10.5 |
| Client event queue | 1,024 events | budget | client session |
| Heartbeat / liveness / handshake | 1 s / 5 s / 5 s | budget | 10.2, 10.7 |
| Sessions per region | >= 20 required, 32 default | budget | 10.9 |
| Per-tick region work | p99 <= 25 ms on the reference worker | budget | 10.9 |
| Session handling | <= 0.5 ms per session per tick | budget | 10.9 |
| Host input queue | 64 inputs, 64 KiB | budget | region host |
| Overload response | shed interest, refuse new sessions before tick debt | budget | 10.9 |
Determinism: authoritative state is exact given the checkpoint and committed per-tick
inputs; timing, delivery, prediction, interpolation and presentation are tolerant
(ADR-0089).
+11
View File
@@ -17,6 +17,7 @@ struct SessionClient::Impl {
SessionClientConfig config;
std::size_t next_grant{};
std::uint64_t unreachable{};
ClientTraffic traffic;
SessionPhase phase{SessionPhase::backoff};
Step step{Step::handshake};
Clock::time_point retry_at{}, deadline{}, last_received{}, last_sent{}, polled_at{};
@@ -100,6 +101,9 @@ struct SessionClient::Impl {
}
const FrameView v{f.type, f.payload};
last_received = now;
const auto bytes = frame_header_bytes + f.payload.size();
++traffic.frames;
traffic.bytes += bytes;
if (step == Step::awaiting_welcome) {
if (f.type == MessageType::close) {
const auto reason = decode_close(v);
@@ -135,6 +139,8 @@ struct SessionClient::Impl {
return false;
}
view = d->first;
++traffic.environment_views;
traffic.environment_view_bytes += bytes;
return true;
}
case MessageType::organism_view: {
@@ -144,6 +150,8 @@ struct SessionClient::Impl {
disconnect(now, std::nullopt);
return false;
}
++traffic.organism_views;
traffic.organism_view_bytes += bytes;
return true;
}
case MessageType::intent_result: {
@@ -327,6 +335,9 @@ std::optional<Welcome> SessionClient::welcome() const noexcept {
std::optional<ViewHeader> SessionClient::latest_view() const noexcept {
return impl_->view;
}
ClientTraffic SessionClient::traffic() const noexcept {
return impl_->traffic;
}
std::uint64_t SessionClient::unreachable_attempts() const noexcept {
return impl_->unreachable;
}
+9
View File
@@ -187,6 +187,15 @@ void connect_view_intents_and_outcomes() {
h.tick();
CHECK(h.until([&] { return must(c->latest_view()).server_tick == 102; }));
CHECK(c->environment().current()->cells()[0].quantity[0] == 102);
// M10.1 traffic counters: every received frame counted with its header.
const auto traffic = c->traffic();
CHECK(traffic.environment_views == 2 && traffic.organism_views >= 1 &&
traffic.environment_view_bytes > 2 * frame_header_bytes &&
traffic.frames >= 1 + traffic.environment_views + traffic.organism_views &&
traffic.bytes >=
traffic.environment_view_bytes + traffic.organism_view_bytes +
(traffic.frames - traffic.environment_views - traffic.organism_views) *
frame_header_bytes);
// Admitted intention: carried by a host input, then durably committed.
CHECK(c->send({1, 0, 1000, 0}));
+82
View File
@@ -0,0 +1,82 @@
#!/usr/bin/env bash
# M10.1 session timing traces (ADR-0089) on one Linux/WSL2 host, no cluster access.
#
# tools/network/session-trace.sh <out-dir> [build-dir]
#
# build-dir (default build/m97-postgres) must be configured with EVO_BUILD_POSTGRES=ON and
# EVO_BUILD_NETWORK=ON; .cache/postgres/install comes from tools/prepare-postgres.sh.
# Creates a throwaway PostgreSQL cluster and objects directory under /tmp, provisions
# the development-v1 region (world 100, region 1, frame 9), runs evo-server with
# synthetic inputs, dev sessions (0.0.0.0:17401) and ops (127.0.0.1:19101), then
# `evo-dev-session trace` at 250/100/1000 ms intervals over loopback. It then writes
# <out-dir>/server-up and waits up to 10 min for <out-dir>/client-done, so a client on
# another host (e.g. Windows -> WSL2 at <out-dir>/wsl-ip.txt) can trace with
# grants-24.bin. Server CPU/RSS is sampled each second; /metrics is captured.
# Development credentials and grants are created fresh in <out-dir>; never reuse them.
set -euo pipefail
[ $# -ge 1 ] || { echo "usage: $0 <out-dir> [build-dir]" >&2; exit 2; }
root="$(cd "$(dirname "$0")/../.." && pwd)"
out="$1"
build="${2:-$root/build/m97-postgres}"
say() { echo "$(date -u +%H:%M:%S) $*"; }
rm -rf "$out"; mkdir -p "$out"; out="$(cd "$out" && pwd)"
cmake --build "$build" --target evo-server evo-dev-session evo-world-clone --parallel 6 > "$out/build.log" 2>&1 ||
{ say "build failed (see $out/build.log)"; exit 1; }
prefix="$root/.cache/postgres/install"
export PATH="$prefix/bin:$PATH" LD_LIBRARY_PATH="$prefix/lib"
db="$(mktemp -d /tmp/evo-trace.XXXXXXXX)"; chmod 700 "$db"
export PGHOST="$db" PGPORT=55434 PGDATABASE=postgres PGUSER="$(id -un)"
unset PGHOSTADDR PGPASSWORD PGSERVICE PGSERVICEFILE
initdb -D "$db/data" --no-locale --encoding=UTF8 --auth-local=trust --auth-host=reject > /dev/null
pg_ctl -D "$db/data" -l "$db/server.log" -o "-k $db -p 55434 -c listen_addresses=''" -w start > /dev/null
cleanup() {
kill -TERM $(jobs -p) 2> /dev/null || true; sleep 2; kill -9 $(jobs -p) 2> /dev/null || true
pg_ctl -D "$db/data" -m immediate stop > /dev/null 2>&1 || true; rm -rf "$db"
}
trap cleanup EXIT
psql -X -q -c 'CREATE ROLE evo_runtime_test NOLOGIN' -c 'CREATE ROLE evo_runtime_login LOGIN IN ROLE evo_runtime_test'
EVO_PG_RUNTIME_ROLE=evo_runtime_test bash "$root/tools/migrate-postgres.sh" > /dev/null
identity=b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1
mkdir -p "$db/objects"; chmod 700 "$db/objects"
"$build/evo-world-clone" provision --world 100 --region 1 --opening development-v1 \
--pg-host "$db" --pg-port 55434 --pg-database postgres --pg-user "$PGUSER" \
--objects "$db/objects" --build "$identity" --retain-build true > "$out/provision.log" 2>&1
"$build/evo-dev-session" credentials --environment dev --server-name dev-region.evolution.test \
--out "$out/creds" > /dev/null
for subject in 21 22 23 24; do
"$build/evo-dev-session" grants --environment dev --key "$out/creds/grant.key" --world 100 --frame 9 \
--region 1 --subject "$subject" --count 2 --out "$out/grants-$subject.bin" > /dev/null
done
"$build/evo-server" --profile lineage --world 100 --region 1 --frame 9 --pg-host "$db" --pg-port 55434 \
--pg-database postgres --pg-user evo_runtime_login --objects "$db/objects" --build "$identity" \
--lease-profile fast --flush-ms 1000 --synthetic-inputs development-v1 \
--session-listen 0.0.0.0:17401 --session-cert "$out/creds/server.pem" \
--session-key "$out/creds/server.key" --session-grant-key "$out/creds/grant.key" \
--session-grant-ledger "$db/objects/dev-session-grants.v1" --session-environment dev \
--ops-listen 127.0.0.1:19101 > "$out/server.log" 2>&1 &
pid=$!
for _ in $(seq 1 300); do grep -q "^ready 1" "$out/server.log" && break; sleep 0.1; done
grep -q "^ready 1" "$out/server.log" || { say "server not ready"; cat "$out/server.log"; exit 1; }
say "server ready"
( while kill -0 "$pid" 2> /dev/null; do
echo "$(date +%s.%N) $(ps -o %cpu=,rss= -p "$pid" 2> /dev/null)"; sleep 1
done ) > "$out/cpu.log" &
{ lscpu | grep -E "Model name|^CPU\(s\)"; free -m | head -2; uname -r; } > "$out/hardware.txt"
run() { # name subject intents interval-ms
local status=0
"$build/evo-dev-session" trace --connect 127.0.0.1:17401 --server-name dev-region.evolution.test \
--ca "$out/creds/dev-ca.pem" --grants "$out/grants-$2.bin" --intents "$3" --interval-ms "$4" \
--out "$out/$1.csv" --timeout 300 > "$out/$1.txt" 2>&1 || status=$?
say "$1 exit=$status"
}
run linux-250ms 21 120 250
run linux-100ms 22 200 100
run linux-1000ms 23 30 1000
curl -s http://127.0.0.1:19101/metrics > "$out/metrics-after-linux.txt" || true
ip -4 addr show eth0 2> /dev/null | awk '/inet /{print $2}' | cut -d/ -f1 > "$out/wsl-ip.txt" || true
touch "$out/server-up"
say "waiting up to 10 min for $out/client-done"
for _ in $(seq 1 3000); do [ -f "$out/client-done" ] && break; sleep 0.2; done
curl -s http://127.0.0.1:19101/metrics > "$out/metrics-end.txt" || true
kill -TERM "$pid"; for _ in $(seq 1 150); do kill -0 "$pid" 2> /dev/null || break; sleep 0.1; done
say "done"