Move the unmarshaler handoff to internal/unmarshal

[creasty]

Before parsing a tag by kind, fillField offers it to the field's own UnmarshalText and then to its UnmarshalJSON, and takes whatever one of them makes of it. Which unmarshaler is asked first, what each is not asked at all, and whose rejection is reported when neither took the tag are rules about unmarshalers, not about defaults: nothing in them needs a field, a tag or a walk.

This is the second of three moves into internal/, after #109: the promoted-method check, the unmarshaler handoff here, and then the state a walk carries down a path.

The change

The handoff becomes internal/unmarshal.Tag(target any, value string) (bool, error). The package takes what an unmarshaler is implemented on rather than a reflect.Value, so reflect stays out of its contract and its tests pass ordinary pointers:

unmarshaled, unmarshalErr := unmarshal.Tag(field.Addr().Interface(), defaultVal)

set.go loses the encoding import, and keeps encoding/json, which the kind switch still decodes tags with.

One thing changes beyond the move. The old code called field.Addr().Interface() twice, once per type assertion; the call site calls it once for both. That is work removed from the path every tagged zero field takes, and it shows up in the benchmarks below.

Why a package

The handoff has four rules the suite could only show through Set, which needs a struct and a tag to ask any of them — set_unmarshaler_test.go spends 617 lines doing so. Under internal/ it is no more public than it was, and each rule is a line. The handoff was a call before the move and is a call after it (unmarshalByInterface cost 438 against the inliner's budget of 80; Tag costs 196), so the boundary adds nothing.

Behavior change

None. set_unmarshaler_test.go's 12 tests pass unchanged through the new call site.

Pins

• internal/unmarshal/unmarshal_test.go, black box (package unmarshal_test), 12 cases. The fixtures keep what they were offered, so a test can tell an unmarshaler that was never asked from one that was asked and took it, and each carries the error it refuses with, so the suite keeps no package-level sentinels and every test names the rejection it expects.
  • Taken: by UnmarshalText; by UnmarshalJSON where there is no UnmarshalText; by UnmarshalJSON after UnmarshalText refused it.
  • Order: a target implementing both is asked through UnmarshalText, and UnmarshalJSON is never offered the value.
  • Rejected: both refuse, so the first rejection is the error; UnmarshalJSON's when it was the only one asked.
  • Not offered: an empty value, to either; "{}" and "[]" to UnmarshalJSON, which would read them as an empty object or array, while UnmarshalText is offered them like any other value; anything at all to a target implementing neither.

Verified

• gofmt -s -l . and go vet ./... are clean. make test passes. make cover (-race -shuffle=on, ./...) gives 100.0% in all three packages, Tag among them. make bench-smoke passes all 46 cases.
• -gcflags=-m still reports path does not escape for set, setField and fillField, and moves nothing to the heap.
• Benchmarks: make bench-compare BASE=origin/master, 6 interleaved rounds at 400ms, Go 1.26.5 darwin/arm64. Allocations identical on every row. The rows that reach the handoff with a tag on a zero field are 3–12% faster — every Parse row but escaped_tag (−2.90% to −7.61%), Set/scalars −5.79%, Set/composites −6.47%, Walk/pointer/tagged_ints −12.32%, Walk/pointer/tagged_chain/depth=4 −10.67%, Fail/nested −7.80% — while the rows that never reach it do not move (Walk/struct/untagged, Walk/struct/nested_values, Walk/slice/structs, Walk/slice/pointers, Walk/pointer/caller_chain). That pattern is the removed Interface() call rather than code placement. Walk/map/slices reads +1.65%, the one row against the pattern, and it parses no tag. Geomean −2.60%.
• Two rows checked over 12 fresh processes each: Parse/unmarshaler/text reads −1.87% in the table but 109–114 ns on both sides, so take it as unmoved; Walk/slice/pointers, which split into two modes while the path index was written, is 184–187 µs here.
• Not run locally: golangci-lint (the installed v1 cannot read the v2 config) and the Go 1.22 leg. CI covers both.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (120766a) to head (79bab8c).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #110   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            5         6    +1     
  Lines          310       310           
=========================================
  Hits           310       310           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.