docs alignment: v1 TLS posture owned by deployment.md, QueueOpts numeric consumer-obligation notes (task pg-fix-docs-alignment, review 002 Finding 6 remainder)

- forwarder.rs's ListenerConnection doc corrected: NoTls is hardwired on
  every connection path (pooled, listener, reconnect) — the pooled path
  never rode the consumer's Config sslmode (a sslmode=require DSN fails
  at connect); grep-audited no other in-crate doc repeats the claim
- PgOpts doc carries the corrected one-line TLS pointer (engine-crate-
  docs posture, ADR-016 §2)
- deployment.md: new 'TLS posture (v1)' subsection (NoTls everywhere,
  sslmode=require DSN fails at connect, topology-level confidentiality
  is the v1 substitute, TLS a post-v1 deployment concern) and a new
  'Consumer-obligation notes on engine options' section carrying the
  QueueOpts trusted-as-given note with code-verified per-field symptoms
  (max_attempts <= 0: never claimed, dead-lettered at the next claim
  call's pre-claim sweep; negative visibility: instantly-reclaimable
  claims; negative retention: every dead row at the next sweep_expired)
  plus the PgOpts::max_size 0-guard counter-case; frontmatter advanced
- alkstore/src/opts.rs: QueueOpts struct doc mirrors the
  consumer-obligation note (ADR-023 §2 scoping: the domain table covers
  trait-surface arguments, not consumer-constructed constants)
- cross-file doc sweep over the fix batch's touched files (forwarder,
  tx, scheduler, store) found no further doc-behavior mismatch
- gates: cargo build / clippy --all-targets -D warnings / fmt --check
  all green (doc-only, no test touched)
This commit is contained in:
glm-5.3-flash committed 2026-10-10 05:08:27 +00:00
1 parent 40625090f6
commit 49face898d
5 files changed
+148 -14

No files matched your search

+55 -1
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-07 (ADR-021 — third review round: drop=rollback keeps pg pool accounting exact under error paths)
last_updated: 2026-10-10 (docs alignment — v1 TLS posture stated; QueueOpts numeric consumer-obligation notes)
---
# Deployment
@@ -82,6 +82,60 @@ engine-owned PostgreSQL schema (default `alkstore`, per-engine option)
— layout per [ADR-010](decisions/010-queue-semantics-depth.md) §8
(resolved from [queues.md](queues.md)'s namespace bullet).
### TLS posture (v1)
The pg engine hardwires `NoTls` on **every connection path** in v1 —
the pooled connections, the dedicated listener connection, and every
reconnect attempt alike; the engine does not ride the consumer's
`Config` sslmode setting, and a DSN carrying `sslmode=require` (or any
TLS demand) fails at connect. The listener's `NoTls` posture is
test-pinned in the type it carries
([ADR-004](decisions/004-postgres-driver.md)); v1 TLS should therefore
be treated as **effectively unavailable** — network confidentiality
between the process and the Postgres server must come from the
deployment topology itself (private network, egress rules, a local
unix socket or sidecar), not from driver TLS. Encrypting traffic
between engine and server is a **post-v1 deployment concern** (wire a
TLS connector through the pool and listener construction); until then
the boundary above is the honest statement, per
[ADR-016](decisions/016-deployment-honesty.md)'s spirit — the matrix
states the limitation rather than having code pretend otherwise.
## Consumer-obligation notes on engine options
Consumer-*constructed* numeric option values are **trusted as given —
the engine does not validate them against domain extents**. The
engine would be a second normative home for semantics the contract
deliberately leaves to the caller's constants; the
[ADR-023](decisions/023-fourth-review-round.md) §2 domain table
covers the trait-surface arguments, not these. This applies to the
queue stamps (`QueueOpts`: `visibility_timeout_s`,
`dead_letter_retention_s`, `max_attempts`) on both engines:
- Negative or zero `visibility_timeout_s` stamps claims whose deadline
is already past — every claim is instantly reclaimable (the
dual-execution window is the consumer's documented budget
[ADR-010](decisions/010-queue-semantics-depth.md) §2).
- Zero or negative `max_attempts` stamps rows the claim statement
never hands out — each is dead-lettered with reason "max attempts
exceeded" at the next claim call on that queue (the pre-claim
sweep's `attempts >= max_attempts` arm), i.e. the queue silently
discards its work.
- Negative `dead_letter_retention_s` deletes every dead row at the
next `sweep_expired` call (retention is driver-free — nothing runs
without a caller).
- The stamps ride *future enqueues only* (`QueueOpts`'s documented
shape) — repair the opts before enqueueing rather than repairing
rows afterwards.
The same trusted-as-given shape applies to `PgOpts::max_size`'s
*positive-integer* contract — 0 is typed-failed at open, the one knob
with an engine-side guard; everything above has none. The
consumer-obligation shape here is the visibility-budgeting precedent
([ADR-010](decisions/010-queue-semantics-depth.md) §2): the constant is
the consumer's, the behavior of a mis-set one is documented, nothing
runtime is fabricated.
## Durability knobs
| Engine | Knob | Shape |