Research: Closing the runtime throughput gap (Tier 2 #1.6)

[eschizoid]

Status: exploratory research. The Tier-A slice landed in PR #117 with honest measurements (see below); Tier B was within noise; Tier C remains the dominant remaining opportunity. Estimates here are direction-of-travel from theory + quick-pass benchmarks — production engineering needs profiler-led validation.

Goal

Close the gap between Telescope's runtime Telescope.mapper(...) path and MapStruct's compile-time-generated bytecode.

Where the gap actually lives — honest re-measurement

Earlier framing on PR #117 implied an 8× speedup from the fast-path. That comparison was apples-to-oranges (bean→record slow path vs record→record fast path). The honest comparison on identical fixtures (JDK 25, Apple Silicon, 2-fork × 5-warmup × 10-iter × 1 s):

Fixture (5 flat scalar fields)	Slow path (ns/op)	Fast path (ns/op)	Δ
record → record	50.4 ± 6.6	44.0 ± 1.5	~12%
bean → record	375.9 ± 7.6	— ¹	—
record → bean	507.9 ± 7.6	— ¹	—

¹ Mixed shape — fast-path tightly requires both sides be the same kind.

The 90× gap to MapStruct lives in the bean↔record / record↔bean rows. Record↔record was already cheap on the slow path because records have LMF-built readers + canonical-ctor spreader. Bean↔X is dominated by getter/setter reflection through the structural Iso + the LinkedHashMap intermediate.

Where the time goes (bean→record slow path, ~376 ns)

preForward hook (null check) — ~1 ns
iso.to(s):
  source structuralIso.from(s) → LinkedHashMap of name → value:
    × 5 bean getter via LMF Function — ~10 ns each ≈ 50 ns
    LinkedHashMap.put per field — ~10 ns each ≈ 50 ns
  remap step (identity in pure auto case):
    × 5 HashMap.get — ~10 ns each ≈ 50 ns
  target structuralIso.to(map) → record:
    × 5 HashMap.get — ~50 ns
    × 1 LMF Supplier.get → canonical ctor invoke ≈ 5 ns
  composition chain virtual dispatch through 3 Iso instances ≈ ~30 ns
postForward hook (null check) — ~1 ns

Bean getter dispatch + HashMap intermediate = ~80% of the cost. The Iso composition chain is ~10%.

Optimization candidates, priority ranked

Tier A — record↔record + bean↔bean fast-path (LANDED in #117)

Per-pair Function<S, T> via cached LMF readers + canonical-ctor spreader. Skip structural Iso composition entirely for the pure-auto-recursion same-shape case.

Measured: ~12% on record→record. Smaller than predicted because records were already cheap. Real value: eliminates the LinkedHashMap intermediate for the eligible cases.

Tier B — Iso composition fusion (LANDED in #117, no measurable speedup)

Fuse the 3-hop srcReader.then(remap).then(tgtBuilder) chain into one Iso with two Function bodies. Architecturally cleaner (2 fewer anonymous Iso allocations per pair, 1 virtual Iso.to dispatch instead of 3). Per-call gain within noise (~3% on the 2-fork bench).

Why it didn't move the needle: composition allocations only fire at build-time. JIT was already inlining the per-call chain reasonably.

Tier C — LinkedHashMap → Object[] structural intermediate (NOT YET LANDED)

This is the big remaining win. Replace the per-call LinkedHashMap<String, Object> intermediate with Object[] indexed by component position. Per-class name → index table cached at populateIso time.

• Impact target: bean→record (376 ns), record→bean (508 ns). Eliminates ~50 ns of HashMap put + ~50 ns of HashMap get per call, plus alloc/GC pressure from the throwaway map.
• Surface: modifies Reflective.structuralIso shape from Iso<S, Map<String, Object>> to Iso<S, Object[]>. Touches all consumers in DeepMap. Real engineering.
• Predicted gain: 30-50% on bean↔X slow paths. Concrete number depends on JIT escape analysis improvements once the map allocation is gone.

Tier D — minor wins (post-Tier C)

• MethodHandle for the Iso chain (probably negligible; the function references already inline)
• Monomorphic per-field Iso composition
• String.hashCode caching (irrelevant once the map intermediate is gone)

What we are explicitly NOT proposing

• Runtime bytecode generation (ASM, ByteBuddy, MethodHandles.classData). Would close the gap further but:

  • Adds ASM as a runtime dependency (~300 KB jar)
  • GraalVM native-image compatibility becomes a nightmare (closed-world assumption fights runtime class generation)
  • --release 17 cross-compile target breaks if we lean on newer MethodHandle.classData APIs

• The Tier A–D approach uses only LambdaMetafactory + cached Function / Supplier — the same primitives already proven in :internal/Beans.java and :internal/Records.java. Lattice-honest, no new deps.

Recommendation

• Tier A + B — landed in feat(perf): Tier-A runtime fast-path — record→record + bean→bean #117. ~12% on record↔record + architectural cleanup. Honest, small wins.
• Tier C — the dominant remaining opportunity. Bean↔X paths (90+× MapStruct) are where adopters feel the pain. Worth a focused PR.

After Tier C, expected ~5-10× MapStruct on bean↔record at the flat tier. At that point the runtime path is "fast enough" for the vast majority of production services and @Bridge codegen remains the documented mitigation for hot paths.

Open questions for design review

1. Cycle interaction. Object[]-backed structural intermediate must coexist with the existing value-level cycle guards in DeepMap.lazyCacheIso. Need a clean test that pins this.
2. Slow-path eligibility boundary. Single Mapping.to(...) row probably stays fast (just substitutes one reader); single Mapping.via(...) probably falls back (nested mapper composition). Needs spec.
3. GraalVM native-image. Can the LMF Function/Supplier substrate survive --initialize-at-build-time for the Tier-C arity cache? Probably yes (matches existing Beans.java pattern) but unverified.

[eschizoid]

Tier C landed — measured outcome

PR #118 (Object[] structural intermediate, replacing the LinkedHashMap<String, Object>) is open and measured cleanly on a freshly rebooted machine. The Tier-C prediction in the original post was 30-50% on bean↔X slow paths; measured 52-58% across every runtime row.

Tier	Direction	Before (Map)	After (Object[])	Δ %
flat	bean → record	340.13 ± 7.9	143.38 ± 2.3	-58%
flat	record → bean	464.27 ± 23.5	213.26 ± 2.5	-54%
nested	bean → record	501.43 ± 15.4	241.21 ± 0.9	-52%
nested	record → bean	709.86 ± 12.4	332.80 ± 5.1	-53%
deep	bean → record	2024.06 ± 380	926.83 ± 25	-54%
deep	record → bean	2292.43 ± 28	1274.30 ± 120	-44%

Allocation per op (the structural change, immune to bench noise):

Benchmark	Before	After	Δ
flat bean → record	776 B/op	112 B/op	-86%
flat record → bean	856 B/op	256 B/op	-70%
nested forward	1200 B/op	176 B/op	-85%
nested backward	1296 B/op	384 B/op	-70%

What the gap looks like now

Flat bean → record: 143 ns vs MapStruct 3.5 ns ≈ 41× gap (down from ~78×). Allocation pressure now in a regime where the JIT can scalar-replace the surviving Object[] on monomorphic call sites.

Tier D research — three agents reported in

Top-5 consolidated levers, ranked by estimated ns reclaim:

1. Holder emits a positional constructArr(Object[]) constructor — kills the i → arr[indexOf(componentNames, i)] O(N²) scan in Reflective.structuralIsoArr bean branch. Est. 30-60 ns.
2. Records fast path for holder-annotated records — gate at Reflective.java:184 excludes @Focus-records that already have RecordInfo.readers[] + ctorFn. Est. 15-30 ns.
3. Hoist FORWARD_SEEN ThreadLocal cycle guard for acyclic type pairs. Est. ~15 ns.
4. Fuse Iso.then 3-hop chain into a single specialised Iso<S, T> — kills 2 anonymous-class virtual hops + one Object[] alloc. Est. 10-15 ns.
5. Capture Function<Object,Object> directly in resolveReadersByPosition instead of the instance -> read(instance, capturedName) wrapper. Est. 10-15 ns.

Cumulative headroom: ~80-135 ns → flat bean → record from 143 → ~10-60 ns (~3-17× MapStruct).

Big-swing alternative: per-pair specialised flat Mapper<A, B> via MethodHandles.filterArguments / permuteArguments — bakes the 5 getters + canonical ctor into a single MH chain. Target ~15-25 ns (~5-7× MapStruct). Eligibility-gated (no overrides, no telescope rows, no conditional, no BUILDER target). Risk: MH composition inlining is empirically 1.5-3× slower per dispatch than LMF.

Next

Sequence the five levers as small surgical PRs. Re-measure after each so we don't carry compounded noise. Defer the MH-specialised mapper until the surgical wins are quantified.

[eschizoid]

Tier D — detailed research findings (3 agents, post-Tier-C)

Now that Tier C is measured (52-58% time + 70-86% allocation), we dispatched three read-only research agents in parallel to scope what's next on the runtime path. Their findings, consolidated:

---

Agent 1 — Post-Tier-C ns budget for flat bean → record (~178 ns target)

#	Step	File:Line	ns est.	Confidence
1	5× bean-getter LMF dispatch (ClassValue + HashMap + Function.apply)	Beans.java:371-380	~70	high — matches beanGetterRead_lmf × 5
2	Per-slot captured-lambda wrapper instance -> read(instance, capturedName)	Reflective.java:233-234	~3-6	medium
3	Forward Object[5] allocation in srcReader.from	Reflective.java:209-211	~5	medium — partly scalar-replaceable
4	Backward remapIsoArr Object[5] + 5× IDENTITY_OBJ_ISO.to virtual dispatch	DeepMap.java:1127-1135	~20	high
5	Record ctorFn.apply via LMF + 2× primitive boxing (int, boolean)	Records.java:288-310	~40	medium-high
6	Three-layer Iso.then virtual dispatch chain (nullable→srcReader→remap→tgtBuilder)	Iso.java:259-272, DeepMap.java:1079	~15	medium
7	nullable forward null-check + lambda hop	DeepMap.java:1192	~2	high
8	Cycle-safe shell: FORWARD_SEEN ThreadLocal + IdentityHashMap + try/finally	DeepMap.java:1170-1184	~15	medium-high
9	Misc: Mapper.forward indirection, megamorphic warm-up, safepoints	—	~5	low

Sum: ~175 ns (±15 ns band), matches measured 178.4 ns.

---

Agent 2 — Per-pair specialised Mapper<A, B> via MethodHandle composition

Mapper<A, B> is final — can't subclass. But we can swap the inner Iso<A, B> at resolveMapper time, building a single fast Iso from the substrate already in place:

• Beans.GETTER_INVOKERS exposes per-property MethodHandle (Object) → Object
• Records.buildCtorFn exposes the canonical ctor as MethodHandle (Object[]) → Object via asSpreader

The trick is to bypass the Object[] allocation entirely via MethodHandles.filterArguments + permuteArguments:

ctorMH       : (T1, T2, T3, T4, T5)        → R
getterMH_i   : (A)                         → Ti
permutedMH   : (A, A, A, A, A)             → R   // filterArguments(ctorMH, 0, g1, …, g5)
finalMH      : (A)                         → R   // permuteArguments(..., {0,0,0,0,0})

Eligibility gate (all must hold at populateIso time):

1. Top-level only (v1)
2. Both sides have a single canonical writer (record ctor or bean no-arg + setters) — exclude @WriteHint(BUILDER) for v1
3. No telescopeFixups
4. No Conditional<?, ?> rows
5. No Drop / Constant / Compute rows at top level
6. No registered pre/post hooks at fast-iso install time
7. No fan-out / rename collisions (every FieldStep has both names set, each appears once per direction)
8. Per-slot Iso whitelisted: identity, SameTypedTo, TypedTransformTo, or Via pointing at a specialised child
9. No nullStrategy == DEFAULT for v1
10. Source / target classes not sealed-abstract

Expected ceiling: realistic target 15-25 ns on flat bean → record (~5-7× MapStruct). Codegen @Bridge sits at 5.5 ns — that's the inlined-bytecode ceiling we won't beat without bytecode-gen.

Top risks:

1. MH composition inlinability — filterArguments / permuteArguments produce LambdaForm-backed (non-direct) handles. LMF refuses them, so the final wrap is MethodHandle.invoke from a final field. Empirically 1.5-3× slower per dispatch than LMF.
2. ClassValue cache poisoning — must key by (srcClass, tgtClass, structural-fingerprint-of-byTargetName) since MapStep[] identity isn't stable across mapper(...) calls.
3. Builder-target plumbing — MethodHandle.foldArguments for builder seed + setter sequence is significantly more complex than the canonical-ctor case. v1 defers builder targets.

---

Agent 3 — Holder bridge under-exploitation (ADR-0006)

Three concrete findings, ranked by impact:

Q2 — Holder constructor is name-keyed → O(N²) per call. CONFIRMED.

FocusProcessor emits construct(Function<String, Object> values) whose body is new R((T1) values.apply("compName"), …). At Reflective.java:205, the call site materialises this as i -> arr[indexOf(componentNames, i)] — indexOf is a linear scan. For a 5-field record: 25 string-compares per write call. Fix: emit a second positional constructArr(Object[]) on the holder; per-call cost drops to one cast + one call + N array indices. Est. 30-60 ns/op savings on flat bean → record.

Q1 — Records fast path is missed for @Focus-annotated records. CONFIRMED.

Reflective.java:184 gates the records fast path on cls.isRecord() && holderReaders == null && holderConstructor == null. When a record carries @Focus, both are non-null → control falls through to the bean branch with the wrapping lens::get capture + linear-scan ctor. Fix: add a second fast path that triggers on cls.isRecord() && holderReaders != null and skips the holder entirely (records already have LMF-bound RecordInfo.readers[] + ctorFn — equivalent dispatch, no wrapper). Est. 15-30 ns/op.

Q4 — No cross-call Iso<S, T> cache. CONFIRMED but low impact today.

DeepMap.java:118 allocates a fresh HashMap<TypePair, Iso<?, ?>> per populateIso call — used only for intra-call cycle handling. The 178 ns headline measures a held-onto Mapper, so this doesn't hit the steady state. But users who call Telescope.mapper(...) inline per request (anti-pattern, but seen in MapStruct migrations) re-resolve every call. Cheap to add an opt-in ClassValue<…> for the zero-steps[] path.

Q3 — LinkedHashMap rebuild in holderReadersFor — build-time only, near-zero impact on steady state. Skip unless touching adjacent code.

---

Consolidated 5-lever sequence (post-Tier-C → ~80-135 ns headroom)

#	Lever	Est. ns saved	Source
1	Holder emits positional constructArr(Object[]) — kill indexOf O(N²) scan	30-60	Agent 3 Q2
2	Records-fast-path for holder-annotated records	15-30	Agent 3 Q1
3	FORWARD_SEEN ThreadLocal hoist for acyclic type pairs	~15	Agent 1 entry 8
4	Iso.then 3-hop chain fusion into single specialised Iso	10-15	Agent 1 top-1
5	Capture Function<Object,Object> directly in resolveReadersByPosition	10-15	Agent 1 top-2

Five surgical PRs, no new abstractions, all lattice-honest. Cumulative target: flat bean → record from 143 → ~10-60 ns, i.e. ~3-17× MapStruct (down from 41×).

After those land, the big-swing MH-composed specialised flat Mapper (Agent 2) targets 15-25 ns for eligible pairs (no overrides, no telescope rows, no conditional, no BUILDER target) — gets us to ~5-7× MapStruct without bytecode gen.

What I'm NOT proposing

Same NOT-list as the original post: no ASM / ByteBuddy / runtime bytecode generation. GraalVM native-image and the --release 17 cross-compile target stay intact.

[eschizoid]

Overnight Tier-D experiment run — results

Four experiments shipped overnight, profile-led from a fresh ns-budget on the post-1.0 hot path. Runtime-path gap to MapStruct narrowed from ~78× (pre-Tier-C) to ~11.6× on deep tier — the tier where production code actually lives.

Stacked results (Exp1 + Exp2 — both clean wins, compose orthogonally)

Bench	1.0 baseline	Stacked	Δ ns	Δ %	vs MapStruct
flat fwd	124.04	106.08 ± 1.3	-17.96	-14.5%	31.8× (was 37×)
flat bwd	188.08	173.17 ± 3.0	-14.91	-7.9%	—
nested fwd	204.30	145.59 ± 4.7	-58.71	-28.7%	28.1× (was 39×)
nested bwd	277.92	224.95 ± 4.6	-52.97	-19.1%	—
deep fwd	926.83	548.73 ± 6.9	-378.10	-40.8%	11.6× (was 19.5×)
deep bwd	1274.30	873.97 ± 11.9	-400.33	-31.4%	—

Per-experiment

PR #123 — Exp1: Fuse src+remap — Eliminates the source-side Object[] intermediate in DeepMap.assembleIso. Single fused Iso<S, T> whose forward body gathers directly from srcReaders[fwdSrcPos[i]].apply(s) per target slot. -14 to -8% across all tiers. Bigger than the agent's 6-8 ns prediction — alloc reduction helped escape analysis more than expected.

PR #124 — Exp2: FORWARD_SEEN hoist for acyclic pairs — Skips the cycle-safe shell ThreadLocal probe on statically-acyclic type pairs. Cyclic SCCs still get the full guard. -30% nested fwd, -40% deep fwd. WAY bigger than predicted — the shell fires once per level walked, compounding in deep trees.

PR #125 — Exp3: Stacked Exp1+Exp2 reference — confirms orthogonal composition. Skip merge; reference only.

PR #126 — Exp4: All-identity short-circuit — INCONCLUSIVE. Wins on flat/nested fwd by 1-6 ns, regresses on nested bwd by +8 ns. Most likely cause: adding a second `Iso.of` call site polluted the JIT inline cache. Pushed as research artifact. Worth re-trying as a static factory.

Updated Tier-D queue

• ✅ Tier-C (LinkedHashMap → Object[]) — shipped in 1.0
• ✅ Iso.identity singleton + ref-eq short-circuit — shipped in 1.0
• ✅ O(N²) → O(N) bean forward name dispatch — shipped in 1.0
• ✅ Records-bypass-wrapping-lambda — shipped in 1.0
• ✅ Fuse src+remap — PR experiment: fuse src+remap — kill source Object[] intermediate (~14% flat fwd) #123, ready for 1.1
• ✅ FORWARD_SEEN hoist for acyclic pairs — PR experiment: FORWARD_SEEN hoist for acyclic pairs (~30-40% nested/deep) #124, ready for 1.1
• 🟡 All-identity short-circuit — inconclusive, re-attempt with static factory
• 🔥 MH-composed specialised flat Mapper — big swing, target ~5-7× MapStruct
• 🔥 Positional holder constructor for backward bean targets — target -30 to -60 ns
• ⭐ Codegen BridgeTelescope wrapper drop — ~1 ns codegen flat
• ⭐ Nested sub-bridge inlining at codegen time — codegen nested → parity with MapStruct
• ⭐ Specialised codegen container hops (each / eachValue / whenPresent) — ~8-15 ns per container hop

Next move

Merge #123 and #124 separately to main, cut v1.1.0. Then attack the queue above.

[eschizoid]

Closing — research charter complete

Every actionable tier from this thread landed:

• Tier A + B → feat(perf): Tier-A runtime fast-path — record→record + bean→bean #117 (same-shape fast-path + Iso composition fusion)
• Tier C (the dominant remaining win) → perf(deepmap): Object[] structural intermediate (LinkedHashMap → array) #118: -52 to -58% time, -70 to -86% allocation on bean↔X, replacing the LinkedHashMap intermediate with an Object[] indexed by component position
• Tier D → experiment: fuse src+remap — kill source Object[] intermediate (~14% flat fwd) #123 + experiment: FORWARD_SEEN hoist for acyclic pairs (~30-40% nested/deep) #124 (Exp1 fuse src+remap, Exp2 — clean orthogonal wins); experiment: all-identity short-circuit (INCONCLUSIVE — keep as research artifact) #126 (Exp4 all-identity short-circuit) was inconclusive and is closed as a research artifact

Net effect: the runtime-path gap to MapStruct narrowed from ~78× → ~11.6× on the deep tier (the tier production code lives in), and the later assembly-time bean-reader capture (#175) pushed bean-side rows down further (~half the pre-capture cost).

The canonical, living record of where the runtime path now stands — with the CI-reproducible matrix — is docs/perf-mapstruct-comparison.md. Codegen is a 1.15× near-tie at the deep tier; the runtime path is "fast enough" for the vast majority of services, with @Bridge codegen as the documented hot-path mitigation.

One carry-forward, not blocking: GraalVM native-image verification of the LMF Function/Supplier substrate under --initialize-at-build-time remains unverified. If/when someone targets native-image, that deserves its own focused issue.

Closing as resolved.