diff --git a/INTENT.md b/INTENT.md index da25b01..f5d18e7 100644 --- a/INTENT.md +++ b/INTENT.md @@ -22,10 +22,28 @@ development engine with four distinct properties: tolerates an undecided rule by quietly picking a default and not raising it, this property is false.)* +A fifth property, added 2026-08-08 because three adversarial review rounds +made it undeniable: + +5. **The instrument is under the same discipline as the engine.** Twelve + fatal defects were found in one measurement, **every one in our + apparatus and none in the game**, and several had already been written + into evidence as conclusions. A tool that reports design findings + without treating its own measurements as claims is reporting its bugs + at the same volume as its results. *(See [`specs/Taxonomy.md`](specs/Taxonomy.md) + for what "defect" now means, and where.)* + The central rule: > **Own the semantics; assimilate the implementation.** +And the second, which says what the product actually is: + +> **Clay-borg is a design-evidence instrument.** Its output is not a +> number about a game; it is an auditable answer to *what does this rule +> do at the table, and how much should you trust that* — +> [`specs/Positioning.md`](specs/Positioning.md). + Clay-Borg owns what an entity, object, command, event, card, zone, relationship, game, simulation, asset, plugin, and capability *mean*. External libraries (wgpu, Rapier, Bevy ECS, Wasmtime, Quinn, egui, Serde, @@ -33,6 +51,23 @@ tracing, …) provide optimized implementations of rendering, physics, networking, serialization, and similar functions behind canonical ports. No external library type should leak across a canonical interface. +## Vocabulary + +*"Error"*, *"failure"*, *"finding"* and *"correction"* were each being +used for the game's design, our formalisation of it, the code, the +measuring apparatus and the sentences we wrote. +[`specs/Taxonomy.md`](specs/Taxonomy.md) fixes that: **every defect +statement names a stratum first** — GAME, MODEL, ENGINE, INSTRUMENT, +ACCOUNT, PRESENTATION — because "a bug in the simulator" and "a gap in the +game" have different owners and different fixes. + +## Where this is going + +Three tracks, none started, in [`specs/Positioning.md`](specs/Positioning.md) §4: +**a second game** (which is the falsifier for "GROUND is an example"), +**game theory as the lens on dynamics**, and **assimilated knowledge about +why games work**, offered to designers. + ## Why GROUND first GROUND requires modest physics but sophisticated social state, simultaneous diff --git a/specs/ChaosRollHistory.md b/specs/ChaosRollHistory.md index 23517ea..73cb0be 100644 --- a/specs/ChaosRollHistory.md +++ b/specs/ChaosRollHistory.md @@ -65,6 +65,7 @@ it recurs; not evidence of anything on its own. | 9 | CB-WP-0037 | d8 = 1 | — | | 10 | CB-WP-0038 | **d8 = 8** | **yes — redraw L, structural was L, so it changed nothing** | | 11 | CB-WP-0039 | d8 = 2 | — | +| 12 | CB-WP-0040 | d8 = 5 | — | **The window's first 8, at declaration 10.** Expectation over ten rolls at d8 is 1.25; one is exactly on rate. @@ -72,7 +73,16 @@ d8 is 1.25; one is exactly on rate. **The override changed nothing**, which is the observation ADR-0017 D2's retirement condition is built from — it needs *a full window whose overrides all change nothing*, in two consecutive windows. This window now -has one qualifying override and **one declaration left to run**. +had one qualifying override, and it changed nothing. + +**Window 3 is closed at 12 declarations. Its verdict is due and is not +written here** — recording it is a change to how the loop constrains its +own operation, which is a tier-M trigger in its own right, and window 2's +verdict was delayed the same way. **One override in twelve, changing +nothing**, is the second consecutive window to produce no override that +changed an outcome; ADR-0017 D2's retirement condition asks for exactly +that in two consecutive windows and should now be evaluated rather than +restated. **Declaration 8 is a re-declaration of the same workplan**, counted separately because it was a materially different pass: CB-WP-0036 was diff --git a/specs/Positioning.md b/specs/Positioning.md new file mode 100644 index 0000000..3d48ed9 --- /dev/null +++ b/specs/Positioning.md @@ -0,0 +1,148 @@ +# Positioning — what clay-borg is for, and what it does that others do not + +Status: **draft**. A working answer to *"where does this sit, and what is +the point of it"*, written against the field rather than in isolation. + +Companion to [`../INTENT.md`](../INTENT.md) (what we are building), +[`Taxonomy.md`](Taxonomy.md) (the vocabulary), and +[`Ornamentation.md`](Ornamentation.md) (the boundary). + +--- + +## 1. The field, honestly + +There are mature systems here and we are not first. + +| system | what it optimises for | what it does not do | +|---|---|---| +| **Ludii** (Digital Ludeme Project) | *generality of representation*. Games as **ludemes** — composable, human-readable concepts. Fast, broad, a game fits in a QR code | it is not built to argue with the designer about the rules, and its evidence is not auditable by a third party | +| **GDL / General Game Playing** (Stanford) | *agent generality* — an agent that plays a game it has never seen | verbose, slow relative to Ludii, and aimed at AI research rather than design support | +| **Machinations** | *economy and feedback-loop simulation*, diagrammatic and immediate | not rules-complete; a model of flows, not of a played game | +| **Tabletop Simulator / boardgame.io** | *play*, human or networked | no analysis; the rules are a script, not a claim | +| **RL self-play stacks** | *strength* | a strong agent tells you what beats what, not why a rule is undecided | + +**Ludii is the closest relative and the right benchmark.** If clay-borg's +answer to *"why not Ludii"* is only "ours is in Rust", there is no answer. + +## 2. What we do differently + +Four things, and each is already visible in the repo rather than aspired +to. + +### 2.1 The measurement is under suspicion by construction + +Every other system in §1 treats its own output as data. **This one treats +its own output as a claim that has to survive an attempt to break it** — +`GameDesign.md` §1 admissibility, the finding register, mutation-proof as +a condition for a control, and mandatory adversarial review at tier L. + +**This is not a posture; it is measured.** Three review rounds on one +measurement found twelve fatal defects, **every one in our instrument and +none in the game** — including two that inverted a verdict already written +down. A tool that reports game-design conclusions without that machinery +is reporting its own bugs at the same volume as its results. + +### 2.2 Authority is federated, and the simulator is not the authority + +The game's owner rules; we report. A rule we cannot execute becomes a +**finding** carried back with the artifact that produced it — never a +default we quietly pick. + +**Ludii's model is a description someone wrote. Ours is a claim about +somebody else's artifact**, with digests and tripwires against their +source of truth, and a queue of open questions that belong to them. That +is a different relationship to the designer than any system above has. + +### 2.3 What is *not* mechanism is modelled too + +[`Ornamentation.md`](Ornamentation.md). Materials, ceremony, typography, +timing — declared, with falsifiers, and separated from the rules by a test +something can run (does the state hash move?). + +Every system in §1 either ignores this or treats it as presentation +config. **We treat "this does not matter" as a claim that can be wrong**, +because our own register is a list of times it was. + +### 2.4 A hypothesis is a package, not a patch + +A design experiment arrives as a selectable variant — a catalog entry, +a machine-readable `rules_delta`, declared success criteria — and is +measured against those criteria, with the results reported including the +parts that fail. The variant is in the game state, so a recording says +which rules it was played under. + +## 3. What that adds up to + +> **Clay-borg is a design-evidence instrument, not a game engine and not a +> game-playing AI.** Its product is an auditable answer to *"what does this +> rule actually do at the table, and how much should you trust that?"* + +The second half of that sentence is the differentiator. Anyone can produce +the number. + +## 4. Where it has to go + +Three tracks, in dependency order. None started. + +### Track A — a second game + +**GROUND is an example, and nothing has tested that claim.** Every +abstraction here has exactly one instance, which by our own rule +(GameDesign §2) means it may have been invented rather than observed. + +The work is to take a **popular, well-understood game** — one where the +dynamics are already documented, so our output can be checked against +something — and build a clay-borg definition efficiently enough that the +cost is itself the finding. **The measurement that matters is how much of +the kernel turns out to be GROUND-shaped.** + +Ludii's ludeme decomposition is the obvious prior art to steal from, and +the honest question is whether we need our own description language at all +or should consume theirs. + +### Track B — game theory as the lens on dynamics + +§4 of [`Taxonomy.md`](Taxonomy.md): our panels measure **dynamics**, and +game theory is the science of exactly that. Today we sample the strategy +space with two hand-written policies and a rank parameter. That is a crude +instrument for questions that have real theory behind them: + +- **dominance** — is an action dominated? (F17 asks this about ATTACK and + answers it with a sweep) +- **equilibrium** — what does competent play converge to, and is it the + play the designer intended? +- **cooperative solution concepts** — GROUND is co-operative with a + defection mechanic; the **core** and the **Shapley value** are the + standard tools for "is this coalition stable" and "what is a seat + contributing", which is precisely what GR-E04 is groping at +- **social dilemmas** — DARVO is one; the literature on them is large + +**The proposed shape is a specialised agent**, not a library: something +that reads a clay-borg game definition and a panel run, and reports what +the theory says about the dynamics — with the same admissibility rules as +everything else, because a Nash equilibrium quoted without its assumptions +is exactly the wrong-subject error in mathematical dress. + +### Track C — assimilated knowledge about why games work + +The furthest out, and the one the maintainer named as the point: +**make what is known about game dynamics available to designers.** + +MDA's aesthetics vocabulary, the balance literature, documented failure +modes (runaway leader, kingmaking, analysis paralysis, dominant strategy, +degenerate equilibrium). The value is not a database — it is that a +finding from a panel run can be **named** as an instance of a known +pattern, and the designer told what usually follows. + +**The risk is obvious and worth stating now**: this track is where a tool +starts telling designers what is fun, on the strength of numbers that +measure dynamics. §4 of the taxonomy is the guard, and it will be under +pressure here. + +## 5. Falsifier + +**Track A is the falsifier for this whole document.** If a second game +cannot be defined without reshaping the kernel around it, then "GROUND is +an example" was never true, clay-borg is a GROUND engine with ambitions, +and §2's differentiators are properties of one bespoke tool rather than of +a framework. diff --git a/specs/Taxonomy.md b/specs/Taxonomy.md new file mode 100644 index 0000000..3bb5fce --- /dev/null +++ b/specs/Taxonomy.md @@ -0,0 +1,185 @@ +# Taxonomy — which system is a statement about? + +Status: **draft**, normative for new work. Changes go through a decision +record in `decisions/`. + +This document exists because the words were doing too much work. *"Error"*, +*"failure"*, *"finding"* and *"correction"* were each being used for the +game's design, our formalisation of it, the code, the measuring apparatus, +and the sentences we wrote — five different things, one vocabulary. + +> **Every defect statement names a stratum before it names anything else.** +> "A bug in the simulator" and "a gap in the game" are not the same kind of +> claim, do not have the same owner, and are not fixed by the same person. + +Grounded in existing practice rather than invented here: the +fault/error/failure chain from **Avizienis, Laprie, Randell & Landwehr** +(*Basic Concepts and Taxonomy of Dependable and Secure Computing*, IEEE +TDSC 1:1, 2004); the model strata and the verification/validation split +from **Sargent** (*Verification and Validation of Simulation Models*); and +**MDA** (Hunicke, LeBlanc & Zubek, 2004) for the game-facing layers. + +--- + +## 1. The strata + +| stratum | canon | what it is | who owns it | +|---|---|---|---| +| **GAME** | Sargent's *problem entity*; MDA *mechanics as designed* | the rules as the game's owner defines them — the edition, the printed text | **the game's owner**, not us | +| **MODEL** | Sargent's *conceptual model* | our formalisation: `GroundRules.md`, the rule ids, the state we chose to represent | us, answerable to the owner | +| **ENGINE** | Sargent's *computerized model* | the kernel that implements the model | us | +| **INSTRUMENT** | measurement apparatus | harnesses, policies, metrics, gates, the trial protocol | us | +| **ACCOUNT** | — | evidence files, register entries, messages, this document | us | +| **PRESENTATION** | MDA *aesthetics*-facing | the page, and everything [`Ornamentation.md`](Ornamentation.md) covers | us, later `clay-animate` | + +### 1.1 The two relations that matter + +> **GAME ↔ MODEL is validation.** *Did we formalise the right game?* +> +> **MODEL ↔ ENGINE is verification.** *Did we implement the formalisation +> correctly?* + +This is Sargent's split and it is the one we kept losing. A statement that +the engine mis-scores a Bond is **verification**. A statement that the +rules do not say what happens when two Bonds break simultaneously is +**validation** — and it is not ours to answer. + +**Sargent's third leg is `data validity`**, and it is where +`editions/` lives: the vendored CSVs, their digests, and the tripwires in +`edition.rs` are data validation, not verification. + +### 1.2 What each stratum's defects look like + +| stratum | a defect here looks like | +|---|---| +| GAME | a rule that does not decide; a dominant strategy; an action that earns its place nowhere | +| MODEL | we represented a rule the edition does not have, or omitted one it does | +| ENGINE | the code does not do what `GroundRules.md` says | +| INSTRUMENT | the measurement answers a different question than the one asked | +| ACCOUNT | the sentence claims more than the artifact shows | +| PRESENTATION | the player cannot see, or misreads, what the state says | + +--- + +## 2. Fault, error, failure + +Avizienis' chain, unchanged, applied **within** a stratum. + +| term | definition | example, INSTRUMENT stratum | +|---|---|---| +| **fault** | the defect in the artifact — the wrong line, the wrong column, the wrong constant | `peak` maximised over `StressSet` payloads | +| **error** | the wrong internal state it produces | the metric holds 1 where the game held 2 | +| **failure** | the deviation visible at the interface | the evidence file says *"peak Stress was 1"* | + +**A fault is dormant until activated.** `attack-value.rs`'s missing +assertion was a fault for weeks and produced no error, because no cell was +ever short. + +### 2.1 The rule that explains our history + +> **A failure in one stratum is a fault in the next.** + +An INSTRUMENT failure (a metric reporting the wrong number) is an ACCOUNT +fault (a sentence built on it). An ACCOUNT failure that reaches the owner +is a fault in *their* decision-making. That is why +[`GameDesign.md`](GameDesign.md) §1 gates what may leave the repo: it is a +firebreak in this chain, not politeness. + +### 2.2 The wrong-subject error, defined at last + +[ADR-0018](../decisions/ADR-0018-a-number-that-does-not-move.md) named a +family and could not say precisely what it was. In this vocabulary: + +> **A wrong-subject error is an ACCOUNT failure with no INSTRUMENT fault.** +> The measurement is correct about *its* subject; the sentence is about a +> different one. + +`peak Stress was 1` — the metric correctly reported the maximum *assigned* +Stress. `Reactive is greedy with one preference changed` — the policy +correctly implemented what was written. **Nothing was miscomputed in +either case**, which is exactly why tests did not catch them and why the +fix is never "add a test to the engine". + +--- + +## 3. The vocabulary, fixed + +| word | means | does not mean | +|---|---|---| +| **finding** | a statement about the **GAME** stratum, admissible under GameDesign §1, addressed to the owner | any defect we happen to notice | +| **defect** | a fault in any stratum we own — MODEL, ENGINE, INSTRUMENT, ACCOUNT, PRESENTATION | a design question | +| **fix** | a change to the **artifact** that removes a fault | a change to what we said | +| **correction** | a change to the **ACCOUNT** — a claim withdrawn, restated or re-derived | a code change | +| **retraction** | a correction of something that has already **left the repo** | an internal edit | +| **regression** | a fault introduced by a change, in any stratum | any failure | +| **inert control** | a control that cannot fail, so proves nothing (ADR-0006 D3) | a control that happens to be green | + +**The register carries findings.** Where an entry is really a defect in a +stratum we own — F18, F24, F25 are ENGINE/data — the row says so, because +"the engine has not read this file" and "the game does not decide this" +are different claims to a reader deciding what to act on. + +--- + +## 4. What the layers measure, and what they cannot + +MDA gives the game-facing split, and it maps onto instruments we already +have: + +| MDA layer | where it lives here | what measures it | +|---|---|---| +| **Mechanics** | GAME → MODEL → ENGINE | the rule-coverage gate, the edition tripwires | +| **Dynamics** — the behaviour that emerges in play | what the ENGINE produces over many games | the policy panels: win rates, DARVO arm rates, action selection | +| **Aesthetics** — the player's response | not representable in state | **trial notes, and nothing else** | + +> **Our panels measure dynamics. Our trial logs sample aesthetics. Neither +> substitutes for the other**, and the recurring temptation is to report a +> dynamics number as though it settled an aesthetics question — *"is the +> game fun at 5 seats"* is not answered by a win rate. + +MDA's own directional insight is the reason: **the designer builds +mechanics upward hoping for a feeling; the player meets the feeling first +and infers the rules.** A simulator sits at the bottom of that arrow and +can only ever report upward. + +--- + +## 5. Worked examples from this repo + +Because a taxonomy with no instances was invented rather than observed +(GameDesign §2). + +| what happened | stratum | fault / error / failure | +|---|---|---| +| `solution_deck()` is a Rust literal that never reads `Solutions.csv` | ENGINE (data validity) | dormant **fault**; no error, because the literal agrees | +| `score()` read `self` while H1's pressure went into `work` | ENGINE | **fault**; error only at round 5; no measured failure | +| GR-P05 — SOLVE offered where it could not act | MODEL, then GAME | our **failure**, escalated to a GAME finding, ruled by the owner | +| ATTACK earns its place in no mode (F17) | **GAME** | a finding — not a defect at all | +| `peak Stress was 1` | ACCOUNT | **failure** with no instrument fault (§2.2) | +| the panels ran under no gate | INSTRUMENT | **fault** — every published figure came from an ungated binary | +| the note channel closed when the game ended | PRESENTATION | **failure**; the state was right, the player could not reach it | + +**Read the stratum column.** Six rows, six different owners and six +different fixes, and every one of them was called "an error" at the time. + +--- + +## 6. Falsifier + +If a defect arises that cannot be placed in exactly one stratum, the +strata are wrong — either too few, or cut in the wrong place. **Record the +instance rather than widening a definition to swallow it**, which is how a +taxonomy stops distinguishing anything. + +A second falsifier, from §2.2: if a wrong-subject error is ever found that +*did* have an instrument fault, then the family is not what ADR-0018 and +this document say it is. + +## Sources + +- Avizienis, Laprie, Randell & Landwehr, *Basic Concepts and Taxonomy of + Dependable and Secure Computing*, IEEE TDSC 1(1), 2004. +- Sargent, *Verification and Validation of Simulation Models*, Winter + Simulation Conference. +- Hunicke, LeBlanc & Zubek, *MDA: A Formal Approach to Game Design and + Game Research*, AAAI Workshop, 2004. diff --git a/workplans/CB-WP-0040-what-a-statement-is-about.md b/workplans/CB-WP-0040-what-a-statement-is-about.md new file mode 100644 index 0000000..f1f0c1b --- /dev/null +++ b/workplans/CB-WP-0040-what-a-statement-is-about.md @@ -0,0 +1,123 @@ +--- +id: CB-WP-0040 +kind: meta +title: "What a statement is about" +status: done +--- + +# Purpose + +``` +structural tier M (fixes the vocabulary the loop uses to describe its + own defects, and states where the repo is going) +chaos d8 = 5 → no override +declared tier M +``` + +**Declaration 12 of chaos window 3 — the window's last.** Its verdict is +due, and this pass does not write it. + +## The report + +> *"It is hard for me to follow what you mean by error, failure, finding +> and correction because i often cant tell if we are talking about the game +> mechanics, the simulator, the telemetry, intended results, +> visualization, etc."* + +**The maintainer is right and the confusion is ours.** Three review rounds +produced twenty-odd defect statements spanning five different systems, all +called "errors". + +## Task: the taxonomy, grounded in canon + +```task +id: CB-WP-0040-T01 +status: done +priority: high +``` + +**Controls:** +- **grounded, not invented** — named sources, because a private vocabulary + is a second thing to learn; +- **worked examples from this repo**, or the taxonomy was invented rather + than observed (GameDesign §2); +- **a falsifier**: what would show the strata are cut wrong. + +**Done 2026-08-08.** [`specs/Taxonomy.md`](../specs/Taxonomy.md). + +**Six strata** — GAME, MODEL, ENGINE, INSTRUMENT, ACCOUNT, PRESENTATION — +from **Sargent**'s problem entity / conceptual model / computerized model, +extended where a simulation-V&V frame stops (we also own an *instrument* +and an *account*). + +**The two relations are the part that was missing.** GAME↔MODEL is +**validation**; MODEL↔ENGINE is **verification**. Nearly every argument we +have had about "is this our bug or their gap" was that distinction going +unnamed. + +**Fault / error / failure** from **Avizienis et al.**, applied within a +stratum, plus the rule that explains the whole review history: **a failure +in one stratum is a fault in the next.** + +**And it finally defines the family ADR-0018 could only point at:** a +wrong-subject error is *an ACCOUNT failure with no INSTRUMENT fault*. The +measurement is right about its own subject; the sentence is about a +different one. **That is why tests never catch these** and why the fix is +never "add a test to the engine". + +**MDA** supplies the game-facing layers and one hard limit: **our panels +measure dynamics, our trial logs sample aesthetics, and neither substitutes +for the other.** A win rate does not answer "is it fun". + +## Task: positioning, and the tracks + +```task +id: CB-WP-0040-T02 +status: done +priority: high +``` + +**Controls:** +- **name the competition and be fair to it** — a differentiator that + requires misdescribing Ludii is not one; +- **every claimed differentiator is visible in the repo already**, not + aspired to; +- **a falsifier for the whole document.** + +**Done 2026-08-08.** [`specs/Positioning.md`](../specs/Positioning.md). + +**Ludii is the closest relative and the right benchmark** — ludemes, a +game in a QR code, far broader than us. If our answer to *"why not Ludii"* +is "ours is in Rust", there is no answer. + +**The four differentiators, each already built:** the measurement is under +suspicion by construction; authority is federated, so the owner rules and +we report; what is *not* mechanism is modelled too; and a hypothesis is a +package with declared criteria rather than a patch. + +> **Clay-borg is a design-evidence instrument.** Its product is an +> auditable answer to *what does this rule do at the table, and how much +> should you trust that*. Anyone can produce the number. + +**Three tracks named, none started** — a second game; game theory as the +lens on dynamics; assimilated knowledge about why games work. + +**Track A is the falsifier for the entire positioning.** If a second game +cannot be defined without reshaping the kernel, then "GROUND is an +example" was never true and the differentiators belong to one bespoke tool +rather than to a framework. **Every abstraction in this repo currently has +exactly one instance**, which by our own rule means it may have been +invented rather than observed. + +## Deliberately not done + +- **No game-theory implementation.** Track B is specified as a shape and + nothing more, because a solution concept quoted without its assumptions + is the wrong-subject error in mathematical dress — and this repo has just + spent three review rounds on that family. +- **No second game started.** It is the largest track and wants its own + declaration. +- **The register rows are not re-stratified.** `Taxonomy.md` §3 says a row + should name its stratum; the existing rows do not yet, and rewriting + twenty-five of them in the pass that invented the rule would put the rule + beyond challenge before anyone had used it.