alkstore/tasks/pg-fix-docs-alignment.md

---
id: pg-fix-docs-alignment
name: Doc alignment — TLS posture, QueueOpts consumer obligations (review 002 Finding 6 remainder)
status: completed
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

- [x] `forwarder.rs`'s sslmode claim matches the code (`NoTls`
      hardwired); no other doc in the crate repeats the claim
- [x] `deployment.md` states the v1 TLS-unavailable posture on all
      connection paths
- [x] `deployment.md` (plus the opts' doc home) carries the
      QueueOpts numeric consumer-obligation note
- [x] Cross-file doc sweep over the fix batch's touched files: no
      doc-behavior mismatch remains (grep-auditable claims spot-checked)
- [x] `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

Decisions of record the implementation made that the description
didn't pin:

- **The QueueOpts mirror landed in core's `alkstore/src/opts.rs`,
  not the pg crate** — the description offered "`queue.rs`'s or
  `opts.rs`'s doc where the opts are documented"; the pg crate's
  `opts.rs` documents `PgOpts` (no `QueueOpts` mention), and
  `QueueOpts`' doc home is core's opts module, which both engines'
  consumers read. The mirror (trusted-as-given numerics, pointer to
  deployment.md) went on the `QueueOpts` struct doc there. The pg
  `PgOpts` doc got a one-line TLS pointer instead (v1 hardwires
  `NoTls` on every path; deployment.md carries the statement) — that
  is the engine-crate-docs posture ADR-016 §2 pins, and `PgOpts` is
  where a consumer meets the config split.
- **Per-field behaviors verified against code before writing the
  symptoms** (the review's "self-dead-letters into churn" was
  imprecise): `max_attempts <= 0` rows are *never claimed* — the
  claim statement's `attempts < max_attempts` conjunct excludes them
  and the pre-claim sweep (`attempts >= max_attempts`) dead-letters
  each at the next claim call on its queue; negative
  `dead_letter_retention_s` deletes *every* dead row at the next
  `sweep_expired` (`died_at <= now - retention` with retention < 0 is
  always true; the sweeper is caller-driven, retained in the doc's
  wording); negative/zero `visibility_timeout_s` stamps
  past-deadline claims (instantly reclaimable). The SQLite engine's
  `resolution.rs` stamps identically, so the "both engines" framing
  is verified, not asserted.
- **deployment.md gained a `Consumer-obligation notes on engine
  options` section** (after Connection budgets, before Durability
  knobs) rather than extending an existing list — the
  visibility-budgeting precedent lives in core-contract.md, and
  this document did not yet have an obligations home; the section
  closes the QueueOpts note and records the one counter-case
  (`PgOpts::max_size`'s 0-guard, `pg-fix-open-path`'s) so the
  trusted-as-given posture is bounded, not blanket. The TLS
  statement is a `TLS posture (v1)` subsection under Connection
  budgets.

## Summary

Doc-only alignment landed (review 002 Finding 6's remainder):

- **`alkstore-postgres/src/forwarder.rs`** — the `ListenerConnection`
  doc no longer claims the pooled path "rides the consumer's
  `Config` sslmode"; it now states `NoTls` is hardwired on *every*
  connection path (pooled, listener, reconnect) and deployment.md
  owns the statement. Grep-audited: no other doc in the crate (crate
  docs, `PgOpts`, `open`) repeats the false claim — `PgOpts` gained
  the corrected TLS pointer.
- **`docs/architecture/deployment.md`** — new `TLS posture (v1)`
  subsection (NoTls everywhere; `sslmode=require` DSN fails at
  connect; topology-level confidentiality is the v1 substitute;
  post-v1 concern; ADR-016 spirit) and new
  `Consumer-obligation notes on engine options` section (the
  QueueOpts numeric trusted-as-given note with the three verified
  per-field symptoms + the `max_size` guard counter-case);
  `last_updated` frontmatter advanced.
- **`alkstore/src/opts.rs`** — `QueueOpts` struct doc carries the
  mirror sentence (trusted-as-given, the ADR-023 §2 scoping, pointer
  to deployment.md for symptoms).
- **Cross-file sweep** (forwarder/tx/scheduler/store, the fix batch's
  touched files): re-read the module docs against the settled
  post-fix code — reconnect retry core, fanout release guard,
  stale-generation reconcile (forwarder); commit-atomic wakes and
  drop=rollback (tx); quarantine + retry + TTL-lapse posture (scheduler);
  open-path guard and DSN-options append (store). No mismatch
  beyond the TLS claim found; the review's scheduler/`sweep_expired`
  doc fixes had already landed with their own fix tasks.
- **Gates**: workspace `cargo build`, `cargo clippy --all-targets --
  -D warnings`, `cargo fmt --check` all green (doc-only change; no
  test touched).