Define server-authoritative symbol semantics (#29)

docs/GAMETESTS.md

@@ -1,15 +1,15 @@
 # GameTest suites
 
-The default dedicated-server run is a small smoke suite: 16 Rivencraft tests
+The default dedicated-server run is a small smoke suite: 17 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 18.
+NeoForge currently adds two of its own tests, so the runner reports 19.
 
 ```shell
 ./gradlew runGameTestServer
 ```
 
-The remaining 46 Rivencraft tests are archived, not deleted. They cover
+The remaining 47 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
@@ -21,7 +21,7 @@ core tests when investigating an issue:
 ```
 
 Available suite names are `linking`, `writing`, `desk`, `binder`, `mixer`, and
-`recipe`. Run all 62 Rivencraft tests (64 including NeoForge's two) before a
+`recipe`. Run all 64 Rivencraft tests (66 including NeoForge's two) before a
 release or after broad cross-system changes:
 
 ```shell

docs/SYMBOL_SEMANTICS.md

@@ -0,0 +1,39 @@
+# Server-authoritative symbol semantics (schema v2)
+
+Milestone 5 issue #29 adds typed meaning to the existing data-pack symbol catalog. Put definitions at `data/<namespace>/rivencraft/symbols/<path>.json`; the file ID becomes the stable symbol ID. For example, `data/example/rivencraft/symbols/terrain/highlands.json` defines `example:terrain/highlands`:
+
+```json
+{
+  "schema_version": 2,
+  "name": "symbol.example.terrain.highlands",
+  "description": "symbol.example.terrain.highlands.description",
+  "category": "example:terrain",
+  "semantics": {
+    "role": "terrain",
+    "value": "example:highlands"
+  }
+}
+```
+
+`name` and `description` are translation keys. `category` is for display and sorting; it does not determine grammar. `semantics.role` and its typed `value` are server-owned. The terrain value above names an Age runtime profile that a later compiler must resolve and validate. A syntactically valid resource ID alone does not guarantee the profile or feature exists.
+
+| Role | Value type and allowed values |
+| --- | --- |
+| `terrain` | Canonical namespaced Age profile ID. |
+| `biome_controller` | `native`, `single`, `tiled`, `grid`, `tiny`, `small`, `medium`, `large`, or `huge`. |
+| `biome` | Canonical namespaced biome ID. |
+| `lighting` | `normal`, `dark`, or `bright`. |
+| `weather` | `normal`, `fast`, `slow`, `off`, `always`, `cloudy`, `rain`, `snow`, or `storm`. |
+| `celestial` | `normal_time` (the first representable single-cycle behavior). |
+| `period_modifier` | JSON number in `[0, 2]`; zero is stopped time. |
+| `angle_modifier` | JSON number in `[0, 360)` degrees. |
+| `phase_modifier` | JSON number in `[0, 360)` degrees; the compiler will convert to turns. |
+| `feature` | Canonical namespaced feature-effect ID; future generation mapping must recognize it. |
+
+These are schema bounds, not claims that Legacy shipped numeric config ranges. See the [Legacy grammar audit](LEGACY_AGE_GRAMMAR_AUDIT.md) for the source values and biome-count rules. Roles outside this table—including multiple suns, gradients, special structures, and hazards—are intentionally unsupported by schema v2. Their meaning requires a later versioned extension, not an unvalidated free-form field.
+
+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.
+
+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_DATA.md

@@ -27,13 +27,17 @@ Schema version 1 contains display metadata only:
 
 `name` and `description` are translation keys, not arbitrary formatted text or
 executable behavior. `category` is a namespaced organizational identifier.
+Milestone 5 adds [server-authoritative schema v2 semantics](SYMBOL_SEMANTICS.md)
+with a typed role and bounded value. Existing v1 definitions remain readable
+but display-only; updating an ID to v2 never rewrites saved pages or books.
 Invalid definitions are logged and excluded by the server. Menus and future
 page synchronization must obtain resolved display metadata from the server;
 clients never make a symbol valid by naming it.
 
 Rivencraft ships a small catalog covering terrain, biomes, lighting, weather,
-celestial behavior, and features. It exists to exercise the complete writing
-workflow before Milestone 5 implements the full legacy grammar.
+celestial behavior, and features. Its v2 semantics prepare for the full
+Legacy-inspired grammar; writing still uses random Age fallback until the
+parser and compiler are implemented.
 
 ## Persistent writing