feat(migration): ICT dimension spine — regions, schools, coaches, teachers, FICO KPIs

[hammad-sarfraz-1]

Makes the migrated ICT coaching observations attributable: which coach observed which teacher, at which school, in which sector.

The gap

V1.0.5__coaching_observations_migrated.sql imported the observation facts — 9,944 observations, 255,417 answers, 497,177 question options, 8,973 teacher visits. It preserved the Django FK columns as opaque BIGINTs, noting that consumers needing identity should "join via other paths".

There is no such path. No region, school, coach-profile or teacher-profile table was ever migrated:

nietemigrated_observations.coach_id     BIGINT  -> nothing
nietemigrated_teacher_visits.teacher_id BIGINT  -> nothing
nietemigrated_school_visits.school_id   BIGINT  -> nothing

So the question is answerable at source and unanswerable in Supabase.

What this adds

V1.0.11__ict_dimension_spine.sql — five lookup tables, one view, RLS, and three guarded FK back-fills that resolve V1.0.5's opaque columns:

Table	Rows
nietemigrated_school_regions	7 sectors
nietemigrated_schools	462
nietemigrated_coach_profiles	117
nietemigrated_teacher_profiles	4,310 rows / 4,259 people
nietemigrated_fico_kpis	5,180

scripts/migrate-ict-spine.py — the loader, following the established fde_production → nietemigrated_* pattern used by the 9 existing migrate-*.py scripts. --dry-run by default, plus --commit, --tables, --verify.

Verified live at source, 2026-08-04

• 8,460 active observations, test accounts excluded (6,406 coach / 900 principal / 1,154 teacher-self)
• 63 coach profiles · 2,711 teachers observed · 337 schools
• Span 2025-08-22 → 2026-08-03
• Sectors: B.K 84 · Sihala 79 · Urban-I 74 · Nilore 67 · Urban-II 67 · Tarnol 61 · (no region) 32 · Durbeen 1

Validated against real PostgreSQL 16

Run with V1.0.5-shaped fact tables (UUID PKs, BIGINT opaque FKs) — not a syntax check. 10 assertions pass: clean apply · idempotent re-apply · all 3 FKs attach as NOT VALID · a new bad write is rejected while legacy rows are tolerated · the view does not fan out on multi-profile teachers · EMIS match beats recency in the tie-break · observation grain respected across subjects · profile-less scores survive with a null name · sector-less schools resolve · zero HR columns present.

The DOWN block drops the spine and leaves V1.0.5 untouched.

Conventions followed

• infrastructure/supabase/migrations/ as V1.0.11__, matching V1.0.5 (the sibling nietemigrated_* migration).
• source_system + migrated_at provenance columns, as V1.0.5 carries.
• BIGINT PKs to match V1.0.5's opaque FK columns exactly — no ID remapping.
• Reads fde_production via TALEEMABAD_DB_*. No BigQuery dependency.

PII: not migrated, rather than guarded

fico_kpis takes 13 of 28 source columns. The 9 HR columns — cnic, date_of_birth, gender, joining_date, last_promotion_date, qualifications, professional_trainings, service_designation, basic_pay_scale — are never selected. No column to leak beats a read-side allow-list.

Also dropped: teacher_name / school / sector / levels / contact_number, which repeat identically on every observation of the same teacher. They come from teacher_profiles through the view.

The tie-break, and why a view

fico_kpis links by user_id; teacher_profiles is keyed by profile id, and one user can hold two profiles (a transferred teacher). The view owns the rule once: prefer the profile whose school EMIS matches the observation, else the most recently modified.

Measured, so the exposure is known: 4,259 teachers, 51 multi-profile. FICO covers 2,257, of which 9 are multi-profile. A further 9 FICO user_ids have no active profile at all — the view LEFT JOINs so their scores survive.

Notes for review

• Nothing has been applied to Supabase and the loader has not been run. This is schema + script only.
• emis is deliberately not unique: 462 live schools carry 459 distinct EMIS with 3 NULL, so a unique constraint would reject the load.
• 32 schools have no region and are unfilterable by sector — surfaced, not hidden.
• Three school lists disagree (schools_school 462 · FDE_Schools 341 · Middle_High_Schools_Updated 228). Reconciling them is deliberately left as a follow-up rather than silently picking one.
• Contains V1.0.11; the companion coaching PR adds V1.0.12. Merging this first keeps the sequence gapless.