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

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
pg-fix-docs-alignment	Doc alignment — TLS posture, QueueOpts consumer obligations (review 002 Finding 6 remainder)	pending	pg-fix-forwarder-reconnect	single	trivial	isolated	implementation	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