Diagnostic connection probe — surface Iceberg metadata to caller

[gordonmurray]

Closes #26.

Before

/api/connect/test returned a binary success/failure with the path echoed back:

{"status":"success","tableInfo":{"path":"s3://...","suggestedQuery":"SELECT * ..."}}

The probe internally read version-hint.text and iceberg_metadata() but discarded the results, so the UI had nothing to show beyond a green tick. A user with a typo in their path got a silent success (if the bucket existed) and no confidence signal.

After

{
  "status": "success",
  "tableInfo": {
    "path": "s3://movies/warehouse/demo/movies",
    "suggestedQuery": "SELECT * FROM iceberg_scan('s3://movies/warehouse/demo/movies') LIMIT 10",
    "format": "iceberg-v2",
    "rows": 37537,
    "files": 1,
    "hasDeletes": false,
    "snapshotId": "6450139374914496971",
    "lastSnapshotAt": "2026-04-15T19:02:46.193000Z"
  }
}

Frontend renders this as a labelled grid under the Connection panel: "Format iceberg-v2, Rows 37,537, Files 1, Last snapshot 2h ago" — turning a silent probe into real onboarding signal. A table with deletes is flagged in red.

How the probe works

Two sub-probes, at least one must succeed:

1. Metadata JSON — SELECT content FROM read_text('<path>/metadata/*.metadata.json') ORDER BY filename DESC LIMIT 1. The glob handles both pyiceberg's NNNNN-<uuid>.metadata.json and Spark's vN.metadata.json naming. Parsed for format-version, current-snapshot-id, last-updated-ms.
2. iceberg_metadata() — aggregate SUM(record_count), COUNT(*), BOOL_OR(manifest_content <> 'DATA') for rows / files / deletes.

If both fail, the whole probe fails → run_connection_test returns None → route returns 400. If one fails but the other succeeds, the response just has fewer fields populated.

Design notes

• version-hint.text isn't written by pyiceberg, so we don't rely on it. The previous implementation's attempt was effectively dead code.
• snapshotId is stringified — Iceberg snapshot IDs are 64-bit and would suffer JS Number precision loss as integers on the wire.
• run_connection_test now returns Optional[TableInfo] (breaking change to its Python signature; only caller updated). Route still returns a 400 on None.

Verified

• pytest backend/tests/ — 5 new tests for the probe behaviour; 41/42 pass (the 1 failure is the intentionally-red test_metrics.py driving feat(metrics): replace placeholder bytesScanned with real DuckDB profile #25, unrelated to this PR).
• ruff check clean.
• End-to-end via docker compose up --build:

Happy path  — 200, full tableInfo populated
Invalid path — 400 Connection test failed
Wrong credentials — 400 Connection test failed
Demo (no tablePath) — 200, full tableInfo from the bundled Iceberg table
Query endpoint — still returns 37,537 rows (no regression)

• Frontend's renderTableInfo exercised in a headless Node harness against the real API payload; HTML output verified for happy / deletes / null cases.