# P1 Reporting Metrics Contract

`FunnelAnalyticsReadService` is a read-only domain service and intentionally has no Livewire, route, view, export, or document-link responsibilities.

## Contract

- `funnel(ReportingScope)`: selected, ISR validated, application-ready, submitted, shortlist/interview, LoA, scholarship award, study abroad unique-student counts, plus `total_applications` separately.
- `highestVerifiedStage(ReportingScope)`: map of student ID to highest verified official stage. Pending claims, missing evidence/verifier, and superseded events are excluded. No ordering or leaderboard data is returned.
- `checkpointTrends(ReportingScope)`: per SRS checkpoint published/current student sample and average score.
- `supportBandDistribution(ReportingScope, checkpoint)`: current Support Band counts by band, preserving SRS, health, application stage, and support band as separate axes.
- `comparativeGroups/ comparativeMentors(ReportingScope)`: aggregate sample sizes only; no default ranking or student payload.
- `dataQuality(ReportingScope)`: missing official evidence, pending claims, missing profiles, and superseded-event counts.

## Scope and privacy

`ReportingScope` applies cohort/group/pod filters and student self-scope. Mentor scope is limited to active assignment groups/pods. The service returns aggregate metrics and no private document URLs or contents.

## Performance boundary

Queries use filtered subqueries, `distinct` student counts, grouped aggregates, and bounded scalar maps. Consumers must paginate any future drill-down; this contract does not return a cohort-sized student matrix or leaderboard.