config: tenant-tree errors use four different Field spellings

[gaborage]

ADR-076 made a database section's normalization errors address themselves — ConfigError.Field reads databases.reporting.host or multitenant.tenants.acme.database.host instead of the root spelling. It deliberately stopped at the startup door. The result is a config package where a consumer can address some section failures and not others, and the split does not follow any line a consumer can see.

Where the spelling still doesn't match

The runtime door. database/manager.go (pool defaults for a dynamically-resolved tenant) and tools/migration/internal/commands/dbtls.go both hold the tenant key and both attach it by wrapping, leaving Field root-spelled. So the same tenant reports two different fields depending on how it was declared:

tenant declared	Field
statically, in multitenant.tenants.acme.database	multitenant.tenants.acme.database.tls
dynamically, via DBConfigProvider	database.tls (key only in the message)

C60.16 tells consumers to route per-tenant failures with strings.HasPrefix(cfgErr.Field, "multitenant.tenants."). That advice works for static tenants and silently never fires for dynamic ones — the worst shape for a routing rule.

The rest of the tenant tree. Three more spellings for sibling failures of the same tenant:

• tenant cache: wrapped as tenant <id> cache: …, Field left cache.*
• checkTenantMessagingConsistency: Field: "multitenant.tenants messaging" — a space, not a path
• NewMultiTenantError: Field: "tenant 'acme' database"

So Field is a koanf path for one failure class and prose for its neighbours.

Why it wasn't fixed in ADR-076

The connect door genuinely has no section — that is ADR-050's asymmetry, and #1025's brief explicitly excluded it. But the callers of the connect door do have the key, which is why this is worth deciding rather than assuming.

ADR-076's "Alternatives considered" names the shape that would dissolve this: give normalizeDatabaseValues the section (or a field prefix) so its errors are born addressed — one parameter at one seam, no prefix surgery, and Action gets built from the right head too (see the Action half in the companion issue). That refactor is the natural home for fixing the runtime door as well.

Suggested scope

1. Decide whether Field is a koanf path always, or prose sometimes — then make the tenant tree consistent with that answer.
2. If it is a path always, qualify at the two runtime-door call sites that already hold the key, and update C60.16's routing advice.

[gaborage]

This was generated by AI during triage.

Reopened: closed by a stray auto-close reference one second after #1115 merged — #1115's own body lists this issue under "Filed not fixed", and no code on main addresses it. Verified 2026-08-21 against daefb32.

[gaborage]

This was generated by AI during triage.

Agent Brief (covers #1113 + #1114 — one PR)

Category: bug
Summary: Complete ADR-076's story: dynamically-resolved tenant errors carry section-qualified Field spellings like static ones, and Action names an env variable that actually reaches the failing key — or stays silent when none can.

Status note: #1113 was closed by a stray auto-close reference one second after #1115 merged, with zero code addressing it (#1115's own body lists it "Filed not fixed") — it has been REOPENED as part of this triage; treat it as live.

Decisions (maintainer, triage grilling 2026-08-21):

• config: tenant-tree errors use four different Field spellings #1113 fixed at the depth ADR-076 itself names ("the better shape… normalizeDatabaseValues takes the section; if the runtime door is ever qualified too, this is where to start") — not by wrapping the two runtime call sites.
• config: ConfigError.Action names the root env var for a named section #1114 (Q7=a): compute the env hint via keyToEnvVar(qualifiedKey) ONLY when the inverse transform round-trips to the same koanf key; otherwise suppress the hint. Do NOT reject _/uppercase section names in this PR (legitimate follow-up issue — file it, don't build it).

Current behavior (verified on main daefb328):

• dbSection.qualify/qualifyField (config/database_section.go) run only from the three STARTUP doors. The runtime door — database/manager.go (ApplyDatabasePoolDefaults → normalizeDatabaseValues, never qualify) and its twin in tools/migration/internal/commands/dbtls.go — still emits root spellings for DBConfigProvider-resolved tenants, so C60.16's HasPrefix(Field, "multitenant.tenants.") routing fires for static tenants and never for dynamic ones (caveat already documented in C60.16; the fix makes it unnecessary).
• Three more unqualified spellings in the tenant tree: the tenant cache wrap (config/validation.go ~1850, Field left cache.*), Field: "multitenant.tenants messaging" (~1826), and config/errors.go tenant-store errors (five call sites in config/tenant_store.go).
• Action is hardcoded root literals (set DATABASE_PORT env var…) even for databases.reporting.port. Verified live: following that hint on a multitenant config CREATES a new failure (partial root block → ADR-047 incomplete-section abort). The correct variables ARE reachable: DATABASES_REPORTING_PORT and MULTITENANT_TENANTS_ACME_DATABASE_PORT both probe green through the blanket underscore→dot transform; keyToEnvVar (config/config.go) is the exact inverse and already used by injection. The trap: a section/tenant name containing _ (nothing forbids it) makes keyToEnvVar emit a variable that lands on a DIFFERENT key and manufactures a startup failure — hence the round-trip guard.

Desired behavior:

• One spelling rule for every database-section error regardless of door: dynamic tenant errors carry multitenant.tenants.<name>.database.<key>-shaped Fields (same predicate C60.16 teaches). The section-aware normalize is the single seam; the manager/dbtls wrappers stop re-wrapping with root spellings.
• The three other tenant-tree spellings qualified consistently.
• Action's env hint derived from the qualified field via keyToEnvVar, emitted only when envVar → transform → same key round-trips (lowercase, no _ in names); suppressed otherwise (the YAML-path half of Action stays, qualified).

Protocol: Field strings and Action text change for consumers matching on them ⇒ breaking: ! title, atom C60.19, addendum to ADR-076 (its scope-out paragraphs are superseded — update them the way ADR-062's consequences were). File the underscore-names follow-up issue and cross-reference it.

Acceptance criteria:

• A dynamic (DBConfigProvider) tenant's pool/TLS failure carries the same qualified Field a static tenant's does — pinned by a test through the manager door; dbtls twin covered.
• The C60.16 consistency test (qualifyField vs delivered-empty spelling) extended to the dynamic door.
• databases.reporting.port failure's Action names DATABASES_REPORTING_PORT; tenant case names MULTITENANT_TENANTS_ACME_DATABASE_PORT; both probed through real config.Load().
• Section name report_db ⇒ NO env hint (round-trip guard test); YAML-path hint still present and qualified.
• The three extra tenant-tree spellings qualified; no root DATABASE_* hint remains for any non-root section (grep-gated as a delta, not absolute count).
• ADR-076 addendum + C60.19; E60 assertions + marker grep; follow-up issue filed for underscore-name rejection.

Out of scope:

• Rejecting _/uppercase in section/tenant names (follow-up issue).
• Non-database tenant sections beyond the three named spellings.
• config: Int/Bool getters swallow present-but-empty keys #1111.