rowproof 0.1.0__py3-none-any.whl

rowproof/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

rowproof/cli/main.py

@@ -0,0 +1,548 @@
+"""rowproof CLI — argparse stand-in for `typer` (see docs/DEV_ENVIRONMENT.md).
+Flags, behavior and exit codes follow spec §7 exactly; only the argument
+*parsing library* differs from the spec's chosen stack.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+import traceback
+
+import rowproof
+from rowproof.cli.render import render_json, render_terminal
+from rowproof.cli.spec import parse_source_spec, resolve_source_spec
+from rowproof.config import load_config
+from rowproof.connectors.clickhouse import ClickHouseConnector
+from rowproof.connectors.postgres import PostgresConnector
+from rowproof.core.errors import RowProofError
+from rowproof.core.hashdiff import diff as run_hashdiff
+from rowproof.core.hashdiff import explain as run_explain
+from rowproof.core.joindiff import diff as run_joindiff
+from rowproof.report.html import render_html
+
+EXIT_MATCH = 0
+EXIT_DIFFERENT = 1
+EXIT_COULD_NOT_COMPARE = 2
+
+# M4 hardening: "Connection retry (3 attempts, backoff) on transient
+# failures; clean exit 2 after." Each connector's own wire module
+# (_pgwire/_chwire/_sfwire) raises its own ConnectionFailedError type for
+# both a genuinely transient failure (network blip, DNS hiccup, timeout)
+# and a permanent one (bad credentials, unknown database) alike -- there's
+# no cheap, reliable way from here to tell those apart without engine-
+# specific error-code inspection, so every connect() failure gets the same
+# short retry rather than none at all. Backoff is deliberately small
+# (0.5s, 1s) so a genuinely permanent failure like a bad password doesn't
+# feel sluggish -- worst case adds ~1.5s before the clean one-line error.
+_CONNECT_RETRY_ATTEMPTS = 3
+_CONNECT_RETRY_BACKOFF_SECONDS = 0.5
+
+
+def _connect_with_retry(connector, dsn: str) -> None:
+    last_error: Exception | None = None
+    for attempt in range(1, _CONNECT_RETRY_ATTEMPTS + 1):
+        try:
+            connector.connect(dsn)
+            return
+        except Exception as e:  # noqa: BLE001 - retried uniformly, see module note above
+            last_error = e
+            if attempt < _CONNECT_RETRY_ATTEMPTS:
+                time.sleep(_CONNECT_RETRY_BACKOFF_SECONDS * attempt)
+    raise last_error  # noqa: RSE102 - last_error is always set: the loop only exits this way after >=1 failed attempt
+
+
+def _report_error(e: Exception, verbose: bool, prefix: str = "error") -> None:
+    """spec §10 + M4: "Every error path produces a one-line human message;
+    traceback only under --verbose." The one-liner always goes to stderr;
+    the traceback (when requested) is appended after it, never instead of
+    it, so a --verbose run is strictly more informative, not different.
+    """
+    print(f"{prefix}: {e}", file=sys.stderr)
+    if verbose:
+        traceback.print_exc()
+
+def _snowflake_factory():
+    # Imported lazily, not at module scope like Postgres/ClickHouse above
+    # — spec §3/§9: Snowflake support is an optional extra
+    # (`rowproof[snowflake]`) precisely because its driver is a "heavy
+    # dependency" a Postgres/ClickHouse-only install shouldn't be forced
+    # to carry. An eager top-level import would defeat that: it'd make
+    # `snowflake-connector-python` a hard dependency of the whole CLI,
+    # breaking every command for a user who installed the base package.
+    try:
+        from rowproof.connectors.snowflake import SnowflakeConnector
+    except ImportError as e:
+        raise RowProofError(
+            "Snowflake support requires the optional extra -- install with "
+            "`pip install rowproof[snowflake]` (or `pipx install rowproof[snowflake]`)"
+        ) from e
+    return SnowflakeConnector()
+
+
+_CONNECTOR_FACTORIES = {
+    "postgres": PostgresConnector,
+    "postgresql": PostgresConnector,
+    "clickhouse": ClickHouseConnector,
+    "ch": ClickHouseConnector,
+    "snowflake": _snowflake_factory,
+    "sf": _snowflake_factory,
+}
+
+
+def _make_connector(engine: str, verbose: bool):
+    factory = _CONNECTOR_FACTORIES.get(engine)
+    if factory is None:
+        supported = ", ".join(sorted(set(_CONNECTOR_FACTORIES) - {"postgresql", "ch", "sf"}))
+        raise RowProofError(f"unsupported engine '{engine}' (supported: {supported})")
+    connector = factory()
+    if verbose and hasattr(connector, "on_query"):
+        connector.on_query = lambda sql: print(f"[sql] {sql}", file=sys.stderr)
+    return connector
+
+
+def _parse_sample_pct(value: str) -> float:
+    """spec §7: `--sample 1%` (the `%` is optional -- `--sample 1` means
+    the same thing)."""
+    text = value.strip().rstrip("%").strip()
+    try:
+        pct = float(text)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(f"--sample expects a percentage like '1%%', got {value!r}") from e
+    if not (0 < pct <= 100):
+        raise argparse.ArgumentTypeError(f"--sample must be between 0 and 100, got {value!r}")
+    return pct
+
+
+def _split_cols(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [c.strip() for c in value.split(",") if c.strip()]
+
+
+def _parse_column_map(value: str | None) -> dict | None:
+    """spec §7: `--column-map a:b,c:d`."""
+    if not value:
+        return None
+    result = {}
+    for pair in value.split(","):
+        pair = pair.strip()
+        if not pair:
+            continue
+        src, _, tgt = pair.partition(":")
+        result[src.strip()] = tgt.strip()
+    return result or None
+
+
+def _connect_pair(args, sql_log: list[str] | None = None):
+    src_spec = parse_source_spec(args.source)
+    tgt_spec = parse_source_spec(args.target)
+    source = _make_connector(src_spec.engine, args.verbose)
+    target = _make_connector(tgt_spec.engine, args.verbose)
+    if sql_log is not None:
+        for connector in (source, target):
+            if hasattr(connector, "on_query"):
+                previous = connector.on_query
+                # spec §8.2: JSON output carries every generated SQL
+                # statement too — reuse the exact same on_query hook
+                # --verbose already installs (chaining onto it, so
+                # --verbose logging to stderr keeps working unchanged)
+                # rather than a second SQL-capturing mechanism.
+                connector.on_query = (
+                    lambda sql, _prev=previous: (_prev(sql) if _prev else None, sql_log.append(sql))
+                )
+    _connect_with_retry(source, src_spec.connect_dsn)
+    _connect_with_retry(target, tgt_spec.connect_dsn)
+
+    # spec §7: `--threads N` — extra, already-connected connectors per
+    # side for core.hashdiff's parallel segment path (see its own
+    # docstring on why genuine parallelism needs genuine extra
+    # connections, and why this is still "one [fixed] connection per
+    # side" in spirit, not a general pool). `explain` never sets
+    # --threads, and `getattr` covers that instead of giving every
+    # subcommand's argparser a `--threads` flag it doesn't use.
+    threads = getattr(args, "threads", 1)
+    source_pool: list = []
+    target_pool: list = []
+    if threads > 1:
+        source_pool = [_make_connector(src_spec.engine, args.verbose) for _ in range(threads)]
+        target_pool = [_make_connector(tgt_spec.engine, args.verbose) for _ in range(threads)]
+        for connector in source_pool:
+            _connect_with_retry(connector, src_spec.connect_dsn)
+        for connector in target_pool:
+            _connect_with_retry(connector, tgt_spec.connect_dsn)
+
+    return source, target, src_spec.table_ref, tgt_spec.table_ref, source_pool, target_pool
+
+
+def resolve_algorithm(requested: str, args) -> str:
+    """spec §4.2: "Use [joindiff] automatically when both sides resolve to
+    the same connection; force with --algorithm joindiff." "same
+    connection" is decided from the parsed DSN (engine + host/port/user/
+    database), not from table identity — two different tables in the same
+    database is exactly the case joindiff is for.
+    """
+    if requested != "auto":
+        return requested
+    src_spec = parse_source_spec(args.source)
+    tgt_spec = parse_source_spec(args.target)
+    if src_spec.engine == tgt_spec.engine and src_spec.connect_dsn == tgt_spec.connect_dsn:
+        return "joindiff"
+    return "hashdiff"
+
+
+def _normalise_kwargs(args) -> dict:
+    return dict(
+        trim=args.trim,
+        case_insensitive=args.case_insensitive,
+        float_precision=args.float_precision,
+        assume_tz=args.assume_tz,
+        column_map=_parse_column_map(args.column_map),
+    )
+
+
+def cmd_diff(args) -> int:
+    source = target = None
+    source_pool: list = []
+    target_pool: list = []
+    try:
+        sql_log: list[str] = []
+        source, target, source_ref, target_ref, source_pool, target_pool = _connect_pair(args, sql_log)
+        key_columns = _split_cols(args.key)
+        columns = _split_cols(args.columns)
+        exclude = _split_cols(args.exclude)
+        algorithm = resolve_algorithm(args.algorithm, args)
+        sample = getattr(args, "sample", None)
+        sample_rows = getattr(args, "sample_rows", None)
+
+        if algorithm == "joindiff":
+            if sample is not None or sample_rows is not None:
+                # spec §4.3: "apply the same sampling predicate to both
+                # sides ... then run hashdiff on the sample" -- sampling
+                # is defined in terms of hashdiff's segmented approach,
+                # not joindiff's single exact query; --algorithm auto
+                # would have picked hashdiff already for two different
+                # connections, so this only fires when the user forced
+                # joindiff (or both sides really are the same connection)
+                # while also asking to sample -- a clear error beats
+                # silently ignoring the flag.
+                raise RowProofError(
+                    "--sample/--sample-rows requires hashdiff (spec §4.3) -- "
+                    "pass --algorithm hashdiff, or diff two different connections "
+                    "so hashdiff is auto-selected"
+                )
+            result = run_joindiff(
+                source, target, source_ref, target_ref,
+                key_columns=key_columns, columns=columns, exclude=exclude,
+                max_diff_rows=args.max_diff_rows,
+                where=args.where, where_source=args.where_source, where_target=args.where_target,
+                **_normalise_kwargs(args),
+            )
+        else:
+            result = run_hashdiff(
+                source,
+                target,
+                source_ref,
+                target_ref,
+                key_columns=key_columns,
+                columns=columns,
+                exclude=exclude,
+                row_threshold=args.row_threshold,
+                max_diff_rows=args.max_diff_rows,
+                where=args.where,
+                where_source=args.where_source,
+                where_target=args.where_target,
+                threads=args.threads,
+                source_pool=source_pool,
+                target_pool=target_pool,
+                sample=sample,
+                sample_rows=sample_rows,
+                **_normalise_kwargs(args),
+            )
+
+        outputs = args.output or ["terminal"]
+        for fmt in outputs:
+            if fmt == "terminal":
+                print(render_terminal(result))
+            elif fmt == "json":
+                text = render_json(result, sql_statements=sql_log)
+                if args.json_path:
+                    with open(args.json_path, "w") as f:
+                        f.write(text)
+                else:
+                    print(text)
+            elif fmt == "html":
+                # spec §8.3: DSNs shown in the report must be redacted --
+                # render_html does that itself (via cli.spec.redact_dsn),
+                # so the *raw* connect_dsn is passed through here, same as
+                # what actually connected (re-parsed rather than plumbed
+                # out of _connect_pair, since parse_source_spec is pure
+                # and cheap, and no other caller needs the DSN back).
+                html_text = render_html(
+                    result,
+                    source_dsn=parse_source_spec(args.source).connect_dsn,
+                    target_dsn=parse_source_spec(args.target).connect_dsn,
+                    sql_statements=sql_log,
+                )
+                if not args.html_path:
+                    raise RowProofError("--output html requires --html-path PATH")
+                with open(args.html_path, "w", encoding="utf-8") as f:
+                    f.write(html_text)
+
+        if args.fail_on == "none":
+            return EXIT_MATCH
+        if args.fail_on == "count":
+            return EXIT_MATCH if result.source_count == result.target_count else EXIT_DIFFERENT
+        return result.exit_code()
+
+    except RowProofError as e:
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+    except Exception as e:  # noqa: BLE001 - CLI boundary: never leak an unhandled traceback
+        # NOTE: this used to re-raise when --verbose was set, meaning to
+        # show a traceback for debugging. That was wrong: re-raising here
+        # doesn't add a traceback to a clean report, it crashes the process
+        # — Python's own unhandled-exception handler then prints the
+        # traceback AND exits with status 1, not 2. A real network-kill
+        # test (tests/integration/test_m0_acceptance.py) caught this doing
+        # exactly that. Spec §13 M0's "kill network mid-run" bullet requires
+        # exit 2 UNCONDITIONALLY, --verbose or not -- `_report_error` always
+        # returns normally (never raises), printing the one-line message
+        # unconditionally and the traceback ONLY when --verbose is set
+        # (M4: "traceback only under --verbose"), so exit 2 below always
+        # still happens either way.
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+    finally:
+        if source is not None:
+            source.close()
+        if target is not None:
+            target.close()
+        for connector in (*source_pool, *target_pool):
+            connector.close()
+
+
+def cmd_explain(args) -> int:
+    source = target = None
+    try:
+        source, target, source_ref, target_ref, _source_pool, _target_pool = _connect_pair(args)
+        key_columns = _split_cols(args.key)
+        columns = _split_cols(args.columns)
+        exclude = _split_cols(args.exclude)
+        statements = run_explain(
+            source, target, source_ref, target_ref,
+            key_columns=key_columns, columns=columns, exclude=exclude,
+            where=args.where, where_source=args.where_source, where_target=args.where_target,
+            **_normalise_kwargs(args),
+        )
+        for stmt in statements:
+            print(stmt)
+        return EXIT_MATCH
+    except RowProofError as e:
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+    except Exception as e:  # noqa: BLE001
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+    finally:
+        if source is not None:
+            source.close()
+        if target is not None:
+            target.close()
+
+
+def _run_one_job(job, connections: dict, verbose: bool) -> int:
+    """One table pair from a `run` config — spec §7: "run many table
+    pairs; one report." Each job prints its own terminal block (so the
+    "one report" is the concatenation, in config order) and the run's
+    overall exit code is the worst of every job's own (spec's exit-code
+    semantics — 0 match / 1 different / 2 could-not-compare — apply the
+    same way per table; "worst" means 2 beats 1 beats 0, the same
+    ordering the exit codes already have).
+    """
+    source = target = None
+    try:
+        src_spec = resolve_source_spec(job.source, connections)
+        tgt_spec = resolve_source_spec(job.target, connections)
+        source = _make_connector(src_spec.engine, verbose)
+        target = _make_connector(tgt_spec.engine, verbose)
+        _connect_with_retry(source, src_spec.connect_dsn)
+        _connect_with_retry(target, tgt_spec.connect_dsn)
+
+        algorithm = job.algorithm
+        if algorithm == "auto":
+            algorithm = (
+                "joindiff"
+                if src_spec.engine == tgt_spec.engine and src_spec.connect_dsn == tgt_spec.connect_dsn
+                else "hashdiff"
+            )
+
+        shared_kwargs = dict(
+            key_columns=job.key, columns=job.columns, exclude=job.exclude,
+            where=job.where, where_source=job.where_source, where_target=job.where_target,
+            trim=job.trim, case_insensitive=job.case_insensitive,
+            float_precision=job.float_precision, assume_tz=job.assume_tz, column_map=job.column_map,
+        )
+        if algorithm == "joindiff":
+            result = run_joindiff(
+                source, target, src_spec.table_ref, tgt_spec.table_ref,
+                max_diff_rows=job.max_diff_rows, **shared_kwargs,
+            )
+        else:
+            result = run_hashdiff(
+                source, target, src_spec.table_ref, tgt_spec.table_ref,
+                row_threshold=job.row_threshold, max_diff_rows=job.max_diff_rows, **shared_kwargs,
+            )
+
+        print(render_terminal(result))
+        print()
+        if job.fail_on == "none":
+            return EXIT_MATCH
+        if job.fail_on == "count":
+            return EXIT_MATCH if result.source_count == result.target_count else EXIT_DIFFERENT
+        return result.exit_code()
+    except RowProofError as e:
+        _report_error(e, verbose, prefix=f"error ({job.source} -> {job.target})")
+        return EXIT_COULD_NOT_COMPARE
+    except Exception as e:  # noqa: BLE001 - never leak a traceback (see cmd_diff's note)
+        _report_error(e, verbose, prefix=f"error ({job.source} -> {job.target})")
+        return EXIT_COULD_NOT_COMPARE
+    finally:
+        if source is not None:
+            source.close()
+        if target is not None:
+            target.close()
+
+
+def cmd_run(args) -> int:
+    try:
+        config = load_config(args.config)
+    except RowProofError as e:
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+
+    if not config.tables:
+        print("error: config has no 'tables' entries", file=sys.stderr)
+        return EXIT_COULD_NOT_COMPARE
+
+    worst = EXIT_MATCH
+    for job in config.tables:
+        code = _run_one_job(job, config.connections, args.verbose)
+        worst = max(worst, code)
+    return worst
+
+
+def cmd_connections_test(args) -> int:
+    try:
+        config = load_config(args.config)
+    except RowProofError as e:
+        _report_error(e, args.verbose)
+        return EXIT_COULD_NOT_COMPARE
+
+    if args.name not in config.connections:
+        print(
+            f"error: unknown connection '{args.name}' (known: {', '.join(sorted(config.connections))})",
+            file=sys.stderr,
+        )
+        return EXIT_COULD_NOT_COMPARE
+
+    dsn = config.connections[args.name]
+    engine = dsn.split("://", 1)[0] if "://" in dsn else ""
+    connector = None
+    try:
+        connector = _make_connector(engine, args.verbose)
+        _connect_with_retry(connector, dsn)
+        connector.query("SELECT 1")
+    except RowProofError as e:
+        _report_error(e, args.verbose, prefix=f"error: connection '{args.name}' failed")
+        return EXIT_COULD_NOT_COMPARE
+    except Exception as e:  # noqa: BLE001 - never leak a traceback (see cmd_diff's note)
+        _report_error(e, args.verbose, prefix=f"error: connection '{args.name}' failed")
+        return EXIT_COULD_NOT_COMPARE
+    finally:
+        if connector is not None:
+            connector.close()
+
+    print(f"{args.name}: ok")
+    return EXIT_MATCH
+
+
+def _add_common_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("source")
+    p.add_argument("target")
+    p.add_argument("--key", help="comma-separated key columns (default: detected PK)")
+    p.add_argument("--columns", help="only compare these columns")
+    p.add_argument("--exclude", help="skip these columns")
+    p.add_argument("--where", help="SQL filter applied to both sides before comparing")
+    p.add_argument("--where-source", help="SQL filter for the source side only (overrides --where)")
+    p.add_argument("--where-target", help="SQL filter for the target side only (overrides --where)")
+    p.add_argument("--verbose", action="store_true", help="log every generated SQL statement")
+    p.add_argument("--trim", action="store_true", help="STR-2: strip trailing whitespace before comparing text")
+    p.add_argument("--case-insensitive", action="store_true", help="STR-2: lower-case text before comparing")
+    p.add_argument("--float-precision", type=int, default=15, help="FLT-1: significant digits (default 15)")
+    p.add_argument("--assume-tz", default="UTC", help="TS-3: timezone assumed for naive timestamps (default UTC)")
+    p.add_argument("--column-map", help="rename columns when matching sides: source_col:target_col,...")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="rowproof")
+    parser.add_argument(
+        "--version", action="version", version=f"rowproof {rowproof.__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    diff_p = sub.add_parser("diff", help="verify two tables match")
+    _add_common_args(diff_p)
+    diff_p.add_argument("--algorithm", choices=["auto", "hashdiff", "joindiff"], default="auto")
+    diff_p.add_argument(
+        "--threads", type=int, default=4,
+        help="parallel segment queries per side, hashdiff only (default 4)",
+    )
+    diff_p.add_argument("--row-threshold", type=int, default=1000)
+    diff_p.add_argument("--max-diff-rows", type=int, default=10_000)
+    sample_group = diff_p.add_mutually_exclusive_group()
+    sample_group.add_argument(
+        "--sample", type=_parse_sample_pct, metavar="PCT",
+        help="diff a deterministic sample of rows, e.g. --sample 1%% (spec §4.3)",
+    )
+    sample_group.add_argument(
+        "--sample-rows", type=int, metavar="N",
+        help="diff a deterministic sample of approximately N rows",
+    )
+    diff_p.add_argument("--output", action="append", choices=["terminal", "json", "html"], default=None)
+    diff_p.add_argument("--json-path")
+    diff_p.add_argument("--html-path", help="file to write the HTML sign-off report to (spec §8.3)")
+    diff_p.add_argument("--fail-on", choices=["none", "any", "count"], default="any")
+    diff_p.set_defaults(func=cmd_diff)
+
+    explain_p = sub.add_parser("explain", help="print the SQL rowproof would run; execute nothing")
+    _add_common_args(explain_p)
+    explain_p.set_defaults(func=cmd_explain)
+
+    run_p = sub.add_parser("run", help="run every table pair in a config file; one report")
+    run_p.add_argument("config", help="path to a rowproof YAML config file")
+    run_p.add_argument("--verbose", action="store_true", help="log every generated SQL statement")
+    run_p.set_defaults(func=cmd_run)
+
+    connections_p = sub.add_parser("connections", help="work with a config file's named connections")
+    connections_sub = connections_p.add_subparsers(dest="connections_command", required=True)
+    connections_test_p = connections_sub.add_parser("test", help="check credentials for a named connection")
+    connections_test_p.add_argument("name", help="connection name, as declared in the config file")
+    connections_test_p.add_argument(
+        "--config", default="rowproof.yaml", help="path to a rowproof YAML config file (default: rowproof.yaml)"
+    )
+    connections_test_p.add_argument("--verbose", action="store_true", help="log every generated SQL statement")
+    connections_test_p.set_defaults(func=cmd_connections_test)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rowproof/cli/render.py

@@ -0,0 +1,132 @@
+"""Terminal + JSON rendering — plain-text stand-in for `rich` (see
+docs/DEV_ENVIRONMENT.md). Behavior/content matches spec §8; only the
+"tables and progress bars" styling is simplified.
+"""
+
+from __future__ import annotations
+
+import json
+
+from rowproof.core.models import DiffResult, TableRef
+
+
+def _display(value):
+    """A value as shown in row-level output (terminal and JSON): the
+    NULL-1 canonical string (spec §6.1: "the literal `\\N`") is the
+    internal SQL-comparison marker every normalise_expr wraps a NULL in —
+    exactly what hashing/equality needs it to be — but showing a data
+    engineer a raw `\\N` in a report reads as a mangled value, not a
+    deliberate marker. Row *output* (this function) shows "NULL" instead;
+    the underlying RowDiff/DiffResult model, the hash, and the
+    IS DISTINCT FROM comparison all keep using the real `\\N` string
+    completely unchanged — only this display step ever runs the swap, and
+    only on a value that is exactly the marker, never a substring match.
+    """
+    if value == "\\N":
+        return "NULL"
+    return value
+
+
+def render_terminal(result: DiffResult) -> str:
+    lines = []
+    lines.append(f"{result.source.qualified_name}  {result.source}  ->  {result.target}")
+    if result.sample_pct is not None:
+        # spec §4.3: "Report results as 'of the sampled rows' with the
+        # sample size stated. Never silently sample." — on its own line,
+        # right under the header, so it can't be missed or mistaken for
+        # a full-table result.
+        lines.append(f"  SAMPLED        {result.sample_pct:g}% of rows — counts below are of the sample only")
+    lines.append(f"  rows           {result.source_count:<20} {result.target_count:<20}")
+    lines.append(f"  key            {', '.join(result.key_columns)}")
+    if result.excluded_columns:
+        lines.append(f"  columns        {len(result.excluded_columns)} excluded ({', '.join(result.excluded_columns)})")
+    lines.append(
+        f"  algorithm      {result.algorithm.value} · {result.segments_examined} segments · "
+        f"{result.queries_per_side} queries/side · {result.elapsed_seconds:.1f}s"
+    )
+    lines.append("")
+    lines.append(f"  missing in target   {result.missing_in_target}")
+    lines.append(f"  extra in target     {result.extra_in_target}")
+    lines.append(f"  changed             {result.changed}")
+
+    if result.row_diffs:
+        lines.append("")
+        for rd in result.row_diffs:
+            key_str = ",".join(str(k) for k in rd.key)
+            if rd.kind == "changed":
+                for col, (sv, tv, rule) in rd.changes.items():
+                    rule_note = f"  ({rule.value})" if rule else ""
+                    lines.append(f"    key={key_str}  {col}  {_display(sv)!r} -> {_display(tv)!r}{rule_note}")
+            else:
+                lines.append(f"    key={key_str}  {rd.kind}")
+        if result.truncated:
+            lines.append(f"  ... row list truncated at {len(result.row_diffs)} rows (counts above are exact)")
+
+    for w in result.warnings:
+        lines.append(f"  warning: {w.message}")
+
+    lines.append("")
+    verdict = "MATCH" if result.is_match else "DIFFERENT"
+    lines.append(f"  result   {verdict}   exit {result.exit_code()}")
+    return "\n".join(lines)
+
+
+def render_json(
+    result: DiffResult,
+    sql_statements: list[str] | None = None,
+) -> str:
+    """spec §8.2: "Stable schema, versioned (schema_version: 1). Contains
+    everything in the terminal output plus every generated SQL statement
+    (redacted), timings, and the warnings list."
+
+    `sql_statements` is the caller's own query log (the CLI already wires
+    every connector's `on_query` hook for `--verbose`; JSON output reuses
+    exactly that same hook to collect this list rather than adding a
+    second SQL-capturing mechanism) — SQL text itself never contains
+    connection secrets (those live in the DSN, which no generated
+    statement ever embeds), so "redacted" here is automatically satisfied
+    by construction, not by a separate scrub step.
+    """
+
+    def default(o):
+        if hasattr(o, "value"):  # Enum
+            return o.value
+        if isinstance(o, TableRef):
+            return {"engine": o.engine, "database": o.database, "schema": o.schema, "table": o.table}
+        raise TypeError(f"not JSON serialisable: {o!r}")
+
+    payload = {
+        "schema_version": 1,
+        "tool": "rowproof",
+        "source": result.source,
+        "target": result.target,
+        "key_columns": list(result.key_columns),
+        "algorithm": result.algorithm,
+        "sample_pct": result.sample_pct,
+        "source_count": result.source_count,
+        "target_count": result.target_count,
+        "missing_in_target": result.missing_in_target,
+        "extra_in_target": result.extra_in_target,
+        "changed": result.changed,
+        "truncated": result.truncated,
+        "is_match": result.is_match,
+        "exit_code": result.exit_code(),
+        "excluded_columns": list(result.excluded_columns),
+        "segments_examined": result.segments_examined,
+        "queries_per_side": result.queries_per_side,
+        "timings": {"total_seconds": round(result.elapsed_seconds, 3)},
+        "sql_statements": list(sql_statements or []),
+        "warnings": [w.message for w in result.warnings],
+        "row_diffs": [
+            {
+                "key": list(rd.key),
+                "kind": rd.kind,
+                "changes": {
+                    col: {"source": _display(sv), "target": _display(tv), "rule": rule.value if rule else None}
+                    for col, (sv, tv, rule) in rd.changes.items()
+                },
+            }
+            for rd in result.row_diffs
+        ],
+    }
+    return json.dumps(payload, default=default, indent=2)