Validate ordered Age writing and highlight Binder errors (#30)

docs/GAMETESTS.md

@@ -1,15 +1,15 @@
 # GameTest suites
 
-The default dedicated-server run is a small smoke suite: 17 Rivencraft tests
+The default dedicated-server run is a small smoke suite: 19 Rivencraft tests
 cover core linking, deterministic Age definition, writing persistence, legacy
 data migration, workstation transactions, and forged/replayed menu actions.
-NeoForge currently adds two of its own tests, so the runner reports 19.
+NeoForge currently adds two of its own tests, so the runner reports 21.
 
 ```shell
 ./gradlew runGameTestServer
 ```
 
-The remaining 47 Rivencraft tests are archived, not deleted. They cover
+The remaining 49 Rivencraft tests are archived, not deleted. They cover
 completed milestone details such as every Age terrain profile, Notebook and
 Desk surface interactions, refill edge cases, book assembly controls, and
 workstation break/drop behavior. Run only the relevant archive alongside the
@@ -17,11 +17,11 @@ core tests when investigating an issue:
 
 ```shell
 ./gradlew runGameTestServer -ParchivedGameTestSuites=desk
-./gradlew runGameTestServer -ParchivedGameTestSuites=linking,binder
+./gradlew runGameTestServer -ParchivedGameTestSuites=grammar,binder
 ```
 
-Available suite names are `linking`, `writing`, `desk`, `binder`, `mixer`, and
-`recipe`. Run all 64 Rivencraft tests (66 including NeoForge's two) before a
+Available suite names are `linking`, `writing`, `grammar`, `desk`, `binder`, `mixer`, and
+`recipe`. Run all 68 Rivencraft tests (70 including NeoForge's two) before a
 release or after broad cross-system changes:
 
 ```shell

docs/SYMBOL_SEMANTICS.md

@@ -39,6 +39,6 @@ These are schema bounds, not claims that Legacy shipped numeric config ranges. S
 
 The server rejects a v2 definition with an unknown top-level or semantics field, missing/incorrectly typed field, unknown role or choice, malformed/non-canonical resource ID, or out-of-range/non-finite number. An invalid definition is logged with its file ID and excluded from the active catalog. Saved pages and books still retain that ID, allowing the player to recover them if the data pack is corrected. A reload atomically replaces the catalog rather than mutating saved writing.
 
-Schema v1 definitions remain readable as **display-only** symbols; existing packs need not be rewritten merely to show or copy pages. A v1 definition cannot add a `semantics` field. To make one eligible for future Age compilation, publish a v2 definition with the **same file path and ID**, adding a valid role and value. Do not rename the page ID or reorder a book's `OrderedWriting`. The client receives only `SymbolDisplayMetadata` (ID, translation keys, category, resolved flag); semantic definitions are not serialized to it. This slice defines and validates meaning but does **not yet apply** written symbols to Age generation; issues #30 and #31 implement parsing and compilation.
+Schema v1 definitions remain readable as **display-only** symbols; existing packs need not be rewritten merely to show or copy pages. A v1 definition cannot add a `semantics` field. To make one eligible for Age grammar parsing, publish a v2 definition with the **same file path and ID**, adding a valid role and value. Do not rename the page ID or reorder a book's `OrderedWriting`. The client receives only `SymbolDisplayMetadata` (ID, translation keys, category, resolved flag); semantic definitions are not serialized to it. The [ordered-writing parser](WRITING_GRAMMAR.md) validates new books, but does **not yet apply** written symbols to Age generation; issue #31 adds compilation.
 
 The six built-in definitions demonstrate terrain, biome-controller, lighting, weather, celestial, and feature roles. A third-party pack may add its own definitions under its namespace. Use an explicit semantic role even when the display category has the same name; the two fields serve different purposes.

docs/WRITING_GRAMMAR.md

@@ -0,0 +1,11 @@
+# Ordered Descriptive Book grammar (Milestone 5, issue #30)
+
+`WritingGrammar` interprets the saved `OrderedWriting` on the server using only `SymbolCatalog`'s schema-v2 semantics. Client display metadata, page names, and supplied translations never determine an Age's meaning. The parser is pure: it returns immutable parsed entries and indexed diagnostics without changing a book or its pages.
+
+New Binder writing has at most one Link Panel plus 27 symbol pages. The Link Panel must be first. A Link-Panel-only book, or an older book with no writing component, keeps the existing random Age path. Any authored supported symbol makes the book a partial or complete grammar, even though **0.4.2.0 still generates a random Age**; issue #31 will compile it into a persistent plan before chunk generation.
+
+The supported order follows the representable subset of the [Legacy grammar audit](LEGACY_AGE_GRAMMAR_AUDIT.md): terrain; zero or more biome pages; biome controller; weather; lighting; zero or more period, angle, or phase modifiers; one celestial page; then zero or more distinct features. Biome pages precede the controller that consumes them, and celestial modifiers precede the celestial page. Terrain, controller, weather, lighting, and celestial are single-choice categories; identical repeats are duplicates and differing values conflict. Repeated modifiers are intentional. Biome pages may repeat, preserving author order and any future weighting; feature IDs may not repeat.
+
+Missing terrain, controller, weather, lighting, celestial, or the controller's minimum biome count is an **incomplete** warning, not an error: issue #31 will fill those branches deterministically from the Age seed. The minimum is zero for Native, one for Single, two for Tiled/Grid, and three for Tiny–Huge. Native cannot consume authored biome pages; Single accepts only one. Unknown IDs, schema-v1 display-only symbols, wrong ordering, misplaced modifiers, duplicates, conflicts, missing/extra Link Panels, and oversized writing are errors. The Binder disables output and exposes the first error on the result-slot tooltip. When that error belongs to a page, its thumbnail is tinted and outlined red, the strip scrolls to it, and hovering it shows the diagnostic. This maps the parser's compact entry position back through any empty page positions. Rejected inputs remain removable. Binding an unwritten Descriptive Book rechecks its server-owned writing and reports the first error without creating an Age.
+
+This slice does not score instability, synthesize missing symbols, or apply symbol effects. Those responsibilities belong to issues #31–#35 and Milestone 6. Existing bound books are not revalidated or migrated merely because a data pack changes.