Initial Commit

openspec/archive/2026-05-02-env-spec-conformance/specs/env/spec.md

@@ -0,0 +1,33 @@
+# Capability Spec Delta: env-spec-conformance
+
+**Package**: `@suaveplan/env`
+**Change**: env-spec-conformance
+**Date**: 2026-04-26
+
+## MODIFIED Requirements
+
+This change does two things in scope:
+
+1. **Folds `**Verified by:**` lines** into every `### ENV-NN —` block of `openspec/specs/env/spec.md` (ENV-01 through ENV-17). Each annotation points at real tests — there are no `deferred` / `follow-up` markers. The new `src/core/create-env/create-env.spec-conformance.test.ts` pins the implicit type-level and wire-level scenarios the original suite did not (literal-type narrowing, loader-chain merge order, cross-loader `${VAR}` interpolation, unresolved-token default, Zod boundary failures for the three public APIs, OTel non-throwing instrumentation, `EnvValidationError.code === ENV.VALIDATION_FAILED`, and `ENV_CODES.*` literal typing).
+
+2. **Realigns spec ↔ impl** for the nine divergences the original audit flagged, plus ENV-12 and ENV-14:
+
+| Divergence | Direction | Change |
+|---|---|---|
+| `objectLoader` signature | spec → impl | ENV-04 documents the single-options `objectLoader({ source, sourceName })` form. |
+| `parseDotenv` malformed-line handling | spec → impl | ENV-05 documents silent-skip for lines without `=` (dotenv-ecosystem convention). |
+| `DotenvLoaderOptions.override` default | spec → impl | ENV-05 specifies `false` (safer; explicit `source` wins). |
+| `createEnv` interpolation pass | impl → spec | ENV-06 contract restored: `createEnv` runs a fixpoint interpolation pass over the merged values map before coercion. |
+| `BaseField.rules()` naming | spec → impl | ENV-07 specs `addRule()` on the base; `optional()`/`default()` lifted per subclass (return-type narrows). |
+| `ValidationResult` shape | spec → impl | ENV-09 specs `{ success, data, errors: ReadonlyArray<EnvError> }`. |
+| `maskSensitive` arg-order / glyph | spec → impl | ENV-10 specs `maskSensitive(schema, values)` and the `'****'` glyph. |
+| `CoercionError` code | impl → spec | `CoercionError` now uses `ENV.INVALID_FORMAT`. The dead `ENV.COERCE_ERROR` registry entry is removed. |
+| Zod-schema boundary wiring (ENV-12) | impl → spec | `createEnv`, `dotenvLoader`, `objectLoader` invoke `CreateEnvOptionsSchema`, `DotenvLoaderOptionsSchema`, `ObjectLoaderOptionsSchema` respectively; invalid options throw `EnvValidationError` with code `ENV.VALIDATION_FAILED`. Remaining schemas are marked `// schema: boundary-only` (consumer-facing). |
+| OTel instrumentation (ENV-14) | impl → spec | `createEnv` records `env.validation.total` (counter, `outcome` label), `env.validation.errors` (counter, `field` label), and `env.load.duration_ms` (histogram, ms) via `metrics.getMeter('suaveplan.env')`. `@opentelemetry/api` added as a runtime dep. |
+
+After this change:
+
+- `bun scripts/openspec-conformance.ts @suaveplan/env` exits 0 with no `error` findings.
+- `bunx turbo lint typecheck test --filter=@suaveplan/env` is green.
+- `bunx turbo test:coverage --filter=@suaveplan/env` meets the 100/100/100/100 threshold.
+- The historical `retroactively ticked` hazard in `openspec/archive/2026-04-19-enterprise-env/tasks.md` is recognised as resolved by this change.