From 327bda64ab827fdf4a82dacf91abb2f48eb001cc Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 1 Aug 2026 12:47:16 +0200 Subject: [PATCH] CB-WP-0006 T07: implement K18, amend K14 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two rules, two different answers, which is the point of a task phrased "implement, or amend and say why". K18 is implemented. "Criterion benches driving the same scenario format at scale" was false — the bench hardcoded its commands and never touched ScenarioFile, while MetricsAndScenarios §3 pointed at a benchmarks/ directory containing only baselines/. benchmarks/synthetic-3p.yaml now holds the workload and both the bench and bench_shape read it: the workload is data, not code. A second defect surfaced while fixing the first. After the bench switched to the file, bench_shape still hardcoded the same sequence, so the workload existed twice — deleting end_round from the YAML broke bench-test while bench_shape kept passing. Duplicated-fact drift in executable form. Both now read the same include_str! and deleting a command breaks both. Explicitly not claimed: this does not unblock AM-3. AM-3's baseline is a declarative game object — moves, turn order, rules. synthetic-3p.yaml is a command list; the rules live in games/ground. Marking it as AM-3's subject would compare a script to a game definition, which is the category error AM-3 is blocked on. The file says so in its own header, where the next person will be tempted. K14 is amended. CommitWindow had zero non-test users and GROUND enforces the same contract inline. Wiring GROUND through it was rejected: it would change the serialized shape of `selections`, which four scenario files assert by dot-path and every state hash depends on, for the sole benefit of making a sentence literally true. The deciding argument is INTENT's, not convenience: abstractions are extracted from working games rather than invented in isolation, and no concept becomes canonical until it survives a second concrete use. CommitWindow was invented before any game needed it and has survived none. Imposing it on GROUND would manufacture the first use rather than discover it. So K14 states what is actually guaranteed, CommitWindow is marked provisional in the source, and it carries a delete-by date of 2026-12-31. Kernel spec->code link 16/18 -> 18/18, stated with the caveat the gate prints every run: that is about names, not assertions. Two self-tests broke and both broke correctly. rule-coverage's gate test hardcoded "unlinked rules exist today" and failed when the last one was linked; it now computes that and asserts the gate fails iff rules are unlinked. facts' text check rejected k_unlinked once it became legitimately empty; empty now renders as "(none)" and the check distinguishes absent from empty. M-D1-MUT: 8 of 14, unchanged — K14 and K18 are kernel rules, not acceptance rows. Co-Authored-By: Claude Opus 5 --- benchmarks/synthetic-3p.yaml | 46 ++++++++++ crates/cb-game-runtime/src/lib.rs | 11 +++ facts.toml | 8 +- games/ground/benches/synthetic.rs | 84 +++++++----------- games/ground/src/lib.rs | 51 +++-------- history/260801-cb-wp-0006-log.md | 77 ++++++++++++++++ specs/GameKernel.md | 49 +++++++++- specs/MetricsAndScenarios.md | 9 +- .../__pycache__/rule-coverage.cpython-312.pyc | Bin 18261 -> 18880 bytes tools/facts.py | 9 +- tools/rule-coverage.py | 17 +++- 11 files changed, 256 insertions(+), 105 deletions(-) create mode 100644 benchmarks/synthetic-3p.yaml diff --git a/benchmarks/synthetic-3p.yaml b/benchmarks/synthetic-3p.yaml new file mode 100644 index 0000000..3a7d9d5 --- /dev/null +++ b/benchmarks/synthetic-3p.yaml @@ -0,0 +1,46 @@ +# K18: the benchmark workload, expressed in the scenario format. +# +# Until CB-WP-0006 T07 the bench hardcoded this command sequence in Rust +# and never touched `ScenarioFile`, so K18 — "Criterion benches driving +# the same scenario format at scale" — was false, and +# MetricsAndScenarios §3's "benchmarks live in benchmarks/" pointed at a +# directory containing only `baselines/`. +# +# Mirrors the CB-RES-0001 harness shape: 3 players, commit/reveal round. +# The bench replays these commands per round at scale; `bench_shape` in +# the aggregate crate pins the resulting 7 commands / 13 events, so a +# change here that alters the shape breaks a test rather than silently +# rescaling AM-6 and AM-7. +# +# NOT an AM-3 subject. AM-3's baseline is a declarative *game object* +# (~36 LOC, boardgame.io) — moves, turn order, rules. This is a command +# list; the rules live in games/ground (1,575 lines). Marking this file +# as AM-3 would compare a script to a game definition, which is the +# category error AM-3 is currently blocked on. +scenario: ground/bench-synthetic-3p +description: One 3-player GROUND round, replayed at scale by the Criterion bench. +covers: [] +seed: 42 +setup: + players: 3 + preset: standard-3p +commands: + - actor: P1 + cmd: select_action + args: { action: ATTACK, target: P2 } + - actor: P3 + cmd: select_action + args: { action: SUPPORT, target: P2 } + - actor: P2 + cmd: select_action + args: { action: GROUND } + - actor: SYSTEM + cmd: reveal + - actor: P2 + cmd: choose_ground_mode + args: { mode: GR } + - actor: SYSTEM + cmd: resolve + - actor: SYSTEM + cmd: end_round +expect: {} diff --git a/crates/cb-game-runtime/src/lib.rs b/crates/cb-game-runtime/src/lib.rs index 54dc504..45b5f67 100644 --- a/crates/cb-game-runtime/src/lib.rs +++ b/crates/cb-game-runtime/src/lib.rs @@ -18,6 +18,17 @@ use std::collections::BTreeMap; /// A simultaneous commit window (GameKernel K12): the runtime opens it /// naming who must submit; submissions are commitment events hidden from /// projections until reveal. +/// +/// **PROVISIONAL — zero non-test users as of 2026-08-01 (K14, GameKernel +/// §2.5a).** GROUND implements the same contract inline in its own +/// aggregate. This type is the *extracted* form, kept because it +/// documents the seam stage 3 and stage 4 will need — but INTENT says a +/// concept becomes canonical only *"after surviving a second concrete +/// use"*, and this has survived none. +/// +/// **Delete it if no second game uses it by 2026-12-31.** A primitive +/// with one hypothetical user and a test that exercises only itself is +/// the AM-11 shape, and this project has paid for that shape twice. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct CommitWindow { /// Players who must submit, and their commitment once received. diff --git a/facts.toml b/facts.toml index ab9e8da..c0c384b 100644 --- a/facts.toml +++ b/facts.toml @@ -70,8 +70,8 @@ fmt = "{:,}" by = "tools/rule-coverage.py" [k_linked] -value = 16 -text = "16" +value = 18 +text = "18" fmt = "{:,}" by = "tools/rule-coverage.py" @@ -82,8 +82,8 @@ fmt = "{:,}" by = "tools/rule-coverage.py" [k_unlinked] -value = 'K14 K18' -text = "K14 K18" +value = '(none)' +text = "(none)" fmt = "{}" by = "tools/rule-coverage.py" diff --git a/games/ground/benches/synthetic.rs b/games/ground/benches/synthetic.rs index b20a903..b396a50 100644 --- a/games/ground/benches/synthetic.rs +++ b/games/ground/benches/synthetic.rs @@ -9,7 +9,7 @@ //! what matters is the shape of the curve, not only the peak number. use cb_events::state_hash_hex; -use cb_game_runtime::{ScenarioGame, Setup}; +use cb_game_runtime::{ScenarioFile, ScenarioGame, Setup}; use cb_kernel::{Actor, Aggregate, PlayerId}; use criterion::{criterion_group, criterion_main, BatchSize, Criterion, Throughput}; use games_ground::{Action, GroundCommand, GroundMode, GroundState}; @@ -39,66 +39,50 @@ fn apply(state: &mut GroundState, actor: Actor, command: &GroundCommand) -> usiz } } -/// One full round for three players: three Selects, Reveal, the GROUND -/// mode choice, Resolve, End. Returns the number of events applied. -fn play_round(state: &mut GroundState) -> usize { - let picks = [ - ( - PlayerId(0), - GroundCommand::SelectAction { - action: Action::Attack, - target: Some(PlayerId(1)), - problem: None, - }, - ), - ( - PlayerId(2), - GroundCommand::SelectAction { - action: Action::Support, - target: Some(PlayerId(1)), - problem: None, - }, - ), - ( - PlayerId(1), - GroundCommand::SelectAction { - action: Action::Ground, - target: None, - problem: None, - }, - ), - ]; +/// K18: the benchmark workload, **loaded from the scenario format**. +/// +/// Until CB-WP-0006 T07 this function hardcoded the command sequence in +/// Rust and never touched `ScenarioFile`, so K18 — "Criterion benches +/// driving the same scenario format at scale" — was false. Embedding the +/// file at compile time keeps the bench self-contained while making the +/// workload *data*: editing `benchmarks/synthetic-3p.yaml` changes what +/// AM-6 and AM-7 measure, and `bench_shape` in the aggregate crate breaks +/// if that changes the round's shape. +const WORKLOAD_YAML: &str = include_str!("../../../benchmarks/synthetic-3p.yaml"); - let mut applied = 0; - for (seat, command) in picks { - applied += apply(state, Actor::Player(seat), &command); - } - applied += apply(state, Actor::System, &GroundCommand::Reveal); - // GR-R05: the GROUND player picks a mode before resolution. - applied += apply( - state, - Actor::Player(PlayerId(1)), - &GroundCommand::ChooseGroundMode { - mode: GroundMode::Gr, - choice: None, - }, +fn workload() -> Vec<(Actor, GroundCommand)> { + let sc = ScenarioFile::from_yaml(WORKLOAD_YAML).expect("bench workload parses"); + // Positive control: an empty or mis-parsed workload would benchmark + // nothing while still reporting a rate. + assert!( + !sc.commands.is_empty(), + "K18: the bench workload has no commands" ); - applied += apply(state, Actor::System, &GroundCommand::Resolve); - applied += apply(state, Actor::System, &GroundCommand::EndRound); + sc.commands + .iter() + .map(|step| GroundState::parse_command(step).expect("bench command parses")) + .collect() +} + +/// One full round for three players, replayed from the scenario workload. +/// Returns the number of events applied. +fn play_round(state: &mut GroundState, round: &[(Actor, GroundCommand)]) -> usize { + let mut applied = 0; + for (actor, command) in round { + applied += apply(state, *actor, command); + } applied } -/// A game ends after Round 5 (GR-R09), so a long run starts a fresh game -/// rather than idling on a finished one. Setup cost is therefore part of -/// the measurement, at one setup per five rounds. fn run_rounds(rounds: usize) -> usize { let mut applied = 0; let mut state = setup(42); + let script = workload(); for round in 0..rounds { if state.outcome.is_some() { state = setup(42 + round as u64); } - let produced = play_round(&mut state); + let produced = play_round(&mut state, &script); // A workload whose commands get rejected still "runs", but it // measures nothing. An earlier version of this bench stalled on // the GR-R03 stress gate and reported throughput for rounds that @@ -163,7 +147,7 @@ fn record_round(state: &mut GroundState, log: &mut Vec `58/58 (100%)` read as "all rules". > > `make coverage` now reports a second, separate denominator: -> **16 of 18** K-rules are named across the source. -> Unlinked: **K14 K18**. -> (K10 was unlinked until CB-WP-0006 T06 implemented replay bundles.) +> **18 of 18** K-rules are named across the source. +> Unlinked: **(none)**. +> K10 was unlinked until T06 implemented replay bundles; K14 and K18 until +> T07 amended one and implemented the other. The link is complete — which +> is a statement about **names**, not about assertions, and the gate says +> so on every run. > > **Kernel rules are link-only, by design.** They are kernel invariants, > not game rules: there is no kernel aggregate, setup preset or command diff --git a/tools/__pycache__/rule-coverage.cpython-312.pyc b/tools/__pycache__/rule-coverage.cpython-312.pyc index ccfb67daf772ef6cd3a2dc18e4fe7877a11e5ade..c975e36446c2cd7ceac1853f073e7c32713b4e36 100644 GIT binary patch delta 1838 zcma)6ZA@EL7(S=%?Z<`E(o(v0fOji}cCCD_Oa^Rxt!&YaIgH743+Xr)Xer%xTVOV~ z0i%m!BNKLJ_5nDuABq7Jm+r5LKNpSKg{WAUEE@fxGbZ~;j6@UP({i_|G1+bIbD#5` z=REIu&wX#dI)^`@xZpFRkwU($<=yV&W#AB~>oCv~Cf0(ixLuoH&$;Bp0_U>*6+r zEv*x>`H@a5bDijIU7u=DNJ&!s{Yr5Cl+Fj*phkhtd0~9+mrbi$$8;ggeWy_ z3>j5O&X(%6>{6kk1&dhZEoAH$gT;YR3y?!w?+CNi6Xg zkviEl%D4u2J>zj}wk!bI6!x=sMSWhqV-}HZ^D5=2Fv^xPIP1|LWkj9CkvC7r1c4HyKI3Cb%0+dIPaDV zVcQznDsdzrTUiM(gR_}(J=_5=N;b=uL;;wYr+gY1fq|t55pNIlCWbqy8$(W1i(+^T z#)n`9M$^!zC)J10820Q*rAsBQIK#z`i+!;*V^?rkd|s5IVx(%A(01qYc+F6DxI-8S z#zi42j*61d9}Goe!cnpRm?R4EK~Xpwijq)tKp>z==yDS+iB4r{us;r~{w>S~vaUJ5 zP=CK5jYPzl5Cq$iXe1OJ5}U}+?88lHvmPx8l}|_*lu5Ft65MN8Si_zX6R3nACN2oU zNJPjkCG<#n4=$tE%lBE~$dOdYz{0=_K>sQaU>ogp37b^CLm6#v6ly0@FHB_&z3b@- z?Q=2Jiw$=AvCERjzSlS4jyW``jO$PQvIX(B3op%WxmtO-@~ZE$Z(-~s(~6^Y#n$$X zEpW>gSh4L{wN*S&W8OW{{-e<`*F3v(v1!G)eIl@0QuejEZu-Q+=Ea6<)#nS-=DLZ! z0Jn{HnyLJ0uz8g?Pq$5aFWDE07xZbn=b;*N-tRSrG=E@~H(lO1)3%6j@mp8(Ez|z# z%1f5Hjs?T){`4mAVq=>3f9vy~mZqH--81e>jVl&cy0Bs)c+2QcH@$FAjq~>7hn$-0 z#t(UV*F9AA$Njw+71sY=g1M%92w*M7{#S378}_$oZdPdkKXq*BR;j;Kaozc;6P`6a zCxt*kkJWw0Nnv2Aef5)g!yqtEnZ*9fGV0iCv5Y1t4U9_T^tWvrw8IdUVl>}hfsfOA z{~bI+tqme~4Z?R*$%bkJj?oWyHREpj%PuD`^)vYZ0Cl$Z;MeI`>yVC}e&QLP&Nxf; zg7hX+gi-}mdM#K7F zqHOGAV=mVW@36o;1J)MO6$Y~mm{mr%-uBWQJ=IZx1F7YX8kIR)qmhXO29xyH-K8Z{ yjGhO`aC delta 1285 zcma)4U1(fI6rQ=ecmMyAg+|kc4DDt&``2`vuA6iltw}cBYFdhUkQPhac5c%B$xWEO zZIbm~R|wUn#x`ZNt+s)PKAEVL1$`2H@IlarQV>c66|oP#1q~E}pmVZWqWIFe+;6^f z=G^Z)GjqS@_=juQ^PSu6Kw`Y`MXB&*`krT`3Ed*$Yu{OFD%c zqFq&oE*Coyn!(J05j~(gF9A0To&c`->)jxvI}35~Wh-Bf+gk4+dT>cEtz%iDJIirb*~5{v4kr^dq-4v>7I&5 zh`APGW~94>K=TNq;SsbCB~TepOBkINw}8>YgBjClG>yYYYo2x{^P7RyYHv|ts!}>k z#&eoNm@+lVv@$uTj7>6yXcrW6F0azOI!>rqkCCxlzEmc;F->8=!%tPQ)=T>;)_S(D zvL{V0s-?VIR48E=OG=q2Gx@Scv`LzqtwbOdKR&RQoja7dAVP=PCYo_)#qL(BWHrem?rZ5xCv4oOnO- z(B)qoTI{))*F)O)gI<=gSrMvD}36;?}wEpP>9&{|KJtzxEgL zYy9LuheZcbqc%G*iY>1LukxP;kBU~>Gu=)V5^x^uGC!N?J#z(UQ9#(shJYUf_)x%_ z8Qj=A5XT^vRbflnbx7O-7zKD2;5`74TC;B7H@nH#GeMlLwG17Qd|Uf;LlFU(<1c61 z_PhynLBN`Pd~o!o3_Agdj{!d7i`kH6>)7t{ud)a6=X^c;f%Oc=t$$P`e&cx8KMb`k A)Bpeg diff --git a/tools/facts.py b/tools/facts.py index e89a4cb..7036fda 100644 --- a/tools/facts.py +++ b/tools/facts.py @@ -142,8 +142,10 @@ def measure(): facts["am_rows"] = (len(mrows), "{:,}", "tools/mutation-check.py") facts["am_unmutatable"] = (sum(1 for r in mrows if r.unmutatable), "{:,}", "tools/mutation-check.py") + # "(none)" rather than "" — an empty rendered value cannot be tagged in + # prose, and reads as a malformed fact rather than a true one. facts["k_unlinked"] = ( - " ".join(r for r in k_rules if r not in k_named), "{}", + " ".join(r for r in k_rules if r not in k_named) or "(none)", "{}", "tools/rule-coverage.py") return facts @@ -350,7 +352,10 @@ def self_test(): check_("every fact records the instrument that produced it", all(v.get("by") for v in keys.values())) check_("every fact records both a value and its rendered text", - all("value" in v and v.get("text") for v in keys.values())) + all("value" in v and v.get("text") is not None + for v in keys.values()), + "a legitimately empty value is still a fact — it must not be " + "reported as malformed") check_("registry is generated, not hand-written", open(REGISTRY).read().startswith("# GENERATED")) diff --git a/tools/rule-coverage.py b/tools/rule-coverage.py index f899413..d564974 100755 --- a/tools/rule-coverage.py +++ b/tools/rule-coverage.py @@ -186,6 +186,14 @@ def self_test(): # The gate date must actually change behaviour, in both directions. # A "binds later" that never binds is the AM-4 failure this replaces. + # What the gate must do depends on whether anything is unlinked, so + # compute that rather than assuming it. An earlier version hardcoded + # "unlinked rules exist today" and failed the moment T07 linked the + # last one — correctly, but for the wrong reason. + _k = parse_rules(open(os.path.join("specs", "GameKernel.md")).read(), + r"\*\*(K\d+)\*\*") + _named = code_ids_over(source_files(), r"\bK\d+\b") + _unlinked = [r for r in _k if r not in _named] before = kernel_arm(today=datetime.date(2026, 1, 1), quiet=True) after = kernel_arm(today=datetime.date(2027, 1, 1), quiet=True) @@ -208,9 +216,12 @@ def self_test(): f"{len(out.splitlines())} lines") check("kernel: quiet suppresses output, loud does not", out.strip() != "" and _silent_output() == "") - check("kernel: gate reports before the binding date, fails after", - before == 0 and after == 2, - f"before={before} after={after}; unlinked rules exist today") + check("kernel: gate never fails before the binding date", + before == 0, f"before={before}") + check("kernel: after the binding date the gate fails iff rules are unlinked", + after == (2 if _unlinked else 0), + f"after={after}, {len(_unlinked)} unlinked" + + (f" ({' '.join(_unlinked)})" if _unlinked else " — all linked")) print("rule-coverage self-test (positive control)") ok = True