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 (layers and ports) and 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

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