ADR-0017 — Targets come from runtime env only #

• Status: Accepted
• Date: 2026-05-07
• Deciders: Natan
• Supersedes: ADR-0003

Context #

ADR-0003 made src/config/targets.ts choose a committed preset from SQA_ENV, then let env vars override individual fields. That worked when SQA only checked a public API URL and bucket name.

PRD-01 expanded SQA to external interfaces that are deployment coordinates and often credential-bearing DSNs: MongoDB, Redis, ClickHouse, Loki, Hatchet, and OpenRouter. At that point committed presets became the wrong abstraction:

• SQA is probing external systems, not selecting an internal app

runtime. Production, staging, development, and localhost targets are input data to the run.

• Credential-bearing values must never be committed.
• Placeholder production hosts create false confidence: the code looks

configured even when the actual run must be supplied by operators.

• A future run may compare multiple environments in one invocation;

that cannot be represented cleanly by one global SQA_ENV preset.

Decision #

All target coordinates come from runtime env. src/config/targets.ts contains no committed presets and no fallback target URLs. It simply maps validated env values into the targets object consumed by system flows.

Target env vars may be empty. Missing target coordinates are not a startup error; the corresponding component returns skip. This lets a partially configured run still report every configured probe while making unconfigured probes explicit in the Result tree. Credential fields follow each component's production contract: for example, ClickHouse permits an empty password when the configured user uses no password, while bearer-token probes skip when the token is empty.

SQA_ENV remains a run label for logs (production, staging, development, localhost). It does not choose URLs, buckets, hosts, users, tokens, or API keys.

Runtime env may come from .env, CI secrets, Apple Keychain wrappers, Kubernetes secrets, or another operator-controlled source. The source does not matter to SQA as long as src/config/env.ts receives the validated values at startup.

Consequences #

• Pro: No production, staging, or development target coordinates are

committed in code.

• Pro: Missing runtime targets are visible as skip outcomes

instead of silently using stale committed defaults.

• Pro: The config model can grow toward multi-target comparison

without fighting a one-env preset selector.

• Con: cp .env.example .env && make run may produce an all-skip

tree until real target env values are supplied.

• Con: make run-prod and make run-dev only set the run label

unless the caller also provides matching target env values.

• Falsifiability: Revisit only if SQA needs a committed target that

is demonstrably public, non-secret, and stable enough to be a product default. That exception should be captured in a new ADR.

See also #

• src/config/env.ts ↗ - validated runtime env.
• src/config/targets.ts ↗ - env-to-target

mapping with no presets.

• ADR-0002 - validate env at startup.