feat: add RelationshipChecker for advisory JOIN validation (v0.7.0)

[flyersworder]

Summary

• Add RelationshipChecker that validates SQL JOINs against declared semantic relationships with three advisory detection modes: join-key correctness, required-filter enforcement, and fan-out risk detection
• Wire into Validator via optional semantic_source parameter — fully backward-compatible
• Warnings only (never blocks), silent on undeclared joins — no false positives from incomplete relationship definitions

What it does

When a SemanticSource with relationships is passed to the Validator, the checker:

1. Join-key correctness — warns if agent joins on wrong columns vs. declared from/to (supports both ON and USING syntax)
2. Required-filter enforcement — warns if a relationship's required_filter column is missing from WHERE
3. Fan-out risk — warns if aggregating (SUM, COUNT, etc.) across a one_to_many join (top-level SELECT only, ignores subqueries)

Test plan

• 18 unit tests covering all three detection modes + edge cases (aliases, bare names, case-insensitive, USING clause, subquery aggregation)
• 3 integration tests for Validator + SemanticSource wiring
• 280/280 tests passing, ruff + ty clean
• Pre-commit hooks pass

🤖 Generated with Claude Code

[flyersworder]

Code review

Found 2 issues:

1. USING clause picks wrong from_table in 3+ table queries (bug)

In _extract_join_columns, the USING branch selects the from-table as [t for t in alias_map.values() if t != joined_table][0]. Since alias_map contains all tables in the query, this picks an arbitrary first match rather than the actual preceding table in the join chain. For FROM orders JOIN customers ON ... JOIN addresses USING (customer_id), the second join resolves from_table to orders instead of customers, causing incorrect relationship lookups or silent misses.

agentic-data-contracts/src/agentic_data_contracts/validation/checkers.py

Lines 373 to 381 in 3fa0816

	# Find the FROM table: first table in alias_map that isn't the joined table
	from_tables = [t for t in alias_map.values() if t != joined_table]
	from_table = from_tables[0] if from_tables else ""
	for ident in using_clause:
	col_name = ident.name.lower()
	# USING means both sides use the same column name
	results.append((from_table, col_name, joined_table, col_name))
	return results

2. _has_aggregation false positive for scalar subqueries in SELECT list (bug)

_has_aggregation iterates select.expressions and calls find_all(*AGG_TYPES) on each, which recurses into scalar subquery nodes. A query like SELECT (SELECT AVG(price) FROM products), o.id FROM orders o JOIN order_items oi ON o.id = oi.order_id triggers a fan-out warning even though the outer query has no aggregation. The existing parent_select guard only skips subqueries in FROM/WHERE, not scalar subqueries embedded in SELECT expressions.

agentic-data-contracts/src/agentic_data_contracts/validation/checkers.py

Lines 430 to 441 in 3fa0816

	@staticmethod
	def _has_aggregation(ast: exp.Expression) -> bool:
	"""Check if the top-level SELECT contains any aggregation functions.
	Ignores aggregations inside subqueries to avoid false positives.
	"""
	for select in ast.find_all(exp.Select):
	if select.parent_select is not None:
	continue
	# Check only the SELECT's own expressions, not subqueries
	for expr in select.expressions:

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}