Files
aevolution/docs/adr/0021-ecs-evaluation.md
T

3.4 KiB

ADR-0021: Isolated EnTT comparison

Status

Accepted for M1.5 measurement only. No production ECS adoption or public API change.

Context

ADR-0005 requires evidence before the bounded sorted-row proof becomes a general ECS. We need sparse multi-component queries and structural churn measurements, including deterministic export cost rather than raw iteration alone.

Decision

Compare a sorted composed-row adapter with EnTT 4.0.0 in an opt-in experiment. Use EnTT commit 85c6bba014049b5de8fad49d25424df2f1f6a8c1, single header SHA256 eedcb83fedffe640334ef69a0647625a186cf1daeb333b21b0a1445f01e89b6c and MIT license SHA256 73547f6370ee16ea560665329bb62d4e2d8250f41eaa204b47a6c694ca3286ea. An explicit preparation command downloads/validates both; configuration is offline and rejects a mismatched header. Default builds do not use EnTT.

The experiment owns adapters and monotonic external IDs. EnTT handles never enter simulation contracts or snapshots. Use a tracking memory resource for container allocation requests; report its scope and limitations. Compare canonical bytes and independent closed-form counter results before accepting timing samples. See protocol.

Alternatives Considered

Flecs is a maintained MIT C/C++ candidate with relationships and scheduling. Those features exceed this first storage/query experiment and would confound a small adoption comparison. It remains an alternative if EnTT's adapter cost or query model fails later needs; no performance ranking against Flecs is claimed. Writing an internal sparse-set framework now would prejudge the experiment.

Benefits

EnTT is C++-native, header-only, and documents views, lifetime and allocator support. Its July 2026 release supplies current maintenance evidence. The experimental adapter can be removed without migrating game state.

Costs

Template compile time, larger experimental executable, an explicit network preparation step and retained MIT attribution. This single-header experiment does not select a general package manager; ADR-0003's compiled-dependency gate still applies. Only the benchmark includes the dependency.

Risks

Independent updates understate deterministic ordering cost for interacting organisms. Small synthetic components may misrepresent real genome/phenotype layouts. Allocator counts exclude process RSS, stack, allocator bookkeeping and snapshot scratch buffers. Seven samples on a shared host are descriptive, not statistical capacity promises. EnTT's native handle reuse is not persistent ID reuse; the adapter must enforce the distinction.

Consequences

Run release correctness checks, sanitizers and both supported compiler families. Record raw samples, toolchain, binary/build observations, canonical equivalence and limitations. Make no production adoption from one fast loop. Foundation maintainers own updates/removal; keep third-party warnings outside owned code. MIT notices remain in the prepared dependency directory and any redistributed experimental binary's accompanying materials. No known-vulnerability absence is asserted merely from version selection.

Sources: EnTT release, pinned source, ECS contracts, Flecs.