> ⚠ **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`](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

```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 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:
```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.*