# Module Contracts: Unified Task Reports by Type

## Backend Report Aggregation Module

# [DEF:ReportsAggregationModule:Module]
# @TIER: CRITICAL
# @SEMANTICS: [reports, aggregation, normalization, task_outcomes]
# @PURPOSE: Aggregate heterogeneous task outcomes into a canonical report model for unified listing and detail retrieval.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> [DEF:TaskManagerModule]
# @RELATION: DEPENDS_ON -> [DEF:TaskPersistenceModule]
# @RELATION: CALLS -> [DEF:ReportsApiContract]
# @INVARIANT: Every returned report MUST include canonical fields {report_id, task_id, task_type, status, updated_at, summary}.
# @PRE: Query parameters are validated and within supported pagination/filter limits.
# @POST: Response contains normalized reports with deterministic ordering and total metadata.
# @POST: Unknown task type is mapped to fallback type "unknown" and remains visible.
# @POST: Partial payloads are rendered with placeholders, never causing report omission.
# [/DEF:ReportsAggregationModule]

---

## Backend Reports API Contract

# [DEF:ReportsApiContract:Module]
# @TIER: CRITICAL
# @SEMANTICS: [api, reports, contracts, pagination]
# @PURPOSE: Define backend HTTP contract for unified report list and report detail endpoints.
# @LAYER: Interface
# @RELATION: DEPENDS_ON -> [DEF:ReportsAggregationModule]
# @RELATION: IMPLEMENTS -> [DEF:Std:API_FastAPI]
# @INVARIANT: Endpoint responses are non-blocking reads and must not start long-running tasks.
# @PRE: Request is authenticated and authorized under existing report/task visibility rules.
# @POST: List endpoint returns {items, total, page, page_size, has_next, applied_filters}.
# @POST: Detail endpoint returns a single normalized report with diagnostics/next actions when available.
# @POST: Validation errors are explicit (400-range) and machine-readable.
# [/DEF:ReportsApiContract]

---

## Frontend Unified Reports Page Contract

<!-- [DEF:UnifiedReportsPage:Component] -->
/**
 * @TIER: CRITICAL
 * @SEMANTICS: [ui, reports, filtering, detail_panel]
 * @PURPOSE: Provide one unified report center with type-distinct visuals and fast operator triage flow.
 * @LAYER: UI
 * @RELATION: DEPENDS_ON -> [DEF:ReportsApiClient]
 * @RELATION: BINDS_TO -> [DEF:ReportTypeProfileRegistry]
 * @INVARIANT: Reports list remains readable and interactive under large history and mixed task types.
 * @PRE: User is authenticated and has access to report data.
 * @POST: User can identify report type from both text label and visual profile.
 * @POST: User can filter by type/status and open detail without leaving report context.
 * @UX_STATE: Loading -> Skeleton list displayed; filters visible but request controls disabled.
 * @UX_STATE: Ready -> List of normalized reports shown with type badges and status indicators.
 * @UX_STATE: NoData -> Friendly empty state with explanation when no reports exist at all.
 * @UX_STATE: FilteredEmpty -> Message "No reports match your filters" with one-click clear action.
 * @UX_STATE: Error -> Inline error block with retry action while preserving filter context.
 * @UX_FEEDBACK: On filter apply, list updates with immediate visual acknowledgment.
 * @UX_RECOVERY: Retry failed loads, clear filters, and continue reading partial reports with placeholders.
 */
<!-- [/DEF:UnifiedReportsPage] -->

---

## Frontend Reports API Client Contract

# [DEF:ReportsApiClient:Module]
# @TIER: STANDARD
# @SEMANTICS: [frontend, api_client, reports]
# @PURPOSE: Wrap report API requests via existing request helpers and expose typed list/detail fetch methods.
# @LAYER: Infra
# @RELATION: DEPENDS_ON -> [DEF:api_module]
# @RELATION: CALLS -> [DEF:ReportsApiContract]
# @INVARIANT: Native fetch is not used directly; existing wrapper-based request path is preserved.
# @PRE: Valid auth token is present when required by backend.
# @POST: Returns parsed report payload or structured error object for UI-state mapping.
# [/DEF:ReportsApiClient]

---

## Frontend Type Profile Registry Contract

# [DEF:ReportTypeProfileRegistry:Module]
# @TIER: STANDARD
# @SEMANTICS: [presentation, report_types, fallback]
# @PURPOSE: Maintain deterministic mapping from task_type to visual profile metadata and fallback behavior.
# @LAYER: UI
# @RELATION: DEPENDS_ON -> [DEF:UnifiedReportsPage]
# @INVARIANT: Exactly one fallback profile exists and is used for unknown task types.
# @PRE: Input task_type may be known or unknown.
# @POST: Returns profile with display label and variant tokens required for rendering.
# [/DEF:ReportTypeProfileRegistry]

---

## Contract Usage Simulation (Key Scenario)

Scenario traced: Operator finds failed migration quickly and triages.

1. `UnifiedReportsPage` requests filtered list (`status=failed`, `task_type=migration`) through `ReportsApiClient`.
2. `ReportsApiClient` calls `ReportsApiContract` list endpoint.
3. `ReportsAggregationModule` normalizes task records and returns canonical report items.
4. `UnifiedReportsPage` enters `Ready` `@UX_STATE`, rendering migration-specific visual profile.
5. Operator opens one report detail.
6. `ReportsApiContract` detail endpoint returns diagnostics + `next_actions`.
7. UI shows actionable failure context and recovery guidance without changing page context.

Continuity check: No interface mismatch found across contracts for list/filter/detail path.