Files
aevolution/docs/adr/0089-m10-timing-and-budgets.md
2026-10-08 12:08:53 -04:00

7.1 KiB

[Reviewed]

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"). Biological rate representation was separately ratified on 2026-10-04: rates will be time-based and converted deterministically at the simulation tick boundary. M11.1 owns the versioned migration and precision contract.

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; normative table: m10-budgets-v1.

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 the biological rates. The maintainer ratified the direction on 2026-10-04: M11.1 expresses rates per unit time and converts them deterministically at each fixed simulation tick. Existing per-tick genome and checkpoint data require a versioned migration. M11.1 must define unit scales, fixed-point precision, remainder/rounding behavior, overflow bounds, and regression evidence that the 50 ms behavior is preserved within the declared error budget. No existing biological rate is silently rescaled.

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.