1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
//! Shared primitives for transforms that change the feature width.
//!
//! [`super::scaling`] is the sibling of this module and covers every transform
//! whose output is as wide as its input. Neither of its two central assumptions
//! survives a width change: it chunks the output buffer by `data.columns()`,
//! and it proves a batch finite by screening each column's extrema under a map
//! that is monotone in one input value. A width-changing transform has neither
//! property — one output column can read every input column, and the map from
//! a value to an output cell need not be monotone in anything.
//!
//! What is deliberately *not* different is the contract. A batch still
//! transforms completely or writes nothing, an output that is not finite is
//! still reported with its location rather than returned, and both shape checks
//! still happen before the first write. Those are tested guarantees on the
//! width-preserving side, and a width change is no reason to weaken them.
//!
//! # Why the callback is per cell
//!
//! [`expand_preflighted`] takes `Fn(&[f32], usize) -> f32` — one input row and
//! one output column — rather than a row-at-a-time writer. That shape is what
//! makes "write nothing on failure" free. A row-at-a-time writer needs
//! somewhere to put a row it has not yet proven finite, which is either an
//! allocation on the hot path or a partial write into the caller's buffer; a
//! per-cell callback can be *evaluated* without being stored, so the validation
//! pass needs no storage at all and the write pass is reached only once nothing
//! can fail. It is also exactly the shape
//! [`super::scaling::transform_preflighted`] already uses, so the two seams
//! read as one contract with two column rules rather than as two designs.
//!
//! The cost is that a caller which could share partial products between output
//! columns — a polynomial expansion is the obvious one — recomputes them per
//! cell. That is a real cost and it is taken deliberately: it buys the
//! guarantee above, the Criterion lanes make it visible, and per `CLAUDE.md` a
//! faster shape is a change to make when a measurement asks for it rather than
//! when a reading of the code suggests it might.
use crateModelError;
use crate;
/// Validates an expansion request against the fitted widths.
///
/// Returns the required output length so callers cannot recompute it
/// differently. The input width, the length overflow, and the output length are
/// all checked before any write, so a rejected batch leaves `output` exactly as
/// the caller left it.
pub
/// Allocates an expansion output and fills it through `expand`.
///
/// The overflow check on the output length is the part worth stating once
/// rather than once per width-changing transformer.
pub
/// Writes `n_features_out` values per input row after proving every one of them
/// finite, and returns a validated view over exactly the values written.
///
/// `proven_finite` is the caller's own sufficient screen: `true` asserts that
/// no cell this batch produces can be non-finite, which lets the values be
/// written in one pass. It is a claim the caller has to have earned — a
/// polynomial expansion earns it by bounding each monomial with the product of
/// its factors' magnitudes, a spline basis under constant extrapolation earns
/// it by being a partition of unity, and a caller with no such argument passes
/// `false` and pays a validation pass. Passing `true` without the argument
/// would not corrupt memory, but it would let a non-finite value reach the
/// output, which is the one thing this function exists to prevent.
///
/// Returning the view rather than `()` is what keeps the finiteness guarantee
/// structural. This function is the code that proves it, so it is the only
/// place among the width-changing transformers that may reach
/// [`MatrixView::from_validated_parts`]; a caller wrapping `output` itself
/// would be restating a claim rather than making one.
pub
/// Feature count below which a batch's magnitudes are bounded on the stack.
///
/// The same number [`super::scaling`] screens with, for the same reason: a
/// fixed array keeps the screen free of an allocation on the transform path,
/// and a batch wider than it simply pays the validation pass instead.
pub const STACK_SCREEN_FEATURES: usize = 256;
/// The largest magnitude each input column carries, or `None` if the batch is
/// wider than the stack screen.
///
/// This is the input half of every sufficient screen a width-changing
/// transformer can offer: `|f(x)|` is bounded by `f` evaluated on these
/// magnitudes whenever `f` is a product of the row's values, which is what a
/// monomial is and what a spline basis is not.
pub
/// Largest expanded width FerricML will build.
///
/// A width is not merely a number here: a fitted expansion reserves a term per
/// output column, and a transformed batch reserves a value per output column
/// *per row*. So an unbounded width is an unbounded allocation, and the bound
/// has to exist for the failure to be a typed error rather than an abort.
///
/// The value matches [`super::scaling`]'s own artifact ceiling, deliberately,
/// so the crate has one answer to "how wide may a fitted transformer be"
/// instead of one per module. At this width a single thousand-row batch is
/// already four gigabytes of output, which is the honest scale of what is being
/// refused.
pub const MAX_EXPANDED_FEATURES: usize = 1_000_000;
/// The binomial coefficient `C(n, k)`, or `None` if it overflows.
///
/// Multiply-then-divide with the smaller of `k` and `n - k`, which keeps every
/// intermediate an exact integer: after step `i` the running value is
/// `C(n - k + i, i)`, so the division never truncates. An intermediate can
/// still overflow where the final value would have fitted, which is why this
/// returns an option rather than saturating — the caller turns it into the same
/// typed refusal a genuinely too-wide expansion gets, and a width that only
/// *nearly* overflows `usize` is far past the ceiling above regardless.
pub