sqlbenchdag 0.1.0__py3-none-any.whl

sql_benchmarks/utils/providers.py

@@ -0,0 +1,184 @@
+import numpy as np
+
+def generate_sequence(rows: int, **kwargs):
+    start = kwargs.get("start", 1)
+    step = kwargs.get("step", 1)
+    return np.arange(start, start + (rows * step), step)
+
+def generate_random_int(rows: int, **kwargs):
+    # Support both canonical (min_value) and YAML-style (min)
+    mn = kwargs.get("min_value") or kwargs.get("min")
+    mx = kwargs.get("max_value") or kwargs.get("max")
+    
+    # Fallback to defaults if still None
+    if mn is None: mn = 0
+    if mx is None: mx = 100
+    return np.random.randint(mn, mx, size=rows)
+
+def generate_random_float(rows: int, **kwargs):
+    # Support both canonical (min_value) and YAML-style (min)
+    mn = kwargs.get("min_value") or kwargs.get("min")
+    mx = kwargs.get("max_value") or kwargs.get("max")
+    
+    # Fallback to defaults if still None
+    if mn is None: mn = 0.0
+    if mx is None: mx = 1.0
+    return np.random.uniform(mn, mx, size=rows)
+
+def generate_choice(rows: int, **kwargs):
+    options = kwargs.get("options", [])
+    weights = kwargs.get("weights", None)
+    if not options:
+        raise ValueError("Provider 'choice' requires 'options' list.")
+    
+    if weights is not None:
+        # Robust Normalization (Restore your fixed arithmetic)
+        w = np.array(weights, dtype=float)
+        if w.sum() <= 0:
+            raise ValueError("Weights must sum to a positive value.")
+        p = w / w.sum()
+        # Force strict 1.0 sum to satisfy numpy
+        if len(p) > 0:
+            p[-1] = 1.0 - p[:-1].sum()
+    else:
+        p = None
+        
+    return np.random.choice(options, size=rows, p=p)
+
+def generate_text_concat(rows: int, existing_data: dict, **kwargs):
+    source_col = kwargs.get("source")
+    prefix = kwargs.get("prefix", "")
+    
+    if not source_col:
+        raise ValueError("Provider 'text_concat' requires 'source' column name.")
+        
+    if source_col not in existing_data:
+        # Fallback if source hasn't been generated yet (should rely on column ordering)
+        # For now, just return prefixes to avoid crash, but warn?
+        # Ideally, we sort generation/topological sort columns.
+        # Assuming table definitions are ordered correctly by user.
+        return [prefix] * rows
+        
+    return [f"{prefix}{x}" for x in existing_data[source_col]]
+
+def generate_foreign_key(rows: int, table_name: str, **kwargs):
+    """
+    Generates foreign keys.
+    Supports distributions:
+    - 'uniform' (Default): Random parent. Avg Depth ~ O(log N).
+    - 'chain': Linked List structure (parent = id - 1). Depth = N.
+    - 'zipf': Power law. Wide tree. Most nodes point to top few IDs.
+    """
+    target_rows = kwargs.get("target_rows")
+    distribution = kwargs.get("distribution", "uniform")
+    
+    # Range of valid IDs
+    mn = 1
+    # If target_rows is set, use it. Else assume self-reference up to current rows.
+    mx = (target_rows if target_rows else rows) + 1 
+    
+    if distribution == "chain":
+        # Point to previous ID. ID 1 points to NULL (represnted as 0 or 1? Let's say 1 to be valid FK)
+        # Actually standard FK usually allows NULL. But our schema might be strict int64.
+        # Let's point root to itself (id=1 -> parent=1) or make it a forest.
+        # For simplicity: parent_id = max(1, id - 1)
+        # But we generate an array of *values*. We don't know the current ID *per row* easily unless we assume row_idx+1 = ID.
+        # Yes, declarative_gen assumes sequence ID 1..N.
+        ids = np.arange(1, rows + 1)
+        parents = ids - 1
+        parents[0] = 1 # Root points to self? Or we need NULL support.
+        # If we return ints, we can't have None.
+        # Sticking to valid ID range [1, mx).
+        parents = np.maximum(1, parents)
+        return parents
+
+    elif distribution == "zipf":
+        # numpy zipf is z ~ 1/k^a. Returns ints >= 1.
+        # We need to map this to valid ID range.
+        # A common trick: parent_id = 1 + (zipf sample % mx)
+        # But we want frequent *low* IDs (1, 2, 3 as roots).
+        # Zipf(a=2) generates many 1s.
+        a = kwargs.get("zipf_a", 2.0)
+        samples = np.random.zipf(a, size=rows)
+        # Map samples to range [1, mx-1] using modulo? 
+        # Better: min(samples, mx-1) to preserve frequency of 1.
+        parents = np.minimum(samples, mx - 1)
+        return parents
+
+    else: # uniform
+        return np.random.randint(mn, mx, size=rows)
+
+def generate_zipf_edges(rows: int, **kwargs):
+    """
+    Generate a directed edge list for a Zipf-distributed supply graph.
+
+    Each row represents one directed supply edge: (from_id, to_id).
+    The number of *outgoing* edges per node follows a power-law / Zipf
+    distribution controlled by the ``zipf_a`` parameter:
+
+      - zipf_a=2.0  → moderate skew  (a few large hubs, long tail of leaves)
+      - zipf_a=1.5  → heavy skew     (very dominant hubs)
+      - zipf_a=3.0  → mild skew      (more uniform, closer to random graph)
+
+    Self-loops are excluded.  The resulting edge list is what gets loaded as
+    the ``supplies`` relation in TypeDB and as the ``supplies`` table in DuckDB.
+
+    Columns produced: ``from_id`` (integer), ``to_id`` (integer).
+
+    Note: ``rows`` here is the *total number of edges*, not nodes.  The number
+    of nodes is controlled by the ``n_nodes`` kwarg (default 500).
+    """
+    n_nodes  = int(kwargs.get("n_nodes",  500))
+    zipf_a   = float(kwargs.get("zipf_a", 2.0))
+    seed     = kwargs.get("seed", 42)
+    rng      = np.random.default_rng(seed)
+
+    # --- 1. Assign each node an out-degree drawn from Zipf ---
+    # numpy's Zipf returns values >= 1.  Cap at n_nodes-1 so a single node
+    # can't supply more companies than exist.
+    raw_degrees = rng.zipf(zipf_a, size=n_nodes)
+    out_degrees = np.minimum(raw_degrees, n_nodes - 1).astype(int)
+
+    # --- 2. Build edge list ---
+    # For each source node, sample ``out_degree`` distinct target nodes
+    # (excluding itself).  Collect until we have exactly ``rows`` edges,
+    # cycling through nodes if needed.
+    from_ids = []
+    to_ids   = []
+    node_ids = np.arange(1, n_nodes + 1)
+
+    for src_idx, deg in enumerate(out_degrees):
+        if len(from_ids) >= rows:
+            break
+        src_id   = src_idx + 1  # 1-indexed
+        targets  = node_ids[node_ids != src_id]
+        chosen   = rng.choice(targets, size=min(deg, len(targets)), replace=False)
+        remaining = rows - len(from_ids)
+        chosen = chosen[:remaining]
+        from_ids.extend([src_id] * len(chosen))
+        to_ids.extend(chosen.tolist())
+
+    # Pad to exact row count if the degree distribution ran out early
+    while len(from_ids) < rows:
+        src = rng.integers(1, n_nodes + 1)
+        tgt = rng.integers(1, n_nodes + 1)
+        if src != tgt:
+            from_ids.append(int(src))
+            to_ids.append(int(tgt))
+
+    return {
+        "from_id": np.array(from_ids[:rows], dtype=np.int64),
+        "to_id":   np.array(to_ids[:rows],   dtype=np.int64),
+    }
+
+
+PROVIDER_REGISTRY = {
+    "sequence": generate_sequence,
+    "random_int": generate_random_int,
+    "random_float": generate_random_float,
+    "choice": generate_choice,
+    "text_concat": generate_text_concat,
+    "foreign_key": generate_foreign_key,
+    "foreign key": generate_foreign_key,  # Alias
+    "zipf_edges": generate_zipf_edges,
+}

sql_benchmarks/utils/scaling.py

@@ -0,0 +1,88 @@
+"""
+Scaling-law analysis: fit each engine's duration to a power law t = a · N^alpha.
+
+The exponent alpha is an engine's complexity class for the workload: ~0 is
+flat, 0.5 is O(sqrt N), 1 is linear. Two engines sharing an alpha but separated
+by a constant factor are the same algorithm at different fixed cost; a larger
+alpha is a fundamentally worse scaling regime.
+
+Single source of truth for both the CLI (scripts/tools/analyze_scaling.py) and
+the reporting asset, which writes scaling.json into every capsule that has a
+row-scaled matrix.
+"""
+import glob
+import json
+import math
+import os
+import statistics
+from typing import Dict, Optional
+
+
+def power_law(points: Dict[int, float]):
+    """Least-squares fit log10(t) ~ alpha*log10(N) + log10(a). Returns (alpha, r2)."""
+    xs = [math.log10(n) for n in points]
+    ys = [math.log10(points[n]) for n in points]
+    k = len(xs)
+    mx, my = sum(xs) / k, sum(ys) / k
+    sxx = sum((x - mx) ** 2 for x in xs)
+    if sxx == 0:
+        return 0.0, 1.0
+    alpha = sum((xs[i] - mx) * (ys[i] - my) for i in range(k)) / sxx
+    b = my - alpha * mx
+    ss_res = sum((ys[i] - (alpha * xs[i] + b)) ** 2 for i in range(k))
+    ss_tot = sum((y - my) ** 2 for y in ys)
+    r2 = 1 - ss_res / ss_tot if ss_tot else 1.0
+    return alpha, r2
+
+
+def regime(alpha: float) -> str:
+    if alpha < 0.15: return "near-constant"
+    if alpha < 0.45: return "sublinear"
+    if alpha < 0.65: return "~O(sqrt N)"
+    if alpha < 1.25: return "~linear"
+    return "superlinear"
+
+
+def _points_from_fragments(results_dir: str, exp_id: str) -> Dict[str, Dict[int, float]]:
+    """engine -> {rows: median_duration_seconds}, read from the capsule's raw fragments."""
+    series: Dict[str, Dict[int, list]] = {}
+    for path in glob.glob(os.path.join(results_dir, exp_id, "fragments", "*.json")):
+        with open(path) as f:
+            data = json.load(f)
+        params = data.get("parameters", {})
+        if "rows" not in params:
+            continue  # needs a numeric row axis (TPC-H uses scale_factor, skip)
+        metrics = data.get("metrics", {})
+        raw = metrics.get("durations_raw") or (
+            [metrics["duration_seconds"]] if metrics.get("duration_seconds") is not None else []
+        )
+        if not raw:
+            continue  # DNF
+        engine = data["meta"]["engine"]
+        series.setdefault(engine, {}).setdefault(int(params["rows"]), []).extend(raw)
+    return {e: {n: statistics.median(v) for n, v in by_rows.items()} for e, by_rows in series.items()}
+
+
+def analyze_capsule(results_dir: str, exp_id: str) -> Optional[dict]:
+    """
+    Returns a scaling report for a capsule, or None if it has no row-scaled
+    timings (e.g. a single-scale or scale_factor-only experiment).
+
+    {engine: {alpha, r2, growth, n_points, regime, points: {rows: seconds}}}
+    """
+    series = _points_from_fragments(results_dir, exp_id)
+    report = {}
+    for engine, pts in series.items():
+        if len(pts) < 2:
+            continue  # a power law needs at least two scale points
+        alpha, r2 = power_law(pts)
+        lo, hi = min(pts), max(pts)
+        report[engine] = {
+            "alpha": round(alpha, 4),
+            "r2": round(r2, 4),
+            "growth": round(pts[hi] / pts[lo], 3),
+            "n_points": len(pts),
+            "regime": regime(alpha),
+            "points": pts,
+        }
+    return report or None

sql_benchmarks/utils/schema.py

@@ -0,0 +1,118 @@
+from pydantic import BaseModel, ConfigDict
+from typing import List, Dict, Optional, Union, Any
+import warnings
+
+# Temporarily silence Dagster's Pydantic V2 Deprecation Warning
+# Since this file is now fully V2, this filter might be unnecessary, 
+# but it's kept here in case the test runner needs it.
+warnings.filterwarnings(
+    "ignore", 
+    category=DeprecationWarning, 
+    message="Support for class-based `config` is deprecated"
+)
+
+# ==========================================
+# 1. TABLE & COLUMN DEFINITIONS (Synthetic)
+# ==========================================
+class ColumnDef(BaseModel):
+    name: str
+    provider: str  # e.g., "sequence", "choice", "foreign_key"
+    
+    # Optional parameters specific to providers
+    options: Optional[List[Any]] = None
+    weights: Optional[List[float]] = None
+    target_table: Optional[str] = None
+    target_column: Optional[str] = None
+    min_value: Optional[Union[int, float]] = None
+    max_value: Optional[Union[int, float]] = None
+    
+    # Nullability Control
+    null_probability: Union[float, str] = 0.0  # Default 0.0 (No NULLs)
+    
+    # Type override for DB DDL (e.g., "double precision")
+    type: Optional[str] = None
+    
+    model_config = ConfigDict(extra='allow')
+
+class IndexDef(BaseModel):
+    columns: List[str]
+    name: Optional[str] = None
+    unique: bool = False
+    method: str = "btree"
+
+class TableDef(BaseModel):
+    # 'rows' can be an integer literal OR a variable name reference (string)
+    rows: Optional[Union[int, str]] = None 
+    columns: Optional[List[ColumnDef]] = None
+    indexes: Optional[List[IndexDef]] = []
+    
+    # --- V2 MIGRATION: Replaces class Config: extra = 'allow' ---
+    model_config = ConfigDict(extra='allow')
+
+# ==========================================
+# 2. DATASET CONFIGURATION (Polymorphic)
+# ==========================================
+class DatasetConfig(BaseModel):
+    model_config = ConfigDict(extra='allow')
+    source: Optional[str] = None
+    tables: Optional[Dict[str, Any]] = None
+    paths: Optional[Dict[str, str]] = None
+    # Base seed for synthetic data generation (declarative_gen). Default 42.
+    # The config is hashed, so changing the seed changes the Experiment ID —
+    # two experiments with different data can never share an identity.
+    seed: Optional[int] = None
+
+# ==========================================
+# 3. EXECUTION CONFIGURATION (The Matrix)
+# ==========================================
+class ExecutionConfig(BaseModel):
+    model_config = ConfigDict(extra='allow')
+
+    engines: List[str]
+
+    # Optional
+    test_suite: Optional[str] = None
+    replication: int = 1
+
+    # Per-engine tuning, namespaced by engine name. Each engine receives ONLY
+    # its own namespace at run time and owns the vocabulary inside it.
+    # Reserved namespaces: postgres, duckdb, actian, typedb, quack.
+    #   engine_params:
+    #     postgres: {work_mem: "64MB", random_page_cost: 1.1}
+    #     duckdb:   {memory_limit: "1GB", threads: 4}
+    # To VARY an engine param across partitions, declare it as a namespaced
+    # matrix dimension instead:  matrix: {postgres.work_mem: [4MB, 1GB]}
+    engine_params: Optional[Dict[str, Dict[str, Any]]] = None
+
+    # The Matrix (can be named matrix or dimensions)
+    matrix: Optional[Dict[str, List[Any]]] = None
+    dimensions: Optional[Dict[str, List[Any]]] = None
+
+# ==========================================
+# 4. ROOT CONFIGURATION
+# ==========================================
+class MetaInfo(BaseModel):
+    # --- V2 MIGRATION: Replaces class Config: extra = 'allow' ---
+    model_config = ConfigDict(extra='allow')
+    # experiment_id is computed by the system (SHA-256 hash). Never set manually.
+    name: Optional[str] = None         # Short human-readable identifier, e.g. "Sort Spill Cliff"
+    description: Optional[str] = None  # Prose description of the hypothesis being tested
+
+class ExperimentSchema(BaseModel):
+    meta: Optional[Dict[str, Optional[str]]] = None
+    dataset: Optional[DatasetConfig] = None
+    execution: Optional[ExecutionConfig] = None
+
+# ==========================================
+# 5. PUBLIC INTERFACE
+# ==========================================
+def validate_yaml_content(config_dict: dict) -> ExperimentSchema:
+    """
+    Validates a raw dictionary against the V7 Schema.
+    Raises pydantic.ValidationError if the contract is violated.
+    """
+    return ExperimentSchema(**config_dict)
+
+def get_json_schema():
+    """Returns the JSON Schema for Agents/LLMs."""
+    return ExperimentSchema.model_json_schema()

sql_benchmarks/utils/semantic_auditor.py

@@ -0,0 +1,81 @@
+import os
+import json
+import pandas as pd
+from typing import List, Dict, Any
+
+class OntologyRegistry:
+    """
+    Placeholder for Proof-of-Concept. 
+    In the future, this would be a full business logic engine.
+    """
+    def __init__(self):
+        # Example constraints
+        self.constraints = {
+            "total_count": {"min": 0},
+            "avg_value": {"min": 0}
+        }
+
+    def validate_row(self, row: Dict[str, Any]) -> List[str]:
+        violations = []
+        for key, val in row.items():
+            if key in self.constraints:
+                limit = self.constraints[key].get("min")
+                if limit is not None and val < limit:
+                    violations.append(f"Value {val} for {key} is below minimum {limit}")
+        return violations
+
+class SemanticAuditor:
+    """
+    Audits result sets for semantic hallucinations or business logic violations.
+    """
+    def __init__(self):
+        self.registry = OntologyRegistry()
+
+    def audit_csv(self, csv_path: str) -> Dict[str, Any]:
+        """
+        Reads a CSV and checks for violations.
+        """
+        if not os.path.exists(csv_path):
+            return {"success": False, "error": f"File not found: {csv_path}"}
+
+        try:
+            df = pd.read_csv(csv_path)
+        except Exception as e:
+            return {"success": False, "error": f"Failed to read CSV: {e}"}
+
+        all_violations = []
+        for idx, row in df.iterrows():
+            row_violations = self.registry.validate_row(row.to_dict())
+            if row_violations:
+                all_violations.append({
+                    "row_index": idx,
+                    "violations": row_violations
+                })
+
+        return {
+            "success": len(all_violations) == 0,
+            "violations": all_violations,
+            "row_count": len(df)
+        }
+
+    def audit_fragment(self, fragment_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Audits a single benchmark result fragment (JSON).
+        """
+        metrics = fragment_data.get("metrics", {})
+        parameters = fragment_data.get("parameters", {})
+        
+        # Flatten metrics and parameters for validation
+        flat_data = {**metrics, **parameters}
+        
+        violations = self.registry.validate_row(flat_data)
+        
+        # Additional logic: Timing hallucinations
+        duration = metrics.get("duration_seconds")
+        if duration is not None and duration < 0:
+            violations.append(f"Negative duration detected: {duration}")
+            
+        return {
+            "success": len(violations) == 0,
+            "violations": violations
+        }

sql_benchmarks/utils/system.py

@@ -0,0 +1,100 @@
+import os
+import mmap
+import platform
+import sys
+import psutil
+import logging
+
+# Use the dagster logger so these events show up in the UI
+logger = logging.getLogger("dagster")
+
+
+def capture_environment() -> dict:
+    """
+    Records the runtime CONDITIONS of an experiment for the result capsule.
+
+    The Experiment ID fingerprints the question (config + SQL + code); this
+    block records the lab bench it was answered on. Same ID on different
+    hardware or engine versions = same question, distinct observation.
+    """
+    import duckdb
+    import dagster
+
+    env = {
+        "python": platform.python_version(),
+        "duckdb": duckdb.__version__,
+        "dagster": dagster.__version__,
+        "os": f"{platform.system()} {platform.release()}",
+        "machine": platform.machine(),
+        "cpu_count_logical": psutil.cpu_count(logical=True),
+        "cpu_count_physical": psutil.cpu_count(logical=False),
+        "ram_total_gb": round(psutil.virtual_memory().total / (1024 ** 3), 1),
+    }
+    try:
+        import polars
+        env["polars"] = polars.__version__
+    except ImportError:
+        pass
+    return env
+
+
+def generator_id() -> str:
+    """
+    The capsule's maker's mark + the exact code revision that produced it —
+    a SLSA-style 'builder' identity. Stamped into every capsule's metadata so
+    each artifact says which tool, at which build, generated it.
+    Falls back to the bare slug outside a git checkout.
+    """
+    import subprocess
+    from ..constants import LAB_SLUG, ROOT_DIR
+    try:
+        sha = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=ROOT_DIR, capture_output=True, text=True, timeout=5,
+        ).stdout.strip()
+        return f"{LAB_SLUG}@{sha}" if sha else LAB_SLUG
+    except Exception:
+        return LAB_SLUG
+
+def thrash_os_cache(override_gb=None):
+    """
+    Forces OS Page Cache eviction by writing to a memory-mapped file 
+    larger than available RAM.
+    
+    Args:
+        override_gb (float): Optional. Force a specific flood size. 
+                             If None, auto-detects Total RAM + 20%.
+    """
+    try:
+        # 1. AUTO-DETECT RAM (Safety First)
+        if os.getenv("SB_SILICON_SAFE") == "1":
+            target_gb = 0.1 # Minimal thrash for flow verification
+            log_msg = "SILICON SAFE MODE: Minimal Cache Thrash (100MB)"
+        elif override_gb:
+            target_gb = float(override_gb)
+            log_msg = f"Manual Flood: {target_gb} GB"
+        else:
+            # We use 'available' memory to stay within system limits
+            available_gb = psutil.virtual_memory().available / (1024 ** 3)
+            # Cap at 50% of available OR 4GB, whichever is smaller
+            target_gb = min(available_gb * 0.5, 4.0)
+            log_msg = f"Auto-Flood: {target_gb:.2f} GB (Available: {available_gb:.2f} GB)"
+
+        logger.info(log_msg)
+
+        # 2. FAST FLOOD (MMAP)
+        if target_gb <= 0: return # Skip if negative or zero
+
+        size_bytes = int(target_gb * 1024 * 1024 * 1024)
+        
+        # Anonymous map (-1) and context manager to ensure it closes
+        with mmap.mmap(-1, size_bytes) as mm:
+            page_size = 4096            
+            # Dirty the pages (Stride to be faster and less intensive)
+            for i in range(0, size_bytes, page_size * 4):
+                mm[i] = 1
+            
+        logger.info("OS Cache Thrashed.")
+        
+    except Exception as e:
+        logger.warning(f"Cache thrash failed: {e}")

sql_benchmarks/validator.py

@@ -0,0 +1,60 @@
+import os
+from .utils.schema import validate_yaml_content
+from .utils.semantic_auditor import OntologyRegistry
+
+class ExperimentValidator:
+    """
+    Ensures the experiment "Contract" is strictly valid before any execution.
+    Combines Pydantic schema validation with business logic rules.
+    """
+    
+    @staticmethod
+    def validate(config_dict: dict, source_label: str = "config"):
+        # 1. Structural & Static Schema Validation
+        try:
+            validate_yaml_content(config_dict)
+        except Exception as e:
+            raise ValueError(f"SCHEMA ERROR in {source_label}:\n{e}")
+
+        # 2. Logic & Ontology Validation
+        execution = config_dict.get("execution", {})
+        matrix = execution.get("matrix") or execution.get("dimensions") or {}
+        
+        # A. Matrix Validation (Numeric constraints)
+        if "rows" in matrix:
+            for r in matrix["rows"]:
+                if isinstance(r, (int, float)) and r < 0:
+                    raise ValueError(f"Negative value {r} not allowed in 'rows'")
+        
+        if "selectivity" in matrix:
+            for s in matrix["selectivity"]:
+                if isinstance(s, (int, float)) and (s < 0 or s > 1):
+                    raise ValueError(f"Selectivity {s} for 'selectivity' must be between 0 and 1")
+
+        dataset = config_dict.get("dataset", {})
+        tables = dataset.get("tables", {})
+        
+        if isinstance(tables, dict):
+            # B. Stats Validation (Weights)
+            for table_name, table_def in tables.items():
+                if not isinstance(table_def, dict): continue
+                for col in table_def.get("columns", []):
+                    if "weights" in col:
+                        weights = col["weights"]
+                        if any(w < 0 for w in weights):
+                            raise ValueError(f"LOGIC ERROR: Negative weight in {table_name}.{col['name']}")
+                        if sum(weights) <= 0:
+                            raise ValueError(f"LOGIC ERROR: Weights sum to zero or less in {table_name}.{col['name']}")
+
+            # C. Integrity Validation (Foreign Keys)
+            defined_tables = set(tables.keys())
+            for table_name, table_def in tables.items():
+                if not isinstance(table_def, dict): continue
+                for col in table_def.get("columns", []):
+                    if col.get("provider") == "foreign_key":
+                        target = col.get("target_table")
+                        if target not in defined_tables:
+                             raise ValueError(f"Broken FK in '{table_name}.{col['name']}'. Target table '{target}' not defined")
+
+        print(f"[SUCCESS] Contract '{source_label}' validated.")
+        return True