parse. It returns a Validated<NonEmptyList<FieldError>, Person>: the domain value, or every bad field at once, each located by its path. build is total, so it returns the wire directly. The types say so:

    Person person = new Person("Ada", 36);
    PersonMappingImpl personMapping = PersonMappingImpl.INSTANCE; // bind once, reuse

    // Same-named, same-typed components match automatically:
    PersonDto dto = personMapping.build(person); // total
    Validated<NonEmptyList<FieldError>, Person> back =
        personMapping.parse(dto); // accumulating, located

Where this lives: Your first mapping.

In a mix-in: a plain interface holding the leaf, which each spec extends alongside MappingSpec. An inherited leaf counts as if the spec declared it wherever a component matches it, and stays inert where none does, so TagMapping is accepted too:

interface EmailVocabulary {
  default ValidatedPrism<String, EmailAddress> email() {
    return EmailCodecs.EMAIL;
  }
}

record Lead(String name, EmailAddress email) {}

record LeadDto(String name, String email) {}

record Tag(String label) {}

record TagDto(String label) {}

@GenerateMapping
interface LeadMapping extends EmailVocabulary, MappingSpec<Lead, LeadDto> {}

@GenerateMapping
interface TagMapping extends EmailVocabulary, MappingSpec<Tag, TagDto> {}

Where this lives: Shared vocabulary: mix-in interfaces.

Refused. Of the two fixes the message offers, the bridge comes first:

Add '@OptionalBridge java.util.Optional<java.lang.String> phone();' to the spec

The processor will not guess that a null means absent: on most record wires a null really is a defect, reported as a located must not be null. So the bridge is declared one component at a time, in writing. The other fix, a leaf over the whole Optional, maps the pair but leaves null a located error, so only the bridge gives the field an absent state.

Where this lives: Optional fields: @OptionalBridge.

Two leaves, one for each component whose type differs on the wire. The processor never applies a codec on its own, so each conversion is declared. Each leaf is named after the domain component it parses, and its type arguments put the wire type first:

enum Priority { LOW, HIGH }

record Ticket(UUID id, Priority priority) {}

record TicketDto(String id, String priority) {}

@GenerateMapping
interface TicketMapping extends MappingSpec<Ticket, TicketDto> {
  default ValidatedPrism<String, UUID> id() {
    return StandardCodecs.uuid();
  }

  default ValidatedPrism<String, Priority> priority() {
    return StandardCodecs.enumByName(Priority.class);
  }
}

The refusal names the component and the leaf to add:

target field 'TicketDto.id' has no usable source. The types differ (java.lang.String vs
java.util.UUID) and no matching leaf method was found. Found on Ticket: [id, priority]. Add
'default ValidatedPrism<java.lang.String, java.util.UUID> id()' to the spec.

Where this lives: Standard codecs and Validated leaves.

4. Every value parse reads is null-guarded, and a null becomes a located error beside every other bad field, never an exception. A nested spec's errors locate under the component that holds it:

    assertThatValidated(
            InvoiceMappingImpl.INSTANCE.parse(
                new InvoiceDto("INV-2", new CustomerDto(null, "not-an-email"))))
        .isInvalid()
        .hasFieldErrors("customer.name: must not be null", "customer.email: not an email address");

Where this lives: Null has an address, not a stack trace and Nesting, containers, and recursion.

The leaf is named after the type it produces, not the component it parses. A leaf is found by its name, so emailAddress() matches nothing, and the message says what it expects:

leaf 'emailAddress' names no component of Customer. A leaf is a zero-parameter 'default' named
after the DOMAIN component it parses (or an inner component of a flattened one); an unmatched
leaf would silently validate nothing.

Rename it email(). A leaf declared on the spec must bind, because one that matches nothing would validate nothing, silently. A leaf inherited from a mix-in, as in Checkpoint 2, may stay inert instead.

Where this lives: Validated leaves and Shared vocabulary: mix-in interfaces.

3. The constructor needs every component, so it runs only once they have all parsed. checkOut never parsed, so the invariant is never checked, while the missing guest still accumulates beside it:

    ReservationDto request =
        new ReservationDto(
            null, // no guest
            List.of(
                new StayDto("2026-03-01", "2026-03-04"),
                new StayDto("2026-03-09", "07/03/2026"))); // meant to leave before it arrives

    assertThatValidated(ReservationMappingImpl.INSTANCE.parse(request))
        .isInvalid()
        .hasFieldErrors(
            "guest: must not be null",
            "stays.1.checkOut: not an ISO-8601 date (expected e.g. 2026-07-28)");

A record reports its components' errors or its invariant, never both.

Where this lives: A record's own invariants.

It does not compile. Sealed dispatch is exhaustive in both directions, so parse needs a domain subtype for every wire subtype. Nothing produces CashDto, so a parse that compiled would have nowhere to send one:

permitted subtype 'com.example.CashDto' of 'PaymentDto' is never produced. parse must dispatch
every wire subtype back to a domain subtype; this one has no mapping spec from any. Add a domain
subtype and spec for it, or remove it from the sealed wire interface.

Where this lives: Sealed hierarchies.

No. The Impl implements the spec, and the spec declares an instance method with a body (its email leaf). So initialising the Impl initialises the spec first. A program that reads VisitorMapping.MAPPER first is fine, which is why the test passes. A program that uses VisitorMappingImpl.INSTANCE first evaluates the constant while the Impl's INSTANCE is still null, and the constant keeps that null for good:

    // Two programs, each loading this package afresh, so neither sees what the other ran:
    assertThat(mapperAfterFirstUsing("VisitorMapping")).isNotNull(); // the spec first
    assertThat(mapperAfterFirstUsing("VisitorMappingImpl")).isNull(); // the Impl first

Which class a program reaches first depends on its code paths, so the failure comes and goes. Bind the Impl in the calling code instead: a local, a field of the calling class, or an injected ValidatedPrism.

Where this lives: Bind in the caller, not on the spec.

Two specs: one for the parcel pair, which lifts the list element by element, and one for the shipment. The shipment spec needs a StandardCodecs leaf for id, a rename from parcels to the wire's items, and a bridge for note. sku and grams match by name and type, so they need nothing:

@GenerateMapping
interface ParcelMapping extends MappingSpec<Parcel, ParcelDto> {}

@GenerateMapping
interface ShipmentMapping extends MappingSpec<Shipment, ShipmentDto> {
  default ValidatedPrism<String, UUID> id() {
    return StandardCodecs.uuid();
  }

  @MapField(to = "items")
  List<Parcel> parcels();

  @OptionalBridge
  Optional<String> note();
}

The client reads parcels.1.sku: error paths use the domain's names, even where the wire says items. The test checks all three requirements:

    ShipmentMappingImpl shipments = ShipmentMappingImpl.INSTANCE;

    assertThatValidated(
            shipments.parse(
                new ShipmentDto(
                    "not-a-uuid",
                    List.of(new ParcelDto("A-1", 250), new ParcelDto(null, 90)),
                    null)))
        .isInvalid()
        .hasFieldErrors(
            "id: not a UUID (expected e.g. 123e4567-e89b-12d3-a456-426614174000)",
            "parcels.1.sku: must not be null"); // the domain's name, not the wire's `items`

    UUID id = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
    assertThatValidated(
            shipments.parse(
                new ShipmentDto(id.toString(), List.of(new ParcelDto("A-1", 250)), null)))
        .hasValue(new Shipment(id, List.of(new Parcel("A-1", 250)), Optional.empty()));

Where this lives: Nesting, containers, and recursion, Renames: @MapField, Standard codecs and Optional fields: @OptionalBridge.