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