---
id: pg-fix-docs-alignment
name: Doc alignment — TLS posture, QueueOpts consumer obligations (review 002 Finding 6 remainder)
status: pending
depends_on: [pg-fix-forwarder-reconnect]
scope: single
risk: trivial
impact: isolated
level: implementation
tags: [wave-4-fixes, postgres-engine, docs]
---

## Description

The doc-alignment remainder of the wave-4 general review
(`docs/reviews/002-wave-4-general-review.md` §Finding 6 + §Minor
notes) — the items that live in docs rather than the code files the
other fix tasks own. (The scheduler and `sweep_expired` doc fixes are
NOT here — they ride `pg-fix-scheduler-resilience` and
`pg-fix-dedupe-cleanup`, their files' tasks.)

- **TLS posture honesty**: every connection (pooled `store.rs:161`,
  listener `store.rs:196`) is hardwired `NoTls`, but
  `forwarder.rs:53-57`'s doc says the pooled path "rides the
  consumer's Config sslmode" — misleading; a `sslmode=require` DSN
  fails at connect. v1 TLS is effectively unavailable. Fix both ends:
  correct the forwarder doc to match the code, and **`deployment.md`
  owns the statement** (v1 ships `NoTls` on all connection paths;
  TLS is a post-v1 deployment concern — the deployment matrix's
  honesty posture, ADR-016's spirit). Check the crate-level docs and
  `PgOpts` docs for the same claim while there.
- **QueueOpts numeric consumer-obligation note**: queue/`QueueOpts`
  numeric values are trusted unvalidated (negative
  `max_attempts`/visibility/retention stamp into rows verbatim; zero
  `max_attempts` self-dead-letters into churn). The ADR-023 domain
  table pins extents/durations/boundaries only, so this is not a
  defect — but a one-sentence doc note (consumer-obligation, like the
  visibility-budgeting one) prevents surprise. Home: `deployment.md`
  (the budget/consumer-obligation section), with a mirror sentence in
  `queue.rs`'s or `opts.rs`'s doc where the opts are documented.
- **Light mismatch sweep**: re-read the pg engine's doc comments
  touched by the fix batch (forwarder, tx, scheduler, store) for any
  *new* doc-behavior mismatch the fixes introduced — the fix tasks
  correct their own sites, this is the cross-file consistency pass.

Doc-only task: no code behavior changes; gates must stay green.

**Depends on `pg-fix-forwarder-reconnect`** only because the forwarder
doc being corrected is in the file that task restructures — land after
it and correct against the settled code.

## Acceptance Criteria

- [ ] `forwarder.rs`'s sslmode claim matches the code (`NoTls`
      hardwired); no other doc in the crate repeats the claim
- [ ] `deployment.md` states the v1 TLS-unavailable posture on all
      connection paths
- [ ] `deployment.md` (plus the opts' doc home) carries the
      QueueOpts numeric consumer-obligation note
- [ ] Cross-file doc sweep over the fix batch's touched files: no
      doc-behavior mismatch remains (grep-auditable claims spot-checked)
- [ ] `cargo build`, clippy `-D warnings`, fmt clean (doc-only change;
      tests unaffected)

## References

- docs/reviews/002-wave-4-general-review.md §Finding 6 + §Minor notes
  (TLS bullet, QueueOpts bullet)
- docs/architecture/deployment.md (the budget/consumer-obligation
  home; the visibility-budgeting note's precedent shape)
- docs/architecture/decisions/016-deployment-honesty.md (the honesty
  posture)
- docs/architecture/decisions/023-fourth-review-round.md (the domain
  table — why QueueOpts numerics are consumer-obligation, not defect)

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion