# Earth High Precision Boundary PMTiles Plan

## Status

Superseded status:

This plan originally treated boundaries as collector-managed source records. The current implementation has moved country boundaries out of the datasource / collector lifecycle. Boundaries are now Earth static rendering assets managed by `Operations and Configuration -> Earth Content -> Boundary Precision` and `/api/v1/earth/boundaries/*`. The bundled low-precision GeoJSON is the default fallback, and high precision is an opt-in local PMTiles build.

Historical implementation notes below are retained only as context and must not be used as the current architecture:

- Three standard source collectors now handle real source ingestion: `earth_admin0_boundaries`, `earth_coastline`, and `earth_claim_lines`.
- Each source collector reads endpoint / headers / auth / `target_schema=earth_boundary_source` from Collector Settings, downloads the configured payload, stores the full artifact under `data/earth-boundary-sources/<collector>/<sha256>.*`, and writes a hash / feature-count / artifact-path record to `CollectedData`.
- The backend `earth_boundary_tiles` item is now a downstream PMTiles builder. It refuses to run until the three source records exist, then skips rebuilds when source / POV policy / build config are unchanged.
- The frontend boundary layer now requires the production `pmtiles-mvt` provider and no longer falls back to legacy low-precision GeoJSON.
- Generated loose boundary data is ignored by Git and is not the production deployment format.
- Production PMTiles builds require external `tippecanoe` and `pmtiles` CLIs; missing tools fail the builder clearly instead of registering fake tile records.

Still required before claiming true one-to-one high precision:

- Replace the repository seed GeoJSON with audited high-precision admin boundary, coastline, and claim-line source packages.
- Run a real geometry preparation step that applies the China POV policy through union / subtract / validity repair before PMTiles creation.
- Build and publish `earth-boundaries-china-pov-v1.pmtiles` plus its manifest.

## Summary

The Earth boundary layer should use one static PMTiles archive containing MVT tiles instead of thousands of loose GeoJSON files. The artifact is POV-specific: `earth-boundaries-china-pov-v1.pmtiles` has China POV baked in during offline source preparation, and the browser never patches political boundaries at runtime.

Production should serve a single PMTiles artifact through static hosting and HTTP range requests. In development or on machines that have not opted into high precision, missing PMTiles falls back to the bundled low-precision GeoJSON so the Earth base remains usable.

## Key Implementation Rules

- Source inputs must be auditable. OSM admin boundaries, coastline packages, and claim-line endpoints are configured through Earth Content boundary precision settings; `config/earth-boundary-sources.example.json` remains the versioned example template.
- China POV geometry is applied before tiling:
  - Zangnan and Aksai Chin are unioned into China and subtracted from India.
  - Taiwan/Penghu, Diaoyu Dao and affiliated islands, Chiwei Yu, and South China Sea islands are China hover/country features.
  - The South China Sea dashed line is a claim-line layer only; it never consumes Malaysian, Philippine, Vietnamese, or other land polygons.
  - Kosovo is not an independent country surface in this profile; Gaza is a Palestine region.
- PMTiles/MVT layer names are fixed for the frontend:
  - `boundary_admin0`
  - `boundary_disputed_internal`
  - `coastline`
  - `claim_line`
- The frontend provider is selected from local high-precision preference plus the boundary manifest:
  - `tileProvider: "pmtiles-mvt"` reads the PMTiles artifact.
  - Missing high-precision preference, missing manifest, or missing PMTiles artifact falls back to low-precision GeoJSON.
- Redis is not part of v1. Static PMTiles plus browser/CDN range caching is the default performance model.

## Cleanup And Documentation

- Do not commit generated loose tiles under `frontend/public/earth/data/boundaries/` or source downloads under `data/earth-boundary-sources/`.
- Remove stale generated debug data before production builds; regenerate it only when smoke testing the debug path.
- Keep the high-level plan, backend collector docs, layer style docs, and ops runbook aligned whenever the provider contract changes.
- After implementation changes, provide user-facing operation steps covering source configuration, artifact build/deploy, page verification, and fallback troubleshooting.

## Verification

- The Earth boundary build API reports missing source configuration or missing tools clearly, without creating datasource collection records.
- The PMTiles builder fails as not ready when source artifacts exist but `tippecanoe` / `pmtiles` are missing.
- Running the PMTiles builder twice returns `unchanged` on the second run when inputs are stable.
- `git add . --dry-run` does not include generated loose boundary tiles or source downloads.
- `/home/ray/.bun/bin/bun run build` passes in `frontend`.
- Manual Earth checks confirm:
  - PMTiles range requests are issued only for visible tiles.
  - Boundary toggle, hover tooltip, and country highlight still work.
  - PMTiles failure reports a high-precision boundary error; machines without high-precision enabled continue drawing low-precision fallback boundaries.

## Assumptions

- "One-to-one" means source-faithful to the selected audited vector source, not hand-tuned to a screenshot.
- The China POV artifact is static and versioned; no runtime region-based POV switching is planned.
- The repository low-precision seed file is retained as the runtime fallback for country boundaries.