[AZ-305] c6 PostgresFilesystemStore: TileStore + TileMetadataStore impl

Adds the production PostgresFilesystemStore implementing both protocols
in a single class. Filesystem-backed JPEG I/O (atomic sidecar write,
read-only mmap) + Postgres-backed metadata (spatial bbox, LRU, voting,
upload bookkeeping). Wires composition via `from_config` classmethod.

Key behaviors:
- AC-3 strict reading: INSERT runs first inside an open transaction;
  duplicate-key collisions raise `TileMetadataError` BEFORE any byte is
  written, leaving the original file + sidecar byte-identical. Atomic
  sidecar write happens inside the same transaction; commit closes it.
  Comp-delete remains as a safety net for the rare commit-after-write
  failure path.
- AC-2 content-hash gate runs before any I/O.
- Construction performs an orphan-file reconciliation scan and emits an
  INFO `c6.store.construct` log with steady-state stats.

Adds `c6.write` and `c6.write_failed` FDR record kinds (schema v1.1.0,
forward-compatible) and a thin operator CLI at
`c6_tile_cache.tools dump` for inspection.

Dependencies: adds `psycopg-pool>=3.2,<4.0` for the connection pool used
on the F3 read-hot path.

Tests: 25 new tests for c6_tile_cache cover AC-1..AC-15 plus
MmapTilePixelHandle + helper round-trips. Full Tier-2 unit suite passes
(1215 passed, 8 skipped, 1 pre-existing unrelated failure
`test_ac8_read_host_tuple_on_jetson` — missing `pynvml` on macOS,
Jetson-only).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-12 18:01:50 +03:00
parent bf33b94260
commit d1c1cd9ab4
14 changed files with 2382 additions and 18 deletions
@@ -115,6 +115,18 @@ KNOWN_PAYLOAD_KEYS: Final[dict[str, frozenset[str]]] = {
"measured_at_ns",
}
),
# AZ-305 / E-C6: emitted by PostgresFilesystemStore on every successful
# write_tile. `tile_id` is the canonical UUIDv5 derived from
# (zoom_level, tile_x, tile_y, source, flight_id). `source` is the
# `TileSource` enum value. `disk_bytes` is the JPEG payload length.
# `content_sha256` is the lowercase hex digest of the JPEG body.
"c6.write": frozenset({"tile_id", "source", "disk_bytes", "content_sha256"}),
# AZ-305 / E-C6: emitted on every failed write_tile path. `reason`
# is a short machine-readable tag (content_hash_mismatch, freshness_reject,
# metadata_error, fs_error); `error_class` is the exception class name;
# `message` is the rewrapped exception's str (truncated to keep the
# record inline).
"c6.write_failed": frozenset({"tile_id", "source", "reason", "error_class", "message"}),
}
KNOWN_KINDS: Final[frozenset[str]] = frozenset(KNOWN_PAYLOAD_KEYS.keys())