From 819137c1dffdd73e60251e67fc7b7d63d6e800f6 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 3 Oct 2026 12:29:58 -0400 Subject: [PATCH] Ratify M10.1 timing and workload budgets with session traces 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 --- apps/evo-dev-session/main.cpp | 215 +++++++++++++++++++++- docs/ROADMAP.md | 4 + docs/STATUS.md | 13 +- docs/adr/0089-m10-timing-and-budgets.md | 99 ++++++++++ docs/adr/README.md | 1 + docs/architecture/NETWORK_ARCHITECTURE.md | 3 +- docs/architecture/OPEN_QUESTIONS.md | 2 +- docs/engineering/VALIDATION.md | 29 +++ docs/networking/DEV_SESSION_PROTOCOL.md | 4 +- docs/networking/M10_TIMING_TRACES.md | 47 +++++ include/evo/network/session_client.hpp | 8 + schemas/network/m10-budgets-v1.md | 42 +++++ src/network/session/client.cpp | 11 ++ tests/network_session.cpp | 9 + tools/network/session-trace.sh | 82 +++++++++ 15 files changed, 557 insertions(+), 12 deletions(-) create mode 100644 docs/adr/0089-m10-timing-and-budgets.md create mode 100644 docs/networking/M10_TIMING_TRACES.md create mode 100644 schemas/network/m10-budgets-v1.md create mode 100644 tools/network/session-trace.sh diff --git a/apps/evo-dev-session/main.cpp b/apps/evo-dev-session/main.cpp index 7321b13..f0e6839 100644 --- a/apps/evo-dev-session/main.cpp +++ b/apps/evo-dev-session/main.cpp @@ -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 #include #include +#include #include #include #include @@ -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 v, double p) { + std::sort(v.begin(), v.end()); + const auto rank = + static_cast(std::ceil(p / 100.0 * static_cast(v.size()))); + return v[std::clamp(rank, 1, v.size()) - 1]; +} +void report(const char* name, const std::vector& 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(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(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(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 samples; + std::vector view_at; + std::vector view_tick; + std::vector view_bytes; + std::optional last_tick; + ClientTraffic seen{}; + std::uint64_t sequence = 0, resolved = 0; + std::optional 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(e.result.status); + if (e.result.status != IntentStatus::admitted) { + ++resolved; + std::printf("trace rejected sequence=%llu status=%u\n", + static_cast(e.sequence), + static_cast(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(traffic.environment_view_bytes - + seen.environment_view_bytes) / + static_cast(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(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 admission, durable, lead, intervals; + std::uint64_t admitted = 0, durable_count = 0; + for (const auto& s : samples) { + if (s.status == static_cast(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(s.outcome_tick) - + static_cast(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(admitted), + static_cast(durable_count), + static_cast(*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( + view_tick.empty() ? 0 : view_tick.back() - view_tick.front()), + seconds, static_cast(total.bytes) / seconds, + static_cast(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(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; } diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 1aeb9af..8159047 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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 diff --git a/docs/STATUS.md b/docs/STATUS.md index 02b7d08..e7c4b36 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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 diff --git a/docs/adr/0089-m10-timing-and-budgets.md b/docs/adr/0089-m10-timing-and-budgets.md new file mode 100644 index 0000000..f9cbd94 --- /dev/null +++ b/docs/adr/0089-m10-timing-and-budgets.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index d6f2706..9c06d4a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/architecture/NETWORK_ARCHITECTURE.md b/docs/architecture/NETWORK_ARCHITECTURE.md index aaa45e3..1d99078 100644 --- a/docs/architecture/NETWORK_ARCHITECTURE.md +++ b/docs/architecture/NETWORK_ARCHITECTURE.md @@ -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. diff --git a/docs/architecture/OPEN_QUESTIONS.md b/docs/architecture/OPEN_QUESTIONS.md index f495d93..b77e8fc 100644 --- a/docs/architecture/OPEN_QUESTIONS.md +++ b/docs/architecture/OPEN_QUESTIONS.md @@ -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 | diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 7dbe69a..8335eb4 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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). diff --git a/docs/networking/DEV_SESSION_PROTOCOL.md b/docs/networking/DEV_SESSION_PROTOCOL.md index 9fb90da..83fa6d0 100644 --- a/docs/networking/DEV_SESSION_PROTOCOL.md +++ b/docs/networking/DEV_SESSION_PROTOCOL.md @@ -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. diff --git a/docs/networking/M10_TIMING_TRACES.md b/docs/networking/M10_TIMING_TRACES.md new file mode 100644 index 0000000..2b6ab66 --- /dev/null +++ b/docs/networking/M10_TIMING_TRACES.md @@ -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 ` (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. diff --git a/include/evo/network/session_client.hpp b/include/evo/network/session_client.hpp index 2b54a3d..bf19f04 100644 --- a/include/evo/network/session_client.hpp +++ b/include/evo/network/session_client.hpp @@ -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 take_events(); diff --git a/schemas/network/m10-budgets-v1.md b/schemas/network/m10-budgets-v1.md new file mode 100644 index 0000000..de84c17 --- /dev/null +++ b/schemas/network/m10-budgets-v1.md @@ -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). diff --git a/src/network/session/client.cpp b/src/network/session/client.cpp index f82ad6b..656e361 100644 --- a/src/network/session/client.cpp +++ b/src/network/session/client.cpp @@ -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 SessionClient::welcome() const noexcept { std::optional 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; } diff --git a/tests/network_session.cpp b/tests/network_session.cpp index 48286fc..7c4f091 100644 --- a/tests/network_session.cpp +++ b/tests/network_session.cpp @@ -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})); diff --git a/tools/network/session-trace.sh b/tools/network/session-trace.sh new file mode 100644 index 0000000..f45f4ff --- /dev/null +++ b/tools/network/session-trace.sh @@ -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 [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 +# /server-up and waits up to 10 min for /client-done, so a client on +# another host (e.g. Windows -> WSL2 at /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 ; never reuse them. +set -euo pipefail +[ $# -ge 1 ] || { echo "usage: $0 [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"