Durable migration narratives and design rationales under fire-data-schema. Executable truth is postgres-contract-rls-and-keys.md and supabase/migrations/.
Source of truth for why the v2 schema evolved. Do not duplicate this content elsewhere; link here from onboarding notes.
| File | Read when |
|---|---|
postgres-contract-rls-and-keys.md | Implementing migrations, adapters, or RPCs — exact types, FKs, triggers, keys (wins over narrative SQL). |
conceptual-tables-and-grain.md | Table names, grain, intent (non-executable). |
v2-design-rationale-overview.md | High-level v2 rationale when onboarding. |
v2-001-initial-migration-narrative.md | Initial v2 baseline structures (historical). |
v2-002-filter-codes-migration-narrative.md | Filter-axis unification; embedded get_fire_data at file bottom is historical. |
incremental-patches-and-rpc-changelog.md | Targeted patches; current get_fire_data branching narrative. |
crosstab-and-bucket-modeling.md | Dimension/filter/metric modeling tradeoffs. |
brask-ingest-loop-and-invariants.md | BRASK adapter loop and invariants. |
postgres-contract-rls-and-keys.md + latest supabase/migrations/ + npm run types:gen:fire-data.| Topic | Owner | Notes |
|---|---|---|
| Column types, FKs, triggers, natural keys, upsert templates | postgres-contract-rls-and-keys.md | Overrides illustrative SQL in migration narratives when they drift. |
| Runtime filter-axis contract | v2-002-filter-codes-migration-narrative.md + postgres contract | Rationale in v2-002 narrative; physical FK semantics in postgres contract. |
get_fire_data behaviour | incremental-patches-and-rpc-changelog.md + postgres contract + generated types | Do not copy UNION-era SQL from v2-002 narrative into new migrations. |
| BRASK ingest loop | brask-ingest-loop-and-invariants.md | Adapter guidance; schema semantics still from postgres contract. |
When a migration changes RPCs or keys, update the postgres contract doc and the incremental changelog; touch migration narratives only when the story changes.