From 84197b67ad5d825a91eeef205a6c5281609d81d4 Mon Sep 17 00:00:00 2001 From: otivm Date: Sat, 2 May 2026 10:13:29 +0000 Subject: [PATCH] docs: rewrite roadmap and update handover to OTIVM-III state --- docs/handover-game-dev.md | 174 +++++++++++++++++++++----------------- docs/roadmap.md | 150 +++++++++++++++++++++----------- 2 files changed, 196 insertions(+), 128 deletions(-) diff --git a/docs/handover-game-dev.md b/docs/handover-game-dev.md index b0e0560..89db2fb 100644 --- a/docs/handover-game-dev.md +++ b/docs/handover-game-dev.md @@ -1,5 +1,5 @@ # Handover — OTIVM Game Development -### Date: 2026-04-28 +### Date: 2026-05-02 ### For: Incoming assistant (game development track) ### Read this completely before doing anything @@ -29,13 +29,14 @@ In order: 2. `docs/architecture/infrastructure.md` — container topology, API protocol 3. `docs/architecture/terminology.md` — three-layer vocabulary, naming convention 4. `docs/architecture/latin-bridge.md` — Latin terms, admission standard, semantic entries -5. `docs/architecture/parameter-registry.md` — all simulation parameters, scope, layer, maturity -6. `docs/actors/CHARACTER-FRAMEWORK.md` — six backgrounds, twelve starting parameters -7. `docs/scenarios/SCENARIO-MERCHANT-0000.md` — the BALNEA prologue, background selection -8. `docs/scenarios/SCENARIO-MERCHANT-0001.md` through `0003.md` — the founding trilogy -9. `docs/cities/CITY-OSTIA-0001.md` — Ostia as pressure field, not backdrop -10. `docs/roadmap.md` — where the game is going (warning: body is stale, vision and principles still valid) -11. This file +5. `docs/parameter-registry.md` — canonical parameters, scope, layer, maturity +6. `docs/parameter-registry-additions.md` — 44 additional tokens from corpus review +7. `docs/actors/CHARACTER-FRAMEWORK.md` — six backgrounds, twelve starting parameters +8. `docs/scenarios/SCENARIO-MERCHANT-0000.md` — the BALNEA prologue, background selection +9. `docs/scenarios/SCENARIO-MERCHANT-0001.md` through `0003.md` — the founding trilogy +10. `docs/cities/CITY-OSTIA-0001.md` — Ostia as pressure field, not backdrop +11. `docs/roadmap.md` — where the game is going +12. This file The parameter registry is the bridge between the design documents and the schema. Read it before touching any database code. @@ -77,6 +78,21 @@ one write domain per container, no shared filesystems between containers. - Branch: `main` (direct push, Claude Code handles this) - MCP: connected via `mcp.civicus.us` — Claude chat reads any file directly +### Git protocol — mandatory, non-negotiable +Before touching any file: +``` +git fetch origin main +git merge origin/main +``` +After making changes: +``` +git add [specific named files only — never git add .] +git commit -m "scope: description" +git push origin main +``` +NEVER: `--rebase`, `--force`, `git stash`, `git reset --hard`, `git add .` +NEVER: commit without fetching and merging first. + ### Backups - Command: `vzdump 1105 --compress zstd --storage local --mode snapshot` on srv-a (root shell) - Document every backup in `docs/archives.md` immediately after — see existing entries for format @@ -89,15 +105,20 @@ one write domain per container, no shared filesystems between containers. - React 19 + Vite 8 frontend (`src/`) - Fastify backend (`server/index.js`) — serves `dist/`, save API, TESSERA map endpoint -- `data/otivm.sqlite3` — TESSERA physical data, read-only by game server -- `data/saves/` — per-player JSON save files (gitignored) -- `better-sqlite3` installed — used by server for TESSERA queries +- `data/otivm.sqlite3` — TESSERA physical data, read-only by game server (`better-sqlite3`) +- `data/saves/` — per-player save files (gitignored) + - OTIVM-I/II: `{token}.json` + - OTIVM-III+: `{token}.sqlite3` (created from `data/create_player_db.sql`) + - Both formats coexist during migration. JSON files are never deleted. +- `data/create_otivm_db.sql` — TESSERA world schema (read-only reference) +- `data/create_player_db.sql` — per-player schema (OTIVM-III, committed at 17e82d0) +- `better-sqlite3` installed — used by server for TESSERA queries and player databases - PM2 under `otivm` user (never root) - Ecosystem file: `ecosystem.config.cjs` --- -## 4. Current game state — as of 2026-04-28 +## 4. Current game state — as of 2026-05-02 ### OTIVM-I — complete Five trade routes Ostia → Alexandria, journal, otium/negotium mechanic, @@ -123,60 +144,54 @@ per-player saves via 8-char hex token, 128 concurrent players supported. - Sea hexes are dark by definition — no data, no storage - `session_abandoned` event — saves are never deleted, they receive a terminal event - REST API for all inter-container data flows — no shared filesystems -- Per-player SQLite (128 files) replacing JSON saves — planned for OTIVM-III +- Per-player SQLite replacing JSON saves — schema committed, wiring is OTIVM-III + +### OTIVM-III — schema committed, wiring not yet started + +**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`. Pre-seeded with 72 rows (12 parameters × +6 backgrounds). Validated clean. + +**What OTIVM-III requires — in order:** + +1. **Backend wiring:** `server/index.js` opens or creates + `data/saves/{token}.sqlite3` using `create_player_db.sql` on first + access. Same `GET/POST /api/save/:token` interface — frontend does + not change. + +2. **JSON migration:** On `GET /api/save/:token`, if `{token}.json` + exists but `{token}.sqlite3` does not, import JSON into SQLite + automatically. One-time, transparent to the player. JSON files + left in place — never deleted. + +3. **Parameter initialisation:** On new game creation, player chooses + background. Seed `actor_parameters` from `background_starting_values` + for the chosen background. `value_true`, `value_perceived`, + `confidence_tag`, and `observable_level` all correctly populated. + `auctoritas` gets `value_social` as a third record. No parameter + flattened to a single integer. + +**Non-negotiable schema rules (from parameter-registry.md):** +- `value_true` and `value_perceived` are always separate columns +- `confidence_tag` is always a first-class column, never a comment +- `auctoritas` has three records: `value_true`, `value_perceived`, `value_social` +- Timestamp column is always `recorded_at` +- Rows are never deleted — only archived or superseded +- Scenario parameters must not leak into actor parameters as permanent values ### Known deferred items - Journal local state does not reset on new game (React state issue, low priority) - H7 cells rendered as circles — hex geometry deferred pending client-side h3-js - Map coastline is five isolated H5 clusters — route corridor coverage deferred to OTIVM-III+ -- Roadmap body is stale — rewrite planned under project owner direction +- Terrain in `data/otivm.sqlite3` is modern WorldCover — restoration layer (HYDE 3.3 + KK10) not yet built. No release may present terrain as historically accurate. --- -## 5. OTIVM-III — defined, not yet started +## 5. Design corpus -OTIVM-III is the data plumbing release. Three things: - -**1. Per-player SQLite — 128 pre-provisioned databases** - -Replace JSON save files in `data/saves/` with SQLite databases in -`data/players/`. Pre-provision all 128 at container setup — no database -created on demand under player load. The schema is defined by the parameter -registry and the SQLite schema document (pending — this is the next -document to be produced). - -The atomic unit is **time**. The database is a time-series of events. -Current parameter values are derived from event history. The schema must -treat uncertainty, confidence, and perceived-vs-true values as first-class -records, not comments. - -**2. RATIONES tab — the third screen** - -Add a third tab alongside Ledger and Map. This is the disaggregated -accounts — the line items of every NEGOTIVM. Not a dashboard. A Roman -merchant's RATIONES: what was spent at each ITER, on what, at what rate. - -The player sees a historically authentic accounting surface. The system -records parameters beneath it. Raw parameter values remain hidden or -available only in advanced view. - -**3. Internal API for aggregation (1103)** - -1105 exposes an internal endpoint that 1103 can call on a schedule to -collect player event snapshots for aggregation. Anonymised behavioral -data only — no save file contents transferred raw. - -**Before any OTIVM-III code is written:** -Read `docs/architecture/parameter-registry.md` in full. The schema -must not flatten AVCTORITAS into an integer. Uncertainty, observability, -and perceived-vs-true are structural requirements, not optional features. - ---- - -## 6. Design corpus — what ChatGPT produced this session - -The following documents were produced in collaboration with ChatGPT and -represent the design substrate for OTIVM-III and beyond. Read them in order. +The following documents are the design substrate for OTIVM-III and beyond. **Scenarios** (`docs/scenarios/`): - `SCENARIO-MERCHANT-0000.md` — The BALNEA Conversation (prologue, background selection) @@ -184,35 +199,36 @@ represent the design substrate for OTIVM-III and beyond. Read them in order. - `SCENARIO-MERCHANT-0002.md` — The Capuan Timber Yard Fire (upstream choke-point logic) - `SCENARIO-MERCHANT-0003.md` — The FAENUS Offer (capital without cargo) -These form a trilogy with a prologue. Each success condition is sharper -than the last. The trilogy teaches: event → dependencies → price → capital. - **Actors** (`docs/actors/`): - `CHARACTER-FRAMEWORK.md` — twelve parameters, hidden traits, background rules - `BACKGROUND-0001` through `BACKGROUND-0006` — six asymmetric starting lives -These are not classes. They are starting parameter profiles that drift -toward decision history over time (`background_drift` parameter). - **Cities** (`docs/cities/`): - `CITY-OSTIA-0001.md` — Ostia substrate: urban zones, population model, infrastructure parameters, social nodes, daily and seasonal rhythm -Ostia functions as a pressure field. It is not scenery. Every parameter -in the city document connects to actor parameters and scenario triggers. - **Architecture** (`docs/architecture/`): - `infrastructure.md` — settled container topology and API protocol - `terminology.md` — three-layer vocabulary, rejected terms, naming rules - `latin-bridge.md` — Latin term admission standard and full semantic entries -- `research-brief-roman-venture.md` — ChatGPT research instructions - `parameter-registry.md` — all parameters, scope, layer, maturity +- `parameter-registry-additions.md` — 44 additional tokens from corpus review + +**Corpus** (`docs/training/corpus/`): +- 20 Layer 0 primitive facts (commerce domain) +- 5 Layer 1 worked examples +- 1 sketch awaiting promotion +- `commerce_chunks.jsonl` — 230 training chunks, 5 layers + +**Law and commerce dialogues** (`docs/law/`, `docs/commerce/`, `docs/economy/`): +- 37 dialogues reviewed, sanitized, and cleared for use +- Source material for the parameter registry additions --- -## 7. The SVCCINUM thread +## 6. The SVCCINVM thread -The amber (`SVCCINUM`) in the grain route cargo is not merely a goods label. +The amber (`SVCCINVM`) in the grain route cargo is not merely a goods label. It is the first explicit connection between OTIVM and CIVICVS. The amber originated in Maglemoisian forests in approximately 8000 BCE — the same territory and period that CIVICVS models. When both simulations share a @@ -220,7 +236,7 @@ TESSERA substrate, the amber in the MERCATOR's hold will be traceable to a specific H3 cell where a CIVICVS Constructor gathered or traded it. This thread runs through the `origin_h3_r5` provenance stub in `constants.js`, -through the SVCCINUM entry in `latin-bridge.md`, through the `occ_flag` stub +through the SVCCINVM entry in `latin-bridge.md`, through the `occ_flag` stub parameter in the registry, through to OTIVM-VIII and OTIVM-IX. Do not lose this thread. It is the architectural consequence of building @@ -228,7 +244,7 @@ both systems on the same physical reality layer from the start. --- -## 8. Workflow — one file, one step, one confirmation +## 7. Workflow — one file, one step, one confirmation Every change follows this sequence without exception: @@ -242,28 +258,30 @@ Every change follows this sequence without exception: --- -## 9. Hard rules +## 8. Hard rules - Never run PM2 as root — always as otivm user - Never commit secrets — no tokens, no keys, no passwords - Never push to main without building — `npm run build` must pass first -- JSON flat files for player state — until OTIVM-III replaces them with SQLite +- Per-player SQLite for player state — `data/saves/{token}.sqlite3` from `data/create_player_db.sql` +- JSON saves coexist during migration — never deleted, never overwritten - H3 IDs on every location — never a coordinate pair or string name alone - Never make assumptions about disk state — always read from Gitea MCP first - Uncertainty is a first-class record, not a comment — applies to all schema work - The data warehouse is the product — the game is the public interface - Real weather only in CIVICVS — DWD data always, no simulation +- Design one step ahead — no release planned beyond the next confirmed step --- -## 10. Commit message convention +## 9. Commit message convention Imperative mood, present tense, under 72 characters. `Add Mediterranean SVG map to Map screen` not `Added map`. --- -## 11. What the dataset assistant is doing in parallel +## 10. What the dataset assistant is doing in parallel See `docs/handover-dataset.md` for full detail. Current state: @@ -271,13 +289,13 @@ See `docs/handover-dataset.md` for full detail. Current state: - `staging_otivm.sqlite3` in sync - Pipeline venv provisioned at `/home/otivm/pipeline-venv` - Four datasets pending download to Drive 1 (BGR IGME5000, HYDE 3.3, KK10, HydroRivers) -- Per-H5 pipeline architecture not yet designed — next dataset session task +- Per-H5 pipeline architecture designed (RFC-TESSERA-4.0-001), not yet coded -When `otium.sqlite3` is expanded with new H5 hexes (OTIVM-III first new +When `otivm.sqlite3` is expanded with new H5 hexes (OTIVM-III first new waypoint), the game development assistant will be told. The `/api/map/:h5/:epoch` endpoint requires no changes — it is already parameterised by H5 ID. --- -*Handover 2026-04-28 — game development track* +*Handover 2026-05-02 — game development track* *Claude chat designs. Claude Code implements. The human decides.* diff --git a/docs/roadmap.md b/docs/roadmap.md index 17df760..6ea0bdf 100644 --- a/docs/roadmap.md +++ b/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. ---