Skip to main content

logit_loom_diffusion/
projected_component.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Create-new projection transforms for floating-point `SafeTensors` components.
4
5use std::collections::{BTreeMap, BTreeSet};
6
7use logit_loom_core::{CoreError, Digest};
8use serde::{Deserialize, Serialize};
9use serde_json::Value;
10
11/// Maximum selected tensors in one derived-component transform.
12pub const MAX_PROJECTED_COMPONENT_TENSORS: usize = 4_096;
13/// Maximum UTF-8 bytes in one selected tensor name.
14pub const MAX_PROJECTED_COMPONENT_TENSOR_NAME_BYTES: usize = 1_024;
15/// Maximum basis rank accepted by the reference transform.
16pub const MAX_PROJECTED_COMPONENT_BASIS_RANK: u32 = 4_096;
17/// Maximum finite basis elements accepted by the reference transform.
18pub const MAX_PROJECTED_COMPONENT_BASIS_ELEMENTS: u64 = 64 * 1024 * 1024;
19/// Maximum `SafeTensors` JSON header accepted by the transform.
20pub const MAX_PROJECTED_COMPONENT_HEADER_BYTES: usize = 64 * 1024 * 1024;
21
22/// Matrix side on which an orthogonal projection is applied.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "snake_case")]
25pub enum ProjectedComponentFormulaV1 {
26    /// `W' = (I - alpha U U^T) W`; the first tensor axis is the feature axis.
27    LeftProjection,
28    /// `W' = W (I - alpha U U^T)`; the second tensor axis is the feature axis.
29    RightProjection,
30}
31
32/// Deterministic reduction and output-scalar policy.
33#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case")]
35pub enum ProjectedComponentReductionV1 {
36    /// Canonical row/rank order, `f64` accumulation, and one final `f32` cast.
37    OrderedF64ToF32,
38}
39
40/// Exact orthonormal basis declaration.
41#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
42#[serde(deny_unknown_fields)]
43pub struct ProjectedComponentBasisV1 {
44    /// Feature width of each rank-major basis row.
45    pub feature_width: u32,
46    /// Number of rank-major basis rows.
47    pub rank: u32,
48    /// Exact canonical little-endian `f32` basis identity.
49    pub data: Digest,
50}
51
52/// Exact create-new component transform.
53#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
54#[serde(deny_unknown_fields)]
55pub struct ProjectedComponentPlanV1 {
56    /// Exact runtime-compatible topology identity.
57    pub topology: Digest,
58    /// Exact source component bytes.
59    pub source: Digest,
60    /// Exact orthonormal basis declaration.
61    pub basis: ProjectedComponentBasisV1,
62    /// Matrix-side projection formula.
63    pub formula: ProjectedComponentFormulaV1,
64    /// Canonical deterministic reduction policy.
65    pub reduction: ProjectedComponentReductionV1,
66    /// Exact IEEE-754 projection strength bits in `0..=1`.
67    pub strength_bits: u32,
68    /// Canonically ordered exact `SafeTensors` parameter names.
69    pub tensors: Vec<String>,
70    /// Exact implementation identity.
71    pub implementation: Digest,
72}
73
74impl ProjectedComponentPlanV1 {
75    /// Returns the finite projection strength.
76    ///
77    /// # Errors
78    ///
79    /// Returns an error for NaN, infinity, or a value outside `0..=1`.
80    pub fn strength(&self) -> Result<f32, CoreError> {
81        let strength = f32::from_bits(self.strength_bits);
82        if !strength.is_finite() || !(0.0..=1.0).contains(&strength) {
83            return Err(CoreError::invalid(
84                "projected component plan",
85                "strength must be finite and within 0..=1",
86            ));
87        }
88        Ok(strength)
89    }
90
91    /// Validates canonical plan metadata and returns its identity.
92    ///
93    /// # Errors
94    ///
95    /// Returns an error for malformed basis dimensions, tensor selectors,
96    /// strength, reduction, or implementation identity.
97    pub fn digest(&self) -> Result<Digest, CoreError> {
98        let elements = u64::from(self.basis.feature_width)
99            .checked_mul(u64::from(self.basis.rank))
100            .ok_or_else(|| {
101                CoreError::invalid("projected component plan", "basis element count overflowed")
102            })?;
103        if self.basis.feature_width == 0
104            || self.basis.rank == 0
105            || self.basis.rank > MAX_PROJECTED_COMPONENT_BASIS_RANK
106            || elements > MAX_PROJECTED_COMPONENT_BASIS_ELEMENTS
107            || self.tensors.is_empty()
108            || self.tensors.len() > MAX_PROJECTED_COMPONENT_TENSORS
109            || self.tensors.iter().any(|name| {
110                name.is_empty()
111                    || name.len() > MAX_PROJECTED_COMPONENT_TENSOR_NAME_BYTES
112                    || name.contains('\0')
113            })
114            || !self.tensors.windows(2).all(|pair| pair[0] < pair[1])
115            || self.implementation != projected_component_implementation_v1()
116        {
117            return Err(CoreError::invalid(
118                "projected component plan",
119                "basis, tensors, or implementation are empty, excessive, or non-canonical",
120            ));
121        }
122        self.strength()?;
123        Digest::of_serializable("projected-component-plan-v1", self)
124    }
125}
126
127/// Before/after identity for one transformed tensor.
128#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
129#[serde(deny_unknown_fields)]
130pub struct ProjectedComponentTensorReceiptV1 {
131    /// Exact tensor name.
132    pub name: String,
133    /// Tensor bytes before projection.
134    pub before: Digest,
135    /// Tensor bytes after projection.
136    pub after: Digest,
137    /// First matrix dimension.
138    pub rows: u64,
139    /// Second matrix dimension.
140    pub columns: u64,
141}
142
143/// Complete create-new component mutation manifest.
144#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
145#[serde(deny_unknown_fields)]
146pub struct ProjectedComponentManifestV1 {
147    /// Exact plan identity.
148    pub plan: Digest,
149    /// Exact source bytes.
150    pub source: Digest,
151    /// Required topology identity.
152    pub topology: Digest,
153    /// Exact basis identity.
154    pub basis: Digest,
155    /// Applied formula.
156    pub formula: ProjectedComponentFormulaV1,
157    /// Applied implementation.
158    pub implementation: Digest,
159    /// Exact new component bytes.
160    pub output: Digest,
161    /// Canonically tensor-ordered mutation records.
162    pub tensors: Vec<ProjectedComponentTensorReceiptV1>,
163}
164
165impl ProjectedComponentManifestV1 {
166    /// Validates complete lineage and returns the manifest identity.
167    ///
168    /// # Errors
169    ///
170    /// Returns an error for inconsistent plan/source/basis/formula/output or
171    /// incomplete/non-canonical selected-tensor coverage.
172    pub fn digest_for(
173        &self,
174        plan: &ProjectedComponentPlanV1,
175        output: &[u8],
176    ) -> Result<Digest, CoreError> {
177        if self.plan != plan.digest()?
178            || self.source != plan.source
179            || self.topology != plan.topology
180            || self.basis != plan.basis.data
181            || self.formula != plan.formula
182            || self.implementation != plan.implementation
183            || self.output != projected_component_output_v1(output)
184            || self.tensors.len() != plan.tensors.len()
185            || self
186                .tensors
187                .iter()
188                .map(|tensor| &tensor.name)
189                .ne(plan.tensors.iter())
190            || self
191                .tensors
192                .iter()
193                .any(|tensor| tensor.rows == 0 || tensor.columns == 0)
194        {
195            return Err(CoreError::invalid(
196                "projected component manifest",
197                "lineage, output, or tensor coverage differs from the plan",
198            ));
199        }
200        let no_op = plan.strength()? == 0.0;
201        if no_op
202            && self
203                .tensors
204                .iter()
205                .any(|tensor| tensor.before != tensor.after)
206        {
207            return Err(CoreError::invalid(
208                "projected component manifest",
209                "tensor mutation identities disagree with no-op status",
210            ));
211        }
212        Digest::of_serializable("projected-component-manifest-v1", self)
213    }
214}
215
216/// Successful create-new transformation output.
217#[derive(Clone, Debug, PartialEq, Eq)]
218pub struct ProjectedComponentOutputV1 {
219    /// Complete new `SafeTensors` bytes.
220    pub bytes: Vec<u8>,
221    /// Exact mutation manifest.
222    pub manifest: ProjectedComponentManifestV1,
223}
224
225/// Returns the exact reference-transform implementation identity.
226pub fn projected_component_implementation_v1() -> Digest {
227    Digest::of_bytes(
228        "projected-component-implementation-v1",
229        b"safetensors-f32;preserve-header-and-unselected-bytes;ordered-f64-to-f32;create-new",
230    )
231}
232
233/// Returns the exact source-component identity.
234pub fn projected_component_source_v1(bytes: &[u8]) -> Digest {
235    Digest::of_bytes("projected-component-source-v1", bytes)
236}
237
238/// Returns the exact canonical little-endian basis identity.
239pub fn projected_component_basis_v1(bytes: &[u8]) -> Digest {
240    Digest::of_bytes("projected-component-basis-f32-le-v1", bytes)
241}
242
243/// Returns the exact derived-component identity.
244pub fn projected_component_output_v1(bytes: &[u8]) -> Digest {
245    Digest::of_bytes("projected-component-output-v1", bytes)
246}
247
248/// Creates a new projected `SafeTensors` component without changing the source.
249///
250/// The exact source header, metadata, unselected tensor bytes, tensor offsets,
251/// and file length are preserved. Only selected finite `F32` matrix payloads
252/// are rewritten.
253///
254/// # Errors
255///
256/// Returns an error for substituted source/basis bytes, malformed or aliased
257/// `SafeTensors` ranges, unsupported dtype/rank, missing selectors, incompatible
258/// feature axes, non-finite data, a non-orthonormal basis, or arithmetic
259/// overflow. No partial output is returned.
260pub fn project_safetensors_component_v1(
261    source: &[u8],
262    basis_bytes: &[u8],
263    plan: &ProjectedComponentPlanV1,
264) -> Result<ProjectedComponentOutputV1, CoreError> {
265    plan.digest()?;
266    if plan.source != projected_component_source_v1(source)
267        || plan.basis.data != projected_component_basis_v1(basis_bytes)
268    {
269        return Err(CoreError::invalid(
270            "projected component input",
271            "source or basis identity differs from the plan",
272        ));
273    }
274    let basis = decode_f32(basis_bytes, "projected component basis")?;
275    validate_basis(&basis, &plan.basis)?;
276    let parsed = ParsedSafeTensors::parse(source)?;
277    let selected = plan.tensors.iter().cloned().collect::<BTreeSet<_>>();
278    if selected
279        .iter()
280        .any(|name| !parsed.tensors.contains_key(name))
281    {
282        return Err(CoreError::invalid(
283            "projected component plan",
284            "a selected tensor is absent from the source",
285        ));
286    }
287
288    let mut output = source.to_vec();
289    let mut receipts = Vec::with_capacity(plan.tensors.len());
290    for name in &plan.tensors {
291        let tensor = parsed.tensors.get(name).ok_or_else(|| {
292            CoreError::invalid("projected component plan", "selected tensor is absent")
293        })?;
294        if tensor.dtype != "F32" || tensor.shape.len() != 2 {
295            return Err(CoreError::invalid(
296                "projected component tensor",
297                "selected tensors must be rank-two F32 matrices",
298            ));
299        }
300        let rows = tensor.shape[0];
301        let columns = tensor.shape[1];
302        let feature = match plan.formula {
303            ProjectedComponentFormulaV1::LeftProjection => rows,
304            ProjectedComponentFormulaV1::RightProjection => columns,
305        };
306        if feature != u64::from(plan.basis.feature_width) {
307            return Err(CoreError::invalid(
308                "projected component tensor",
309                "declared feature axis is incompatible with the basis width",
310            ));
311        }
312        let absolute_start = parsed
313            .data_start
314            .checked_add(tensor.start)
315            .ok_or_else(|| CoreError::invalid("SafeTensors", "tensor offset overflowed"))?;
316        let absolute_end = parsed
317            .data_start
318            .checked_add(tensor.end)
319            .ok_or_else(|| CoreError::invalid("SafeTensors", "tensor end overflowed"))?;
320        let source_tensor = source.get(absolute_start..absolute_end).ok_or_else(|| {
321            CoreError::invalid("SafeTensors", "tensor range exceeds source bytes")
322        })?;
323        let values = decode_f32(source_tensor, "projected component tensor")?;
324        let expected_elements = rows.checked_mul(columns).ok_or_else(|| {
325            CoreError::invalid("projected component tensor", "matrix size overflowed")
326        })?;
327        if u64::try_from(values.len()).unwrap_or(u64::MAX) != expected_elements {
328            return Err(CoreError::invalid(
329                "projected component tensor",
330                "matrix shape and byte count differ",
331            ));
332        }
333        let transformed = transform_matrix(&values, rows, columns, &basis, plan)?;
334        let transformed_bytes = encode_f32(&transformed);
335        if transformed_bytes.len() != source_tensor.len() {
336            return Err(CoreError::invalid(
337                "projected component tensor",
338                "projection changed the tensor byte length",
339            ));
340        }
341        output[absolute_start..absolute_end].copy_from_slice(&transformed_bytes);
342        receipts.push(ProjectedComponentTensorReceiptV1 {
343            name: name.clone(),
344            before: Digest::of_bytes("projected-component-tensor-v1", source_tensor),
345            after: Digest::of_bytes("projected-component-tensor-v1", &transformed_bytes),
346            rows,
347            columns,
348        });
349    }
350
351    let manifest = ProjectedComponentManifestV1 {
352        plan: plan.digest()?,
353        source: plan.source.clone(),
354        topology: plan.topology.clone(),
355        basis: plan.basis.data.clone(),
356        formula: plan.formula,
357        implementation: plan.implementation.clone(),
358        output: projected_component_output_v1(&output),
359        tensors: receipts,
360    };
361    manifest.digest_for(plan, &output)?;
362    Ok(ProjectedComponentOutputV1 {
363        bytes: output,
364        manifest,
365    })
366}
367
368/// Recomputes and verifies one complete create-new transform.
369///
370/// # Errors
371///
372/// Returns an error if the output or manifest differs from a fresh exact
373/// transform of the supplied source and basis.
374pub fn verify_projected_component_v1(
375    source: &[u8],
376    basis_bytes: &[u8],
377    output: &[u8],
378    plan: &ProjectedComponentPlanV1,
379    manifest: &ProjectedComponentManifestV1,
380) -> Result<(), CoreError> {
381    manifest.digest_for(plan, output)?;
382    let expected = project_safetensors_component_v1(source, basis_bytes, plan)?;
383    if expected.bytes != output || expected.manifest != *manifest {
384        return Err(CoreError::invalid(
385            "projected component verification",
386            "output or manifest differs from exact recomputation",
387        ));
388    }
389    Ok(())
390}
391
392#[derive(Clone, Debug)]
393struct TensorEntry {
394    dtype: String,
395    shape: Vec<u64>,
396    start: usize,
397    end: usize,
398}
399
400struct ParsedSafeTensors {
401    data_start: usize,
402    tensors: BTreeMap<String, TensorEntry>,
403}
404
405impl ParsedSafeTensors {
406    fn parse(source: &[u8]) -> Result<Self, CoreError> {
407        let length_bytes: [u8; 8] = source
408            .get(..8)
409            .ok_or_else(|| CoreError::invalid("SafeTensors", "header length is absent"))?
410            .try_into()
411            .map_err(|_| CoreError::invalid("SafeTensors", "header length is malformed"))?;
412        let header_len = usize::try_from(u64::from_le_bytes(length_bytes))
413            .map_err(|_| CoreError::invalid("SafeTensors", "header length exceeds usize"))?;
414        if header_len == 0 || header_len > MAX_PROJECTED_COMPONENT_HEADER_BYTES {
415            return Err(CoreError::invalid(
416                "SafeTensors",
417                "header length is zero or excessive",
418            ));
419        }
420        let data_start = 8_usize
421            .checked_add(header_len)
422            .ok_or_else(|| CoreError::invalid("SafeTensors", "data offset overflowed"))?;
423        let header = source
424            .get(8..data_start)
425            .ok_or_else(|| CoreError::invalid("SafeTensors", "header exceeds source bytes"))?;
426        let root: Value = serde_json::from_slice(header).map_err(|error| {
427            CoreError::invalid("SafeTensors", format!("header JSON is invalid: {error}"))
428        })?;
429        let object = root
430            .as_object()
431            .ok_or_else(|| CoreError::invalid("SafeTensors", "header root must be an object"))?;
432        let data_bytes = source
433            .len()
434            .checked_sub(data_start)
435            .ok_or_else(|| CoreError::invalid("SafeTensors", "data offset exceeds source bytes"))?;
436        let mut tensors = BTreeMap::new();
437        let mut ranges = Vec::new();
438        for (name, value) in object {
439            if name == "__metadata__" {
440                if !value.is_object() {
441                    return Err(CoreError::invalid(
442                        "SafeTensors",
443                        "metadata must remain a JSON object",
444                    ));
445                }
446                continue;
447            }
448            if name.is_empty()
449                || name.len() > MAX_PROJECTED_COMPONENT_TENSOR_NAME_BYTES
450                || name.contains('\0')
451            {
452                return Err(CoreError::invalid(
453                    "SafeTensors",
454                    "tensor name is empty, excessive, or contains NUL",
455                ));
456            }
457            let entry = parse_tensor_entry(value)?;
458            if entry.start >= entry.end || entry.end > data_bytes {
459                return Err(CoreError::invalid(
460                    "SafeTensors",
461                    "tensor range is empty or outside the data section",
462                ));
463            }
464            ranges.push((entry.start, entry.end, name.as_str()));
465            tensors.insert(name.clone(), entry);
466        }
467        if tensors.is_empty() {
468            return Err(CoreError::invalid("SafeTensors", "contains no tensors"));
469        }
470        ranges.sort_unstable_by_key(|range| (range.0, range.1));
471        if ranges.windows(2).any(|pair| pair[0].1 > pair[1].0) {
472            return Err(CoreError::invalid(
473                "SafeTensors",
474                "aliased or overlapping tensor ranges are unsupported",
475            ));
476        }
477        Ok(Self {
478            data_start,
479            tensors,
480        })
481    }
482}
483
484fn parse_tensor_entry(value: &Value) -> Result<TensorEntry, CoreError> {
485    let object = value
486        .as_object()
487        .ok_or_else(|| CoreError::invalid("SafeTensors", "tensor entry must be an object"))?;
488    if object.len() != 3
489        || !object.contains_key("dtype")
490        || !object.contains_key("shape")
491        || !object.contains_key("data_offsets")
492    {
493        return Err(CoreError::invalid(
494            "SafeTensors",
495            "tensor entry must contain only dtype, shape, and data_offsets",
496        ));
497    }
498    let dtype = object["dtype"]
499        .as_str()
500        .ok_or_else(|| CoreError::invalid("SafeTensors", "dtype must be a string"))?
501        .to_owned();
502    let shape = object["shape"]
503        .as_array()
504        .ok_or_else(|| CoreError::invalid("SafeTensors", "shape must be an array"))?
505        .iter()
506        .map(|dimension| {
507            dimension
508                .as_u64()
509                .filter(|dimension| *dimension > 0)
510                .ok_or_else(|| {
511                    CoreError::invalid("SafeTensors", "shape dimensions must be positive integers")
512                })
513        })
514        .collect::<Result<Vec<_>, _>>()?;
515    let offsets = object["data_offsets"]
516        .as_array()
517        .filter(|offsets| offsets.len() == 2)
518        .ok_or_else(|| {
519            CoreError::invalid("SafeTensors", "data_offsets must contain two integers")
520        })?;
521    let start = usize::try_from(
522        offsets[0]
523            .as_u64()
524            .ok_or_else(|| CoreError::invalid("SafeTensors", "tensor start must be an integer"))?,
525    )
526    .map_err(|_| CoreError::invalid("SafeTensors", "tensor start exceeds usize"))?;
527    let end = usize::try_from(
528        offsets[1]
529            .as_u64()
530            .ok_or_else(|| CoreError::invalid("SafeTensors", "tensor end must be an integer"))?,
531    )
532    .map_err(|_| CoreError::invalid("SafeTensors", "tensor end exceeds usize"))?;
533    Ok(TensorEntry {
534        dtype,
535        shape,
536        start,
537        end,
538    })
539}
540
541fn transform_matrix(
542    values: &[f32],
543    rows: u64,
544    columns: u64,
545    basis: &[f32],
546    plan: &ProjectedComponentPlanV1,
547) -> Result<Vec<f32>, CoreError> {
548    let rows = usize::try_from(rows)
549        .map_err(|_| CoreError::invalid("projected component", "rows exceed usize"))?;
550    let columns = usize::try_from(columns)
551        .map_err(|_| CoreError::invalid("projected component", "columns exceed usize"))?;
552    let width = usize::try_from(plan.basis.feature_width)
553        .map_err(|_| CoreError::invalid("projected component", "basis width exceeds usize"))?;
554    let rank = usize::try_from(plan.basis.rank)
555        .map_err(|_| CoreError::invalid("projected component", "basis rank exceeds usize"))?;
556    let strength = f64::from(plan.strength()?);
557    if strength == 0.0 {
558        return Ok(values.to_vec());
559    }
560    let mut output = values.to_vec();
561    match plan.formula {
562        ProjectedComponentFormulaV1::LeftProjection => {
563            for column in 0..columns {
564                for vector in 0..rank {
565                    let basis_row = &basis[vector * width..(vector + 1) * width];
566                    let coefficient =
567                        basis_row
568                            .iter()
569                            .enumerate()
570                            .fold(0.0_f64, |sum, (row, basis)| {
571                                sum + f64::from(*basis) * f64::from(values[row * columns + column])
572                            });
573                    for (row, basis) in basis_row.iter().enumerate() {
574                        let index = row * columns + column;
575                        let next =
576                            f64::from(output[index]) - strength * coefficient * f64::from(*basis);
577                        output[index] = finite_f32(next)?;
578                    }
579                }
580            }
581        }
582        ProjectedComponentFormulaV1::RightProjection => {
583            for row in 0..rows {
584                let offset = row * columns;
585                for vector in 0..rank {
586                    let basis_row = &basis[vector * width..(vector + 1) * width];
587                    let coefficient =
588                        basis_row
589                            .iter()
590                            .enumerate()
591                            .fold(0.0_f64, |sum, (column, basis)| {
592                                sum + f64::from(values[offset + column]) * f64::from(*basis)
593                            });
594                    for (column, basis) in basis_row.iter().enumerate() {
595                        let index = offset + column;
596                        let next =
597                            f64::from(output[index]) - strength * coefficient * f64::from(*basis);
598                        output[index] = finite_f32(next)?;
599                    }
600                }
601            }
602        }
603    }
604    Ok(output)
605}
606
607#[allow(
608    clippy::cast_possible_truncation,
609    reason = "the declared output representation is finite f32"
610)]
611fn finite_f32(value: f64) -> Result<f32, CoreError> {
612    let value = value as f32;
613    if !value.is_finite() {
614        return Err(CoreError::invalid(
615            "projected component arithmetic",
616            "result overflowed finite f32",
617        ));
618    }
619    Ok(value)
620}
621
622fn validate_basis(values: &[f32], basis: &ProjectedComponentBasisV1) -> Result<(), CoreError> {
623    const TOLERANCE: f64 = 1.0e-5;
624
625    let width = usize::try_from(basis.feature_width)
626        .map_err(|_| CoreError::invalid("projected component basis", "width exceeds usize"))?;
627    let rank = usize::try_from(basis.rank)
628        .map_err(|_| CoreError::invalid("projected component basis", "rank exceeds usize"))?;
629    if values.len() != width.saturating_mul(rank) {
630        return Err(CoreError::invalid(
631            "projected component basis",
632            "byte count differs from width and rank",
633        ));
634    }
635    for left in 0..rank {
636        for right in left..rank {
637            let dot = values[left * width..(left + 1) * width]
638                .iter()
639                .zip(&values[right * width..(right + 1) * width])
640                .fold(0.0_f64, |sum, (left, right)| {
641                    sum + f64::from(*left) * f64::from(*right)
642                });
643            let expected = if left == right { 1.0 } else { 0.0 };
644            if !dot.is_finite() || (dot - expected).abs() > TOLERANCE {
645                return Err(CoreError::invalid(
646                    "projected component basis",
647                    "basis rows are not orthonormal",
648                ));
649            }
650        }
651    }
652    Ok(())
653}
654
655fn decode_f32(bytes: &[u8], field: &'static str) -> Result<Vec<f32>, CoreError> {
656    if bytes.is_empty() || !bytes.len().is_multiple_of(4) {
657        return Err(CoreError::invalid(
658            field,
659            "bytes must contain complete nonempty f32 elements",
660        ));
661    }
662    bytes
663        .chunks_exact(4)
664        .map(|chunk| {
665            let value =
666                f32::from_bits(u32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
667            value
668                .is_finite()
669                .then_some(value)
670                .ok_or_else(|| CoreError::invalid(field, "every value must be finite"))
671        })
672        .collect()
673}
674
675fn encode_f32(values: &[f32]) -> Vec<u8> {
676    values
677        .iter()
678        .flat_map(|value| value.to_bits().to_le_bytes())
679        .collect()
680}
681
682#[cfg(test)]
683mod tests {
684    use super::*;
685
686    fn f32_bytes(values: &[f32]) -> Vec<u8> {
687        encode_f32(values)
688    }
689
690    fn safetensors(first: &[f32], second: &[f32]) -> Vec<u8> {
691        let first_bytes = first.len() * 4;
692        let second_end = first_bytes + second.len() * 4;
693        let header = format!(
694            "{{\"__metadata__\":{{\"kept\":\"exact\"}},\"a\":{{\"dtype\":\"F32\",\"shape\":[2,2],\"data_offsets\":[0,{first_bytes}]}},\"b\":{{\"dtype\":\"F32\",\"shape\":[2,2],\"data_offsets\":[{first_bytes},{second_end}]}}}}"
695        );
696        let mut bytes = Vec::new();
697        bytes.extend_from_slice(&u64::try_from(header.len()).unwrap().to_le_bytes());
698        bytes.extend_from_slice(header.as_bytes());
699        bytes.extend_from_slice(&f32_bytes(first));
700        bytes.extend_from_slice(&f32_bytes(second));
701        bytes
702    }
703
704    fn plan(source: &[u8], basis: &[u8], strength: f32) -> ProjectedComponentPlanV1 {
705        ProjectedComponentPlanV1 {
706            topology: Digest::of_bytes("test-projection-topology", b"krea"),
707            source: projected_component_source_v1(source),
708            basis: ProjectedComponentBasisV1 {
709                feature_width: 2,
710                rank: 1,
711                data: projected_component_basis_v1(basis),
712            },
713            formula: ProjectedComponentFormulaV1::LeftProjection,
714            reduction: ProjectedComponentReductionV1::OrderedF64ToF32,
715            strength_bits: strength.to_bits(),
716            tensors: vec!["a".to_owned()],
717            implementation: projected_component_implementation_v1(),
718        }
719    }
720
721    #[test]
722    fn zero_strength_copies_every_byte_exactly() {
723        let source = safetensors(&[1.0, 2.0, 3.0, 4.0], &[5.0, 6.0, 7.0, 8.0]);
724        let basis = f32_bytes(&[1.0, 0.0]);
725        let plan = plan(&source, &basis, 0.0);
726        let output = project_safetensors_component_v1(&source, &basis, &plan).unwrap();
727        assert_eq!(output.bytes, source);
728        assert_eq!(
729            output.manifest.tensors[0].before,
730            output.manifest.tensors[0].after
731        );
732        verify_projected_component_v1(&source, &basis, &output.bytes, &plan, &output.manifest)
733            .unwrap();
734    }
735
736    #[test]
737    fn left_projection_changes_only_selected_tensor_payload() {
738        let source = safetensors(&[1.0, 2.0, 3.0, 4.0], &[5.0, 6.0, 7.0, 8.0]);
739        let basis = f32_bytes(&[1.0, 0.0]);
740        let plan = plan(&source, &basis, 1.0);
741        let output = project_safetensors_component_v1(&source, &basis, &plan).unwrap();
742        let parsed = ParsedSafeTensors::parse(&source).unwrap();
743        let a = &parsed.tensors["a"];
744        let b = &parsed.tensors["b"];
745        let a_start = parsed.data_start + a.start;
746        let a_end = parsed.data_start + a.end;
747        let b_start = parsed.data_start + b.start;
748        let b_end = parsed.data_start + b.end;
749        assert_eq!(
750            decode_f32(&output.bytes[a_start..a_end], "test").unwrap(),
751            vec![0.0, 0.0, 3.0, 4.0]
752        );
753        assert_eq!(&output.bytes[..a_start], &source[..a_start]);
754        assert_eq!(&output.bytes[b_start..b_end], &source[b_start..b_end]);
755    }
756
757    #[test]
758    fn malformed_alias_basis_and_orientation_fail_without_output() {
759        let source = safetensors(&[1.0, 2.0, 3.0, 4.0], &[5.0, 6.0, 7.0, 8.0]);
760        let non_orthogonal = f32_bytes(&[2.0, 0.0]);
761        let bad_basis_plan = plan(&source, &non_orthogonal, 1.0);
762        assert!(
763            project_safetensors_component_v1(&source, &non_orthogonal, &bad_basis_plan).is_err()
764        );
765
766        let basis = f32_bytes(&[1.0, 0.0]);
767        let mut wrong_axis = plan(&source, &basis, 1.0);
768        wrong_axis.basis.feature_width = 3;
769        assert!(project_safetensors_component_v1(&source, &basis, &wrong_axis).is_err());
770
771        let header = "{\"a\":{\"dtype\":\"F32\",\"shape\":[1,2],\"data_offsets\":[0,8]},\"b\":{\"dtype\":\"F32\",\"shape\":[1,2],\"data_offsets\":[4,12]}}";
772        let mut aliased = Vec::new();
773        aliased.extend_from_slice(&u64::try_from(header.len()).unwrap().to_le_bytes());
774        aliased.extend_from_slice(header.as_bytes());
775        aliased.extend_from_slice(&[0_u8; 12]);
776        let alias_plan = plan(&aliased, &basis, 1.0);
777        assert!(project_safetensors_component_v1(&aliased, &basis, &alias_plan).is_err());
778    }
779}