W6: PR #68 polish — three-latencies doc (callout in README + dedicated docs/three-latencies.md)

[NikolayS]

Parent: #85
Target PR: #68 (branch `docs/three-latencies`)

Scope

Restructure PR #68 to the agreed shape (user confirmed):

1. ~5-line callout in main `README.md` referencing the three-latencies concept (linking to the dedicated doc).
2. Dedicated `docs/three-latencies.md` with the full explanation. Promote the relevant bits from `docs/pgq-concepts.md` (do not duplicate; `pgq-concepts.md` is contributor-only glossary).
3. Update `docs/README.md` (the docs index) to list `three-latencies.md`.

TDD

Docs-only — no automated test. Verify:

• README callout is short and links work.
• `docs/three-latencies.md` renders cleanly on GitHub.
• No duplicate content with `docs/pgq-concepts.md` after the move.

Reporting

• Comment on this issue with restructure plan before pushing.
• Comment with commit SHA after each commit.
• Final comment: PR ready for REV review.

Style + anti-leak

CLAUDE.md rules. No GitLab/AR/sahmed mentions.

Don't merge

PR-only.

[NikolayS]

Restructure plan (before pushing)

Content moves as follows:

• README.md ## Three latencies becomes a ~5-line callout: one sentence naming the three latencies, a 3-bullet summary, and a link to docs/three-latencies.md. The current draft README section is too long (duplicates the concept doc prose); it will be trimmed to tease-only.
• docs/three-latencies.md (new file) receives the full explanation promoted from docs/pgq-concepts.md: problem framing, the three-latency table, the "end-to-end is tunable" subsection with tick-cadence table, load-behavior comparison, and when-to-pick guidance. This is a user-facing doc, not a glossary.
• docs/pgq-concepts.md retains its glossary role (event/batch/tick/consumer/ticker/tick-rule/per-queue-tuning). The ## Three latencies section added in the draft is removed and replaced with a one-line cross-reference pointing to the new dedicated page.
• docs/README.md gains a new entry under "For users" listing three-latencies.md.

No SQL, no code, no test changes.

[NikolayS]

Commit bf560ae — docs: promote three-latencies to dedicated page

• Created docs/three-latencies.md with full explanation (three-latency table, tunable e2e section, tick-cadence trade-off table, load behavior comparison, when-to-pick guidance).
• README ## Three latencies trimmed to a 5-line callout (3 bullets + link to the new doc).
• docs/pgq-concepts.md ## Three latencies body replaced with a 3-line cross-reference; no duplicate prose remains.
• docs/README.md updated to list three-latencies.md under "For users".

[NikolayS]

Ready for REV review. PR: #68

[NikolayS]

Reviewer flag addressed: the "or vice versa. They are independent." clause in the paragraph introducing latency #3 was physically incorrect — #3 ≥ max(#1, #2) by construction, so the reverse direction (sub-ms #3 while #1 or #2 takes seconds) is impossible.

Flagged sentence (removed):

"#3 is the one application behavior depends on (SLAs, retries, perceived staleness). You can have #1 and #2 in microseconds and still have #3 in seconds — or vice versa. They are independent."

Replacement:

"#3 is what application behavior depends on (SLAs, retries, perceived staleness). The trap: #3 is bounded below by #1 + #2, but the magnitude of #1 and #2 doesn't determine #3 — tick cadence and consumer poll interval do. You can drive #1 and #2 to microseconds and still have #3 in seconds because the ticker hasn't fired yet. The reverse — sub-ms #3 while #1 or #2 takes seconds — isn't possible: a message can't be visible to a consumer faster than it can be written and read."

Commit: 2fc23c8 on branch docs/three-latencies.

[NikolayS]

Second fix on the same branch: the doc claimed the TRUNCATE-style rotation extension to metadata tables (pgque.tick, pgque.subscription) was already implemented — it is not. That work is tracked in #61 / #62 (DRAFT) and has not yet merged.

Removed claim:

"...the metadata-table bloat is a separate story and is addressed by extending the same rotation pattern to those tables — at sufficiently high tick rates that mitigation becomes necessary."

Replacement:

"...the metadata-table bloat is a separate story. PgQue v0.2.0 has the same UPDATE pattern on the small subscription/tick tables as upstream PgQ — the bloat shape is bounded but real under sustained held-xmin. Extending TRUNCATE-style rotation to those tables is tracked in #61 / #62 and will land in a later release."

Commit: e6ac0df on branch docs/three-latencies.

[NikolayS]

Option A applied — forward-reference dropped. Commit: e774575. PR #68 ready for re-merge.

[NikolayS]

Dropped 'When to pick which' + 'Provenance' per user feedback. Commit: 06c0b6c. PR #68 ready for re-merge.

[NikolayS]

PR #68 merged — three-latencies doc shipped. Closing as done.