Files

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

2026-05-02 10:13:29 +00:00

15 KiB

Raw Blame History

⚠ SECTION 4 REWRITTEN — 2026-05-02

The vision (Sections 1–3) and design principles (Section 5) remain 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.

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.

OTIVM — Roadmap

otium · Latin: leisure, rest, creative withdrawal. The condition under which civilisation advances.

1. Vision

OTIVM is a browser-based idle game with a Classical Roman motif. One screen. One merchant. One ledger. You dispatch galleys, trade goods, and rest — and the world slowly reveals itself through what you carry and where you have been. Beneath the Roman surface lies eight thousand years of physical and human geography, encoded at H3 resolution and traceable to citable academic sources. The game is light-hearted. The substrate is not.

2. Player experience arc

OTIVM-I — The Ledger

One merchant. One resource loop. Five routes.

You are a Roman merchant in Ostia with fifty denarii and a battered ledger. You dispatch galleys on trade routes, wait for them to return, and rest when the work is done. Rest builds auctoritas — the reputation that opens what comes next. The journey unfolds through the goods you trade and the journal entries they unlock. The narrative voice is that of the merchant himself: observant, dry, occasionally surprised by what he finds at the end of a long road.

Five chapters: Ostia → Capua → Brundisium → Carthago → Alexandria.

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 powers everything that follows. At this resolution the hexes are invisible to the player. They are infrastructure.

OTIVM-III — The Database

Player state becomes a record.

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:

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.
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.
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.

OTIVM-IV — The Seasons

Real time enters the game.

Dispatches take real hours. Weather affects routes — the sea crossing to Carthago closes in winter storms, mountain passes slow in autumn. Weather data feeds from DWD (Deutscher Wetterdienst), the same source used by the CIVICVS Simulator, delayed six hours from actual Berlin atmospheric conditions and projected onto the Roman world. The preparation window model from the Simulator appears here in simplified form: the game pre-renders the next session's conditions during downtime.

OTIVM-V — Provenance

Goods acquire a past.

The amber your merchant trades did not originate in a warehouse. It came from a specific place — a forested coastline, a river mouth, a trading post. That place has H3 coordinates. Those coordinates have TESSERA data: elevation, terrain class, hydrology, and occupation evidence from the Mesolithic cultures that preceded the Roman world by six thousand years. The player does not see the data directly. They see the merchant's journal entry about a strange bead that feels old in a way coins do not. The depth is real. The atmosphere is earned.

OTIVM-VI — The City

Waypoints become places.

Ostia has a harbour, a market, and a tavern. Each has a function. Prices fluctuate. Rumours move through the tavern before they move through the market. The harbour has ship availability. Each city's physical character — its elevation, its proximity to water, its terrain — comes from TESSERA H9 cell data. A port city built on low coastal terrain behaves differently from a hill town on limestone.

OTIVM-VII — The Atlas

The map opens.

The Mediterranean expands. New routes appear beyond the five original chapters. The map renders using H3 geometry at a resolution where the hexes become visible — a honeycomb of the known world, each cell carrying physical data from TESSERA. Azgaar's Fantasy Map Generator exports are used as a projection reference layer for political geography and named territories, mapped onto the TESSERA physical substrate. The player sees a living atlas. The developer sees a queryable spatial database.

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: 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.

OTIVM-IX — Convergence

OTIVM and CIVICVS share a world.

A participant in the CIVICVS Mesolithic Simulator — running in 8000 BCE — performs an action that produces a good. That good enters the trade network. Thousands of years later, a Roman merchant in OTIVM carries something whose origin is traceable to a specific simulated human action in the Mesolithic. The two systems share the TESSERA substrate. The data warehouse connects them. This is not a gimmick. It is the architectural consequence of building both systems on the same physical reality layer from the start.

OTIVM-X — The Platform

OTIVM becomes infrastructure.

The game is now a public-facing interface to the CIVICVS platform. Any world that can be encoded as H3 cells and TESSERA data can be surfaced through OTIVM's rendering layer. The Roman world was chosen first because it is familiar and navigable. It is not the only world.

3. Technology convergence arc

The physical substrate — TESSERA

TESSERA is a globally consistent, immutable, academically grounded encoding of Earth's physical surface as H3 hexagonal cells. Each cell carries an 8-byte record:

Byte	Field	Source
0–1	Elevation	GEBCO 2025
2	Terrain class	ESA WorldCover 2021 v200
3	Hydrology	HydroSHEDS v1.1
4	Geology flag	BGR IGME5000
5	Geology deposit	USGS MRDS
6–7	Occupation evidence	RFC-TESSERA-3.0-OCC-001

Every field value is traceable to a named, versioned, citable source dataset. Every tile, once generated, is content-addressed by its SHA-256 hash. H9 resolution (~180m) is the primary data resolution. H7 is the tile unit. H3's hierarchical structure means any OTIVM location encoded as an H3 ID at any resolution can be mapped to its TESSERA physical properties without coordinate transformation.

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 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.

The game layer — OTIVM

OTIVM sits above CIVICVS in the same stack. It uses the same H3 grid, the same physical substrate, and will share the same weather source. It differs in period (Roman, ~14 BCE), tone (light-hearted, public-facing), and access model (browser-based, up to 128 concurrent players, no scheduling required).

The convergence point is the data warehouse: a shared layer where TESSERA cells, CIVICVS simulation events, and OTIVM trade provenance can be queried together across ten thousand years of the same physical geography.

The Azgaar bridge

Azgaar's Fantasy Map Generator produces GeoJSON and SVG exports of political geography: territories, named regions, trade routes, cultural boundaries. These are projection references — they encode human geography onto physical terrain. The bridge layer maps Azgaar polygon centroids to H3 cells via point-in-polygon, then queries TESSERA for each cell's physical properties. Azgaar provides the political surface. TESSERA provides the physical truth beneath it. The bridge is planned for OTIVM-VII.

4. What exists today — 2026-05-02

These are verifiable claims about what is built and running.

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: 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.

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.

5. Design principles — do not violate

H3 from day one. Every location in OTIVM is an H3 cell ID. Never a coordinate pair, never a string name alone. This enables TESSERA queries at any future release without data migration.
One screen, one loop. OTIVM-I ships when the core loop is fun. Complexity is added in named releases, not incrementally bolted on.
Physical reality only in the data layer. TESSERA encodes what is physically true. OTIVM encodes what the merchant knows. These are separate layers and must never be conflated.
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.
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.

OTIVM is part of TheRON — The Residential Owner-operated Network. Single contributor: project owner. AI assistants implement, document, flag — do not direct.

15 KiB Raw Blame History Unescape Escape