docs(clients): cross-driver parity matrix

[NikolayS]

Summary

Adds clients/README.md with the cross-driver parity matrix called for in #144.

• v0.2.0 parity-must-have table covering connect/close, send, send_batch, receive, ack, nack (retry_after + reason), and Consumer (max_messages, unknown_handler policy) for Python / Go / TypeScript.
• Cells reflect what is on main today. Per-driver PRs are in flight to fill the TBD rows.
• v0.2.1 follow-ups subsection enumerates deferred audit items: Go client: add missing thin wrappers/options for parity and ease of use #138, Clients: align typed error mapping across Python, Go, and TypeScript #140, Clients: expose explicit text-vs-JSON payload APIs consistently #141, Clients: define behavior for SQL-valid NULL event type/payload #143, TypeScript client: avoid process-global pg bigint parser mutation at import time #145, TypeScript consumer: use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency #147, Clients: do not hide ack() no-op result in TypeScript/Go #148, Clients: define transactional consumer API/story for receive-process-ack #150, TypeScript client: ticker()/forceTick() discard SQL return values and docs misstate behavior #151.
• Cross-links to umbrella Umbrella: deep audit findings for Python, Go, and TypeScript drivers #146 and parity issue Clients: define and implement a cross-driver API parity matrix #144.

Closes the docs portion of #144. The implementation portion is covered by the in-flight per-driver PRs (fix/clients-python-v0.2.0, fix/clients-go-v0.2.0, fix/clients-typescript-v0.2.0).

Test plan

• No SQL or test files modified
• Doc-only change; renders as a GitHub-flavored Markdown table

---

Generated by Claude Code

[NikolayS]

REV review — PR #152 docs/clients-parity-matrix

Verdict: PASS (non-blocking nits only)

Reviewed head 4c6fd1b against base d66c16f. Doc-only change adding clients/README.md parity matrix. Skipped Security and Test analysis per REV rubric (docs change).

Bugs / cell accuracy vs current main

Cross-checked every row against the source on main:

Capability	Python (client.py/consumer.py)	Go (pgque.go/consumer.go)	TS (client.ts/consumer.ts)	Matrix	Verdict
connect / close	connect() + PgqueClient.close()	Connect() + Close()	connect() + Client.close()	✓/✓/✓	accurate
send	PgqueClient.send	Client.Send	Client.send	✓/✓/✓	accurate
send_batch	PgqueClient.send_batch present	absent	absent	✓/TBD/TBD	accurate
receive	PgqueClient.receive	Client.Receive	Client.receive	✓/✓/✓	accurate
ack	PgqueClient.ack	Client.Ack	Client.ack	✓/✓/✓	accurate
nack w/ retry_after+reason	both params	hardcoded '60 seconds', no reason	NackOptions { retryAfter, reason }	✓/TBD/✓	accurate (Go TBD lines up with #153)
Consumer max_messages	ctor kwarg	hardcoded 100 in consumer.go Receive call	opts.maxMessages	✓/TBD/✓	accurate
Consumer unknown_handler policy	acks + WARN log	nacks unknown msg	nacks unknown msg	TBD/TBD/TBD	see below

One ambiguity, non-blocking: the unknown_handler policy row is TBD for all three, but all three drivers already implement a policy on main today (Python: ack+warn; Go/TS: per-message nack). If the row means "user-configurable policy hook" (i.e. #138-style), the TBDs are fine — please add a footnote like "TBD = configurable policy hook; current default behavior differs per driver" so readers don't read TBD as "no behavior at all."

No cell is wrong vs main. No cell that should already be ✓ is mislabeled TBD.

Guidelines (CLAUDE.md)

• Naming: lowercase pgque for code refs, PgQue in prose — both used correctly.
• No leaked person names beyond what is already in source headers (Nikolay Samokhvalov, Marko Kreen via PgQ attribution); no GitLab/internal infra/Round/WI references.
• Conventional Commits: title docs(clients): cross-driver parity matrix ✓.
• No SECURITY DEFINER / search_path concerns (docs).

Docs

• Internal anchors render correctly as a GitHub-flavored Markdown table.
• Cross-links to umbrella Umbrella: deep audit findings for Python, Go, and TypeScript drivers #146 and parity issue Clients: define and implement a cross-driver API parity matrix #144 present and correctly framed ("closes the docs portion of Clients: define and implement a cross-driver API parity matrix #144"); deferred items (Go client: add missing thin wrappers/options for parity and ease of use #138, Clients: align typed error mapping across Python, Go, and TypeScript #140, Clients: expose explicit text-vs-JSON payload APIs consistently #141, Clients: define behavior for SQL-valid NULL event type/payload #143, TypeScript client: avoid process-global pg bigint parser mutation at import time #145, TypeScript consumer: use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency #147, Clients: do not hide ack() no-op result in TypeScript/Go #148, Clients: define transactional consumer API/story for receive-process-ack #150, TypeScript client: ticker()/forceTick() discard SQL return values and docs misstate behavior #151) listed with one-line scope.
• Tone matches the existing docs/ flat layout — short, present tense, no marketing.
• Legend mentions "N/A" but no row uses it; harmless.
• Nit: header says "v0.2.0 parity matrix" while the intro says "tracks parity" — consider adding the install version / date the matrix was captured at, since the doc is explicitly a main-snapshot.

Architecture (CLAUDE.md rule 3 / SQL 1:1 wrappers)

Every row in the matrix is a 1:1 wrapper over a pgque.* SQL primitive:

• send → pgque.send
• send_batch → pgque.send_batch
• receive → pgque.receive
• ack → pgque.ack
• nack → pgque.nack
• Consumer is a thin poll loop around receive + ack/nack; not a composite that reduces to multiple primitives in a non-obvious way.

No row implies a composite that hides multiple SQL calls behind one driver method. Aligned with rule 3. The v0.2.1 follow-ups (subscribe/unsubscribe/ticker/force_tick per #138, typed errors #140, send_text/send_json shape #141, NULL handling #143, bigint parser #145, LISTEN/NOTIFY #147, ack no-op #148, transactional consumer #150, ticker return values #151) are all wrapper- or shape-level concerns — appropriate for v0.2.1, not blockers for the v0.2.0 parity-must-have set.

Note: TS client.ts already implements subscribe/unsubscribe/ticker/forceTick on main, while #138 covers them as a v0.2.1 follow-up across all drivers. Consider a brief footnote that TS is partially ahead, so readers don't think those wrappers are missing everywhere.

Summary

Matrix is accurate against d66c16f. Cells correctly anticipate #153 (Go nack/Consumer), #155 (Python — already mostly ✓), #154 (TS — already mostly ✓). No blocking issues. Two non-blocking nits: clarify unknown_handler TBD semantics and note TS's existing subscribe/unsubscribe/ticker wrappers.

---

Generated by Claude Code

[NikolayS]

Updated the matrix to reflect the actual v0.2.0 ship state (commit 3bad71c).

All 7 TBD cells eliminated. Verified each row against origin/main source and the diffs in #153 / #154 / #155, then added two rows (subscribe/unsubscribe and ticker/force_tick) that the original matrix omitted but which are already shipped on TS main and deferred for Python/Go via #138.

Post-merge tally per driver:

• Python: 8 ✓ / 2 ✗ (subscribe + ticker deferred to v0.2.1 per Go client: add missing thin wrappers/options for parity and ease of use #138)
• Go: 8 ✓ / 2 ✗ (subscribe + ticker deferred to v0.2.1 per Go client: add missing thin wrappers/options for parity and ease of use #138)
• TypeScript: 9 ✓ / 1 ✗ (send_batch deferred to v0.2.1 per Go client: add missing thin wrappers/options for parity and ease of use #138)

Notes from the verification pass:

• TS subscribe / unsubscribe / ticker(queue?) / forceTick(queue) are all on main today (clients/typescript/src/client.ts lines 195-251) — promoted from TBD to ✓.
• Python send_batch and Consumer.max_messages are already on main — promoted from TBD to ✓.
• Python nack(retry_after=, reason=) is already on main (client.py:254-) — confirms ✓.
• Go gains SendBatch, WithMaxMessages, WithUnknownHandlerPolicy, and Nack(...NackOption) (with WithRetryAfter/WithReason) via fix(clients/go): nack-fail handling, unknown-type policy, options, SendBatch #153.
• TS gains unknownHandlerPolicy (and bumps default maxMessages 100 -> 500) via fix(clients/typescript): nack-fail handling, unknown-type policy, undefined payload, safe max_messages default #154; Python gains unknown_handler="nack"|"ack" via fix(clients/python): nack unknown types by default + safe max_messages default #155.

Header note added above the table makes the assumption explicit: "Status as of v0.2.0 (assumes PRs #153, #154, #155 merge as planned)." v0.2.1 follow-ups subsection retained and slightly expanded so #138 covers both the deferred Python/Go wrappers and the deferred TS send_batch.

---

Generated by Claude Code

[NikolayS]

Dropped the v0.2.1 follow-ups section from clients/README.md — that roadmap belongs in the linked issues, not the user-facing README. Kept a single one-line pointer (See #146 for the cross-driver audit umbrella.) in place of the former Related issues block.

Commit: 383e7c0
Diff: 1 insertion, 19 deletions (net -18)
CI: queued on 383e7c0 (PG 14/15/16/17/18, client-smoke, verify, claude-review).

---

Generated by Claude Code

[NikolayS]

Leo review — PR #152

Scope reviewed: clients/README.md at head 10d11a0.

BLOCKING

None found.

NON-BLOCKING

None.

POTENTIAL / watch later

• This matrix is intentionally a snapshot of current main. It will need updates as fix(clients/go): nack-fail handling, unknown-type policy, options, SendBatch #153/fix(clients/typescript): nack-fail handling, unknown-type policy, undefined payload, safe max_messages default #154/fix(clients/python): nack unknown types by default + safe max_messages default #155 or other client API parity PRs land.

Review notes

• Removed stale planned-state wording that assumed fix(clients/go): nack-fail handling, unknown-type policy, options, SendBatch #153/fix(clients/typescript): nack-fail handling, unknown-type policy, undefined payload, safe max_messages default #154/fix(clients/python): nack unknown types by default + safe max_messages default #155 would merge.
• Matrix now matches the public client API currently visible on main:
  • all three clients expose send/send_batch/receive/ack/nack basics
  • Python + Go lack first-class subscribe/ticker wrappers
  • Go lacks nack retry/reason options and max-messages option
  • Python still silently acks unknown types; Go/TypeScript avoid silent ack
  • configurable unknown-type policy is not yet exposed by any client on main
• The note about raw SQL fallback is useful and accurate.

Validation

• Rebased cleanly on current main.
• clients/README.md content assertions passed locally.
• git diff --check passed.
• CI is pending on the updated head.

Verdict: READY once CI is green.

[NikolayS]

Lifecycle / testing evidence for head 10d11a0

Updated this PR after rebasing on current main because the old matrix described a planned future state assuming #153/#154/#155 would merge. The document now tracks the public client API actually present on main.

Validation:

• Rebased cleanly on current main.
• Reviewed public client APIs in:
  • clients/python/pgque/__init__.py, client.py, consumer.py
  • clients/go/pgque.go, consumer.go, options.go
  • clients/typescript/src/client.ts, consumer.ts, types.ts, index.ts
• Local content assertions passed for the key matrix rows.
• git diff --check passed.
• CI green on head 10d11a0:
  • verify
  • PG14–18 SQL tests
  • Python client tests
  • Go client tests
  • TypeScript client tests

Review verdict: ready for maintainer approval / merge.

[NikolayS]

Update for head b584947

Expanded the matrix with useful API differences that were missing from the first pass:

• raw SQL escape hatch (conn / Pool() / rawPool)
• typed client errors
• lossless PostgreSQL bigint ID representation
• consumer wakeup model (LISTEN/NOTIFY vs polling)
• consumer poll interval option
• consumer retry delay option

These rows are based on the current public APIs in the Python, Go, and TypeScript clients on main.

Validation:

• Rebased/current with latest main.
• Local content assertions passed for the new rows.
• git diff --check passed.
• CI green on b584947:
  • verify
  • PG14–18 SQL tests
  • Python client tests
  • Go client tests
  • TypeScript client tests

Verdict remains: ready for maintainer approval / merge.