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

## v0.45.0 — Operational Readiness, Scalability & CI Completeness

**Status: Planned.** Derived from [plans/PLAN_OVERALL_ASSESSMENT_9.md](../plans/PLAN_OVERALL_ASSESSMENT_9.md) §Dimension 4 (Scalability), §Dimension 8 (Operational Readiness), §Dimension 10 (CI).

> **Release Theme**
> Close all operational, scalability, and CI gaps identified in the assessment.
> Make deployment assets production-grade, shared-memory structures configurable,
> runtime status SQL-visible, and CI gates comprehensive.

---

### Features

| ID | Title | Effort | Priority | Assessment ref |
|----|-------|--------|----------|----------------|
| A46-1 | Dockerfile VERSION sync from Cargo.toml | S | P0 | OPS-01 |
| A46-2 | Container HEALTHCHECK for all runtime images | S | P1 | OPS-02 |
| A46-3 | CNPG production examples with worker budgets | M | P1 | OPS-03, SCAL-07 |
| A46-4 | `pgtrickle.preflight()` SQL function | M | P0 | OPS-04, SCAL-02 |
| A46-5 | `pgtrickle.worker_pool_status()` SQL function | M | P1 | OPS-04 |
| A46-6 | Production monitoring split (demo vs production) | S | P2 | OPS-06 |
| A46-7 | Invalidation ring configurable capacity + overflow metrics | M | P0 | SCAL-01 |
| A46-8 | Worker-slot exhaustion as SQL-visible status | M | P1 | SCAL-02 |
| A46-9 | Incremental DAG rebuild optimization | L | P1 | SCAL-03 |
| A46-10 | Lag-aware cross-database scheduling | L | P2 | SCAL-04 |
| A46-11 | Citus failure counter persistence | M | P1 | SCAL-05 |
| A46-12 | WAL slot preflight check | M | P1 | SCAL-06 |
| A46-13 | Cross-platform CI blocking (Windows/macOS) | M | P1 | CI-01, TEST-07 |
| A46-14 | Full-image PR smoke test | M | P0 | CI-02 |
| A46-15 | E2E coverage schedule restore + module tracking | M | P1 | CI-03, TEST-08 |
| A46-16 | Storage Backends reference page | M | P2 | FEAT-03 |
| A46-17 | dbt macro option sync | S | P2 | FEAT-06 |

**A46-1 — Dockerfile VERSION sync.**
In `Dockerfile.hub` and `Dockerfile.ghcr`, derive `ARG VERSION` from
`Cargo.toml` during build using a build-arg extraction step, or require the
release workflow to pass it and fail if it differs from Cargo. Remove stale
hardcoded defaults (`0.11.0`, `0.13.0`).

**A46-2 — Container HEALTHCHECK.**
Add `HEALTHCHECK CMD pg_isready -U postgres || exit 1` to all runtime
Dockerfiles (`Dockerfile.demo`, `Dockerfile.hub`, `Dockerfile.ghcr`). For test
images, optionally add extension-aware checks.

**A46-3 — CNPG production examples.**
Ship separate `cnpg/cluster-dev.yaml` and `cnpg/cluster-production.yaml`.
Production example includes:
- Worker budget formula: `max_worker_processes = 8 + (2 * num_databases) + worker_pool_size`
- Explicit resource requests and limits
- WAL sizing and archive configuration
- Storage class guidance
- Monitoring hooks and ServiceMonitor

**A46-4 — `pgtrickle.preflight()`.**
SQL function that checks and reports:
- `max_worker_processes` vs required slots
- `max_replication_slots` vs WAL-eligible sources
- `wal_level` is `logical` (if WAL CDC desired)
- `shared_preload_libraries` includes `pg_trickle`
- Scheduler is running and enabled
- Returns structured JSON with pass/fail per check

**A46-5 — `pgtrickle.worker_pool_status()`.**
SQL function returning: pool size, active workers, idle workers, queued jobs,
jobs in flight, blocked databases (if any), and last scheduler tick time.

**A46-6 — Production monitoring split.**
Separate `monitoring/` into `monitoring/demo/` (current compose) and add
`monitoring/production/README.md` with TLS/auth notes, least-privilege exporter
role setup, and Kubernetes ServiceMonitor examples.

**A46-7 — Invalidation ring configurable capacity.**
Make `INVALIDATION_RING_CAPACITY` configurable via
`pg_trickle.invalidation_ring_capacity` (preload-time, default 128). Add an
overflow counter exposed through diagnostics and Prometheus. Track overflow
events for capacity planning.

**A46-8 — Worker-slot exhaustion SQL visibility.**
When worker slots are exhausted, record the event in catalog/shmem and expose
through `pgtrickle.preflight()` and `pgtrickle.scheduler_diagnostics()` as a
blocked reason rather than only logging.

**A46-9 — Incremental DAG rebuild optimization.**
Maintain dependency-local schedule invalidation and cache CALCULATED schedule
results by generation counter. Avoid O(V) re-resolution iterations for small
changes. Add large-DAG benchmarks (1000+ nodes) for incremental rebuild under
repeated ALTER/CREATE/DROP.

**A46-10 — Lag-aware cross-database scheduling.**
Graduate from static per-database quotas to lag-aware scheduling that considers
observed staleness/freshness lag when distributing refresh capacity across
databases. Persist fairness state across scheduler restarts.

**A46-11 — Citus failure counter persistence.**
Move `CITUS_WORKER_FAILURES` from thread-local storage in the scheduler worker
to catalog or shared memory with timestamps. Expose through diagnostics so
failure patterns survive scheduler restarts.

**A46-12 — WAL slot preflight.**
Before enabling WAL/auto mode across many sources, check available replication
slots vs required. Report required slots, available slots, and sources blocked
by capacity through `pgtrickle.preflight()`.

**A46-13 — Cross-platform CI blocking.**
- Make Windows compile failures blocking on scheduled runs (remove
  `continue-on-error: true`)
- Add Windows compile check to PR gate for pure Rust modules
- Keep pgrx/Postgres-specific integration tests on Linux

**A46-14 — Full-image PR smoke test.**
Add a CI job that runs on PR and push to main:
- Build the E2E Docker image
- Install the extension
- Run a representative 5-minute smoke test covering DVM, CDC, and scheduler
- Keep exhaustive full E2E as scheduled/manual

**A46-15 — E2E coverage schedule restore.**
Fix the coverage workflow condition to allow scheduled weekly runs (not only
manual dispatch). Add module-level coverage reporting for DVM, CDC, WAL, and
scheduler paths. Consider non-decreasing coverage requirements for core files.

**A46-16 — Storage Backends reference page.**
Add `docs/STORAGE_BACKENDS.md` documenting:
- Available backends and their prerequisites
- Supported/unsupported combinations
- Migration behavior between backends
- Failure modes and fallback semantics
- Extension dependencies (e.g., columnar requires `cstore_fdw`)

**A46-17 — dbt macro option sync.**
Generate dbt macro option schemas from the `CreateStreamTableOptions` struct
(introduced in v0.44.0). Ensure new options are automatically available in dbt
macros without manual synchronization.

### Test Coverage

| ID | Title | Effort | Priority | Assessment ref |
|----|-------|--------|----------|----------------|
| T-A46-1 | Preflight function accuracy tests | M | P0 | OPS-04 |
| T-A46-2 | Worker-pool status accuracy | M | P1 | OPS-04 |
| T-A46-3 | Invalidation ring overflow behavior test | M | P1 | SCAL-01 |
| T-A46-4 | Large-DAG incremental rebuild benchmark | L | P1 | SCAL-03 |
| T-A46-5 | WAL slot preflight accuracy | S | P1 | SCAL-06 |
| T-A46-6 | Full-image PR smoke test validation | M | P0 | CI-02 |
| T-A46-7 | Cross-platform compile gate verification | S | P1 | CI-01 |

**T-A46-1.**
E2E test: deliberately misconfigure `max_worker_processes` too low, call
`pgtrickle.preflight()`, verify it reports the issue with actionable guidance.

**T-A46-2.**
E2E test: start pool workers, queue jobs, verify `worker_pool_status()` returns
accurate counts for active, idle, queued states.

**T-A46-3.**
E2E test: create 200+ stream tables rapidly (exceeding ring capacity), verify
overflow counter increments, full rebuild occurs, and all stream tables are
eventually refreshed correctly.

**T-A46-4.**
Criterion benchmark: 1000-node DAG with repeated ALTER/CREATE/DROP operations,
measuring incremental rebuild time vs full rebuild time.

**T-A46-5.**
E2E test: configure `max_replication_slots` to a low value, attempt WAL mode
on more sources than slots allow, verify preflight reports the constraint.

**T-A46-6.**
Verify the PR smoke test catches a deliberately broken extension (e.g.,
missing SQL migration) and fails the CI gate.

### Conflicts & Risks

- **A46-9** (DAG optimization) and **A46-10** (lag-aware scheduling) are
  complex scheduler changes. Land incrementally with feature flags.
- **A46-14** (full-image smoke) adds CI time to every PR. Keep the smoke test
  under 5 minutes by running only a representative subset.
- **A46-7** (ring capacity) changes shared memory layout. Requires careful
  upgrade testing.

### Exit Criteria

- [ ] A46-1: No stale VERSION defaults in public Dockerfiles
- [ ] A46-2: All runtime images pass container healthcheck within 30s
- [ ] A46-3: Production CNPG example provisions workers correctly
- [ ] A46-4: `preflight()` catches misconfigured clusters
- [ ] A46-7: Invalidation ring capacity is configurable, overflow tracked
- [ ] A46-9: Incremental DAG rebuild is measurably faster for small changes on large DAGs
- [ ] A46-13: Windows compile failures are blocking
- [ ] A46-14: Full-image smoke test gates PRs
- [ ] A46-15: E2E coverage runs weekly with module reporting
- [ ] Extension upgrade path tested (`0.45.0 → 0.46.0`)
- [ ] `just lint` passes with zero warnings
- [ ] `just test-all` passes
