suaveplan/openspec/archive/2026-04-19-enterprise-env/proposal.md

# OpenSpec Change: enterprise-env

- **Change ID**: enterprise-env
- **Package**: `@suaveplan/env`
- **Category**: universal
- **Target path**: `packages/universal/env`
- **Status**: PROPOSED
- **Date**: 2026-04-19
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/env.md`

## Summary

Greenfield implementation of `@suaveplan/env` for the genesis branch. The existing main-branch env package provides the baseline public-API surface to preserve; this change delivers enterprise-grade type-safe environment variable loading with schema-first validation, a rich set of typed field builders (string, number, boolean, enum, URL, email, port, JSON, array), pluggable loaders (dotenv file, plain object), common presets for server apps, structured errors with `ENV.*` codes, Zod schemas, OTel instrumentation, property-based tests via fast-check, and benchmarks.

## Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

## Available workspace deps on genesis

| Package | Available |
|---------|-----------|
| `@suaveplan/error` | ✅ |
| `@suaveplan/types` | ✅ |
| `@suaveplan/logger` | ✅ |
| `@suaveplan/opentelemetry` | ❌ not yet built — use `@opentelemetry/api` directly |
| `@suaveplan/schema-registry` | ❌ not yet built — export Zod schemas directly |

External deps (via catalog):

- `zod` → `catalog:forms`
- `@opentelemetry/api` → `catalog:observability`
- `tslib` → `catalog:build`

Dev deps (via catalog):

- `vitest`, `@vitest/coverage-istanbul` → `catalog:testing`
- `fast-check` → `catalog:testing`
- `mitata` → `catalog:testing`

## Preserved public API surface (from main branch)

### Constants

- `DEFAULT_ARRAY_SEPARATOR` — default delimiter used by `ArrayField`
- `EMAIL_PATTERN` — regex for RFC-5322-compatible email validation
- `FALSY_VALUES` — string values coerced to `false` by `BooleanField`
- `INTERPOLATION_PATTERN` — regex matching `${VAR}` tokens in raw values
- `PORT_MAX` — upper bound for valid TCP port (65535)
- `PORT_MIN` — lower bound for valid TCP port (1)
- `TRUTHY_VALUES` — string values coerced to `true` by `BooleanField`

### Core

- `createEnv(schema, options?)` — loads env vars through configured loaders, validates all fields, collects or throws errors, returns typed record
- `CollectedErrors` — map of field key → array of error messages produced during a collect-mode run
- `EnvResult<S>` — the resolved typed record produced by `createEnv`
- `BaseField<T>` — abstract base class for all field builders; holds rules, default, sensitive flag, description
- `FieldConfig<T>` — runtime configuration snapshot extracted from any `BaseField`
- `RuleOptions` — options accepted by `BaseField.rules()` for adding a named validation rule
- `maskSensitive(values, schema)` — replaces sensitive field values with `***` in the result map
- `validate(input)` → `ValidationResult` — runs all rules for a single field, accumulating failures
- `ValidateInput` — `{ key, raw, field, coerced? }` fed into `validate`
- `ValidationResult` — `{ ok, errors }` where `errors` is an array of `{ rule, message }` pairs

### Types

- `AnyField<T, R>` — minimal interface every field builder satisfies; used for schema maps
- `CreateEnvOptions` — options accepted by `createEnv`: `loaders`, `errorMode`, `signal?`
- `EnvError` — `{ key, message, value? }` shape for a single validation failure
- `EnvSchema` — `Record<string, AnyField>` used as the schema argument to `createEnv`
- `ErrorMode` — `'throw' | 'collect' | 'warn'`
- `InferEnv<S>` — maps an `EnvSchema` to the resulting typed record type
- `InferFieldType<F>` — extracts the value type from a field builder
- `Loader` — `{ name: string; load(): LoaderResult }` interface for env sources
- `LoaderResult` — `{ values: Record<string, string>; source: string }`
- `OptionalKeys<S>` — keys whose fields may produce `undefined`
- `RequiredKeys<S>` — keys whose fields always produce a value
- `Simplify<T>` — intersection flattener utility type
- `ValidationRule<T>` — `{ name, message, validate(value): boolean }`

### Fields

- `StringField` / `str` — string field builder; rules: `minLength`, `maxLength`, `pattern`, `nonempty`
- `NumberField` / `num` — number field; rules: `min`, `max`, `integer`
- `BooleanField` / `bool` — boolean field; coerces TRUTHY_VALUES / FALSY_VALUES strings
- `EnumField<V>` / `enums` — enum field locked to a declared `EnumValues` tuple
- `EnumValues` — string-tuple type constraint for `EnumField`
- `UrlField` / `url` — URL field; validates via `URL` constructor, optional protocol restriction
- `EmailField` / `email` — email field; validates against `EMAIL_PATTERN`
- `PortField` / `port` — port field; integer in `[PORT_MIN, PORT_MAX]`
- `JsonField<T>` / `json` — JSON field; accepts a `JsonValidator<T>` for runtime shape checking
- `JsonValidator<T>` — `(parsed: unknown) => T` used with `JsonField`
- `ArrayField<T>` / `array` — array field; splits by `DEFAULT_ARRAY_SEPARATOR` (or custom), maps each item through an `ItemField`
- `ItemField<T>` — per-element field descriptor for `ArrayField`

### Loaders

- `dotenvLoader(options?)` — reads a `.env` file from disk and returns a `LoaderResult`
- `parseDotenv(content)` — pure function: parses a dotenv-format string into a `Record<string, string>`
- `DotenvLoaderOptions` — `{ path?, encoding?, override? }`
- `objectLoader(obj, options?)` — wraps an in-memory object as a loader
- `ObjectLoaderOptions` — `{ source? }` (source label for diagnostics)

### Presets — common

- `nodeEnvField` — `NODE_ENV` enum field locked to `'development' | 'test' | 'production' | 'staging'`
- `portField` — `PORT` with default 3000
- `hostField` — `HOST` with default `'0.0.0.0'`
- `logLevelField` — `LOG_LEVEL` enum locked to standard logger levels
- `debugField` — `DEBUG` boolean with default `false`
- `appNameField` — `APP_NAME` required string
- `appVersionField` — `APP_VERSION` string with default `'0.0.0'`
- `timezoneField` — `TZ` string with default `'UTC'`
- `workersField` — `WORKERS` integer number
- `commonFields` — composite preset: `nodeEnvField + portField + hostField + logLevelField + debugField`

### Presets — server

- `databaseUrlField` — `DATABASE_URL` sensitive required URL
- `redisUrlField` — `REDIS_URL` sensitive URL
- `sessionSecretField` — `SESSION_SECRET` sensitive required string with `minLength: 32`
- `corsOriginField` — `CORS_ORIGIN` string or array
- `rateLimitMaxField` — `RATE_LIMIT_MAX` integer number
- `rateLimitWindowField` — `RATE_LIMIT_WINDOW_MS` integer number
- `trustProxyField` — `TRUST_PROXY` boolean with default `false`
- `smtpHostField` — `SMTP_HOST` string
- `smtpPortField` — `SMTP_PORT` port field
- `smtpUserField` — `SMTP_USER` string
- `smtpPassField` — `SMTP_PASS` sensitive string
- `smtpFromField` — `SMTP_FROM` email field
- `serverFields` — composite: common server connection + SMTP fields

### Transforms (coerce utilities)

- `coerceString(raw)` — identity / trim
- `coerceNumber(raw)` — parses float, rejects NaN
- `coerceInteger(raw)` — parses integer, rejects non-integer
- `coerceBoolean(raw)` — maps truthy/falsy string sets
- `coerceArray(raw, separator?)` — splits and trims
- `coerceJson(raw)` — `JSON.parse` with structured error on failure
- `CoerceFn<T>` — `(raw: string) => T`
- `CoerceEntry<T>` — `{ coerce: CoerceFn<T> }` mixin used internally

### Utilities

- `EnvValidationError` extends `SuaveplanError` — thrown in `'throw'` error mode
- `MissingEnvError` extends `SuaveplanError` — thrown when a required key is absent
- `CoercionError` extends `SuaveplanError` — thrown when coercion fails for a raw value
- `DotenvParseError` extends `SuaveplanError` — thrown by `parseDotenv` on malformed input
- `createEnvError(key, message, value?)` — factory for `EnvError` value objects
- `interpolate(template, values)` — resolves `${VAR}` tokens in a string from a values map
- `hasInterpolation(value)` — returns `true` if the string contains any `${VAR}` tokens
- `extractVariables(template)` — returns the list of variable names referenced in a template string

## New genesis additions

### Structured errors

- `EnvError` base class extends `SuaveplanError` with codes under the `ENV.*` namespace registered via `defineCodes`
- Codes:
  - `ENV.VALIDATION_FAILED` — one or more fields failed validation rules
  - `ENV.MISSING_REQUIRED` — a required field has no value and no default
  - `ENV.INVALID_FORMAT` — coercion of a raw string to the target type failed
  - `ENV.PARSE_ERROR` — dotenv file parse failed or JSON parse failed
- `EnvValidationError`, `MissingEnvError`, `CoercionError`, `DotenvParseError` all extend `EnvError` using the appropriate code
- All errors carry `{ key, raw?, source? }` context for diagnostics

### Zod schemas

- `FieldConfigSchema` — validates the `FieldConfig<unknown>` shape at runtime
- `ValidationResultSchema` — validates `{ ok, errors }` produced by `validate`
- `EnvResultSchema` — validates the merged output record from `createEnv`
- `CreateEnvOptionsSchema` — validates options passed to `createEnv`
- `DotenvLoaderOptionsSchema`, `ObjectLoaderOptionsSchema` — validates loader options at the boundary
- All schemas exported from `*.schemas.ts` sibling files

### OTel instrumentation on createEnv

- Counter `env.validation.total` (labels: `outcome: 'success' | 'error'`) — incremented once per `createEnv` call
- Counter `env.validation.errors` (label: `field`) — incremented once per field that fails validation
- Histogram `env.load.duration_ms` — duration of the full `createEnv` call including all loaders
- All meters via `@opentelemetry/api`; no-op without exporter

### Property-based tests (fast-check)

- Field parsers round-trip: `coerce(raw)` produces a stable value for all valid `raw` strings
- `maskSensitive` never leaks values: for any schema with sensitive fields, the masked output never contains the original raw value at that key
- `validate` accumulates all errors: if N rules fail, `ValidationResult.errors.length === N`
- `parseDotenv` is pure: same input always yields same output

### Benchmarks (mitata)

- `createEnv` with a 20-field schema, object loader, no errors — hot-path throughput
- `validate` hot path — single field with 5 rules, all passing

## Impact

- Adds one new package: `packages/universal/env`
- Adds one new spec capability: `env`
- No existing package consumers on genesis yet