1 vin.models.target_finite_horizon

vin.models.target_finite_horizon

Actor-only finite-horizon scorer for persisted :math:Q_H chain views.

By default the scorer estimates a scalar member of the bounded conditional-value family

\[ Q_h(s_t,e,q_{t,i}\mid b_t),\qquad 1 \le h \le b_t \le H_{\max}. \]

Here s_t is the actor-visible state before selecting action t: immutable root evidence, the strictly causal selected-pose prefix, the current finite candidate table, and factual remaining budget b_t. e is the target object represented by its root-relative pose and metric extents, and q_{t,i} is one materialized candidate camera. The requested residual horizon h selects an estimand; it is not a substitute for b_t and does not reveal future observations. Supervision, oracle lineage, and policy masks remain outside this module.

The opt-in continuing_scalar_v1 profile instead requires an explicit finite lookahead 1 <= h <= H_max independent of recorded chain length. Its budget projection receives zero, preserving parameter shapes while removing the artificial replay countdown from predictions. Recorded metadata is retained for validation and audit. This profile does not confer deployment certification.

The model implements the shared A0/A1--S0-pose--root-moments scorer. A1 candidate-to-state attention remains the default; A0 is its identical-input independent-row MLP control. For each materialized candidate row the scorer separates four information paths:

• a physical trunk encodes the candidate in the rollout-root and current-camera frames together with compact root-scene evidence; it is independent of the target, requested horizon, labels, and authoritative action_mask;
• a conditional-value query adds the target expressed in the candidate frame;
• the configured A0/A1 fusion combines that query with exactly five shared state tokens: scene, target, causal pose history, remaining budget :math:b_t, and requested residual horizon :math:h;
• a modular terminal decoder maps the shared feature to one continuous conditional value. Regression predicts it directly; CORAL discretizes the same fitted-Q target and decodes fixed continuous representatives.

The default root scene carrier is intentionally small and lossy: detached EVL channel moments plus root-frame semidense point mean, standard deviation, presence, and support. Privileged S1 may add a same-width residual formed from strictly causal selected-depth surfaces expressed from the factual current camera. Both are executable controls, not claims that global pooling is a sufficient reconstruction state. Candidate rows never exchange information, so a joint row permutation produces the same output permutation and duplicate rows remain identical.

1.1 Classes

Name	Description
TargetFiniteHorizonScorer	Predict candidate feasibility and conditional finite-horizon value.
TargetFiniteHorizonScorerConfig	Configure the actor-only finite-horizon value scorer.

1.1.1 TargetFiniteHorizonScorer

vin.models.target_finite_horizon.TargetFiniteHorizonScorer(config)

Predict candidate feasibility and conditional finite-horizon value.

The module exposes one deep interface: a batched QhActorTensors enters and one candidate-aligned QhScoreOutput leaves. Every materialized row is encoded independently of action_mask. Candidate rows never attend to one another, so jointly permuting candidate poses and masks permutes both outputs identically and invalid rows cannot influence valid rows.

1.1.1.1 Theory

The public family is

\[ Q_h(s_t,e,q_{t,i}\mid b_t),\qquad 1\le h\le b_t\le H_{\max}. \]

b_t is the factual number of acquisitions still available in the stored state; h is the number of rewards represented by this query. They are separately normalized by H_max and encoded by separate MLPs, so an off-diagonal query changes the value estimand without falsifying the actor state. None means the factual diagonal h=b_t. Realized rows reject h=0 or h>b_t; padded states use h=0 only. Q_0=0 is a mathematical backup boundary and has no learned output.

The physical trunk reads candidate root/current-relative pose and a compact root-scene summary. Its feasibility head therefore cannot read the target, requested horizon, remaining budget, labels, or action_mask. Conditional Q additionally reads candidate-to-target geometry and five shared state tokens: root scene, target, causal pose history, budget, and requested horizon. Candidate rows are independent queries over those shared tokens; no attention axis crosses candidates.

Geometry uses explicit transform direction. candidate_pose_relative_root is root-from-candidate :math:T_{r\leftarrow c_i}. The physical trunk also forms current-from-candidate :math:T_{c_t\leftarrow c_i}. Conditional Q receives candidate-from-target :math:T_{c_i\leftarrow e}, so the same target induces a different relation for every candidate without making feasibility target-dependent.

The target token encodes the root-relative target pose plus metric extents. Target source is an experiment-profile fact rather than something inferred from tensor shape. Scene context is the deliberately lossy root_moments_v1 carrier. Causal history first expresses the exact selected-pose prefix from the current camera. H0 takes its masked mean; the optional H1 carrier adds relative age and causal temporal attention before returning the same one-token interface. H1 remains an S0-pose trajectory ablation: it does not invent selected observations or make compact root moments a sufficient dynamic reconstruction state.

The CF+ H0 role is the source-protocol-matched counterfactual for S1. It requires the same strictly causal CF-GT carrier and data population, but the prediction graph consumes none of its numeric payload. Consequently any change confined to selected depth, depth-valid support, calibration, or selected-camera poses must leave both raw heads exactly unchanged. S1 instead uses canonical float32 backprojection and a fixed-width, density-weighted point-set residual. Its scene feature remains shared across candidate rows and target independent; candidate-relative point queries are deliberately deferred. Its final bias-free residual projection starts at zero, and dynamic scene rows traverse the same per-state linear path as static H0. Thus matched zero-residual S1 and H0 predictions are bitwise equal at initialization rather than merely close despite shape-dependent GEMM rounding. Neither CF+ role is deployable, and comparing CF0 with CF+ H0 does not identify an S1 representation gain.

1.1.1.2 Notes

Syntactic admission does not assert empirical support. Lightning owns which horizons receive targets, while a verified inference bundle owns the manifest-bound set of horizons that may be deployed.

1.1.1.3 Methods

Name	Description
validate_artifact_state	Validate non-learned architecture state against scorer configuration.
forward	Return mask-independent candidate predictions in stored order.

1.1.1.3.1 validate_artifact_state

vin.models.target_finite_horizon.TargetFiniteHorizonScorer.validate_artifact_state(
    require_publishable=False,
)

Validate non-learned architecture state against scorer configuration.

Learned weights may vary while the scorer configuration stays fixed, but CORAL edges and representatives are experiment identity: they determine supervision labels and convert ordinal mass back into the continuous units used by Bellman backup and policy ranking. This hook gives bundle owners one decoder-agnostic validation seam and leaves direct regression as the no-extra-state baseline.

1.1.1.3.2 forward

vin.models.target_finite_horizon.TargetFiniteHorizonScorer.forward(
    actor,
    *,
    requested_horizon=None,
)

Return mask-independent candidate predictions in stored order.

1.1.1.3.2.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched actor-visible chain with candidate support Tensor["B S N", bool], compact root EVL evidence, and—only for the named privileged S1 profile—the complete causal selected-depth prefix.	required
requested_horizon	Tensor | None	Optional Tensor["B S", int64] value query. Legacy None selects recorded remaining budget and admits 1 <= h <= b_t <= H_max. Continuing requires explicit 1 <= h <= H_max independent of recorded countdown and omits the budget feature. Padding is zero in both profiles.	None

1.1.1.3.2.2 Returns

Name	Type	Description
	QhScoreOutput	Candidate-aligned conditional Q and feasibility logits. Both are
	QhScoreOutput	finite on materialized realized rows and zero only on padding.
	QhScoreOutput	CORAL additionally returns threshold logits and its fixed support
	QhScoreOutput	in value_auxiliary for Lightning supervision and diagnostics;
	QhScoreOutput	policy backup and ranking still use only conditional_q.

1.1.2 TargetFiniteHorizonScorerConfig

vin.models.target_finite_horizon.TargetFiniteHorizonScorerConfig()

Configure the actor-only finite-horizon value scorer.

1.1.2.1 Attributes

Name	Description
hidden_dim	Shared candidate and state token width.
pose_encoder	R6D plus LFF encoder used for target, candidate, and history poses.
scene_channels	Ordered compact root-EVL fields pooled into the state token.
representation_semantics	Versioned scene-token meaning bound into scorer and artifact identity.
scene_encoder	Optional explicit scene carrier; None preserves legacy S0 identity.
history_encoder	H0/H1 representation of the strictly causal selected-pose prefix.
state_fusion	A0/A1 interaction over the identical candidate query and state tokens.
dropout	Training-only dropout in state fusion and the value decoder.
value_decoder	Terminal scalar-Q decoder over the shared candidate-state feature.
max_horizon	Largest admitted acquisition horizon; remaining budget is normalized by this value.
horizon_query_semantics	Legacy budget-bounded query or explicit continuing lookahead independent of replay length.
experiment_profile	Named source role admitted by the scorer.
target_type	Return the concrete scorer constructed by :meth:setup_target.