chalkruntime 3.43.74__tar.gz → 3.43.76__tar.gz

{chalkruntime-3.43.74 → chalkruntime-3.43.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chalkruntime
-Version: 3.43.74
+Version: 3.43.76
 Summary: Runtime support library for Chalk AI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{chalkruntime-3.43.74 → chalkruntime-3.43.76}/chalkruntime/invoker/vectorized_hasmany_sampler.py

@@ -689,6 +689,12 @@ class PolarsVectorizedHasManySampler(VectorizedHasManySampler):
         hm_lf = hm_df
         hm_mapping_lf = mapping_table
 
+        # See `HAS_MANY_INPUT_TS_COL_NAME`: present iff each has-many row is a version for one input time,
+        # in which case an input row only matches the rows computed for its own `__ts__`.
+        join_on_input_time = HAS_MANY_INPUT_TS_COL_NAME in hm_lf.columns
+        if join_on_input_time and TS_COL_NAME not in resolver_inputs_lf.columns:
+            raise ValueError(f"The resolver inputs must have a '{TS_COL_NAME}' column to match has-many data on it")
+
         # If we do not have the feature time column, append it with nulls
         if foreign_ts_feature.fqn not in hm_lf.columns:
             hm_lf = hm_lf.with_columns(pl.lit(None, pl.Datetime("us", "UTC")).alias(foreign_ts_feature.fqn))
@@ -703,6 +709,9 @@ class PolarsVectorizedHasManySampler(VectorizedHasManySampler):
             unique_on = [foreign_pkey_feature.fqn, foreign_ts_feature.fqn]
             if not allow_planner_postponed_has_many_sampling_planner_option:
                 unique_on.append(TS_COL_NAME)
+            if join_on_input_time:
+                # Versions computed for different input times are distinct rows, not duplicates.
+                unique_on.append(HAS_MANY_INPUT_TS_COL_NAME)
             # Add __index__ to prevent cross-transaction deduplication in bulk queries
             # This ensures that duplicate GL codes across different transactions in a bulk query
             # are treated as distinct results, not as duplicates to be removed
@@ -726,6 +735,11 @@ class PolarsVectorizedHasManySampler(VectorizedHasManySampler):
             over = [pl.col(foreign_pkey_feature.fqn)]
             if INDEX_COL_NAME in hm_lf.columns:
                 over.append(pl.col(INDEX_COL_NAME))
+            if join_on_input_time:
+                # A row is replaced only by a later version computed for the same input time; the versions for
+                # other input times are separate histories and would otherwise mark this one as replaced at its
+                # own feature time.
+                over.append(pl.col(HAS_MANY_INPUT_TS_COL_NAME))
             hm_lf = hm_lf.with_columns(
                 [
                     pl.col(foreign_ts_feature.fqn).alias(OBSERVED_AT_FEATURE_COL_NAME),
@@ -788,6 +802,9 @@ class PolarsVectorizedHasManySampler(VectorizedHasManySampler):
             for f in filters_from_feature
         ]
 
+        if join_on_input_time:
+            left_join_cols = [*left_join_cols, TS_COL_NAME]
+            right_join_cols = [*right_join_cols, HAS_MANY_INPUT_TS_COL_NAME]
         # Rename the left join column here since all the left table's column names had that prefix added.
         left_join_cols = [RESOLVER_INPUT_PREFIX + left_join_col for left_join_col in left_join_cols]
 
@@ -1472,6 +1489,8 @@ class PyArrowVectorizedHasManySampler(VectorizedHasManySampler):
             table_has_struct_or_list(resolver_inputs_table)
             or table_has_struct_or_list(has_many_table[0])
             or has_many_feature.underlying.get_nearest_neighbor_join_info()
+            # This sampler does not match per-input-time has-many rows on the input time.
+            or HAS_MANY_INPUT_TS_COL_NAME in has_many_table[0].column_names
         )
 
 

chalkruntime-3.43.76/chalkruntime/sql_rewriter/filter_injection_site.py

@@ -0,0 +1,167 @@
+"""Support for the ``chalk_filter_injection_site`` marker comment.
+
+By default, when Chalk pushes a filter into a ``.chalk.sql`` resolver, it wraps the entire query
+in ``SELECT * FROM (<original query>) tmp WHERE <filter>``. That outer ``WHERE`` is correct, but
+some engines (notably Redshift) will not always push such an outer predicate down through CTEs,
+joins, aggregations, or window functions to the underlying table scan. A resolver author can place
+a marker comment to tell us exactly where the filter should be injected instead::
+
+    WITH foo AS (SELECT * FROM bar /* chalk_filter_injection_site */)
+    SELECT * FROM foo
+
+The marker may optionally name the (output) columns that should be filtered at that site. This is
+how filters get routed when several CTEs each need a different filter::
+
+    WITH
+      users    AS (SELECT * FROM users_t    /* chalk_filter_injection_site[user_id] */),
+      accounts AS (SELECT * FROM accounts_t /* chalk_filter_injection_site[account_id] */)
+    SELECT u.user_id, a.account_id, ...
+    FROM users u JOIN accounts a ON u.account_id = a.account_id
+
+The named columns are the resolver's *output* column names (the keys of the resolver field
+mapping), and they must be referenceable from the marked ``SELECT``'s ``WHERE`` clause. The common
+``SELECT *`` pass-through case satisfies this; a renaming projection (``SELECT x AS user_id``) does
+not, because standard SQL evaluates ``WHERE`` before ``SELECT`` aliases.
+
+The marker only changes *where* a filter lands. The outer wrap that each rewriter already produces
+is preserved as a correctness backstop, so a mis-placed or unsatisfiable marker never changes query
+results -- at worst the in-place injection is skipped and behavior falls back to the outer wrap.
+
+One placement caveat: the sqlglot *parser* drops comments in some positions (notably an own-line
+marker between the WHERE predicate and QUALIFY), so the AST-based site finding above cannot see
+them and this module's python rewriters keep the outer wrap. The native execution path locates the
+marker textually instead (libchalk's ``FilterInjection.for_sql_resolver``), so it honors those placements.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from typing import Iterable, Optional
+
+import sqlglot
+import sqlglot.expressions as sqlglot_expressions
+from chalk.utils.log_with_context import get_logger
+
+_logger = get_logger(__name__)
+
+INJECTION_SITE_MARKER = "chalk_filter_injection_site"
+
+# The trailing ``\b`` keeps ``chalk_filter_injection_site_other`` from matching the marker. The
+# optional bracket group captures a comma-separated list of output column names. We ``search``
+# (rather than fullmatch) so the marker is recognized even when it shares a comment with other text.
+_MARKER_RE = re.compile(INJECTION_SITE_MARKER + r"\b\s*(?:\[(?P<cols>[^\]]*)\])?", re.IGNORECASE)
+
+
+@dataclasses.dataclass(frozen=True)
+class FilterInjectionSite:
+    """A ``SELECT`` carrying a ``chalk_filter_injection_site`` comment, plus the optional set of
+    output columns the author scoped that site to."""
+
+    select: sqlglot_expressions.Select
+    columns: Optional[frozenset[str]]
+    """Output columns this site accepts. ``None`` means the site is unqualified and accepts every
+    filterable column; an empty set means the site was explicitly scoped to no columns."""
+
+    def accepts(self, column_name: str) -> bool:
+        return self.columns is None or column_name in self.columns
+
+    def inject(self, condition: sqlglot_expressions.Condition | str, *, dialect: str | None) -> None:
+        """AND ``condition`` into this site's ``WHERE`` clause, mutating the parsed tree in place.
+
+        ``copy=False`` is required: the surrounding query (which the rewriter subsequently wraps)
+        holds a reference to this same ``Select`` node, so the injection must mutate it rather than
+        return a fresh copy.
+        """
+        self.select.where(condition, dialect=dialect, copy=False)
+
+
+def _parse_marker(comment: str) -> tuple[bool, Optional[frozenset[str]]]:
+    """Return ``(is_marker, columns)`` for a single comment string.
+
+    ``columns`` is ``None`` for an unqualified marker and a (possibly empty) frozenset of output
+    column names for a ``[...]``-qualified marker.
+    """
+    match = _MARKER_RE.search(comment)
+    if match is None:
+        return False, None
+    cols_group = match.group("cols")
+    if cols_group is None:
+        return True, None
+    columns = frozenset(stripped for raw in cols_group.split(",") if (stripped := raw.strip().strip("\"'")))
+    return True, columns
+
+
+def _iter_nodes(expression: sqlglot.Expression) -> Iterable[sqlglot.Expression]:
+    # ``Expression.walk`` yields ``(node, parent, key)`` tuples on the pinned sqlglot (19.8.3) but
+    # yields bare nodes on newer releases; tolerate both so this keeps working across upgrades.
+    for item in expression.walk():
+        yield item[0] if isinstance(item, tuple) else item
+
+
+def find_filter_injection_sites(expression: sqlglot.Expression) -> list[FilterInjectionSite]:
+    """Find every ``chalk_filter_injection_site`` marker in ``expression``.
+
+    Multiple markers that resolve to the same ``SELECT`` are merged into a single site (their column
+    scopes are unioned; an unqualified marker widens the merged site to accept all columns) so a
+    given condition is never injected into the same ``SELECT`` twice.
+    """
+    by_select: dict[int, FilterInjectionSite] = {}
+    order: list[int] = []
+    for node in _iter_nodes(expression):
+        comments = node.comments
+        if not comments:
+            continue
+        for comment in comments:
+            is_marker, columns = _parse_marker(comment)
+            if not is_marker:
+                continue
+            select = (
+                node if isinstance(node, sqlglot_expressions.Select) else node.find_ancestor(sqlglot_expressions.Select)
+            )
+            if select is None:
+                _logger.warning(
+                    "Ignoring a '%s' marker that is not contained within a SELECT statement.",
+                    INJECTION_SITE_MARKER,
+                )
+                continue
+            key = id(select)
+            if key not in by_select:
+                by_select[key] = FilterInjectionSite(select=select, columns=columns)
+                order.append(key)
+            else:
+                existing = by_select[key]
+                if existing.columns is None or columns is None:
+                    merged: Optional[frozenset[str]] = None
+                else:
+                    merged = existing.columns | columns
+                by_select[key] = FilterInjectionSite(select=select, columns=merged)
+    return [by_select[key] for key in order]
+
+
+def inject_at_accepting_sites(
+    sites: list[FilterInjectionSite],
+    column_name: str,
+    condition: sqlglot_expressions.Condition | str,
+    *,
+    dialect: str | None,
+) -> int:
+    """Inject ``condition`` into every site that accepts ``column_name``; return the count injected.
+
+    A sqlglot condition is copied for each site so the same node is never shared across two places in
+    the tree (raw ``WHERE`` strings are re-parsed by ``Select.where`` and so need no copy).
+    """
+    injected = 0
+    for site in sites:
+        if not site.accepts(column_name):
+            continue
+        to_inject = condition.copy() if isinstance(condition, sqlglot_expressions.Expression) else condition
+        site.inject(to_inject, dialect=dialect)
+        injected += 1
+    return injected
+
+
+def is_noop_condition(condition: sqlglot.Expression) -> bool:
+    """Whether ``condition`` is a literal ``TRUE`` (what the filter converters emit when nothing can
+    be pushed down). Injecting it would only add ``WHERE TRUE`` noise, so callers skip it."""
+    return isinstance(condition, sqlglot_expressions.Boolean) and condition.this is True

{chalkruntime-3.43.74 → chalkruntime-3.43.76}/chalkruntime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chalkruntime
-Version: 3.43.74
+Version: 3.43.76
 Summary: Runtime support library for Chalk AI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{chalkruntime-3.43.74 → chalkruntime-3.43.76}/pyproject.toml

@@ -45,7 +45,7 @@ name = "chalkruntime"
 description = "Runtime support library for Chalk AI"
 readme = "README.md"
 requires-python = ">=3.11"
-version = "3.43.74"
+version = "3.43.76"
 
 
 [tool.deptry]

chalkruntime-3.43.74/chalkruntime/sql_rewriter/filter_injection_site.py

@@ -1,382 +0,0 @@
-"""Support for the ``chalk_filter_injection_site`` marker comment.
-
-By default, when Chalk pushes a filter into a ``.chalk.sql`` resolver, it wraps the entire query
-in ``SELECT * FROM (<original query>) tmp WHERE <filter>``. That outer ``WHERE`` is correct, but
-some engines (notably Redshift) will not always push such an outer predicate down through CTEs,
-joins, aggregations, or window functions to the underlying table scan. A resolver author can place
-a marker comment to tell us exactly where the filter should be injected instead::
-
-    WITH foo AS (SELECT * FROM bar /* chalk_filter_injection_site */)
-    SELECT * FROM foo
-
-The marker may optionally name the (output) columns that should be filtered at that site. This is
-how filters get routed when several CTEs each need a different filter::
-
-    WITH
-      users    AS (SELECT * FROM users_t    /* chalk_filter_injection_site[user_id] */),
-      accounts AS (SELECT * FROM accounts_t /* chalk_filter_injection_site[account_id] */)
-    SELECT u.user_id, a.account_id, ...
-    FROM users u JOIN accounts a ON u.account_id = a.account_id
-
-The named columns are the resolver's *output* column names (the keys of the resolver field
-mapping), and they must be referenceable from the marked ``SELECT``'s ``WHERE`` clause. The common
-``SELECT *`` pass-through case satisfies this; a renaming projection (``SELECT x AS user_id``) does
-not, because standard SQL evaluates ``WHERE`` before ``SELECT`` aliases.
-
-The marker only changes *where* a filter lands. The outer wrap that each rewriter already produces
-is preserved as a correctness backstop, so a mis-placed or unsatisfiable marker never changes query
-results -- at worst the in-place injection is skipped and behavior falls back to the outer wrap.
-
-One placement caveat: the sqlglot *parser* drops comments in some positions (notably an own-line
-marker between the WHERE predicate and QUALIFY), so the AST-based site finding above cannot see
-them and this module's python rewriters keep the outer wrap. ``compute_native_injection_site``
-below locates the marker textually instead, so the native execution path honors those placements.
-"""
-
-from __future__ import annotations
-
-import dataclasses
-import re
-from typing import Iterable, Optional
-
-import sqlglot
-import sqlglot.expressions as sqlglot_expressions
-from chalk.utils.log_with_context import get_logger
-
-from chalkruntime.sql_rewriter.sqlglot_parsing import sqlglot_dialect_object
-
-_logger = get_logger(__name__)
-
-INJECTION_SITE_MARKER = "chalk_filter_injection_site"
-
-# The trailing ``\b`` keeps ``chalk_filter_injection_site_other`` from matching the marker. The
-# optional bracket group captures a comma-separated list of output column names. We ``search``
-# (rather than fullmatch) so the marker is recognized even when it shares a comment with other text.
-_MARKER_RE = re.compile(INJECTION_SITE_MARKER + r"\b\s*(?:\[(?P<cols>[^\]]*)\])?", re.IGNORECASE)
-
-
-@dataclasses.dataclass(frozen=True)
-class FilterInjectionSite:
-    """A ``SELECT`` carrying a ``chalk_filter_injection_site`` comment, plus the optional set of
-    output columns the author scoped that site to."""
-
-    select: sqlglot_expressions.Select
-    columns: Optional[frozenset[str]]
-    """Output columns this site accepts. ``None`` means the site is unqualified and accepts every
-    filterable column; an empty set means the site was explicitly scoped to no columns."""
-
-    def accepts(self, column_name: str) -> bool:
-        return self.columns is None or column_name in self.columns
-
-    def inject(self, condition: sqlglot_expressions.Condition | str, *, dialect: str | None) -> None:
-        """AND ``condition`` into this site's ``WHERE`` clause, mutating the parsed tree in place.
-
-        ``copy=False`` is required: the surrounding query (which the rewriter subsequently wraps)
-        holds a reference to this same ``Select`` node, so the injection must mutate it rather than
-        return a fresh copy.
-        """
-        self.select.where(condition, dialect=dialect, copy=False)
-
-
-def _parse_marker(comment: str) -> tuple[bool, Optional[frozenset[str]]]:
-    """Return ``(is_marker, columns)`` for a single comment string.
-
-    ``columns`` is ``None`` for an unqualified marker and a (possibly empty) frozenset of output
-    column names for a ``[...]``-qualified marker.
-    """
-    match = _MARKER_RE.search(comment)
-    if match is None:
-        return False, None
-    cols_group = match.group("cols")
-    if cols_group is None:
-        return True, None
-    columns = frozenset(stripped for raw in cols_group.split(",") if (stripped := raw.strip().strip("\"'")))
-    return True, columns
-
-
-def _iter_nodes(expression: sqlglot.Expression) -> Iterable[sqlglot.Expression]:
-    # ``Expression.walk`` yields ``(node, parent, key)`` tuples on the pinned sqlglot (19.8.3) but
-    # yields bare nodes on newer releases; tolerate both so this keeps working across upgrades.
-    for item in expression.walk():
-        yield item[0] if isinstance(item, tuple) else item
-
-
-def find_filter_injection_sites(expression: sqlglot.Expression) -> list[FilterInjectionSite]:
-    """Find every ``chalk_filter_injection_site`` marker in ``expression``.
-
-    Multiple markers that resolve to the same ``SELECT`` are merged into a single site (their column
-    scopes are unioned; an unqualified marker widens the merged site to accept all columns) so a
-    given condition is never injected into the same ``SELECT`` twice.
-    """
-    by_select: dict[int, FilterInjectionSite] = {}
-    order: list[int] = []
-    for node in _iter_nodes(expression):
-        comments = node.comments
-        if not comments:
-            continue
-        for comment in comments:
-            is_marker, columns = _parse_marker(comment)
-            if not is_marker:
-                continue
-            select = (
-                node if isinstance(node, sqlglot_expressions.Select) else node.find_ancestor(sqlglot_expressions.Select)
-            )
-            if select is None:
-                _logger.warning(
-                    "Ignoring a '%s' marker that is not contained within a SELECT statement.",
-                    INJECTION_SITE_MARKER,
-                )
-                continue
-            key = id(select)
-            if key not in by_select:
-                by_select[key] = FilterInjectionSite(select=select, columns=columns)
-                order.append(key)
-            else:
-                existing = by_select[key]
-                if existing.columns is None or columns is None:
-                    merged: Optional[frozenset[str]] = None
-                else:
-                    merged = existing.columns | columns
-                by_select[key] = FilterInjectionSite(select=select, columns=merged)
-    return [by_select[key] for key in order]
-
-
-def inject_at_accepting_sites(
-    sites: list[FilterInjectionSite],
-    column_name: str,
-    condition: sqlglot_expressions.Condition | str,
-    *,
-    dialect: str | None,
-) -> int:
-    """Inject ``condition`` into every site that accepts ``column_name``; return the count injected.
-
-    A sqlglot condition is copied for each site so the same node is never shared across two places in
-    the tree (raw ``WHERE`` strings are re-parsed by ``Select.where`` and so need no copy).
-    """
-    injected = 0
-    for site in sites:
-        if not site.accepts(column_name):
-            continue
-        to_inject = condition.copy() if isinstance(condition, sqlglot_expressions.Expression) else condition
-        site.inject(to_inject, dialect=dialect)
-        injected += 1
-    return injected
-
-
-def is_noop_condition(condition: sqlglot.Expression) -> bool:
-    """Whether ``condition`` is a literal ``TRUE`` (what the filter converters emit when nothing can
-    be pushed down). Injecting it would only add ``WHERE TRUE`` noise, so callers skip it."""
-    return isinstance(condition, sqlglot_expressions.Boolean) and condition.this is True
-
-
-@dataclasses.dataclass(frozen=True)
-class NativeFilterInjectionSite:
-    """A pre-computed splice point for the native (libchalk) rewriters.
-
-    The native execution path keeps the resolver's SQL as verbatim text and cannot re-render it
-    through sqlglot, so instead of handing it a parsed site we hand it a *text offset*:
-
-    - ``inside_where`` False: ``index`` is where a new `` WHERE (<filter>)`` clause belongs -- after
-      the marked SELECT's FROM/JOIN zone (and after the marker comment itself), before any
-      GROUP BY/QUALIFY/ORDER BY/closing parenthesis.
-    - ``inside_where`` True: ``index`` points immediately past the marked SELECT's existing WHERE
-      keyword, so filters are spliced as ``(<filter>) AND`` prefixes.
-
-    The offsets are computed against the exact ``sql`` string passed in, which must be the same
-    string handed to the native UDF as ``raw_query``.
-    """
-
-    index: int
-    inside_where: bool
-
-
-# Token types that end the zone where a WHERE clause may be introduced in the marked SELECT.
-_CLAUSE_STOP_TOKENS = frozenset(
-    name
-    for name in (
-        "GROUP_BY",
-        "HAVING",
-        "QUALIFY",
-        "WINDOW",
-        "ORDER_BY",
-        "LIMIT",
-        "OFFSET",
-        "FETCH",
-        "UNION",
-        "EXCEPT",
-        "INTERSECT",
-        "SEMICOLON",
-    )
-    if hasattr(sqlglot.TokenType, name)
-)
-
-
-def _enclosing_comment_span(sql: str, name_match: re.Match[str]) -> Optional[tuple[int, int]]:
-    """The (start, end) offsets of the comment containing the marker name at ``name_match`` --
-    through the ``*/`` of a block comment, or through the newline of a ``--`` line comment."""
-    block_start = sql.rfind("/*", 0, name_match.start())
-    line_start = sql.rfind("--", 0, name_match.start())
-    if block_start == -1 and line_start == -1:
-        return None
-    if block_start > line_start:
-        block_end = sql.find("*/", name_match.end())
-        return None if block_end == -1 else (block_start, block_end + len("*/"))
-    newline = sql.find("\n", name_match.end())
-    # A line-comment marker with no trailing newline leaves nowhere safe to splice.
-    return None if newline == -1 else (line_start, newline + 1)
-
-
-def compute_native_injection_site(sql: str, dialect: str | None) -> Optional[NativeFilterInjectionSite]:
-    """Compute the text splice point for ``sql``'s ``chalk_filter_injection_site`` marker, for the
-    native SQL execution path. Returns ``None`` whenever injection cannot be done safely, in which
-    case the native rewriters fall back to their outer subquery wrap:
-
-    - no marker, several markers, or a column-qualified marker (the native rewriters build one
-      combined filter over all pushdown columns, so a scoped site cannot be honored);
-    - a marker in a GROUP BY/ORDER BY/... clause of its SELECT: no WHERE clause may start there.
-      (A marker anywhere in the FROM zone or the WHERE zone is fine: FROM-zone sites splice a new
-      WHERE at the end of the zone, WHERE-zone sites splice ``((filter)) AND`` at the clause head.);
-    - an existing WHERE predicate containing a top-level OR: the splice prepends ``(filter) AND``,
-      which would bind tighter than the OR and silently change the predicate's meaning;
-    - ``${...}`` resolver parameters (the engine substitutes them before execution, shifting every
-      offset this function computes);
-    - anything the tokenizer or parser cannot make sense of.
-    """
-    # Cheap pre-check first: this runs for every native SQL resolver at plan time, and the
-    # overwhelmingly common case is "no marker", which must not pay for a parse.
-    if INJECTION_SITE_MARKER not in sql.lower():
-        return None
-    if "${" in sql:
-        return None
-    # Callers pass the *native* dialect names, which sqlglot sometimes spells differently, and a
-    # couple of which it cannot read at all; `sqlglot_dialect_object` answers None for those and
-    # the marker falls back to the wrap.
-    dialect_obj = sqlglot_dialect_object(dialect)
-    if dialect_obj is None:
-        return None
-    try:
-        # Everything here is textual/tokenizer-based on purpose: the sqlglot *parser* drops
-        # comments in some positions (an own-line marker between the WHERE predicate and QUALIFY),
-        # and the tokenizer attaches an own-line comment to the *following* token -- so neither
-        # AST comments nor token attachment can locate the marker reliably. The regex locates it
-        # positionally; the token stream is used only for clause/parenthesis structure.
-        name_matches = list(_MARKER_RE.finditer(sql))
-        if len(name_matches) != 1:
-            return None
-        if name_matches[0].group("cols") is not None:
-            # Column-qualified sites cannot be honored natively: the rewriters build one combined
-            # filter over all pushdown columns.
-            return None
-        comment_span = _enclosing_comment_span(sql, name_matches[0])
-        if comment_span is None:
-            return None
-        marker_start, marker_end = comment_span
-
-        tokens = dialect_obj.tokenize(sql)
-        # Anchor on the last token that ends before the marker comment begins (purely positional,
-        # immune to the tokenizer's comment-attachment quirks).
-        marker_idx = None
-        for i, token in enumerate(tokens):
-            if token.end < marker_start:
-                marker_idx = i
-            else:
-                break
-        if marker_idx is None:
-            # Nothing precedes the marker; there is no SELECT for it to mark.
-            return None
-
-        zone, zone_where_idx = _marker_clause_zone(tokens, marker_idx)
-        if zone == "WHERE":
-            # A marker anywhere in the WHERE zone authorizes the site; the splice lands at the
-            # *head* of the clause (`WHERE ((filter)) AND <original predicate>`), which stays valid
-            # SQL no matter where in the predicate the marker itself sits.
-            if zone_where_idx is None:
-                # Unreachable: a "WHERE" zone always carries its WHERE token index. Guarded rather
-                # than asserted because this runs at plan time in production (-O strips asserts).
-                return None
-            if _where_zone_has_top_level_or(tokens, zone_where_idx):
-                return None
-            return NativeFilterInjectionSite(index=tokens[zone_where_idx].end + 1, inside_where=True)
-        if zone != "FROM":
-            # GROUP BY / HAVING / QUALIFY / ORDER BY / ... -- no WHERE clause may start here.
-            return None
-
-        # FROM zone: scan forward for the end of the SELECT's FROM/WHERE region, tracking
-        # parenthesis depth relative to the marker. A closing parenthesis that drops below the
-        # marker's depth is the end of the enclosing CTE/subquery.
-        depth = 0
-        previous_end = max(tokens[marker_idx].end + 1, marker_end)
-        for token_idx in range(marker_idx + 1, len(tokens)):
-            token = tokens[token_idx]
-            token_name = token.token_type.name
-            if token_name == "L_PAREN":
-                depth += 1
-            elif token_name == "R_PAREN":
-                depth -= 1
-                if depth < 0:
-                    return NativeFilterInjectionSite(index=previous_end, inside_where=False)
-            elif depth == 0:
-                if token_name == "WHERE":
-                    if _where_zone_has_top_level_or(tokens, token_idx):
-                        return None
-                    return NativeFilterInjectionSite(index=token.end + 1, inside_where=True)
-                if token_name in _CLAUSE_STOP_TOKENS:
-                    return NativeFilterInjectionSite(index=previous_end, inside_where=False)
-            previous_end = max(token.end + 1, marker_end)
-        # End of statement: the FROM zone runs to the end of the text.
-        return NativeFilterInjectionSite(index=previous_end, inside_where=False)
-    except Exception:
-        _logger.warning("Failed to compute a native filter injection site; falling back to the wrap.", exc_info=True)
-        return None
-
-
-# Clause keywords that name the zone a backward scan lands in; anything here other than WHERE
-# means the marker sits after the point where a WHERE clause could start. (Membership-only, so
-# ordering is irrelevant; frozenset spelled out to satisfy the no-set-literals semgrep rule.)
-_POST_WHERE_ZONE_TOKENS = frozenset(name for name in _CLAUSE_STOP_TOKENS if name != "SEMICOLON")
-
-
-def _marker_clause_zone(tokens: list, marker_idx: int) -> tuple[str, Optional[int]]:
-    """Which clause of its enclosing SELECT the marker-carrying token sits in: ``"FROM"`` (anywhere
-    from the select list through the FROM/JOIN zone), ``"WHERE"`` (paired with the index of that
-    WHERE token), or ``"POST_WHERE"`` (GROUP BY and later). Scans backward at balanced parenthesis
-    depth; leaving the enclosing subquery or finding SELECT/FROM at depth 0 means no later clause
-    keyword preceded the marker."""
-    depth = 0
-    for i in range(marker_idx, -1, -1):
-        token_name = tokens[i].token_type.name
-        if token_name == "R_PAREN":
-            depth += 1
-        elif token_name == "L_PAREN":
-            depth -= 1
-            if depth < 0:
-                return "FROM", None
-        elif depth == 0:
-            if token_name == "WHERE":
-                return "WHERE", i
-            if token_name in _POST_WHERE_ZONE_TOKENS:
-                return "POST_WHERE", None
-            if token_name in ("FROM", "SELECT"):
-                return "FROM", None
-    return "FROM", None
-
-
-def _where_zone_has_top_level_or(tokens: list, where_idx: int) -> bool:
-    """Whether the WHERE clause starting at ``tokens[where_idx]`` contains an OR at parenthesis
-    depth 0. Splicing ``(filter) AND`` at the head of such a predicate would bind tighter than the
-    OR and silently change its meaning, so those sites are refused."""
-    depth = 0
-    for i in range(where_idx + 1, len(tokens)):
-        token_name = tokens[i].token_type.name
-        if token_name == "L_PAREN":
-            depth += 1
-        elif token_name == "R_PAREN":
-            depth -= 1
-            if depth < 0:
-                return False
-        elif depth == 0:
-            if token_name in _CLAUSE_STOP_TOKENS:
-                return False
-            if token_name == "OR":
-                return True
-    return False