[fft] Simplify series operand access: direct indexing, span conversion, zero-pad-tolerant extend_to

[devin-ai-integration]

Summary

Removes the recurring rough edges in the series:: layer (now includes the operator normalization originally split out as #80):

1. underlying() is gone. The like contract is now: direct indexing plus two span borrows — into the engine primitives and into the series layer's own exactness-tagged span:

   concept like = ... requires(const S& s, int i) {
       { s[i] } -> convertible_to<const value_type&>;
       { std::span<const value_type>(s) };                          // borrows into engine ops
       requires convertible_to<const S&, span<E, S::exact_v>>;      // borrows into the series layer
   };

   Each wrapper provides operator span<E, exact_v> (vec already had it; cached/cached_span/prefix_cached gain it), and vec gains explicit vec(span<E, exact_>) so materializing an owned copy of any series-like is just exact<E> r(c). std::span<const T> borrows go through std::span's range constructor (deliberately no conversion operator on series::span — offering both paths makes every implicit conversion ambiguous under -Wconversion). cached/prefix_cached keep a non-contract uncached() unwrapper for the by-reference case (subproduct_tree::rev_prod). At the sites: q.underlying()[0] → q[0], span<E, false> a = a_.underlying(); → span<E, false> a = a_;.

2. The sz(coeffs) zero-padding footgun. extend_to's doubling loop clamps each step's read to the coefficients that fit:

   while (t.size() < m) {
       int s = t.size();
       t.v.resize(2 * s);
       core::extend(t.v, coeffs.first(min(sz(coeffs), 2 * s)));
   }

   By the prefix contract, a size-s transform can only exist if all nonzero coefficients fit in 2s — so anything past the clamp is necessarily zero and dropping it is exact (no value inspection, no float-equality trimming). The top-level sz(coeffs) <= 2 * m assert is the one conservative check kept. The old "must extend_to before padding" ordering constraint in kth_term_of_rational_function is gone, and a cache seeded from short coeffs can later be grown with a longer zero-padded buffer of the same sequence.

3. Series operators normalized onto cached_span (folded from [fft] Normalize series operators onto cached_span operands #80). detail::whole_operand is the whole-span counterpart to product_operand: any like operand becomes a cached_span (borrowed coefficients + the cache serving them):

   template <like S>
   cached_span<E, S::exact_v> whole_operand(const S& s, fft::transformed<E>& tmp) {
       return {s, whole_cache_or(s, tmp)};
   }

   square/multiply_add2/middle_product and kth_term_of_linear_recurrence run on that form (auto av = detail::whole_operand(a, ta_); then av, av.cache() straight into the fft:: entry points); operator*'s call sites, operator+/operator-, ps_inv, ps_log's assert, and cached::operator== drop their coefficient plumbing. Internals uniformly use series::span, not std::span, for coefficient views.

No algorithmic or semantic changes: cache selection, precisions, and transform sizes are identical throughout.

Testing

• Full audit of all fft code (all engines' extend_to/transform/finish/downsample/negate_arg against the clamped-prefix contract; series operator cache pairings; poly.hpp/online.hpp call sites) — one issue found and fixed: the dual span-conversion ambiguity above (it produced -Wconversion warnings at every implicit borrow).
• Full unit suite green (2822854 assertions, 106 cases, all engines) after the underlying() removal.
• Full Library Checker verification: every fft-related problem AC under both g++ and g++-sanitizer environments (convolutions incl. crt/split, all FPS ops, composition, multipoint/interpolation, characteristic polynomial, kth_term_of_linearly_recurrent_sequence 20/20); kth_term/multipoint/interpolation re-verified after the contract change.
• Padded-extend harness: seed a transform from unpadded coeffs, extend with a longer zero-padded buffer, compare finish(sq(...)) against a fresh transform — exact agreement (err = 0) across ntt/split/real for lengths {1,2,3,5} × seeds {2,4} × targets {8,16} × paddings.
• Real-engine length-1 extend_to verified bit-identical to fresh transforms across seed/target sizes.

Stacked follow-up: #81 (storage-separation prototype).

Link to Devin session: https://app.devin.ai/sessions/66a2d877f2354e30b3fdfa0c15061db2
Requested by: @ecnerwala

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

GCC Code Coverage Report

📂 Overall coverage

Metric	Coverage
Lines	🟡 7909/9647 (82.0%)
Functions	🟢 1063/1167 (91.1%)
Branches	🟡 6287/8016 (78.4%)

[beta-devin-ai-integration]

Devin Review found 1 potential issue.

[beta-devin-ai-integration]

🟡 New comment packs two clauses onto one line, against the repository's comment formatting rule

The newly added comment above the transform seeding puts two clauses on the same line and wraps mid-clause (// Seed the loop transforms from any whole caches; the buffers below hold the at src/fft/series.hpp:343-344), so it does not follow the repository's documented comment layout.
Impact: Comment formatting diverges from the project's stated style, making the comment harder to edit line-by-line.

Rule in AGENTS.md: one sentence/clause per comment line

AGENTS.md ("Comment style") requires: "Start each sentence/clause on a new line — this makes comments easier to read and edit in a line-based editor. Don't rewrap them into paragraphs." The added comment instead joins two independent clauses with ; on the first line and continues the second clause onto the next line.

Suggested change

	// Seed the loop transforms from any whole caches; the buffers below hold the
	// current p, q (zero-padded, which extend_to ignores).
	// Seed the loop transforms from any whole caches;
	// the buffers below hold the current p, q (zero-padded, which extend_to ignores).

---

Was this helpful? React with 👍 or 👎 to provide feedback.