Add seed extraction handover for incoming assistant
This commit is contained in:
otivm
215
docs/handover-seed-extraction.md
Normal file
215
docs/handover-seed-extraction.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user