Umbrella: deep audit findings for Python, Go, and TypeScript drivers

[NikolayS]

Scope

Umbrella for the 2026-04-30 deep driver audit across:

• clients/python
• clients/go
• clients/typescript

Review goals:

• correctness against PgQue SQL semantics;
• alignment across all three drivers;
• “thin wrappers over SQL primitives / don't reinvent the wheel”;
• ease of use;
• tests that actually catch semantic regressions.

Local test evidence

TypeScript:

cd clients/typescript
npm run check
# ok

# Fresh temp DB with sql/pgque.sql installed:
PGQUE_TEST_DSN=postgresql:///... npm test
# 22 passed

Python:

# Fresh temp DB with sql/pgque.sql installed, temp venv:
python -m pytest -q clients/python/tests
# 39 passed, 2 failed

Go:

go test ./clients/go
# not run locally: go binary missing on review host

Go findings are from code inspection + SQL repros; CI should be used as the execution gate.

Filed issues

High/data-safety:

• Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134 — high-level consumers can skip unreturned batch rows when max_messages < batch size.
• Clients: Go/TypeScript consumers ack batch even when nack fails #135 — Go/TypeScript consumers ack batch even when nack() fails.
• Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 — unknown event type policy differs across Python/Go/TypeScript.
• Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137 — Python tests fail on fresh install / weak transaction assertions.

Driver/API alignment and ergonomics:

• Go client: add missing thin wrappers/options for parity and ease of use #138 — Go client missing thin wrappers/options for parity/ease-of-use.
• Clients: align typed error mapping across Python, Go, and TypeScript #140 — typed error mapping inconsistent/under-specified.
• Clients: expose explicit text-vs-JSON payload APIs consistently #141 — explicit text-vs-JSON payload APIs missing/inconsistent.
• Go client: Consumer docs describe the opposite handler/error semantics #142 — Go Consumer docs contradict runtime semantics.
• Clients: define behavior for SQL-valid NULL event type/payload #143 — define behavior for SQL-valid NULL event type/payload.
• Clients: define and implement a cross-driver API parity matrix #144 — define/implement cross-driver API parity matrix.
• TypeScript client: avoid process-global pg bigint parser mutation at import time #145 — TypeScript client mutates process-global pg bigint parser at import time.

Suggested order

1. Fix Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134 first. It affects all three high-level Consumers and can silently skip work.
2. Fix Clients: Go/TypeScript consumers ack batch even when nack fails #135 before relying on Go/TS consumers for retry/DLQ correctness.
3. Decide Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 once, then update docs/tests in all drivers.
4. Fix Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137 so Python CI is trustworthy.
5. Use Clients: define and implement a cross-driver API parity matrix #144 as the parity roadmap; individual implementation issues can branch from it.

Non-goals

This audit did not attempt to rewrite drivers or merge PRs. It documents defects and alignment gaps for red/green TDD fixes.

Additional TypeScript/pass-3 findings filed

• TypeScript consumer: use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency #147 — TypeScript Consumer should use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency.
• Clients: do not hide ack() no-op result in TypeScript/Go #148 — TypeScript/Go should not hide ack() no-op result.
• TypeScript client: top-level undefined payload is not JSON null as documented #149 — TypeScript top-level undefined payload is not JSON null as documented.
• Clients: define transactional consumer API/story for receive-process-ack #150 — define a transactional Consumer API/story for receive-process-ack across drivers.
• TypeScript client: ticker()/forceTick() discard SQL return values and docs misstate behavior #151 — TypeScript ticker() / forceTick() discard SQL return values and docs misstate behavior.

Updated suggested order:

1. Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134, Clients: Go/TypeScript consumers ack batch even when nack fails #135, TypeScript client: top-level undefined payload is not JSON null as documented #149 are correctness/data-safety first.
2. Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 is a product/API policy decision; unblock docs/tests after choosing.
3. Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137 makes Python CI trustworthy.
4. TypeScript consumer: use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency #147 and Clients: define transactional consumer API/story for receive-process-ack #150 affect high-level Consumer usability/latency semantics.
5. Clients: define and implement a cross-driver API parity matrix #144 coordinates parity; 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/Clients: do not hide ack() no-op result in TypeScript/Go #148/TypeScript client: ticker()/forceTick() discard SQL return values and docs misstate behavior #151 are implementation/API cleanup underneath it.

[NikolayS]

Critical re-review note — 2026-04-30

After re-checking the audit findings skeptically:

Still true / high priority

• Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134 remains a real correctness hazard. receive(max_return) limits returned rows, while ack(batch_id) finishes the full underlying batch. The effect is consumer-level skipping of unreturned rows, not global deletion, but it is still dangerous for high-level Consumers with default 100 vs default PgQue batch threshold 500.
• Clients: Go/TypeScript consumers ack batch even when nack fails #135 remains valid for Go/TypeScript. If a message is selected for nack() and nack() fails, later ack() can incorrectly advance the batch. This is an at-least-once safety issue, even if failure cases are less common.
• Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137 remains valid: Python tests fail on a fresh install and some tests violate send/tick/receive transaction boundaries.
• TypeScript client: top-level undefined payload is not JSON null as documented #149 remains valid: JSON.stringify(undefined) is not JSON 'null'.

Reclassified

• Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 is real alignment drift, but should be treated as a product/API policy decision rather than inherently a bug. If the intended Consumer model is “handlers are filters; unknown types are logged and acked,” Python is correct and Go/TS should align. If the intended model is “unknown means unprocessable,” Go/TS are closer. The issue was downgraded from bug to enhancement.

Lower-priority but still useful

• 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, Go client: Consumer docs describe the opposite handler/error semantics #142, Clients: define behavior for SQL-valid NULL event type/payload #143, Clients: define and implement a cross-driver API parity matrix #144, 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 are mostly parity/ergonomics/docs/API-shape issues. They still make sense, but they should not all block the immediate release. Use Clients: define and implement a cross-driver API parity matrix #144 to decide the minimum cross-driver surface, then close/defer the rest deliberately.

Release-blocker recommendation

Treat only these as immediate blockers unless product scope says otherwise:

1. Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134
2. Clients: Go/TypeScript consumers ack batch even when nack fails #135
3. Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137
4. TypeScript client: top-level undefined payload is not JSON null as documented #149
5. Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 decision only, not necessarily implementation

[NikolayS]

Closing as completed — all driver-audit leaves have a destination for v0.2.0 or v0.2.1.

Shipped (merged):

• Clients: high-level consumers can skip unreturned batch rows when max_messages < batch size #134 + Clients: Go/TypeScript consumers ack batch even when nack fails #135 + Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 — cross-driver data-safety alignment via 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 (nack-fail handling, unknown-handler policy default, max_messages default).
• Python client: tests fail on fresh PgQue install and encode weak transaction assertions #137 — Python test transaction discipline via test(clients/python): commit before force_tick in 2 tests #139 (and fix(clients/python): nack unknown types by default + safe max_messages default #155).
• Go client: Consumer docs describe the opposite handler/error semantics #142 — Go Consumer doc/runtime alignment via fix(clients): v0.2.0 data-safety + consumer alignment #156-track (fix(clients/go): nack-fail handling, unknown-type policy, options, SendBatch #153).
• Clients: define and implement a cross-driver API parity matrix #144 — parity matrix shipped via docs(clients): cross-driver parity matrix #152.
• TypeScript client: top-level undefined payload is not JSON null as documented #149 — TypeScript top-level undefined payload coercion via fix(clients/typescript): nack-fail handling, unknown-type policy, undefined payload, safe max_messages default #154.

v0.2.0 scope:

• Clients: align typed error mapping across Python, Go, and TypeScript #140 — typed errors: Python and TypeScript shipped earlier; Go portion now in PR fix(clients/go): typed errors for cross-driver parity (#140) #200.

Deferred to v0.2.1+ per #156's "v0.2.1 follow-ups":

• Go client: add missing thin wrappers/options for parity and ease of use #138 — Go missing thin wrappers (Subscribe/Unsubscribe/Ticker/ForceTick).
• Clients: expose explicit text-vs-JSON payload APIs consistently #141 — explicit text-vs-JSON payload APIs.
• Clients: define behavior for SQL-valid NULL event type/payload #143 — NULL ev_type/ev_data policy across drivers (a viable diff exists at fix(clients): handle NULL ev_type/ev_data per driver (#143) #199 if promoted).
• TypeScript client: avoid process-global pg bigint parser mutation at import time #145 — TS bigint global parser mutation (PR fix(clients/typescript): scope bigint parser to pgque pool (#145) #189 draft).
• TypeScript consumer: use PgQue LISTEN/NOTIFY wakeups instead of poll-only 30s latency #147 — TS LISTEN/NOTIFY wakeups (PR [POSTPONED post-v0.2.0] fix(clients/typescript): wake consumer on LISTEN/NOTIFY (#147) #194 draft).
• Clients: do not hide ack() no-op result in TypeScript/Go #148 — TS/Go ack rowcount surfacing (PR fix(clients): surface SQL ack() rowcount (TS+Go) (#148) #192 draft).
• Clients: define transactional consumer API/story for receive-process-ack #150 — transactional Consumer API.
• TypeScript client: ticker()/forceTick() discard SQL return values and docs misstate behavior #151 — TS ticker/forceTick SQL returns (PR fix(clients/typescript): surface ticker/forceTick SQL returns (#151) #188 draft).

The audit roadmap has done its job.

---

Generated by Claude Code