0.3.0-alpha1 release notes: breaking/behavior changes to include

[NikolayS]

Tracking issue so breaking/behavior changes from the #283 fix series make it into the 0.3.0-alpha1 release notes (there is no CHANGELOG.md; notes are authored at release time per clients/*/RELEASE.md).

Items collected so far from the deep reviews:

1. Python client — Event.extra removed (breaking). From fix(python): consumer loop drain, error survival, dead Event.extra #291: the Event.extra: dict[str, str] field never worked (data placed there was silently dropped; pgque.send has no extras surface). It is now removed, and constructing Event(..., extra={...}) raises TypeError. One-line note recommended by the reviewer since Event is a public dataclass.

2. Experimental pgque.throughput() — bucket alignment changed (behavior). From fix: experimental SQL bugs + CI coverage #288: buckets now align to epoch (UTC) boundaries via to_timestamp(floor(epoch/sec)*sec) instead of session-timezone minute boundaries. This is what makes sub-minute and non-minute-multiple bucket sizes correct, but existing callers of minute-multiple buckets may see bucket boundaries shift. Non-positive bucket sizes now raise instead of dividing by zero.

3. Consumer loop behavior (all three clients) — worth a "fixed" note, not breaking. From fix(go): back off before re-polling failed batch #284/fix(ts): back off on nack/ack failure in consumer #289/fix(python): consumer loop drain, error survival, dead Event.extra #291: consumers now back off one poll interval before re-polling an unfinished batch (previously a zero-delay hot loop re-executing handlers), the Python consumer drains backlogs immediately and survives connection loss/failover instead of exiting.

Add further items here as remaining PRs from the series merge; close when the release notes are drafted.

[NikolayS]

0.3.0 release-audit handoff (2026-07-10)

Nothing in this audit is merged yet. The following is the candidate release-note and integration checklist once the draft PR stack is reviewed.

Highlights to call out

• Producer idempotency: pgque.send_idem() provides queue-scoped retry keys with bounded TTL windows. Duplicate attempts return the original event id; this does not change at-least-once consumer delivery.
• Partition keys: keyed send routes through fixed slot consumers for per-key order and cross-key parallelism. Setup is atomic, slot claims are nonblocking and lease-fenced, and partition_slot_status exposes incomplete/stalled slots. Operational caveats belong in the notes: every slot must be polled, reads scale roughly with n, and first-party clients do not yet implement claim/rebalance helpers.
• Ruby client: first 0.3 client line, with reconnect/backoff resilience, namespaced ruby/v... tags, typed missing-consumer errors, strict event extras, and explicit NULL event behavior.
• pg_tle: a tested, data-preserving 0.2.0 -> 0.3.0 ALTER EXTENSION update path. Never advise uninstall/reinstall for an upgrade; DROP EXTENSION ... CASCADE removes queue data.

Breaking / behavior notes

Keep the existing issue items for Python Event.extra, throughput bucket alignment, and consumer backoff/reconnect behavior. Add:

• Public 0.3 SQL argument names are stabilized for named calls; the alpha input names migrate while preserving state, owners, grants, function identity on stable reinstall, and dependent objects.
• Legacy ordinary consumer names containing # remain valid; only partitioned logical consumer setup rejects ambiguous # names.
• Python, TypeScript, and Ruby preserve SQL NULL message type/payload as NULL/nil. NULL type never dispatches to a nil-key handler; wildcard/unknown policy applies. Go intentionally retains its historical empty-string/empty-byte normalization.
• Ruby Event rejects unsupported extra* input rather than silently dropping it, and missing consumers raise ConsumerNotFound while remaining retryable by the resilient loop.

Support and upgrade wording

• Supported production majors: PostgreSQL 14–18.
• PostgreSQL 19 beta 1 is a continuously tested forward-compatibility lane, not a production-support claim.
• Plain SQL upgrades are in-place, single-transaction installer reruns. Tested paths cover v0.1 on PG14/PG19 beta, v0.2 on PG17, and v0.3 alpha on PG17.
• Stable release preparation must promote all four SQL/TLE install+uninstall artifacts atomically, verify the manifest, switch docs to stable:v0.3.0 with stable paths and tag-pinned links, and use reviewed release-notes-0.3.0.md.
• RubyGems already contains immutable 0.3.0.rc.1; the next Ruby candidate must bump to a new version (for example 0.3.0.rc.2) before even a dry run.

Draft PR order / stack

• Partition stack: fix(partition-keys): fence lease release #311 -> fix(partition-keys): make claims nonblocking #321 -> fix(partition-keys): make slot setup atomic #336 -> fix(sql): stabilize 0.3 named arguments #339 -> docs: document idempotency and partition keys #342.
• pg_tle/release stack: release(pg_tle): preserve data across 0.3 upgrades #333 -> fix(release): make promotion atomic #340.
• Ruby release stack: fix(ruby): namespace gem tags #323 -> fix(ruby): validate release workflow #343.
• Ruby behavior changes integrate cleanly in this order: fix(ruby): reject unsupported event extras #330, fix(ruby): classify missing consumers #331, fix(ruby): make Consumer resilient #318, fix(clients): define nullable message behavior #338; fix(python): derive runtime version from metadata #332 is Python-only.
• Independent fixes/docs: docs(clients): repair snapshot links #319, fix(idempotency): use wall-clock TTL #320, fix(upgrade): preserve legacy hash consumers #322, docs(ci): clarify Postgres support #329, fix(ci): fail closed on Postgres readiness #337.

Known integration resolutions to preserve when bases advance: keep all four upgrade-matrix lanes (v0.1 PG14+PG19 beta, v0.2 PG17, alpha PG17); keep both promotion and readiness verifier steps; keep the development-path pg_tle upgrade warning in main docs.

Validation completed

• Fresh full regression + acceptance: PG14, PG18, PG19 beta; experimental/reinstall/uninstall on PG18.
• Upgrade fixtures and post-upgrade reinstall/named-argument identity checks for v0.1, v0.2, and alpha.
• Real pg_tle fresh install/uninstall, immutable v0.2 data-preserving update, and fresh full regression.
• Multi-session receive serialization, nonblocking slot claim/TTL fencing, DLQ replay race, and cooperative registration race.
• Python 3.12: 85 tests + wheel/sdist checks; Go race suite; TypeScript: 89 tests + package; Ruby 3.3: 99 tests / 280 assertions / zero skips + gem checks.
• Deterministic generation, release promotion/rollback, docs development+simulated-stable contracts, website build/internal links, actionlint, shellcheck.
• All main-based audit PRs currently have green checks. Stacked core PRs do not receive the main-only workflow by design; the entire 24-commit candidate was assembled and tested locally without pushing or merging it. docs: document idempotency and partition keys #342's website check is green.

Remaining release gates

• release(ruby): complete trusted-publishing prerequisites #328: configure/prove the RubyGems trusted-publishing GitHub environment (external repository setting).
• release(ci): require passing checks before main merges #334: add required status checks to the active main ruleset (external repository setting).
• Review and merge the draft stack, resolve bases with the integration notes above, then run the final promoted stable-artifact matrix from fix(release): make promotion atomic #340. Do not tag from the current devel branches.