### Write

Multi-edit packing (static factories — see [Multi-edit](#multi-edit)):

| Method | Returns |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Telescope.all(Edit...)` | Reusable `Telescope` normalizer that runs every edit, in argument order, on `apply(s)`. **Compile-checked.** |
| `Edit.over(Telescope, Function)` | Pair a pre-built path with its per-leaf transformation. Static-import-friendly: `import static …Edit.over;`. **Compile-checked.** |

---

## Cookbook

### A single field

```java
final Telescope name = Telescope.of(User.class).field(User::name);

name.read(alice); // "alice"
name.set(alice, "Bob"); // User with name="Bob"
name.update(alice, String::toUpperCase); // User with name="ALICE"
```

### Nested fields

```java
final Telescope city = Telescope.of(User.class)
.field(User::address)
.field(Address::city);

city.update(alice, String::toUpperCase);
```

### Every element of a collection inside a record

```java
final Telescope userNames = Telescope.of(Team.class)
.each(Team::users)
.field(User::name);

userNames.update(team, String::toUpperCase);
userNames.toList(team); // List
```

### Sealed-type case

```java
sealed interface Event permits Created, Updated, Deleted {}
record Created(String id) implements Event {}
record Updated(String id, String diff, int revision) implements Event {}
record Deleted(String id) implements Event {}

final Telescope updatedDiff = Telescope.of(Event.class)
.as(Updated.class)
.field(Updated::diff);

updatedDiff.update(event, s -> s + "!"); // no-op if not Updated
updatedDiff.find(event); // Optional
```

### Optional field

```java
record Profile(String id, Optional nickname) {}

final Telescope nick = Telescope.of(Profile.class).whenPresent(Profile::nickname);

nick.update(profile, String::toUpperCase); // no-op if nickname is empty
```

### Map values

```java
record Index(Map byKey) {}

final Telescope values = Telescope.of(Index.class).eachValue(Index::byKey);

values.update(index, v -> v * 10);
```

### Typed container leaves (pre-built fragments)

When you want a path that ends _at_ the container (not at its elements), use the typed `.list(Class::accessor)` /
`.setField(...)` / `.mapField(...)` / `.optional(...)` instance methods. They return narrower subclasses
(`ListTelescope`, `SetTelescope`, `MapTelescope`, `OptionalTelescope`) whose typed terminal step (`.each()` /
`.values()` / `.present()`) descends into elements with zero runtime container dispatch — pure lattice composition,
fully compile-checked.

```java
record Box(List tags) {}

// Build the list-typed path once; descend on demand.
final ListTelescope tags = Telescope.of(Box.class).list(Box::tags);
final Telescope elements = tags.each(); // typed .each() — compile-checked

elements.update(box, String::toUpperCase);

// Set / Map / Optional follow the same shape.
record Cart(Set items) {}

final SetTelescope items = Telescope.of(Cart.class).setField(Cart::items);
items.each().field(Item::sku).update(cart, String::toUpperCase);
```

For pre-built paths from elsewhere — composed `Telescope.then(...)` fragments, return types of helper methods, etc. —
promote them with `Telescope.asList(...)` / `.asSet(...)` / `.asMap(...)` / `.asOptional(...)` so the typed terminal
becomes available:

```java
final Telescope> raw = ...; // built somewhere else
Telescope.asList(raw).each().field(Department::name).update(co, String::toLowerCase);
```

### Indexed traversal

When a read or update depends on position, not just value, use the indexed forms. The index is the 0-based position in
traversal order (flat across nested `each` levels):

```java
final Telescope members = Telescope.of(Team.class).each(Team::members);

members.toListIndexed(team); // [Indexed[0, "alice"], Indexed[1, "bob"], ...]
members.updateIndexed(team, (i, name) -> i + ": " + name); // "0: alice", "1: bob", ...
```

### Filter mid-path

```java
final Telescope engineeringEmails = Telescope.of(Company.class)
.each(Company::departments)
.filter(d -> "Engineering".equals(d.name()))
.each(Department::teams)
.each(Team::users)
.field(User::email);

engineeringEmails.update(company, String::toLowerCase);
// Engineering emails lowercased; Sales untouched.
```

### Sealed-case + collection

```java
record Stream(List events) {}

final Telescope bumpRevisions = Telescope.of(Stream.class)
.each(Stream::events)
.as(Updated.class)
.field(Updated::revision);

bumpRevisions.update(stream, r -> r + 1);
// Created / Deleted events pass through unchanged.
```

### Sibling access

A plain `update` lambda only sees the focused value. When the transform needs sibling fields (the focused price needs
the SKU; the focused user needs the team name), close over the source — it's already in scope, since you pass it as the
first argument.

```java
record Team(String name, List users) {}

record User(String name, String bio) {}

static final Telescope USERS = Telescope.of(Team.class).each(Team::users);

// Set every user's bio to mention the team name. The lambda reads the sibling `team.name()`.
final Team stamped = USERS.update(team, (user) -> new User(user.name(), "Member of " + team.name()));
```

This works for every variant — `updateAsync`, `updateEither`, `updateValidated`, `updateOptional` — because the root the
lambda needs is the same value you already hold. If the source is an expression rather than a variable, hoist it to a
local first (`final var team = fetchTeam();`) and close over that.

### Multi-edit

To apply several edits at different paths in one go, declare each path once as a static final, then pack the edits with
`Telescope.all(over(...), over(...))`. Every step is fully compile-checked.

**Recommended form — `Telescope.all(over(...), over(...))`.** Each `over(PATH, fn)` is one edit; `Telescope.all(...)`
folds them into a reusable `Telescope` whose `.apply(s)` runs every edit in argument order.

```java
import static io.github.eschizoid.telescope.Edit.over;

static final Telescope EMAILS = Telescope.of(Company.class)
.each(Company::departments)
.each(Department::teams)
.each(Team::users)
.field(User::email);

static final Telescope DEPT_NAMES = Telescope.of(Company.class)
.each(Company::departments)
.field(Department::name);

static final Telescope USER_NAMES = Telescope.of(Company.class)
.each(Company::departments)
.each(Department::teams)
.each(Team::users)
.field(User::name);

final Telescope normalize = Telescope.all(
over(EMAILS, String::toLowerCase),
over(DEPT_NAMES, String::trim),
over(USER_NAMES, titleCase));

final Company done = normalize.apply(company);
normalize.apply(companyB); // reusable across sources
```

`over(path, fn)` ties a `Telescope` to a `Function`; `javac` enforces the leaf type match. Each edit lives
on its own line, the count is visible at a glance, and there is no chain-blur between paths.

**Single-edit shortcut.** For one edit, just call `update` on the path:

```java
EMAILS.update(company, String::toLowerCase);
```

**Chain accumulator (alternative).** The same semantics as `Telescope.all(...)` are also available as a fluent chain via
`.update(path, fn)` and `.with(fn)` terminated by `.apply(source)` — useful when you want an inline path mid-chain
without naming it. The chain reads less clearly for multiple distinct paths (the navigation segments visually blur), so
prefer `Telescope.all(over(...))` when packing two or more edits.

```java
// Equivalent to the Telescope.all(...) form above:
Telescope.of(Company.class)
.update(EMAILS, String::toLowerCase)
.update(DEPT_NAMES, String::trim)
.update(USER_NAMES, titleCase)
.apply(company);

// Inline one-shot trailing edit on a pre-built chain:
Telescope.of(Company.class)
.update(EMAILS, String::toLowerCase)
.each(Company::departments).field(Department::name).with(String::trim)
.apply(company);
```

Edits run sequentially in argument / insertion order; the second sees the first's result, not the original source. An
empty `Telescope.all()` (or an unedited chain) returns the source unchanged from `.apply(...)`.

---

## Type conversion

Two records that represent the same data (`Entity ↔ Dto`) convert through a bidirectional `Iso` that composes into
longer paths like any other telescope.

### Hand-written (`from / to / using`)

Write the two conversion functions yourself; telescope doesn't auto-map (that's MapStruct's territory). What's different
is that the conversion becomes a value, so it threads into longer paths.

```java
final Telescope userIso = Telescope.from(UserEntity.class)
.to(UserDto.class)
.using((e) -> new UserDto(e.id(), e.email(), e.name()), (d) -> new UserEntity(d.id(), d.email(), d.name()));

UserDto dto = userIso.read(entity); // forward

UserEntity updated = userIso.update(entity, (d) -> new UserDto(d.id(), d.email().toLowerCase(), d.name()));
// ↑ round-trips through DTO, returns Entity
```

The conversion is an `Iso`, which means it composes into longer paths:

```java
record EntityPage(List items, int total) {}

// Walk into the page, view each entity as a DTO, focus the email, lowercase it.
// Result is an EntityPage with UserEntity items — entities modified by round-tripping through DTO.
Telescope.of(EntityPage.class)
.each(EntityPage::items)
.then(userIso) // ← Iso participates in the lattice
.field(UserDto::email)
.update(page, String::toLowerCase);
```

### Deep recursive mapping (`Telescope.map(A.class, B.class, to(...)...)`)

The recommended shape for record-to-record (and POJO↔POJO, and cross-paradigm) conversion: pass the source and target
classes up front, then varargs of `MapStep` rows. **Recursion is the default.** Same-named components identity-map,
nested records / POJOs recurse, `List↔List` / `Set↔Set` / `Map↔Map` / `Optional↔Optional`
lift the inner-element Iso through the container automatically (to any depth — `List>>` works by
construction). You only spell the _differences_.

```java
import static io.github.eschizoid.telescope.mapping.Mapping.to;
import static io.github.eschizoid.telescope.mapping.Mapping.via;

// All same-name, no overrides — the pure-copy 1-liner:
final Telescope userMapper = Telescope.map(UserEntity.class, UserDto.class);

// Tree-deep mapping with two renames — every other field figures itself out:
final Telescope companyMapper = Telescope.map(
CompanyEntity.class,
CompanyDto.class,
to(CompanyEntity::founded, CompanyDto::since), // top-level rename
to(UserEntity::name, UserDto::fullName)
); // applies wherever User↔UserDto recurses
```

The second example covers a 5-level structure — `Company → Department → Team → User → Address` — with `List`, `Map`, and
`Optional` containers at multiple depths. Both renames are declared _once_; the `User::name → UserDto::fullName` rule
fires _every time_ recursion encounters the `UserEntity ↔ UserDto` type pair (in `users[]`, in
`department.head: Optional`, in `company.ceo: Optional` — all three at once).

**How `to(...)` overrides are keyed.** Each `to(srcAccessor, tgtAccessor)` row carries its source and target record
classes implicitly via the method references. `Telescope.map(...)` reads them via `SerializedLambda` and uses
`(sourceClass, targetClass)` as the key. When the recursion lands on a matching pair, the row's correspondence is
applied; otherwise the recursion auto-resolves that component.

**Cycle handling.** Self-referencing structures (a `User` that contains `Optional`) terminate naturally — the
recursion caches each type pair as it descends, and re-entry returns the in-progress entry instead of recursing forever.

**Override forms.** Static-import-friendly factories on `Mapping`:

| Factory | Purpose | MapStruct equivalent |
| ----------------------------- | --------------------------------------------------- | ------------------------------------------- |
| `to(src, tgt)` | Rename, same leaf type | `@Mapping(source, target)` |
| `to(src, tgt, fwd, bwd)` | Bidirectional typed transform | `@Mapping(source, target, qualifiedBy)` |
| `forward(src, tgt, fn)` | Forward-only typed transform | (separate `@Mapper` interface) |
| `toOrElse(src, tgt, default)` | Null-coalesce to a default value | `@Mapping(defaultValue = "...")` |
| `toOrElseGet(src, tgt, sup)` | Null-coalesce via a `Supplier` | `@Mapping(defaultExpression = "java(…)")` |
| `enumTo(src, tgt, SE, TE)` | By-name enum mapping with build-time exhaustiveness | `@ValueMapping(source = "X", target = "Y")` |
| `via(src, tgt, mapper)` | Drop in a pre-built nested mapper | (composition by hand) |
| `constant(tgt, value)` | Forward-only literal at the target slot | `@Mapping(constant = "...")` |
| `compute(tgt, supplier)` | Forward-only supplier-computed value | `@Mapping(expression = "java(...)")` |
| `drop(src)` | Skip the source field; backward zero-fills it | `@Mapping(ignore = true)` |

Example — three of those rows together:

```java
import static io.github.eschizoid.telescope.mapping.Mapping.*;

Telescope.mapper(
UserEntity.class,
UserDto.class,
to(UserEntity::name, UserDto::fullName),
toOrElse(UserEntity::region, UserDto::region, "EMEA"),
enumTo(UserEntity::status, UserDto::status, EntityStatus.class, DtoStatus.class)
);
```

The `via(...)` row works in two flavors: pass an **accessor-typed** mapper (e.g.,
`Mapper, List>`) and telescope uses it as-is, or pass an **element-typed** mapper
(`Mapper`) and telescope detects the accessor's container shape (`List`, `Set`, `Optional`, `Map`
values) and auto-lifts the mapper through it via `Iso.liftList` / `liftSet` / `liftOptional` / `liftMapValues`. One row
either way — no separate `viaList` / `viaSet` factories.

Recursion is auto by default — there's no `auto()` row to declare.

**Result threads through longer paths** like any other telescope:

```java
Telescope.of(EntityPage.class)
.each(EntityPage::items)
.then(companyMapper)
.field(CompanyDto::name)
.update(page, String::toUpperCase); // entities modified by round-tripping through the DTO
```

For lossy or one-way conversions (dropping fields, non-invertible transforms), use `from/to/using` with hand-written
functions. Telescope still won't auto-discover anything fuzzy — recursion only follows exact name matches plus the
same-shape container rule.

---

## Working with POJOs

Telescope's deep-mapping factory handles any combination of records and POJOs through one entry point. The same
`Telescope.map(A.class, B.class, ...)` call covers record↔record, POJO↔POJO, and the cross-paradigm record↔POJO mix at
any depth — the engine picks per side whether to drive the canonical constructor (records) or `Beans.autoWriter` (POJOs)
at every type pair the recursion encounters. The alternative is to navigate the POJO directly with
`Telescope.ofBean(...)`. Either way updates are immutable.

### Convert — `Telescope.map` / `Telescope.mapper`

The same factory described under [Type conversion](#type-conversion) handles POJO↔POJO and cross-paradigm record↔POJO
pairs without ceremony — components match by name on either side (`Pojo::getX` / `RecordOrPojo::x` normalized to `x`),
nested POJOs recurse, and container hops auto-lift. The POJO mechanics this section covers are the bean-construction
lever (`writeBean` / `writeBeans`) for when the auto-detect ladder can't pick a strategy.

```java
import static io.github.eschizoid.telescope.mapping.Mapping.to;
import static io.github.eschizoid.telescope.mapping.WriteHint.WriteStrategy.SETTERS;
import static io.github.eschizoid.telescope.mapping.WriteHint.writeBeans;

class LegacyUser {
/* getId(), getEmail(), getName() + no-arg ctor + setters */
}

record UserRecord(String id, String email, String name) {}

// Same-name 1-liner — every getter/component lines up by normalized name.
final Telescope bridge = Telescope.map(LegacyUser.class, UserRecord.class);
```

Renames (`Mapping.to(srcAcc, tgtAcc)`), typed transforms (`Mapping.to(srcAcc, tgtAcc, fwd, bwd)`), null-coalescing
defaults (`Mapping.toOrElse` / `toOrElseGet`), by-name enum mapping (`Mapping.enumTo`), and pre-built nested mappers
(`Mapping.via(srcAcc, tgtAcc, mapper)`) work the same way they do for records — see the rows under
[Type conversion](#type-conversion).

**`writeBean` — pin a POJO write strategy.** `Beans.autoWriter` picks a ladder: `builder()` → no-arg ctor + setters →
no-arg ctor + reflective field injection → single public all-args ctor (when compiled with `-parameters` and ctor
parameter names match the property names). For classes the auto path refuses (immutable all-args-only POJOs without
`-parameters`, ambiguous multi-ctor classes), pass an explicit `WriteHint.writeBean(target, strategy)` row to force one
of `BUILDER` / `SETTERS` / `FIELDS` / `CONSTRUCTOR`:

```java
import static io.github.eschizoid.telescope.mapping.WriteHint.WriteStrategy.CONSTRUCTOR;
import static io.github.eschizoid.telescope.mapping.WriteHint.writeBean;

// OrderPojo has a public (String sku, int qty) ctor, no builder, no setters — autoWriter would
// refuse without -parameters. The hint forces the CONSTRUCTOR strategy explicitly.
final Telescope conv = Telescope.map(
OrderRecord.class,
OrderPojo.class,
writeBean(OrderPojo.class, CONSTRUCTOR),
to(OrderRecord::sku, OrderPojo::getSku)
);
```

Validation is eager: a misconfigured hint (`BUILDER` on a no-builder class, hint targeting a record, duplicate hint,
unused hint) throws at `Telescope.map(...)` time — not on first `iso.to()` deep in production.

**`writeBeans(STRATEGY)` — one default for every bean target.** When every entity in the recursion shares the same
construction shape (the common JPA case: every `@Entity` needs `SETTERS` so Hibernate's identity assignment fires), one
`writeBeans(SETTERS)` row replaces N per-class enumerations. Per-class `writeBean(X.class, ...)` still wins for class
`X`. At most one `writeBeans(...)` default per call.

```java
import static io.github.eschizoid.telescope.mapping.WriteHint.WriteStrategy.SETTERS;
import static io.github.eschizoid.telescope.mapping.WriteHint.writeBean;
import static io.github.eschizoid.telescope.mapping.WriteHint.writeBeans;

final Mapper orderMapper = Telescope.mapper(
Order.class,
OrderEntity.class,
writeBeans(SETTERS), // default for OrderEntity, CustomerEntity, LineItemEntity, AddressEmbeddable, …
writeBean(CashRegisterEntity.class, FIELDS) // override on one specific target
);
```

```java
Telescope.of(Page.class) // Page is a record holding List
.each(Page::items)
.then(bridge) // each POJO ↔ record at this hop
.field(UserRecord::email)
.update(page, String::toLowerCase);
```

```java
final Mapper mapper = Telescope.mapper(UserBean.class, UserView.class);

final UserView withFresh = mapper.patch(view, new UserView(null, "new@x", null));

// Container promotion for a bulk endpoint:
final Mapper, List> bulk = mapper.liftList();
final List view = bulk.forward(beans);

// Thread the conversion into a longer Telescope chain via .then():
Telescope.of(Page.class)
.each(Page::items)
.then(mapper.asTelescope())
.field(UserView::email)
.update(page, String::toLowerCase);
```

For a worked end-to-end demo using every public Mapping / Mapper / Telescope row through a Spring Boot 4, Hibernate, and
Jackson REST pipeline, see [`examples/springboot/`](examples/springboot/).

**`@Bridge` — reflection-free, compile-checked (any pair).** The codegen counterpart to `Telescope.map(...)`. Annotate
the source you own with the target type; the processor generates `Bridge.BRIDGE`, a `Telescope`
built from direct component/getter reads and constructor / builder / setter calls. Both sides may be records or POJOs —
record⇄record, record⇄POJO, POJO⇄POJO. Fields match by name (a bijection); a name mismatch or a missing construction
strategy is a compile error, not a runtime one:

```java
import io.github.eschizoid.telescope.annotations.Bridge;

@Bridge(UserDto.class)
record UserEntity(String id, String email) {}

// Generated alongside: UserEntityBridge.BRIDGE (a Telescope)
UserDto dto = UserEntityBridge.BRIDGE.read(entity);

// BRIDGE is a Telescope value, so it threads through a longer path:
final Page lowered = Telescope.of(Page.class)
.each(Page::entities) // each UserEntity on the page
.then(UserEntityBridge.BRIDGE) // view it as a UserDto
.field(UserDto::email)
.update(page, String::toLowerCase);
```

It auto-detects each side's strategy at compile time (record canonical constructor; POJO name-matched constructor →
builder → no-arg + setters). Renames and per-field transforms can't be expressed in an annotation — use the runtime
`map` / `from/to/using` for those. Wire up `telescope-codegen` as shown under [Installation](#installation).

**`from/to/using` — hand-written.** When the mapping is lossy, one-directional, or just custom, write both functions
yourself:

```java
public static final Telescope USER_BRIDGE = Telescope.from(LegacyUser.class)
.to(UserRecord.class)
.using(
(l) -> new UserRecord(l.getName(), l.getEmail(), l.getAddress()),
(r) -> {
final var u = new LegacyUser();
u.setName(r.name());
u.setEmail(r.email());
u.setAddress(r.address());
return u;
}
);
```

### Navigate — `ofBean`

When you'd rather not define a mirror record, navigate the POJO directly. `.field(Pojo::getX)` reads via the getter;
`set`/`update` rebuild the POJO immutably with that one property changed (write strategy auto-detected per type: builder
→ setters → field injection). Deep paths and `.each(...)` compose like records:

```java
Telescope.ofBean(LegacyUser.class)
.field(LegacyUser::getAddress)
.field(Address::getCity)
.update(user, String::toUpperCase); // new LegacyUser; the original is untouched
```

**Cost — measured.** `ofBean` rebuilds the whole POJO and re-reads every getter at _each_ level of the path: a 3-level
update benchmarks at ~442 ns/op (~18x a hand-written copy, ~1.8x record reflection — see
[`benchmarks/`](benchmarks/README.md)). Fine for ordinary use (sub-microsecond); for a hot loop over many objects,
convert to a record once with `Telescope.map(Pojo.class, Record.class)` and navigate the record (or use `@BeanFocus`
codegen) instead. The runtime deep-mapping bridges are cheaper — ~114 ns (POJO→record) and ~142 ns (POJO↔POJO), in line
with the record→record mapper (~112 ns).

**Aliasing — beans aren't records.** An update rebuilds the _spine_ (the path to the changed field) with fresh objects
and shares references to untouched subtrees. With records that's always safe; with mutable POJOs the new and old object
share the same off-path sub-POJO instances, so mutating a shared sub-object afterward shows through both. Treat the
shared parts as effectively immutable.

### Scope

`Telescope.map(...)` / `@Bridge` match by exact name and need a same-named field on each side (with optional rename rows
via `Mapping.to(srcAcc, tgtAcc)`); nested collections recurse automatically. The `FIELDS` write strategy (and `ofBean`'s
field-injection fallback) uses `setAccessible`, so under JPMS the POJO's package must be `opens`'d to
`io.github.eschizoid.telescope` — `CONSTRUCTOR` / `BUILDER` / `SETTERS` (and all of `@Bridge`) use public members only.

---

## Compile-time, reflection-free navigation (`@Focus` / `@BeanFocus`)

The reflection-based `Telescope.of(User.class).field(User::name)` path resolves the field name at runtime — fast enough
for ordinary use (~100 ns), but a typo or a rename surfaces as a runtime error, not a compile error. Annotate the types
you navigate with `@Focus` (records) or `@BeanFocus` (POJOs) and add the processor to your build; for each annotated
type the processor emits a sibling **fluent typed path navigator** that reads like the runtime DSL but is fully
compile-checked and reflection-free.

**Same path, two ways.** The two surfaces produce the same terminal `Telescope` and the same `update`
result — they only differ in _when_ the path is resolved (runtime vs `javac`) and _how_ it's dispatched (reflection vs
direct method-ref + constructor calls). On the [benchmarks](benchmarks/README.md), the reflective deep-field path
measures ~262 ns/op; the codegen lens path it desugars to measures ~45 ns/op (~5.8x).

```java
// Reflective — runtime resolution, ~100 ns per field hop
Telescope.of(Company.class)
.each(Company::departments).each(Department::teams)
.each(Team::users).field(User::email)
.update(company, String::toLowerCase);

// Compile-time, reflection-free — same Telescope, generator-built
CompanyPath.of()
.departments().each().teams().each()
.users().each().email()
.update(company, String::toLowerCase);
```

```java
import io.github.eschizoid.telescope.annotations.Focus;

@Focus record Address(String city, String zip) {}
@Focus record User(String name, int age, Address address) {}
@Focus record Team(String name, List users) {}
@Focus record Company(String name, List teams) {}

// Generated: Path per annotated type plus a step class per collection-shaped component.
// Usage reads like the reflective DSL — but every hop is type-checked by javac and every read /
// rebuild is a direct method-ref + constructor call (no reflection):
final Telescope userNames = CompanyPath.of()
.teams().each() // step over List → TeamPath
.users().each() // step over List → UserPath
.name(); // terminal Telescope

final Company shouted = userNames.update(company, String::toUpperCase);

// Single fields are just as direct:
UserPath.of().address().city().update(alice, String::toUpperCase);
```

Each scalar component yields a terminal `Telescope`; each sub-record component (also `@Focus`-annotated) yields a
`<sub>Path` to keep navigating; each container component yields a small step class whose `.each()` (List/Set/
Iterable), `.eachValue()` (Map values, keys preserved), or `.whenPresent()` (Optional) returns the element's `Path` when
the element is itself annotated, or a terminal `Telescope` otherwise. At any hop, `.get()` returns the current
`Telescope` — so a step or path _is_ a navigator, but every leaf is the same `Telescope` value the reflective DSL
gives you.</sub>

**Ops at every hop, effects included.** Every generated `Path` and `Step` also forwards the full `Telescope` operation
surface — `read` / `find` / `toList` / `count` / `exists` / `set` / `update` / `updateIndexed` / `toListIndexed` /
`then` plus the four effect methods `updateAsync` (with or without `Executor`) / `updateOptional` / `updateEither` /
`updateValidated`. You don't need to terminate with `.get()` first; the navigator stands in for the wrapped Telescope at
any intermediate hop. So `CompanyPath.of().teams().each().users().each().updateAsync(company, svc::lookup, pool)`
returns a `CompletableFuture` directly, with the effect threaded through the generated chain.

**Bridge hops — conversion as a navigator step.** If a type carries both `@Focus`/`@BeanFocus` (so it has a `*Path`) and
`@Bridge(Target.class)` (so it has a `*Bridge.BRIDGE`), the navigator gains a fluent **`as()`** method that
chains the bridge in. The navigator becomes a single compile-checked surface for _both_ navigation _and_ conversion,
crossing paradigms naturally (record↔record, record↔POJO, POJO↔POJO):

```java
@Focus
@Bridge(UserDto.class)
record UserEntity(String id, String email) {}

@Focus
record UserDto(String id, String email) {}

// Navigate through the bridge into a target field, then update. The Iso round-trips, so the
// result is a new UserEntity:
final UserEntity lowered = UserEntityPath.of()
.asUserDto() // → UserDtoPath
.email() // → Telescope
.update(entity, String::toLowerCase);
```

The return type degrades to a terminal `Telescope` when the target isn't itself annotated (so there's no
`Path` to chain into). The reverse direction (target's Path getting `.asSource()`) still goes through
`.then(SourceBridge.BRIDGE.reverse())` for now — forward only at the navigator level.

Gradle wiring:

```kotlin
implementation("io.github.eschizoid:telescope-core:1.0.5")
annotationProcessor("io.github.eschizoid:telescope-codegen:1.0.5")
```

`@Focus` and `@BeanFocus` are source-retention and inert without the processor, so annotating costs nothing if you don't
wire up codegen. Only top-level records / classes are supported (the generated top-level navigator can't reference a
nested type's constructor).

**`@BeanFocus` — the POJO analog.** Same surface as `@Focus`, applied to a POJO with either a static `builder()` or a
no-arg constructor + `setX` setters. Field injection isn't available to generated code, so a POJO that exposes neither
is a compile error; reach for runtime `Telescope.ofBean` in that case. Compare ~488 ns for the runtime `ofBean` 3-level
path vs ~15 ns for a generated `@Bridge` conversion in the benchmark — the navigator gets you the same reflection-free
win for navigation.

```java
import io.github.eschizoid.telescope.annotations.BeanFocus;

@BeanFocus public class UserBean { /* getId/getEmail + setters, or a static builder() */ }

// Generated alongside: UserBeanPath with the same fluent surface as a record navigator.
UserBeanPath.of().email().update(user, String::toLowerCase); // no reflection
```

---

## Effects

The same path that powers `.update(...)` lifts through four effects with one method change: **async**,
**all-or-nothing**, **short-circuit**, and **error-accumulating**. Validate every email in a `Batch` and report all the
bad ones in one call? Two lines. Run an HTTP normalization call for every focused element with bounded concurrency? Pass
an `Executor`. The DSL writes the structural plumbing; you supply the per-element function.

Pick the method by the function you have — the type system picks the applicative. Chaining stages of different effects
is handled by the bridge methods on `Either` / `Validated`; see [Chaining stages](#chaining-stages).

### Picking the method

**Picking between `updateEither` and `updateValidated`:**

- Use **`updateEither`** when failures should _halt work_: parsers where a malformed root makes children meaningless,
dependent stages, expensive per-element calls. Subsequent elements are never even called.
- Use **`updateValidated`** when you want _every_ problem reported: form validation (show the user every wrong field at
once), batch quality reports, lightweight predicates over many elements. Every element is processed; failures are
collected.

The difference is control flow, not just result shape. You can't recover short-circuit behavior by post-converting a
Validated result, and you can't recover all-errors reporting from an Either that stopped after the first failure.

### The four effects, one at a time

Each effectful method works on its own. Pick the one that matches the function you have. The examples below share this
tiny domain:

```java
record Order(String id, String email) {}

record Batch(List orders) {}

// Reusable path declared once, used by every example below.
static final Telescope ALL_EMAILS = Telescope.of(Batch.class).each(Batch::orders).field(Order::email);
```

**`updateAsync` — fan out, gather back.**

```java
// Hit an HTTP service to normalize every email in parallel. The future completes
// when every per-element future has completed; failures propagate.
final CompletableFuture done = ALL_EMAILS.updateAsync(batch, normalizer::normalizeAsync);
```

The path navigation, the per-element future creation, and the structural rebuild collapse into one method call. The
naive alternative — `stream().map(CompletableFuture::supplyAsync).collect(toList())` followed by
`CompletableFuture.allOf(...)` followed by manual reconstruction of the `Batch` — is the boilerplate this replaces.

**`updateValidated` — collect every error.**

```java
record EmailError(String email, String reason) {}

final Validated result = ALL_EMAILS.updateValidated(batch, this::checkEmail);

return result.fold(this::respondBadRequest, this::save);

// The per-element predicate lives in a named method — easier to read, easier to test:
private Validated checkEmail(final String email) {
if (!email.contains("@")) return Validated.invalid(new EmailError(email, "missing @"));
return Validated.valid(email.toLowerCase());
}
```

Every bad email across the entire batch is reported, not just the first one. The applicative does the accumulation. The
user code never touches an error list directly.

**`updateEither` — short-circuit on the first failure.**

```java
record ParseError(String input, String message) {}

final Either result = ALL_EMAILS.updateEither(batch, EmailParser::tryParse);

return result.fold(this::respondError, this::save);
```

The first email that fails to parse wins; later emails aren't even called. Use this when the first failure is enough —
it's strictly cheaper than `updateValidated` because there's no accumulation.

**`updateOptional` — all-or-nothing.**

```java
// If any single email fails to mask (returns Optional.empty), the whole batch becomes empty —
// partial state is impossible.
final Optional masked = ALL_EMAILS.updateOptional(batch, this::tryMask);
```

This is the right tool when a partially-updated structure would be a bug, not a feature.

### Bounded async

By default `updateAsync` invokes `fn` synchronously per focused element; concurrency is whatever the futures returned by
`fn` already had. To cap concurrent invocations, pass an `Executor`:

```java
try (final var pool = Executors.newFixedThreadPool(10)) { // ≤10 in-flight HTTP calls
final CompletableFuture done = path.updateAsync(batch, this::fetchAsync, pool);
done.join();
}
```

`fn` is wrapped in `CompletableFuture.supplyAsync(..., pool)`, so the executor bounds when `fn` is called. For fully
non-blocking `fn` (e.g. `HttpClient.sendAsync`) that's the right bound; for blocking work inside `fn`, the pool size is
the literal upper bound on in-flight operations.

### Working with `Either` and `Validated`

`Either` and `Validated` are sealed records shipped with the library, no Vavr/Arrow dependency. The typical
handler is `.fold(...)`:

```java
return parsed.fold(this::respondError, this::save);
```

Pattern matching also works when you need to destructure the value, but Java's inference can't elide the type parameters
in switch arms, so `.fold(...)` is usually less noisy:

```java
return switch (parsed) {
case Either.Right(var c) -> save(c);
case Either.Left(var err) -> respondError(err);
};
```

Both `Either` and `Validated` expose the same compact handler API:

| Method | Notes |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `fold(onLeft, onRight)` | Collapse both sides into a single value. Usually what you want. |
| `map(f)` | Transform the success side; failure passes through. |
| `isLeft()` / `isRight()` | Boolean tests, when a `switch` would be overkill. |
| `mapLeft(f)` (Either) | Transform the failure side; useful for normalizing error types at a boundary. |
| `mapErrors(f)` (Validated) | Same idea as `mapLeft`, applied to every accumulated error. |
| `swap()` (Either) | Flip left and right. |
| `flatMap(f)` (Either) | Sequence two Eithers; short-circuits on the first `Left`. |
| `andThen(f)` (Validated) | Sequence two Validateds; short-circuits on `Invalid` (use `combine` to accumulate). |
| `Validated.combine(a, b, f)` (Validated, static) | Combine two Validateds; accumulates errors across both branches. |
| `toValidated()` (Either) | Bridge to `Validated`: `Left(e)` becomes a single-element `Invalid([e])`. |
| `toEither()` (Validated) | Bridge to `Either`: `Invalid(errs)` becomes `Left(errs)`. |
| `flatMapAsync(f)` (both) | Sequence an async stage; failures stay in the result, only success runs. |
| `toOptional()` (both) | Drop the error and bridge to JDK `Optional`. Use when downstream only cares about the success path. |
| `getOrElse(default)` (both) | Return the success value, or `default` on failure. |
| `getOrElseGet(supplier)` (both) | Same, with a lazy default for expensive cases. |
| `combineAll(List<…>)` (Validated, static) | Combine a list of validations into a `Validated>`; accumulates every error. |

### Chaining stages

Multi-stage flows use the bridge methods on `Either` / `Validated` to keep the error channel consistent across different
effects. The pattern is: normalize each stage's error type with `mapErrors` / `mapLeft`, bridge between accumulating and
short-circuiting with `toEither` / `toValidated`, then `flatMap` / `andThen` for sync stages or `flatMapAsync` when the
next stage returns a `CompletableFuture`.

Sync-only example — validate emails, then look up users, with one unified `List` error channel:

```java
// Stage 1: collect every bad email, then hand off to short-circuit code
// → Either, Batch>
final Either, Batch> afterEmails = emailPath
.updateValidated(batch, this::checkEmail)
.mapErrors(EmailError::reason) // EmailError -> String
.toEither(); // accumulating -> short-circuit

// Stage 2: short-circuit on the first user lookup failure, normalize its error too
// → Either, Batch>
final Either, Batch> afterUsers = afterEmails.flatMap((b) ->
userPath.updateEither(b, this::lookupUser).mapLeft((err) -> List.of(err.id() + " not found"))
);
```

Crossing into an async stage uses `flatMapAsync`, which mirrors `flatMap` but accepts a function returning a
`CompletableFuture`. Errors remain in the `Either` (or `Validated`) result; only the success side runs asynchronously:

```java
return afterUsers.flatMapAsync(ok -> enrichPath.updateAsync(ok, this::enrich));
// → CompletableFuture, Batch>>
```

---

## Constraints worth knowing

1. **Records only.** Field navigation rebuilds via the record's canonical constructor. Non-record types throw at runtime
with a clear message. To work with POJOs, bridge them to a record — see [Working with POJOs](#working-with-pojos).
2. **Method references, not lambdas.** `User::name` works; `u -> u.name()` doesn't. The compiler synthesizes a name like
`lambda$xx$0` and we can't recover the field name from it. The library throws a clear error.
3. **`List` element types are inferred from the method-ref signature**, not from runtime generics. That's why
`each(Team::users)` works without a type witness — `Team::users` has compile-time type `Function>`
and Java unifies `E = User`.
4. **Reflection cost.** Field access uses `RecordComponent.getAccessor().invoke(...)` and the canonical constructor —
roughly ~100 ns per reflective field access, vs ~10 ns for a hand-written record copy; the reflection-free `lens`
path (`@Focus` codegen) sits in between. Fine for almost everything; matters for tight loops. See
[`benchmarks/`](benchmarks/README.md) for measured numbers.
5. **Sibling-context updates close over the source.** A plain `update` lambda only sees the focused value. If you need
to read sibling fields (e.g., focus `LineItem::unitPrice` but want the sibling `sku` to call a price service), the
source is already in scope as the first argument — reference it inside the lambda
(`update(order, item -> … order.sku() …)`). Hoist the source to a local first if it's an expression.
6. **One documented runtime-check point on the runtime DSL.** Every typed entry point (`.field(Accessor)`,
`.each(Accessor)`, `.list(Accessor)` / `.set` / `.map` / `.optional` and their typed terminals,
`.eachValue(Accessor)`, `.whenPresent(Accessor)`, the static `Telescope.asList` / `asSet` / `asMap` / `asOptional`
promotions, the bridges, `.with(fn)`, `.apply(S)`, every `update*` variant) is fully compile-checked. One escape
hatch is _not_ compile-checked, by design, and it's named so the call site says so:
- `.fieldByName(String)` / `.fieldByName(String, Class)` — late-bound field name (config-driven paths). `javac`
can't verify the name exists or that the inferred type matches the actual field. Wrong name → runtime error.