216 lines
6.7 KiB
Markdown
216 lines
6.7 KiB
Markdown
# 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.*
|