Add Ground Zero terrain pipeline and playable assets

Docs/Terrain/TileRegistrySchema.md

@@ -0,0 +1,160 @@
+# Tile Registry Schema
+
+## Purpose
+
+The tile registry is the authoritative operational index for terrain tiles. It
+tracks what tiles exist, where they are, which source data generated them, what
+package version is published, and whether the tile is ready for clients.
+
+The first implementation only needs the Ground Zero tile and neighbors. The
+schema is intentionally shaped so it can scale toward hundreds of millions of
+possible 1 km tiles later.
+
+## Prototype Grid
+
+For the MVP, the tile key uses UTM zone 10N and the lower-left 1 km grid corner.
+
+```text
+gz_us_ca_pacifica_utm10n_e544_n4160
+```
+
+Fields encoded in the prototype ID:
+
+- Location family: `gz_us_ca_pacifica`
+- Projection: `utm10n`
+- Easting kilometer: `e544`
+- Northing kilometer: `n4160`
+
+The final global grid is still a design decision. The MVP schema keeps explicit
+projection and metric bounds so tiles can be migrated later if the global index
+changes.
+
+## Tile Status
+
+Allowed status values:
+
+- `unknown`: placeholder exists, no source work started.
+- `queued`: selected for source lookup or generation.
+- `source_data_found`: required source datasets are identified.
+- `generated`: terrain package generated but not validated.
+- `validated`: QA checks passed.
+- `packaged`: client/server package created.
+- `published`: package is available to clients.
+- `deprecated`: superseded by a newer tile version.
+- `blocked`: source or generation issue needs manual review.
+
+## Core Tables
+
+### `terrain_tiles`
+
+Tracks one logical 1 km tile.
+
+Required fields:
+
+- `tile_id`
+- `grid_scheme`
+- `projection`
+- `utm_zone`
+- `easting_min_m`
+- `northing_min_m`
+- `easting_max_m`
+- `northing_max_m`
+- `tile_size_m`
+- `center_latitude`
+- `center_longitude`
+- `status`
+- `biome_primary`
+- `generation_version`
+- `package_version`
+- `created_at`
+- `updated_at`
+
+### `terrain_tile_neighbors`
+
+Tracks adjacency for stitching and prefetching.
+
+Required fields:
+
+- `tile_id`
+- `direction`
+- `neighbor_tile_id`
+
+### `terrain_tile_sources`
+
+Tracks datasets used or intended for each tile.
+
+Required fields:
+
+- `tile_id`
+- `source_kind`
+- `source_name`
+- `source_uri`
+- `license_name`
+- `source_version`
+- `coverage_status`
+
+### `terrain_tile_packages`
+
+Tracks generated downloadable packages.
+
+Required fields:
+
+- `package_id`
+- `tile_id`
+- `package_version`
+- `unreal_engine_version`
+- `world_partition_ready`
+- `package_uri`
+- `content_hash`
+- `package_size_bytes`
+- `created_at`
+- `published_at`
+
+### `terrain_tile_generation_jobs`
+
+Tracks generation pipeline work.
+
+Required fields:
+
+- `job_id`
+- `tile_id`
+- `job_type`
+- `status`
+- `requested_at`
+- `started_at`
+- `finished_at`
+- `log_uri`
+- `error_summary`
+
+## Separation Of Concerns
+
+Terrain tile state should be separate from player-made world state.
+
+Terrain registry owns:
+
+- Source terrain and water data.
+- Generated landscape package.
+- Biome/resource hints.
+- Tile status and package version.
+- Client cache/version compatibility.
+
+Player/world persistence owns:
+
+- Player inventory, stats, and position.
+- Placed structures.
+- Resource depletion, if needed.
+- Claims, settlements, containers, and ownership.
+- Tile-local gameplay changes.
+
+This separation lets us regenerate terrain tiles later without overwriting
+player-built history.
+
+## First Validation Rules
+
+- Tile bounds must be exactly 1000 m x 1000 m in the projected coordinate system.
+- Center latitude/longitude must fall inside tile bounds.
+- Every published tile must have at least one elevation source.
+- Every published tile must have a generation version and package version.
+- Neighbor records must be reciprocal once adjacent tiles are generated.
+- A tile package cannot be `published` until it is `validated`.
+- Terrain package hash must change when package version changes.