Correct stale env-var statements in engine/iouring/doc.go and the adaptive.Engine comment; ioUringViable ignores the tier cap

[FumingPower3925]

Stale statements to correct in engine/iouring and adaptive (found while writing #418's table)

Checked against main c08e30c:

1. engine/iouring/doc.go, CELERIS_IOURING_PBUF_COUNT. The doc says values "are clamped to [16, 32768]" and that non-power-of-two values "cause ring registration failure and automatic fallback". resolveBufRingCount actually rounds a non-power-of-two up to the next power of two and clamps to [1024, 32768] (bufRingCountMin = 1024).
2. engine/iouring/doc.go, CELERIS_IOURING_SEND_ZC. The doc says the "final default decision [is] pending measured cluster A/B benchmarks (celeris#465)". io_uring: probeSendZC can never detect copy-fallback — SEND_ZC enabled on every host regardless of NIC #465 is closed, and the default is decided: SEND_ZC is on wherever the startup probe finds it working.
3. The adaptive.Engine type comment says CELERIS_ADAPTIVE_START "disables the runtime switch". It only chooses the start engine: chooseStartEngine is the variable's only reader, and the controller still switches. The README (docs: state the TLS posture, document the tuning environment variables, and give overload a doc.go #677) and the docs site (docs: correct the engine tuning facts, add the recovery catalog row, show in-process HTTPS on std docs#71) now say this correctly.
4. Behaviour, not text: ioUringViable does not consult the tier CELERIS_MAX_IOURING_TIER caps to. With the cap at none on a 6.10+ kernel, Adaptive still treats io_uring as viable. Each promotion then fails to build the io_uring engine ("io_uring not available on this system") and backs off through abortStandbyBuild. That is safe, but it is repeated work plus a WARN per attempt. Consider treating a capped none as not viable.

Items 1-3 are comment-only. They wait until the #657 fix PRs have landed, because those PRs change both packages.

[FumingPower3925]

#694 fixes item 4 (the behaviour bug) with a failing-first test, and corrects items 1-3 plus the two stale pointers to #465 (doc.go:12-13, probe.go:294-295).

Item 4: ioUringViable ignored the tier (adaptive/engine.go:136-147)

• Mechanism. probe.capIOUringTier(p, None) clears IOUringTier and every feature flag, but not KernelMajor/KernelMinor. On a 6.10+ kernel, the "bundles era" branch alone returned viable. Two things followed:
  • the up-switch stayed enabled, so each promotion built an io_uring engine that iouring.New refuses and backed off with a WARN
  • a high-concurrency hint picked an io_uring start that fell back to epoll with a WARN
• Fix. ioUringViable checks p.IOUringTier.Available() first, which is iouring.New's own predicate.
• Failing first on GitHub's runner (kernel 6.17.0-1022-azure). Commit b3c8ee9 is the tests alone on 9f4d89b's code. CI run 36241380107, Adaptive job: 103 PASS, 4 FAIL, 0 SKIP.
  • TestIOUringViable_TierUnavailable: "io_uring tier None on a 6.12 kernel is viable".
  • TestNew_TierCapNoneNeverPromotes/{no-hint,high-concurrency-hint} (real probe.Probe() + New under CELERIS_MAX_IOURING_TIER=none): "the conns-per-worker UP switch is enabled". The hint case also logged WARN … io_uring start engine unavailable, falling back to epoll start.
• Fixed. db3cc3b, CI run 36241796802: 9/9 green, Adaptive job 107 PASS, 0 FAIL, 0 SKIP.
• Mutants (Docker golang:1.27, kernel 7.0.12):
  • fixed: 14/0/0
  • availability check removed: 4 FAIL, the same four as CI
  • check made too strong (< High): killed by the Base-tier control, because a base-capped engine is still buildable
• Wider than the env var: Docker's default seccomp profile, measured.
  • probe.ProbeWith leaves IOUringTier at its default None whenever ProbeIOUring fails (probe/probe.go:118-123), but it has already recorded the real kernel version. So a 6.10+ host where io_uring_setup is refused meets the same condition with no env var set.
  • docker-seccomp-probe.sh (golang:1.27, Docker's DEFAULT seccomp profile, kernel 7.0.12-linuxkit, no CELERIS_MAX_IOURING_TIER): probe.Probe() reports tier=none available=false. TestNew_TierCapNoneNeverPromotes, with its env cap removed, FAILS on b3c8ee9 (the tests alone on 9f4d89b's code): the up-switch is enabled and New logs at WARN. It PASSES on db3cc3b (the fix).
  • Control (docker-seccomp-control.sh): the same probe program with --security-opt seccomp=unconfined reports tier=optional available=true. The tier=none above therefore comes from the seccomp profile, not from the kernel or the VM.
  • So on 9f4d89b, the default Adaptive engine in a container under Docker's default seccomp profile, on a 6.10+ kernel, keeps its up-switch enabled (measured, above). Each promotion it then attempts fails to build io_uring and backs off with a WARN; that step is the issue's reading and was not measured here. fix(adaptive): treat io_uring capped to none as not viable; correct stale io_uring env docs (celeris#679) #694 fixes that case too.
  • kernel.io_uring_disabled: from reading only, not measured.

Items 1-3

1. CELERIS_IOURING_PBUF_COUNT (doc.go, and the envPbufCount comment in worker.go): a value that is not a power of 2 is rounded up to one and clamped to [1024, 32768] (resolveBufRingCount). It is not clamped to [16, 32768], and it does not fail ring registration.
2. CELERIS_IOURING_SEND_ZC (doc.go and resolveSendZCPolicy in probe.go): "auto" enables it wherever the startup probe passes. Whether that should stay the default is an open measurement owned by Measure #465: SEND_ZC on/off A/B on the real fabric with per-scenario CPU, both arches #585. The text does not say it is decided, and the pointers to io_uring: probeSendZC can never detect copy-fallback — SEND_ZC enabled on every host regardless of NIC #465 are gone.
3. adaptive.Engine comment: CELERIS_ADAPTIVE_START only chooses the start engine, and the controller still switches. Deterministic behaviour comes from Config.Engine.

Also: the doc.go line saying CI uses CELERIS_MAX_IOURING_TIER was wrong (no workflow sets it). The README row now says what none does to Adaptive.

Evidence and scripts: evidence/celeris-673-679-653-424/lane-20260926/679/.

This comment only reports. The issue closes when #694 merges.