[devmotion]

Almost all of ReverseDiff's broadcasting hung off entry points Julia never documented as extension points, and the documented ones were unused: 2191 Base.broadcast overloads, 1777 broadcast!, and a 2001-method materialize table keyed on any package's style, against a single copy(::Broadcasted) method and no copyto!. Overloading broadcast directly short-circuits the pipeline before a Broadcasted is built, so f.(x) and broadcast(f, x) could diverge, which Base guarantees they cannot.

Design

• TrackedStyle{N} <: AbstractArrayStyle{N} — tracks dimensionality and inherits Base's scalar, tuple and Unknown precedence rules. The broadcast overloads and the materialize table are deleted, so f.(x) and broadcast(f, x) are the same computation by construction. .= into a TrackedArray fails in setindex!, whose error now says to use y = f.(x) instead. Like master's, the new copy also accepts the uninstantiated Broadcasted that LinearAlgebra passes on Julia 1.13.

• The implementation is chosen from the argument types and from Broadcast.combine_eltypes, the inferred element type Base also chooses its output container by. A TrackedArray holds only Reals, so a Complex or Tuple result is traced with the scalar rules, as on master. Inference only picks the path, and both paths give the same derivatives. Inference also decides whether a Real result is recorded: a broadcast whose f cannot return a Dual is left off the tape, and one that can is recorded even if no element did so while recording, so replaying ifelse.(x .> 0, x, 0.0) recorded at negative x still differentiates the other branch. The scalar-rule path keeps the output container Base would pick for the untracked arguments; a TrackedArray of a static array is broadcast as a static array of its elements. The :tracker path and four @generated functions go with it.

• Only tracked arguments are seeded. DiffRules gives besselj a literal NaN partial for its order, and NaN * 0.0 == NaN, so dualizing untracked arguments poisoned every partial of the same Dual, as in besselj.(1.5, y[1] .+ a) or besselj.(nu, y) .* y, which gave NaN gradients on master. Never dualizing untracked arguments also removes the SVector/DiffResults machinery from broadcasting (map still uses it). One tag is derived per broadcast, Tag(BroadcastTag{typeof(f)}(), typeof(argvals)) keyed on the types of all argument values, rather than per element from the element types, so a Dual of an enclosing differentiation, even on an untracked argument, gives a newer tag whenever an argument's type carries it. A Dual hidden in an abstract element type, such as Real[1.0, a], sends the broadcast to the scalar rules, which raise the forward-over-reverse error from the Notes. That includes the case where the configured derivative type could hold the perturbation, GradientConfig(x, typeof(a)), which master differentiated correctly; a concrete [1.0, a] still works. The marker lets @skip drop these perturbations, at every order, as it drops tracking; value leaves them alone. value of a tracked Diagonal rewraps its diagonal, since Julia 1.13 maps over a Diagonal by broadcasting over it, which would be recorded; a test checks that value of every LinearAlgebra.StructuredMatrix type records nothing. ReverseDiff nested inside a broadcast raises the descriptive error from the Notes; tagging it properly is left to Perturbation Confusion (Nested Differentiation Bug) #45.

• Where f's partials are known in closed form, the cache names them instead of storing them. knownpartials dispatches on the operation and its arguments and caches a Contract(op, args) per tracked argument — that argument collects op(seed, args...) from each element of the output's derivative, with args naming broadcast arguments by position:

  	entry
  +, -, identity	identity or -, on the seed alone
  *	* with the other argument
  /, \	/ by an untracked denominator

  A Contract is zero-size, and a named argument is read back through instruction.input where record! already captured it, once per reverse pass, only for known partials and only the arguments a partial names — so nothing is stored, the partial cannot go stale on a replay, and an untracked array is not copied twice. op meets the seed rather than the partial, so / forms no reciprocal, which is how 1e-10 * sum(y ./ 1e-310) keeps the finite gradient Divide instead of multiplying by cached reciprocals (fixes #239) #298 gave it. A tracked denominator (partial -x/y²) keeps a Dual per element, and so do *, / and \ when their two arguments differ in shape and neither is a scalar, and any broadcast with a tuple argument, since tuples are not RealOrArray. + and - name no argument, so they need no shape check.

Against master

Runtime of ReverseDiff.gradient(f, x) for x = rand(n) and an untracked w = rand(n), with Chairmarks, best of five alternating runs:

f(x)	n	master µs	branch µs	time	bytes
sum(x ./ w)	10k	24.83	19.58	0.79	0.86
sum(x .* w)	10k	21.79	19.21	0.88	1.00
sum(x .* x)	10k	28.50	24.96	0.88	1.00
sum(x .* 2.0)	1k / 10k / 100k	2.42 / 15.83 / 156.04	2.19 / 14.25 / 138.88	0.91 / 0.90 / 0.89	1.00
sum(x .+ 2.0)	10k	15.50	13.96	0.90	1.00
sum(x .+ w)	10k	17.54	16.13	0.92	1.00
sum(x .* 2.0 .+ 3.0)	10k	24.58	22.92	0.93	0.87
sum(exp.(x))	10k / 100k	51.62 / 513.92	51.62 / 505.13	1.00 / 0.98	1.00
sum(sin.(x))	10k	86.25	86.71	1.01	1.00

exp and sin keep a Dual per element either way and are at parity. Separately, arrays of TrackedReal whose element type fixes the derivative type are differentiated like a TrackedArray rather than scalar-wise. Recording a broadcast over three such arrays of n = 10k, with a fresh tape per sample:

case	master µs	branch µs	time	bytes	tape entries
x .* y	2205.62	34.25	0.016	0.25	10000 → 1
x .* y .+ z	4527.12	60.25	0.013	0.25	20000 → 1

A Vector{TrackedReal}, which does not fix it, is traced scalar-wise as on master.

Known partials naming such an array, or an adjoint TrackedVector, at n = 16000:

case	master ms	branch ms
v .* Real[b...], with Real[b...] built in f	0.439	0.438
v .* [v[i] for i in 1:n]	0.164	0.159
x' .* x'	8.08	0.238

	master	branch
precompile (Base.compilecache, best of 3)	9.99 s	6.59 s
load (using, best of 5 fresh processes)	1.90 s	1.74 s
methods on broadcast / broadcast! / materialize	2191 / 1777 / 2001	0 / 0 / 0
methods on map / map! / hcat / vcat	2173 / 1759 / 1197 / 1197	1529 / 0 / 1197 / 1197
detect_ambiguities(ReverseDiff)	847 (296 broadcast-related)	551 (0)
src lines	—	−432

All numbers are on Julia 1.12.7, for master at b796032 and the branch at dd47fc9, and the counts are of ReverseDiff's own methods only.

Issues

Each reproducer was run on both sides.

• Fixes MethodError on length(::DiffResults.ImmutableDiffResult{1, Float64, Tuple{Float64}}) #265 — a 0-d broadcast collapsed to a single ImmutableDiffResult, whose length was then taken.
• Fixes Error when using scalar vs. vector to operate on tracked inupt #214 — the scalar and one-element-vector forms now agree; the scalar form raised a ForwardOptimize ambiguity.
• Addresses ReverseDiff defines a huge number of methods. #226 — see the method and ambiguity counts above. hcat/vcat are out of scope and still account for 2394, map for 1529.
• Fixes a BoundsError from map(f, x, y) over a TrackedArray and an array whose element type admits TrackedReal, such as map(hypot, x, Real[1.0, 2.0]) or map(hypot, x, [x[1], x[2]]) (no issue filed). The plain array was treated as constant, yet the reverse pass read its partial. It is now differentiated like a second TrackedArray.
• Fixes a setindex!(::SVector…) error when f's inferred return type is abstract, such as t -> t > 0 ? t : z[] for z = Ref{Real}(0.0) (no issue filed).
• Fixes Incorrect element type when nesting ForwardDiff inside ReverseDiff #67 — ForwardDiff nested inside ReverseDiff: the reproducer's Jacobian is now I, where master raised a MethodError converting a Dual to Float64. This is the reverse-over-forward case from the Notes.
• Addresses Incorrect results when nesting ReverseDiff inside ForwardDiff #168 — forward-over-reverse now raises "ForwardDiff cannot differentiate through ReverseDiff" instead of returning zero derivatives, see the Notes. Its reverse-over-reverse example is Perturbation Confusion (Nested Differentiation Bug) #45 and gives the same wrong result on both sides.
• Getindex of zero-array is ambiguous #126, StaticArray of TrackedReals doesn't currently work (and I think it could) #153 and sum with dims fails if the tracked reals have different types #172 have since been fixed on master (Give tracked reals with a free origin a zero and a one (fixes #172), and pin #126 #302, Support StaticArrays with TrackedArrays (fixes #153) #307), and Method ambiguities with SparseArrays.jl #278 and Ambiguity issue with transposed of sparse matrices from SparseArrays.jl #131 no longer reproduce on either side on Julia 1.12; all five behave identically on both sides.
• Record Broadcast.broadcasted instead of Broadcast.broadcast #215 is deliberately out of scope; this is its prerequisite.

Notes

• .= with a tracked right-hand side still throws — it never worked, and the in-place recording machinery it would route into was itself dead code (map!(DiffResult.value, ...), a UnionAll with no value field). Making it work needs a ∇broadcast!, left as a follow-up.
• The fused map methods taking a TrackedReal are removed. map iterates a scalar as a one-element collection, so there was nothing to fuse, and their reverse pass and replay both threw, on master too. Base and the scalar rules now handle these calls, and recording makes a constant 9 allocations instead of 14–16, about 2× fewer bytes for short arrays and growing with the untracked array's length (28× at n = 1000). The SkipOptimize map methods taking a TrackedReal go too: Base.map and the scalar @skip rules give the same results and leave the tape empty.
• value of a tracked Adjoint or Transpose now keeps the wrapper instead of returning a dense Matrix, as the * rules already unwrapped them.
• @skip now drops every level of ReverseDiff tracking, from arrays as well as scalars, so hessian(v -> sum(v .* @skip(exp).(v)), a) is zero, consistent with its gradient exp.(a); master raises a MethodError there. The fixed-arity SkipOptimize call methods (from 2016) are folded into the Vararg one, which infers and does not allocate.
• seed!'s catch-all is narrowed to ::Real: it silently did nothing for arrays and tuples reaching it from a broadcast whose output element type is not Real. jacobian now raises an ArgumentError for outputs whose elements are not real numbers, such as jacobian(x -> [x, x], x0) or complex results, where master returned zeros.
• Whether an argument could hide a tracked value was decided by fieldcount, which answers differently per version since Array gained fields in 1.11; it is now asked of the element type. A broadcast whose arguments carry a perturbation the derivative type cannot hold now takes the scalar rules: reverse-over-forward such as ReverseDiff.gradient(x -> ForwardDiff.derivative(a -> sum(x .* a^2), 2.0), x0) now works, where master raised a MethodError, and forward-over-reverse raises the error below.
• An elementwise operation on arrays of TrackedReal whose element type fixes the derivative type, such as A + A or A .* 2 for A::Matrix{TrackedReal{Float64,Float64,Nothing}}, now returns a TrackedArray instead of an Array. Recording such a result through a rule that tracks it, such as record_plus, nests one TrackedArray in another via the new track(::TrackedArray, …). Hessians still come out right on direct runs, replays and compiled tapes, but nesting without tags is the perturbation-confusion risk of Perturbation Confusion (Nested Differentiation Bug) #45, and the method carries a TODO for it.
• A broadcast whose f cannot return a Dual, such as round.(x), floor.(x) or (t -> 1.0).(x), is constant in x and now returns a plain Array rather than a TrackedArray with zero derivatives. Like floor and the other scalar rules that return untracked values, it is then left off the tape, so a replay does not recompute it (Non-differentiable operations are left off the tape, so replays return stale values and gradients #313). Such a replay now silently keeps the recorded values, as in sum(round.(x)); master threw while recording it. A type-unstable f, such as t -> t > 0 ? t : 0, is always recorded, with its inferred union promoted (here to Float64); over a static array its results are kept in an MVector, so a replay can write into them. Master failed on these for every array type.
• ForwardDiff differentiating through ReverseDiff, as in ForwardDiff.derivative(a -> sum(ReverseDiff.gradient(x -> x[1] * a, x0)), a0), buries the tracked value in a Dual, and gave zero derivatives on master. It now raises "ForwardDiff cannot differentiate through ReverseDiff", and converting such a Dual to a TrackedReal, which would cut it off the tape, raises an error too. TrackedReals and Duals wrapping tracked values no longer promote to a common type, so reverse-over-forward with arrays mixing both, such as ForwardDiff.derivative(a -> sum([x[1] * a^2, x[2]]), 2.0) inside ReverseDiff.gradient, now works, also through a broadcast; master raised a MethodError. Telling the two nestings apart in general needs tags (Perturbation Confusion (Nested Differentiation Bug) #45).
• A tuple argument with no tracked elements, such as x .* (1.0, 2.0, 3.0), is now fused like an array instead of traced element by element. A tuple with a tracked element is still traced element by element, since its elements are not seeded.
• Unrelated cleanups: the test runner now includes test files by relative path, and show(::TrackedReal) prints its pieces instead of interpolating a string.
• Downstream packages depend on broadcast behaviour, hence the minor version bump.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.27%. Comparing base (27dc11d) to head (2e04217).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #301      +/-   ##
==========================================
+ Coverage   89.37%   94.27%   +4.89%     
==========================================
  Files          19       19              
  Lines        1977     1695     -282     
==========================================
- Hits         1767     1598     -169     
+ Misses        210       97     -113     

☔ 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.