Define writing and symbol data model (#17)

docs/PORTING.md

@@ -34,6 +34,7 @@ acceptance issue and all required implementation issues are complete.
    renderer compatibility. **Complete.** See
    [Milestone 3](https://gitea.tail180fb1.ts.net/dnorberg/rivencraft/milestone/8).
 4. **Writing system** — pages, symbols, notebooks, desks, and book assembly.
+   **In progress.**
 5. **Age grammar** — translate symbol combinations into modern biome, noise,
    dimension-type, and world-generation configuration. Optional integrations
    may add composable biome regions and seasonal behavior.
@@ -61,6 +62,11 @@ The writing system and Age grammar will build on the existing page-free Age
 path. Page-free books remain a useful deterministic fallback and test fixture
 after written symbol combinations become available.
 
+Milestone 4 begins with a versioned, data-pack-defined symbol catalog and an
+immutable ordered-writing model. See [WRITING_DATA.md](WRITING_DATA.md). These
+contracts preserve unknown symbol identifiers and store author intent; they do
+not interpret symbols into Age generation, which remains Milestone 5 work.
+
 ## Provenance rules
 
 - New code uses the `net.dnorberg.rivencraft` package.

docs/WRITING_DATA.md

@@ -0,0 +1,46 @@
+# Writing and symbol data
+
+Milestone 4 stores what a player wrote without deciding what that writing does
+to an Age. Milestone 5 owns grammar validation, symbol interaction, instability,
+and translation into biome, noise, dimension-type, and other world-generation
+configuration.
+
+## Symbol catalog
+
+The authoritative server catalog loads JSON resources from
+`data/<namespace>/rivencraft/symbols/<path>.json`. The resource ID is the
+symbol ID. For example, `data/rivencraft/rivencraft/symbols/terrain/standard.json`
+defines `rivencraft:terrain/standard`.
+
+Schema version 1 contains display metadata only:
+
+```json
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.terrain.standard",
+  "description": "symbol.rivencraft.terrain.standard.description",
+  "category": "rivencraft:terrain"
+}
+```
+
+`name` and `description` are translation keys, not arbitrary formatted text or
+executable behavior. `category` is a namespaced organizational identifier.
+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.
+
+## Persistent writing
+
+`SymbolReference` stores only a namespaced symbol ID. `WritingEntry` is either
+a symbol reference or a baseline link-panel marker. `OrderedWriting` retains up
+to 256 entries in exact player-authored order. All three contracts have both
+persistent codecs and bounded network codecs.
+
+Removing a data pack never removes its IDs from saved writing. A missing ID is
+resolved as client-safe **Unresolved Symbol** display metadata while retaining
+the original namespaced ID for diagnostics and later restoration. This is
+deliberately different from treating an unknown symbol as valid grammar.