coulomb/clay-borg
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

CB-WP-0040: name the stratum before naming the defect
Some checks failed
ci / check (push) Failing after 3s
Details

Browse source 
The maintainer could not tell whether "error", "failure", "finding" or
"correction" referred to the game's design, our formalisation of it, the
code, the measuring apparatus, or the sentences we wrote. Three review
rounds produced twenty-odd defect statements spanning five systems, all
called errors. The confusion was ours.

specs/Taxonomy.md, grounded in named canon rather than invented here: six
strata 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 what was missing:
GAME<->MODEL is validation, MODEL<->ENGINE is verification, and nearly
every argument about "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 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, which is why tests never catch them.

MDA supplies the game-facing layers and one hard limit: our panels measure
dynamics, our trial logs sample aesthetics, and a win rate does not answer
"is it fun".

specs/Positioning.md names the field fairly — Ludii is the closest
relative and the right benchmark — and the four differentiators, each
already built rather than aspired to. Clay-borg is a design-evidence
instrument; anyone can produce the number. Three tracks named and none
started: a second game, game theory as the lens on dynamics, and
assimilated knowledge about why games work.

Track A is the falsifier for the whole positioning: every abstraction here
has exactly one instance, which by our own rule may mean invented rather
than observed.

Chaos window 3 closes at 12 declarations with one override that changed
nothing. Its verdict is due and is deliberately not written here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-08 11:41:16 +02:00
parent c4a8a227c0
commit 713a9df7fd
5 changed files with 502 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

35
INTENT.md
View file

@ -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

12
specs/ChaosRollHistory.md
View file

@ -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

148
specs/Positioning.md Normal file
View file

@ -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.

185
specs/Taxonomy.md Normal file
View file

@ -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.

123
workplans/CB-WP-0040-what-a-statement-is-about.md Normal file
View file

@ -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.