feat: spec-level Postel's-Law tolerant readers + stable enum constants

[caballeto]

Summary

The Terraform provider now decodes response-DTO multi-value enums as
plain string. So when the API adds a new monitor type, alert channel
kind, or incident status, the provider's Read() keeps working —
terraform refresh won't surface the resource as drift just because
a downstream API value is unknown to this provider build.

Authoring stays strict: terraform plan still rejects unknown values
on Create/Update (sourced from generated subtype-tag constants in
internal/api/enums.go).

Implementation

Three pieces:

1. Spec-level relaxation — scripts/preprocess.mjs (vendored copy
   of mono's @devhelm/openapi-tools) runs relaxResponseEnumsInSpec
   before oapi-codegen sees the spec. Response-DTO enum fields land
   in internal/generated/types.go as plain string.

2. scripts/oapi-codegen.yaml (new) — pins
   always-prefix-enum-values: true and
   resolve-type-name-collisions: true so the constants
   oapi-codegen emits stay stable across spec evolution. Without
   these, oapi-codegen silently drops the MonitorDtoType prefix
   when a single-value enum collapses, breaking compile in
   downstream code.

3. internal/api/enums.go — input-side OneOf slices are
   sourced from generated subtype-tag constants (e.g.
   MonitorAuthConfigBasicAuthConfigTypeBasic) walked at init time,
   so adding a new spec value auto-extends validation without
   hand edits.

internal/api/validate.go is documented as the Go counterpart to
Zod safeParse (sdk-js) and Pydantic model_validate (sdk-python):
runtime response validation driven by the spec. The function now
skips multi-value-enum Valid() checks on response DTOs (those are
string after relaxation) and only fires on single-value
discriminator tags — exactly the desired Postel behaviour.

Cross-surface design: mini/runbooks/api-contract.md § 3.3.

Tests

• go vet ./... clean.
• go build ./... clean.
• go test ./... — all packages green.
• enums_coverage_test.go rewritten to walk constants by
  typeNameSuffix, so new spec values are auto-covered.
• Negative tests around response-side enum rejection flipped to
  assert acceptance (Postel). Input-side stringvalidator.OneOf
  negative tests stay strict.
• Codegen is deterministic: double-regen produces bit-identical
  internal/generated/types.go.

Test plan

• CI green.
• terraform-provider-devhelm acceptance tests pass against
  the test API stack.
• Verify internal/generated/types.go: response DTOs (e.g.
  MonitorDto.type) are typed string; input DTOs (e.g.
  CreateMonitorRequest.type) keep typed MonitorType.

Made with Cursor