1 lightning.finite_horizon.certification

lightning.finite_horizon.certification

Bounded population certification for learned finite-horizon Q_2.

This module evaluates a frozen scorer bundle against the factual dense- successor two-step target already owned by aria_nbv.lightning.finite_horizon.module.QhLightningModule.compute_exact_q2_targets. It does not define another Bellman target, train a model, or perform endpoint policy evaluation. Its narrow responsibility is to select a deterministic, stratified, bounded subset of a frozen held-out corpus and quantify how closely the learned recursive target

.. math::

r_t + t Q{}(s_{t+1}, a^*, 1)

matches the factual finite-support control

.. math::

r_t + t {aA_{}(s_{t+1})} r_{t+1}(a).

The resulting error is model evidence: it measures the learned Q_1 path inside the recursion. Candidate and selected-action rows from one scene are correlated observations, not independent replications. V2 therefore aggregates the row ledger by (ordered_store_manifest_sha256, scene_id) and requires every selected unit to pass. It is distinct from implementation-recursion parity, which injects an exact one-step table and belongs in unit tests. Positive oracle-lookahead headroom is also distinct and remains an independently owned endpoint-policy prerequisite for claims above horizon two.

1.1 Classes

Name	Description
QhDecoderSupport	Optional fixed scalar support exposed by an ordinal value decoder.
QhExactQ2CertificationSpec	Frozen selection, support, and numeric gates for one certification run.
QhExactQ2Certifier	Certify one frozen scorer against selected factual exact-Q_2 rows.

1.1.1 QhDecoderSupport

lightning.finite_horizon.certification.QhDecoderSupport(
    kind,
    lower_representative,
    upper_representative,
    lower_edge,
    upper_edge,
)

Optional fixed scalar support exposed by an ordinal value decoder.

Regression has no finite decoder support and passes None. A CORAL caller supplies the lowest/highest class representatives and threshold edges so the receipt can distinguish decoded-value saturation from outer- class occupancy. These values diagnose support choice; they do not change Bellman targets or candidate ranking.

1.1.1.1 Attributes

Name	Description
kind	Decoder family; V2 admits only "coral" on this finite-support path.
lower_representative	Lowest decoded continuous-Q representative.
upper_representative	Highest decoded continuous-Q representative.
lower_edge	Lowest ordinal label boundary.
upper_edge	Highest ordinal label boundary.

1.1.2 QhExactQ2CertificationSpec

lightning.finite_horizon.certification.QhExactQ2CertificationSpec(
    absolute_tolerance,
    relative_tolerance,
    minimum_independent_units,
    minimum_exact_rows_per_independent_unit,
    independent_unit_aggregation,
    minimum_population_coverage=0.95,
    max_selected_chains=4096,
    max_chains_per_stratum=64,
    selection_seed=0,
    positive_headroom_threshold=1e-08,
)

Frozen selection, support, and numeric gates for one certification run.

1.1.2.1 Parameters

Name	Type	Description	Default
absolute_tolerance	float	Absolute fitted-target error admitted per exact Q_2 row, in root-normalized return units.	required
relative_tolerance	float	Additional tolerance proportional to the absolute exact target value. This is never used to divide near-zero targets.	required
minimum_independent_units	int	Smallest number of selected scene-level units with exact evidence allowed to support promotion.	required
minimum_exact_rows_per_independent_unit	int	Smallest exact factual selected-action support required within every selected unit.	required
independent_unit_aggregation	Literal['all_units_v1']	Closed policy requiring every selected unit to pass its row support and numeric tolerances.	required
minimum_population_coverage	float	Minimum fraction of census chains selected by the bounded stratified sampler. Coverage is over chain identity, not over unobserved eligible Q_2 rows.	0.95
max_selected_chains	int	Global materialization and scorer-call bound.	4096
max_chains_per_stratum	int	Per-stratum cap before balanced allocation.	64
selection_seed	int	Integer mixed into deterministic identity hashes. It changes the selected evidence and is therefore receipt identity.	0
positive_headroom_threshold	float	Minimum positive endpoint gain used only when summarizing the separately owned oracle-headroom diagnostic. It does not relax or tighten exact-Q_2 target agreement.	1e-08

1.1.2.2 Notes

The stratum freezes scene, target row, configured horizon, candidate- width bin, candidate generator, rollout recipe, and behavior policy. Candidate width is finite-table support; it is not a tree branch axis.

1.1.2.3 Attributes

Name	Description
absolute_tolerance	Finite nonnegative absolute error allowance in additive return units.
relative_tolerance	Finite nonnegative allowance scaled by the absolute exact target.
minimum_independent_units	Required number of selected scene units with exact factual support.
minimum_exact_rows_per_independent_unit	Required factual selected-action exact rows within every selected unit.
independent_unit_aggregation	Closed policy under which no pooled statistic may hide a failed unit.
minimum_population_coverage	Minimum selected fraction of the metadata-visible chain population.
max_selected_chains	Global upper bound on chain materialization and scorer calls.
max_chains_per_stratum	Per-stratum chain cap before balanced allocation.
selection_seed	Seed mixed into deterministic chain-identity ranking.
positive_headroom_threshold	Separate oracle-headroom diagnostic threshold; never an error tolerance.

1.1.3 QhExactQ2Certifier

lightning.finite_horizon.certification.QhExactQ2Certifier(spec)

Certify one frozen scorer against selected factual exact-Q_2 rows.

The certifier first performs a metadata-only census through dataset.chain_identity. It then materializes at most spec.max_selected_chains complete chains, preserving causal history and successor linkage while bounding actor-store and scorer work. Hard masks remain owned by QhLightningModule; this class consumes its public admitted and exact-support tensors and never substitutes a learned feasibility decision.

1.1.3.1 Theory

Rows within one scene share geometry, target-generation conditions, candidate policy, and rollout lineage. Treating them as independent would create pseudoreplication: increasing candidate or chain count could manufacture apparent evidence without increasing scene diversity. V2 therefore uses

\[ u=(\operatorname{sha256}(M_1,\ldots,M_K),\;\mathrm{scene\_id}) \]

as the independent unit, where the ordered manifest digest binds the complete store population. Row errors remain auditable, but promotion requires the predeclared minimum number of units and an all_units_v1 pass. Five units are a minimum diversity/admissibility floor, not a statistical-power or generalization guarantee.

1.1.3.2 Methods

Name	Description
certify	Return deterministic exact-Q_2 population evidence.

1.1.3.2.1 certify

lightning.finite_horizon.certification.QhExactQ2Certifier.certify(
    module,
    dataset,
    device,
    ordered_store_manifest_sha256,
    decoder_support=None,
)

Return deterministic exact-Q_2 population evidence.

1.1.3.2.1.1 Parameters

Name	Type	Description	Default
module	QhLightningModule	Frozen online/target scorer composition. The target copy must already contain the same selected bundle weights.	required
dataset	_QhCertificationDataset	Frozen held-out chain population with metadata-only chain identities and dense-valid fitted-Q supervision.	required
device	torch.device	Device used only for scorer and target computation.	required
ordered_store_manifest_sha256	str	Digest of the ordered rollout-store manifest tuple bound by the evaluated bundle. Together with scene_id it defines one independent evidence unit.	required
decoder_support	QhDecoderSupport | None	Fixed CORAL scalar support, or None for direct continuous regression.	None

1.1.3.2.1.2 Returns

Name	Type	Description
	dict[str, object]	JSON-safe evidence containing population census, selected row
	dict[str, object]	ledger, per-stratum aggregates, tolerance results, and decoder-
	dict[str, object]	support diagnostics. learned_recursion_passed concerns the
	dict[str, object]	trained model; it is not an implementation-parity claim.

1.1.3.2.1.3 Raises

Name	Type	Description
	ValueError	If corpus identity is incomplete, a materialized chain disagrees with its census identity, exact support escapes the learner’s admitted support, or numeric evidence is non-finite.