clay-borg/specs/Ornamentation.md

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