fix(config): keep an explicit false/0/"" from config.yaml

[EricAndrechek]

Fixes #631.

What was wrong

Each boot-config default lived in a cleanenv env-default tag. cleanenv applies those after the YAML decode, to any field that is still at its zero value. So it could not tell a key the file set to false/0/"" apart from a key the file left out. otel.traces.enabled: false loaded as true, and sample_rate: 0 loaded as 1.0. Nothing reported it.

The fix (direction 1 from the issue)

• internal/config/config.go: a new unexported defaults() is now the only place defaults are defined. Load starts from it, cleanenv decodes the YAML over it, and then applies the WH_* variables. Precedence is still env > YAML > default. All env-default tags are gone. The env tags are unchanged, so unboundEnv, rejectUnknownKeys and TestEnvSettingsDir_MatchesStructTag behave exactly as before.
• I did not choose direction 2 (record which keys the file set, then restore them after cleanenv). It would keep the defaults in tags and add a second pass that has to stay in step with cleanenv. Direction 1 removes the cause and is smaller.

Behaviour change

A zero value you write in config.yaml now takes effect. If your file relied on the bug:

• sample_rate: 0 now exports no traces, or no DEBUG/INFO logs. Before, it silently exported everything.
• A signal set to enabled: false is now off.
• shutdown_timeout: 0 now skips the drain.
• cache.l1_max_cost: 0 now refuses boot with cache init: MaxCost can't be zero. server.port: 0 and data_dir: "" also refuse boot. An empty prometheus.path refuses boot when Prometheus is enabled.

To get the default back, delete the key. Env vars already honoured an explicit zero, so they are unchanged. This is described under Fixed in the CHANGELOG.

Tests (internal/config/defaults_test.go, all through config.Load)

• TestLoad_YAMLZeroIsKept: for each key in the issue's table, a YAML false/0/"" comes back unchanged. This is the case that fails if defaults are applied again after the decode. I confirmed it: with the old loader it fails, and so do TestLoad_IssueReproFile, TestLoad_YAMLZeroPortIsRefused and TestConfig_NoEnvDefaultTags.
• TestLoad_IssueReproFile: loads the issue's repro file as written.
• TestLoad_AbsentKeyGetsDefault: when the file exists but leaves a key out, that key gets its default.
• TestLoad_EnvWinsOverYAMLZeroAndDefault: env wins over a YAML zero, an env zero wins over a YAML value, and an env zero wins over the default when there is no file.
• TestZeroCases_CoverEveryNonZeroDefault: a new non-zero default without regression coverage fails this test.
• TestConfig_NoEnvDefaultTags: refuses any env-default tag.
• TestDocs_DefaultsMatchCode: each Config field has exactly one row in configuration.mdx. The row must name the field's env var, and its Default column must parse to the value in defaults(). Doc rows with no matching field also fail.

Deliberately left out

• PR feat(config): cache.backend=redis selects the shared cache #630's -1 sentinel for cache.redis.compress_min_bytes. Once this lands, 0 could mean "never compress". That change belongs to feat(config): cache.backend=redis selects the shared cache #630's owner.
• Adding a Validate check for cache.l1_max_cost <= 0. Ristretto already refuses 0 at boot, and a new check would break every test that builds a Config literal without a cache block.

Reviewers

• pre-push-reviewer (opus), at 252ef7b: ship_it, with 0 MUST, 0 SHOULD and 0 MAY findings. It read cleanenv v1.5.0's source to confirm the precedence. It also checked that no shipped config file (config.yaml, tests/e2e/fixtures/config.yaml, deployments/compose/standalone.yaml) relied on the bug.
• docs-reviewer (opus), at 252ef7b: ship_it, with 0 findings.

Gate gap #454: reviewer markers land in the main checkout, not this worktree.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EJr5tY4WQUy2sc4MbW67vL

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 255328ad-972a-48eb-8dde-623fe3916a07

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Docs preview is live → https://6e1fc77c-wavehouse-docs.wave-rf.workers.dev

• Commit — 40b5038: Merge remote-tracking branch 'origin/main' into fix/config-yaml-zero
• Author — @EricAndrechek
• Committed — 2026-09-25 18:30 (UTC-04:00)
• Deployed — 2026-09-25 18:39 EDT

[github-code-quality]

Code Coverage Overview

Languages: Go

Go

The overall line coverage in commit 40b5038 in the fix/config-yaml-zero branch is 94%. The line coverage in commit 0cbb386 in the main branch is 93%.

Show a line coverage summary of the most impacted files.

File	main 0cbb386	fix/config-yaml-zero 40b5038	+/-
internal/mq/embedded.go	88%	89%	+1%
internal/ingest/worker.go	97%	98%	+1%
internal/config/config.go	94%	97%	+3%

---

_{Updated September 25, 2026 22:39 UTC}