fix(avro): resolve field names by NAME when the codec proves it, and reject nested selectors (#95)

[kryptt]

Stacked on #97 (fix/fields-namedtuple-tuplen-96). Merge that one first; this PR's base is
its branch, so the diff shown here is only my six commits.

Fixes the silent field mis-targeting surfaced while investigating #95, plus a second, independent
hazard with the same symptom found while reproducing it.

This does not close #95. That issue asks for an efficient whole-record construction primitive,
and nothing here addresses it. What it does close is the defect its reporter's codec shape exposed:
their schema carries computed/derived columns ("no equivalent of a computed/derived field mechanism"
in the issue body), which is exactly the shape that made every .field(_.x) past the divergence
read and write the wrong slot.

The hazard

.field(_.x) resolved x to the schema field at its DECLARATION INDEX and nothing else.
AvroWalk.fieldNameAt's whole body was fields.get(declIdx).name, guarded only against a
non-record parent (AvroWalk.scala:414) and an index past the end (AvroWalk.scala:422). The
field's name, its type and the record's arity were never consulted.

That is sound exactly while the codec's schema is positionally 1:1 with the case class — true by
construction for every kindlings-derived codec, and not true for a hand-written or
vulcan.Codec field list, which can add a computed column, drop one, or reorder:

// vulcan schema {a, computed, b, c}   vs   case class Three(a, b, c)
codecPrism[Three].field(_.b).getOption(bytes)      // Some("A0|B0")  <- read `computed`
codecPrism[Three].field(_.b).replace("B1")(bytes)  // rewrote `computed`

Valid Avro bytes, wrong content. Nothing catches it: get-put, put-get, put-put and modify-fusion
all hold on a mis-targeted optic (it is a perfectly lawful Optional onto the wrong field),
round-trips hold, and every fixture in AvroSpecFixtures is kindlings-derived, hence 1:1, hence
blind. One function, six call sites:

#	Site	file:line (before)
S1	AvroPrism.widenPath ← .field(_.x)	AvroPrism.scala:249
S2	same ← selectDynamic	AvroPrismMacro.scala:40
S3	AvroPrism.resolveFieldNames ← .fields(...)	AvroPrism.scala:302
S4	AvroTraversal.widenSuffix ← .each.field(_.x)	AvroTraversal.scala:158
S5	AvroTraversal.toFieldsTraversal ← .each.fields(...)	AvroTraversal.scala:219
S6	every deeper hop after .union[B] / a nested .field	AvroWalk.scala:351-380

The mechanism, and why all-or-nothing

One rung above position, firing only when the codec has proved the whole correspondence:

1. Nominal, all-or-nothing. If EVERY case field maps to a DISTINCT schema field — exactly, or
   uniquely up to _/-/. and case — the map is total and injective, so it is the codec's own
   answer, not a guess. Partial or colliding coverage disqualifies the rung for every field.
2. Positional (Field navigation must honor the schema's field names, not the Scala field names #35), unchanged. Where a name transform lands, because a transform REMOVES the
   literal Scala name by construction, so rung 1 cannot have fired.

The totality requirement is the load-bearing part, and it is measured, not argued. The per-field
form of rung 1 ("does THIS field's name appear?") INTRODUCES corruption: FpVisit(userId, user)
against legacy columns {uid, user_id} is correct by position today, and a per-field rung re-aims
userId at user_id — a currently-working call site silently moved to the wrong column. Requiring
totality makes the rung abstain there (user matches nothing) and position stays right.

An arity gate was rejected on the same kind of evidence: it refuses 13 of 28 legitimate call
sites — abbreviated wire names plus a trailing ingested_at, a dropped cachedHash, a trailing
checksum on an element codec, a digest in a nested codec — every one correct today because the
extra field is at the tail and shifts nothing. It buys 3 cells.

False-positive scorecard (ResolutionFalsePositiveSpec, 28 legitimate call sites)

Scored against SLOT TRUTH — which schema slot a write actually touched, never copy(...), which
cannot tell a wrong slot from a stale derived one.

	CORRECT	LOUD-REFUSAL	SILENT-WRONG	SILENT-MISS
before (published behaviour)	28	0	0	0
after (this PR)	27	1	0	0

The single moved cell is hatch-record-probe-absent — .fieldNamed on a name the reader schema
does not carry, None before and a construction-time refusal now. That is the deliberate change
below. The two TRIPWIRE: examples (zero SILENT-WRONG, zero SILENT-MISS) pass both ways and are
the whole safety argument for touching the resolver.

AvroFieldNamingSpec's other 8 examples — issue #35's own snake_case regression suite — pass
untouched.

.fieldNamed is checked at construction

The escape hatch every error message points at appended the literal with no schema lookup at
all, although the prism already holds the schema. A typo — or the Scala field name passed where
the schema name was meant — was a runtime SILENT MISS: reads None, writes hand back the payload
unchanged and report success. Sending someone from a loud construction failure to a silent runtime
one is the wrong direction.

Two carve-outs: a MAP parent (.fieldNamed is also how a map KEY is addressed, keys are data,
and feature-detecting an absent key is legitimate — three cells pin it) and an unresolvable parent
path (the walk already reports that, and refusing would change the meaning of a prism deliberately
built against a drifted root schema). Record-level feature detection moves to
codec.schema.getField(name).

Two existing examples change: AvroFieldNamingSpec's "a bad explicit .fieldNamed misses (None),
it does not corrupt" pinned the defect and now asserts the refusal, and AvroBytesSpec keeps its
PathMissing coverage by storing the PathStep.Field("name") through the internal constructor that
example already uses two lines above.

The nested-selector hole (second, independent bug)

MacroSelectors.extractFieldName matched Lambda(_, Select(_, name)) with any receiver. A
nested path _.inner.y is Select(Select(Ident(_), "inner"), "y"), so it matched, yielded the bare
name "y", and every cursor macro resolved y on the parent:

// NOuter(inner: NInner(x, y), y)
codecPrism[NOuter].field(_.inner.y).getOption(bytes)  // Some("OUTER_Y")
codecPrism[NOuter].field(_.inner).field(_.y)          // Some("INNER_Y")

Silent corruption on a perfectly 1:1, kindlings-derived codec, with no schema divergence involved
at all — and the macros' own "nested paths are not yet supported inside a single call; chain them"
abort was unreachable for exactly the shape it was written for. 100% decidable at compile time.
LensMacro never had this (it uses the strict extractSingleFieldName plus a knownFields.contains
check); the cursor macros simply never got the same treatment.

Both halves land: the extractor now requires the Select receiver to be the lambda parameter
(keeping the wrapper tolerance that is the only reason it exists beside the strict form), and
requireCaseField[A] aborts when a single-hop selector names a non-case-field — those used to pass
through as a literal field name and miss at runtime. Five call sites: AvroPrismMacro.fieldImpl /
fieldTraversalImpl, JsonPrismMacro.fieldImpl / fieldTraversalImpl (eo-circe),
JsoniterPrismMacro.fieldName (eo-jsoniter, shared by prism and traversal). grep finds zero
nested-selector call sites in the repo; the circe, jsoniter, avro and generics suites all pass.

Documented residual limitations (ResolutionResidualSpec, pinned as executable examples)

The memo this PR implements asserted these by inspecting the rule. They are now run, and every
one behaves as predicted:

Cause 1 — no name signal (names unrecoverable AND the list permuted, so the rung abstains and
position decides, wrongly). Reachable only by a differential probe of the codec or an explicit
declaration.

• 5a {beta_name, alpha_name} vs {alpha, beta} — reads beta for alpha
• b2 {seq_no, event_ts} vs {occurredAt, seqNo} — reads the sequence number; a
  timestamp-millis logical type annotates the same physical long, so it cannot disambiguate
• b6 compensating arity (one case field dropped, one computed column added): counts equal, position
  wrong from the insertion point on
• at3 userId_ and user_id both normalise to userid — ambiguity is no signal, so position
  lands on the stale duplicate

Cause 2 — a MISLEADING name signal (a column bears a case field's name but holds a different
value; the map is total and injective, so it is trusted).

• at1 {digest, id, raw_ident, payload} — id is a derived public identifier
• at2 {USER_ID, user_ident, balance} — USER_ID is a stale legacy column

Both cause-2 cells were wrong on 0.15.1 too, with one real cost: the corrupt value is now more
plausible (pub-REAL-ID rather than a digest length). at1's payload is fixed by the change
— it read id before. .fieldNamed reaches all six, and that is asserted too.

Accepted behaviour change: a hand-written codec that permutes the Scala names (writes case
field a into a schema field literally named b, and vice versa) resolved correctly by position and
now resolves by name, i.e. wrongly. No name transform can produce that shape — a transform is a
function of the name alone — but a hand-written field list can.

Cost

Zero per operation, verified from bytecode rather than asserted. javap -p -c over the compiled
avro classes puts every reference to resolveFieldName / fieldNameAt / requireField* in
AvroPrism's widenPath / widenPathNamed / toFieldsPrism / resolveFieldNames and
AvroTraversal's widenSuffix / widenSuffixNamed / toFieldsTraversal. AvroFocus,
AvroFocus$Leaf, AvroFocus$Fields, AvroRecordPrism, AvroRecordTraversal and
AvroBinaryCursor contain none.

Construction time is not free, and the number is reported rather than waved at (best of 5 ×
200 000 builds, same box, same session):

	base	this PR
identity names .field(_.name)	84.9	98.6 ns/build
snake_case .field(_.clickId)	85.1	264.0 ns/build
nested .field(_.meta).field(_.performanceSourceId)	116.9	430.3 ns/build

The gap is inherent to totality: the rung resolves every case field before trusting any one of
them, so a snake_case parent runs a normalised name compare per (case field × schema field) pair
where position ran none. A first cut using Set[Int] for injectivity cost 316 / 462; the shipped
version scans the filled prefix of the result array instead and adds an early "more case fields than
schema fields ⇒ no total map" precondition. Paid once per drilled prism, strictly off the read/write
path.

Back-compat

Every touched signature is private[avro], but transparent inline bakes the accessor into
caller bytecode (inline$widenPath$i1 gains a List[String] parameter), so downstream must
recompile, not re-jar. MiMa is off build-wide (tlMimaPreviousVersions := Set.empty), so this is
a release note, not a build gate; mimaReportBinaryIssues is green.

Gates

sbt "scalafixAll; scalafmtAll", then — as the last step, after every source edit —
scalafmtCheckAll + scalafmtSbtCheck + benchmarks/scalafmtCheck + scalafixAll --check: all
[success]. avroIntegration/test 212/212, root test all green (409 in tests, 212 avro, 92
core, 56 jsoniter, 42 circe, …), mimaReportBinaryIssues clean, docs/mdoc + docs/laikaSite
build.

Follow-ups NOT in this PR

• TargetingLaws / TargetingTests in cats-eo-laws — an optic vs. an extrinsic reference
  accessor. The only thing that can catch a resolution mechanism's own mistake, and the hazard
  class is carrier-wide (circe/jsoniter resolve by the literal Scala name, zio.schema's
  EoAccessorBuilder and kyo's Record.lens[F]("name") are the same shape). The fixtures land here;
  the reusable ruleset is next.
• A differential codec probe — encode two sentinels through codec.encode, diff the slots,
  observe which schema field a case field actually lands in. The only mechanism that reaches residual
  cause 1, needs no declaration and no name heuristics, and would turn a wrong hand-written field
  mapping from believed into refused. Must degrade to the ladder rather than refuse.
• AvroCodec.parseInputUnsafe's fabricated empty record (AvroCodec.scala:329-339) — a parse
  failure yields new GenericData.Record(schema), so modifyUnsafe on 4 junk bytes returns
  {"items": null}: a valid payload with all data erased. Adjacent silent-corruption hole, unrelated
  to resolution, cheap to fix.
• AvroVulcan.codec's eager val schema; .at(i) has no ARRAY check (silent Miss on the whole byte
  face); AvroVulcan.codecMapped as a user-side escape for residual cause 1.

🤖 Generated with Claude Code

https://claude.ai/code/session_0194EHFR4NamCpTHiqy7B74V

[kryptt]

⚠️ These six commits never reached main. This PR was merged into fix/fields-namedtuple-tuplen-96 28 seconds after that branch had itself been squash-merged to main as #97 (8d0cb29), so the merge landed on a ref that no longer had a path to main — confirmed three ways: git merge-base --is-ancestor 7fc97fe origin/main is false, caseNames (the nominal rung's own identifier) has grep -c = 0 in main:avro/.../AvroWalk.scala, and gh api .../compare/main...7fc97fe reports status: diverged.

GitHub refuses to retarget a merged PR ("Cannot change the base branch of a closed pull request"), so the content has been recovered onto a fresh branch off main with these six commits cherry-picked unchanged — the resulting diff is byte-identical to this one (2183 lines, verified with diff -q).

Review continues in #105 (#105); this PR stays closed as a record.