docs: rewrite roadmap and update handover to OTIVM-III state

docs/roadmap.md

@@ -1,39 +1,12 @@
-> ⚠ **THIS ROADMAP NEEDS REWRITING — 2026-04-27**
+> ⚠ **SECTION 4 REWRITTEN — 2026-05-02**
 >
 > The vision (Sections 1–3) and design principles (Section 5) remain
-> valid. **Section 4 ("What exists today") is stale and must not be
-> treated as current.** Specifically:
+> valid. Section 4 ("What exists today") has been updated to reflect
+> actual state as of 2026-05-02. The previous stale version described
+> a decommissioned pipeline node and an OTIVM-III scope that has since
+> been redefined. See git log for the prior version.
 >
-> **1. The global tessera.db no longer exists on a reachable server.**
-> The Dell pipeline node has been decommissioned. The TESSERA 4.0
-> architecture replaces the global database with a per-hex pipeline
-> that writes directly to `data/otivm.sqlite3`. New hexes are added
-> one H5 at a time by the dataset assistant as the game expands.
-> References to "TESSERA global pipeline", "Stage 05 running",
-> "assembling on Dell pipeline node" are all obsolete.
->
-> **2. The roadmap does not mention the restoration layer.**
-> `terrain` in `data/otivm.sqlite3` is modern WorldCover 2021 data.
-> It is wrong for any historical period. The Mediterranean was 60–70%
-> forested in Roman times and Mesolithic times. The restoration layer
-> (HYDE 3.3 + KK10 datasets) will correct terrain to historically
-> appropriate values when it is built. Until then, no release may
-> present terrain data as historically accurate. This is a significant
-> gap in the roadmap that affects the scope of OTIVM-III through
-> OTIVM-VI.
->
-> **3. Release numbering is out of date.**
-> OTIVM-III in this roadmap describes "The Factor" (NPC model). The
-> actual next release must first establish the SQLite server connection
-> and replace the placeholder map coastline. The Factor is deferred
-> until after the database and map work is complete. Discuss with the
-> project owner before acting on any release scope in this document.
->
-> **The roadmap rewrite is the first task for the game development
-> assistant. Do not write code until the roadmap is current and
-> approved by the project owner.**
->
-> Current state is accurately described in `docs/handover-game-dev.md`.
+> **Current state is accurately described in `docs/handover-game-dev.md`.**
 > Dataset state is in `docs/handover-dataset.md`.
 > Full dataset inventory and triage is in `docs/TESSERA-dataset-registry.md`.
 
@@ -67,14 +40,50 @@ The game saves per player. Up to 128 concurrent players share one server.
 ### OTIVM-II — The Map
 *The Mediterranean becomes visible.*
 
-The five waypoints become real places on a rendered map. Routes are drawn on it. Distance is meaningful. You can see where your galley is. The map uses H3 hexagonal geometry — the same grid that underlies TESSERA, the physical world model that will power everything that follows. At this resolution the hexes are invisible to the player. They are infrastructure.
+The five waypoints become real places on a rendered map. Routes are drawn on it. Distance is meaningful. You can see where your galley is. The map uses H3 hexagonal geometry — the same grid that underlies TESSERA, the physical world model that powers everything that follows. At this resolution the hexes are invisible to the player. They are infrastructure.
 
 ---
 
-### OTIVM-III — The Factor
-*You hire your first agent.*
+### OTIVM-III — The Database
+*Player state becomes a record.*
 
-A factor appears — an NPC with a name, a journal voice, and a personality. He can run a route while you run another. He can also fail: fall ill, be robbed, make a bad deal. Managing him is different from managing a galley. He has opinions. This is the first Constructor — the character model inherited from the CIVICVS Mesolithic Simulator, now running in the Roman world.
+Per-player JSON save files are replaced by per-player SQLite databases
+at `data/saves/{token}.sqlite3`. The schema is defined by
+`data/create_player_db.sql` and the parameter registry. The frontend
+does not change. The API surface does not change. The data structure
+beneath becomes correct.
+
+Three changes only:
+
+1. **Backend:** `better-sqlite3` opens or creates the player database
+   on first access, seeding `actor_parameters` from
+   `background_starting_values` based on the chosen background. The
+   `GET /api/save/:token` and `POST /api/save/:token` endpoints remain
+   unchanged in interface.
+
+2. **Migration:** On first access, if a `.json` save exists but no
+   `.sqlite3` exists, the JSON is imported into the new schema
+   transparently. JSON files are left in place as reference — never
+   deleted.
+
+3. **Parameter initialisation:** On new game creation, the player
+   chooses a background. The six canonical backgrounds seed twelve
+   actor parameters into `actor_parameters` with correct
+   `value_true`, `value_perceived`, `confidence_tag`, and
+   `observable_level` fields. `auctoritas` carries `value_social`
+   as a third record. No parameter is flattened to a single integer.
+
+This is the release that makes the parameter registry live in gameplay.
+The player sees nothing different. The behavioral record becomes real.
+
+**Known constraints at OTIVM-III:**
+- Terrain in `data/otivm.sqlite3` is ESA WorldCover 2021 — modern
+  data, not historical. No release may present terrain as historically
+  accurate until the restoration layer (HYDE 3.3 + KK10) is built.
+- Map coastline is five isolated H5 clusters. Route corridor H5 hexes
+  are not yet in the database. The map is correct at waypoints only.
+- The per-hex pipeline (RFC-TESSERA-4.0-001) is designed but not coded.
+  New waypoints cannot be added without building it.
 
 ---
 
@@ -109,7 +118,7 @@ The Mediterranean expands. New routes appear beyond the five original chapters.
 ### OTIVM-VIII — The Deep Past
 *The Mesolithic world surfaces.*
 
-Goods that originate in the far north carry traces of the cultures that first moved them. The amber road, the flint from the Pyrenean foothills, the ochre from ridge deposits — each traceable through TESSERA's occupation evidence layer (byte 7, OCC_FLAG) to one of the four launch Mesolithic cultures: Maglemosian, Ertebølle, Sauveterrian, Azilian. The Roman merchant does not know what Mesolithic means. He knows the amber is old. The player can look it up. The data is citable.
+Goods that originate in the far north carry traces of the cultures that first moved them. The amber road, the flint from the Pyrenean foothills, the ochre from ridge deposits — each traceable through TESSERA's occupation evidence layer (byte 7, OCC_FLAG) to one of the four launch Mesolithic cultures: Maglemoisian, Ertebølle, Sauveterrian, Azilian. The Roman merchant does not know what Mesolithic means. He knows the amber is old. The player can look it up. The data is citable.
 
 ---
 
@@ -146,7 +155,7 @@ Every field value is traceable to a named, versioned, citable source dataset. Ev
 
 ### The simulation layer — CIVICVS
 
-CIVICVS is a Mesolithic narrative simulator set in ~8000 BCE, Spree-Havel valley, Berlin (52.5°N, 13.4°E). It runs on TESSERA's physical substrate. Real Berlin weather data from DWD, delayed 6–12 hours, drives atmospheric conditions. Characters (Constructors) have knowledge, relationships, and skills gated by corpus chunks embedded as vectors in ChromaDB. The corpus is academically grounded in Maglemosian, Ertebølle, Sauveterrian, and Azilian material culture.
+CIVICVS is a Mesolithic narrative simulator set in ~8000 BCE, Spree-Havel valley, Berlin (52.5°N, 13.4°E). It runs on TESSERA's physical substrate. Real Berlin weather data from DWD, delayed 6–12 hours, drives atmospheric conditions. Characters (Constructors) have knowledge, relationships, and skills gated by corpus chunks embedded as vectors in ChromaDB. The corpus is academically grounded in Maglemoisian, Ertebølle, Sauveterrian, and Azilian material culture.
 
 CIVICVS establishes the session model, the Constructor model, and the weather integration that OTIVM will inherit in releases IV and IX.
 
@@ -162,23 +171,63 @@ Azgaar's Fantasy Map Generator produces GeoJSON and SVG exports of political geo
 
 ---
 
-## 4. What exists today
+## 4. What exists today — 2026-05-02
 
-> ⚠ **This section is stale as of 2026-04-27. See warning at top of
-> document. Do not treat as current. The roadmap rewrite will replace
-> this section.**
+These are verifiable claims about what is built and running.
 
-These are verifiable claims about what was built and running as of April 2026 — before the architecture change to TESSERA 4.0 per-hex pipeline.
+**TESSERA scoped dataset:** `data/otivm.sqlite3` — 12,005 H9 rows
+across five Mediterranean waypoints, all `status=2`. `paleo_epochs`
+table populated with 9 epochs per RFC-TESSERA-3.0-PALEO-001. Schema
+follows RFC-TESSERA-4.0-001: integer H3 IDs, per-field provenance FKs,
+lifecycle states, row-never-deleted model. Five fields populated:
+`elev_cm`, `terrain`, `hydro`, `geo_dep`, `geo_flag`. `occ_flag` is
+placeholder (0x00) — Stage 06 not yet written.
 
-**TESSERA global pipeline:** Stages 00–04 complete. Elevation, terrain, hydrology, geology flag, and geology deposit encoded for 8,591,961 H7 tiles. Stage 05 (geology assembly) crashed at 97.3% and was abandoned. Stage 06 (culture sampling) not written. Global SpatiaLite database (tessera.db) on Dell pipeline node — decommissioned.
-
-**TESSERA 4.0 scoped dataset:** `data/otivm.sqlite3` — 12,005 H9 rows across five Mediterranean waypoints, all `status=2`. `paleo_epochs` table populated with 9 epochs. Per-hex pipeline not yet built — see `docs/handover-dataset.md`.
+**TESSERA global pipeline:** The Dell pipeline node has been
+decommissioned. The TESSERA 4.0 architecture replaces the global
+database with a per-H5 pipeline that writes directly to
+`data/otivm.sqlite3`. The per-H5 pipeline is designed in
+RFC-TESSERA-4.0-001 but not yet coded. Four datasets pending local
+download before pipeline work begins: BGR IGME5000, HYDE 3.3, KK10,
+HydroRivers.
 
 **TESSERA API:** Not yet deployed.
 
-**CIVICVS Simulator:** Shell API operational. Corpus in ChromaDB. Map and Scene containers in development. Real weather integration specified, not yet running continuously.
+**CIVICVS Simulator:** Shell API operational. Corpus in ChromaDB. Map
+and Scene containers in development. Real weather integration
+specified, not yet running continuously.
 
-**OTIVM:** Live at `otium.civicus.us`. OTIVM-I and OTIVM-II complete. See `docs/handover-game-dev.md` for current state.
+**OTIVM:** Live at `otium.civicus.us`. OTIVM-I and OTIVM-II complete
+and live. See `docs/handover-game-dev.md` for current game state.
+
+**Per-player SQLite schema:** `data/create_player_db.sql` committed
+at `17e82d0`. Eight tables: `actor_profile`, `actor_parameters`,
+`parameter_drift_log`, `ventures`, `venture_legs`, `scenario_state`,
+`events`, `background_starting_values`. Seeded with 72 rows (12
+parameters × 6 backgrounds). Validated clean. Not yet wired into the
+backend — that is OTIVM-III.
+
+**Parameter registry:** `docs/parameter-registry.md` — 12 canonical
+actor parameters plus city, scenario, and relation parameters.
+`docs/parameter-registry-additions.md` — 44 additional tokens derived
+from full corpus review (law, commerce, economy dialogues). Both
+committed and approved.
+
+**Corpus:** 20 Layer 0 primitive facts, 5 Layer 1 worked examples,
+1 sketch in `docs/training/corpus/`. 37 dialogues across
+`docs/economy/`, `docs/law/`, `docs/commerce/` — all reviewed,
+sanitized, and cleared. `commerce_chunks.jsonl` — 230 training chunks,
+5 layers, evaluated and approved.
+
+**Known gaps that constrain future releases:**
+- Terrain in `data/otivm.sqlite3` is ESA WorldCover 2021 (modern).
+  Restoration layer (HYDE 3.3 + KK10) not yet built. No release may
+  present terrain as historically accurate until this is resolved.
+- Map coastline is five isolated H5 clusters. Route corridor H5 hexes
+  are not in the database. The map is geographically correct at
+  waypoints only.
+- `occ_flag` is placeholder everywhere — occupation evidence layer
+  (RFC-TESSERA-3.0-OCC-001) not yet populated.
 
 ---
 
@@ -190,8 +239,9 @@ These are verifiable claims about what was built and running as of April 2026
 - **No vaporware in public documentation.** Section 4 of this document is the template. Every public claim is either running, committed, or explicitly marked as planned.
 - **The data warehouse is the product.** The game is the public interface. The substrate is the value.
 - **Real weather only.** DWD data always. No simulated weather.
-- **JSON flat files for local state.** No database on the OTIVM container for player saves. Save files are per-player JSON. A shared database is a future convergence-layer problem.
+- **Per-player SQLite for player state.** `data/saves/{token}.sqlite3` per player, created from `data/create_player_db.sql`. Write-safe: one writer per file, any number of readers. JSON save files remain in place as reference — never deleted.
 - **BSD 2-Clause license.** The code is open. The data pipeline methodology is open. Academic scrutiny is welcome.
+- **Design one step ahead.** No release is planned beyond the next confirmed step. Everything is a first-time experiment. Prediction beyond one step is speculation.
 
 ---