TheRON/otivm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
otivm
2026-05-02 10:13:29 +00:00
parent 17e82d01b8
commit 84197b67ad
2 changed files with 196 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
docs/handover-game-dev.md
View File

@@ -1,5 +1,5 @@
# Handover — OTIVM Game Development # Handover — OTIVM Game Development
### Date: 2026-04-28 ### Date: 2026-05-02
### For: Incoming assistant (game development track) ### For: Incoming assistant (game development track)
### Read this completely before doing anything ### Read this completely before doing anything
@@ -29,13 +29,14 @@ In order:
2. `docs/architecture/infrastructure.md` — container topology, API protocol 2. `docs/architecture/infrastructure.md` — container topology, API protocol
3. `docs/architecture/terminology.md` — three-layer vocabulary, naming convention 3. `docs/architecture/terminology.md` — three-layer vocabulary, naming convention
4. `docs/architecture/latin-bridge.md` — Latin terms, admission standard, semantic entries 4. `docs/architecture/latin-bridge.md` — Latin terms, admission standard, semantic entries
5. `docs/architecture/parameter-registry.md` — all simulation parameters, scope, layer, maturity 5. `docs/parameter-registry.md` — canonical parameters, scope, layer, maturity
6. `docs/actors/CHARACTER-FRAMEWORK.md` — six backgrounds, twelve starting parameters 6. `docs/parameter-registry-additions.md` — 44 additional tokens from corpus review
7. `docs/scenarios/SCENARIO-MERCHANT-0000.md` — the BALNEA prologue, background selection 7. `docs/actors/CHARACTER-FRAMEWORK.md` — six backgrounds, twelve starting parameters
8. `docs/scenarios/SCENARIO-MERCHANT-0001.md` through `0003.md` — the founding trilogy 8. `docs/scenarios/SCENARIO-MERCHANT-0000.md` — the BALNEA prologue, background selection
9. `docs/cities/CITY-OSTIA-0001.md` — Ostia as pressure field, not backdrop 9. `docs/scenarios/SCENARIO-MERCHANT-0001.md` through `0003.md` — the founding trilogy
10. `docs/roadmap.md` — where the game is going (warning: body is stale, vision and principles still valid) 10. `docs/cities/CITY-OSTIA-0001.md` — Ostia as pressure field, not backdrop
11. This file 11. `docs/roadmap.md` — where the game is going
12. This file
The parameter registry is the bridge between the design documents and the The parameter registry is the bridge between the design documents and the
schema. Read it before touching any database code. 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) - Branch: `main` (direct push, Claude Code handles this)
- MCP: connected via `mcp.civicus.us` — Claude chat reads any file directly - 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 ### Backups
- Command: `vzdump 1105 --compress zstd --storage local --mode snapshot` on srv-a (root shell) - 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 - 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/`) - React 19 + Vite 8 frontend (`src/`)
- Fastify backend (`server/index.js`) — serves `dist/`, save API, TESSERA map endpoint - Fastify backend (`server/index.js`) — serves `dist/`, save API, TESSERA map endpoint
- `data/otivm.sqlite3` — TESSERA physical data, read-only by game server - `data/otivm.sqlite3` — TESSERA physical data, read-only by game server (`better-sqlite3`)
- `data/saves/` — per-player JSON save files (gitignored) - `data/saves/` — per-player save files (gitignored)
- `better-sqlite3` installed — used by server for TESSERA queries - 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) - PM2 under `otivm` user (never root)
- Ecosystem file: `ecosystem.config.cjs` - 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 ### OTIVM-I — complete
Five trade routes Ostia → Alexandria, journal, otium/negotium mechanic, 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 - Sea hexes are dark by definition — no data, no storage
- `session_abandoned` event — saves are never deleted, they receive a terminal event - `session_abandoned` event — saves are never deleted, they receive a terminal event
- REST API for all inter-container data flows — no shared filesystems - 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 ### Known deferred items
- Journal local state does not reset on new game (React state issue, low priority) - 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 - 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+ - 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: The following documents are the design substrate for OTIVM-III and beyond.
**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.
**Scenarios** (`docs/scenarios/`): **Scenarios** (`docs/scenarios/`):
- `SCENARIO-MERCHANT-0000.md` — The BALNEA Conversation (prologue, background selection) - `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-0002.md` — The Capuan Timber Yard Fire (upstream choke-point logic)
- `SCENARIO-MERCHANT-0003.md` — The FAENUS Offer (capital without cargo) - `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/`): **Actors** (`docs/actors/`):
- `CHARACTER-FRAMEWORK.md` — twelve parameters, hidden traits, background rules - `CHARACTER-FRAMEWORK.md` — twelve parameters, hidden traits, background rules
- `BACKGROUND-0001` through `BACKGROUND-0006` — six asymmetric starting lives - `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/`): **Cities** (`docs/cities/`):
- `CITY-OSTIA-0001.md` — Ostia substrate: urban zones, population model, - `CITY-OSTIA-0001.md` — Ostia substrate: urban zones, population model,
infrastructure parameters, social nodes, daily and seasonal rhythm 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/`): **Architecture** (`docs/architecture/`):
- `infrastructure.md` — settled container topology and API protocol - `infrastructure.md` — settled container topology and API protocol
- `terminology.md` — three-layer vocabulary, rejected terms, naming rules - `terminology.md` — three-layer vocabulary, rejected terms, naming rules
- `latin-bridge.md` — Latin term admission standard and full semantic entries - `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.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 It is the first explicit connection between OTIVM and CIVICVS. The amber
originated in Maglemoisian forests in approximately 8000 BCE — the same originated in Maglemoisian forests in approximately 8000 BCE — the same
territory and period that CIVICVS models. When both simulations share a 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. specific H3 cell where a CIVICVS Constructor gathered or traded it.
This thread runs through the `origin_h3_r5` provenance stub in `constants.js`, 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. parameter in the registry, through to OTIVM-VIII and OTIVM-IX.
Do not lose this thread. It is the architectural consequence of building 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: 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 run PM2 as root — always as otivm user
- Never commit secrets — no tokens, no keys, no passwords - Never commit secrets — no tokens, no keys, no passwords
- Never push to main without building — `npm run build` must pass first - 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 - 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 - 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 - 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 - The data warehouse is the product — the game is the public interface
- Real weather only in CIVICVS — DWD data always, no simulation - 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. Imperative mood, present tense, under 72 characters.
`Add Mediterranean SVG map to Map screen` not `Added map`. `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: 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 - `staging_otivm.sqlite3` in sync
- Pipeline venv provisioned at `/home/otivm/pipeline-venv` - Pipeline venv provisioned at `/home/otivm/pipeline-venv`
- Four datasets pending download to Drive 1 (BGR IGME5000, HYDE 3.3, KK10, HydroRivers) - 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` waypoint), the game development assistant will be told. The `/api/map/:h5/:epoch`
endpoint requires no changes — it is already parameterised by H5 ID. 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.* *Claude chat designs. Claude Code implements. The human decides.*

150
docs/roadmap.md
View File

@@ -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 > The vision (Sections 1–3) and design principles (Section 5) remain
> valid. **Section 4 ("What exists today") is stale and must not be > valid. Section 4 ("What exists today") has been updated to reflect
> treated as current.** Specifically: > 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.** > **Current state is accurately described in `docs/handover-game-dev.md`.**
> 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`.
> Dataset state is in `docs/handover-dataset.md`. > Dataset state is in `docs/handover-dataset.md`.
> Full dataset inventory and triage is in `docs/TESSERA-dataset-registry.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 ### OTIVM-II — The Map
*The Mediterranean becomes visible.* *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 ### OTIVM-III — The Database
*You hire your first agent.* *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 ### OTIVM-VIII — The Deep Past
*The Mesolithic world surfaces.* *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 ### 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. 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 These are verifiable claims about what is built and running.
> document. Do not treat as current. The roadmap rewrite will replace
> this section.**
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 global pipeline:** The Dell pipeline node has been
decommissioned. The TESSERA 4.0 architecture replaces the global
**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`. 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. **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. - **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. - **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. - **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. - **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.
--- ---