Reporting

Purpose and authority boundary

Reporting consumes verified Protocol, Workflow, Deduplication, corpus snapshot, title/abstract conduct, Full Text cases, supplemental authority, provenance, and an immutable workspace-generation cut. It validates that every component describes the same review history, then derives counts, exclusion reasons, audit counts, gaps, disclosures, and explicit nonclaims.

Projection rule: the report is derived output. It cannot invent missing cases, collapse unresolved outcomes, or replace source authority. A diagnostic projection may contain gaps; a finalized report may not.

Verified review slice

VerifiedReviewWorkspaceCut
  ├─ Protocol generation
  ├─ Workflow generation
  ├─ Deduplication generation
  ├─ Corpus Snapshot generation
  ├─ Screening conduct generation
  └─ one Full Text generation per represented included candidate
        ↓ exact authority cross-checks
ReviewFlowProjection
        ↓ conservation + completeness + nonclaims
VerifiedReviewFlowReport

The workspace cut binds workspace id, project revision, role, generation id, manifest digest, and Full Text candidate where applicable. Duplicate or missing singleton roles, a Full Text generation for the wrong candidate, or drift between any manifest-bound authority fails before projection.

Key types and services

• VerifiedReviewWorkspaceCut makes the historical generation set explicit and digest-bearing.
• VerifiedReportingWorkflowAuthority adapts a verified Workflow, including waiver/amendment and template bindings, without accepting an id/digest pair as proof.
• ReviewSliceAuthorities is the full verified input cut; FullTextReviewCaseAuthorities groups each admission, exact artifact chain, conduct journal/handoff, and optional extraction.
• ReviewFlowProjector.Project validates bindings and derives ReviewFlowProjection with counts, reasons, audit counts, gaps, disclosures, and nonclaims.
• ReviewFlowProjector.Finalize enforces complete Full Text coverage, count conservation, reason totals, nonclaims, and deviation blockers.
• ReportingCanonicalCodec serializes and rehydrates the exact slice and report records from verified authorities.
• PersistedReportingVerifier performs strict byte-only shape, digest, count, reason, binding, and nonclaim verification at CLI/import boundaries.
• ReviewFlowMarkdownRenderer produces deterministic LF-only human-readable output from the verified report.

Source: NexusScholar.Reporting. Accepted FE-06 design: ADR 0033.

Count conservation and gaps

identified = duplicates_consolidated + post_dedup
post_dedup = title_abstract_included + title_abstract_excluded
title_abstract_included = full_text_included + full_text_excluded
included = full_text_included

sum(title/abstract reason counts) = title_abstract_excluded
sum(full-text reason counts)      = full_text_excluded

An included title/abstract candidate without one terminal Full Text case becomes a typed missing-full-text-case gap. Duplicate cases or cases for non-included candidates are invalid authority, not mere gaps. Conflicts, adjudications, corrections, and invalidations are counted from accepted journals rather than UI state.

Canonical records and disclosures

The slice schema is nexus.reporting.review-slice-binding/1.0.0; it binds every source digest and workspace generation. The report schema is nexus.reporting.review-flow-report/1.0.0; it binds the slice digest, source authorities, counts, reasons, audit counts, disclosures, and nonclaims. Both use canonical-json-record.

Verified waivers, amendments, deviations, and Rapid Review profile shortcuts must match exact Workflow/Protocol/template requirements. Shortcut consequences, mitigations, required mitigation artifacts, and reporting disclosure are compared exactly. An unresolved Protocol inconsistency blocks final reporting.

Typical developer flow

1. Resolve the immutable workspace cut and every source authority named by it.
2. Build ReviewSliceAuthorities; never substitute current pointers after the cut is fixed.
3. Call Project and expose gaps for remediation.
4. Call Finalize only after gaps and blocking deviations are resolved and explicit nonclaims are supplied.
5. Persist slice bytes, report bytes, Markdown, and digests together; package them with Bundle v2 and the export ledger.
6. At a process boundary, use PersistedReportingVerifier; full source-authority replay remains a stronger application-level operation.

Failure and refusal behavior

Stable categories reject invalid authority, incomplete slice, conservation failure, and noncanonical record. Specific checks catch stale Protocol/Workflow/snapshot/conduct/handoff, incomplete/foreign workspace generations, duplicate or wrong Full Text cases, unbound extraction, mismatched supplemental authority, altered Rapid Review shortcut, stale provenance, missing nonclaims, unresolved deviation, negative/inconsistent counts, duplicate reasons, unknown fields, and altered/noncanonical bytes.

Tests, extension points, and nonclaims

ReportingTests cover conserved finalization, gaps, authority drift, deviations, strict persisted shape, and deterministic rendering. ReportingFixtureTests replay reporting fixtures. Independent closure and full validation are recorded in FE-06 Completion Evidence.

New reporting standards should be separate versioned projections over the verified slice. The current module does not claim PRISMA certification, journal-submission conformance, statistical synthesis, narrative truth, archive identity, signatures, full CLI source replay, provider coverage, database/cloud behavior, or broad PHP compatibility.