# v0.40.0 — Operator Trust, Maintainability & Release Confidence

> **Full technical details:** [v0.40.0.md-full.md](v0.40.0.md-full.md)

**Status: Planned** | **Scope: Large**

> Finish the post-v0.37 hardening arc with generated references and runbooks,
> drain-mode proof, alert rules, secret hygiene, unsafe-surface gating,
> large-file decomposition, L0-cache truthfulness, and a clear event-wake
> direction before the roadmap resumes embedding-focused feature work.

---

## What is this?

v0.38.0 and v0.39.0 make correctness claims and distributed behavior credible.
v0.40.0 makes the operator experience and engineering process credible too.
This is the release that turns a large, fast-moving extension into a platform
with generated references, explicit runbooks, actionable alerts, safer tooling,
and a smaller maintenance surface.

---

## Generated operator surface and runbooks

The assessment found too much public surface area being tracked manually:
hundreds of GUCs and SQL-facing definitions, security assumptions that live in
code rather than docs, and semantics such as TRUNCATE or `cdc_paused` that are
easy to misunderstand. v0.40.0 adds generated GUC and SQL API inventories,
security-model documentation, secret-handling guidance for relay users,
and explicit runbooks for drain mode and incident response.

---

## Observability, drain mode, and ecosystem parity

Metrics alone are not enough if operators still have to design their own alert
rules from scratch. This release ships alert rules and dashboard coverage for
freshness, WAL slot lag, worker saturation, Citus lease health, and trace export
failures, and it proves drain mode end to end under load rather than treating it
as a nominal API.

The surrounding tools must also catch up with the core surface added in v0.35-
v0.39: dbt and relay views need to understand temporal/vector states,
drain mode, force-full overrides, and safer credential handling.

---

## Maintainability and remaining platform decisions

The assessment still found very large core files, a large unsafe surface with a
manual-only inventory workflow, and ambiguity around whether the so-called L0
cache is merely process-local or should become shared. v0.40.0 continues the
decomposition of `api/mod.rs`, parser rewrites, and scheduler loop state,
makes unsafe inventory a real PR gate, and either implements or explicitly
documents the long-term direction for the L0 cache and event-driven wake.

---

## Also in v0.40.0

- Secret-scanning workflow coverage for relay examples and docs
- Decision records for L0-cache direction and latch-backed wake versus formal
  deprecation

---

## Scope

v0.40.0 is a large release because it spans documentation generation,
monitoring, ecosystem parity, maintainability, and release-confidence tooling.
It is still part of the hardening programme, not a detour from it: the goal is
to remove the last major trust and process gaps before the deferred embedding
programme restarts in v0.41.0.

> **Release-order note:** The old `embedding_stream_table()` and advanced RAG
> plan is not dropped. It moves to v0.43.0 after the hardening arc in
> v0.38.0-v0.40.0.

---

*Previous: [v0.39.0 — Distributed Hardening & Diagnostic Depth](v0.39.0.md)*
*Next: [v0.41.0 — Embedding Pipeline Infrastructure & ANN Maintenance](v0.41.0.md)*
