[fft] Prototype: out-parameter storage forms + clobber conventions (NTT first)

[devin-ai-integration]

Summary

Draft/prototype, stacked on #79. Separates storage from semantics the way we discussed: no opaque byte arena — instead the caller pre-constructs/reserves a transformed/product and the engine builds into it, and clobber permission is encoded in the parameter form. engine.hpp states the convention:

const&          borrowed, read-only
&& / by-value   sink: the callee owns it and may clobber (finish works in the product's buffer)
& out-param     overwritten, reusing the object's existing capacity

Each engine concept requirement now carries a comment giving the expected function signature and its reference-passing semantics, e.g.:

// transform(std::span<const value_type> in, int n) -> transformed
// extend_to(transformed& t, int m, std::span<const value_type> coeffs): grows t in place
// mul/sq/mul2(const transformed&..., int n) -> product: inputs borrowed, fresh product returned
// finish(product&& p, std::span<value_type> out, Op = assign_op{}): sink;
// consumes p's contents (the inverse transform runs in p's buffer), but p keeps its allocation

Engine-side (NTT only for now, optional per engine):

transform(in, n, transformed& out)
mul(a, b, n, product& out)
downsample(t, n, odd, out)        // out may alias t (reads are forward of writes)
negate_arg(t, n, transformed& out) // must not alias

The value-returning forms become one-line wrappers over these. Generic callers use dispatch helpers that fall back to move-assignment for engines without the forms:

fft::transform_into<E>(in, n, out);
fft::mul_into<E>(a, b, n, out);
fft::downsample_into<E>(t, n, odd, out);
fft::negate_arg_into<E>(t, n, out);

kth_term_of_rational_function is the consumer proof: tnq/prod/half are hoisted out of the loop, and since the sizes are stable per iteration (transforms at n, products at n/2), each object allocates at most once for the whole computation on engines with the out-param forms.

Findings (allocation audit)

Counting operator new inside one kth_term_of_rational_function call (NTT, warm buffer_pool):

	allocs	bytes
before (#79), d=1000 k≈10^12	202	1.3 MB
before, d=100000 k≈10^15	252	211 MB
after, d=1000	7	45 KB
after, d=100000	7	5.5 MB

(~5% wall-clock improvement at d=100000; identical results.) The per-iteration allocations were: negate_arg (n), mul (n), downsample (n/2) ×2 products, plus the realloc when extend_to doubles the recycled half back to n — all now capacity reuse. Remaining copies: tp = half / tq = half (n/2 each) are inherent while finish consumes its product in place; a non-consuming finish would have to copy anyway.

Open questions before rolling out further:

• whether to promote the out-param forms into the engine concept (making them required) once split/real/crt/algebras implement them, and retire the _into helpers in favor of calling E:: directly;
• sq/mul2/add out-param forms (not needed by this consumer, so omitted);
• whether split's two-span product / algebras' per-channel storage want a different reserve story (they'd benefit the most — their products are the big allocations).

Testing

• Full audit of all fft code on this branch: the NTT out-param aliasing claims verified against core::even_half/odd_half's forward-read structure; the new concept signature comments checked against every engine's actual overloads (ntt/crt/split/real/algebras); finish's keeps-allocation claim confirmed for all engines (each runs the inverse in the product's own buffers). One stale preamble typo fixed (finish(..., span<value_type>& out) → by-value span).
• ./build/tests "[fft]" → 26727 assertions, 85 cases, all pass (the _into fallback path covers the engines without out-param forms).
• Full Library Checker verification on this branch: every fft-related problem AC under both g++ and g++-sanitizer environments, including kth_term_of_linearly_recurrent_sequence 20/20.
• Allocation harness results above (old vs new binaries agree on outputs).

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	🟡 8167/9961 (82.0%)
Functions	🟢 1113/1218 (91.4%)
Branches	🟡 6348/8220 (77.2%)