tegwick
627992bc85
Some checks failed
ci / check (push) Failing after 5s
Reading Player_Mats.csv and Glossary.csv — which O4 had forbidden declaring about until they were read — found a rule. Player_Mats' choice_rule column IS GR-R03: at Stress 4-5 choose ATTACK or GROUND unless you spend a ready Freedom token. The engine's stress_gated and allowed_under_stress_gate match it exactly, and now have a tripwire. So Ornamentation.md gains §1.3: the unit is a column, not a file. Classifying Player_Mats as ornamentation would have thrown a rule away with the colour swatches. A mixed artifact is normal — a player mat is a rule printed on a decorated card in the box too. O4 is rewritten and re-grounded from provisional to rule accordingly. O5, O6, O7 declared with falsifiers. O7's is not theoretical: back_design_id is unread in four vendored files, and hidden information is what card backs are for. CB-EV-0029 answers T04's question per rule rather than as a count — yes, every checkable clause — and states the reading that result does NOT support: it shows GroundRules.md was a faithful secondary source for the clauses with behaviour to check, not that the engine is correct. 10 of 19 files vendored. Nine still unread, and Rules_Text.csv is the one that matters: every clause checked here was checked against our own transcription of it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
268 lines
11 KiB
Markdown
268 lines
11 KiB
Markdown
# Ornamentation — what a game is besides its rules
|
||
|
||
Status: **draft**, normative for new work. Changes go through a decision
|
||
record in `decisions/`.
|
||
|
||
Companion to [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md)
|
||
(layers and ports) and [`GameDesign.md`](GameDesign.md) (findings about
|
||
the game). This document draws **one boundary**: between what the rules
|
||
can see and everything else a player experiences — and says which repo
|
||
each belongs to as the simulator grows.
|
||
|
||
> **A good game is not only its rules.** It is materials, flow, timing,
|
||
> relatability, illustration, typography, and the ceremony around play.
|
||
> A simulator that models only the rules models a *part* of the game, and
|
||
> should say which part rather than implying it is the whole.
|
||
|
||
---
|
||
|
||
## 1. Two categories, and the test between them
|
||
|
||
**Mechanism** is anything that can change the state the rules can see.
|
||
|
||
**Ornamentation** is everything else the player nonetheless experiences.
|
||
|
||
### 1.1 The test
|
||
|
||
> **Does it move the state hash?**
|
||
>
|
||
> If yes, it is mechanism. If no, it is ornamentation.
|
||
|
||
This reuses an instrument the project already has and already trusts:
|
||
`state_hash` is what makes a session comparable to its replay, and what a
|
||
trial note binds to (ADR-0019 D3). **The line is therefore executable, not
|
||
editorial** — which matters here more than elsewhere, because everything
|
||
downstream depends on the classification being right.
|
||
|
||
### 1.2 Ornamentation usually decorates a mechanism rather than replacing it
|
||
|
||
The clearest case, and the one that named this document:
|
||
|
||
| the fact | category | why |
|
||
|---|---|---|
|
||
| the deck's permutation | **mechanism** | it decides the deal; in clay-borg it comes from the seed |
|
||
| **who shuffles**, and the shuffling | **ornamentation** | no rule can see it |
|
||
| the hands after dealing | **mechanism** | the state contains them |
|
||
| **who deals**, cards arriving one at a time, entering from the right | **ornamentation** | the same hands either way |
|
||
|
||
So ornamentation is typically **a ceremony around, or a presentation of, a
|
||
mechanism** — and occasionally a thing with no mechanism under it at all.
|
||
|
||
**"Has a decision in it" is NOT the test.** Choosing who deals is a
|
||
decision, and it is ornamentation. This was the open question in
|
||
CB-WP-0036 and the maintainer settled it: these are ornamental *because
|
||
they are not necessary*, not because nobody chooses.
|
||
|
||
### 1.3 The unit is a column, not a file
|
||
|
||
**Discovered by doing it** (CB-WP-0037 T03). `Player_Mats.csv` looks like
|
||
pure ornamentation — a symbol, a colour, a title for each of six seats —
|
||
and one of its columns is GR-R03 itself:
|
||
|
||
> *"At Stress 0–3 choose any action. At Stress 4–5 choose ATTACK or GROUND
|
||
> unless you spend a ready Freedom token."*
|
||
|
||
That is the stress gate the engine enforces in `stress_gated` and
|
||
`allowed_under_stress_gate`. **Classifying the file would have thrown a
|
||
rule away with the colour swatches.**
|
||
|
||
So a declaration names *what* it ornaments, not *where the bytes live*. A
|
||
mixed artifact is normal: the mat is a rule printed on a decorated card,
|
||
which is exactly what a player mat is in the box too.
|
||
|
||
### 1.4 Why not "ritual"
|
||
|
||
`ritual` reads as ceremony only, and half of this category is not
|
||
ceremonial — card stock, a typeface, the drift of a discard, how legible a
|
||
player mat is. **`ornamentation` covers the material and the ceremonial
|
||
together**, and carries the right implication: it is *applied to* the
|
||
thing, and it is not structural — and §1.3 is why *applied to* is the
|
||
right preposition: it sits on something, it is not the something.
|
||
|
||
Ornamentation is **not decoration in the pejorative sense**. This project
|
||
uses "decoration" for a control that cannot fail (ADR-0006 D3), and that
|
||
word is spoken for.
|
||
|
||
---
|
||
|
||
## 2. Why clay-borg names what it will never render
|
||
|
||
The rendering belongs downstream (§3). The **classification does not**,
|
||
for one reason:
|
||
|
||
> **Calling something ornamentation is a claim that it does not matter to
|
||
> the game — and claims that something does not matter are exactly the
|
||
> claims this project has been wrong about.**
|
||
|
||
The register is the evidence. `quantity` in `Tokens.csv` was measured
|
||
across 750 games before being declared non-binding (CB-EV-0027 §3), and
|
||
the argument that settled it was *not* "nothing exceeded it" — it was that
|
||
no numbered rule mentions a supply, so enforcing one would have been the
|
||
engine deciding a rules question. F18 stands open because four edition
|
||
files were assumed not to matter. CB-WP-0023 exists because SOLVE was
|
||
offered where it could not act.
|
||
|
||
**A classification is a claim about the game.** It therefore belongs where
|
||
this project keeps claims about the game — with a reproduction and a
|
||
falsifier (GameDesign §1) — and not in a renderer's stylesheet, where
|
||
nothing can contradict it.
|
||
|
||
### 2.1 What a declaration carries
|
||
|
||
1. **What it ornaments** — the mechanism it accompanies, or `none`.
|
||
2. **Why it does not bind** — by rule text where the edition has one, or
|
||
by measurement, or explicitly *"provisional, nobody has ruled"*.
|
||
3. **What would falsify it** — the rule or observation that would make it
|
||
mechanism. A declaration that cannot be wrong is not a claim.
|
||
|
||
**Provisional is a legitimate state and must be said out loud.** The
|
||
failure mode this project has already committed once is canonising a
|
||
provisional default by implementing it quietly.
|
||
|
||
### 2.2 Ornamentation is sourced, not invented
|
||
|
||
ADR-0015's discipline applies unchanged: **the game's own words, where the
|
||
game has words.** Card text, mat layout, the vocabulary in `Glossary` and
|
||
the stage names in `DARVO` are ornamentation-bearing data that exists
|
||
upstream and is currently **unvendored** (F18).
|
||
|
||
Where the edition says nothing, clay-borg may choose — and must **label
|
||
the choice as ours**, exactly as the rankings panel labels its one derived
|
||
superlative *"clay-borg's reading, not a rule"* (CB-EV-0026 §5).
|
||
|
||
---
|
||
|
||
## 3. The module boundary
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
CB["clay-borg
|
||
state - rules - admissibility
|
||
trials - findings
|
||
ornamentation DECLARED
|
||
one simple built-in view"]
|
||
CA["clay-animate
|
||
movement - timing - layering
|
||
the interactive pace's presentation"]
|
||
CP["clay-physics
|
||
material simulation
|
||
cards - table - gravity"]
|
||
CB -->|"facts + declarations"| CA
|
||
CA --> CP
|
||
```
|
||
|
||
**clay-borg is the simulation core and stays that way.** Its built-in view
|
||
is deliberately plain: simple frontend/backend interaction, simple UI
|
||
concepts, so attention stays on the game and the simulation rather than on
|
||
a rendering pipeline. **Its native pace is Speed** (§4), and it is tuned
|
||
for that.
|
||
|
||
**clay-animate** is where movement lives: a card summoned larger beside
|
||
the acting seat, shrinking toward its target, a discard drifting without
|
||
resizing. It is a *later, separate repository* and needs a client/server
|
||
interaction materially more complex than the core should carry.
|
||
|
||
**clay-physics** is further out still: real material behaviour.
|
||
|
||
### 3.1 The rule that makes the boundary hold
|
||
|
||
> **Downstream may read. Downstream may not decide.**
|
||
|
||
This is [ADR-0007](../decisions/ADR-0007-hot-seat-in-a-browser.md) D5 —
|
||
*the page reports raw pointer facts and constructs no commands* — restated
|
||
one level up, at the repository boundary rather than the script boundary.
|
||
|
||
A game played through `clay-animate` must be **indistinguishable, in the
|
||
record, from the same game played through clay-borg's own view.** If a
|
||
renderer can change an outcome it is not a renderer.
|
||
|
||
### 3.2 Why the port is not being built yet
|
||
|
||
**No consumer exists.** This project's own rules say a kind with no
|
||
instance was invented rather than observed (GameDesign §2) and a gate that
|
||
cannot go red is decoration (ADR-0006 D3). An interface designed against
|
||
an imagined client would be both.
|
||
|
||
**What is being fixed now is the vocabulary and the boundary.** The port
|
||
gets designed when `clay-animate` exists to pull on it, and the first
|
||
version of it should be *the data clay-borg already emits* — the journal
|
||
is already the sequence of what happened, and CB-WP-0032 already reads it.
|
||
|
||
---
|
||
|
||
## 4. Pace
|
||
|
||
`--pace speed | interactive` (proposed; **not** `--mode`, which is
|
||
already `ScoringMode`).
|
||
|
||
| pace | what it means |
|
||
|---|---|
|
||
| **speed** | ornamentation is skipped; the view jumps to the result. **The default**, and what `sim`, `trials`, benchmarks and bot play always use |
|
||
| **interactive** | ornamentation is performed |
|
||
|
||
Pace selects **how much ornamentation is performed**. It can never select
|
||
*different mechanism*, which §5 states as an invariant rather than an
|
||
intention.
|
||
|
||
`prefers-reduced-motion` behaves as **speed**.
|
||
|
||
---
|
||
|
||
## 5. Invariants
|
||
|
||
These are the document's teeth. **I1–I4 are checkable today, cheaply**,
|
||
which is the point — this project has 62 untagged literals as evidence of
|
||
what a broad unenforced requirement produces (ADR-0018 D4).
|
||
|
||
| | invariant |
|
||
|---|---|
|
||
| **I1** | Ornamentation never moves `state_hash`. |
|
||
| **I2** | Ornamentation never enters the journal or the recording. |
|
||
| **I3** | The same seed and the same decisions produce a **byte-identical recording** at any pace, through any renderer. |
|
||
| **I4** | Speed pace costs the core **nothing** — not "little": `sim`, `trials` and the benchmarks are unaffected. |
|
||
| **I5** | Every ornamentation declaration states what would falsify it (§2.1). |
|
||
|
||
**I3 is the falsifier for the whole boundary.** If it ever fails,
|
||
something downstream has become mechanism and the split has stopped being
|
||
real.
|
||
|
||
### 5.1 What to do when ornamentation must be preserved
|
||
|
||
I2 keeps the recording canonical, which raises a fair objection: a replay
|
||
then cannot reproduce **what a player actually saw**.
|
||
|
||
The answer already exists in this repo. A trial keeps *two* files — the
|
||
recording and a sibling log of what the player said (GameDesign §5). **A
|
||
session's ornamentation goes in a sibling too**, never in the scenario.
|
||
One artifact stays replayable; the other stays human.
|
||
|
||
---
|
||
|
||
## 6. Where a new capability goes
|
||
|
||
In order. The first match wins.
|
||
|
||
1. **Can it change a legal move, an outcome, or the state hash?**
|
||
→ clay-borg, as mechanism, under the existing rule budgets.
|
||
2. **Is it a claim that something does *not* matter?**
|
||
→ clay-borg, as a declared ornamentation with a falsifier (§2.1).
|
||
**This is the step that gets skipped**, and skipping it is how a
|
||
provisional default becomes canon without anyone deciding.
|
||
3. **Is it the presentation, timing or movement of either?**
|
||
→ clay-animate.
|
||
4. **Does it need materials to behave like materials?**
|
||
→ clay-physics.
|
||
5. **None of these?** Then it is not yet understood well enough to place,
|
||
and the honest move is a finding, not a module.
|
||
|
||
---
|
||
|
||
## 7. Falsifier for this document
|
||
|
||
If an ornamentation declaration is ever found to have changed an outcome,
|
||
§1.1's test is not the right test and this document is wrong at the root —
|
||
not patchable at the edges.
|
||
|
||
If, after `clay-animate` exists, **§3.2's deferred port turns out to have
|
||
needed designing here all along**, then the "no consumer, no interface"
|
||
rule cost more than it saved, and that should be recorded against it.
|