specs/Ornamentation.md: what a game is besides its rules

Draws one boundary — between what the rules can see and everything else a
player experiences — and says which repository each belongs to as the
simulator grows.

"Ritual" becomes ornamentation: half the category is material rather than
ceremonial, and "decoration" is already spoken for in this repo (a control
that cannot fail). The test is not "does it have a decision in it" —
choosing who deals is a decision and is ornamental. The test is whether
the state hash moves, which reuses the instrument that already binds a
trial note to a position.

The part that earns its place in clay-borg rather than in a renderer's
stylesheet: calling something ornamentation is a CLAIM THAT IT DOES NOT
MATTER, and this project's register is a list of times that claim was
wrong — quantity in Tokens.csv, F18's four unread files, SOLVE offered
where it could not act. So a declaration carries a falsifier, and
"provisional" is a state it must say out loud.

Downstream may read, may not decide — ADR-0007 D5 restated at the
repository boundary. The port to clay-animate is deliberately NOT
designed: no consumer exists, and an interface built against an imagined
client is the same defect as a gate that cannot go red.

Five invariants, four checkable today. I3 — same seed and decisions
produce a byte-identical recording at any pace through any renderer — is
the falsifier for the whole split.

CB-WP-0036 re-declared from L to M accordingly: the animation architecture
that made it L has moved to clay-animate. No code had been written and the
tier-L review had not been run, which is the only reason it could be
re-scoped rather than unwound.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

specs/ArchitectureBlueprint.md

@@ -5,6 +5,9 @@ the stable structural decisions: layers, component planes, capability ports,
 data flows, and repository layout. For motivation and product intent see
 [`../INTENT.md`](../INTENT.md); for the full originating exploration see
 [`../history/260730-InitialExploration.md`](../history/260730-InitialExploration.md).
+For the boundary between what the rules can see and everything else a
+player experiences — and which repository each belongs to as the simulator
+grows — see [`Ornamentation.md`](Ornamentation.md).
 
 Status: **draft** — this blueprint is normative for new work but still
 malleable (Clay). Changes go through a decision record in `decisions/`.

specs/Ornamentation.md

@@ -0,0 +1,250 @@
+# 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 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.
+
+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.