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