# ADR 0003: Response validation is a tolerant `TypedDict` base plus a `validator[T]` wrapper

- Status: accepted
- Date: 2026-08-07 (carried over 2026-09-06)

## Context

Six independently built clients converged on the same validation shape without copying it from one template: a `TypedDict` base decorated `@pydantic.with_config({'extra': 'allow'})` that every generated wire-shape type uses instead of a bare `typing_extensions.TypedDict`, plus `validator[T]`, a lazily built `pydantic.TypeAdapter[T]` wrapper that catches `pydantic.ValidationError` and re-raises it as the runtime's own `ValidationError`.

The pattern was reconsidered when one client's generated code was found building a bare `TypeAdapter` at module scope instead. On inspection that was a codegen inconsistency in one file, not evidence the wrapper is unnecessary. The core's envelope unwrapping and API error-code mapping already live in one place; folding pydantic's error translation into that same method would conflate two distinct failures (a malformed API response vs. a schema mismatch) into one.

`extra='allow'` is not pydantic's default (that is `'ignore'`, which drops unknown fields silently), and `'forbid'` was never used by any of the six. The choice is deliberate.

## Decision

`truewire-core` ships this pattern, and generated clients use it:

- a `TypedDict` base configured `extra='allow'`, used by every generated wire-shape `TypedDict`;
- `validator[T]`, whose `.python()`, `.json()` and `.dump()` are the one place `pydantic.ValidationError` becomes `truewire_core.ValidationError`;
- envelope and error-code mapping stay a separate method in the client core, and never duplicate the wrapper's translation.

`extra='allow'` specifically:

- `'forbid'` turns any undocumented field the API adds to a live payload into a hard failure on every validated call, with no client-side control over when the API ships the change or when the spec gets regenerated to catch up.
- `'ignore'` avoids the crash but silently drops the field from the returned dict. Data that was on the wire disappears with no signal, which a client that calls itself response-validated should not do quietly.
- `'allow'` keeps declared fields typed and validated and lets undeclared ones ride along. A typed caller sees nothing extra; a caller inspecting the dict still gets the field. Promoting it to a declared field later changes nothing about what was actually returned in the meantime.

## Consequences

The client survives additive drift, a new field on a response, without a broken validated call in production. The two failure modes, API-level errors and schema-validation errors, each have exactly one place they are mapped.

Left open: `extra='allow'` only protects against additive drift. An API that changes a field's meaning, or restructures a response entirely, still validates cleanly as long as the declared subset happens to type-check. Nothing today logs that extra fields arrived on a call for a human to fold into the next spec revision.