fix(clients): v0.2.0 data-safety + consumer alignment

[NikolayS]

Summary

Cross-driver fix to lock the v0.2.0 consumer contract on data-safety:
no driver may silently drop a message because of a missing handler or a
Nack failure, and the default max_messages matches the default
queue_ticker_max_count so a single Receive can drain a batch.

• Unknown event types are nacked by default in all three drivers,
  with an explicit opt-in to restore the previous warn+ack behaviour
  for allow-list filter patterns. This intentionally reverses
  PR fix(clients/python): consumer warns + acks unhandled event types #121's Python warn+ack default per the maintainer audit on
  Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 — see the rationale in Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136.
• Per-batch nack-failure tracking in Go and TS: if any nack errors,
  the final batch ack is skipped so PgQ redelivers via the existing
  batch lifecycle. Python was already correct via psycopg's
  with conn.transaction() rollback.
• Default max_messages raised to 500 in all drivers (matches
  default pgque.queue.queue_ticker_max_count).
• TypeScript: top-level undefined payload is coerced to JSON
  'null' (matches Python's None handling).
• Docs: new clients/README.md parity matrix; per-driver READMEs
  updated to describe the new defaults and options.

Per-driver changes

Python (clients/python/)

• consumer.py: new unknown_handler: Literal["ack", "nack"] = "nack"
  param. Default nacks unhandled types with reason
  "no handler for type=X". "ack" restores the previous WARNING +
  ack behaviour.
• consumer.py: default max_messages 100 → 500.
• tests/test_consumer.py: replace the warn+ack test with two new
  tests — test_consumer_nacks_unhandled_event_type (default; asserts
  retry-or-DLQ row appears AND next receive does not return the same
  msg_id) and test_consumer_acks_unhandled_event_type_when_opt_in
  (asserts no retry row, batch advances, warning emitted).
• README.md: documents the new default + the >= ticker_max_count
  recommendation.

Go (clients/go/)

• consumer.go: per-batch nackFailed tracking; ack skipped if any
  nack errored. Doc comments on HandlerFunc, Handle, Start
  updated to match runtime behaviour (Go client: Consumer docs describe the opposite handler/error semantics #142).
• options.go: new WithMaxMessages(n),
  WithUnknownHandlerPolicy(p) with UnknownHandlerPolicy enum
  (NackUnknown default, AckUnknown opt-in).
• pgque.go: default maxMessages = 500. Client.Nack now accepts
  variadic NackOptions (WithRetryAfter, WithReason); existing
  callers compile unchanged. New Client.SendBatch 1:1 wrapper for
  pgque.send_batch(text, text, jsonb[]).
• README.md: examples for the new options and SendBatch.

TypeScript (clients/typescript/)

• consumer.ts: per-poll nackFailed tracking; new
  unknownHandlerPolicy?: 'ack' | 'nack' (default 'nack').
• client.ts: shared encodeJsonbPayload coerces top-level
  undefined to JSON 'null' for send (and any future
  sendBatch).
• types.ts: extends ConsumerOptions with unknownHandlerPolicy,
  bumps default maxMessages to 500.
• test/: new tests for the ack-policy opt-in and undefined coercion.
• README.md: documents the new options and undefined semantics.

Cross-driver parity (clients/README.md, new)

• Capability matrix per driver
• Locked-in nack-default contract
• List of v0.2.1+ deferred items

Issues

Closes #134, #135, #136, #137, #142, #149.
References #138 (partial: variadic NackOptions land here, the
Subscribe/Unsubscribe/Ticker/ForceTick Go wrappers stay
deferred per maintainer), #144 (docs portion: parity matrix).

Out of scope (deferred to v0.2.1+): #140, #141, #143, #145, #147,
#148, #150, #151.

Test plan

• Python: PGQUE_TEST_DSN=... python3 -m pytest clients/python/tests/ → 41 pass, 1 pre-existing baseline
  failure (test_send_batch_none_payload_produces_json_null —
  missing conn.commit() between send_batch and force_tick,
  out of scope here).
• Go: PGQUE_TEST_DSN=... go test -race -count=1 ./clients/go/... → all pass (12.5s).
• TypeScript: PGQUE_TEST_DSN=... npm test in
  clients/typescript/ → 24/24 pass; npm run check (tsc
  --noEmit on src + tests) is clean.
• go vet ./clients/go/... clean.

Notes

• Reverses fix(clients/python): consumer warns + acks unhandled event types #121 (the warn+ack default that just merged) as
  pre-arranged by the maintainer / Clients: align unknown event type policy across Python, Go, and TypeScript consumers #136 audit. The opt-in
  unknown_handler="ack" keeps that behaviour available for the
  filter-style consumers that motivated fix(clients/python): consumer warns + acks unhandled event types #121.
• No SQL files touched.
• Existing Go Nack(ctx, batchID, msg) callers continue to compile
  (variadic options are appended, not required).

---

Generated by Claude Code

[NikolayS]

Closing — superseded by the per-driver split per the maintainer's "multiple agents" preference:

• docs(clients): cross-driver parity matrix #152 — cross-driver parity matrix doc (closes Leo's audit Clients: define and implement a cross-driver API parity matrix #144 docs portion)
• fix(clients/go): nack-fail handling, unknown-type policy, options, SendBatch #153 — Go data-safety + options + SendBatch
• fix(clients/typescript): nack-fail handling, unknown-type policy, undefined payload, safe max_messages default #154 — TypeScript data-safety + undefined payload + defaults
• fix(clients/python): nack unknown types by default + safe max_messages default #155 — Python nack-default + max_messages 500 + strong test assertions

Each PR has its own REV in flight. The work in this branch and the per-driver branches are equivalent in scope; the per-driver PRs are easier to review independently and align with the maintainer's stated preference.

No code is lost — all four targeted issues (#134, #135, #136, #149) are covered by the per-driver PRs above. Closing this branch and PR.

---

Generated by Claude Code