fix: correct tutorial claims, benchmark setup, and CI readiness

[NikolayS]

Summary

Correct the tutorial and related health/latency guidance against released PgQue 0.2.2.

• Define pending_events as a sequence-based estimate of ticked backlog, not unticked events or an exact unread-row count.
• Separate scheduler checks from materialized ticks. Qualify the historical 52 ms benchmark with its lowered queue thresholds and fast consumer polling.
• Explain healthy idle/manual queue lag and make the illustrative lag values consistent.
• Fix benchmark setup to use supported positive intervals. Preserve historical result files and identify their measurement limits.
• Replace socket-only database readiness probes with a final TCP target-database check. Add fail-closed controls and a benchmark compatibility regression to CI.
• Repair an existing broken snapshot-rule documentation link.

The latency findings F2/F9 describe one issue. The eight claims marked accurate remain supported. No product SQL, SQL installer, SDK runtime, or historical benchmark result bytes change.

Testing

• Released 0.2.2 installed on PostgreSQL 18.3: role memberships, force/tick distinction, sequence metric caveats, full-batch ceiling failure and recovery, retry identity/counts, DLQ replay, and status conversion pass.
• Benchmark regression RED: original setup rejects zero intervals. GREEN: repaired actual setup, positive intervals, unforced tick, two-message complete delivery, acknowledgment, and cleanup pass.
• Disposable PostgreSQL 18 initialization barrier: old socket probe reports ready while TCP remains unavailable; the final TCP helper waits for the target database.
• Readiness positive/unavailable/invalid-attempt controls, shellcheck, shell syntax, and Python compile checks pass.
• Clean-source website build and rendered local-link/anchor checks pass.

This is not a new latency measurement or a full performance sweep. Fresh remote CI and exact-head REV are separate gates. No release is implied.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-14T03:36:48.675095Z	73d3aa2	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[NikolayS]

Final verification

Head: 73d3aa2ba51baa5193620ad003df450a7948f6f0
Base: 58d754456ed9ca36f67dff66d40b05ddd446839e

Findings audit

All 13 report findings were checked against the released 0.2.2 installer and effective function definitions.

• F1: corrected pending_events to a sequence-based ticked-backlog estimate, not an exact unread count or unticked events.
• F2/F9: one duplicated latency issue. Added the historical benchmark queue settings and separated scheduler checks from created ticks.
• F8: qualified health guidance for active, idle, and manually ticked queues.
• F10: corrected the illustrative lag values for the walkthrough's manual-ticking assumptions; this is not a universal inequality between separate observations.
• F3–F7 and F11–F13: all eight claims are supported. Clarified that the status rate is configured cadence, not a measurement.

The audit also found unsupported zero intervals in benchmark setup. The repair uses positive intervals. Product SQL, installers, SDK runtime, and historical benchmark results are unchanged. No new latency result is claimed.

Testing

• CI: all 17 jobs pass, including PostgreSQL 14–19beta1, stable installation, upgrades, scheduler installation paths, all four SDK suites, and benchmark setup regression.
• Website check: passes. Local rendered-site check covers 20 HTML pages and 479 links, with no broken links. Corrected scheduler units render.
• Released 0.2.2 on PostgreSQL 18.3: role membership, forced-tick/metric distinctions, complete-batch ceiling and recovery, retry identity/counts, DLQ replay, and status conversion pass.
• Benchmark RED/GREEN: original setup fails interval validation; repaired actual setup, unforced tick, complete two-event delivery, acknowledgment, and cleanup pass.
• Readiness RED/GREEN: socket-ready/TCP-unavailable startup state reproduced. Host-removal mutation is rejected. The original helper exceeds the stalled-probe test deadline; the repaired helper stops and emits diagnostics. Readiness controls and shellcheck pass.

Review

Exact-head REV uses complete bounded diff coverage across all 10 changed paths. Earlier review findings about TCP regression coverage, scheduler units, and unbounded probes were repaired. Final result: PASS, no retained findings; 36,129/36,129 diff bytes reviewed across 3/3 batches, with complete receipts. Head and base remained unchanged. This covers the changed diff, not every unchanged source path.

Scope limits: no full performance sweep, new latency measurement, or release qualification is implied. Merge and publication remain separate actions.