vibespatial.overlay.strategies¶

Overlay workload-family planning and strategy detection.

The public overlay surface and the GPU-owned overlay executor both need the same answer to the same question: what is the true constructive workload we are about to run? This module turns row counts, candidate-pair evidence, and surface semantics into one immutable planning object so execution-family selection happens at the public boundary or chunk boundary instead of drifting into ad hoc mid-pipeline branches.

Uses the shared WorkloadShape enum from vibespatial.runtime.crossover for broadcast detection (nsf.5), falling back to overlay-specific detection for broadcast_left (which the shared enum intentionally omits).

Classes¶

`OverlayExecutionFamily`	Enum where members are also (and must be) strings
`OverlayTopologyClass`	Enum where members are also (and must be) strings
`OverlayResultShape`	Enum where members are also (and must be) strings
`OverlayStrategy`	Immutable constructive planning object for overlay execution.

Functions¶

`plan_overlay_operation`(→ OverlayStrategy)	Plan the constructive workload family for an overlay operation.
`select_overlay_strategy`(→ OverlayStrategy)	Detect workload shape and select the overlay execution family.

Module Contents¶

class vibespatial.overlay.strategies.OverlayExecutionFamily¶

Enum where members are also (and must be) strings

CLIP_REWRITE = 'clip_rewrite'¶

BROADCAST_RIGHT_INTERSECTION = 'broadcast_right_intersection'¶

BROADCAST_RIGHT_DIFFERENCE = 'broadcast_right_difference'¶

COVERAGE_UNION = 'coverage_union'¶

GROUPED_UNION = 'grouped_union'¶

GENERIC_RECONSTRUCTION = 'generic_reconstruction'¶

class vibespatial.overlay.strategies.OverlayTopologyClass¶

Enum where members are also (and must be) strings

MASK_CLIP = 'mask_clip'¶

BROADCAST_MASK = 'broadcast_mask'¶

COVERAGE = 'coverage'¶

GROUPED_SET = 'grouped_set'¶

RECONSTRUCTION = 'reconstruction'¶

class vibespatial.overlay.strategies.OverlayResultShape¶

Enum where members are also (and must be) strings

LEFT_ROWS = 'left_rows'¶

PAIRWISE_ROWS = 'pairwise_rows'¶

GROUPED_LEFT_ROWS = 'grouped_left_rows'¶

SURFACE_PARTS = 'surface_parts'¶

class vibespatial.overlay.strategies.OverlayStrategy¶

Immutable constructive planning object for overlay execution.

name: str¶

many_side: str¶

reason: str¶

workload_shape: vibespatial.runtime.crossover.WorkloadShape | None = None¶

operation: str = 'intersection'¶

topology_class: OverlayTopologyClass¶

semantics_flags: frozenset[str]¶

result_shape: OverlayResultShape¶

execution_family: OverlayExecutionFamily¶

fusion_plan: vibespatial.runtime.fusion.FusionPlan | None = None¶

property workload_shape_label: str¶

property semantics_label: str¶

property fusion_stage_labels: str¶

telemetry_detail(*, left_rows: int, right_rows: int, candidate_pair_count: int) → str¶

vibespatial.overlay.strategies.plan_overlay_operation(*, left_rows: int, right_rows: int, how: str, candidate_pair_count: int = 0, clip_rewrite: bool = False, keep_geom_type: bool | None = None, prefer_exact_polygon_gpu: bool = False, preserve_lower_dim_results: bool = False) → OverlayStrategy¶: Plan the constructive workload family for an overlay operation.

vibespatial.overlay.strategies.select_overlay_strategy(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, how: str, *, candidate_pair_count: int = 0) → OverlayStrategy¶: Detect workload shape and select the overlay execution family.