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

## v0.80.0 — Operational Excellence, Documentation Completeness & Final v1.0 Gate

**Status: ✅ Released.**

> **Release Theme**
> Final v1.0 gate: completes every remaining observability, documentation,
> CI, and fuzzing item from the Assessment-15 hardening arc. After this
> release pg_trickle meets all criteria for a 1.0 release: comprehensive
> SQL documentation, operational runbooks, full CI gate coverage, fuzz
> testing for core differentiator subsystems, and meaningful health/metrics
> observability for production deployments.

---

### Operational Excellence

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| O-1 | DVM fallback/performance reason codes in refresh history + health_check() | M | P1 |
| O-2 | health_check() ring overflow alert | S | P1 |
| O-3 | Cleanup backlog trend metrics in metrics_summary() | S | P1 |

**O-1 — DVM fallback reason codes**

Three reason codes are now set in `pgt_refresh_history.refresh_reason` and
surfaced as a `dvm_fallbacks` check in `health_check()`:
- `CORRELATED_SUBQUERY_DELTA_QUADRATIC` — correlated subquery in WHERE clause
  forces full-aggregate fallback.
- `CASE_IN_LIST_DVM_DRIFT_FULL_FALLBACK` — CASE/IN-list aggregate drift pattern.
- `REGEX_COMPLEXITY_CLASSIFIER_UNCERTAIN` — CASE aggregate with EXISTS/subquery
  inside CASE predicate; new `classify_case_aggregate_subquery_uncertain()`
  classifier added to `src/refresh/mod.rs`.

The `dvm_fallbacks` check queries `pgt_refresh_history` filtered to the last
1 hour and emits WARN if any of these reason codes are present.

**O-2 — Ring overflow alert**

`ring_overflow_trend` check in `health_check()` calls
`crate::shmem::invalidation_ring_overflow_count()` and emits WARN if the
counter is non-zero. A non-zero count means the scheduler fell back to a
full DAG rebuild instead of a targeted partial rebuild.

**O-3 — Cleanup backlog in metrics_summary()**

`metrics_summary()` extended with two new columns:
- `cleanup_backlog_count` — total entries in `pgt_cleanup_status`.
- `cleanup_blocked_count` — entries with `blocked = true`.

Requires DROP + CREATE of `metrics_summary()` at upgrade time (return type changed).

---

### Documentation Completeness

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-1 | docs lint script — verify all #[pg_extern] are documented | M | P1 |
| DOC-2 | DVM_SUPPORT_MATRIX.md — comprehensive pattern reference | M | P1 |

**DOC-1 — pg_extern docs lint**

`scripts/check_pg_extern_docs.py`:
- Scans all `src/**/*.rs` for `#[pg_extern]` declarations.
- Cross-references against `docs/SQL_REFERENCE.md` and `docs/SQL_API_CATALOG.md`.
- Reports undocumented exports as failures.
- `ALLOWED_MISSING` set covers internal trigger functions never called by users.
- Integrated into `just docs-lint` (CI gate).
- Passes: "DOC-1 passed: 124 exported function(s) covered by SQL docs"

**DOC-2 — DVM support matrix**

`docs/DVM_SUPPORT_MATRIX.md`:
- Supported patterns: scan, filter, aggregate, joins, semi/anti-join, DISTINCT,
  CTEs, UNION ALL, lateral, window, scalar subqueries.
- Fallback reason codes table with conditions and mitigation actions.
- IMMEDIATE-mode restrictions table.
- Known-unsupported forms: q12 CASE/IN-list, q20 correlated aggregate.
- Quick-reference table for all DVM behaviors.

---

### Upgrades & Operations

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| U-1 | ROLLBACK_RUNBOOK.md — operational rollback runbook | M | P1 |
| U-2 | Document upgrade E2E cutoff policy in CHANGELOG | S | P1 |

**U-1 — Rollback runbook**

`docs/ROLLBACK_RUNBOOK.md` covers:
1. Why downgrades are unsafe (schema migrations, WAL decoder format, shmem
   layout, frontier state).
2. Pre-upgrade backup requirements (pg_dump + filesystem snapshot + CNPG).
3. Recommended snapshot workflow: drain → snapshot → upgrade → verify.
4. Step-by-step restore path from a snapshot.
5. Upgrade E2E cutoff policy pointer.

**U-2 — Upgrade E2E cutoff policy**

Documented in `CHANGELOG.md` top section: defines the tested upgrade path
window (N-2 → current) and what to do for longer-range upgrades.

---

### Build & CI

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| B-1 | Update CONTRIBUTING.md CI gate docs with full workflow matrix | S | P1 |
| B-2 | cargo-deny in PR gates | S | P1 |

**B-1 — CI gate documentation**

`CONTRIBUTING.md` now includes a full workflow trigger matrix table with 25+
CI jobs and columns for: PR gate, push to main, daily schedule, manual dispatch.
Includes note about `cargo-deny` path-filter behavior.

**B-2 — cargo-deny PR gate**

`dependency-policy.yml` already has `pull_request` trigger. Confirmed active
and documented in the CONTRIBUTING.md matrix.

---

### Performance & Fuzzing

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| P-5 | Fuzz target for DVM snapshot fingerprint cache classifiers | M | P1 |

**P-5 — Snapshot fingerprint cache fuzz target**

`fuzz/fuzz_targets/snapshot_fingerprint_fuzz.rs`:
- Tests that all three classifiers never panic on arbitrary UTF-8 input.
- Tests determinism: same input → same output.
- Tests known-safe queries never trigger classifiers.
- Tests q12 canonical query triggers `case_in_list` but not `correlated`.
- Wrapper functions exposed via `src/fuzz_pub.rs`:
  - `refresh_classify_case_in_list_pub()`
  - `refresh_classify_correlated_subquery_pub()`
  - `refresh_classify_case_aggregate_subquery_uncertain_pub()`

---

### Architecture Documentation

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| A-3 | Document internal event trigger functions | S | P1 |

**A-3 — Event trigger documentation**

`src/hooks.rs` module-level doc comment expanded to include:
- Full event trigger subsystem overview table (trigger name, event, handler).
- Detailed description of `_on_ddl_end()`: pipeline steps, ring buffer behavior,
  overflow fallback.
- Detailed description of `_on_sql_drop()`: dropped object handling, catalog
  interaction timing.
- Invalidation ring capacity/overflow documentation.

Individual function doc comments on `_on_ddl_end()` and `_on_sql_drop()`
expanded with SQL registration snippets, pipeline role, and overflow behavior.

---

### Recommended Implementation Order

1. O-1 (reason codes + dvm_fallbacks health check)
2. O-2 (ring overflow alert)
3. O-3 (cleanup backlog metrics)
4. DOC-1 (pg_extern lint script)
5. DOC-2 (DVM support matrix)
6. U-1 (rollback runbook)
7. U-2 (upgrade cutoff policy)
8. B-1 (CI gate docs)
9. B-2 (cargo-deny PR gate)
10. P-5 (snapshot fingerprint fuzz)
11. A-3 (event trigger docs)

---

### Acceptance Criteria

- [x] `health_check()` returns `dvm_fallbacks` and `ring_overflow_trend` rows
- [x] `metrics_summary()` returns `cleanup_backlog_count` and `cleanup_blocked_count`
- [x] `python3 scripts/check_pg_extern_docs.py` exits 0
- [x] `docs/DVM_SUPPORT_MATRIX.md` exists and covers all patterns
- [x] `docs/ROLLBACK_RUNBOOK.md` exists
- [x] CHANGELOG.md contains upgrade E2E cutoff policy
- [x] CONTRIBUTING.md has full CI matrix table
- [x] `cargo-deny` gates PRs
- [x] `fuzz/fuzz_targets/snapshot_fingerprint_fuzz.rs` exists and compiles
- [x] `src/hooks.rs` has expanded doc comments on both event trigger functions
- [x] All tests pass (no skipped tests)
- [x] `just fmt && just lint` passes with zero warnings