71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
|
# ADR-0002: Game-state kernel — survey approval and implementation decision
|
|||
|
|
|
|||
|
|
Date: 2026-07-31
|
|||
|
|
Status: accepted
|
|||
|
|
Capability: game.kernel.authoritative-state
|
|||
|
|
Inputs: research/CB-RES-0001-game-kernel.md (approved),
|
|||
|
|
history/260731-game-kernel-{research,challenge,response}.md
|
|||
|
|
|
|||
|
|
## Approval (InnerLoop step 2)
|
|||
|
|
|
|||
|
|
The CB-RES-0001 survey is **approved**. It passed one round of adversarial
|
|||
|
|
review: the challenge found one blocking overclaim (degradation
|
|||
|
|
attribution) and three significant gaps (memory methodology, omitted
|
|||
|
|
candidates OpenSpiel/Ludii, unsourced D3 ceiling); all were resolved with
|
|||
|
|
new measurements or corrections, none overturned the comparative
|
|||
|
|
conclusions. The candidate set is judged adequate; the baselines are
|
|||
|
|
trustworthy within their stated provenance (measured vs cited vs
|
|||
|
|
estimated), with the event-sourcing ceiling explicitly parity-capped.
|
|||
|
|
|
|||
|
|
**Benchmark-to-beat, named:** boardgame.io 0.50.2 per the survey's
|
|||
|
|
baseline table (throughput ~1,100–1,900 moves/s degrading with history in
|
|||
|
|
every configuration; 120 deps/37 MB; ~36-LOC declarative game definition),
|
|||
|
|
plus the **stipulated engineering target** of ≥100,000 applied events/s
|
|||
|
|
with flat scaling (@100k within 10% of @5k) and bit-identical replay.
|
|||
|
|
|
|||
|
|
## Decision (InnerLoop step 3): reimplement, assimilating patterns
|
|||
|
|
|
|||
|
|
Build the Clay-Borg semantic kernel as **our own Rust implementation**
|
|||
|
|
(`cb-kernel` + `cb-events` + `cb-game-runtime`) — not a wrapper around any
|
|||
|
|
surveyed system. Per the Clay-Borg rule, we own the semantics; what we
|
|||
|
|
assimilate from the field is *patterns*, each with a named source:
|
|||
|
|
|
|||
|
|
| Assimilated pattern | From | Into |
|
|||
|
|
|---|---|---|
|
|||
|
|
| Declarative game definition (setup/moves/phases as data + pure functions) | boardgame.io | game-package rules API |
|
|||
|
|
| Tooling-enforced determinism (not convention) | Rune | seeded RNG service, denied ambient time/random, replay double-run check in the scenario runner |
|
|||
|
|
| Command → validate → events → fold, snapshots bound replay | event-sourcing (cqrs-es pattern) | kernel mutation pipeline |
|
|||
|
|
| Information-state framing for imperfect information | OpenSpiel | per-player projection model |
|
|||
|
|
| Hand-zone / object-visibility semantics | TTS (pattern only) | tabletop layer, later |
|
|||
|
|
|
|||
|
|
Rejected alternatives: **assimilate boardgame.io** (inactive, JS-bound,
|
|||
|
|
history-degrading in best config — fails D2/D3/D4); **build on OpenSpiel**
|
|||
|
|
(right semantics, wrong layer — research kernel without projection/
|
|||
|
|
networking/snapshot surface, heavyweight C++/Python boundary); **ECS as
|
|||
|
|
kernel** (bevy_ecs stays in the world layer per the blueprint).
|
|||
|
|
|
|||
|
|
## Expected advantage per dimension (honest trades)
|
|||
|
|
|
|||
|
|
- **D3 speed: better.** Flat per-event cost with snapshots; the 100k/s
|
|||
|
|
floor. Declared caveat: part of the margin over boardgame.io is language
|
|||
|
|
choice; the commitment that matters is flat scaling, and the
|
|||
|
|
event-sourcing comparison stays at parity until a Rust comparator is
|
|||
|
|
measured.
|
|||
|
|
- **D2 weight: better.** Target ≤20 transitive crates for the headless
|
|||
|
|
kernel (vs 120 npm packages), measured by M-D2-DEP/M-D2-LOC/M-D2-BLD.
|
|||
|
|
- **D1 specification: parity, aiming better.** Match boardgame.io's
|
|||
|
|
declarative compactness on the synthetic workload (≤~40 LOC equivalent);
|
|||
|
|
surpass via rule-to-scenario traceability (M-D1-COV), which no candidate
|
|||
|
|
has. Declared trade: we do not attempt Ludii/GDL-class generality — one
|
|||
|
|
game family first, canon only after a second concrete use.
|
|||
|
|
- **D4 optionality: better.** Port pattern with null/reference impls from
|
|||
|
|
day one, capability boundary WIT-expressible later, zero foreign types in
|
|||
|
|
canonical interfaces (M-D4-LEAK=0). No surveyed candidate offers this.
|
|||
|
|
|
|||
|
|
## Gate
|
|||
|
|
|
|||
|
|
Per InnerLoop, no kernel implementation code existed before this ADR.
|
|||
|
|
Next steps: T05 (GROUND rules spec, derived from ground-game), T06 (kernel
|
|||
|
|
spec with acceptance metrics tied to these baselines), T07 (workspace +
|
|||
|
|
harness), T08 (code loop).
|