# Quality Hardening and Failure Contracts

The development API is deliberately frozen during this hardening phase. The purpose is to deepen integration and maintenance guarantees rather than add new analytical surface area.

## Public API contract

A machine-readable manifest records all exported function names and formal argument names. Tests compare the installed namespace against this manifest so accidental public additions, removals, or signature changes become explicit failures rather than silent drift.

The relevant governance interfaces include `validate_gp3bayes_object()`, `capture_gp3bayes_schema()`, `validate_gp3bayes_schema()`, `create_analysis_manifest()`, and `compare_analysis_manifests()`.

## Lightweight post-fit adapters

Small adapters are useful because they let downstream reports use stable data frames rather than inspect internal object fields. Examples include `backend_environment_table()`, `loo_influence_atlas_table()`, `prediction_profile_table()`, `prediction_surface_table()`, `prediction_draws_long()`, and `prior_posterior_draws_long()`.

## Explicit failure boundaries

Fit-dependent extraction helpers such as `extract_expected_predictions()`, `extract_posterior_predictions()`, `extract_linear_predictions()`, `extract_log_likelihood()`, and `extract_sampler_diagnostics()` reject malformed inputs rather than guessing.

Prediction-comparison helpers retain explicit bounds. In particular, `prediction_pairwise_contrasts()` and `prediction_rank_probabilities()` require the analyst to opt into larger comparison sets rather than expanding combinatorially without review.

## Prediction diagnostics

The diagnostic layer separates descriptive posterior evidence from automatic decisions. `binary_group_calibration()`, `posterior_predictive_summary_table()`, `predictive_coverage_table()`, `duration_pit_table()`, and `loo_group_influence_table()` return evidence for review; none automatically certifies adequacy or excludes observations/groups.

## Output safety

Writers such as `write_model_card()`, `write_publication_registry()`, `write_diagnostic_dashboard_report()`, `write_analysis_bundle_report()`, and `save_publication_registry_figures()` remain explicit-output operations. The package does not use the current working directory as an implicit reporting destination.

## Why examples are selective

Not every exported wrapper has a runnable Rd example. Many functions require a fitted Bayesian backend object, and duplicating expensive fits across hundreds of help topics would make checks slower without improving the underlying API. The package therefore combines short deterministic Rd examples for lightweight functions with articles, unit tests, integration tests, and complete reference documentation for fit-dependent workflows.