feat(compare): types for enriched comparison payload

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0146VHeLAWjDVE2B5uU67jCB

nextjs-app/lib/types.ts

@@ -99,6 +99,21 @@ export interface OfstedInspection {
   rc_leadership_governance: number | null;
   rc_early_years: number | null;
   rc_sixth_form: number | null;
+  /** Where the effective overall grade came from: a graded (Section 5)
+   * inspection, or carried forward from an ungraded (Section 8) outcome. */
+  grade_source?: 'graded' | 'ungraded_carried_forward' | null;
+  /** Renewed-framework (Nov 2025) area judgements, coded + labelled by the
+   * backend from the live-sampled Ofsted vocabulary. Empty when the school
+   * has no report-card inspection. Safeguarding is never included here. */
+  report_card?: Record<string, ReportCardEntry>;
+  /** The school's page on ofsted.gov.uk (never a deep report link). */
+  ofsted_page_url?: string;
+  report_url?: string | null;
+}
+
+export interface ReportCardEntry {
+  code: number;
+  label: string;
 }
 
 export interface SchoolCensus {
@@ -129,6 +144,12 @@ export interface SchoolAdmissions {
   /** 1st-preference applications per place offered (>1 means oversubscribed). */
   oversubscription_ratio?: number | null;
   oversubscribed: boolean | null;
+  total_offers?: number | null;
+  second_preference_offers?: number | null;
+  third_preference_offers?: number | null;
+  /** Applications naming this school from families in another LA, and offers to them. */
+  cross_la_applications?: number | null;
+  cross_la_offers?: number | null;
 }
 
 export interface SenDetail {
@@ -172,6 +193,22 @@ export interface SchoolResult {
   school_id: number;
   year: number;
 
+  // Progress confidence intervals + writing working-towards (published for
+  // years with progress measures, i.e. up to 2022/23)
+  reading_progress_lower_ci?: number | null;
+  reading_progress_upper_ci?: number | null;
+  writing_progress_lower_ci?: number | null;
+  writing_progress_upper_ci?: number | null;
+  writing_working_towards_pct?: number | null;
+  maths_progress_lower_ci?: number | null;
+  maths_progress_upper_ci?: number | null;
+
+  // KS4 banding and disadvantage gaps
+  /** DfE's own plain-English Progress 8 label, e.g. "Well above average". */
+  progress_8_banding?: string | null;
+  attainment_8_disadvantage_gap?: number | null;
+  progress_8_disadvantage_gap?: number | null;
+
   // Pupil numbers
   total_pupils: number | null;
   eligible_pupils: number | null;
@@ -308,10 +345,47 @@ export interface SchoolDetailsResponse {
 export interface ComparisonData {
   school_info: School;
   yearly_data: SchoolResult[];
+  // Supplementary blocks (additive; absent on an old backend)
+  ofsted?: OfstedInspection | null;
+  census?: SchoolCensus | null;
+  admissions?: SchoolAdmissions | null;
+  admissions_history?: SchoolAdmissions[];
+  deprivation?: SchoolDeprivation | null;
+}
+
+export interface BenchmarkBlock {
+  eal_pct: number | null;
+  sen_support_pct: number | null;
+  disadvantaged_pct: number | null;
+  median_pupils: number | null;
+  /** Primary only — weighted by cohort size. */
+  disadvantaged_rwm_expected_pct?: number | null;
+}
+
+/** Computed from our dataset — NOT official DfE figures. UI copy must say
+ * "state-school average (computed from our dataset)" (the `source` string). */
+export interface Benchmarks {
+  source: string;
+  year: number;
+  primary: BenchmarkBlock;
+  secondary: BenchmarkBlock;
+}
+
+export interface NationalAverages {
+  year: number;
+  primary: Record<string, number>;
+  secondary: Record<string, number>;
+  by_year: Array<{
+    year: number;
+    primary: Record<string, number>;
+    secondary: Record<string, number>;
+  }>;
 }
 
 export interface ComparisonResponse {
   comparison: Record<string, ComparisonData>;
+  national_averages?: NationalAverages;
+  benchmarks?: Benchmarks;
 }
 
 export interface RankingItem {