Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

35.2 KB
Raw Blame
"""Static AST guards enforcing the hard invariant: the interaction rollout
mode can decide whether a NEW native row gets produced, and nothing else.
It can never affect how an already-published row is read, answered, or
closed. The only exception is the resume command seam's handling of an
active interaction row it could not read: whether it refuses follows this
process's frozen mode and topology (see
``native_publication_enabled_in_this_process``); a row it did read is
handled the same way under every mode. Covers the import/reference guards
on read-side consumers, the counted-call-site guards on the module's own
public symbols, and the guard machinery's own self-check.

Everything here parses real source files with the standard library ``ast``
module under whatever interpreter runs pytest. This suite must run under
Python >= 3.11: the codebase uses ``match`` statements elsewhere, which an
older stdlib ``ast`` cannot parse, and a parse failure in this suite must
fail loudly (see test_tw4 below), never silently skip a file.
"""

from __future__ import annotations

import ast
import sys
from pathlib import Path

import pytest

import xagent.web.api.a2a as a2a_module
import xagent.web.api.chat as chat_module
import xagent.web.api.v1.tasks as v1_tasks_module
import xagent.web.api.websocket as websocket_module
import xagent.web.models.task_interaction as task_interaction_module
import xagent.web.services.chat_history_service as chat_history_service_module
import xagent.web.services.task_interaction_read as task_interaction_read_module
import xagent.web.services.task_interaction_service as task_interaction_service_module
import xagent.web.services.task_question_cancel as task_question_cancel_module
import xagent.web.services.task_resume as task_resume_module
import xagent.web.services.task_start as task_start_module
import xagent.web.services.task_stream_snapshot as task_stream_snapshot_module

pytestmark = pytest.mark.skipif(
    sys.version_info < (3, 11),
    reason="AST guards require Python >= 3.11 to parse this codebase's syntax",
)

# ---------------------------------------------------------------------------
# Import guard: the module half (nine modules, zero import expected)
# ---------------------------------------------------------------------------

_IMPORT_GUARD_MODULES = {
    "chat.py": chat_module,
    "chat_history_service.py": chat_history_service_module,
    "a2a.py": a2a_module,
    "task_resume.py": task_resume_module,
    "task_start.py": task_start_module,
    # The tuple adapter and the fifth consumption point. Both are read
    # side: the adapter answers "what is this task asking" and the v1
    # snapshot builder consumes it, and neither may reach for the
    # publication gate. Note what this half does and does not prove: it
    # rejects an import statement in these files themselves, not a
    # transitive one -- the adapter imports the interaction service,
    # which does import the rollout module for an unrelated counter. The
    # function half below is what covers the reference itself.
    "task_interaction_read.py": task_interaction_read_module,
    "v1/tasks.py": v1_tasks_module,
    # Two more read-side consumers: the stream snapshot loader reads the
    # pending question of a waiting task, and the question-cancel service
    # reads it and then closes the active row.
    "task_stream_snapshot.py": task_stream_snapshot_module,
    "task_question_cancel.py": task_question_cancel_module,
}

# websocket.py is exempted by name from the module-half check. Its
# read-side consumer (_load_historical_stream_snapshot_sync) is a closure
# seed of the function-half check below, which binds that function's own
# scope rather than every import in the module.
_WEBSOCKET_IMPORT_EXEMPTION = frozenset({"websocket.py"})


def _module_source_path(module) -> Path:
    return Path(module.__file__)


def _imports_interaction_rollout(tree: ast.Module) -> bool:
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            if any("interaction_rollout" in alias.name for alias in node.names):
                return True
        elif isinstance(node, ast.ImportFrom):
            if node.module and "interaction_rollout" in node.module:
                return True
            if any("interaction_rollout" in alias.name for alias in node.names):
                return True
    return False


def _parse(path: Path) -> ast.Module:
    source = path.read_text()
    try:
        return ast.parse(source, filename=str(path))
    except SyntaxError as exc:  # pragma: no cover - guard self-check below
        raise AssertionError(f"failed to parse {path}: {exc}") from exc


@pytest.mark.parametrize("label", sorted(_IMPORT_GUARD_MODULES))
def test_tw1a_import_guard_modules_do_not_import_interaction_rollout(label):
    module = _IMPORT_GUARD_MODULES[label]
    tree = _parse(_module_source_path(module))
    assert not _imports_interaction_rollout(tree), (
        f"{label} must not import interaction_rollout: read-side consumers "
        "and close-side statements must stay unaware of the rollout mode "
        "(see the module docstring's hard invariant)"
    )


def test_tw1c_websocket_module_half_exemption_is_named_and_exactly_one_module():
    assert _WEBSOCKET_IMPORT_EXEMPTION == {"websocket.py"}


# ---------------------------------------------------------------------------
# Reference guard: the function half (websocket.py's replacement for
# module-level zero-import: 8 closure seeds, own-scope-only banned-name scan)
# ---------------------------------------------------------------------------

_BANNED_NAMES = frozenset(
    {
        "interaction_rollout",
        "evaluate_native_publication",
        "get_interaction_rollout_policy",
        # The resume seam's accessor: its one production call site is
        # pinned by the counted-call-site guard below.
        "native_publication_enabled_in_this_process",
        # Included even though the production call-count guard below would
        # also catch a read-side consumer calling this: a fail-closed guard
        # should never depend on a second guard to notice the same
        # violation.
        "validate_interaction_rollout_at_startup",
        "InteractionRolloutPolicy",
        # The module-private accessor and its backing singleton: a
        # read-side consumer reaching for either one bypasses the public
        # accessor (and its own fail-fast check) entirely, so both must be
        # banned directly rather than relying on the public name alone to
        # catch it.
        "_require_policy",
        "_policy",
    }
)

# The 8 closure seeds are not 3: get_task and get_task_status's own bodies
# (the code outside their nested _get_task_sync / _get_task_status_sync
# definitions) are themselves part of the read path -- they are the
# *callers* of the nested sync functions, not reachable *from* them, so a
# scan that only checked the 3 innermost functions would miss a banned name
# referenced directly in the outer function body. Two more seeds were added
# alongside the tuple adapter: the adapter's own entry point is the one
# function every waiting-status read now funnels through, and the fifth
# consumption point (v1's task info snapshot builder) had no closure-half
# coverage at all before this. The stream snapshot loader is a seed for the
# same reason as the v1 snapshot builder: it reads the pending question
# directly.
_CLOSURE_SEEDS = [
    ("chat.py", "get_task"),
    ("chat.py", "get_task._get_task_sync"),
    ("chat.py", "get_task_status"),
    ("chat.py", "get_task_status._get_task_status_sync"),
    ("websocket.py", "_load_historical_stream_snapshot_sync"),
    ("task_interaction_read.py", "get_pending_interaction_question"),
    ("v1/tasks.py", "_load_task_info_snapshot"),
    ("task_stream_snapshot.py", "load_task_stream_snapshots"),
]

_SOURCE_BY_LABEL = {
    "chat.py": chat_module,
    "websocket.py": websocket_module,
    "task_interaction_read.py": task_interaction_read_module,
    "v1/tasks.py": v1_tasks_module,
    "task_stream_snapshot.py": task_stream_snapshot_module,
}


def _direct_scope_functions(scope) -> list:
    """Function/async-function defs belonging to ``scope``'s own scope.

    Walks through control-flow wrappers (``try``/``if``/``with``/loops --
    none of which introduce a new Python scope) but does not descend into a
    further-nested function or class body. ``_get_task_sync`` sits inside a
    ``try:`` block directly in ``get_task``'s body, so a check that only
    looked at immediate AST children (``ast.iter_child_nodes(scope)``, no
    deeper) would silently never find it -- exactly the failure mode this
    helper (and the ast.walk-based approach in general) exists to avoid.
    """
    results = []

    def _walk(node):
        for child in ast.iter_child_nodes(node):
            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                results.append(child)
                # A new scope -- do not look inside it for *this* scope's
                # functions; it gets scanned separately under its own name.
            elif isinstance(child, ast.ClassDef):
                pass  # a new scope; irrelevant to this codebase's shape here
            else:
                _walk(child)

    _walk(scope)
    return results


def _find_qualified_function(tree: ast.Module, qualname: str):
    """Resolve a dotted qualname (``outer.inner``) to its FunctionDef node.

    Not a Module.body-only lookup: ``_get_task_sync`` and
    ``_get_task_status_sync`` are nested one level deep inside a ``try:``
    block, and a shallow walk would silently never find them.
    """
    parts = qualname.split(".")
    scope = tree
    found = None
    for index, name in enumerate(parts):
        candidates = _direct_scope_functions(scope)
        found = next((c for c in candidates if c.name == name), None)
        if found is None:
            raise AssertionError(
                f"function {qualname!r} not found (stuck resolving "
                f"part {index} = {name!r})"
            )
        scope = found
    return found


def _own_scope_identifiers(func_node) -> set[str]:
    """Every Name id / Attribute attr referenced in this function's own
    body -- not descending into further-nested function definitions, which
    get scanned separately under their own qualified name. Without this
    exclusion, an outer function would be flagged for merely *containing*
    a banned reference inside an inner definition, turning a real guard
    into noise on the first unrelated nested helper."""
    identifiers: set[str] = set()

    class _Visitor(ast.NodeVisitor):
        def visit_FunctionDef(self, node):  # noqa: N802 - ast visitor API
            if node is func_node:
                self.generic_visit(node)
            # else: a deeper nested def -- belongs to its own scope, skip.

        def visit_AsyncFunctionDef(self, node):  # noqa: N802
            self.visit_FunctionDef(node)

        def visit_Name(self, node):  # noqa: N802
            identifiers.add(node.id)

        def visit_Attribute(self, node):  # noqa: N802
            identifiers.add(node.attr)
            self.generic_visit(node)

    _Visitor().visit(func_node)
    return identifiers


def _scan_closure_for_banned_names() -> dict[str, set[str]]:
    """For each of the 8 closure seeds, the banned names (if any) found in
    its own scope. Real production files, always re-parsed from disk."""
    hits: dict[str, set[str]] = {}
    trees = {
        label: _parse(_module_source_path(module))
        for label, module in _SOURCE_BY_LABEL.items()
    }
    for label, qualname in _CLOSURE_SEEDS:
        func_node = _find_qualified_function(trees[label], qualname)
        found = _own_scope_identifiers(func_node) & _BANNED_NAMES
        if found:
            hits[f"{label}::{qualname}"] = found
    return hits


def test_tw1b_closure_seeds_reference_no_banned_names():
    # _get_task_sync / _get_task_status_sync sit one level inside a `try:`
    # block in get_task / get_task_status, not as direct ast.Module.body
    # children -- a scanner that only checked Module.body would silently
    # never find either one, turning this into an always-green false guard.
    # _find_qualified_function (used above to resolve the 8 closure seeds)
    # walks through control-flow wrappers for exactly this reason.
    hits = _scan_closure_for_banned_names()
    assert hits == {}, f"read-side consumer(s) reference the rollout module: {hits}"


# ---------------------------------------------------------------------------
# The protocol marker literal guard: any comparison against a protocol
# version marker attribute must name INTERACTION_PROTOCOL_VERSION, not the
# literal it happens to equal today. Two call sites share this scanner: the
# read surface's ``interaction_protocol_version`` marker (default attribute
# name below) and the service module's ``protocol_version`` marker on the
# envelope/row objects that actually decide version compatibility -- see
# _SERVICE_MARKER_ATTR_NAMES and its own test below.
# ---------------------------------------------------------------------------

_DEFAULT_MARKER_ATTR_NAMES = frozenset({"interaction_protocol_version"})

# The service module's version-comparison sites read ``protocol_version``
# off ``envelope`` or a fetched ``row``/``ir`` object, never the read
# surface's ``interaction_protocol_version`` name -- a different attribute
# name on different carrier objects, not a second occurrence of the same
# one. Kept as its own named set (rather than unioning into the default)
# so a bare ``_protocol_marker_comparisons(tree)`` call keeps scanning for
# exactly the one name it always has.
_SERVICE_MARKER_ATTR_NAMES = frozenset({"protocol_version"})


def _protocol_marker_comparisons(
    tree: ast.Module, attr_names: frozenset[str] = _DEFAULT_MARKER_ATTR_NAMES
) -> list[tuple[int, str]]:
    """Every comparison against one of ``attr_names`` in a parsed module,
    as (line, comparator source shape).

    ``attr_names`` is a set, not a single string, because the two
    production call sites this scanner covers name their marker attribute
    differently: the read surface's ``interaction_protocol_version``
    (this function's default) and the service module's ``protocol_version``
    (see ``_SERVICE_MARKER_ATTR_NAMES``). Each caller passes the one name
    relevant to the file it is scanning; the set is never widened to cover
    both at once, so a match in one file cannot be satisfied by the other
    file's attribute spelling.

    Counts two shapes, not just the direct one: comparing the attribute
    itself (``<obj>.<attr_name> != ...``), or comparing a local variable
    that was assigned, in one direct step, from that exact attribute
    (``marker = <obj>.<attr_name>`` followed later by ``marker != ...``)
    -- both production call sites read the marker into a local once and
    compare that, rather than comparing the attribute inline, an entirely
    ordinary style a guard that only recognized the inline shape would be
    blind to.

    Every operand of the comparison is checked, not only ``node.left``:
    the marker can just as easily appear reversed (``1 !=
    row.protocol_version``, or the aliased ``1 != marker``) or as a
    middle term of a chained comparison (``lo < marker < 2``), and a scan
    that only recognized ``node.left`` would be blind to all three --
    exactly the shapes a hand-reversed or chained rewrite of an existing
    check tends to produce. For a comparison with one or more operands
    recognized as the marker, every *other* operand in that same
    comparison is reported as something the marker was compared against;
    a chained comparison can therefore report more than one shape for a
    single line. Two attributes sharing the same match set within one
    call (e.g. ``ir.protocol_version != envelope.protocol_version``, both
    named in ``attr_names``) leaves no *other* operand at all, so that
    shape reports nothing -- it is a cross-object equality check, not a
    version-vs-literal one, and out of scope for this guard.

    This is a whole-module scan, not a scope-aware one: an assignment
    anywhere in the module can alias a name compared anywhere else in the
    module. Disclosed blind spots, not fixed here because each of the two
    production files this scanner covers has few enough call sites to
    audit by hand: a name reused for something unrelated in a different
    function is not distinguished from a real alias, and conditional
    rebinding is not modeled at all -- a name reassigned to something else
    in a later branch of the same function is still treated as an alias
    for the rest of that function. Both are provably fine for today's
    production callers; a caller reusing the same local variable name for
    an unrelated value would need this widened first.

    A plain two-operand ``marker is None`` (or ``None is marker``)
    comparison is excluded outright, not merely allowed to differ from
    the named constant: it asks an unrelated question (has a marker ever
    been published at all, not which version it names), and ``None`` has
    no version number to drift out of sync with a constant. That
    exclusion is deliberately narrow -- only a simple two-operand
    comparison where the marker's only counterpart is a literal ``None``
    -- so a chained comparison that happens to include ``None`` among
    several operands is still reported in full.
    """

    aliases: set[str] = set()
    for node in ast.walk(tree):
        if (
            isinstance(node, ast.Assign)
            and len(node.targets) == 1
            and isinstance(node.targets[0], ast.Name)
            and isinstance(node.value, ast.Attribute)
            and node.value.attr in attr_names
        ):
            aliases.add(node.targets[0].id)

    def _is_marker(operand: ast.expr) -> bool:
        if isinstance(operand, ast.Attribute):
            return operand.attr in attr_names
        return isinstance(operand, ast.Name) and operand.id in aliases

    found: list[tuple[int, str]] = []
    for node in ast.walk(tree):
        if not isinstance(node, ast.Compare):
            continue
        operands = [node.left, *node.comparators]
        marker_indices = [
            i for i, operand in enumerate(operands) if _is_marker(operand)
        ]
        if not marker_indices:
            continue
        other_operands = [
            operand for i, operand in enumerate(operands) if i not in marker_indices
        ]
        if (
            len(operands) == 2
            and len(other_operands) == 1
            and isinstance(other_operands[0], ast.Constant)
            and other_operands[0].value is None
        ):
            # The marker's one counterpart in a plain two-operand
            # comparison is a literal None -- a presence check, not a
            # "which version" check (see docstring).
            continue
        for operand in other_operands:
            if isinstance(operand, ast.Name):
                found.append((node.lineno, operand.id))
            elif isinstance(operand, ast.Constant):
                found.append((node.lineno, repr(operand.value)))
            else:
                found.append((node.lineno, type(operand).__name__))
    return found


def test_tw1d_read_surface_never_compares_the_marker_through_a_bare_literal():
    """The read surface's own step 0 only asks whether a native row was
    ever staged at all (``marker is None``, excluded from ``found`` below
    -- see ``_protocol_marker_comparisons``'s own docstring) and no longer
    decides *which* version it names; that recognition now lives with
    ``materialize_compatibility_view``'s own check on the interaction
    row's ``protocol_version`` field, a different attribute this scanner
    does not match. So this module is not expected to contain any
    ``interaction_protocol_version``-vs-version comparison today -- but
    if one is ever added back here, it must name
    ``INTERACTION_PROTOCOL_VERSION``, never a bare literal that would
    silently drift out of sync with a second protocol version. Mutation:
    add ``if marker != 1: ...`` back to the read surface and this test
    turns red (see test_tw1d_guard_flags_a_planted_literal_comparison for
    the same check against synthetic source)."""

    tree = _parse(_module_source_path(task_interaction_read_module))
    comparisons = _protocol_marker_comparisons(tree)
    offenders = [
        (line, shape)
        for line, shape in comparisons
        if shape != "INTERACTION_PROTOCOL_VERSION"
    ]
    assert offenders == [], f"marker compared against a non-constant: {offenders}"


def test_tw1d_guard_flags_a_planted_literal_comparison(tmp_path):
    """The guard's own destructive check: a literal comparison must be
    reported, not silently accepted."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(task):\n"
        "    if task.interaction_protocol_version != 1:\n"
        "        return None\n"
    )
    assert _protocol_marker_comparisons(_parse(planted)) == [(2, "1")]


def test_tw1d_guard_flags_a_planted_reversed_literal_comparison(tmp_path):
    """The marker can appear on the right-hand side of the comparison
    (``1 != task.interaction_protocol_version``) just as easily as on the
    left -- a rewrite that flips operand order for style reasons is
    ordinary, not adversarial. A guard that only inspected ``node.left``
    would miss this entirely."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(task):\n"
        "    if 1 != task.interaction_protocol_version:\n"
        "        return None\n"
    )
    assert _protocol_marker_comparisons(_parse(planted)) == [(2, "1")]


def test_tw1d_guard_flags_a_planted_aliased_reversed_literal_comparison(tmp_path):
    """The same right-hand-side blind spot, compounded with the local
    alias the read surface itself uses: ``marker`` assigned from
    ``interaction_protocol_version`` and then compared with the literal
    on the left (``1 != marker``)."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(task):\n"
        "    marker = task.interaction_protocol_version\n"
        "    if 1 != marker:\n"
        "        return None\n"
    )
    assert _protocol_marker_comparisons(_parse(planted)) == [(3, "1")]


def test_tw1d_guard_flags_a_planted_chained_literal_comparison(tmp_path):
    """The marker can also appear as the middle term of a chained
    comparison (``lo < marker < hi``), where it is neither ``node.left``
    nor the sole entry in ``node.comparators`` -- both of the other
    operands in the chain must be reported, not just one."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(task):\n"
        "    marker = task.interaction_protocol_version\n"
        "    if 0 < marker < 2:\n"
        "        return None\n"
    )
    assert _protocol_marker_comparisons(_parse(planted)) == [(3, "0"), (3, "2")]


def test_tw1e_service_module_never_compares_the_marker_through_a_bare_literal():
    """The three places task_interaction_service.py actually decides
    whether a version is recognized -- create()'s envelope check, the
    compatibility view's row check, and respond()'s envelope check --
    each compare a ``protocol_version`` attribute (on ``envelope`` or a
    fetched row) against a version. All three must name
    ``INTERACTION_PROTOCOL_VERSION``, never a bare literal that would
    silently drift out of sync with a second protocol version. This is
    the read surface's sibling check (test_tw1d above), aimed at the
    module that actually does the comparing today: task_interaction_read
    only asks whether a marker exists at all (``marker is None``, not a
    version comparison), while this module runs the real check.
    Mutation: replace any of the three ``INTERACTION_PROTOCOL_VERSION``
    call sites with a bare ``1`` and this test turns red (see the
    test_tw1e_guard_flags_a_planted_* tests below for the same check
    against synthetic source, and the module docstring's live mutation
    log for the two real call sites exercised end to end)."""

    tree = _parse(_module_source_path(task_interaction_service_module))
    comparisons = _protocol_marker_comparisons(
        tree, attr_names=_SERVICE_MARKER_ATTR_NAMES
    )
    offenders = [
        (line, shape)
        for line, shape in comparisons
        if shape != "INTERACTION_PROTOCOL_VERSION"
    ]
    assert offenders == [], f"marker compared against a non-constant: {offenders}"


def test_tw1e_guard_flags_a_planted_literal_comparison_on_a_row_attribute(tmp_path):
    """The service module's shape: a fetched row's ``protocol_version``
    compared inline against a bare literal (mirrors the real check at
    task_interaction_service.py's compatibility-view call site)."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(row):\n    if row.protocol_version != 1:\n        return None\n"
    )
    assert _protocol_marker_comparisons(
        _parse(planted), attr_names=_SERVICE_MARKER_ATTR_NAMES
    ) == [(2, "1")]


def test_tw1e_guard_flags_a_planted_reversed_literal_comparison(tmp_path):
    """Same reversed-operand blind spot as test_tw1d above, checked
    against the service module's ``protocol_version`` attribute name
    instead of the read surface's ``interaction_protocol_version``."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(row):\n    if 1 != row.protocol_version:\n        return None\n"
    )
    assert _protocol_marker_comparisons(
        _parse(planted), attr_names=_SERVICE_MARKER_ATTR_NAMES
    ) == [(2, "1")]


def test_tw1e_guard_flags_a_planted_aliased_literal_comparison(tmp_path):
    """The service module's own step 0 in each of its three checks reads
    ``envelope.protocol_version`` (or ``row.protocol_version``) into a
    local once and compares that -- the same aliasing shape as the read
    surface's ``marker`` local, exercised here against
    ``protocol_version`` instead of ``interaction_protocol_version``."""

    planted = tmp_path / "planted.py"
    planted.write_text(
        "def read(envelope):\n"
        "    version = envelope.protocol_version\n"
        "    if version != 1:\n"
        "        return None\n"
    )
    assert _protocol_marker_comparisons(
        _parse(planted), attr_names=_SERVICE_MARKER_ATTR_NAMES
    ) == [(3, "1")]


# ---------------------------------------------------------------------------
# The guard machinery's own self-check -- a parse failure must fail loudly
# ---------------------------------------------------------------------------


def test_tw4_syntax_error_in_a_scanned_file_fails_loudly(tmp_path):
    broken = tmp_path / "broken.py"
    broken.write_text("def f(:\n    pass\n")
    with pytest.raises(AssertionError):
        _parse(broken)


# ---------------------------------------------------------------------------
# Counted-call-site guards: production symbols (src/, excluding tests/)
# ---------------------------------------------------------------------------


def _src_root() -> Path:
    # xagent.web.api.chat is .../src/xagent/web/api/chat.py
    return _module_source_path(chat_module).parents[2]


def _iter_src_files():
    root = _src_root()
    for path in sorted(root.rglob("*.py")):
        yield path


def _count_calls(symbol: str) -> list[tuple[Path, int]]:
    hits: list[tuple[Path, int]] = []
    for path in _iter_src_files():
        tree = _parse(path)
        for node in ast.walk(tree):
            if not isinstance(node, ast.Call):
                continue
            func = node.func
            if isinstance(func, ast.Name) and func.id == symbol:
                hits.append((path, node.lineno))
            elif isinstance(func, ast.Attribute) and func.attr == symbol:
                hits.append((path, node.lineno))
    return hits


def test_tw2a_evaluate_native_publication_has_zero_production_callers():
    hits = _count_calls("evaluate_native_publication")
    assert hits == [], f"unexpected production caller(s): {hits}"


_GET_POLICY_SITE_WHITELIST = {
    ("app.py", "readiness_check"),
    ("admin_interaction_rollout.py", "get_interaction_rollout_diagnostics"),
}


def _enclosing_function_name(tree: ast.Module, lineno: int) -> str | None:
    best = None
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            start = node.lineno
            end = max(
                (getattr(n, "lineno", start) for n in ast.walk(node)), default=start
            )
            if start <= lineno <= end:
                if best is None or start > best.lineno:
                    best = node
    return best.name if best is not None else None


def test_tw2c_get_interaction_rollout_policy_has_at_most_two_whitelisted_sites():
    # The bound is <=2, not ==2, on purpose: a count of 1 (e.g. if the admin
    # diagnostics endpoint moved into its own later change) must stay valid
    # too -- only a site outside the whitelist, or more than 2 sites total,
    # may fail this guard.
    hits = _count_calls("get_interaction_rollout_policy")
    seen = set()
    for path, lineno in hits:
        tree = _parse(path)
        func_name = _enclosing_function_name(tree, lineno)
        seen.add((path.name, func_name))

    assert len(hits) <= 2, f"more than 2 call sites: {hits}"
    for site in seen:
        assert site in _GET_POLICY_SITE_WHITELIST, f"unlisted call site: {site}"


def _call_site_functions(symbol: str) -> list[tuple[str, str | None]]:
    """``(file name, enclosing function)`` of every production call of
    ``symbol``, one entry per call."""
    return [
        (path.name, _enclosing_function_name(_parse(path), lineno))
        for path, lineno in _count_calls(symbol)
    ]


def test_tw2e_native_publication_enabled_in_this_process_has_one_call_in_resume_task():
    assert _call_site_functions("native_publication_enabled_in_this_process") == [
        ("task_command_execution.py", "resume_task")
    ]


def test_tw2f_native_publication_enabled_in_this_process_is_imported_by_name_once():
    imports = []
    for path in _iter_src_files():
        for node in ast.walk(_parse(path)):
            if isinstance(node, ast.ImportFrom):
                imports.extend(
                    (path.name, alias.asname)
                    for alias in node.names
                    if alias.name == "native_publication_enabled_in_this_process"
                )
    assert imports == [("task_command_execution.py", None)]


def test_tw2d_validate_interaction_rollout_at_startup_runs_at_both_host_entries():
    hits = _count_calls("validate_interaction_rollout_at_startup")
    assert sorted(path.relative_to(_src_root()).as_posix() for path, _ in hits) == [
        "web/app.py",
        "web/worker.py",
    ]


# ---------------------------------------------------------------------------
# Task.source construction literals and post-construction mutation
# ---------------------------------------------------------------------------


def _source_literal_call_sites() -> list[tuple[Path, int, str]]:
    """Every ``source=`` / ``task_source=`` keyword whose value is a string
    literal, scoped to ``src/xagent/web`` (the audited scope -- scanning by
    keyword name rather than by callee, since Task.source is written
    through several different call targets, not just ``Task(...)``; a
    callee-restricted scan would silently miss most of them). The
    migrations directory is excluded even though it is part of that
    audited scope: historical backfills are allowed to write retired
    literals current code no longer produces, and a scan that is not
    kwarg-name-scoped elsewhere in the tree would pick up unrelated APIs
    that happen to share the same keyword name (e.g. a "source" kwarg on
    an entirely unrelated personal-database helper)."""
    hits: list[tuple[Path, int, str]] = []
    root = _src_root() / "web"
    for path in sorted(root.rglob("*.py")):
        if "migrations" in path.parts:
            continue
        tree = _parse(path)
        for node in ast.walk(tree):
            if not isinstance(node, ast.Call):
                continue
            for kw in node.keywords:
                if kw.arg in ("source", "task_source") and isinstance(
                    kw.value, ast.Constant
                ):
                    if isinstance(kw.value.value, str):
                        hits.append((path, node.lineno, kw.value.value))
    return hits


def test_tw3a_source_literals_are_a_subset_of_task_source_literals():
    hits = _source_literal_call_sites()
    literals = {value for _, _, value in hits}
    assert literals <= task_interaction_module.TASK_SOURCE_LITERALS, (
        f"literal(s) outside TASK_SOURCE_LITERALS: "
        f"{literals - task_interaction_module.TASK_SOURCE_LITERALS}"
    )


# Named, exact -- not a wildcard rule. Each is a bot/handler setting its
# *own* instance attribute (self.channel_id), unrelated to any Task ORM
# row; audited as the complete set at the pinned baseline. Paths are
# relative to src/xagent/web.
_TASK_ATTRIBUTE_MUTATION_EXEMPT_SITES = frozenset(
    {
        ("channels/feishu/bot.py", "channel_id"),
        ("channels/slack/bot.py", "channel_id"),
        ("channels/slack/trace_handler.py", "channel_id"),
        ("channels/telegram/bot.py", "channel_id"),
    }
)


def _attribute_assignments(
    attr_names: tuple[str, ...],
) -> list[tuple[Path, int, str, bool]]:
    """Every assignment to ``x.<attr> = ...`` / ``x.<attr> += ...`` in
    src/xagent/web where ``<attr>`` is one of ``attr_names``, tagged with
    whether the receiver ``x`` is ``self``. Receiver is not filtered out at
    collection time -- the self/non-self split is the test's job, so a
    drift in which sites are self-only is visible instead of silently
    never collected."""
    hits: list[tuple[Path, int, str, bool]] = []
    web_root = _src_root() / "web"
    for path in sorted(web_root.rglob("*.py")):
        tree = _parse(path)
        for node in ast.walk(tree):
            targets = []
            if isinstance(node, ast.Assign):
                targets = node.targets
            elif isinstance(node, ast.AugAssign):
                targets = [node.target]
            for target in targets:
                if isinstance(target, ast.Attribute) and target.attr in attr_names:
                    is_self = (
                        isinstance(target.value, ast.Name) and target.value.id == "self"
                    )
                    hits.append((path, node.lineno, target.attr, is_self))
    return hits


def test_tw3b_no_post_construction_mutation_outside_the_named_self_exemption():
    hits = _attribute_assignments(("source", "channel_id"))
    web_root = _src_root() / "web"

    non_self = [
        (path, lineno, attr) for path, lineno, attr, is_self in hits if not is_self
    ]
    assert non_self == [], f"non-self post-construction mutation(s) found: {non_self}"

    self_sites = {
        (str(path.relative_to(web_root)), attr)
        for path, _lineno, attr, is_self in hits
        if is_self
    }
    added = self_sites - _TASK_ATTRIBUTE_MUTATION_EXEMPT_SITES
    removed = _TASK_ATTRIBUTE_MUTATION_EXEMPT_SITES - self_sites
    assert self_sites == _TASK_ATTRIBUTE_MUTATION_EXEMPT_SITES, (
        "self-attribute exemption set drifted from the audited baseline. "
        f"New site(s) found that are not yet exempted: {added or '{}'} -- "
        "this is expected when a new bot class assigns its own "
        "self.source/self.channel_id; after confirming the receiver is not "
        "a Task row, add the file to "
        "_TASK_ATTRIBUTE_MUTATION_EXEMPT_SITES. "
        f"Previously-exempted site(s) no longer found: {removed or '{}'} -- "
        "the exemption set must shrink to drop them."
    )