From 865c9b06370bdaf6a3551529f0705b4d81ade93a Mon Sep 17 00:00:00 2001 From: otivm Date: Sun, 26 Apr 2026 06:27:55 +0000 Subject: [PATCH] Add seed extraction handover for incoming assistant --- docs/handover-seed-extraction.md | 215 +++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/handover-seed-extraction.md diff --git a/docs/handover-seed-extraction.md b/docs/handover-seed-extraction.md new file mode 100644 index 0000000..55e6648 --- /dev/null +++ b/docs/handover-seed-extraction.md @@ -0,0 +1,215 @@ +# Handover — TESSERA 4.0 Seed Extraction +### Date: 2026-04-26 +### For: Incoming assistant (dataset development track) +### Read this completely before doing anything + +--- + +## 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 + +```sql +-- 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. 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: +```python +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: +```python +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.*