it_loopback_ir's daemon clamps at the -10 dBFS default, not the rig ceiling, when driving real ports

[mkovero]

Problem

When it_loopback_ir is routed through real ports (AC_LOOPBACK_OUT / AC_LOOPBACK_IN set), the daemon it spawns runs under an isolated HOME whose config is written by write_loopback_config (ac-rs/crates/ac-daemon/tests/it_loopback_ir.rs:270). That config sets no drive_max_dbfs, so the daemon falls back to the default ceiling of −10 dBFS (ac-rs/crates/ac-core/src/config.rs:18-19). The rig's own ceiling in ~/.config/ac/config.json is never read.

So on a rig, the only thing holding the sweep at the standing −40 dBFS is the request (AC_LOOPBACK_LEVEL_DBFS). .agents/rig.md → hard constraints says a request-side-only limit is not the interlock: the clamp must live in the config of the daemon actually running the session. plot_ir has honoured that clamp since #360, but this test's daemon gets it set 30 dB higher than the rig allows.

Observed 2026-09-14 on pupu (192.168.9.27) while verifying PR #441: AC_LOOPBACK_LEVEL_DBFS=-40 was the effective limit. scripts/rig/run-loopback-ir.sh in that PR adds a request-side refusal above the rig ceiling. That is a convenience, not the interlock, and does not fix this.

What must be true

• When the test drives real ports, its daemon's config carries a drive_max_dbfs that is not above the rig's standing ceiling. Where the value comes from (env var, reading the rig config, fixed −40) is a design choice for this issue.
• The self-loop route (jackd -d dummy, no port variables) keeps working unchanged.

What makes the check fail

A test must show that with real ports named and AC_LOOPBACK_LEVEL_DBFS set above the intended ceiling, the level that reaches the engine is the ceiling, not the request. A test that only asserts a key exists in the written config cannot go red on the harm case.

[mkovero]

spec

type: bug

problem statement
When it_loopback_ir runs against real ports (AC_LOOPBACK_OUT / AC_LOOPBACK_IN set), the daemon it spawns runs under an isolated HOME. The config written there has no drive_max_dbfs, so that daemon uses the default ceiling instead of the rig's standing ceiling. The only thing holding the sweep at a rig-safe level is then the request (AC_LOOPBACK_LEVEL_DBFS). Under .agents/rig.md → hard constraints, a limit set only in the request is not the interlock. The clamp has to be in the config of the daemon actually running the session. As things stand, one mistyped or missing env var puts a sweep on physical outputs at up to the default ceiling. Observed on pupu 2026-09-14 while verifying #441. The request-side refusal in #441's scripts/rig/run-loopback-ir.sh does not close this gap.

acceptance criteria

• When the test drives real ports, the daemon it spawns has a drive_max_dbfs in its config that is not above the rig's standing ceiling of −40 dBFS — provenance: assumed (operator policy bound from .agents/rig.md / drive-level consent rule, not a measured or derived quantity)
• Harm-case test: real ports named, AC_LOOPBACK_LEVEL_DBFS set above the intended ceiling. The level that reaches the engine is no higher than the ceiling. Either the daemon clamps it or the daemon refuses the request, whichever plot_ir already does under drive_max_dbfs governs set_drive alone — plot_ir and calibrate emit unclamped, and calibrate defaults to -10 dBFS #360. It must not be the requested level.
• The harm-case test must fail when the drive_max_dbfs in the written config is removed or set above the ceiling. A test that only checks that a config key exists does not meet this criterion.
• Self-loop route (jackd -d dummy, no port variables) behaves exactly as before and its existing tests pass unchanged.
• If the design picks a ceiling source that can be missing (env var, rig config file), a real-port run with no ceiling available does not fall back silently to the default. What it does instead (refuse, or use a fixed ceiling) is the architect's decision and is written into the test.

out of scope

• The request-side refusal in docs(rig): one runbook and scripts for testing binaries on a rig #441's scripts/rig/run-loopback-ir.sh (convenience only; stays as is).
• Changing the daemon-wide default ceiling in ac-core config.
• Machine enforcement of rig interlocks in ac-daemon / ac-cli in general (.agents/rig.md scopes that out).
• Other integration tests that spawn daemons under an isolated HOME. Fix only if the architect finds the same defect, and file it as a separate issue.

files likely affected

• ac-rs/crates/ac-daemon/tests/it_loopback_ir.rs — write_loopback_config and the new harm-case test
• ac-rs/crates/ac-core/src/config.rs — read only, to see where the default comes from; not expected to change
• unknown — rig docs or script, if the ceiling source becomes an env var the operator must set

needs architect review
yes. The issue leaves the ceiling source open: env var, reading the rig's ~/.config/ac/config.json, or a fixed −40 dBFS. Each choice fails differently when the value is missing. A silent fallback is its own defect class. That decision has to come before implementation.

estimated complexity
medium: 2–8h

[mkovero]

design decision

core question
Where does the real-port daemon's drive_max_dbfs come from, what happens when that source is missing, and how can a harm-case test go red without a rig?

Assumption, not in the spec: the harm-case test must run under plain cargo test, not --ignored. On this repo, a guard that only runs on the rig is a guard that does not run. That is possible: FakeEngine::start (ac-rs/crates/ac-daemon/src/audio/fake/mod.rs:181) takes any port names, so a --fake-audio daemon can run plot_ir against the exact config written for a real-port route.

option A — fixed −40 dBFS constant in the test, written only on the real-port route
Add a const RIG_DRIVE_CEILING_DBFS: f64 = -40.0 to it_loopback_ir.rs. Routing carries a drive_max_dbfs: Option<f64>: Some(RIG_DRIVE_CEILING_DBFS) when AC_LOOPBACK_OUT/IN are set, None on the self-loop. The config writer adds the key only when it is Some, so the self-loop config stays byte-for-byte what it is today. No new env var and no new operator input.
tradeoffs: This source cannot be missing, so criterion 5 is met by construction. A run with no ceiling cannot happen. The ceiling is visible in a diff. The cost: an authorized exception above −40 (.agents/rig.md allows one) cannot go through this test without a source edit. I count that as correct. rig.md wants the authorization recorded, and a committed change to a named constant is a stronger record than an env var. The rig-session-2 pattern (a daemon under a hand-written config) is still there for exception runs. Also, the pupu speaker ceiling (−50) cannot be enforced server-side this way.

option B — mandatory env var AC_LOOPBACK_DRIVE_MAX_DBFS, refused when missing or above −40
Real-port route panics before spawn if the var is missing or above −40. run-loopback-ir.sh passes RIG_DRIVE_CEILING_DBFS, or RIG_SPEAKER_CEILING_DBFS on --route speaker.
tradeoffs: This would move pupu's −50 speaker ceiling from script-only to a server-side clamp for this test, which is a real gain. The costs: it adds a third mandatory operator input, and that input can be missing, so it needs its own refusal path and its own test. It also changes the invocation that #441 (open, unmerged) documents and scripts. So both PRs would have to change the same interface in lockstep. And the −40 cap still has to be a constant in the test, so option A's constant exists either way.

option C — read the rig's own ~/.config/ac/config.json (rejected)
Config's serde default fills drive_max_dbfs with −10 when the key is absent (ac-rs/crates/ac-core/src/config.rs:18-19,94). So loading it through Config falls back silently to the very default this issue is about. Reading raw JSON avoids that, but it ties the test's safety to whatever is in the operator's home directory. The pupu profile does not list drive_max_dbfs in RIG_AC_CONFIG_EXPECT, so nothing checks that the key is there.

recommendation
Option A. .agents/rig.md places the interlock in "the config of the daemon actually running the session". The test writes that config itself, so the ceiling belongs at the point where the config is written, as a value that cannot be absent. An env var (B) or a foreign file (C) adds a missing-value case this issue would then have to handle.

This does not fix: pupu's speaker route stays clamped at −40 server-side. Its −50 ceiling is still enforced only by run-loopback-ir.sh --route speaker, same as today. Option B is the follow-up if that gap matters. File it separately; it is not part of this issue.

affected modules

• ac-daemon integration tests: it_loopback_ir.rs gains the ceiling constant, a pure routing constructor, a config builder split from the file write, an applied-level line in the record, and a non-ignored fake-audio harm-case test.
• ac-daemon test harness doc: common/mod.rs module doc says it_loopback_ir shares only alloc_ports/alloc_home, and that stops being true.
• rig docs/scripts: text saying the isolated-HOME daemon clamps only at the −10 default becomes false.

file manifest

ac-rs/crates/ac-daemon/tests/it_loopback_ir.rs
ac-rs/crates/ac-daemon/tests/common/mod.rs
docs/runbooks/loopback-ir.md
docs/runbooks/rig-testing.md
scripts/rig/run-loopback-ir.sh

interface changes

• ZMQ session schema: none.
• CLI flags: none.
• Cargo feature flags: none.
• Public function signatures: none. Test-private items only.
• Test env contract: unchanged. AC_LOOPBACK_OUT/IN/LEVEL_DBFS/DURATION_S keep their current meaning. AC_LOOPBACK_LEVEL_DBFS stays mandatory on the real-port route. A request above −40 is not refused by the test: the daemon clamps it, as plot_ir has since drive_max_dbfs governs set_drive alone — plot_ir and calibrate emit unclamped, and calibrate defaults to -10 dBFS #360 (apply_drive_ceiling, handlers/audio/plot.rs:646), and the record prints both numbers.

ZMQ protocol impact
no. The test reads the existing plot_ir sync reply level_dbfs and measurement/report → report.stimulus.level_dbfs. ac-cli and ac-view are unaffected.

implementation notes for developer

• Ceiling constant. Add a doc comment citing .agents/rig.md → hard constraints. Value −40.0 dBFS, provenance: assumed (operator policy, inherited from triage criterion 1).
• Routing::from_env (it_loopback_ir.rs:192-225). Split out a pure constructor that takes the four optional raw values, and make from_env a thin wrapper around it. The harm test must build a real-port Routing without std::env::set_var, because other tests in the binary run in parallel. The half-route panic and the mandatory-level expect stay in the pure constructor. Rewrite the expect message at :206-210: it still says plot_ir does not apply drive_max_dbfs, which has been false since drive_max_dbfs governs set_drive alone — plot_ir and calibrate emit unclamped, and calibrate defaults to -10 dBFS #360.
• write_loopback_config (:270-284). Split it into a builder that returns the serde_json::Value and a writer that saves it. Keep the self-loop's Value identical to today's. A small unit test that the self-loop config has no drive_max_dbfs key guards criterion 4. That is a key-presence check, which is fine here, but it is not the harm test.
• Harm-case test (non-#[ignore]d, in it_loopback_ir.rs). Model: plot_ir_clamps_level_to_drive_max_dbfs, ac-rs/crates/ac-daemon/tests/it_protocol/plot_ir.rs:104.
  • Build a real-port Routing with the pure constructor, using any two JACK-looking port names.
  • Pass the builder's Value to common::Daemon::spawn_with_config (common/mod.rs:161). That spawns --fake-audio and has the pid identity check. Do not reuse this file's spawn_jack: its readiness loop has no pid check, which a non-ignored parallel test needs. Refer to the harness types by path (common::Daemon, common::Client), because this file has its own Daemon/Client.
  • Request level_dbfs: 0.0 — provenance: derived. It has to be above the −10 default so that deleting the key changes the applied level, and above −40 so that any raised ceiling shows up.
  • Assert against a literal -40.0, not the constant. Otherwise raising the constant would carry the assertion along with it and stay green. Assert the sync reply level_dbfs == −40.0 and report.stimulus.level_dbfs == −40.0 (tolerance 1e-9, derived: apply_drive_ceiling is f64::min, which is exact). Also assert that neither equals the request.
  • Before approving, check that it goes red on each of three mutations: (1) delete the key from the builder, which gives −10; (2) set the constant to −30, which gives −30; (3) write the key on the self-loop branch only. Record the three red runs in the PR body.
• loopback_ir_recovers_sharp_peak (:445-455). After the plot_ir ack, print requested → applied in the record block and add drive_max_dbfs to describe(). describe() currently prints the request as if it were the level used. Add an assertion that applied ≤ ceiling on the real-port route. It is a record guard, not the interlock: the ack can come after emission starts. Say that in the comment next to it.
• Module doc (:32-41) and common/mod.rs:18-21. Update to match what now happens.
• docs(rig): one runbook and scripts for testing binaries on a rig #441 sequencing. docs(rig): one runbook and scripts for testing binaries on a rig #441 is open, and it edits this test file's doc comments and the same expect message. It also adds docs/runbooks/rig-testing.md (lines 106-112 and 162-164 on its branch) and a header comment in scripts/rig/run-loopback-ir.sh (lines 13-15). All three state the −10 isolated-HOME gap as current fact.
  • Branch from main explicitly.
  • If docs(rig): one runbook and scripts for testing binaries on a rig #441 merges first: rebase, and correct those three passages. The script's --level check stays as the convenience docs(rig): one runbook and scripts for testing binaries on a rig #441 describes it as. Change only the comment that calls it the thing holding the rig ceiling. docs/runbooks/loopback-ir.md is deleted by docs(rig): one runbook and scripts for testing binaries on a rig #441, so drop it.
  • If this merges first: update docs/runbooks/loopback-ir.md's "only limit on what reaches the converter" paragraph, and leave a comment on docs(rig): one runbook and scripts for testing binaries on a rig #441 naming the three passages it has to correct before merge.
• Out of scope, not the same defect. The module doc of ac-rs/crates/ac-daemon/examples/ir_probe.rs (lines 18-20) still says plot_ir ignores drive_max_dbfs. That probe connects to an already-running daemon and does not spawn one under an isolated HOME, so the stale text is a doc slip, not this defect. Leave it alone. The other isolated-HOME spawners (it_level_clamp, ac-cli's it_plot_ir, it_ensure_server, common::Daemon) all run --fake-audio, so none of them drive hardware. No separate issue is needed.

scope
scope-none. Matches triage's label.

risks

• Harm test passes for the wrong reason: it builds its own config instead of calling the production builder, so it cannot go red when the real writer loses the key. Mitigation: the test must use the same builder function Daemon::spawn_jack uses, and must show the three red runs listed above.
• An operator reads the fixed ceiling as blocking a legitimately authorized −30 run: Mitigation: the constant's doc comment says exceptions above −40 do not go through this test, and names the rig-session-2 hand-written-config pattern.
• docs(rig): one runbook and scripts for testing binaries on a rig #441 and this PR each merge with text that contradicts the other: Mitigation: the sequencing note above. QA checks the runbook/script passages against whichever base the PR lands on.
• A user reads the fix as closing the speaker gap: Mitigation: the "does not fix" line above. The PR body repeats it.

[mkovero]

Operator acceptance, relayed from a Claude Code session on 2026-09-14 (~22:15Z), in the operator's words: "-40 is accepted".

This accepts acceptance criterion 1's ceiling value, −40 dBFS, tagged assumed (operator policy from .agents/rig.md → hard constraints). It is now an operator-accepted value. The provenance tag stays assumed, because it is still policy, not a measurement.

Rig evidence for PR #445 at 799d7d8 is on the PR: #445 (comment)