satellite-provider/_docs/02_document/contracts/data-access/tile-storage.md

Contract: tile-storage

Component: DataAccess Producer task: AZ-484 (v1.0.0 — multi-source schema) + AZ-503-foundation (v2.0.0 — tile identity columns) + AZ-505 (v2.0.0 freeze — covering index + location_hash-keyed reads + bulk inventory) Consumer tasks: AZ-485 (UAV upload endpoint, cycle 5 — uav-tile-upload.md v1.1.0), AZ-505 (inventory endpoint, this cycle — tile-inventory.md v1.0.0), future SatAR / additional-source tasks Version: 2.0.0 Status: frozen Last Updated: 2026-05-12

Purpose

Defines how satellite imagery tiles are persisted in the tiles table when more than one acquisition source (and multiple UAV flights per source) can write to the same geographic cell, AND how the table is indexed for the two distinct read patterns it serves:

1. Producer writes (POST /api/satellite/upload, GoogleMapsDownloaderV2) — per-source, per-flight UPSERTs keyed by integer slippy coords.
2. Consumer reads:
   • Leaflet hot path — GET /tiles/{z}/{x}/{y} returns the most-recent variant by location_hash.
   • Bulk inventory — POST /api/satellite/tiles/inventory returns one row per location_hash across many cells in one round trip.

Producers must agree on the source enum, captured_at semantics, flight_id semantics, and the per-(source × flight) UPSERT contract. Readers must use the location_hash-keyed selection rule and tolerate the multi-source / multi-flight row layout.

Shape

Schema (PostgreSQL tiles table — relevant columns only)

-- Pre-existing columns (unchanged since AZ-484)
id                  UUID            PRIMARY KEY
tile_zoom           INT             NOT NULL
tile_x              INT             NOT NULL
tile_y              INT             NOT NULL
latitude            DOUBLE PRECISION NOT NULL
longitude           DOUBLE PRECISION NOT NULL
tile_size_meters    DOUBLE PRECISION NOT NULL
tile_size_pixels    INT             NOT NULL
image_type          VARCHAR(10)     NOT NULL
file_path           VARCHAR(500)    NOT NULL
created_at          TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP
updated_at          TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP

-- AZ-484 (v1.0.0)
source              VARCHAR(32)     NOT NULL    -- enum-stored: 'google_maps' | 'uav'
captured_at         TIMESTAMP       NOT NULL    -- UTC; producer-supplied semantics, see below

-- AZ-503-foundation (this contract — v2.0.0)
flight_id           UUID            NULL        -- per-UAV-flight identifier; NULL for google_maps + legacy uav
location_hash       UUID            NOT NULL    -- UUIDv5(TileNamespace, "{tile_zoom}/{tile_x}/{tile_y}")
content_sha256     BYTEA           NULL        -- SHA-256 of JPEG body at insert time; NULL for legacy rows only
legacy_id           UUID            NULL        -- pre-AZ-503 random `id` preserved for one deprecation cycle

-- Vestigial columns (preserved per coderule.mdc; readers MUST NOT depend on them)
maps_version        VARCHAR(50)     NULL
version             INT             NULL

Field reference (v2.0.0)

Field	Type	Required	Description	Constraints
source	enum (TileSource) stored as VARCHAR(32)	yes	Producer of the tile	'google_maps' or 'uav'. New values require a contract version bump.
captured_at	TIMESTAMP UTC	yes	Producer-defined "moment the imagery represents"	For google_maps: DateTime.UtcNow at download time (provider does not expose original imagery date). For uav: the UAV capture timestamp supplied by the upload client. Must be UTC; non-UTC must be converted before write.
flight_id	UUID	no (NULL for google_maps + legacy uav)	Per-flight identifier supplied by the UAV upload endpoint	When source = 'uav' AND tile is AZ-503+ era → NOT NULL. When source = 'google_maps' → MUST be NULL. Pre-AZ-503 uav rows may have NULL. UPSERT collapses NULL via COALESCE(flight_id, '00000000-…'::uuid).
location_hash	UUID (v5)	yes	Deterministic cell identifier	UUIDv5(Uuidv5.TileNamespace, "{tile_zoom}/{tile_x}/{tile_y}"). Cross-repo invariant — TileNamespace = 5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c. Identical byte-for-byte with gps-denied-onboard/components/c6_tile_cache/_uuid.py:TILE_NAMESPACE.
content_sha256	BYTEA (32)	yes for AZ-503+ writes (NULL only for pre-AZ-503 rows the migration could not re-hash)	SHA-256 of the JPEG body at insert time	Application invariant: enforced NOT NULL on new writes via TileEntity.ContentSha256. Migration 014 left the column nullable because it could not safely re-open tile files on disk during schema migration.
legacy_id	UUID	no	Pre-AZ-503 random id preserved for one deprecation cycle	NULL for AZ-503+ rows; populated for rows that pre-date migration 014. Will be dropped in a follow-up migration once external references are confirmed flushed.
(tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-…'::uuid))	composite	yes	Per-source-per-flight uniqueness	Enforced via UNIQUE INDEX idx_tiles_unique_identity. Replaces the AZ-484 lat/lon-keyed uniqueness from idx_tiles_unique_location_source.

Indexes (v2.0.0)

-- Per-source-per-flight uniqueness. NULL-safe via COALESCE.
CREATE UNIQUE INDEX idx_tiles_unique_identity
    ON tiles (
        tile_zoom, tile_x, tile_y, tile_size_meters, source,
        COALESCE(flight_id, '00000000-0000-0000-0000-000000000000'::uuid)
    );

-- Leaflet hot-path covering index. AZ-505.
CREATE INDEX tiles_leaflet_path
    ON tiles (location_hash, captured_at DESC, updated_at DESC, id DESC)
    INCLUDE (file_path, source);

Indexes dropped in v2.0.0:

• idx_tiles_unique_location_source (AZ-484 lat/lon-keyed uniqueness) — dropped by migration 014; superseded by idx_tiles_unique_identity.
• idx_tiles_unique_location (pre-AZ-484 4-column uniqueness) — dropped by migration 013; included here for completeness.
• idx_tiles_location_hash (lightweight lookup added by migration 014) — dropped by migration 015; superseded — equality lookups by location_hash use the leading column of tiles_leaflet_path.

Producer write API

Operation	Repository method	Conflict semantics
Insert / replace same-(source, flight) row for a cell	ITileRepository.InsertAsync(TileEntity)	ON CONFLICT (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-…'::uuid)) DO UPDATE SET file_path, latitude, longitude, captured_at, updated_at, content_sha256. Producers MUST set Source, CapturedAt, LocationHash, ContentSha256. Producers MUST set FlightId when source = uav.
Update by primary key	ITileRepository.UpdateAsync(TileEntity)	Updates by id only. Caller's responsibility not to violate the unique index.
Delete by primary key	ITileRepository.DeleteAsync(Guid)	Removes a single row by id; no cascade.

Consumer read API and selection rule

Operation	Repository method	Selection rule
Read by id	ITileRepository.GetByIdAsync(Guid)	Returns the row identified by id (no source/flight filter).
Read most-recent for a cell by slippy coordinates	ITileRepository.GetByTileCoordinatesAsync(zoom, x, y)	Computes location_hash = UUIDv5(TileNamespace, "{zoom}/{x}/{y}") and returns the row with the highest (captured_at, updated_at, id) tuple for that hash across all sources/flights. At most one row.
Read region	ITileRepository.GetTilesByRegionAsync(lat, lon, sizeMeters, zoomLevel)	Returns at most one row per (tile_zoom, tile_x, tile_y, tile_size_meters) group, selected by the same most-recent rule.
Bulk inventory lookup	ITileRepository.GetTilesByLocationHashesAsync(IReadOnlyList<Guid> locationHashes)	Returns at most one row per requested location_hash, selected by DISTINCT ON (location_hash) ... ORDER BY location_hash, captured_at DESC, updated_at DESC, id DESC. Used by the AZ-505 inventory endpoint.

The selection rule is most-recent across all sources and flights ordered by captured_at DESC, with (updated_at DESC, id DESC) as deterministic tie-breakers. No voting / trust-promotion filter is applied at this layer.

Invariants

• Inv-1: Every row has a non-null source whose string value is a member of TileSource. Rows with unknown source values are a contract violation.
• Inv-2: Every row has a non-null captured_at in UTC.
• Inv-3: At most one row exists per (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-…'::uuid)). NULL-coalesced flight_id is what makes google_maps rows (where flight_id is always NULL) deduplicate to one row per cell-and-size-and-source.
• Inv-4: For any cell with one or more rows, the row returned by GetByTileCoordinatesAsync and the per-cell row returned by GetTilesByRegionAsync are identical.
• Inv-5: The source column value space is closed: only the snake_case wire values defined in SatelliteProvider.Common.Enums.TileSourceConverter ("google_maps", "uav") are valid. Adding a new producer requires a new TileSource enum member, a corresponding wire value in TileSourceConverter, AND a contract version bump (minor). Note: TileEntity.Source is stored as the wire string (not the C# enum) because Dapper's TypeHandler<T> for enum types is bypassed during read deserialization (Dapper issue #259); TileSourceConverter.{ToWireValue,FromWireValue} is the documented bridge.
• Inv-6: captured_at semantics are producer-defined per the Field Reference table above; consumers MUST NOT reinterpret it (e.g., consumers MUST NOT assume captured_at from google_maps reflects original imagery date).
• Inv-7 (new in v2.0.0): location_hash is functionally determined by (tile_zoom, tile_x, tile_y) — every row with the same slippy coords has the same hash, and that hash equals UUIDv5(Uuidv5.TileNamespace, "{tile_zoom}/{tile_x}/{tile_y}"). The namespace constant is a cross-repository invariant that must NOT be changed unilaterally — see coderule.mdc "cross-repo invariants" and the AZ-503 migration header.
• Inv-8 (new in v2.0.0): When source = 'google_maps', flight_id MUST be NULL. When source = 'uav' AND the row is AZ-503+ era (created after migration 014), flight_id SHOULD be non-NULL; legacy uav rows with NULL flight_id are tolerated for one deprecation cycle.
• Inv-9 (new in v2.0.0): GetByTileCoordinatesAsync filters by location_hash, not by (tile_zoom, tile_x, tile_y) directly. Callers that pass the same (z, x, y) tuple get byte-identical results to v1.0.0 because the hash is deterministic; this is a behavior-preserving rewrite that exists to make the leaflet hot path index-only against tiles_leaflet_path.

Non-Goals

• Not covered: Per-source / per-flight historical revision retention. Same-(source, flight) uploads to the same cell overwrite the previous row by design — this is not a versioned table. Consumers wanting season selection or rollback must propose a v3 schema.
• Not covered: Cross-source / cross-flight merging or compositing at read time. Reads return exactly one row per cell.
• Not covered: Quality scoring, threshold gating, or voting / trust-promotion at this layer. Voting is owned by gps-denied-onboard Design Task #2 and consumes flight_id from this contract.
• Not covered: Backwards-compatible reads against the v1.0.0 unique index. Migration 014 is mandatory before any consumer of v2.0.0 runs.
• Not covered: The vestigial maps_version and version columns. Consumers MUST NOT read them; producers MUST NOT write them in v1.0.0+.
• Not covered: content_sha256 integrity verification on read. The column is populated for new writes; downstream verification is a future-task concern.

Versioning Rules

• Patch (2.0.x): Documentation clarifications, additional invariants that do not change runtime behavior, expanded test cases.
• Minor (2.x.0): Adding a new TileSource enum member; adding optional columns that consumers may safely ignore; adding new repository read methods; widening the tiles_leaflet_path INCLUDE list to remove heap fetches from inventory.
• Major (3.0.0): Removing or renaming a column; changing the unique index columns; changing the selection rule (e.g., adding source priority or voting filter); changing captured_at from required to optional or vice versa; introducing per-(source, flight) historical revisions; changing the Uuidv5.TileNamespace constant (would also break sibling repos and require coordinated cross-repo work).

Each version bump requires updating the Change Log below and notifying every consumer listed in the header. If consumers' tasks have not yet been written, the producer task is responsible for surfacing the change to the user before merging.

Test Cases

Case	Input	Expected	Notes
valid-google-only	Insert source='google_maps' captured_at=T1 flight_id=NULL for a fresh cell	Single row returned by region read; source='google_maps', captured_at=T1.	v1.0.0 baseline regression case.
valid-multi-source	Insert google_maps captured_at=T1, then uav captured_at=T2 > T1 flight_id=F1 for same cell	Both rows persisted; GetByTileCoordinatesAsync returns the uav row.	AC-1 + AC-2 of AZ-484.
valid-multi-flight	Insert two uav rows with distinct flight_ids for same (z, x, y), captured_at=T1 and T2 > T1	Both rows persisted under idx_tiles_unique_identity; most-recent rule returns the T2 row.	v2.0.0 new — was a unique-index violation under v1.0.0.
same-source-same-flight-upsert	Insert uav captured_at=T1 flight_id=F1, then uav captured_at=T2 > T1 flight_id=F1 for same cell	Exactly one uav/F1 row remains, with captured_at=T2 and updated file_path.	AZ-484 AC-3, preserved through AZ-503 schema rewrite.
time-tiebreak	Insert google_maps captured_at=T, then uav captured_at=T flight_id=F1 (identical timestamps) for same cell	Selection deterministic by (updated_at DESC, id DESC) tie-break; result must be reproducible across two test runs with the same seed.	Inv-4 enforcement.
location-hash-stability	Compute UUIDv5 for (z=18, x=154321, y=95812) both in C# (Uuidv5.Create) and in Postgres (migration 014 helper)	Identical 16 bytes. Both equal gps-denied-onboard's Python uuid5(TILE_NAMESPACE, "18/154321/95812").	Inv-7 cross-repo invariant.
leaflet-index-only	Seed ≥ 100k rows, VACUUM ANALYZE tiles, then EXPLAIN SELECT file_path FROM tiles WHERE location_hash = $1 ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1	Plan contains Index Only Scan using tiles_leaflet_path; Heap Fetches ≤ 1.	AZ-505 AC-3.
bulk-inventory-ordering	GetTilesByLocationHashesAsync with 2500 hashes (mix of present + absent)	Result is one-row-per-distinct-hash, most-recent across (source, flight). Order is hash-keyed; caller re-aligns to request order.	AZ-505 AC-1 / AC-4.
backfill-completeness	Migration 013 against a snapshot DB with N pre-existing rows	Post-migration row count is N; every row has source='google_maps' and captured_at = created_at.	AZ-484 AC-4.
location-hash-backfill	Migration 014 against a snapshot DB after AZ-484 has applied	Every row has non-NULL location_hash matching the application-side UUIDv5 for that row's (tile_zoom, tile_x, tile_y).	AZ-503-foundation guarantee.
invalid-source	Direct SQL insert with source='satar' (not in enum)	Repository read either rejects deserialization or raises a contract violation; behavior MUST surface the violation, not swallow it.	Inv-1 + coderule.mdc "never suppress errors silently".

Change Log

Version	Date	Change	Author
1.0.0	2026-05-11	Initial contract — multi-source schema (source, captured_at), 5-column unique key, most-recent-across-sources read rule. Produced by AZ-484.	autodev (Step 9)
2.0.0	2026-05-12	MAJOR. Identity columns + covering-index freeze. Added columns: flight_id (per-UAV-flight, nullable), location_hash (UUIDv5, NOT NULL), content_sha256 (BYTEA, app-NOT-NULL), legacy_id (pre-AZ-503 random id preserved one cycle). Replaced AZ-484 idx_tiles_unique_location_source (lat/lon-keyed) with idx_tiles_unique_identity (integer slippy + per-flight, NULL-coalesced) — migration 014. Added covering index tiles_leaflet_path (location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source) — migration 015. Rewrote GetByTileCoordinatesAsync to filter on location_hash (behavior-preserving — same UUIDv5 deterministic on both ends — to enable index-only scan on the leaflet hot path). Added GetTilesByLocationHashesAsync for the AZ-505 bulk inventory endpoint. Introduced Inv-7 / Inv-8 / Inv-9. Produced jointly by AZ-503-foundation (cycle 5, columns + identity index) and AZ-505 (cycle 6, covering index + location_hash-keyed reads + bulk inventory). Consumers reviewed at bump time: AZ-485 (uav-tile-upload.md v1.1.0) — already aligned in cycle 5; AZ-505 (tile-inventory.md v1.0.0) — produced jointly.	autodev (Step 10, cycle 6)