1 oracle.target_rri

oracle.target_rri

Target-aware Oracle RRI scoring over finite candidate tables.

This module scores valid candidate rows with target-specific point-mesh RRI and owns typed target-scoring invalidity outcomes. The current generation path samples a privileged GT target task upstream; this scorer uses its OBB as an oracle/evaluation crop. Missing targets, empty mesh crops, sparse current support, or unusable depth are expected invalidity cases and surface as typed TargetRriInvalidity outcomes.

Scene RRI may be emitted as a diagnostic from the same candidate point clouds, but it must not replace target RRI labels in thesis-core rollout stores.

1.1 Theory

Target-conditioned rollout scoring joins two intentionally separate contracts. Candidate generation receives a sanitized target descriptor; the scorer receives the full Oracle task to crop evaluation geometry and compute target-RRI labels. Candidate scores therefore measure improvement for the selected task without exposing GT identity or crop state through the descriptor contract.

1.2 Attributes

Name	Description
SCENE_CROP_POLICY_SNIPPET_EXTENT_V1	Scene-RRI crop policy matching the existing snippet occupancy-extent scorer.
TARGET_CROP_POLICY_GT_OBB_ORIENTED_ANY_VERTEX_V1	Target crop policy: keep mesh faces with any vertex inside the matched oriented GT OBB.
TARGET_POINT_CROP_POLICY_GT_OBB_MEMBERSHIP_V1	Successor crop policy: keep points whose centres lie inside the matched oriented GT OBB.

1.3 Classes

Name	Description
CandidateRenderCropConfig	Conservative scoring-only crop; selected history remains full scene.
TargetEndpointMeasurement	Independent root/final target measurement from prepared raw geometry.
TargetEndpointMetricValues	One finite point–mesh endpoint evaluation retained for repeatability audit.
TargetRriInvalidity	Expected target-scoring failure with a stable semantic reason.
TargetRriScorer	Evaluate valid candidates with target-cropped oracle RRI.
TargetRriScorerConfig	Config-as-factory wrapper for target-cropped oracle-RRI rollout scoring.
TargetScoringCapture	Actual scoring tensors borrowed by a bounded validation observer.
TargetSuccessorSupportError	A valid candidate table contains an unmeasurable prepared successor.

1.3.1 CandidateRenderCropConfig

oracle.target_rri.CandidateRenderCropConfig()

Conservative scoring-only crop; selected history remains full scene.

The scorer derives fusion support in addition to its unchanged scoring margin. Extra halo affects rendering only, never metric geometry.

1.3.1.1 Attributes

Name	Description
extra_halo_m	Additional rendering halo in world metres, beyond canonical fusion support.
face_selection_mode	Operational face screening mode; defaults preserve historical serialization.
face_chunk_size	Maximum screening face rows per batch in batched mode.

1.3.2 TargetEndpointMeasurement

oracle.target_rri.TargetEndpointMeasurement(
    root_points_world,
    final_points_world,
    root_error_m2,
    final_error_m2,
    endpoint_gain,
    root_accuracy_m2,
    root_completeness_m2,
    final_accuracy_m2,
    final_completeness_m2,
    preparation,
    target_mesh_vertices_sha256,
    target_mesh_faces_sha256,
    target_extent_sha256,
    target_mesh_vertex_count,
    target_mesh_face_count,
    target_extent_world,
    repeats,
    repeat_max_abs_delta,
    noop,
    noop_error_delta_m2,
    metric_name='target_point_mesh_endpoint_gain_v1',
    epsilon=DEFAULT_RRI_EPSILON,
)

Independent root/final target measurement from prepared raw geometry.

The two point clouds are the complete prepared states supplied to the point–mesh metric. They are retained so a receipt can preserve the exact measurement inputs instead of treating accumulated one-step gains as an independent endpoint observation.

1.3.2.1 Attributes

Name	Description
root_points_world	Prepared root target cloud as Tensor["P_0 3"] in world metres.
final_points_world	Prepared final target cloud as Tensor["P_H 3"] in world metres.
root_error_m2	Root bidirectional point–mesh error in square metres.
final_error_m2	Final bidirectional point–mesh error in square metres.
endpoint_gain	Root-normalized endpoint reduction (d_0-d_H)/(d_0+epsilon).
root_accuracy_m2	Root point-to-mesh component in square metres.
root_completeness_m2	Root mesh-to-point component in square metres.
final_accuracy_m2	Final point-to-mesh component in square metres.
final_completeness_m2	Final mesh-to-point component in square metres.
preparation	Exact ordered reconstruction preparation used for both endpoints.
target_mesh_vertices_sha256	Content hash of the exact cropped target-mesh vertices passed to the metric.
target_mesh_faces_sha256	Content hash of the exact cropped target-mesh faces passed to the metric.
target_extent_sha256	Content hash of the exact target extent passed to the metric.
target_mesh_vertex_count	Number of cropped target-mesh vertices bound by the receipt.
target_mesh_face_count	Number of cropped target-mesh faces bound by the receipt.
target_extent_world	Exact metric extent values in world metres, conventionally six AABB bounds.
repeats	Three identical root/final metric evaluations in execution order.
repeat_max_abs_delta	Maximum absolute scalar delta from repeat zero across every retained metric.
noop	One independently evaluated root/root no-op measurement.
noop_error_delta_m2	Signed no-op final-minus-root bidirectional error in square metres.
metric_name	Stable semantic identity of the endpoint metric.
epsilon	Denominator guard used by the endpoint gain.

1.3.3 TargetEndpointMetricValues

oracle.target_rri.TargetEndpointMetricValues(
    root_error_m2,
    final_error_m2,
    endpoint_gain,
    root_accuracy_m2,
    root_completeness_m2,
    final_accuracy_m2,
    final_completeness_m2,
)

One finite point–mesh endpoint evaluation retained for repeatability audit.

Squared-error components are nonnegative; root-normalized gain may be negative when adding observations worsens the measured reconstruction.

1.3.4 TargetRriInvalidity

oracle.target_rri.TargetRriInvalidity(reason, message)

Expected target-scoring failure with a stable semantic reason.

1.3.4.1 Attributes

Name	Description
reason	Stable reason code suitable for hard-invalid masks and diagnostics.
message	Human-readable failure context for logs and inspection surfaces.

1.3.5 TargetRriScorer

oracle.target_rri.TargetRriScorer(config, *, sample, target_sample, target_task)

Evaluate valid candidates with target-cropped oracle RRI.

The scorer renders candidate depth, backprojects world-frame point clouds, crops current and candidate points to the matched target OBB, crops the mesh with the configured policy, and returns target-RRI labels plus audit metrics. Invalid target crops abort the target row rather than producing low labels. If any candidate has no prepared successor support, the scorer rejects the aligned table as measurement-invalid instead of filtering candidate rows.

1.3.5.1 Attributes

Name	Description
invalidity	Return evidence invalidity known before candidate scoring.

1.3.5.2 Methods

Name	Description
measure_endpoint_pair	Measure root and final states once without rendering new candidates.
score_candidate_depths	Score a complete hard-valid table from one already captured raster.
acquire_selected_observation	Acquire full-scene selected depth and raw world points at scoring resolution.

1.3.5.2.1 measure_endpoint_pair

oracle.target_rri.TargetRriScorer.measure_endpoint_pair(root_state, final_state)

Measure root and final states once without rendering new candidates.

Both endpoints pass independently through the same canonical fusion, target crop, and metric preparation used for candidate labels. This is deliberately distinct from reducing stored one-step gains. Every primary, repeated, and no-op scalar must pass numerical admission; unmeasurable evidence returns a typed invalidity instead of a label.

1.3.5.2.2 score_candidate_depths

oracle.target_rri.TargetRriScorer.score_candidate_depths(
    candidates,
    state,
    depths,
    *,
    backprojection_stride,
)

Score a complete hard-valid table from one already captured raster.

This measurement-only seam isolates point sampling from rasterization: callers may pass the same :class:CandidateDepths object with several positive strides. Candidate shell indices, physical world-camera poses, reference pose, and raster camera dimensions are validated before any measurement. Rendering cost is deliberately absent; a panel runner must retain it once as shared acquisition cost.

1.3.5.2.2.1 Parameters

Name	Type	Description	Default
candidates	CandidateSamplingResult	Candidate table that originally produced depths.	required
state	OracleRriState	Fixed factual state and prepared root evidence.	required
depths	CandidateDepths	Complete rendered hard-valid candidate table.	required
backprojection_stride	int	Positive pixel sampling stride. Booleans are rejected rather than coerced to integers.	required

1.3.5.2.2.2 Returns

Name	Type	Description
	OracleCandidateEvaluation | TargetRriInvalidity	Canonical candidate evaluation or the scorer’s typed invalidity.

1.3.5.2.3 acquire_selected_observation

oracle.target_rri.TargetRriScorer.acquire_selected_observation(
    candidates,
    compact_index,
)

Acquire full-scene selected depth and raw world points at scoring resolution.

Original mesh, camera calibration and pixel stride define causal history; neither cropped background nor later high-resolution retention substitutes for these observations. Compact-row and shell identity are checked.

1.3.6 TargetRriScorerConfig

oracle.target_rri.TargetRriScorerConfig()

Config-as-factory wrapper for target-cropped oracle-RRI rollout scoring.

1.3.6.1 Attributes

Name	Description
target_type	Return the target-aware Oracle scorer constructed by this config.
depth	Depth renderer used once per candidate table before target/scene scoring.
oracle	Point-mesh oracle metric configuration shared by target and scene RRI.
candidate_render_crop	Opt-in crop; None preserves full rendering and historical serialization.
backprojection_stride	Pixel stride for backprojecting rendered candidate depths.
target_crop_margin_m	Optional symmetric margin applied in GT-OBB local coordinates.
min_current_target_points	Minimum current observed/support points inside the target crop.
include_scene_rri	Whether to compute diagnostic scene RRI from the same point-cloud batch.
eval_point_cloud_source	Oracle current/root point-cloud source used for target and scene labels.
eval_camera_label	Camera stream used for ASE-depth root evaluation points.
eval_depth_far_m	Maximum ASE root depth to retain; defaults to the renderer zfar.
eval_fusion_voxel_size_m	Voxel size used to canonical-fuse root and selected-history eval points.
eval_fusion_max_points	Maximum retained current-eval points after canonical fusion.
target_eval_max_points	Maximum retained oracle/eval points after target-local crop fusion.
reward_mode	Candidate score used for rollout selection.
target_crop_policy	Versioned reference-mesh crop stored as lineage; exact v2 requires zero margin.
scene_crop_policy	Diagnostic scene-RRI crop policy matching the scene-level scorer.
verbosity	Console verbosity.
is_debug	Enable debug logging in scorer dependencies.
log_timing	Emit per-call timing diagnostics for rollout evidence generation.
audit_candidate_reconstruction_shell_indices	Up to eight full-shell rows whose prepared target successors are retained.

1.3.7 TargetScoringCapture

oracle.target_rri.TargetScoringCapture(
    candidates,
    depths,
    evaluation,
    accumulated_points_world,
    prepared_current_points_world,
    prepared_successor_points_world,
    prepared_successor_lengths,
    step_index,
    root_pose_world,
    root_time_ns,
    root_frame_index,
    root_trajectory_index,
    original_face_count,
    rendered_original_face_indices,
    effective_render_halo_m,
    original_vertex_count,
    rendered_vertex_count,
    timings,
)

Actual scoring tensors borrowed by a bounded validation observer.

The observer must snapshot retained payloads without changing labels, candidates or random state. Absent observers allocate no capture object.

1.3.7.1 Attributes

Name	Description
candidates	Original candidate object and complete shell/compact valid mapping.
depths	Actual calibrated scoring raster; enabled crops can truncate background.
evaluation	Complete measured candidate table, before replay selection.
accumulated_points_world	Actual prior selected global evidence Tensor["P_h 3", float32], world metres.
prepared_current_points_world	Actual metric-prepared current target Tensor["P 3", float32], world metres.
prepared_successor_points_world	Actual padded target successors Tensor["V P 3", float32], world metres.
prepared_successor_lengths	Valid successor lengths Tensor["V", int64], compact-row aligned.
step_index	Actual replay step index; external raster scoring uses zero.
root_pose_world	Actual physical replay root pose, independent of the sample’s reference rig.
root_time_ns	Actual root timestamp, or explicitly unavailable.
root_frame_index	Actual acquired root frame index, or explicitly unavailable.
root_trajectory_index	Actual root trajectory row, or explicitly unavailable.
original_face_count	Number of faces in the original full scene, before render-only filtering.
rendered_original_face_indices	Retained source face rows Tensor["F_crop", int64]; None denotes full scene.
effective_render_halo_m	Total render crop margin in metres, including score margin, fusion guard and extra halo.
original_vertex_count	Original full scene vertex count for rendering cost interpretation.
rendered_vertex_count	Actual render-mesh vertex count after optional face filtering/remapping.
timings	Measured production durations in seconds, excluding observer work.

1.3.8 TargetSuccessorSupportError

oracle.target_rri.TargetSuccessorSupportError(row_indices)

A valid candidate table contains an unmeasurable prepared successor.

The complete aligned table is rejected. Campaign schedulers may catch this exact exception to record an expected measurement-support rejection while continuing with later roots; unrelated ValueError failures remain implementation errors.

1.4 Functions

Name	Description
current_root_target_support_counts	Count prepared current-root crop points for each GT task before selection.

1.4.1 current_root_target_support_counts

oracle.target_rri.current_root_target_support_counts(
    sample,
    tasks,
    config,
    *,
    root_pose_world,
    root_time_ns,
    root_trajectory_index,
    root_frame_index,
)

Count prepared current-root crop points for each GT task before selection.

The shared scorer engine builds the fixed observed-prefix root once and applies exactly the same global fusion and target crop as candidate scoring. No mesh or candidate depth is rendered. A zero count is an unavailable label, never an observed zero RRI value.