fix(stats): surface summary-stat cache write side via telemetry (#951)

[paddymul]

Fixes #951 — the xorq summary-stat snapshot cache did its I/O with no operator-visible signal.

What

The cache read/write itself is correct; this makes the write side observable rather than forensic.

• xorq_buckaroo — add cache_snapshots / cache_bytes / cache_write_errors to the firstpull.summary_stats span attrs (already available from cache_run_stats()), alongside the existing cache_status / cache_hits / cache_misses / cache_secs. A write_errors > 0 run now reaches a telemetry consumer.
• xorq_stat_pipeline — capture the stat.xorq.total span handle in process_table and have _log_cache_stats(span) attach the per-run cache outcome to it. Every process_table run — not just the firstpull — now routes its cache outcome through a bound telemetry sink, independent of log level. The log.info summary line stays for local perf/debug sessions.

Why

Verified against 0.15.3: a cold /load_expr writes 45 snapshot parquets on the miss and a warm one reads them back (0 rewrites) — correct — but across all 90 cache operations the server's stderr stayed empty and the telemetry carried no write-side signal. _log_cache_stats emits at log.info to a server log file no deployment reads, so _write_snapshot's failure counter (#910) was invisible in practice: a cache that silently stops writing (a write regression, a permissions problem, an unstable key) could only be caught by counting .parquet files by hand. Telemetry is the channel a deployment actually consumes, so the write outcome now rides the span (#943).

Tests

tests/unit/test_xorq_stats_v2.py::TestSnapshotCacheRun:

• test_cache_outcome_rides_total_span_to_telemetry — a cold run with a bound sink emits stat.xorq.total carrying cache_status="miss", cache_snapshots > 0, cache_bytes > 0, cache_write_errors == 0.

tests/unit/server/test_load_expr.py:

• test_load_expr_telemetry_emits_session_correlated_spans — extended to assert the three write-side fields on the firstpull.summary_stats span.

Both confirmed failing against pre-fix source (KeyError on the new attrs) and passing with the fix. Full relevant suite green (102 passed across the stats, load_expr, perf-log and telemetry-sink files); ruff + paddy-format clean (pre-commit + pre-push).

🤖 Generated with Claude Code

[github-actions]

📦 TestPyPI package published

pip install --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo==0.15.3.dev28542295615

or with uv:

uv pip install --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo==0.15.3.dev28542295615

MCP server for Claude Code

claude mcp add buckaroo-table -- uvx --from "buckaroo[mcp]==0.15.3.dev28542295615" --index-strategy unsafe-best-match --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ buckaroo-table

📖 Docs preview

🎨 Storybook preview