PR3: HybridReader query-result cache + clear_cache trait + @uncache + dual VL mime

[jimhester]

Draft — stacked on posit-dev/ggsql#423 (HybridReader). This PR lives in my fork (jimhester/ggsql) with base = pr2-hybrid-reader so the diff shows only the cache work on top of PR2. Opened in draft per posit-dev/ggsql#423 (comment) so the proposed staging-layer design can be informed by the concrete caching mechanism here. When PR2 merges to posit-dev/ggsql:main, I'll rebase and re-target this PR (or re-open it) against upstream.

Summary

Bundles four follow-ups to PR2 (HybridReader):

1. Query-result cache for HybridReader — memoizes (reader_uri, sql) results in the staging DuckDB so visualization iteration
   (tweak DRAW, change a SCALE, re-run) is sub-millisecond on
   cache hits instead of round-tripping to the primary reader.
2. Reader::clear_cache() trait method — default Ok(()) so
   readers without a cache (DuckDB, SQLite, ODBC, ADBC) inherit a
   no-op; HybridReader overrides to drop its cache tables.
3. Jupyter -- @uncache meta-command — clears the active reader's
   cache from inside a notebook cell without restarting the kernel.
4. Dual Vega-Lite v5 + v6 mime emission in the Jupyter kernel —
   JupyterLab 4.x (built-in v5 renderer) and nteract / newer
   Lab extensions (v6) both display natively without the embedded
   HTML fallback.

Each piece on its own is below the threshold of "worth a PR" — the
trait method has no motivation without the cache, and the
meta-command has no motivation without the trait method. They're a
unit. The VL mime change is small and rides along since it ships in
the same ggsql-jupyter/src/display.rs file the -- @uncache
dispatch lives next to. Reviewers who prefer to split the VL mime
change into PR3.5 — happy to oblige.

Companion design comment with the broader sequencing context:
#341 (comment).

Motivation

Visualization workflows iterate fast: change DRAW, change a
SCALE, re-run. Each iteration re-runs the SQL — usually identical
text — against the primary reader. For a remote backend (Trino,
Snowflake, anything over Flight SQL) that's wasteful network and
time. The cache memoizes results in the staging DuckDB, keyed on
(reader_uri, sql) with TTL and a byte-budget LRU. Hits are
sub-millisecond; misses fall through transparently. Scope is
deliberately narrow to HybridReader — other reader types don't
have a place to store results.

The trait method exists so non-Hybrid readers can be passed to
generic code that calls clear_cache() without per-type
match-and-cast. The Jupyter meta-command exists because the
notebook is the primary place users encounter the cache: when a
remote table changes underneath you, -- @uncache is faster than
# Restart Kernel + re-running every preceding cell.

The VL mime change addresses a JupyterLab 4.x reality: its
built-in @jupyterlab/vega5-extension only handles v5, while the
ecosystem (nteract, newer Lab extensions) increasingly emits v6.
Emitting both means the client picks whichever it has, with the
HTML/vega-embed fallback only kicking in when neither native
renderer is present.

Design

Cache (src/reader/hybrid_cache.rs + hybrid.rs integration)

The cache module is reader-agnostic: SHA-256 over (reader_uri, sql) joined by \n (the separator prevents (ab, c) and (a, bc)
from colliding), truncated to 16 hex chars (64 bits — collision
odds negligible at any realistic cache size), used as the suffix in
the per-query staging table name __ggsql_cache_<hex>. A
single __ggsql_cache_meta__ table tracks
(cache_key, reader_uri, sql, fetched_at, last_accessed, row_count, byte_estimate).

HybridReader::execute_sql consults the cache:

1. If the query references a registered name → route to staging
   (PR2 behavior, unchanged).
2. Else if cache disabled → direct passthrough to primary.
3. Else look up the cache key; if present and within TTL, return
   the staged result and touch the last-accessed timestamp.
4. Else fetch from primary, register the result under
   __ggsql_cache_<hex> in staging, insert the meta row,
   then run LRU eviction over max_bytes.

Empty-width DataFrames bypass caching (DuckDB's arrow(...) table
function rejects zero-column schemas).

Defaults: enabled, 300s TTL, 512 MB max. Tunable via
HybridReader::with_cache_config(CacheConfig). Globally disabled
with GGSQL_HYBRID_CACHE_DISABLED=1 (read once at
CacheConfig::default()).

Reader::clear_cache()

fn clear_cache(&self) -> Result<()> {
    Ok(())
}

Trait default. HybridReader overrides to call
hybrid_cache::clear_all, which iterates the meta table and drops
each per-key cache table, then defensively deletes any leftover
meta rows.

Jupyter -- @uncache meta-command

Mirrors the existing -- @connect: <uri> pattern:

• META_UNCACHE_PREFIX = "-- @uncache"
• parse_uncache_meta_command(code) returns Some(()) iff the
  trimmed code is the prefix followed only by whitespace.
• QueryExecutor::execute checks this first; on match, calls
  self.reader.clear_cache()? and returns an empty DataFrame so
  the cell renders cleanly.

Vega-Lite v5 + v6 mime

format_vegalite in display.rs builds two serde_json::Values:
the original spec (emitted as application/vnd.vegalite.v6+json)
and a clone with the $schema field rewritten to the v5 schema URL
(emitted as application/vnd.vegalite.v5+json). The $schema
rewrite is necessary because JupyterLab's vega5 extension validates
schema-URL-vs-mime-version. The HTML/vega-embed fallback and
text/plain remain as before.

A drive-by fix in the same function: the output_location: "plot"
hint (Positron Plot-pane routing) was previously placed at the top
level of the output object, which fails Jupyter's notebook-format
schema validation and causes JupyterLab to silently drop the
output. Moving it inside metadata per the schema fixes the
dropped-output case.

Testing

All offline, no external setup:

Cache (hybrid_cache.rs)

• Key stability across calls; URI and SQL each affect the key;
  separator-injection collision resistance.
• Meta-table DDL idempotency (ensure_meta callable twice).
• INSERT-OR-REPLACE behavior on the cache_key PK.
• Lookup → insert → touch (advances last_accessed) → drop cycle.

Cache (hybrid.rs)

All cache-hit assertions go through a CountingReader that wraps
DuckDBReader and shares an Arc<AtomicUsize> call counter so the
test can read it after the reader is moved into Box<dyn Reader>:

• Default config has enabled=true, ttl_secs=300.
• with_cache_config applies custom TTL / byte budget / enabled.
• A repeat execute_sql of the same query reaches the primary
  exactly once (counter stops at 1).
• ttl=0 always misses — counter advances on every call (the strict
  < comparison guarantees this even within the same millisecond).
• LRU eviction with a 1-byte budget evicts entry A when B is
  inserted, so re-querying A increments the counter again.
• clear_cache() resets the cache; the next call increments the
  counter as if from scratch.
• The viz pipeline emits SQL strings through execute_sql that the
  cache memoizes — re-issuing one of the pipeline's sub-queries
  (the schema-fetch SQL targeting the global temp table) is served
  from cache and does NOT advance the data counter. This guarantees
  that any pipeline that re-emits the same SQL string within the
  TTL is memoized.

Jupyter

• parse_uncache_meta_command accepts -- @uncache,
  -- @uncache \n; rejects SELECT 1.
• QueryExecutor::execute("-- @uncache") returns
  ExecutionResult::DataFrame(...) against the default
  duckdb://memory reader (a no-op clear_cache on the trait
  default — proves the dispatch arm is wired).
• format_vegalite emits both v5 and v6 mime keys; the v5 payload
  has its $schema rewritten to the v5 URL.

Limitations

• Cache key uses a fixed "hybrid-primary" placeholder for the
  reader URI portion (the Reader trait doesn't expose a URI).
  Each HybridReader instance has its own staging DuckDB namespace,
  so keys don't need to cross-collide between instances. If a future
  trait extension exposes a real URI, the placeholder becomes the
  actual URI and the test on key uniqueness across URIs starts
  passing for free.
• No spill-to-disk; the cache lives in the staging DuckDB instance
  owned by a single HybridReader and dies with it.
• Eviction failures are logged and swallowed (eprintln!) since
  the user's data is already returned at that point. If review
  prefers structured logging, swapping to tracing::warn! is a
  trivial follow-up.
• The viz pipeline's whole-iteration cache reuse (issuing
  r.execute(viz_query) twice and serving the second call entirely
  from cache) is gated on upstream pipeline determinism — the
  current pipeline issues schema/range/data sub-queries whose SQL
  depends on HashMap iteration order, and the temp-table DDL is
  uncacheable by design (zero-column DDL result). Each individual
  sub-query is cached and replayed correctly when re-issued
  verbatim. Improving end-to-end viz iteration deduplication is a
  separate follow-up — the cache infrastructure here is the
  prerequisite.

What's next

PR4 (ggsql-python PyO3 bindings) depends on PR1+PR2+PR3.