parse. It returns a Validated<NonEmptyList<FieldError>, Address>: 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:

    Address address = new Address("1 High Street", "Leeds", "LS1 4AP");
    AddressMappingImpl addressMapping = AddressMappingImpl.INSTANCE; // bind once, reuse

    // Same-named, same-typed components match automatically:
    AddressDto dto = addressMapping.build(address); // total
    Validated<NonEmptyList<FieldError>, Address> back =
        addressMapping.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 WarehouseMapping is accepted too:

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

record Courier(String name, EmailAddress email) {} // as on Record Mapping Basics

record CourierDto(String name, String email) {}

record Warehouse(String code, int bays) {} // as on Record Mapping Basics

record WarehouseDto(String code, int bays) {}

@GenerateMapping
interface CourierMapping extends EmailVocabulary, MappingSpec<Courier, CourierDto> {}

@GenerateMapping
interface WarehouseMapping extends EmailVocabulary, MappingSpec<Warehouse, WarehouseDto> {}

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 a spec, and a list of them.

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. latest never parsed, so the invariant is never checked, while the missing order id still accumulates beside it:

    DeliveryDto request =
        new DeliveryDto(
            null, // no order id
            List.of(
                new DeliveryWindowDto("2026-03-01", "2026-03-04"),
                new DeliveryWindowDto("2026-03-09", "07/03/2026"))); // 7 March, before earliest

    assertThatValidated(DeliveryMappingImpl.INSTANCE.parse(request))
        .isInvalid()
        .hasFieldErrors(
            "orderId: must not be null",
            "windows.1.latest: 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 warning was right. 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 CustomerSummaryMapping.MAPPER first is fine, which is why the test passes. A program that uses CustomerSummaryMappingImpl.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("CustomerSummaryMapping")).isNotNull(); // the spec first
    assertThat(mapperAfterFirstUsing("CustomerSummaryMappingImpl")).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: A spec never holds its Impl in a constant.

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 a spec, and a list of them, Renames: @MapField, Standard codecs and Optional fields: @OptionalBridge.