Add CachingReader binding (stacked on #9)

[cpsievert]

Summary

Exposes upstream ggsql 0.5.2's CachingReader to Python as ggsql.CachingReader. Source reads hit the primary reader (memoized with TTL + LRU byte budget); all ggsql-generated derived SQL (__ggsql_* tables) runs on a private in-memory DuckDB cache.

reader = ggsql.CachingReader("duckdb://memory", ttl_secs=60)
# or wrap any Python object with the bridge protocol
# (execute_sql / register / unregister) — the querychat path
reader = ggsql.CachingReader(my_reader)
spec = reader.execute("SELECT ... VISUALISE ...")

• Primary accepts a duckdb:// connection string (built fresh internally) or a bridged Python reader; passing an existing DuckDBReader instance errors with guidance.
• Config from GGSQL_CACHE_DISABLED / GGSQL_CACHE_TTL / GGSQL_CACHE_MAX_BYTES, keyword args take precedence.
• No GIL release in execute (bridged primaries call back into Python — same stance as DuckDBReader).

Why: querychat currently rejects ggsql queries with layer-level sources and re-runs identical base reads on every LLM tool call. test_layer_level_source_through_bridge demonstrates VISUALISE ... FROM <table> running end-to-end through a bridged primary — the capability querychat's _viz_ggsql.py names as its long-term fix.

Benchmark evidence (merge gate)

Benchmark: simulated LLM-style viz session — 9 tool calls sharing one identical base read over a 3M-row DataFrameSource (iterative chart refinement), 1 exact repeat, 1 multi-relation query. Old path = querychat's hand-rolled split (_viz_ggsql.py @ querychat 40f328e4); new path = whole-query execution through CachingReader wrapping the querychat executor — see draft PR posit-dev/querychat#321 for the integration.

call	old (s)	new (s)
1	4.839	5.107
2	5.909	3.576
3	7.512	5.322
4	5.335	2.979
5	4.459	2.195
6	5.947	3.684
7	5.256	2.981
8	5.922	3.623
9	5.896	3.647
multi-relation	unsupported	3.582s
total (calls 1–9)	51.075	33.113

Source reads during calls 1–9 (one shared base read): old = 9, new = 1. The multi-relation call adds 2 more on the new path (base + layer source); the old path rejects such queries outright.

Takeaways:

• 9× fewer source reads for iterative chart refinement — the LLM loop's dominant pattern.
• ~35% wall-time reduction overall, with no cold-path regression (call 1: 5.1s vs 4.8s — small cache-staging overhead).
• Remaining per-call cost is data movement + Vega-Lite rendering of the ~1.5M-row result, not the source read.
• Capability unlock: DRAW ... FROM <table> (multi-relation) queries now work end-to-end through the bridged executor.

Environment: ggsql 0.5.2 (this branch), M-series arm64, Python 3.12. Two consecutive runs produced near-identical numbers. Repro: .venv/bin/python _dev/ggsql-caching-benchmark/bench.py on querychat branch ggsql-caching-reader (posit-dev/querychat#321).

Stacking

Stacked on #9 (ggsql-0.5.2-upgrade); base retargets to main after #9 merges. Design spec and implementation plan live locally in docs/superpowers/ (gitignored).

Test plan

• 15 new tests: constructor dispatch, memoization hit/miss, TTL expiry, enabled=False + env-var disable, layer-level source through bridged primary, cache-resident routing, top-level execute fast path, package export
• Full suite: 121 passed, 5 skipped; cargo fmt --check and cargo clippy -- -D warnings clean