docs(README): mention benchmark/ directory

[NikolayS]

Closes #87.

Summary

Adds a brief pointer to benchmark/ in the existing ## Benchmarks section. Numbers there are framed as reference and exploration, not a final verdict (cf. Brendan Gregg — benchmarking is hard).

Why scope was reduced

Earlier iterations attempted a full hero rewrite with an inline benchmark table and methodology line. The maintainer pulled it back to a minimal mention given the methodology refinements still in flight (#123, #124, #127). The architectural framing of pgque's xmin-horizon immunity remains the responsibility of the existing README sections.

Scope

• README.md only (~5 lines added inside the existing ## Benchmarks section).
• No code changes.
• No bench numbers or methodology specifics inlined.

🤖 Generated with Claude Code

[NikolayS]

REV review — PR #128

Verdict: REQUEST CHANGES (blocking anti-leak hits in commit message + PR body).
Confidence: HIGH.
SOC2: SKIPPED per instructions (docs PR).

---

Anti-leak (HEADLINE) — 2 BLOCKING [HIGH] hits

Public README copy itself: CLEAN. I re-ran the full grep panel against README.md on docs/readme-hero-xmin — empty. No gitlab, no sahmed, no artifact-registry, no @AR, no WI #76/#77, no Round-N, no R[4-9], no hetzner, no @postgres-ai, no instance IDs. The hero reads as a clean public artifact. Good.

However, two adjacent public artifacts contain R8:

1. Commit message — 9ddd114 docs(README): lead with xmin-horizon argument and R8 numbers. Matches \bR[4-9]\b. Commit messages are permanent, public, and indexed by GitHub search. They are part of the public artifact set.
2. PR body — contains "R8 headline numbers and verbatim methodology line" and "R8/Round-8 in public copy" (the latter inside an anti-leak self-confirmation, which is itself a leak vector). Matches \bR[4-9]\b twice.

The manager explicitly wrote in the issue #87 directive: "Any phrase like 'WI #77', 'Round 8', 'R8' in the public copy. Inside this issue thread is fine; the README copy must read as a clean public artifact." Commit messages and PR descriptions on a public repo are public copy — they are not the "issue thread."

Required actions before merge:

• Force-push (with explicit user confirmation) a re-worded commit: e.g. docs(README): lead with xmin-horizon argument and benchmark numbers (drop R8).
• Edit PR body via gh pr edit 128 --body ... to replace R8 headline numbers → manager-approved headline numbers, and replace the anti-leak self-scan grep block with one that does not itself contain R[4-9]\b as a literal.

I am explicitly NOT making these edits — that is the author/manager's call (per REV constraints, no PR modification).

---

Bug hunter — factual accuracy: PASS

Cross-checked the hero against the manager's canonical R8 reference in issue #87 and against blueprints/SPECx.md:

• Headline table (7 rows × 8 columns): verbatim match — diff against the issue W9: README hero rewrite — lead with xmin-horizon argument and R8 numbers #87 spec returns zero content delta (only the surrounding blockquote prefix differs, which is a rendering decoration).
• Methodology line: verbatim match — same prose, only adds a **Methodology:** bold prefix, which the manager spec explicitly allows ("verbatim or near-verbatim"). Hardware (AWS i4i.2xlarge, Xeon Platinum 8375C), PG version, telemetry tools, run duration, held-xmin window, producer rate, payload size all exact.
• xmin-horizon failure-mode prose: accurate. Idle-in-tx + long OLAP + stalled replication slot pinning xmin → autovacuum can't reclaim dead tuples produced by UPDATE/DELETE in SKIP LOCKED hot path → heap growth → superlinear scan degradation. This is the standard MVCC-pressure failure mode, consistent with docs/three-latencies.md ("long-running tx, idle-in-transaction, lagging logical replication slot, physical standby with hot_standby_feedback=on").
• Snapshot-cursor batching claim: accurate per blueprints/SPECx.md lines 100, 277, 453 (pgque.batch_event_sql() uses txid_visible_in_snapshot, txid_snapshot_xmax, txid_snapshot_xip — a snapshot cursor, not row-level locks).
• TRUNCATE rotation claim: accurate per blueprints/SPECx.md (3-table INHERITS rotation, maint_rotate_tables_step1/step2, "TRUNCATE rotation" called out 5+ times).
• Companion metadata-rotation fact (1,000 vs 21,000+): consistent with the R7 companion finding referenced in the manager comment in W9: README hero rewrite — lead with xmin-horizon argument and R8 numbers #87. PR Rotate subscription and tick tables to avoid held-xmin bloat (#61) #62 (metadata-table rotation) is referenced in the manager spec; the actual numerical claim is what the manager pre-vetted.
• CTA \i sql/pgque.sql: resolves — sql/pgque.sql exists on the branch (175,165 bytes, 175 KiB, install header verified).
• Image docs/images/death_spiral.gif: exists (2,972,957 bytes, 2.83 MiB — note PR body says 2.97 MiB which is the decimal MB rounding; minor).

---

Security: N/A (docs).

Tests: N/A (docs).

Guidelines (CLAUDE.md compliance)

• Conventional Commits: docs(README): ... prefix correct, subject 56 chars (slightly over the 50-char guideline, low severity).
• Binary units: "MiB/s" used in benchmark column header — compliant with the binary-units rule. "200-byte" payload — fine.
• SQL style in CTA: \i sql/pgque.sql — psql meta-command, no SQL keyword case to enforce.
• Schema-qualified identifiers: N/A (no SQL in hero beyond CTA).

Docs review

• Hero structure: tagline → image → problem → architectural answer → table → companion fact → methodology → CTA → closing positioning para. Clean flow.
• Cross-references with docs/three-latencies.md: the hero does not directly link three-latencies.md, but the bottleneck framing ("snapshot SELECT, no SKIP LOCKED scan") is consistent with the three-latencies doc. No conflict. Note: docs/three-latencies.md was merged in PR docs: three-latencies explanation #68 (2026-04-30) but is NOT yet on the PR branch. After merge of docs(README): mention benchmark/ directory #128 this is moot, but if you want a hero→three-latencies cross-link it would need a follow-up.
• Link integrity: all 30 markdown links in the hero resolve. PgCon 2009 deck, Speakerdeck deck, HN, GitHub, internal anchors — all good.
• Tone: matches existing docs/ polish (cf. docs/three-latencies.md, docs/benchmarks.md). Kafka-vs-task-queue closing framing preserved verbatim from prior README — good continuity.
• Badge nit applied: %5Ci_and_go → %5Ci_to_install per manager nit. Renders as \i to install.

---

CI

7/8 checks pass; claude-review pending (this review). No failures.

---

Summary

The hero copy itself is excellent — factually accurate, manager-approved verbatim numbers, clean tone, correct structure, all links work. The only blocking issue is anti-leak in the commit message and PR body, both of which are public artifacts on a public repo. Per the manager's explicit guidance in issue #87, the string "R8" must not appear in any public copy. The commit message and PR description need to be re-worded before merge.

Counts: 2 BLOCKING [HIGH] (anti-leak in commit message + PR body), 0 [MED], 1 [LOW] (commit subject 56 chars, slightly over the 50-char Conventional-Commits guideline).

Anti-leak status: README clean — commit message + PR body have R8 hits (BLOCKING).
Factual-accuracy assessment: PASS — table and methodology verbatim, all architectural claims verified against SPECx.md.

Not approving, not denying, not merging — flagging for author + manager.

[NikolayS]

REV Review — PR #128 (round 2)

CI: 7/8 pass, claude-review pending (this review). All functional checks green (test 14/15/16/17/18, verify, client-smoke).
R1 anti-leak BLOCKING resolution: partial

R1 listed two required actions:

1. Re-word commit to drop R8 from subject — DONE (b0d660d subject is now docs(README): xmin-horizon hero with benchmark table).
2. Edit PR body to (a) replace R8 headline numbers → benign phrasing and (b) "replace the anti-leak self-scan grep block with one that does not itself contain R[4-9]\b as a literal" — only (a) done; (b) not done.

Independent re-scan:

• README: clean (grep against branch HEAD — empty)
• commit history: clean (b0d660d body — empty match)
• PR title: clean
• PR body: hits — the ## Anti-leak confirmation block still contains the literal regex string gitlab|sahmed|artifact[_-]?registry|@AR\b|wi[ -]?#?7[67]|round[ -]?[4-9]\b|R[4-9]\b inside backticks, plus the prose "No GitLab, no sahmed, no AR, no WI references". Word-boundary matches: @AR, gitlab, GitLab, sahmed, and R[4-9]\b as a literal grep pattern.
• diff: clean

The hits in the PR body are the same self-confirmation-block leak vector R1 explicitly called out and asked to be removed. The strings sahmed and @AR are not abstract regex concepts — they are real watch-listed identifiers and they now appear verbatim in the public PR description.

Suggested fix (not applying — REV does not modify): replace the entire ## Anti-leak confirmation section with a non-self-revealing line, e.g.:

Anti-leak grep panel was run against README.md; result was empty.

…with no literal pattern strings.

Verdict: FIXES NEEDED

Counts: 1 BLOCKING [HIGH] (PR body still contains literal anti-leak watch terms in self-confirmation block — same vector R1 flagged as item #2), 0 [MED], 0 [LOW].

---

REV-style review (security, bugs, tests, guidelines, docs). SOC2 items skipped per project policy. Anti-leak independently re-verified across all 4 surfaces.

[NikolayS]

R3 quick-check — BLOCKING resolved

Ran anti-leak grep (round[4-9], R[4-9], WI#76/77, gitlab, sahmed, artifact_registry, @AR) across all four surfaces: PR body (meta JSON), diff, commit history, and the branch code. All three grep invocations exited 1 — zero matches on every surface.

The R2 BLOCKING (grep block containing watchlisted patterns verbatim) is confirmed removed. No further anti-leak issues found.

[NikolayS]

REV Review — PR #128 (round 4)

Hero direction change verification:

• Bench table removed: yes (grep -c "^| pgque |" README.md → 0)
• Verbatim methodology line removed: yes (grep -c "AWS i4i.2xlarge" README.md → 0)
• Humble benchmark/ pointer added with Brendan-Gregg framing: yes — exact text: "These numbers are for reference and exploration, not a final verdict; benchmarking PostgreSQL queues is hard (cf. Brendan Gregg) and the methodology continues to evolve."
• xmin-horizon architectural argument retained: yes (6 occurrences of "xmin" in README; full explanation preserved in hero section)
• CTA + image link intact: yes (\i sql/pgque.sql present 3×; docs/images/death_spiral.gif image link confirmed)

Anti-leak across all 4 surfaces: clean (meta.json, diff, git history, README — no round-4/R4-9/WI#76-77/gitlab/sahmed/artifact-registry hits; i4i.2xlarge absent from README entirely)

CI: all pass (claude-review, client-smoke, test PG14–18, verify — 8/8)

Verdict: READY FOR USER REVIEW

---

REV-style review (security, bugs, tests, guidelines, docs). SOC2 items skipped per project policy.

[NikolayS]

REV Final — PR #128

Scope: 1 file — README.md
Commit count: 1 (8adb76b docs(README): mention benchmark/ directory)
Net README diff: ~5 lines added (3 prose + blank line above Architecture header)
"cf. Brendan Gregg": retained
Anti-leak (all surfaces): clean
CI: 5 pass, 3 pending (client-smoke, claude-review, test(15)) — no failures

Note: PR title (docs(README): xmin-horizon hero with benchmark table) and PR body still describe the original hero-rewrite scope. The diff is correct and minimal, but the description is stale. Low risk for a docs-only PR; maintainer should decide whether to update before merge.

Verdict: READY FOR USER REVIEW (with optional title/body cleanup)

---

REV-style final verify after maintainer-directed scope reduction. SOC2 skipped per project policy.