🎉 tau-rag v2.0

Release notes — 68 features, 1096 tests, 6 side-channel analytics stores, 4 background daemons, 4 HTML dashboards.

What v2.0 means: API stability pledge. Everything under /v1/* is now stable. Additive changes only. Breaking changes will be delivered under a new /v2/* namespace. features.* in /v1/version tracks currently-active capabilities so clients can feature-detect.

Headline numbers

Metric	Value
Tests passing	1096 (up from 32 at v1.32)
Endpoints	80+ across `/v1` and `/v1/admin`
Side-channel analytics stores	6
Background daemons	4
HTML dashboards	4
Iterations	68 (v1.32 → v2.00)

Architecture (v2.0 shape)

Retrieval core

4 retrievers: bm25 gematria hilbert graph → rank-based fuser → optional reranker → structure-preserving verifier → TAU-Ω signal aggregator.

Observability stack (6 layers, all composable)

Layer	Shipped	Path
push	v1.71 webhook + v1.79 circuit breaker	`TAU_RAG_AUDIT_WEBHOOK_URL`
batch	v1.74 audit export	`/v1/admin/audit/export`
pull-stream	v1.75 SSE log tail	`/v1/admin/logs/stream`
history	v1.78 metrics + v1.88 content-health	`/v1/admin/metrics/history`
breaker	v1.79 (inside webhook dispatcher)	`/v1/admin/webhook`
rules	v1.80 + v1.81 scheduler	`/v1/admin/alerts`

Content analytics (the 6-dim grid)

Dim	Version	Store
per-doc	v1.82	`DocumentStatsStore`
per-retriever	v1.83	`RetrieverAttributionStore`
(doc, doc) pair	v1.84	`CoCitationStore`
per-query	v1.89	`QueryStatsStore`
doc freshness	v1.94	`DocFreshnessStore`
(query, doc) pair	v1.96	`QueryDocAffinityStore`

Cross-cut views: content health (v1.85), update priorities (v1.95), query analytics UI (v1.98), unified dump/restore (v1.97).

Auth & safety

API key store with sha256-hashed storage + scopes (read/write/admin)
Grace-period rotation (v1.76) — no downtime key refresh
Per-endpoint rate limits (v1.73) — longest-prefix override
Eval harness with quality + latency regression gates (v1.58, v1.87)

Debugging

Every response carries X-Request-ID
obs log: ring buffer + optional JSONL file + stdout + SSE tail + webhook
Query replay (v1.99) — opt-in body capture + re-execute by request_id

Patterns that formed along the way

Side-channel store pattern

Each analytics dimension is an independent module:

Thread-safe singleton + set_X()/get_X() for test injection
Pipeline hook fires record() after step 7 (signals), silent-fail on exception
Admin CRUD: GET/POST/DELETE + audit event on mutations
Persistence opt-in via env var
Feature flag in /v1/version.features.*

Daemon lifecycle pattern

4 background threads (AutoSnapshotter, MetricsHistorySampler, AlertScheduler, AnalyticsRetentionScheduler) share the same shape:

start() / stop() / is_running / status()
threading.Event.wait(timeout=interval_s) for clean stop — no polling loops
Silent-fail on tick errors (last_error stored; loop continues)
Quiet-on-zero callbacks (where applicable) — avoid flooding audit log with no-op ticks

HTML dashboard pattern

4 dashboards (admin UI, content health, chunks viewer, query analytics) share the same design:

Inline CSS — zero JS, zero CDN, 10–20KB self-contained
Escape-safe: all untrusted text (doc IDs, query text) goes through html.escape(quote=True); tested with XSS payloads
?refresh=N → meta http-equiv="refresh" for wall screens, no JS timer
Pure render functions; endpoint is a thin wrapper

Singleton-with-injection

Every stateful module (auth, obs, limiter, cache, 6 analytics stores, 4 schedulers) uses the same pair: module-level singleton + setter for test injection. Lets prod use globals while tests keep clean state per run. No dependency injection framework.

Breaking / deprecation notice

No breaking changes in v2.0. This is a stability pledge release — all /v1/* paths work identically.
Any future breaking change will be delivered under /v2/* with a 6-month parallel-run period.
Feature flags in /v1/version.features.* are discovery not contract — they may come and go as features evolve.

What's still open

Honest accounting:

Core retrieval quality has not advanced much since v1.58. The last 15 iterations were platform / analytics heavy. Post-v2.0 work should lean back into the retrievers.
Multi-process state (rate limiter, obs log, analytics counters) is still in-memory. v1.97 dump+merge is the workaround. Real solution is Redis-backed limiter + shared obs.
OTEL distributed tracing not implemented. Request IDs are manual correlation; OTEL spans would cross pipeline stages naturally.
Semantic answer cache not implemented. Current cache is exact-match by query string. Embedding-similarity cache would give real latency improvements.

Credits

This stretch shipped across one long coding session, with one Living Document (RAG_Projects_Ultimate_Report.html) tracking every iteration. The Living Doc remains the canonical changelog — this file is a v2.0 summary.

Released 19 April 2026.