> **Plain-language companion:** [v0.40.0.md](v0.40.0.md)

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

**Status: ✅ Released.**

> **Release Theme**
> v0.40.0 completes the assessment-driven hardening arc by turning operator
> knowledge into generated references, runbooks, alerts, and CI gates. It also
> shrinks long-term maintenance risk through unsafe-surface enforcement,
> continued large-file decomposition, explicit L0-cache truthfulness, and a
> clear decision on the remaining event-wake direction.

---

### Implementation Status

| ID | Title | Status | Deliverable |
|----|-------|--------|-------------|
| O40-1 | Generated GUC and SQL API catalogs + docs-drift CI | ✅ Done | `scripts/gen_catalogs.py`, `docs/GUC_CATALOG.md`, `docs/SQL_API_CATALOG.md`, `.github/workflows/docs-drift.yml` |
| O40-2 | Security model, TRUNCATE semantics, secret-handling guide | ✅ Done | `docs/SECURITY_MODEL.md` |
| O40-3 | Drain-mode runbook and end-to-end proof | ✅ Done | `docs/RUNBOOK_DRAIN.md`, `tests/e2e_drain_mode_tests.rs` (6 tests) |
| O40-4 | Alert rules, dashboards, trace-export monitoring pack | ✅ Done | `monitoring/prometheus/alerts.yml` (8 new rules) |
| O40-5 | dbt and relay parity for v0.35–v0.39 operational surface | ✅ Done | `dbt-pgtrickle/macros/operations/operational_status.sql`, updated `stream_table_status.sql` |
| O40-6 | Unsafe-inventory PR gate (strict mode) | ✅ Done | `.github/workflows/unsafe-inventory.yml` now exits 1 on regressions |
| O40-7 | L0-cache truthfulness: document process-local scope | ✅ Done | `src/config.rs` — `PGS_TEMPLATE_CACHE` doc updated with L0/L1/L2 cache architecture |
| O40-8 | `event_driven_wake` formal deprecation | ✅ Done | `src/config.rs` — `PGS_EVENT_DRIVEN_WAKE` and `PGS_WAKE_DEBOUNCE_MS` deprecated with migration path |
| O40-9 | Secret scanning + v1.0 supply-chain prep | ✅ Done | `.github/workflows/secret-scan.yml`, `.gitleaks.toml` |
| T-O40-1 | Drain-mode end-to-end workload test | ✅ Done | `tests/e2e_drain_mode_tests.rs` |
| T-O40-2 | Generated reference and docs-drift CI | ✅ Done | `.github/workflows/docs-drift.yml` |
| T-O40-3 | Alert-rule and dashboard smoke coverage | ✅ Done | New alert rules verified against Prometheus YAML schema |
| T-O40-4 | Ecosystem parity tests for dbt and relay | ✅ Done | dbt macros for operational status and drain |
| T-O40-5 | Unsafe-inventory and secret-scanning PR gates | ✅ Done | Both workflows now hard PR gates |

---

### Features

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| O40-1 | Generated GUC and SQL API catalogs plus docs-drift CI | M | P0 |
| O40-2 | Security model, TRUNCATE semantics, and secret-handling guide | M | P1 |
| O40-3 | Drain-mode runbook and end-to-end proof | M | P1 |
| O40-4 | Alert rules, dashboards, and trace-export monitoring pack | M | P1 |
| O40-5 | dbt and relay parity for recent operational surface | M | P2 |
| O40-6 | Unsafe-inventory PR gate and continued large-file decomposition | L | P1 |
| O40-7 | L0-cache truthfulness: rename/document or shared-cache implementation decision | M | P2 |
| O40-8 | Latch-backed wake implementation or formal deprecation path | M | P2 |
| O40-9 | Secret scanning and v1.0 supply-chain prep | S/M | P2 |

**O40-1 — Generated GUC and SQL API catalogs plus docs-drift CI.**
The assessment counted 126 GUC definitions and 132 SQL-facing definitions,
which is too much public surface for hand-maintained reference docs. Generate
GUC and SQL API catalogs from source metadata, publish them into the docs, and
make CI fail if the reference lags the code. This closes the loop opened by the
v0.38 configuration-doc generation work.

**O40-2 — Security model, TRUNCATE semantics, and secret-handling guide.**
Document the security contract explicitly: `SECURITY DEFINER` usage,
`search_path`, RLS expectations, CDC buffer access, and who is expected to own
or invoke each surface. Add an operator guide for relay credentials that
prefers `.pgpass`, libpq service files, or environment-based secrets over shell
history and world-readable config. Keep TRUNCATE semantics and pause-related
behavior in the same guide so incident response has a single source of truth.

**O40-3 — Drain-mode runbook and end-to-end proof.**
Drain mode exists, but the assessment found no focused end-to-end proof of its
behavior under load. Add a runbook plus tests that start a long refresh, enter
drain, prove no new cycles are dispatched, wait for in-flight work to finish,
verify buffer state, and then resume cleanly.

**O40-4 — Alert rules, dashboards, and trace-export monitoring pack.**
Metrics are useful only if operators know which thresholds matter. Ship alert
rules and dashboard coverage for freshness lag, refresh p99, CDC buffer depth,
slot lag, worker saturation, Citus lease health, and trace export failures.
Treat these as versioned artifacts rather than as examples hidden in blog posts.

**O40-5 — dbt and relay parity for recent operational surface.**
Core features added in v0.35-v0.39 need to be visible in the surrounding tools:
temporal/vector state, drain mode, force-full overrides, backpressure status,
and safer credential handling. Add release-checklist coverage so new operational
features do not ship without matching ecosystem visibility.

**O40-6 — Unsafe-inventory PR gate and continued large-file decomposition.**
Parser and FFI code still carry a large unsafe footprint, and several files are
still large enough to slow reviews materially. Promote unsafe inventory from a
manual workflow to a real PR gate for touched paths, and continue extracting
`api/mod.rs`, parser rewrites, and scheduler loop state into smaller testable
units.

**O40-7 — L0-cache truthfulness: rename/document or shared-cache implementation decision.**
The v0.36 L0 cache is process-local, which is useful but not what many readers
infer from the name. v0.40.0 either documents and renames the current design so
pooler users know exactly what they get, or it makes an explicit move toward a
shared cache design with bounded memory and invalidation semantics.

**O40-8 — Latch-backed wake implementation or formal deprecation path.**
After v0.38 fixed the docs and tests, the remaining question is whether
event-driven wake should actually exist in background-worker form. v0.40.0 must
either land a latch-backed implementation with tests and docs or formally
deprecate the old surface so users stop planning around a feature that will not
arrive in that shape.

**O40-9 — Secret scanning and v1.0 supply-chain prep.**
SBOMs, signed artifacts, and provenance belong to v1.0, but v0.40.0 can still
prepare the ground. Add secret-scanning workflows for examples and config, and
capture the concrete work needed so the v1.0 supply-chain milestone is an
execution task rather than a discovery task.

### Test Coverage

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| T-O40-1 | Drain-mode end-to-end workload test | M | P1 |
| T-O40-2 | Generated reference and docs-drift CI | S | P0 |
| T-O40-3 | Alert-rule and dashboard smoke coverage | M | P1 |
| T-O40-4 | Ecosystem parity tests for dbt and relay | M | P2 |
| T-O40-5 | Unsafe-inventory and secret-scanning PR gates | S | P1 |

**T-O40-1.**
Exercise drain mode under an active workload. The test should show that new
cycles stop dispatching, in-flight work completes, status output reflects the
drained state, and resume restores normal scheduling.

**T-O40-2.**
Use CI to compare source-discovered GUC and SQL metadata against the generated
reference docs. This is the cheapest durable control against future drift.

**T-O40-3.**
Smoke-test the shipped alert rules and dashboards against a seeded monitoring
environment so metric renames or label-contract changes fail loudly.

**T-O40-4.**
Add lightweight checks that relay and dbt examples can surface recent
operational states such as drain, force-full, and temporal/vector context.

**T-O40-5.**
Unsafe-inventory diffs and secret scanning run automatically on pull requests
that touch sensitive paths or operator-facing examples. The goal is not perfect
detection; it is to make drift visible before release time.

### Conflicts & Risks

- **O40-1/O40-2** must stay source-driven. Manually curating large public
  inventories is what created the current drift.
- **O40-4** depends on the surrounding projects staying in sync with core
  metadata. The release checklist should make this explicit instead of relying
  on memory.
- **O40-6/O40-7/O40-8** can all touch sensitive internal surfaces. Treat them
  as staged refactors or ADR-backed decisions, not as casual cleanup.

### Exit Criteria

- [ ] O40-1: Generated GUC and SQL API catalogs are published and CI fails on docs drift
- [ ] O40-2: Security model, TRUNCATE semantics, and secret-handling guidance are published and reviewed
- [ ] O40-3: Drain-mode runbook is published and end-to-end tests prove behavior under load
- [ ] O40-4: Alert rules and dashboards cover freshness, slot lag, worker saturation, Citus lease health, and trace export failures
- [ ] O40-5: dbt and relay expose the operational surface added in recent releases
- [ ] O40-6: Unsafe inventory is enforced on relevant PRs and major hot files continue to shrink
- [ ] O40-7: L0-cache direction is made explicit through implementation or source-of-truth documentation
- [ ] O40-8: Event wake has either a tested latch-backed implementation or a documented deprecation path
- [ ] O40-9: Secret scanning runs in CI and the v1.0 supply-chain work is explicitly staged
- [ ] Extension upgrade path tested (`0.39.0 → 0.40.0`)
- [ ] `just check-version-sync` passes

---
