chore: replace file:line references with symbol names in comments

Line-number references drift silently. Several were already wrong:
factory.py:627-628 / :631-636 / :632-702 (cited as run_query, now
lookup_domain), validator.py:307 (cited as the EXPLAIN round-trip, now
the relationship advisory block), test_validator.py:412 (a class
boundary), and factory.py:634-636 in test_sdk.

Each now names the symbol it means -- Validator.validate ->
explain_adapter.explain, run_query's _with_remaining, Validator's frozen
_QueryRuleEntry, RequiredFilterValuesChecker's class docstring, and
TestValidatorWithSemanticSource::test_validator_with_semantic_source_emits_warnings.
The four references that were still accurate are converted too, so the
convention is uniform and the drift class is gone.

Comments only -- no behaviour change. Full suite 812 passed; prek green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: flyersworder

src/agentic_data_contracts/tools/factory.py

@@ -235,8 +235,8 @@ def create_tools(
     )
 
     # Build relationship index for BFS path-finding in lookup_relationships.
-    # This is a snapshot, same pattern as Validator (validator.py:70) which also
-    # captures relationships at construction time.  Direct table lookups go
+    # This is a snapshot, same pattern as Validator's frozen _QueryRuleEntry,
+    # which also captures its inputs at construction time.  Direct lookups go
     # through semantic_source.get_relationships_for_table() instead.
     _rel_index = (
         build_relationship_index(semantic_source.get_relationships())
@@ -392,8 +392,8 @@ async def preview_table(args: dict[str, Any]) -> dict[str, Any]:
         # QUERY SHAPE the caller writes — `required_filter`, `no_select_star`,
         # `require_limit`, `max_joins` — because preview synthesises its own
         # SELECT *  LIMIT N and those rules guard run_query's user-supplied SQL.
-        # Mirrors Validator._is_table_in_scope + _rule_applies_to_principal
-        # (validator.py:233-247); keep the table/principal predicates in sync.
+        # Mirrors Validator._is_table_in_scope + _rule_applies_to_principal;
+        # keep the table/principal predicates in sync.
         block_msgs: list[str] = []
         warn_msgs: list[str] = []
         log_msgs: list[str] = []
@@ -765,8 +765,9 @@ async def trace_metric_impacts(args: dict[str, Any]) -> dict[str, Any]:
     async def inspect_query(args: dict[str, Any]) -> dict[str, Any]:
         sql = args.get("sql", "")
         # validate() runs a synchronous EXPLAIN/dry-run round-trip to the DB
-        # (validator.py:307) when an explain adapter is configured, so offload
-        # it to a worker thread to keep the event loop responsive.
+        # (Validator.validate -> explain_adapter.explain) when an explain
+        # adapter is configured, so offload it to a worker thread to keep the
+        # event loop responsive.
         result = await asyncio.to_thread(validator.validate, sql)
         data: dict[str, Any] = {
             "valid": not result.blocked,
@@ -799,8 +800,9 @@ def _with_remaining(msg: str) -> str:
             )
 
         # Phase 1 + 2: query checks + EXPLAIN. validate() makes a synchronous
-        # EXPLAIN/dry-run DB round-trip (validator.py:307), so offload it to a
-        # worker thread to avoid blocking the event loop.
+        # EXPLAIN/dry-run DB round-trip (Validator.validate ->
+        # explain_adapter.explain), so offload it to a worker thread to avoid
+        # blocking the event loop.
         vresult = await asyncio.to_thread(validator.validate, sql)
         if vresult.blocked:
             session.record_retry()

src/agentic_data_contracts/tools/langchain.py

@@ -25,7 +25,7 @@
 violations as JSON without blocking. The in-tool path here therefore only
 runs ``session.check_limits()`` and the ``BLOCKED —`` prefix sniff; SQL
 validation is left to the underlying tools (``run_query`` self-validates
-at ``factory.py:632-702``).
+inside ``factory.create_tools``).
 
 Requires the ``[langchain]`` extra: ``pip install agentic-data-contracts[langchain]``.
 """
@@ -54,8 +54,8 @@
 
 def _with_remaining(message: str, session: ContractSession) -> str:
     """Append the canonical ``Remaining: {budget}`` suffix used by
-    ``run_query`` (factory.py:627-628) so wrapper-emitted blocks carry
-    the same diagnostic footprint as run_query's own blocks."""
+    ``run_query``'s own ``_with_remaining`` helper, so wrapper-emitted
+    blocks carry the same diagnostic footprint as run_query's own blocks."""
     return f"{message}\nRemaining: {json.dumps(session.remaining(), default=str)}"
 
 
@@ -220,9 +220,9 @@ def _check(self, request: ToolCallRequest) -> ToolMessage | None:
         # Session-limit breach: do NOT call ``record_retry()`` here. The
         # session is already past its cap; recording another retry would
         # increment past it for no benefit and risks double-counting if a
-        # future ceiling is added. This mirrors ``factory.py:631-636`` where
-        # ``run_query`` similarly skips ``record_retry`` on limit-exceeded
-        # but does record on validation-block (next branch).
+        # future ceiling is added. This mirrors ``run_query`` in ``factory``,
+        # which similarly skips ``record_retry`` on limit-exceeded but does
+        # record on validation-block (next branch).
         try:
             self._session.check_limits()
         except LimitExceededError as e:
@@ -274,9 +274,10 @@ async def awrap_tool_call(
         handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
     ) -> ToolMessage | Command[Any]:
         # _check runs the synchronous Validator.validate(), which makes a
-        # blocking EXPLAIN/dry-run DB round-trip (validator.py:307). Offload it
-        # to a worker thread so a slow check cannot stall the event loop in an
-        # async runtime. The sync wrap_tool_call path calls _check directly.
+        # blocking EXPLAIN/dry-run DB round-trip via explain_adapter.explain.
+        # Offload it to a worker thread so a slow check cannot stall the event
+        # loop in an async runtime. The sync wrap_tool_call path calls _check
+        # directly.
         blocked = await asyncio.to_thread(self._check, request)
         if blocked is not None:
             return blocked

src/agentic_data_contracts/tools/middleware.py

@@ -49,8 +49,9 @@ async def wrapper(args: dict[str, Any]) -> dict[str, Any]:
             sql = args.get("sql", "")
             if sql:
                 # validate() makes a synchronous EXPLAIN/dry-run DB round-trip
-                # (validator.py:307), so offload it to a worker thread to keep
-                # the event loop responsive — same rationale as factory.py.
+                # (Validator.validate -> explain_adapter.explain), so offload it
+                # to a worker thread to keep the event loop responsive — same
+                # rationale as factory.py.
                 result = await asyncio.to_thread(validator.validate, sql)
                 if result.blocked:
                     session.record_retry()

src/agentic_data_contracts/tools/sdk.py

@@ -10,8 +10,8 @@
 
 SQL validation is intentionally **not** auto-applied. Doing so would
 block ``inspect_query`` from reporting violations as JSON; the canonical
-``run_query`` self-validation at ``factory.py:632-702`` already covers
-the cost path.
+``run_query`` self-validation inside ``factory.create_tools`` already
+covers the cost path.
 
 Pass ``apply_middleware=False`` to opt out (preserves the pre-0.20.0
 behavior where only ``run_query`` self-checked limits).
@@ -35,8 +35,8 @@
 
 def _with_remaining(message: str, session: ContractSession) -> str:
     """Append the canonical ``Remaining: {budget}`` suffix used by
-    ``run_query`` (factory.py:627-628) so wrapper-emitted blocks carry
-    the same diagnostic footprint as run_query's own blocks."""
+    ``run_query``'s own ``_with_remaining`` helper, so wrapper-emitted
+    blocks carry the same diagnostic footprint as run_query's own blocks."""
     return f"{message}\nRemaining: {json.dumps(session.remaining(), default=str)}"
 
 

tests/test_portability/test_contract_round_trip.py

@@ -33,8 +33,10 @@
 
 # A query whose verdict depends on the semantic source: joining orders -> customers
 # without the relationship's required_filter ("status != 'cancelled'") makes the
-# producer emit a warning (mirrors test_validator.py:412). The table allowlist and
-# rules (tenant_id filter present, explicit columns) are satisfied, so it is never
+# producer emit a warning (mirrors
+# TestValidatorWithSemanticSource::test_validator_with_semantic_source_emits_warnings).
+# The table allowlist and rules (tenant_id filter, explicit columns) are
+# satisfied, so it is never
 # *blocked* — the only enforcement signal is the semantic-source-derived warning.
 SEMANTIC_DEPENDENT_SQL = (
     "SELECT o.id, c.name FROM analytics.orders o"

tests/test_tools/test_factory_principals.py

@@ -461,8 +461,8 @@ async def test_required_filter_values_unmapped_caller_passes(
         self, preview_adapter: DuckDBAdapter
     ) -> None:
         # C2 companion: callers absent from values_by_principal fall through
-        # the rule (mirrors RequiredFilterValuesChecker's documented contract,
-        # checkers.py:339-340). Preview proceeds.
+        # the rule (mirrors RequiredFilterValuesChecker's documented
+        # contract in its class docstring). Preview proceeds.
         contract = _preview_contract(
             """
     - name: tenant_scoped_to_alice

tests/test_tools/test_row_format.py

@@ -242,7 +242,8 @@ async def test_preview_table_compact_carries_columns(
     text = result["content"][0]["text"]
     # `columns` must precede `rows` in the serialized body — json.dumps
     # preserves insertion order, so the model reads the header before the
-    # positional values it must align to (factory.py:449-450).
+    # positional values it must align to (see the key-order comment in
+    # preview_table).
     assert text.index('"columns"') < text.index('"rows"')
     body = json.loads(text)
     assert body["columns"] == ["id", "amount", "tenant_id"]

tests/test_tools/test_sdk.py

@@ -146,7 +146,7 @@ async def test_wrap_with_session_check_blocks_on_limit_exceeded(
     callable returns the canonical BLOCKED envelope without invoking
     the inner function. The envelope includes a ``Remaining:`` suffix so
     the agent can see remaining budget — matching ``run_query``'s own
-    blocked-path format at ``factory.py:634-636``."""
+    blocked-path format, produced by its ``_with_remaining`` helper."""
     session = ContractSession(contract_with_limits)
     for _ in range(4):  # exceed max_retries=3
         session.record_retry()