ADR-0002 - Validate env at startup #

• Status: Accepted
• Date: 2026-05-07
• Deciders: Natan

Context #

The runner reads several env vars (SQA_ENV, LOG_LEVEL, LOG_FORMAT, SNAPPY_*). Two failure modes:

1. Late discovery. A typo in SQA_ENV surfaces only when the first

probe tries to look up its target URL - by which time we've printed logs, started a run, and confused the operator.

1. undefined propagation. Reading process.env.X directly returns

undefined for missing vars, which becomes "undefined" in a fetch URL or silently disables a feature, depending on the call site.

Both are §1.6(d) failures: nothing forces the env to be correct.

Decision #

A single src/config/env.ts module validates every env var with @t3-oss/env-core ↗ + zod and exports a typed env object. Defaults are encoded in the schema.

Forbidden elsewhere: process.env.X. The lint rule for this is informal (code review only) - promote to an ESLint rule if it ever gets violated.

Consequences #

• Pro: Bad config fails at startup with a structured error naming

the offending var. The operator sees it before any probe runs.

• Pro: Type-safety for env reads - env.SQA_ENV is a typed enum,

not string | undefined.

• Con: Adding a new env var is a two-step change (schema + caller).

Trivial cost, high benefit.

• Falsifiability: Revisit if the schema becomes a bottleneck for

rapid iteration (e.g. you're shipping new probe vars weekly without a release cycle). Until then, validate.