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)	completed	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

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).