% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{facets_output_contract_review}
\alias{facets_output_contract_review}
\title{Build a FACETS output-contract review}
\usage{
facets_output_contract_review(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  branch = c("facets", "original"),
  contract_file = NULL,
  include_metrics = TRUE,
  top_n_missing = 15L
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. If omitted,
diagnostics are computed internally with \code{residual_pca = "none"}.}

\item{bias_results}{Optional output from \code{\link[=estimate_bias]{estimate_bias()}}. If omitted and
at least two facets exist, a 2-way bias run is computed internally.}

\item{branch}{Contract branch. \code{"facets"} checks legacy-compatible columns.
\code{"original"} adapts branch-sensitive contracts to the package's compact
naming.}

\item{contract_file}{Optional path to a custom contract CSV.}

\item{include_metrics}{If \code{TRUE}, run additional numerical consistency checks.}

\item{top_n_missing}{Number of lowest-coverage contract rows to keep in
\code{missing_preview}.}
}
\value{
An object of class \code{mfrm_facets_contract_review} with:
\itemize{
\item \code{overall}: one-row output-contract review summary
\item \code{column_summary}: coverage summary by table ID
\item \code{column_review}: row-level output-contract review
\item \code{missing_preview}: lowest-coverage rows
\item \code{metric_summary}: one-row metric-check summary
\item \code{metric_by_table}: metric-check summary by table ID
\item \code{metric_checks}: row-level metric checks
\item \code{settings}: branch/contract metadata
}
}
\description{
Build a FACETS output-contract review
}
\details{
This function checks produced report components against a FACETS-style
output-contract specification (\code{inst/references/facets_column_contract.csv}) and
returns:
\itemize{
\item column-level coverage per contract row
\item table-level coverage summaries
\item optional metric-level consistency checks
}

It is intended for output-contract QA and regression review. It does
not establish external validity or software equivalence beyond the specific
schema/metric contract encoded in the contract file.
}
\section{Bounded GPCM boundary}{

This helper remains blocked for bounded \code{GPCM} fits in 0.2.1. The FACETS
output contract includes score-side rows whose measure-to-score and
uncertainty semantics are validated for the current Rasch-family route, not
for free-discrimination bounded \code{GPCM}. Use \code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}} before
routing a bounded \code{GPCM} fit into score-side compatibility-output helpers.

Coverage interpretation in \code{overall}:
\itemize{
\item \code{MeanColumnCoverage} and \code{MinColumnCoverage} are computed across all
contract rows (unavailable rows count as 0 coverage).
\item \code{MeanColumnCoverageAvailable} and \code{MinColumnCoverageAvailable} summarize
only rows whose source component is available.
}

\code{summary(out)} is supported through \code{summary()}.
\code{plot(out)} is dispatched through \code{plot()} for class
\code{mfrm_facets_contract_review} (\code{type = "column_coverage"}, \code{"table_coverage"},
\code{"metric_status"}, \code{"metric_by_table"}).
}

\section{Interpreting output}{

\itemize{
\item \code{overall}: high-level output-contract coverage and metric-check pass
rates.
\item \code{column_summary} / \code{column_review}: where output-schema mismatches
occur.
\item \code{metric_summary} / \code{metric_checks}: numerical consistency checks tied to the
current contract.
\item \code{missing_preview}: direct path to unresolved output-contract gaps.
}
}

\section{Typical workflow}{

\enumerate{
\item Run \code{facets_output_contract_review(fit, branch = "facets")}.
\item Inspect \code{summary(contract_review)} and \code{missing_preview}.
\item Patch upstream table builders, then rerun the output-contract review.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
contract_review <- facets_output_contract_review(fit, diagnostics = diag, branch = "facets")
summary(contract_review)
p <- plot(contract_review, draw = FALSE)
}
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=build_fixed_reports]{build_fixed_reports()}},
\link{mfrmr_compatibility_layer}
}
