vibespatial.runtime.provenance¶

Provenance tagging and rewrite system for spatial operation optimization.

Tags intermediate GeometryArray results with metadata about the operation that created them, enabling downstream operations to recognize patterns and substitute cheaper equivalents automatically.

See ADR-0039 for the design rationale.

Attributes¶

`REWRITE_REGISTRY`
`PROVENANCE_REWRITES_ENV_VAR`
`R1_BUFFER_INTERSECTS`
`R5_BUFFER_ZERO`
`R6_BUFFER_CHAIN`
`R2_SJOIN_BUFFER_INTERSECTS`
`R7_SIMPLIFY_ZERO`

Classes¶

`ProvenanceTag`	Metadata about how a GeometryArray was created.
`RewriteRule`	Declarative rewrite rule specification.
`RewriteEvent`	Record of a provenance-based rewrite that fired.

Functions¶

`register_rewrite`(→ None)	Add a rewrite rule to the registry.
`get_rewrite_candidates`(→ tuple[RewriteRule, Ellipsis])	Look up candidate rewrite rules for a (producer, consumer) pair.
`record_rewrite_event`(→ RewriteEvent)
`get_rewrite_events`(→ list[RewriteEvent])
`clear_rewrite_events`(→ None)
`set_provenance_rewrites`(→ None)	Override provenance rewrites. Pass None to clear (use env var or default).
`provenance_rewrites_enabled`(→ bool)	Check if provenance rewrites are enabled. Default: True.
`infer_geom_types`(→ frozenset[str] \| None)	Infer geometry family names from a GeometryArray.
`make_buffer_tag`(→ ProvenanceTag)	Create a provenance tag for a buffer operation.
`attempt_rewrite_buffer_intersects`(→ numpy.ndarray \| None)	Attempt R1: buffer(r).intersects(Y) -> dwithin(Y, r).
`attempt_provenance_rewrite`(→ numpy.ndarray \| None)	Check if the left operand's provenance enables a cheaper rewrite.

Module Contents¶

class vibespatial.runtime.provenance.ProvenanceTag¶

Metadata about how a GeometryArray was created.

operation: str¶

params: tuple[tuple[str, Any], Ellipsis]¶

source_geom_types: frozenset[str] | None¶

source_array: Any | None = None¶

reason: str = ''¶

get_param(key: str, default: Any = None) → Any¶

class vibespatial.runtime.provenance.RewriteRule¶

Declarative rewrite rule specification.

name: str¶

input_pattern: str¶

consumer_operation: str¶

preconditions: tuple[str, Ellipsis]¶

reason: str¶

class vibespatial.runtime.provenance.RewriteEvent¶

Record of a provenance-based rewrite that fired.

rule_name: str¶

surface: str¶

original_operation: str¶

rewritten_operation: str¶

reason: str¶

detail: str = ''¶

elapsed_seconds: float = 0.0¶

to_dict() → dict[str, Any]¶

vibespatial.runtime.provenance.REWRITE_REGISTRY: dict[tuple[str, str], list[RewriteRule]]¶

vibespatial.runtime.provenance.register_rewrite(rule: RewriteRule) → None¶: Add a rewrite rule to the registry.

vibespatial.runtime.provenance.get_rewrite_candidates(tag_operation: str, consumer_operation: str) → tuple[RewriteRule, Ellipsis]¶: Look up candidate rewrite rules for a (producer, consumer) pair.

vibespatial.runtime.provenance.record_rewrite_event(*, rule_name: str, surface: str, original_operation: str, rewritten_operation: str, reason: str, detail: str = '', elapsed_seconds: float = 0.0) → RewriteEvent¶

vibespatial.runtime.provenance.get_rewrite_events(*, clear: bool = False) → list[RewriteEvent]¶

vibespatial.runtime.provenance.clear_rewrite_events() → None¶

vibespatial.runtime.provenance.PROVENANCE_REWRITES_ENV_VAR = 'VIBESPATIAL_PROVENANCE_REWRITES'¶

vibespatial.runtime.provenance.set_provenance_rewrites(enabled: bool | None) → None¶: Override provenance rewrites. Pass None to clear (use env var or default).

vibespatial.runtime.provenance.provenance_rewrites_enabled() → bool¶: Check if provenance rewrites are enabled. Default: True.

vibespatial.runtime.provenance.infer_geom_types(ga: vibespatial.api.geometry_array.GeometryArray) → frozenset[str] | None¶

Infer geometry family names from a GeometryArray.

Uses OwnedGeometryArray tags (zero-cost) when available, otherwise falls back to shapely.get_type_id.

vibespatial.runtime.provenance.make_buffer_tag(source: vibespatial.api.geometry_array.GeometryArray, distance: float | int, cap_style: str, join_style: str, single_sided: bool, quad_segs: int) → ProvenanceTag¶: Create a provenance tag for a buffer operation.

vibespatial.runtime.provenance.R1_BUFFER_INTERSECTS¶

vibespatial.runtime.provenance.R5_BUFFER_ZERO¶

vibespatial.runtime.provenance.R6_BUFFER_CHAIN¶

vibespatial.runtime.provenance.R2_SJOIN_BUFFER_INTERSECTS¶

vibespatial.runtime.provenance.R7_SIMPLIFY_ZERO¶

vibespatial.runtime.provenance.attempt_rewrite_buffer_intersects(tag: ProvenanceTag, left: vibespatial.api.geometry_array.GeometryArray, right: Any, **kwargs: Any) → numpy.ndarray | None¶: Attempt R1: buffer(r).intersects(Y) -> dwithin(Y, r).

vibespatial.runtime.provenance.attempt_provenance_rewrite(op: str, left: vibespatial.api.geometry_array.GeometryArray, right: Any, **kwargs: Any) → numpy.ndarray | None¶

Check if the left operand’s provenance enables a cheaper rewrite.

Returns the rewritten result array, or None if no rewrite applies.