TheRON/otivm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
otivm/docs/handover-seed-extraction.md

7.3 KiB
Raw Permalink Blame History

⚠ RETIRED — 2026-04-27

This document describes the original TESSERA 4.0 seed extraction workflow using tessera.db on the Dell pipeline node. That infrastructure no longer exists.

The current dataset assistant handover is: docs/handover-dataset.md

This document is preserved as historical record of the seed extraction session that produced the initial 12,005 H9 rows in data/otivm.sqlite3. Do not act on any instruction in this document — the Dell, tessera-pipeline CT, and tessera.db are all decommissioned.

Handover — TESSERA 4.0 Seed Extraction

Date: 2026-04-26

Status: RETIRED — see docs/handover-dataset.md

For: Historical reference only

0. Your role

You are the dataset assistant. Your immediate task is to create otivm.sqlite3 by extracting the five OTIVM launch waypoint hexes from tessera.db on the Dell SSD. You do not touch game code. You do not modify the roadmap. You do not run any pipeline stage without explicit project owner instruction.

The game assistant works in parallel on otium.civicus.us. You share the OTIVM Gitea repo but work on different files.

1. The RFC — read it first

docs/RFC-TESSERA-4.0-001.md in this repo is the normative schema. Read it completely before writing a single line of code. It defines:

  • All table schemas with exact column names and types
  • Row lifecycle states (1=draft, 2=current, 3=superseded, 4=retired)
  • Per-field provenance as integer FKs
  • H5 coverage completeness tracking
  • The pipeline contract
  • The staging protocol

The schema is approved. Do not deviate from it.

2. Infrastructure

Dell (root@ai, 10.0.0.41)

  • tessera.db at /home/tessera/tessera.db — 158GB SpatiaLite, the seed source
  • tessera-pipeline LXC: scripts at /opt/tessera-pipeline/
  • Python venv: /opt/tessera-pipeline/venv/bin/python3
  • USB is READ-ONLY — no writes to /mnt/tessera-* without explicit permission

OTIVM container (otium-dev, 10.0.0.23)

  • App user: otivm
  • Repo at /home/otivm/OTIVM
  • Claude Code runs here as otivm user via work alias
  • Python venv: /home/otivm/venv
  • This is where otivm.sqlite3 will live: /home/otivm/OTIVM/data/otivm.sqlite3

proliant-dev (srv-a, 10.0.0.11)

  • tessera-store CT (1102, 10.0.0.21): empty, infrastructure ready
  • Not needed for seed extraction — that runs on the Dell

3. tessera.db schema — what you are extracting from

-- Source table in tessera.db (SpatiaLite)
tessera_cells:
  h9_cell   TEXT  -- H3 res-9 cell ID (string format)
  h7_cell   TEXT  -- H3 res-7 parent
  lat       REAL
  lon       REAL
  elev_cm   INTEGER
  terrain   INTEGER
  hydro     INTEGER
  geo_dep   INTEGER
  geo_flag  INTEGER
  geom      BLOB  -- not needed, do not extract

tessera_h7:
  h7_cell   TEXT
  fingerprint TEXT
  generated_at INTEGER
  n_cells   INTEGER

occ_flag does not exist in tessera.db — stage 06 was never run. Set occ_flag = 0 and occ_conf = 4 (no_data) for all seed rows.

4. The five OTIVM launch waypoints

City H5 (TEXT) Notes
Ostia 851e805bfffffff Mediterranean coast, low terrain
Capua 851e8333fffffff Campanian plain
Brundisium 851e8ba3fffffff Adriatic coast
Carthago 85386e23fffffff North Africa
Alexandria 853f5ba7fffffff Nile delta

Each H5 contains 343 H9 cells (7 H7 children × 49 H9 per H7). Total minimum: 5 × 343 = 1,715 H9 rows.

All five are well within the completed portion of tessera.db — the Mediterranean is fully populated through stage 04. No missing data expected except occ_flag (stage 06 not run) and some geo_dep/geo_flag cells at the edge of MRDS/IGME5000 coverage.

5. Source registry seed values

Register these sources in source_registry before extraction:

source_key source_name version license
GEBCO_2025 GEBCO 2025 Grid 2025 CC-BY 4.0
ESA_WORLDCOVER_V200 ESA WorldCover v200 v2.0.0 CC-BY 4.0
HYDROSHEDS_V11 HydroSHEDS v1.1 1.1 CC-BY 4.0
USGS_MRDS USGS Mineral Resources Data System 2022-08-23 public domain
BGR_IGME5000 BGR IGME5000 2007 Geonutz 2013
TESSERA3_SEED TESSERA 3.0 seed extraction 2026-04-26 internal

Confidence grades for seed rows:

  • elev: source=GEBCO_2025, conf=2 (indicated)
  • terrain: source=ESA_WORLDCOVER_V200, conf=2 (indicated)
  • hydro: source=HYDROSHEDS_V11, conf=2 (indicated)
  • geo_dep: source=USGS_MRDS, conf=2 if value != 255, else conf=4
  • geo_flag: source=BGR_IGME5000, conf=2 if value != 0, else conf=4
  • occ: source=TESSERA3_SEED, conf=4 (no_data), value=0

6. H3 integer conversion

tessera.db stores H3 IDs as TEXT (e.g. 891e805b31bffff). otivm.sqlite3 stores H3 IDs as INTEGER (64-bit H3 index).

In Python using the h3 library:

import h3
h9_int = h3.str_to_int(h9_text)   # TEXT → INTEGER
h9_text = h3.int_to_str(h9_int)   # INTEGER → TEXT

The h5 INTEGER value for each waypoint:

h5_int = h3.str_to_int('851e805bfffffff')  # Ostia
# etc.

7. Deployment workflow

Claude Code on otium-dev handles all file writes and git commits. Claude chat produces files with instruction headers. Claude Code writes them to disk, commits, pushes.

No manual tarball workflow. No direct server commands from Claude chat.

The extraction script runs on the Dell (tessera-pipeline CT), not on otium-dev. The output otivm.sqlite3 is then copied to the OTIVM container.

Copy path (after extraction on Dell):

/tmp/otivm.sqlite3 on tessera-pipeline CT
→ lxc file pull to Dell host /tmp/
→ scp to otium-dev /home/otivm/OTIVM/data/otivm.sqlite3

8. What to produce — in order

  1. data/create_otivm_db.sql — SQL to create the schema (all tables per RFC-TESSERA-4.0-001, lookup table inserts) Claude Code writes this. Human runs it on otium-dev to create the empty data/otivm.sqlite3.

  2. pipeline/seed_extract.py — extraction script Reads from tessera.db on the Dell (via tessera-pipeline CT), writes to staging_otivm.sqlite3 in /tmp. Follows the pipeline contract from the RFC. Claude Code writes this. Human deploys to tessera-pipeline CT.

  3. pipeline/seed_promote.py — promotion script Promotes draft rows to current in staging_otivm.sqlite3, verifies row counts, updates h5_coverage. Claude Code writes this.

  4. Copy staging to production — human runs the copy from staging_otivm.sqlite3 to otivm.sqlite3 after verification.

  5. Verify — query otivm.sqlite3 to confirm all five H5 hexes have status=2 in h5_coverage and correct H9 counts.

9. Hard rules

  • Do not write to USB (/mnt/tessera-*) without explicit permission
  • Do not modify tessera.db — it is the immutable seed source
  • Do not touch game code (src/, server/, App.jsx, etc.)
  • Do not run any script without explicit project owner instruction
  • Always read RFC-TESSERA-4.0-001.md before writing any schema code
  • One file. One step. One confirmation. Never batch.

10. Gitea

Repo: https://gitea.barternetwork.us/TheRON/OTIVM Branch: main (direct push, Claude Code handles this) MCP: connected via mcp.civicus.us — read any file directly

Handover 2026-04-26 — seed extraction track RFC approved. Schema locked. Extract five waypoints. Verify. Done.

Reference in New Issue View Git Blame Copy Permalink