1 targets.observation_support

targets.observation_support

Causal observation support for actor-visible target allocation.

This module summarizes evidence that was already acquired at a decision root. It does not extract support, associate observations to targets, authenticate a producer, or persist a second manifest. Producers own surface identity, direction bins, visible masks, and projected boxes; this interface validates their declared causal and provenance bindings before a training allocator uses the evidence.

1.1 Classes

Name	Description
ObservationSupportDecision	Independently supplied decision identity checked against one prefix.
TargetObservation	One acquired view associated with an actor-visible target.
TargetSupportPrefix	Identity-bound acquired observations for one actor-visible target.
TargetSupportSummary	Separate exposure, directional, and deduplicated-surface evidence.

1.1.1 ObservationSupportDecision

targets.observation_support.ObservationSupportDecision(
    source_manifest_hash,
    split_manifest_hash,
    sample_key,
    root_id,
    cutoff_ns,
    source_split,
    collection_split,
    reference_pose_world_rig,
)

Independently supplied decision identity checked against one prefix.

Construct this value from the current admitted target/root context rather than by copying fields from TargetSupportPrefix. The caller that owns source-manifest admission remains responsible for checking these hash values against the current manifest DTO.

1.1.1.1 Attributes

Name	Description
source_manifest_hash	Immutable VIN source-store manifest hash.
split_manifest_hash	Hash binding the ordered source population and its source split.
sample_key	Immutable VIN source-sample identity.
root_id	Physical decision-root identity.
cutoff_ns	Inclusive last acquisition time visible to the decision.
source_split	VIN source split; the challenger admits training sources only.
collection_split	Collection/campaign split; the challenger admits training evidence only.
reference_pose_world_rig	Flattened 12-value world-from-rig pose defining the decision root.

1.1.2 TargetObservation

targets.observation_support.TargetObservation(
    frame_id,
    timestamp_ns,
    source_role,
    source,
    surface_ids=None,
    direction_bin=None,
    visible_mask_fraction=None,
    projected_obb_fraction=None,
)

One acquired view associated with an actor-visible target.

Each optional measurement has its own availability state. None means that modality was unavailable for the frame, while an empty surface tuple or a zero area is a measured empty result.

1.1.2.1 Attributes

Name	Description
frame_id	Stable sensor-frame identity used to deduplicate repeated records.
timestamp_ns	Acquisition timestamp in the same clock as the decision cutoff.
source_role	Acquired factual-prefix or selected-transition role.
source	Actor-observed channel; privileged GT or rendered depth is inadmissible.
surface_ids	Stable surface-element IDs; None is unavailable and () is known empty.
direction_bin	Producer-defined target-relative direction bin, when available.
visible_mask_fraction	Occlusion-aware visible mask area divided by image area, in [0, 1].
projected_obb_fraction	Clipped projected OBB area divided by image area, in [0, 1].

1.1.3 TargetSupportPrefix

targets.observation_support.TargetSupportPrefix(
    source_manifest_hash,
    split_manifest_hash,
    sample_key,
    root_id,
    observed_target_id,
    descriptor_hash,
    evidence_id,
    protocol_id,
    cutoff_ns,
    source_split,
    collection_split,
    reference_pose_world_rig,
    observations,
)

Identity-bound acquired observations for one actor-visible target.

The prefix carries no oracle association, reward, or hypothetical candidate render. Repeated identical frame records are accepted and summarized once; conflicting records under one frame identity fail closed.

1.1.3.1 Attributes

Name	Description
source_manifest_hash	Immutable VIN source-store manifest hash declared by the producer.
split_manifest_hash	Declared ordered source-population manifest hash.
sample_key	Immutable VIN source-sample identity.
root_id	Physical root whose acquired prefix produced this evidence.
observed_target_id	Actor-visible target identity; any GT association is an oracle-side join.
descriptor_hash	Hash of the actor-visible descriptor snapshot used at this root.
evidence_id	Producer receipt for the declared observation payload and extraction protocol.
protocol_id	Frozen support extraction, surface identity, association, and direction-bin contract.
cutoff_ns	Inclusive last acquisition time allowed in the prefix.
source_split	VIN source split declared for the prefix.
collection_split	Collection/campaign split declared for the prefix.
reference_pose_world_rig	Flattened 12-value world-from-rig pose defining the root frame.
observations	Acquired observations only, with independent measurement availability.

1.1.3.2 Methods

Name	Description
validate_decision	Require an exact independently supplied causal and provenance binding.
summarize	Reduce unique acquired frames without conflating support modalities.

1.1.3.2.1 validate_decision

targets.observation_support.TargetSupportPrefix.validate_decision(decision)

Require an exact independently supplied causal and provenance binding.

The comparison is intentionally exact: a support receipt cannot be replayed at another root, cutoff, source population, collection split, or reference pose. This method validates declared identities; the allocation owner must still compare the decision hashes and sample key with the current source-manifest DTO.

1.1.3.2.2 summarize

targets.observation_support.TargetSupportPrefix.summarize()

Reduce unique acquired frames without conflating support modalities.

Surface support is a set union, directional diversity is the number of distinct producer-defined bins, visible-mask exposure is a per-frame sum, and projected OBB support is a per-frame maximum. None of these is a full-object completeness estimate.

1.1.4 TargetSupportSummary

targets.observation_support.TargetSupportSummary(
    observed_frames,
    surface_frames,
    unique_surface_count,
    direction_frames,
    direction_bins,
    visible_mask_frames,
    visible_mask_exposure,
    projected_obb_frames,
    max_projected_obb_fraction,
)

Separate exposure, directional, and deduplicated-surface evidence.

1.1.4.1 Attributes

Name	Description
observed_frames	Number of distinct acquired frames, including unavailable modalities.
surface_frames	Frames with surface-ID measurements, including measured empty sets.
unique_surface_count	Union cardinality of surface IDs; None means the modality was unavailable.
direction_frames	Frames with an available target-relative direction bin.
direction_bins	Distinct observed direction bins; None means no directional measurement.
visible_mask_frames	Frames with visible-mask measurements, including measured zero area.
visible_mask_exposure	Sum of visible-mask fractions over distinct frames, not unique surface area.
projected_obb_frames	Frames with projected-OBB measurements, including measured zero area.
max_projected_obb_fraction	Largest measured projected OBB fraction, without an occlusion claim.