V0.20 Scope - Unified Generator Confidence Reports#

Summary#

v0.20 is a reporting/supportability release.

Stable path:

residual / fit / verification / candidate-validation / orbit diagnostics -> JSON-compatible generator confidence report -> categorical evidence label and component statuses

This release promotes the notebook confidence-card teaching pattern into one public runtime reporting helper.

Stable Scope#

v0.20 adds submodule-only runtime APIs:

  • pdelie.reporting.summarize_generator_confidence(...)

  • pdelie.examples.run_generator_confidence_report_example(...)

No root pdelie export is added.

Confidence Helper#

Frozen signature:

pdelie.reporting.summarize_generator_confidence(
    *,
    residual=None,
    generator=None,
    fit_diagnostics=None,
    verification=None,
    candidate_validation=None,
    coverage=None,
    consistency=None,
    orbit=None,
    thresholds=None,
    extra_metrics=None,
) -> dict[str, Any]

The helper accepts canonical ResidualBatch, GeneratorFamily, and VerificationReport objects where available, plus existing runtime report mappings for residual, fit, verification, candidate validation, coverage, consistency, and orbit evidence.

If generator is a GeneratorFamily, the helper nests both summarize_generator_family(...) and summarize_generator_fit_diagnostics(...) unless explicit fit_diagnostics is supplied.

Report Semantics#

Frozen output fields:

  • summary_schema_version = "0.1"

  • summary_type = "generator_confidence"

  • confidence_label

  • component_statuses

  • nested evidence summaries

  • thresholds

  • missing_evidence

  • extra_metrics

Frozen confidence_label values:

  • strong

  • qualified

  • failed

  • insufficient_evidence

Frozen component statuses:

  • passed

  • warning

  • failed

  • not_configured

  • unavailable

No scalar confidence score ships in v0.20.

Threshold Policy#

Supported threshold keys:

  • residual_max_abs

  • residual_rms

  • verification_first_error

  • verification_max_error

  • coverage_fraction_min

Residual and coverage checks are pass/fail only when corresponding thresholds are configured. Verification passes when classification is not failed unless configured error thresholds fail. Fit and candidate validation use existing evidence labels and conclusion labels.

Non-goals#

v0.20 does not add:

  • scalar confidence score

  • benchmark success policy

  • train/test split policy

  • heldout-leakage policy

  • transformed FieldBatch collections from reporting helpers

  • canonical confidence object

  • new PDEs

  • KS runtime promotion

  • weak-form expansion

  • broad dataset adapters

  • time-translation APIs

  • neural or callable generator APIs

  • operator-facing APIs

  • root pdelie exports

Milestone Status#

  • Milestone 0: COMPLETE - scope freeze

  • Milestone 1: COMPLETE - semantics freeze

  • Milestone 2: COMPLETE - reporting helper implementation

  • Milestone 3: COMPLETE - example and notebook alignment

  • Milestone 4: COMPLETE - cross-PDE confidence coverage

  • Milestone 5: COMPLETE - API/public-surface audit

  • Milestone 6: COMPLETE - release gate and readiness

Release Gate Expectations#

v0.20 is complete only if:

  • summarize_generator_confidence(...) is documented and importable from pdelie.reporting

  • root pdelie remains unchanged

  • reports are JSON-compatible

  • direct-SVD, fallback, partial-validation, failed-candidate, residual-threshold-failure, and insufficient-evidence cases are covered

  • example output is JSON only

  • no new numerical scope, KS runtime API, weak-form expansion, broad adapter, train/test policy, scalar score, or operator-facing API lands

  • package/readiness docs preserve the v1.0 package-index publishing deferral