1 lightning.finite_horizon.diagnostic_evidence

lightning.finite_horizon.diagnostic_evidence

Read and reduce immutable finite-horizon QH diagnostic evidence.

The public product keeps three different claims separate. Cell disposition describes execution, original-label H1 metrics describe diagnostic label prediction, and longer-horizon residuals describe fitted objective support. None of these quantities is a calibrated reconstruction-quality measurement.

Rows are reduced within a held-out scene, then seeds within that scene, and only then across scenes. A state row is therefore never treated as an independent scene-level replicate.

1.1 Classes

Name	Description
QhDiagnosticCellDisposition	Observed state of one cell from the frozen assignment.
QhDiagnosticCellEvidence	Validated evidence for one assignment cell.
QhDiagnosticEvidence	Read-only product for one frozen QH diagnostic assignment.
QhDiagnosticHistoryAvailability	Availability of optional, non-authoritative fit telemetry.
QhDiagnosticHistoryEvidence	Receipt-bound local telemetry; it has no fit-result authority.
QhDiagnosticLossCurve	One producer-declared loss series and its retained event denominator.
QhDiagnosticLossPoint	One supported optimization or validation loss observation.
QhH1Decision	Provisional original-label H1 decision from equal-scene comparisons.
QhH1RunMetrics	State-reduced original-label diagnostics for one held-out scene and seed.
QhH1SceneComparison	Seed-aware H1 comparison reduced to one independent held-out scene.
QhHorizonSupport	Fitted and held-out support for one factual prediction horizon.

1.1.1 QhDiagnosticCellDisposition

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticCellDisposition()

Observed state of one cell from the frozen assignment.

1.1.1.1 Attributes

Name	Description
PLANNED	The assignment exists, but the cycle has no terminal inventory yet.
COMPLETED	The cell has a complete outcome and all required receipts.
FAILED	The cell retained a failed or interrupted terminal outcome.
MISSING	A terminal cycle inventory names the cell, but its outcome is absent.

1.1.2 QhDiagnosticCellEvidence

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticCellEvidence(
    cell_id,
    fold,
    held_out_scene,
    objective,
    model,
    seed,
    disposition,
    failure,
    h1_metrics,
    horizons,
    content_sha256=None,
    history=_UNAVAILABLE_HISTORY,
)

Validated evidence for one assignment cell.

1.1.2.1 Attributes

Name	Description
cell_id	Path-stable cell identity relative to the evidence root.
fold	Frozen scene-held-out fold number.
held_out_scene	Scene used only for held-out evaluation in this fold.
objective	Fitted objective family; constants belong to the H1 family.
model	Diagnostic model or training-fitted constant control.
seed	Fit seed; the deterministic constant control has no seed.
disposition	Planned, completed, failed, or missing execution state.
failure	Typed retained failure detail for failed or incomplete evidence.
h1_metrics	Original-label H1 diagnostics for completed matrix cells.
horizons	Fitted horizon support with optional held-out residual support.
content_sha256	Digest binding validated bytes, including partial artifacts of a missing cell.
history	Optional receipt-bound optimization telemetry; historical fits remain unavailable.

1.1.3 QhDiagnosticEvidence

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticEvidence(
    root,
    mode,
    source_revision,
    content_sha256,
    planned_cell_count,
    disposition_counts,
    cells,
    h1_decision,
    interpretation='diagnostic_label_prediction_not_calibrated_reconstruction_quality',
)

Read-only product for one frozen QH diagnostic assignment.

1.1.3.1 Attributes

Name	Description
root	Resolved evidence root; source files are never modified.
mode	Frozen assignment mode.
source_revision	Source revision recorded by the assignment.
content_sha256	Digest binding all source bytes validated by this read transaction.
planned_cell_count	Number of cells derived from the frozen folds, models, and seeds.
disposition_counts	Counts over the complete planned population.
cells	Every planned cell in deterministic fold/objective/model/seed order.
h1_decision	Scene-held-out H1 decision for a matrix with sufficient evidence.
interpretation	Mandatory scientific scope of all label-prediction quantities.

1.1.4 QhDiagnosticHistoryAvailability

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticHistoryAvailability()

Availability of optional, non-authoritative fit telemetry.

1.1.5 QhDiagnosticHistoryEvidence

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticHistoryEvidence(
    availability,
    path,
    event_count,
    curves,
    detail=None,
    content_sha256=None,
)

Receipt-bound local telemetry; it has no fit-result authority.

1.1.6 QhDiagnosticLossCurve

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticLossCurve(
    kind,
    semantics,
    points,
    supporting_event_count,
)

One producer-declared loss series and its retained event denominator.

1.1.7 QhDiagnosticLossPoint

lightning.finite_horizon.diagnostic_evidence.QhDiagnosticLossPoint(
    optimizer_update,
    value,
)

One supported optimization or validation loss observation.

1.1.8 QhH1Decision

lightning.finite_horizon.diagnostic_evidence.QhH1Decision(
    signal,
    practical_tie_band,
    scene_comparisons,
    equal_scene_mean_practical_regret,
    root_scene_wins,
    shuffled_scene_wins,
    root_vs_shuffled_scene_wins,
)

Provisional original-label H1 decision from equal-scene comparisons.

1.1.8.1 Attributes

Name	Description
signal	Diagnostic development signal, never a reconstruction-quality claim.
practical_tie_band	Minimum regret difference used for practical H1 comparisons.
scene_comparisons	Per-scene model means after seed reduction.
equal_scene_mean_practical_regret	Equal-scene model means; missing scene support produces None.
root_scene_wins	Scenes where root improves over geometry, or None without full support.
shuffled_scene_wins	Scenes where the shuffled-label null improves over geometry.
root_vs_shuffled_scene_wins	Scenes where root has strictly lower regret than the shuffled-label null.

1.1.9 QhH1RunMetrics

lightning.finite_horizon.diagnostic_evidence.QhH1RunMetrics(
    planned_states,
    admitted_states,
    reason_counts,
    zero_or_practical_tie_states,
    informative_states,
    informative_pairs,
    pair_order_fraction,
    mean_raw_regret,
    mean_practical_regret,
    mean_absolute_error,
)

State-reduced original-label diagnostics for one held-out scene and seed.

1.1.9.1 Attributes

Name	Description
planned_states	All state rows retained by the H1 evaluation receipt.
admitted_states	Rows with finite labels and predictions admitted to numerical summaries.
reason_counts	Counts by admission or exclusion reason, retaining the planned denominator.
zero_or_practical_tie_states	Admitted states whose regret is inside the configured practical tie band.
informative_states	Admitted states containing at least one label-separated candidate pair.
informative_pairs	Candidate pairs with label separation larger than the practical tie band.
pair_order_fraction	Correctly ordered informative pairs divided by informative pairs.
mean_raw_regret	Mean selected-candidate raw regret over admitted states.
mean_practical_regret	Mean tie-banded regret over admitted states.
mean_absolute_error	Mean candidate-label absolute error over admitted states.

1.1.10 QhH1SceneComparison

lightning.finite_horizon.diagnostic_evidence.QhH1SceneComparison(
    scene_id,
    model,
    seeds,
    mean_practical_regret,
)

Seed-aware H1 comparison reduced to one independent held-out scene.

1.1.10.1 Attributes

Name	Description
scene_id	Independent held-out scene identity.
model	Compared diagnostic model.
seeds	Completed seeds contributing to this scene mean.
mean_practical_regret	Mean of seed-level state means; constant controls have no seed axis.

1.1.11 QhHorizonSupport

lightning.finite_horizon.diagnostic_evidence.QhHorizonSupport(
    horizon,
    fitted_state_count,
    fitted_candidate_count,
    held_out_state_count,
    held_out_mean_loss,
    held_out_mean_absolute_error,
)

Fitted and held-out support for one factual prediction horizon.

1.1.11.1 Attributes

Name	Description
horizon	One-based factual horizon.
fitted_state_count	Training states supporting this fitted horizon.
fitted_candidate_count	Training candidates supporting this fitted horizon.
held_out_state_count	Held-out states in the residual receipt, or None when unevaluated.
held_out_mean_loss	Held-out bootstrapped TD loss; this is not policy return.
held_out_mean_absolute_error	Held-out target error; this is not reconstruction calibration.

1.2 Functions

Name	Description
classify_qh_assignment_marker	Identify QH-owned assignment names before a mixed evidence catalog admits them.
read_qh_diagnostic_evidence	Validate and reduce one immutable diagnostic-cycle directory.
read_qh_h1_run_metrics	Read one H1 receipt and reduce state rows without changing the scene unit.
read_store_metadata_sha256	Read JSON bytes once and return the validated object with their digest.

1.2.1 classify_qh_assignment_marker

lightning.finite_horizon.diagnostic_evidence.classify_qh_assignment_marker(path)

Identify QH-owned assignment names before a mixed evidence catalog admits them.

This is only a dispatch probe. The full reader below remains responsible for validating the assignment and its bound evidence. A malformed or schema-less file stays ambiguous so a QH attempt can still appear as an invalid catalog entry rather than silently disappearing.

1.2.2 read_qh_diagnostic_evidence

lightning.finite_horizon.diagnostic_evidence.read_qh_diagnostic_evidence(root)

Validate and reduce one immutable diagnostic-cycle directory.

The reader validates assignment/cohort identity, terminal inventory hashes, complete-cell fit and evaluation receipt bindings. An incomplete cell retains the digest of every artifact validated before its missing receipt. Missing terminal-inventory artifacts are represented as missing cells; contradictory digests or identities fail closed.

1.2.3 read_qh_h1_run_metrics

lightning.finite_horizon.diagnostic_evidence.read_qh_h1_run_metrics(
    path,
    *,
    expected_scene=None,
    expected_practical_tie_band=None,
)

Read one H1 receipt and reduce state rows without changing the scene unit.

1.2.4 read_store_metadata_sha256

lightning.finite_horizon.diagnostic_evidence.read_store_metadata_sha256(path)

Read JSON bytes once and return the validated object with their digest.