feat(ukvi): Phase 19C — UKVI attendance/compliance escalation workflow (#235)

Third batch of Phase 19 (Statutory and Regulatory Execution). Completes
the UKVI sponsor-duty escalation workflow on top of the existing UKVI
CRUD surface and attendance-monitoring models.

1. Pure decision utility `utils/ukvi-escalation.ts::decideUkviEscalation`.
   Given a sponsored student's compliance status, visa status, rolling
   attendance-monitoring snapshot history and existing reports, decides
   whether to escalate, the recommended compliance status, and which
   UKVIReportType to raise. Encodes the COMPLIANT → AT_RISK →
   NON_COMPLIANT → REPORTED ladder by consecutive non-compliant
   snapshots; selects NO_SHOW vs NON_COMPLIANCE by run severity;
   suppresses duplicate reports; short-circuits non-sponsored and
   already-REPORTED records. Same purity contract as 17A/17D/17E/18A-D/
   19A/19B utilities — no Prisma, no I/O. Rule overrides + clamping.

2. Service orchestration in `ukvi.service.ts`:
   - evaluateEscalation(recordId, options, userId, req) — loads the
     record (with monitoring history + reports), runs the pure utility,
     and in persist mode raises a draft UKVIReport and promotes the
     compliance status (routing the status change through update() so
     the existing ukvi.compliance_changed event fires). Preview is the
     default. Always emits ukvi.escalation_evaluated.
   - submitReport / acknowledgeReport — the draft → submitted →
     acknowledged report lifecycle, mirroring the 19B HESA-return
     lifecycle pattern. acknowledgeReport stamps the Home Office ref
     and promotes the parent record to REPORTED. State-precondition
     guards with force overrides.
   - recordContactPoint — records an engagement-monitoring touchpoint
     (the sponsor's retained evidence) with audit + event.

3. Repo helpers in compliance.repository.ts: getReportById,
   updateReport, getContactPointById.

4. Endpoints (all on the existing ukviRouter, COMPLIANCE-gated, so the
   router count stays 57):
   - POST /v1/ukvi/contact-points
   - POST /v1/ukvi/:id/evaluate-escalation
   - POST /v1/ukvi/reports/:id/submit
   - POST /v1/ukvi/reports/:id/acknowledge

5. Webhooks: ukvi.escalation_evaluated, ukvi.contact_point_recorded,
   ukvi.report_created, ukvi.report_submitted, ukvi.report_acknowledged.

6. Tests:
   - ukvi-escalation.test.ts (new) — 19 pure-function cases.
   - ukvi.service.test.ts (new) — 16 service-orchestration cases.

Verification
- Server tsc: clean (EXIT 0).
- prisma validate: clean.
- Server Vitest: 808/808 passing across 46 files (was 773/44 on main;
  +19 pure + 16 service).
- ESLint of new source files: 0 errors, 0 warnings.
- docs-truth: all checks pass; router count unchanged at 57.
- Gate 4 (no direct Prisma in services): the service routes through the
  compliance repository, not the Prisma client.

Deliberately out-of-scope (later 19 batches)
- EC claims + appeals downstream actions / reporting — 19D.
- Compliance dashboards, evidence trails, closeout — 19E.
- Home Office SMS XML export of the UKVIReport set — a future batch
  alongside the 19B HESA export pipeline (the report lifecycle and
  status model are in place; the wire format is deferred).
- Scheduled attendance-monitoring snapshot generation that feeds the
  escalation evaluator — sequenced to Phase 20 (n8n scheduled jobs).

Co-authored-by: Claude <noreply@anthropic.com>

Author: RJK134

server/src/__tests__/unit/ukvi-escalation.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Phase 19C — pure-function tests for `utils/ukvi-escalation`.
+ *
+ * Covers the sponsor-duty escalation ladder: non-sponsored short-circuit,
+ * already-reported short-circuit, the COMPLIANT → AT_RISK → NON_COMPLIANT
+ * progression by consecutive non-compliant snapshots, NO_SHOW vs
+ * NON_COMPLIANCE report-type selection, duplicate-report suppression,
+ * rule overrides + clamping, snapshot ordering, and determinism.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  decideUkviEscalation,
+  DEFAULT_UKVI_ESCALATION_RULES,
+  type UkviEscalationInput,
+  type AttendanceSnapshotForEscalation,
+} from '../../utils/ukvi-escalation';
+
+const snap = (
+  monitoringDate: string,
+  attendancePercentage: number,
+  compliant: boolean,
+): AttendanceSnapshotForEscalation => ({ monitoringDate, attendancePercentage, compliant });
+
+const base = (overrides: Partial<UkviEscalationInput> = {}): UkviEscalationInput => ({
+  tier4Status: 'SPONSORED',
+  complianceStatus: 'COMPLIANT',
+  attendanceMonitoring: [],
+  existingReports: [],
+  ...overrides,
+});
+
+describe('decideUkviEscalation — out-of-scope short-circuits', () => {
+  it('does not escalate a NOT_SPONSORED student', () => {
+    const out = decideUkviEscalation(base({ tier4Status: 'NOT_SPONSORED' }));
+    expect(out.shouldEscalate).toBe(false);
+    expect(out.recommendedStatus).toBe('COMPLIANT');
+    expect(out.recommendedReportType).toBeNull();
+    expect(out.reasons[0]).toContain('not SPONSORED');
+  });
+
+  it('does not escalate a PENDING visa student', () => {
+    const out = decideUkviEscalation(base({ tier4Status: 'PENDING' }));
+    expect(out.shouldEscalate).toBe(false);
+    expect(out.riskLevel).toBe('GREEN');
+  });
+
+  it('does not re-escalate an already-REPORTED record', () => {
+    const out = decideUkviEscalation(
+      base({
+        complianceStatus: 'REPORTED',
+        attendanceMonitoring: [snap('2026-03-01', 0, false), snap('2026-02-01', 0, false)],
+      }),
+    );
+    expect(out.shouldEscalate).toBe(false);
+    expect(out.recommendedStatus).toBe('REPORTED');
+    expect(out.recommendedReportType).toBeNull();
+    expect(out.riskLevel).toBe('RED');
+  });
+
+  it('returns COMPLIANT when there are no snapshots', () => {
+    const out = decideUkviEscalation(base());
+    expect(out.shouldEscalate).toBe(false);
+    expect(out.recommendedStatus).toBe('COMPLIANT');
+    expect(out.consecutiveNonCompliant).toBe(0);
+  });
+});
+
+describe('decideUkviEscalation — compliant case', () => {
+  it('stays COMPLIANT when the most recent snapshot is within threshold', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 90, true), snap('2026-02-01', 50, false)],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('COMPLIANT');
+    expect(out.consecutiveNonCompliant).toBe(0);
+    expect(out.shouldEscalate).toBe(false);
+  });
+});
+
+describe('decideUkviEscalation — AT_RISK band', () => {
+  it('moves to AT_RISK after one consecutive non-compliant snapshot', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 55, false), snap('2026-02-01', 90, true)],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('AT_RISK');
+    expect(out.recommendedReportType).toBeNull();
+    expect(out.riskLevel).toBe('AMBER');
+    expect(out.consecutiveNonCompliant).toBe(1);
+    expect(out.shouldEscalate).toBe(true); // status moves COMPLIANT → AT_RISK
+  });
+
+  it('does not re-flag escalation when already AT_RISK at the same band', () => {
+    const out = decideUkviEscalation(
+      base({
+        complianceStatus: 'AT_RISK',
+        attendanceMonitoring: [snap('2026-03-01', 55, false), snap('2026-02-01', 90, true)],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('AT_RISK');
+    expect(out.shouldEscalate).toBe(false);
+  });
+});
+
+describe('decideUkviEscalation — NON_COMPLIANT + reportable event', () => {
+  it('moves to NON_COMPLIANT and recommends NON_COMPLIANCE after two consecutive', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 40, false), snap('2026-02-01', 45, false)],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('NON_COMPLIANT');
+    expect(out.recommendedReportType).toBe('NON_COMPLIANCE');
+    expect(out.riskLevel).toBe('RED');
+    expect(out.consecutiveNonCompliant).toBe(2);
+    expect(out.shouldEscalate).toBe(true);
+  });
+
+  it('recommends NO_SHOW when the run is total disengagement (0%)', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 0, false), snap('2026-02-01', 0, false)],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('NON_COMPLIANT');
+    expect(out.recommendedReportType).toBe('NO_SHOW');
+  });
+
+  it('counts only the most recent consecutive run, broken by a compliant snapshot', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [
+          snap('2026-03-01', 40, false),
+          snap('2026-02-15', 90, true), // breaks the run
+          snap('2026-02-01', 30, false),
+        ],
+      }),
+    );
+    expect(out.consecutiveNonCompliant).toBe(1);
+    expect(out.recommendedStatus).toBe('AT_RISK');
+  });
+
+  it('suppresses a duplicate report when a non-draft report of the same type exists', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 40, false), snap('2026-02-01', 45, false)],
+        existingReports: [{ reportType: 'NON_COMPLIANCE', reportDate: '2026-02-20', status: 'submitted' }],
+      }),
+    );
+    expect(out.recommendedStatus).toBe('NON_COMPLIANT');
+    expect(out.recommendedReportType).toBeNull();
+    expect(out.reasons.some((r) => r.includes('already exists'))).toBe(true);
+  });
+
+  it('still recommends a report when only a draft of the same type exists', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 40, false), snap('2026-02-01', 45, false)],
+        existingReports: [{ reportType: 'NON_COMPLIANCE', reportDate: '2026-02-20', status: 'draft' }],
+      }),
+    );
+    expect(out.recommendedReportType).toBe('NON_COMPLIANCE');
+  });
+});
+
+describe('decideUkviEscalation — snapshot ordering', () => {
+  it('sorts unordered snapshots most-recent-first before evaluating', () => {
+    const out = decideUkviEscalation(
+      base({
+        // deliberately oldest-first / shuffled
+        attendanceMonitoring: [
+          snap('2026-01-01', 30, false),
+          snap('2026-03-01', 95, true),
+          snap('2026-02-01', 40, false),
+        ],
+      }),
+    );
+    // most recent (2026-03-01) is compliant → COMPLIANT
+    expect(out.recommendedStatus).toBe('COMPLIANT');
+    expect(out.consecutiveNonCompliant).toBe(0);
+  });
+
+  it('falls back to percentage-vs-threshold when the compliant flag is non-boolean', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [
+          { monitoringDate: '2026-03-01', attendancePercentage: 50, compliant: undefined as unknown as boolean },
+          { monitoringDate: '2026-02-01', attendancePercentage: 50, compliant: undefined as unknown as boolean },
+        ],
+      }),
+    );
+    // 50% < 70% default threshold → both non-compliant → NON_COMPLIANT
+    expect(out.recommendedStatus).toBe('NON_COMPLIANT');
+    expect(out.consecutiveNonCompliant).toBe(2);
+  });
+});
+
+describe('decideUkviEscalation — rule overrides', () => {
+  it('honours a custom report threshold', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 40, false), snap('2026-02-01', 45, false), snap('2026-01-01', 40, false)],
+        rules: { nonCompliantConsecutive: 3 },
+      }),
+    );
+    expect(out.consecutiveNonCompliant).toBe(3);
+    expect(out.recommendedStatus).toBe('NON_COMPLIANT');
+    expect(out.effectiveRules.nonCompliantConsecutive).toBe(3);
+  });
+
+  it('honours a custom attendance threshold', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 80, true), snap('2026-02-01', 80, true)],
+        rules: { attendanceThreshold: 85 },
+      }),
+    );
+    // stored compliant flag is true, so the flag wins regardless of threshold
+    expect(out.recommendedStatus).toBe('COMPLIANT');
+  });
+
+  it('clamps a broken nonCompliantConsecutive below atRiskConsecutive back to a sane value', () => {
+    const out = decideUkviEscalation(
+      base({
+        attendanceMonitoring: [snap('2026-03-01', 40, false)],
+        rules: { atRiskConsecutive: 2, nonCompliantConsecutive: 1 },
+      }),
+    );
+    // nonCompliantConsecutive clamped up to >= atRiskConsecutive
+    expect(out.effectiveRules.nonCompliantConsecutive).toBeGreaterThanOrEqual(
+      out.effectiveRules.atRiskConsecutive,
+    );
+  });
+
+  it('clamps a negative attendanceThreshold back to default', () => {
+    const out = decideUkviEscalation(base({ rules: { attendanceThreshold: -5 } }));
+    expect(out.effectiveRules.attendanceThreshold).toBe(DEFAULT_UKVI_ESCALATION_RULES.attendanceThreshold);
+  });
+});
+
+describe('decideUkviEscalation — determinism', () => {
+  it('returns identical output across repeated runs', () => {
+    const input = base({
+      attendanceMonitoring: [snap('2026-03-01', 40, false), snap('2026-02-01', 45, false)],
+    });
+    expect(decideUkviEscalation(input)).toEqual(decideUkviEscalation(input));
+  });
+});