PDELie Label Registry#

Status: advisory. This registry documents every label vocabulary that PDELie emits or accepts through its stable public reporting surfaces. Adding a new label family requires a scope-freeze note in the release that introduces it. Renaming or removing an existing label is a breaking change and is not permitted through a semver-patch release.

The registry exists because label vocabularies proliferate quickly (readiness, confidence, supportability, risk, verification, evidence, policy…) and become uncitable if not centrally documented. Downstream tooling that maps PDELie summaries into experiment trackers, dashboards, or publication tables should consume this registry rather than re-deriving allowed values from source.

Registry table#

Each row is one label family. Columns:

  • Field name — the JSON field the vocabulary populates.

  • Owner — the release that froze the vocabulary.

  • Summary type(s) — the summary_type string(s) of payloads that carry the field.

  • Allowed values — closed set. Downstream consumers must treat any value outside the set as a schema violation.

  • Semantics category — one of empirical (measured from data), diagnostic (measured from internal state), pass_fail (synthesis of underlying evidence), supportability (whether the release supports the configured setup), decision (a scope-freeze-time decision recorded in configured evidence).

  • Source reference — file+line in src/pdelie/ where the vocabulary is defined.

Field name

Owner

Summary type(s)

Allowed values

Category

Source reference

readiness_label

v0.21

field_batch_readiness, xarray_dataset_readiness

ready, needs_attention, not_ready

supportability

src/pdelie/reporting/summaries.py:40

confidence_label

v0.20

generator_confidence

strong, qualified, failed, insufficient_evidence

pass_fail

src/pdelie/reporting/summaries.py:38

supportability_label

v0.24

weak_form_supportability

supported_existing_slice, diagnostic_only, failed, insufficient_evidence

supportability

src/pdelie/reporting/summaries.py:107-110

risk_label

v0.23

split_leakage_provenance

no_detected_overlap, traceable_overlap, missing_provenance, inconclusive

supportability

src/pdelie/reporting/summaries.py:99-102

classification

v0.4

verification_report

exact, approximate, failed

empirical

src/pdelie/verification/finite_transform.py:58-61,105

conclusion

v0.16 (generator), v0.17 (formula)

symmetry_candidate_validation_report

validated, partially_validated, failed

empirical

src/pdelie/reporting/summaries.py:500-505

evidence_label

v0.11+

generator_fit_diagnostics, embedded in generator_family fit diagnostics

direct_svd_in_tolerance, reference_fallback, mixed, unavailable

diagnostic

src/pdelie/reporting/summaries.py:31-33

residual_domain_policy

v0.30c

residual_batch

full_grid, interior_only, drop_boundary_width_k, not_configured

diagnostic

src/pdelie/reporting/summaries.py:1320-1327

component status (per-component within confidence, weak-supportability, downstream-workflow synthesis)

v0.10

embedded in synthesis payloads

passed, warning, failed, not_configured, unavailable

diagnostic

src/pdelie/reporting/summaries.py:39

KdV scope decision labels

v0.25

kdv_scope_decision_example

current_frozen_supported, deferred_no_go

decision

docs/planning/V0_25_SCOPE.md + src/pdelie/examples/kdv_scope_decision.py

Categories in more depth#

empirical labels are measurements against the data with a documented threshold. verification.classification == "exact" requires the finite-transform error curve to remain below 1e-12; anything above but below the failure threshold is approximate; above the failure threshold is failed. symmetry_candidate.conclusion == "validated" requires every configured check to pass; partially_validated means one or more checks were unavailable but none failed; any failed check downgrades the whole candidate to failed.

diagnostic labels record internal state at report time. evidence_label reports which fit path produced the coefficients (direct_svd_in_tolerance = SVD produced a solution within the training epsilon; reference_fallback = we fell back to the reference generator; mixed = span metric agreed but not identity; unavailable = fit was skipped). residual_domain_policy records the trim rule the residual metrics used. Component status is the per-check summary before synthesis.

pass_fail labels are the final rollup of pass/fail synthesis. Today confidence_label is the only one: strong requires every configured component passed and evidence present; qualified allows warnings on non-critical components with the essential ones still passed; failed if any critical component fails; insufficient_evidence if too many components are not_configured/unavailable.

supportability labels are the release’s statement about whether the configured setup is supported. readiness_label, supportability_label, and risk_label are all in this category — none of them is a claim about numerical correctness beyond what the underlying checks measure; they encode whether PDELie’s release scope covers the case.

decision labels record scope-freeze-time decisions. The KdV current_frozen_supported / deferred_no_go pair is the only current instance; future scope-freeze artifacts will use the same shape (e.g. a hypothetical v0.32 The Well feasibility label lattice with scalar_slice_supported / blocked_multichannel_required, if that scope-freeze lands).

Vocabulary rules#

  1. Do not overload existing families. Adding qualified_with_reservations to confidence_label for a new evaluator is a breaking change and requires a new release cycle. Instead, introduce a new family (e.g. a discovery_task_supportability_label field on a new discovery_task_result summary) and document it here.

  2. Do not reuse the same string across incompatible families. failed appears in five families here, and that’s fine because they are distinguishable by the field name; a hypothetical failed_but_promotable in one family and a different meaning in another would break downstream consumers.

  3. Every new label vocabulary is a scope-freeze artifact. New families land through a docs/planning/V0_NN_SCOPE.md or docs/design/*.md document that names the field, allowed values, category, and semantics. The release-gate manifest (configs/release_gate_manifest.json) enforces the phrasing on the scope doc.

  4. Downstream tooling must not derive labels from source. MLflow / DVC / Weights & Biases integrations should consume this registry (or docs/specs/support_matrix.v0_30.json and its successors) rather than reading src/pdelie/reporting/summaries.py allowed-value frozensets. This is what protects the registry against silent drift.

  5. v0.31’s discovery_task_result will reuse existing families, not add a fifth discovery_task_supportability_label. Per the v0.31a scope freeze at docs/planning/V0_31_DISCOVERY_TASK_BRIDGE_SCOPE.md, the task-bridge release consumes readiness_label, confidence_label, and supportability_label on embedded sub-summaries and records warnings: list[str] at the top level. If a new task-level vocabulary genuinely becomes necessary in v0.31b or later, it will be added here first, then to the schema.

Planned additive extensions (not shipped)#

The following are planned as additive fields on existing summaries and are not part of any stable contract yet. They appear here so the label registry can grow in one place rather than fragmenting across release notes.

  • method_scores: dict[str, float] | None on generator_confidence (planned for v0.32a or later). Numeric per-component scores (span-distance, residual-l2, error-curve-max) alongside the existing categorical confidence_label. Enables downstream calibration studies without breaking the v0.20 frozen confidence_label contract.

  • uncertainty_report: dict | None on generator_confidence (planned for v0.32a or later). Where a method emits mean/variance/HDR intervals, this is where they land. None for point-estimate methods (the current default for polynomial_translation_svd).

  • calibration_report: dict | None on generator_confidence (planned for v0.32a or later). Reliability-diagram / ECE data where available. None for uncalibrated methods.

These three fields are scope-freeze-planned per docs/planning/PLAN.md’s v0.32a planning note. Downstream consumers may pre-register keys but must accept None until the fields ship as documented public API.

See also#

  • docs/specs/API_STABILITY.md — the source of truth for which summary functions and their labels are stable public API.

  • docs/specs/SUPPORT_MATRIX.md — the compact per-PDE support map.

  • docs/specs/support_matrix.v0_30.json — the current machine-readable release matrix.

  • docs/strategy/SCIENTIFIC_POSITIONING.md — brief vocabulary-boundaries summary.