# SPEC — F-004 Typed config and feature flags

## Problem
Risky features need activation separate from deployment; env access must be typed.
Today env access is ad-hoc (`process.env.X ?? fallback` scattered in entrypoints)
and there is no activation mechanism distinct from deploy.

## Goal
Fail-fast typed config plus a simple feature flag module behind an interface.

## Scope IN
- Typed env config loader in `src/infrastructure/config`, fail fast on missing/invalid required vars (all problems reported in one clear message)
- `FeatureFlagProvider` interface with simple in-memory store implementation (`src/modules/flags`)
- Deployment ≠ activation: flags seed from `FLAG_*` env vars at boot and can be mutated at runtime without redeploy
- DB pool refactor to consume config instead of sniffing env itself

## Scope OUT
- No external flag service
- No per-user segmentation
- No admin HTTP endpoint for flags yet (first consumer decides shape; store API is runtime-mutable already)

## Required vs optional vars
| Var | Required | Default |
|---|---|---|
| DATABASE_URL | yes | — |
| PORT | no | 3000 (valid: integer 1–65535) |
| HOST | no | 0.0.0.0 |
| LOG_LEVEL | no | info |
| NODE_ENV | no | development (valid: development/test/production) |
| REDIS_URL | no | undefined |
| FLAG_<NAME> | no | parsed as true/false |

## Acceptance criteria
1. Given a missing required env var When the app starts Then startup fails with a clear message naming the var.
2. Given flag off When a code path guarded by the flag runs Then the path is skipped.
3. Flag state change does not require redeploy (runtime `setEnabled` on the store).
4. `./scripts/verify.sh` green.

## Non-functional
- No new dependencies: hand-rolled validation is small, explicit and boring.
- Config loader is a pure function of an env object (testable without touching process.env).