TheRON/otivm

Fork 0

Files

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

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

13 KiB

Raw Blame History

Handover — OTIVM Game Development

Date: 2026-05-02

For: Incoming assistant (game development track)

Read this completely before doing anything

0. Your role

You are the game development assistant. You design and build the OTIVM browser game at otium.civicus.us. You work in Claude chat (claude.ai), produce one file at a time as a downloadable attachment, and Claude Code on the container commits and pushes.

You do not touch pipeline scripts, SQL schema, or TESSERA extraction code. That work belongs to the dataset assistant (see docs/handover-dataset.md). You share the OTIVM Gitea repo but work on different files.

The game is live. The server is running. Every change you make is visible to real users within seconds of pm2 restart otivm.

1. Read these files before writing any code

In order:

CLAUDE.md — workflow, three-shell model, ground rules, deployment facts
docs/architecture/infrastructure.md — container topology, API protocol
docs/architecture/terminology.md — three-layer vocabulary, naming convention
docs/architecture/latin-bridge.md — Latin terms, admission standard, semantic entries
docs/parameter-registry.md — canonical parameters, scope, layer, maturity
docs/parameter-registry-additions.md — 44 additional tokens from corpus review
docs/actors/CHARACTER-FRAMEWORK.md — six backgrounds, twelve starting parameters
docs/scenarios/SCENARIO-MERCHANT-0000.md — the BALNEA prologue, background selection
docs/scenarios/SCENARIO-MERCHANT-0001.md through 0003.md — the founding trilogy
docs/cities/CITY-OSTIA-0001.md — Ostia as pressure field, not backdrop
docs/roadmap.md — where the game is going
This file

The parameter registry is the bridge between the design documents and the schema. Read it before touching any database code.

2. Infrastructure

OTIVM container (otivm-dev, CT 1105)

App user: otivm
Repo at /home/otivm/OTIVM
Claude Code runs here as otivm user via work alias (cd ~/OTIVM && claude)
Python venv: /home/otivm/venv
Pipeline venv: /home/otivm/pipeline-venv
PM2 home: /home/otivm/.pm2
Node: /usr/bin/node (v22)
App port: 3000
WireGuard: 10.110.0.18

Five containers on srv-a (10.0.0.11)

See docs/architecture/infrastructure.md for the full topology. The architecture is settled: REST over HTTPS on the WireGuard mesh, one write domain per container, no shared filesystems between containers.

CT	Role
1101	tessera-pipeline
1102	tessera-store (master database)
1103	tessera-dev (aggregation)
1104	apt-cache
1105	otivm-dev (this container)

Nginx proxy

Lives on wg-pk (198.58.111.109) — not on this container
Proxies otium.civicus.us → 10.110.0.18:3000

Gitea

Repo: https://gitea.barternetwork.us/TheRON/OTIVM
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
Download each dump to workstation cold storage
Never take a backup without documenting it. Never document one not taken.

3. Stack

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 (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-05-02

OTIVM-I — complete

Five trade routes Ostia → Alexandria, journal, otium/negotium mechanic, per-player saves via 8-char hex token, 128 concurrent players supported.

OTIVM-II — complete and live

The map is live and rendering from real TESSERA data.

src/screens/Map.jsx — fog-of-war SVG map
H7 land cells rendered at real geographic positions (lat/lon from API)
Progressive reveal by chapter — only visited waypoints are visible
Sea = permanent darkness — no data needed, no storage needed
/api/map/:h5/:epoch endpoint — H7 land/sea classification with centroids
Epoch parameterised — default roman_14bce (sl_offset_cm = -10)
data/otivm.sqlite3 — 12,005 H9 rows, five H5 waypoints, paleo_epochs table live
Session lifecycle — session_abandoned event written on new game, old saves preserved
active_dispatch, events[] in save state — sequencing substrate for future releases
galleyProgress() utility in gameState.js
Provenance fields on all routes (origin_h3_r5, origin_region, cultural_note)

Architecture decisions locked in OTIVM-II

H3 IDs on all waypoints — permanent, TESSERA-compatible
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 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:

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.
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.
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+
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. Design corpus

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)
SCENARIO-MERCHANT-0001.md — The Bronze Forge Fire (second-order market logic)
SCENARIO-MERCHANT-0002.md — The Capuan Timber Yard Fire (upstream choke-point logic)
SCENARIO-MERCHANT-0003.md — The FAENUS Offer (capital without cargo)

Actors (docs/actors/):

CHARACTER-FRAMEWORK.md — twelve parameters, hidden traits, background rules
BACKGROUND-0001 through BACKGROUND-0006 — six asymmetric starting lives

Cities (docs/cities/):

CITY-OSTIA-0001.md — Ostia substrate: urban zones, population model, infrastructure parameters, social nodes, daily and seasonal rhythm

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

6. The SVCCINVM thread

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 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 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 both systems on the same physical reality layer from the start.

7. Workflow — one file, one step, one confirmation

Every change follows this sequence without exception:

Claude chat discusses the change and produces one downloadable file
Human uploads to Gitea manually, or pastes into Claude Code
If code: npm run build && pm2 restart otivm
Human confirms result
Claude chat proceeds to next step

One file. One step. One confirmation. Never batch.

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

9. Commit message convention

Imperative mood, present tense, under 72 characters. Add Mediterranean SVG map to Map screen not Added map.

10. What the dataset assistant is doing in parallel

See docs/handover-dataset.md for full detail. Current state:

data/otivm.sqlite3 live — 12,005 rows, paleo_epochs populated, FK clean
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 designed (RFC-TESSERA-4.0-001), not yet coded

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-05-02 — game development track Claude chat designs. Claude Code implements. The human decides.

13 KiB Raw Blame History Unescape Escape