Module reports 

Reports capability: the typed, paginated agent API for the category and what reports — the agent twin of the most-used human screens (severity-report / category-report).

Reads straight from the report_summary rollup (crate::backend::{category_rollup, what_rollup, severity_total, category_total}): indexed, refreshed on the run-completion path, and already paginated. This is the structured counterpart to the HTML reports the legacy routes render; both reflect the same rollup, so humans and agents see the same numbers.

Structs

CategoryReportDto

The category report for a (corpus, service, severity): one row per category (a page of them), plus the severity grand totals to compute shares against.

DocumentReportDto

The per-article forensic report (the micro magnification): one document’s conversion outcome for a service, plus the messages behind it — the answer to “what are the errors of this article?”.

EntryListDto

The deepest report rung: the paginated list of documents (paper ids) affected by a specific (severity, category, what). The agent twin of the entry-list screen and the bridge from the macro what-breakdown counts to per-article forensics — “which papers have this issue?”, so an agent can enumerate and then drill into each via the document endpoint. Page with offset/page_size (default 100, max 1000).

EntryRowDto

One affected document in the entry list: its short name (paper id), task id, and the message detail that placed it under the queried (severity, category, what).

GlobalRunControlDto

Acknowledgement for a global pause/resume-all conversion control.

MessageCountsDto

True per-severity message totals for a document (the real counts behind a possibly-sampled messages list — see DocumentReportDto::messages).

MessageDto

One worker-log message behind a document’s status: its severity and the category/what/ details triple parsed from the worker’s cortex.log.

RefreshAckDto

Acknowledgement for a forced report-rollup refresh: the background crate::jobs handle to poll.

ReportRowDto

One report row: a category (in the category report) or a what class (in the drill-down), with its distinct-task and message counts.

RerunAckDto

Acknowledgement of a rerun: the scope that was marked and who marked it.

RunControlDto

Result of a pause/resume run-control action (the agent twin of the report screen’s Pause/Resume buttons).

ScopeRefreshAckDto

Acknowledgement of a scoped report-cache refresh: the scope that was busted and who busted it.

ServiceOverviewDto

The service-overview hub (the macro top rung of the report ladder): the (corpus, service) conversion-status breakdown an agent reads first, before drilling into a severity. The status keys double as the <severity> path segment for the category report (GET /api/reports/<corpus>/<service>/<severity>).

StatusCountDto

One status bucket in the service overview: a conversion-status key with its task count and its share of the valid-task total.

WhatReportDto

The what drill-down for a (corpus, service, severity, category): one row per what (a page), plus the category totals.

Functions

api_category_report

The category report (agent twin of the severity screen): one row per category, descending by task count, paginated. 400 on an unknown severity, 404 on an unknown corpus/service.

api_document

The per-article forensic report (agent micro-drill-down): a single document’s status for a service plus every worker-log message behind it — “what are the errors of this article?”. <name> is the document’s short name as it appears in reports (e.g. 0801.1234). 404 on an unknown corpus / service / document.

api_entry_list

Lists the documents affected by a (corpus, service, severity, category, what) — the agent twin of the deepest report screen (the entry list). Paginated (offset/page_size, default 100, max MAX_REPORT_PAGE_SIZE); offset is capped at MAX_REPORT_OFFSET (a 400 beyond it — see P-4). 400 on an unknown severity, 404 on an unknown corpus/service.

api_service_overview

The service-overview hub (agent twin of the top report screen): the (corpus, service) conversion-status breakdown — total + per-status counts/percentages — the macro entry point an agent reads before drilling into a severity. Shares backend::progress_report with the HTML top screen, so the numbers match. 404 on an unknown corpus/service.

api_what_report

The what drill-down (agent twin of the category screen): one row per what within a category, descending by task count, paginated. 400 on an unknown severity, 404 on an unknown corpus/service.

category_service_report

Category-level report: the what classes within a (severity, category).

category_service_report_all

Category-level report with paging/all-messages query params.

document_lookup_redirect

Query-style entry to the per-article forensic screen: GET /document/<corpus>/<service>?name=<id> → 303 to the canonical path URL /document/<corpus>/<service>/<id>. This is the no-JS fallback target for the service-overview “look up an article” form (the JS enhancement navigates to the path URL directly), so a human can jump to one article’s forensics by id without drilling the report ladder — even with scripting off. 400 on a blank name; the document itself is validated at the path route (404 there if unknown).

document_report_page

The per-article forensic screen (HTML twin of api_document): a document’s status and the table of every worker-log message behind it. The fast structured view of “what are the errors of this article?” — straight from the parsed log_* rows (no result-archive fetch), complementing the rendered /preview. 404 on an unknown corpus / service / document. Lives at a top-level /document/... path (a sibling of /preview/...) so it never collides with the same-shape severity/category report route.

is_valid_rerun_severity

Severities valid for a rerun filter — which differs from the report rollup, because rerun filters tasks (or their messages), it doesn’t aggregate a report (R-9). With a category the scope is over log messages (warning/error/fatal/invalid + the all-messages info); without one it is over task status (no_problem/warning/error/fatal/invalid — no_problem IS a legitimate rerun scope, e.g. regenerating output after a worker upgrade, and info is not a task status). One shared validator for the agent (rerun_report) and human (serve_rerun) surfaces, so both reject the same typos instead of silently mis-scoping to no_problem.

pause_all_api

Pause all conversions — block every in-progress task fleet-wide so the dispatcher stops leasing new work everywhere. The agent twin of the dashboard’s “Pause all conversions”. Token-gated; returns the count blocked. Reversible with the resume twin.

pause_run_api

Pause a run — block every in-progress task (status >= 0) of a (corpus, service) so the dispatcher stops leasing them. The agent twin of the report screen’s “Pause run” button. Token-gated via the Actor guard; 404 on an unknown corpus/service. Returns the count blocked. Reversible with the resume twin.

refresh_report_scope

Report-footer “Refresh this report”: drop the cached report grains for this (corpus, service) scope so the next view recomputes them from current data. Scoped (not the global all-corpora bust refresh_reports does) and synchronous — busting report_grain_cache is an instant keyed DELETE, so there is no background job to poll; the caller just reloads. Gated by the signed-in AdminSession cookie (the footer shows the button only to admins; a missing session is a clean 401 for the XHR rather than an HTML redirect). 404 on an unknown corpus/service, 204 on success. Agent twin: refresh_report_scope_api.

refresh_report_scope_api

Busts this (corpus, service)’s cached report grains — the agent twin of the report footer’s “Refresh this report” action (refresh_report_scope) — so its reports recompute from current data on the next view (a heavy slice recomputes off the request path; see crate::frontend::concerns::serve_report). Scoped, unlike the global bust refresh_reports does. The bust is an instant keyed DELETE, so this returns 200 OK immediately — there is no background job to poll. Token-gated via the Actor guard (X-Cortex-Token header or ?token=); 401 without a valid token, 404 on an unknown corpus/service.

refresh_reports

Forces a rebuild of the report_summary rollup that backs every report page, as a background job — the rebuild is multi-minute at production scale, so it must not block the request (see docs/archive/REPORT_FRESHNESS.md). Returns the job handle immediately (202 Accepted); poll GET /api/jobs/<job> for status/health. Debounced: a refresh already in flight is reused rather than piled on. Token-gated via the Actor guard (X-Cortex-Token / ?token=); 401 without a valid token.

refresh_reports_human

The human twin of refresh_reports: the jobs-dashboard “Refresh reports now” button. Gated by the signed-in AdminSession cookie (the jobs dashboard is signed-in-only; anonymous → sign-in), spawns the same debounced refresh job, and redirects to /jobs where the admin watches it run — the async UI pattern (no blocking, no JS).

rerun_report

Marks the selected (corpus, service[, severity, category, what]) scope for reprocessing — the agent twin of the report screen’s rerun action, and a new historical run. Token-gated via the Actor guard (X-Cortex-Token header or ?token=); 401 without a valid token, so results can’t be wiped by an unauthenticated caller. 400 on an unknown severity, 404 on an unknown corpus/service. Returns 202 Accepted.

resume_all_api

Resume all conversions — return every Blocked task fleet-wide to TODO. The agent twin of the dashboard’s “Resume all conversions”. Token-gated; returns the count resumed.

resume_run_api

Resume a run — return every Blocked task (status < -5) of a (corpus, service) to TODO so the dispatcher picks them up again. The agent twin of the report screen’s “Resume run” button. Token-gated via the Actor guard; 404 on an unknown corpus/service. Returns the count resumed.

routes

The route set for the reports capability (typed API + the human report screens).

severity_service_report

Severity-level report: the categories carrying messages of severity.

severity_service_report_all

Severity-level report with paging/all-messages query params.

top_service_report

Top-level corpus/service report (overall progress).

what_service_report

what-level report: the task list for a (severity, category, what).

what_service_report_all

what-level report with paging/all-messages query params.