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

## v0.51.0 — Citus Chaos Resilience & Documentation Truth

**Status: Released.**

> **Release Theme**
> Prove that the Citus distributed integration survives real failure scenarios;
> remove the deprecated `event_driven_wake` dead weight; bring every piece of
> documentation into full alignment with the implemented code.

---

### Implementation Status

| ID | Title | Status |
|----|-------|--------|
| FEAT-10-01 | Citus Chaos Test Rig (3 scenarios) | ✅ Done |
| CQ-10-02 | Remove Deprecated `event_driven_wake` GUC | ✅ Done |
| DOC-10-01 | ARCHITECTURE.md pg_tide Boundary Section | ✅ Done |
| DOC-10-02 | Configuration Deprecation and Removal Banners | ✅ Done |
| DOC-10-03 | Recursive CTE Strategy Selection Heuristic | ✅ Done |
| COR-10-02 | Document CDC-Fires-When-Disabled Behavior | ✅ Done |

---

### Correctness

#### COR-10-02 — Document CDC-Fires-When-Disabled Behavior

`pg_trickle.enabled = false` stops the scheduler from dispatching refreshes
but CDC triggers continue to fire and write to change buffers. This is by
design (keeps buffers ready for immediate use when re-enabled) but is
undocumented and surprises operators who expect `enabled = false` to be a
complete quiet mode.

Add to `docs/CONFIGURATION.md` under `pg_trickle.enabled`:

> **Note on CDC triggers**: Setting `enabled = false` stops the scheduler from
> refreshing stream tables but does **not** disable CDC trigger execution.
> Change buffers continue to accumulate. This is intentional: when the extension
> is re-enabled, stream tables can refresh immediately from the buffered changes
> rather than performing a full table scan.
>
> To fully quiesce CDC overhead during extended maintenance, use
> `pgtrickle.drain()` before disabling, then `DROP TRIGGER` the CDC triggers
> manually and recreate them via `pgtrickle.repair_stream_table()` when
> re-enabling.

---

### Code Quality

#### CQ-10-02 — Remove Deprecated event_driven_wake GUC

The `pg_trickle.event_driven_wake` GUC has been non-functional since
PostgreSQL background workers cannot use `LISTEN`/`NOTIFY`. It has been
deprecated with default `false` since v0.39.0. It still emits a runtime
WARNING when set to `true` and adds dead code paths.

Remove entirely:
- GUC registration in `src/config.rs`
- Runtime warning emission and `event_driven = false` stub in
  `src/scheduler/scheduler_loop.rs`
- `docs/CONFIGURATION.md` entry (replace with a migration note)
- `docs/FAQ.md` and `docs/TROUBLESHOOTING.md` entries
- Update `tests/e2e_wake_tests.rs` to remove tests for the removed GUC

Add to `CHANGELOG.md` under a **Breaking Changes** heading for v0.51.0:
> `pg_trickle.event_driven_wake` has been removed. This GUC had no effect
> since v0.39.0. Remove it from `postgresql.conf` to avoid an unknown GUC
> warning on upgrade.

---

### Features

#### FEAT-10-01 — Citus Chaos Test Rig

Three chaos scenarios for Citus distributed topology, added to
`tests/e2e_citus_chaos_tests.rs` and registered in `stability-tests.yml`.

**Scenario 1: Coordinator restart during active refresh** (CHAOS-5)
**Scenario 2: Worker node kill with shard redistribution** (CHAOS-6)
**Scenario 3: Network partition simulation** (CHAOS-7)

All marked `#[ignore]` and run only in the stability-tests workflow.

---

### Documentation

#### DOC-10-01 — ARCHITECTURE.md pg_tide Boundary

Add a new **§ pg_tide Integration** section explaining the v0.46.0
extraction boundary: what stays in pg_trickle vs what lives in pg_tide.

#### DOC-10-02 — Configuration Deprecation and Removal Banners

After removing `event_driven_wake`, audit all remaining deprecated GUC entries
and add consistent `⚠️ Deprecated` callout blocks.

#### DOC-10-03 — Recursive CTE Strategy Selection Heuristic

Document the tier selection criteria (Tier 1–3c) and the
`explain_stream_table()` observability field in `docs/ARCHITECTURE.md`.

---

### Exit Criteria

- [ ] `just fmt` passes
- [ ] `just lint` passes with zero warnings
- [ ] `just test-unit` passes
- [ ] `just test-integration` passes
- [ ] `just test-light-e2e` passes
- [ ] `event_driven_wake` GUC fully removed (no references in src/)
- [ ] Chaos tests CHAOS-5, CHAOS-6, CHAOS-7 present and `#[ignore]` annotated
- [ ] ARCHITECTURE.md has pg_tide boundary section
- [ ] CONFIGURATION.md has CDC-enabled-flag note and deprecation banners
- [ ] Version bumped to 0.51.0
- [ ] CHANGELOG.md entry written
- [ ] ROADMAP.md status updated to ✅ Released