feat(emit): production-harden the ADR-0017 event outbox (v0.5.8)

[alpertarhan]

Summary

Production-hardens the ADR-0017 event outbox (ask.emit() / ask._outbox) into a robust primitive safe to call from triggers and scheduled jobs on the application write hot path. Ships as v0.5.8.

The work was done in two passes — an initial hardening pass, then a critical self-review (independent reviewer agent + empirical verification against a live PostgreSQL) that found real bugs the first pass introduced. Everything below is the post-review, fully-validated result.

Consumer contract is preserved. The pg_ask_events channel, the ask._outbox columns, the pending-row query, and the ask._outbox_emit(text,jsonb,text) / ask._outbox_mark_processed(uuid) / ask.emit signatures are all unchanged. An existing LISTEN pg_ask_events consumer needs zero changes across the upgrade.

---

Why

ask.emit() is meant to be called from DB triggers and cron-style jobs. That imposes two hard constraints the previous implementation didn't fully meet:

1. It must never abort the caller's transaction. A trigger that fires emit must not be rolled back just because an alert was a duplicate or rate-limited.
2. It can't trust the caller. The writer helper is GRANTed to PUBLIC, so any rule enforced only in the Rust wrapper could be bypassed by calling the SQL helper directly.

---

What changed

�� Security — single authority (closes a real bypass)

ask._outbox_emit is now the one place that decides whether and how an event is written. It re-checks events_enabled, validates input, enforces flood control, INSERTs, and fires pg_notify — all atomically in one SECURITY DEFINER call.

Previously validation / the enabled-check / NOTIFY lived only in the Rust ask.emit wrapper. A role with EXECUTE on the PUBLIC-granted helper could call ask._outbox_emit(...) directly to:

• write a newline-laced event name (corrupting the durable log / a listener's routing),
• write a multi-megabyte payload,
• write a row while events were globally disabled,
• …all without firing a NOTIFY.

The Rust layer is now a thin defense-in-depth adapter (cheap events_enabled short-circuit + SPI forward). It does no size/charset validation of its own — duplicating those checks is what caused the drift bugs below.

✅ Input validation (owned solely by SQL — no drift possible)

Field	Rule
event	non-empty, <= 127 chars, ^[A-Za-z0-9][A-Za-z0-9._:-]*$
summary	<= 8192 bytes (octet_length, exact for multi-byte text)
payload	<= pg_ask.events_max_payload_bytes serialized-JSON bytes (new GUC, default 64 KiB; 0 disables)

Violations RAISE invalid_parameter_value before any row is written.

�� Flood control (opt-in GUCs, both default 0 = off)

• pg_ask.events_max_per_minute — per-(emitter, event) rate cap.
• pg_ask.events_dedup_window_ms — collapse identical (emitter, event, payload) repeats, compared via md5(payload::text) (key-order insensitive because jsonb normalizes before the text cast; far cheaper than jsonb = on large payloads).

A suppressed emit is a silent NULL no-op — it never raises (so the firing trigger's transaction is never rolled back) and logs a RAISE DEBUG line for observability under log_min_messages = debug1.

Checks run atomically under a transaction-scoped advisory lock to eliminate the check-then-insert race. The lock uses the two-arg pg_advisory_xact_lock(domain, key) form (domain = 'pg_ask._outbox'), keeping it in a separate lock space from the int8 session lock — no cross-domain collisions.

⚡ Indexes for the new hot paths

• _outbox_rate_idx (emitter, event, ts) — so rate-limit / dedup checks never seq-scan the outbox on emit.
• _outbox_processed_idx (processed_at) WHERE processed_at IS NOT NULL — partial index so retention prunes hit an index instead of a seq scan.

��️ Retention

ask.prune_events('<interval>'[, batch_size]) + SECURITY DEFINER ask._outbox_prune(interval, int). Deletes only already-delivered rows (processed_at IS NOT NULL) older than the interval, in batches (default 10000; 0 = single DELETE). Pending rows are never removed. Operator-only (not granted to PUBLIC).

Honest limitation documented in code/CHANGELOG: as a plpgsql function the whole loop runs in the caller's single transaction, so batching bounds per-statement size (memory, lock acquisition, dead-tuple churn) but does not split WAL across commits or shorten lock lifetime. For that, call it repeatedly from separate transactions.

---

Bugs caught during review (and fixed)

The review pass was deliberately skeptical and verified claims against a live PG instance rather than trusting them. It surfaced real issues:

1. summary byte/char drift (D1). Rust counted bytes (str::len), SQL counted characters (length()) — a multi-byte summary near the limit was accepted by one layer and rejected by the other. Fix: removed Rust validation entirely (SQL is the single authority) and switched SQL to octet_length. Regression test added.
2. payload byte drift (D2). Rust measured compact JSON; SQL measured jsonb::text (which inserts spaces and normalizes numbers) — the "same quantity" claim was false. Fix: same single-authority consolidation.
3. Advisory lock ::int overflow. hashtextextended(...)::int raised integer out of range for hashes outside int4 — which would have crashed every rate-limited/dedup emit in production (and rolled back the firing trigger). Fix: mask to the low 31 bits (& 2147483647). Caught only by the live test run.
4. UNIT_MS GUC vs current_setting()::int. Postgres normalizes a UNIT_MS value (60000 → '1min'), which broke the SQL-side ::int cast. Fix: plain-integer GUC. Also caught only by the live test run.
5. Missing prune index (H1) and advisory-lock namespace collision (H2) — addressed as above.
6. Batch-prune over-claim (D3) — corrected the docs to state the real transaction semantics.

---

Testing & CI

• cargo pgrx test pg18 → 103 passed, 0 failed (+12 new #[pg_test]: validation, direct-call bypass attempts for disabled/invalid-name/oversized-payload, rate-limit, dedup incl. key-order, batched prune, summary byte ceiling, NOTIFY path, channel-name contract).
• cargo fmt --all -- --check → clean (this check found and we fixed formatting in the new test blocks that would otherwise have failed CI).
• cargo clippy --no-default-features --features pg18 -- -D warnings → 0 warnings.
• Migration ↔ bootstrap function bodies verified byte-identical via diff.

All three match ci.yml exactly.

---

Migration / release notes

• New upgrade script sql/pg_ask--0.5.7--0.5.8.sql (idempotent; CREATE OR REPLACE preserves grants).
• New GUCs: events_max_payload_bytes (64 KiB), events_max_per_minute (0), events_dedup_window_ms (0).
• Version bumped to 0.5.8 across pg_ask.control / Cargo.toml / Cargo.lock and CHANGELOG. The release maintainer owns final versioning/tagging — adjust the version/tag here if 0.5.8 isn't the intended release number.

---

Files

sql/pg_ask--0.5.7--0.5.8.sql   (new migration)
sql/bootstrap.sql              (_outbox_emit authority, _outbox_prune batch, indexes)
sql/finalize.sql               (prune_events operator-only REVOKE)
src/infra/events.rs            (thin adapter; drift source removed)
src/infra/config.rs            (3 new GUCs)
src/api/emit.rs                (emit + prune_events #[pg_extern])
src/lib.rs                     (GUC registration + 12 new tests)
pg_ask.control, Cargo.toml, Cargo.lock, CHANGELOG.md, .gitignore