1 lightning.finite_horizon.experiment

lightning.finite_horizon.experiment

Immutable finite-horizon QH training, certification, and inference.

This module owns experiment-level composition of validated stage datasets, scorer construction, masked Double-Q optimization, deterministic checkpoint selection, content-addressed receipts, atomic bundle publication, explicit held-out evaluation, and bounded exact-Q_2 certification. Scorer architecture stays in aria_nbv.vin; factual replay and actor joins remain with their data owners.

1.1 Classes

Name	Description
QhDiagnosticFitRequest	Train a research model without granting deployable bundle identity.
QhDiagnosticH1EvaluationRequest	Evaluate verified fixed H1 predictions on an explicitly bound population.
QhDiagnosticHorizonEvaluationRequest	Read bootstrapped held-out residuals by supported factual horizon.
QhDiagnosticJointEvaluationRequest	Evaluate factual fitted-Q residuals and recorded action-selectability.
QhExactQ2CertificationRequest	Immutable request for bounded held-out learned-recursion evidence.
QhExactQ2CertificationResult	Immutable reference to one exact-Q_2 certification receipt.
QhExperiment	Fit, publish, verify, and reconstruct immutable QH bundles.
QhExperimentConfig	Compose the scorer, optimizer module, data loaders, and trainer.
QhFitRequest	Immutable inputs and output authority for one bounded fitted-Q run.
QhFitResult	Immutable bundle and receipt references emitted by one fit.
QhHeldOutEvaluationRequest	Immutable request for one explicit diagnostic held-out evaluation.
QhHeldOutEvaluationResult	Immutable result of an explicit diagnostic held-out evaluation.

1.1.1 QhDiagnosticFitRequest

lightning.finite_horizon.experiment.QhDiagnosticFitRequest(
    train,
    validation,
    test,
    checkpoint_selection,
    seed,
    output_dir,
    shuffle_h1_training_labels=False,
    source_identity=None,
    cold_initialization=None,
    metric_history_path=None,
    metric_history_identity=None,
    admitted_evaluator_identity=None,
    resume_from=None,
    active_checkpoint_dir=None,
)

Train a research model without granting deployable bundle identity.

The same stage admission applies. A diagnostic may retain the exact final optimizer update instead of selecting a validation checkpoint. Selected CF-GT observations remain privileged even though causal.

1.1.1.1 Attributes

Name	Description
train	Immutable training population.
validation	Scene-disjoint population for validation checkpoint selection.
test	Optional untouched population; None never constructs a test stage.
checkpoint_selection	Validation minimum or fixed final-update diagnostic rule.
seed	Lightning and DataLoader seed.
output_dir	New diagnostic directory; never a deployable inference bundle.
shuffle_h1_training_labels	Permute only admitted training-state H1 rewards with the fit seed.
source_identity	Validated source-cohort seals retained by receipt-backed cycle fits.
cold_initialization	Verified untrained common scorer parameters for controlled architecture fits.
metric_history_path	New JSONL attempt path outside output_dir; None disables telemetry.
metric_history_identity	Stable cell, fold, and seed identity for the sidecar.
admitted_evaluator_identity	Evaluator digest already admitted by the caller’s source-specific validation.
resume_from	Verified full-state checkpoint from the same execution identity.
active_checkpoint_dir	Mutable directory retaining the latest completed-epoch recovery checkpoint.

1.1.2 QhDiagnosticH1EvaluationRequest

lightning.finite_horizon.experiment.QhDiagnosticH1EvaluationRequest(
    fit,
    test,
    output_receipt_path,
    practical_tie_band=0.005,
    constant_fit=None,
    constant_training=(),
    population_role='test',
    device='cpu',
)

Evaluate verified fixed H1 predictions on an explicitly bound population.

1.1.2.1 Attributes

Name	Description
fit	Verified learned diagnostic fit, mutually exclusive with constant_fit.
test	Evaluation population whose reopened provenance must match its declared role.
output_receipt_path	New JSON destination for state-level diagnostic rows.
practical_tie_band	Absolute reward difference treated as a practical candidate tie.
constant_fit	Training-bound constant control, mutually exclusive with :attr:fit.
constant_training	Reopened training populations required to verify constant_fit before evaluation.
population_role	Receipt-bound evaluation role.
device	Inference device; CUDA transfer follows population admission and is recorded in GPU receipts.

1.1.3 QhDiagnosticHorizonEvaluationRequest

lightning.finite_horizon.experiment.QhDiagnosticHorizonEvaluationRequest(
    fit,
    test,
    output_receipt_path,
)

Read bootstrapped held-out residuals by supported factual horizon.

1.1.3.1 Attributes

Name	Description
fit	Verified multistep diagnostic fit whose held-out population is evaluated.
test	Held-out population whose reopened provenance must match the fit identity.
output_receipt_path	New JSON destination for per-horizon residual aggregates.

1.1.4 QhDiagnosticJointEvaluationRequest

lightning.finite_horizon.experiment.QhDiagnosticJointEvaluationRequest(
    fit,
    dataset,
    output_receipt_path,
    population_role='validation',
    device='cpu',
)

Evaluate factual fitted-Q residuals and recorded action-selectability.

The explicit population role binds validation or test evidence to the fit. Neither estimated continuation targets nor operational mask probabilities establish measured long-horizon policy return or pure geometric validity.

1.1.4.1 Attributes

Name	Description
fit	Content-verified legacy fitted-Q diagnostic checkpoint.
dataset	Exact population configuration retained under the selected fit role.
output_receipt_path	New destination for chain/horizon residuals and candidate probabilities.
population_role	Held-out role; TRAIN and canary evaluation are excluded.
device	CPU, CUDA, or MPS inference device; model parameters remain frozen.

1.1.5 QhExactQ2CertificationRequest

lightning.finite_horizon.experiment.QhExactQ2CertificationRequest(
    bundle,
    test,
    spec,
    output_receipt_path,
    device='cpu',
    headroom_store_dir=None,
)

Immutable request for bounded held-out learned-recursion evidence.

1.1.5.1 Parameters

Name	Type	Description	Default
bundle	QhInferenceBundleRef	Verified scorer bundle whose frozen weights are evaluated.	required
test	QhDatasetConfig	Exact held-out dataset configuration already bound by the bundle manifest; a different population is rejected.	required
spec	QhExactQ2CertificationSpec	Numeric tolerances and deterministic stratified selection bounds.	required
output_receipt_path	Path	New JSON destination; existing paths are rejected.	required
device	str	Torch device used for scorer evaluation. Dataset census and materialization remain CPU-owned until each selected batch moves.	'cpu'
headroom_store_dir	Path | None	Optional validated rollout store from which the existing exact-role oracle-headroom diagnostic is summarized. This diagnostic is a persisted terminal-step proxy, not independent endpoint evaluation, and can never satisfy the longer-horizon gate.	None

1.1.6 QhExactQ2CertificationResult

lightning.finite_horizon.experiment.QhExactQ2CertificationResult(
    receipt_path,
    receipt_sha256,
)

Immutable reference to one exact-Q_2 certification receipt.

1.1.6.1 Attributes

Name	Description
receipt_path	JSON receipt containing bound census, row, and gate evidence.
receipt_sha256	Digest of :attr:receipt_path.

1.1.7 QhExperiment

lightning.finite_horizon.experiment.QhExperiment(config)

Fit, publish, verify, and reconstruct immutable QH bundles.

A fit admits nonempty scene-disjoint train, validation, and test datasets, constructs a scorer and masked Double-Q module, selects the minimum validation-loss checkpoint with deterministic tie breaking, and atomically publishes scorer weights plus content-bound receipts. Held-out evaluation and exact-Q_2 certification are explicit later requests; fit never uses test metrics for checkpoint selection.

Published bundles contain inference dependencies rather than resumable training state. load_for_inference verifies hashes, configuration, implementation identity, calibration support, representation semantics, and trained horizons before returning an evaluation-mode scorer.

1.1.7.1 Methods

Name	Description
fit	Train from immutable stages and atomically publish one new bundle.
fit_diagnostic	Fit through the existing trainer without publishing a deployment bundle.
fit_train_canary	Fit a final TRAIN checkpoint through the canonical Lightning lifecycle.
final_diagnostic_checkpoint	Return the verified final-budget reference without rewriting the fit receipt.
load_diagnostic_checkpoint	Load a verified local research checkpoint for diagnostic evaluation.
evaluate_diagnostic_h1	Retain original-label H1 predictions and state regret without fitting.
fit_h1_constant	Fit a scene-equal constant from original training H1 labels only.
evaluate_diagnostic_horizons	Retain held-out objective residuals without claiming policy return.
evaluate_diagnostic_joint	Retain scene-identifiable QH residuals and operational probabilities.
evaluate_held_out	Run diagnostic fitted-Q evaluation on the bundle’s frozen test population.
certify_exact_q2	Certify learned recursive Q_2 targets on the frozen test corpus.
load_for_inference	Verify a bundle and return its scorer with manifest-derived identities.

1.1.7.1.1 fit

lightning.finite_horizon.experiment.QhExperiment.fit(request)

Train from immutable stages and atomically publish one new bundle.

1.1.7.1.1.1 Parameters

Name	Type	Description	Default
request	QhFitRequest	Stage configurations, optional verified warm-start weights, deterministic checkpoint rule, seed, and a new output directory.	required

1.1.7.1.1.2 Returns

Name	Type	Description
	QhFitResult	Bundle reference plus hashed training and checkpoint-selection
	QhFitResult	receipts. The output directory becomes visible only after complete
	QhFitResult	publication.

1.1.7.1.1.3 Raises

Name	Type	Description
	FileExistsError	If the requested immutable destination exists.
	ValueError	If stage, profile, horizon, geometry, warm-start, or checkpoint identities are incompatible.
	RuntimeError	If fitting produces no realized horizon support.

1.1.7.1.2 fit_diagnostic

lightning.finite_horizon.experiment.QhExperiment.fit_diagnostic(request)

Fit through the existing trainer without publishing a deployment bundle.

This operation admits the configured CF0 or privileged CF+ profile, retains complete Lightning checkpoints, and applies ordinary scene separation and checkpoint selection. It does not relax inference bundle admission or create a new optimization loop.

A final-update diagnostic may explicitly disable trainer validation for a training-only preflight. Its selected validation loss is None and its validation denominator remains zero; dataset identities and scene separation are still admitted normally.

1.1.7.1.3 fit_train_canary

lightning.finite_horizon.experiment.QhExperiment.fit_train_canary(request)

Fit a final TRAIN checkpoint through the canonical Lightning lifecycle.

No held-out population is constructed. The distinct canary receipt is loadable for research evaluation, never as an inference bundle. Ordinary diagnostics retain validation admission and scene separation.

1.1.7.1.4 final_diagnostic_checkpoint

lightning.finite_horizon.experiment.QhExperiment.final_diagnostic_checkpoint(
    result,
)

Return the verified final-budget reference without rewriting the fit receipt.

1.1.7.1.5 load_diagnostic_checkpoint

lightning.finite_horizon.experiment.QhExperiment.load_diagnostic_checkpoint(
    result,
    *,
    device='cpu',
)

Load a verified local research checkpoint for diagnostic evaluation.

Returns an evaluation-mode module, not an inference runtime and not a resumed Trainer. Both receipt and checkpoint bytes are checked before deserialization. Only load artifacts from a trusted local fit.

1.1.7.1.6 evaluate_diagnostic_h1

lightning.finite_horizon.experiment.QhExperiment.evaluate_diagnostic_h1(request)

Retain original-label H1 predictions and state regret without fitting.

The checkpoint and diagnostic fit receipt are verified before use. The dataset configuration must equal the one bound for its explicit role; every realized state receives a row, including unsupported/non-finite outcomes. Candidate ties select the lowest admitted index. Full-TRAIN diagnostics are explicitly in-sample and do not affect checkpoint selection.

1.1.7.1.7 fit_h1_constant

lightning.finite_horizon.experiment.QhExperiment.fit_h1_constant(train)

Fit a scene-equal constant from original training H1 labels only.

Candidates average within state, states within scene, then scenes equally. This control uses no held-out or recursive return labels.

1.1.7.1.8 evaluate_diagnostic_horizons

lightning.finite_horizon.experiment.QhExperiment.evaluate_diagnostic_horizons(
    request,
)

Retain held-out objective residuals without claiming policy return.

Recursive targets use the checkpoint’s online/target networks and the original factual rewards. A lower TD residual alone cannot establish counterfactual long-horizon ranking or reconstruction benefit.

1.1.7.1.9 evaluate_diagnostic_joint

lightning.finite_horizon.experiment.QhExperiment.evaluate_diagnostic_joint(
    request,
)

Retain scene-identifiable QH residuals and operational probabilities.

Reopen and verify the fit-bound held-out population before inference. One canonical transaction supplies dense Q1 and either factual bounded queries or the versioned continuing schedule; its same online output supplies feasibility probabilities. Continuing evaluation uses phase 0. Targets depend on the checkpoint’s delayed network and are residual diagnostics, not observed optimal continuation labels. Every materialized candidate supplies its recorded binary action mask, including invalid actions; padding supplies no classification label.

1.1.7.1.10 evaluate_held_out

lightning.finite_horizon.experiment.QhExperiment.evaluate_held_out(request)

Run diagnostic fitted-Q evaluation on the bundle’s frozen test population.

Configuration equality identifies the intended paths but cannot prove that immutable stores still occupy them. Evaluation therefore rebuilds the dataset and rechecks its learning semantics, actor/geometry contracts, full provenance, and ordered store-manifest hashes against the verified bundle before materializing a test batch. The receipt binds that observed provenance. This operation remains separate from fit and provides no endpoint-policy evidence; endpoint evaluation is owned by the online oracle contract.

1.1.7.1.10.1 Raises

Name	Type	Description
	FileExistsError	If the receipt destination already exists.
	ValueError	If the requested configuration or reconstructed test population has drifted from the frozen bundle identity.

1.1.7.1.11 certify_exact_q2

lightning.finite_horizon.experiment.QhExperiment.certify_exact_q2(request)

Certify learned recursive Q_2 targets on the frozen test corpus.

This operation evaluates the selected bundle but does not fit it. The exact control replaces the learned successor value with the maximum persisted one-step reward at the factual successor. Consequently the reported discrepancy isolates the bundle’s learned Q_1 path inside the two-step recursion; it does not re-test tensor-indexing parity and it does not estimate endpoint-policy headroom.

Hard-invalid rows remain excluded by the Lightning owner’s selected_train_mask and successor_backup_mask. The certifier never consults feasibility logits, never multiplies probability by Q, and never widens support beyond the frozen action/label masks.

1.1.7.1.11.1 Parameters

Name	Type	Description	Default
request	QhExactQ2CertificationRequest	Frozen bundle, exact test population, stratified-selection and tolerance contract, new output path, execution device, and optional diagnostic headroom store.	required

1.1.7.1.11.2 Returns

Name	Type	Description
	QhExactQ2CertificationResult	Receipt reference whose content binds the scorer, state fusion,
	QhExactQ2CertificationResult	decoder, actor/source profile, learning semantics, test provenance,
	QhExactQ2CertificationResult	row selection, tolerances, and optional headroom diagnostic.

1.1.7.1.11.3 Raises

Name	Type	Description
	FileExistsError	If the receipt destination already exists.
	ValueError	If bundle, dataset, device, lineage, or diagnostic store identity is invalid or has drifted from the frozen manifest.

1.1.7.1.11.4 Notes

longer_horizon_gate_passed requires both learned-recursion agreement and positive independent held-out endpoint headroom. The optional store diagnostic explicitly declares that it is not an independent endpoint evaluation, so a certification receipt cannot promote h>2 claims by itself.

1.1.7.1.12 load_for_inference

lightning.finite_horizon.experiment.QhExperiment.load_for_inference(
    ref,
    *,
    device,
)

Verify a bundle and return its scorer with manifest-derived identities.

1.1.7.1.12.1 Parameters

Name	Type	Description	Default
ref	QhInferenceBundleRef	Content-bound bundle reference whose schema and manifest hash must match the bytes on disk.	required
device	torch.device | str	Destination device for the reconstructed scorer.	required

1.1.7.1.12.2 Returns

Name	Type	Description
	QhInferenceRuntime	Evaluation-mode scorer and manifest-derived runtime identities used
	QhInferenceRuntime	by online context and trained-horizon admission.

1.1.7.1.12.3 Raises

Name	Type	Description
	ValueError	If the manifest, scorer state, configuration, support artifact, implementation identity, or hashes are inconsistent.

1.1.8 QhExperimentConfig

lightning.finite_horizon.experiment.QhExperimentConfig()

Compose the scorer, optimizer module, data loaders, and trainer.

1.1.8.1 Attributes

Name	Description
scorer	Actor-only scorer config; bundle publication admits deployable CF0 only.
module	Optimizer and Double-Q policy; contract hashes are rebound from admitted data during fit.
trainer	Bounded Lightning execution policy with V1 validation checkpointing.
batch_size	Number of complete rollout chains per batch.
num_workers	DataLoader worker process count.
mps_memory_budget_bytes	Opt-in post-batch live MPS allocation bound; driver pool is reported separately.
commissioning_milestones	Opt-in live optimizer/residency/reload commissioning gates; absent retains historical fitting.
train_scene_sampling	Optional fixed scene-equal block exposure; absent retains historical chain sampling.
pin_memory	Pin collated CPU tensors before accelerator transfer.
persistent_workers	Reuse workers between epochs when num_workers is positive.
objective_profile	Fitted-Q support contract; legacy support is diagnostic-only.
target_type	Return the concrete experiment constructed by :meth:setup_target.

1.1.9 QhFitRequest

lightning.finite_horizon.experiment.QhFitRequest(
    train,
    validation,
    test,
    warm_start_from,
    checkpoint_selection,
    seed,
    output_bundle_dir,
    shuffle_h1_training_labels=False,
)

Immutable inputs and output authority for one bounded fitted-Q run.

1.1.9.1 Attributes

Name	Description
train	Training dataset over one ordered tuple of immutable rollout stores.
validation	Scene-disjoint validation dataset used only for checkpoint selection.
test	Untouched scene-disjoint held-out dataset used after fitting.
warm_start_from	Verified prior bundle providing scorer weights only; optimizer state is never restored.
checkpoint_selection	Closed validation monitor, direction, and tie-break identity.
seed	Global Lightning and DataLoader seed recorded in the bundle.
output_bundle_dir	New immutable destination; any existing filesystem entry is rejected.
shuffle_h1_training_labels	Diagnostic H1-only null; never applies to validation or test labels.

1.1.10 QhFitResult

lightning.finite_horizon.experiment.QhFitResult(
    bundle,
    training_receipt_path,
    training_receipt_sha256,
    checkpoint_selection_receipt_path,
    checkpoint_selection_receipt_sha256,
)

Immutable bundle and receipt references emitted by one fit.

1.1.10.1 Attributes

Name	Description
bundle	Verified reference to the published inference bundle.
training_receipt_path	JSON receipt for trainer inputs, warm-start lineage, and optimizer updates.
training_receipt_sha256	Content digest of training_receipt_path.
checkpoint_selection_receipt_path	JSON receipt for the selected validation checkpoint.
checkpoint_selection_receipt_sha256	Content digest of checkpoint_selection_receipt_path.

1.1.11 QhHeldOutEvaluationRequest

lightning.finite_horizon.experiment.QhHeldOutEvaluationRequest(
    bundle,
    test,
    output_receipt_path,
)

Immutable request for one explicit diagnostic held-out evaluation.

1.1.11.1 Attributes

Name	Description
bundle	Verified bundle whose scorer and frozen test identity are evaluated.
test	Exact test population configuration bound to the bundle manifest.
output_receipt_path	New receipt destination; an existing path is rejected.

1.1.12 QhHeldOutEvaluationResult

lightning.finite_horizon.experiment.QhHeldOutEvaluationResult(
    receipt_path,
    receipt_sha256,
)

Immutable result of an explicit diagnostic held-out evaluation.

1.1.12.1 Attributes

Name	Description
receipt_path	Receipt containing diagnostic fitted-Q aggregates.
receipt_sha256	Digest of :attr:receipt_path.