Skip to main content

tenferro_ad/
traced.rs

1//! Traced reverse- and forward-mode AD on the semantic program of a trace context.
2//!
3//! A differentiated output is snapshotted out of its
4//! [`TraceContext`](tenferro_runtime::TraceContext), the
5//! program-level transform runs on that snapshot, and the derivative program is
6//! imported back into the same context, so gradients compose with further traced
7//! operations and with higher-order transforms.
8
9use std::collections::HashSet;
10use std::sync::Arc;
11
12use tenferro_ops::input_key::TensorInputKey;
13use tenferro_ops::TensorMeta;
14use tenferro_runtime::ad_support::{ones_tensor, RetainedValue};
15use tenferro_runtime::program::{FrozenProgram, ProgramImport, ProgramValue};
16use tenferro_runtime::{
17    Error, ErrorPhase, ExecutionEngine, GraphCompiler, Result, Runtime, Tensor, TraceValue,
18    TracedTensor,
19};
20
21use crate::semantic_extension::{SemanticAdError, SemanticExtensionRuleSet};
22use crate::semantic_transform::{SemanticAdProgram, SemanticAdTransformError};
23use crate::transform_cache::AdTransformCache;
24use crate::AdContext;
25
26fn error_shape_hint(tensor: &TracedTensor) -> Vec<usize> {
27    tensor
28        .try_concrete_shape()
29        .unwrap_or_else(|| vec![0; tensor.rank()])
30}
31
32/// Typed error for the documented, user-reachable inactive-`wrt` state.
33///
34/// The `_optional` siblings expose this state as `Ok(None)`; the strict wrapper
35/// must not report a reachable input condition as an internal invariant.
36pub(crate) fn inactive_wrt_error(op: &'static str, wrt_key: impl std::fmt::Debug) -> Error {
37    Error::invalid_argument(
38        op,
39        ErrorPhase::GraphBuild,
40        "wrt",
41        format!(
42            "{op} is inactive for {wrt_key:?}; use {op}_optional to observe the inactive state"
43        ),
44    )
45}
46
47fn snapshot_error(source: tenferro_runtime::program::ProgramFinishError) -> Error {
48    Error::runtime_state_source("traced AD snapshot", ErrorPhase::GraphBuild, source)
49}
50
51fn import_error(source: tenferro_runtime::program::ProgramBuildError) -> Error {
52    Error::runtime_state_source("traced AD import", ErrorPhase::GraphBuild, source)
53}
54
55/// One differentiated output's snapshot plus its live input interface.
56struct AdSource {
57    frozen: FrozenProgram,
58    /// Context inputs in program input order.
59    inputs: Vec<(TensorInputKey, TraceValue)>,
60}
61
62impl AdSource {
63    fn of(output: &TracedTensor) -> Result<Self> {
64        let (frozen, inputs) = output
65            .context()
66            .ad_snapshot_with_inputs(&[output.trace_value()])
67            .map_err(snapshot_error)?;
68        Ok(Self { frozen, inputs })
69    }
70
71    /// Program input index of `wrt`, when `wrt` is an input of this program.
72    fn slot_of(&self, wrt: &TracedTensor) -> Result<Option<usize>> {
73        let Some(key) = wrt.input_key() else {
74            return Ok(None);
75        };
76        Ok(self
77            .inputs
78            .iter()
79            .position(|(candidate, _)| *candidate == key))
80    }
81
82    fn input_count(&self) -> usize {
83        self.inputs.len()
84    }
85}
86
87fn leaf_input_key(tensor: &TracedTensor) -> Result<TensorInputKey> {
88    tensor.input_key().ok_or_else(|| {
89        Error::invalid_argument(
90            "traced AD",
91            ErrorPhase::GraphBuild,
92            "wrt",
93            "the differentiated tensor is not a trace input",
94        )
95    })
96}
97
98fn seed_leaf(
99    output: &TracedTensor,
100    seeded_value: TraceValue,
101    data: &Arc<RetainedValue>,
102    op: &'static str,
103) -> Result<TraceValue> {
104    // A seed of an externally defined scalar must carry the same canonical scalar
105    // identity as the value it seeds, or the program cannot express it.
106    let identity = output.context().value_scalar_identity(seeded_value);
107    output
108        .context()
109        .bound_input_concrete(Arc::clone(data), identity)
110        .map_err(|source| {
111            Error::invalid_argument(
112                op,
113                ErrorPhase::GraphBuild,
114                "seed",
115                format!("a seed value could not be bound into the trace: {source}"),
116            )
117        })
118}
119
120/// Import derivative roots back into the output's context.
121///
122/// The derivative program's inputs are the source inputs followed by the seeds
123/// the transform introduced; the mapping reuses the live inputs so the imported
124/// operations continue on the same leaves.
125fn import_derivative(
126    output: &TracedTensor,
127    source: &AdSource,
128    derivative: &SemanticAdProgram,
129    seeds: &[(usize, TraceValue)],
130    derivative_output_indices: &[usize],
131    transform: &'static str,
132) -> Result<Vec<TracedTensor>> {
133    let frozen = derivative.frozen();
134    let derivative_inputs = frozen.program.inputs();
135    let source_input_count = source.input_count();
136    let mut input_map: Vec<(ProgramValue, ProgramValue)> =
137        Vec::with_capacity(source_input_count + seeds.len());
138    for (index, (_, live)) in source.inputs.iter().enumerate() {
139        let Some(&derivative_input) = derivative_inputs.get(index) else {
140            return Err(Error::runtime_state(
141                transform,
142                ErrorPhase::GraphBuild,
143                "the derivative program has fewer inputs than the source program",
144            ));
145        };
146        input_map.push((derivative_input, live.program_value()));
147    }
148    for (seed_input_index, seed) in seeds {
149        if *seed_input_index < source_input_count {
150            return Err(Error::runtime_state(
151                transform,
152                ErrorPhase::GraphBuild,
153                "a derivative seed input overlaps the source inputs",
154            ));
155        }
156        let Some(&derivative_input) = derivative_inputs.get(*seed_input_index) else {
157            return Err(Error::runtime_state(
158                transform,
159                ErrorPhase::GraphBuild,
160                "a derivative seed input is outside the derivative program",
161            ));
162        };
163        input_map.push((derivative_input, seed.program_value()));
164    }
165    let mut roots = Vec::with_capacity(derivative_output_indices.len());
166    for &index in derivative_output_indices {
167        let Some(&root) = frozen.program.outputs().get(index) else {
168            return Err(Error::runtime_state(
169                transform,
170                ErrorPhase::GraphBuild,
171                "a derivative output index is outside the derivative program",
172            ));
173        };
174        roots.push(root);
175    }
176    let imported = output
177        .context()
178        .import_values(ProgramImport {
179            program: frozen.program.as_ref(),
180            bindings: None,
181            roots: &roots,
182            input_map: &input_map,
183        })
184        .map_err(import_error)?;
185    imported
186        .into_iter()
187        .map(|value| {
188            output.context().derive_tensor(value).map_err(|source| {
189                Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source)
190            })
191        })
192        .collect()
193}
194
195/// Declared dtype and symbolic extents of a traced value.
196///
197/// Every non-constant extent names one of `tensor`'s own axes; an axis index is
198/// never reused as a tensor id.
199fn tensor_meta_of(tensor: &TracedTensor) -> Result<TensorMeta> {
200    let extents = match tensor.sym_shape() {
201        Some(shape) => shape.to_vec(),
202        None => (0..tensor.rank())
203            .map(|axis| tensor.axis_sym_dim(crate::shape_packing::signed_axis(axis)?))
204            .collect::<std::result::Result<_, _>>()?,
205    };
206    Ok(TensorMeta::exact(tensor.dtype(), extents))
207}
208
209/// Metadata a cotangent seed has to match.
210///
211/// The differentiated output's attached data wins over the program metadata: a
212/// symbolic output that carries data still knows the concrete cotangent shape.
213fn cotangent_meta_of(
214    output: &TracedTensor,
215    source: &AdSource,
216    transform: &'static str,
217) -> Result<TensorMeta> {
218    match output.attached_value() {
219        Some(data) => Ok(TensorMeta::exact(
220            data.dtype(),
221            data.shape()
222                .iter()
223                .map(|&size| tenferro_ops::SymDim::from(size))
224                .collect(),
225        )),
226        None => source_output_metadata(output, source, transform),
227    }
228}
229
230/// Metadata of the differentiated output, used to validate a cotangent seed.
231fn source_output_metadata(
232    output: &TracedTensor,
233    source: &AdSource,
234    transform: &'static str,
235) -> Result<TensorMeta> {
236    let Some(&program_output) = source.frozen.program.outputs().first() else {
237        return Err(Error::runtime_state(
238            transform,
239            ErrorPhase::GraphBuild,
240            "the AD source program has no output",
241        ));
242    };
243    let metadata = source
244        .frozen
245        .program
246        .value_metadata(program_output)
247        .map_err(|source| Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source))?;
248    program_metadata_to_tensor_meta(metadata, output, transform)
249}
250
251fn validate_seed_against_program(
252    transform: &'static str,
253    _source: &AdSource,
254    data: &Arc<RetainedValue>,
255    expected: TensorMeta,
256    input_index: usize,
257) -> Result<()> {
258    validate_seed_tensor(transform, input_index, data, &expected)
259}
260
261/// Metadata a seed has to match.
262///
263/// A symbolic value that carries attached data still knows the concrete shape its
264/// seed must have, so that shape wins over the symbolic extents.
265fn seed_meta_of(tensor: &TracedTensor) -> Result<TensorMeta> {
266    match tensor.attached_value() {
267        Some(data) => Ok(TensorMeta::exact(
268            data.dtype(),
269            data.shape()
270                .iter()
271                .map(|&size| tenferro_ops::SymDim::from(size))
272                .collect(),
273        )),
274        None => tensor_meta_of(tensor),
275    }
276}
277
278/// Seed metadata from the program metadata of `output`.
279///
280/// Program extents name program inputs by position, which is not a tensor id, so
281/// they are never turned into a `SymDim`: an extent that evaluates without inputs
282/// becomes a constant and every other axis names `output`'s own axis.
283fn program_metadata_to_tensor_meta(
284    metadata: &tenferro_runtime::program::ProgramValueMetadata,
285    output: &TracedTensor,
286    transform: &'static str,
287) -> Result<TensorMeta> {
288    let mut extents = Vec::with_capacity(metadata.shape().len());
289    for (axis, extent) in metadata.shape().iter().enumerate() {
290        let tenferro_ops::shape_extent::ShapeExtent::Exact(expr) = extent else {
291            return Err(Error::invalid_argument(
292                transform,
293                ErrorPhase::GraphBuild,
294                "seed",
295                "the differentiated value has no concrete dtype and rank metadata",
296            ));
297        };
298        extents.push(match expr.eval(&[]) {
299            Ok(size) => tenferro_ops::SymDim::from(size),
300            Err(_) => output.axis_sym_dim(crate::shape_packing::signed_axis(axis)?)?,
301        });
302    }
303    Ok(TensorMeta::exact(metadata.dtype(), extents))
304}
305
306fn ad_context(
307    rules: &SemanticExtensionRuleSet,
308    cache: Option<&Arc<AdTransformCache>>,
309) -> AdContext {
310    match cache {
311        Some(cache) => AdContext::with_rules_and_transform_cache(rules.clone(), Arc::clone(cache)),
312        None => AdContext::builder()
313            .with_semantic_extension_rules(rules.clone())
314            .expect("registering semantic extension rules is infallible")
315            .build()
316            .expect("building an AD context with a rule set is infallible"),
317    }
318}
319
320fn vjp_many_impl(
321    output: &TracedTensor,
322    wrts: &[&TracedTensor],
323    cotangent: &TracedTensor,
324    rules: &SemanticExtensionRuleSet,
325    cache: Option<&Arc<AdTransformCache>>,
326    transform: &'static str,
327) -> Result<Vec<Option<TracedTensor>>> {
328    if wrts.is_empty() {
329        return Ok(Vec::new());
330    }
331    let source = AdSource::of(output)?;
332    let slots: Vec<Option<usize>> = wrts
333        .iter()
334        .map(|wrt| source.slot_of(wrt))
335        .collect::<Result<_>>()?;
336    let mut active_inputs = vec![false; source.input_count()];
337    for slot in slots.iter().flatten().copied() {
338        active_inputs[slot] = true;
339    }
340    if !active_inputs.iter().any(|active| *active) {
341        return Ok(vec![None; wrts.len()]);
342    }
343    let cotangent_data = cotangent.attached_value().cloned().ok_or_else(|| {
344        Error::invalid_argument(
345            transform,
346            ErrorPhase::GraphBuild,
347            "cotangent",
348            format!("{transform} cotangent must have concrete tensor data"),
349        )
350    })?;
351    let seed = seed_leaf(output, output.trace_value(), &cotangent_data, transform)?;
352    let active_outputs = vec![true; source.frozen.program.outputs().len()];
353    let derivative = ad_context(rules, cache)
354        .vjp_program(&source.frozen, &active_inputs, &active_outputs)
355        .map_err(semantic_transform_error(transform))?;
356    let Some(seed_input_index) = derivative
357        .derivative_input_indices()
358        .first()
359        .copied()
360        .flatten()
361    else {
362        return Ok(vec![None; wrts.len()]);
363    };
364    validate_seed_against_program(
365        transform,
366        &source,
367        &cotangent_data,
368        cotangent_meta_of(output, &source, transform)?,
369        seed_input_index,
370    )?;
371    let mut requested = Vec::with_capacity(wrts.len());
372    let mut roots = Vec::new();
373    for (index, slot) in slots.iter().enumerate() {
374        let derivative_output = slot.and_then(|slot| {
375            derivative
376                .derivative_output_indices()
377                .get(slot)
378                .copied()
379                .flatten()
380        });
381        requested.push((index, derivative_output));
382        if let Some(derivative_output) = derivative_output
383            && !roots.contains(&derivative_output)
384        {
385            roots.push(derivative_output);
386        }
387    }
388    if roots.is_empty() {
389        return Ok(vec![None; wrts.len()]);
390    }
391    let imported = import_derivative(
392        output,
393        &source,
394        &derivative,
395        &[(seed_input_index, seed)],
396        &roots,
397        transform,
398    )?;
399    let mut results = vec![None; wrts.len()];
400    for (index, derivative_output) in requested {
401        if let Some(derivative_output) = derivative_output
402            && let Some(position) = roots.iter().position(|root| *root == derivative_output)
403        {
404            results[index] = imported.get(position).cloned();
405        }
406    }
407    Ok(results)
408}
409
410fn jvp_many_impl(
411    output: &TracedTensor,
412    wrt_tangents: &[(&TracedTensor, &TracedTensor)],
413    rules: &SemanticExtensionRuleSet,
414    cache: Option<&Arc<AdTransformCache>>,
415    transform: &'static str,
416) -> Result<Option<TracedTensor>> {
417    if wrt_tangents.is_empty() {
418        return Ok(None);
419    }
420    let source = AdSource::of(output)?;
421    let mut seen = HashSet::with_capacity(wrt_tangents.len());
422    let mut active_inputs = vec![false; source.input_count()];
423    let mut tangents = Vec::with_capacity(wrt_tangents.len());
424    for (wrt, tangent) in wrt_tangents {
425        let key = leaf_input_key(wrt)?;
426        if !seen.insert(key.clone()) {
427            return Err(Error::invalid_argument(
428                transform,
429                ErrorPhase::GraphBuild,
430                "wrt_tangents",
431                "wrt_tangents contains duplicate wrt leaves",
432            ));
433        }
434        let tangent_data = tangent.attached_value().cloned().ok_or_else(|| {
435            Error::invalid_argument(
436                transform,
437                ErrorPhase::GraphBuild,
438                "tangent",
439                format!("{transform} tangent must have concrete tensor data"),
440            )
441        })?;
442        tangents.push((wrt, tangent_data));
443    }
444    for (index, (wrt, _)) in tangents.iter().enumerate() {
445        let Some(slot) = source.slot_of(wrt)? else {
446            continue;
447        };
448        active_inputs[slot] = true;
449        let _ = index;
450    }
451    if !active_inputs.iter().any(|active| *active) {
452        return Ok(None);
453    }
454    let derivative = ad_context(rules, cache)
455        .jvp_program(&source.frozen, &active_inputs)
456        .map_err(semantic_transform_error(transform))?;
457    let Some(derivative_output_index) = derivative
458        .derivative_output_indices()
459        .first()
460        .copied()
461        .flatten()
462    else {
463        return Ok(None);
464    };
465    let mut seeds = Vec::with_capacity(tangents.len());
466    for (wrt, data) in tangents {
467        let Some(slot) = source.slot_of(wrt)? else {
468            continue;
469        };
470        let Some(seed_input_index) = derivative
471            .derivative_input_indices()
472            .get(slot)
473            .copied()
474            .flatten()
475        else {
476            continue;
477        };
478        validate_seed_against_program(
479            transform,
480            &source,
481            &data,
482            seed_meta_of(wrt)?,
483            seed_input_index,
484        )?;
485        let seed = seed_leaf(output, wrt.trace_value(), &data, transform)?;
486        seeds.push((seed_input_index, seed));
487    }
488    if seeds.is_empty() {
489        return Ok(None);
490    }
491    let mut imported = import_derivative(
492        output,
493        &source,
494        &derivative,
495        &seeds,
496        &[derivative_output_index],
497        transform,
498    )?;
499    Ok(imported.pop())
500}
501
502pub(crate) fn grad_with_rules_and_cache(
503    output: &TracedTensor,
504    wrt: &TracedTensor,
505    rules: &SemanticExtensionRuleSet,
506    cache: Option<&Arc<AdTransformCache>>,
507) -> Result<TracedTensor> {
508    let key = leaf_input_key(wrt)?;
509    grad_optional_with_rules_and_cache(output, wrt, rules, cache)
510        .and_then(|gradient| gradient.ok_or_else(|| inactive_wrt_error("grad", &key)))
511}
512
513pub(crate) fn grad_optional_with_rules_and_cache(
514    output: &TracedTensor,
515    wrt: &TracedTensor,
516    rules: &SemanticExtensionRuleSet,
517    cache: Option<&Arc<AdTransformCache>>,
518) -> Result<Option<TracedTensor>> {
519    if output.rank() != 0 {
520        return Err(Error::NonScalarGrad {
521            shape: error_shape_hint(output),
522        });
523    }
524    let ones = ones_tensor(output.dtype(), vec![])?;
525    let seed = output
526        .context()
527        .from_tensor_concrete_shape(ones)
528        .map_err(|source| Error::runtime_state_source("grad", ErrorPhase::GraphBuild, source))?;
529    vjp_many_impl(output, &[wrt], &seed, rules, cache, "grad")
530        .map(|mut results| results.pop().flatten())
531}
532
533pub(crate) fn jvp_with_rules_and_cache(
534    output: &TracedTensor,
535    wrt: &TracedTensor,
536    tangent: &TracedTensor,
537    rules: &SemanticExtensionRuleSet,
538    cache: Option<&Arc<AdTransformCache>>,
539) -> Result<TracedTensor> {
540    let key = leaf_input_key(wrt)?;
541    jvp_many_impl(output, &[(wrt, tangent)], rules, cache, "jvp")
542        .and_then(|result| result.ok_or_else(|| inactive_wrt_error("jvp", &key)))
543}
544
545pub(crate) fn jvp_optional_with_rules_and_cache(
546    output: &TracedTensor,
547    wrt: &TracedTensor,
548    tangent: &TracedTensor,
549    rules: &SemanticExtensionRuleSet,
550    cache: Option<&Arc<AdTransformCache>>,
551) -> Result<Option<TracedTensor>> {
552    jvp_many_impl(output, &[(wrt, tangent)], rules, cache, "jvp")
553}
554
555pub(crate) fn jvp_many_with_rules_and_cache(
556    output: &TracedTensor,
557    wrt_tangents: &[(&TracedTensor, &TracedTensor)],
558    rules: &SemanticExtensionRuleSet,
559    cache: Option<&Arc<AdTransformCache>>,
560) -> Result<Option<TracedTensor>> {
561    jvp_many_impl(output, wrt_tangents, rules, cache, "jvp")
562}
563
564pub(crate) fn vjp_with_rules_and_cache(
565    output: &TracedTensor,
566    wrt: &TracedTensor,
567    cotangent: &TracedTensor,
568    rules: &SemanticExtensionRuleSet,
569    cache: Option<&Arc<AdTransformCache>>,
570) -> Result<TracedTensor> {
571    let key = leaf_input_key(wrt)?;
572    vjp_optional_with_rules_and_cache(output, wrt, cotangent, rules, cache)
573        .and_then(|gradient| gradient.ok_or_else(|| inactive_wrt_error("vjp", &key)))
574}
575
576pub(crate) fn vjp_optional_with_rules_and_cache(
577    output: &TracedTensor,
578    wrt: &TracedTensor,
579    cotangent: &TracedTensor,
580    rules: &SemanticExtensionRuleSet,
581    cache: Option<&Arc<AdTransformCache>>,
582) -> Result<Option<TracedTensor>> {
583    vjp_many_impl(output, &[wrt], cotangent, rules, cache, "vjp")
584        .map(|mut results| results.pop().flatten())
585}
586
587pub(crate) fn vjp_many_with_rules_and_cache(
588    output: &TracedTensor,
589    wrts: &[&TracedTensor],
590    cotangent: &TracedTensor,
591    rules: &SemanticExtensionRuleSet,
592    cache: Option<&Arc<AdTransformCache>>,
593) -> Result<Vec<Option<TracedTensor>>> {
594    vjp_many_impl(output, wrts, cotangent, rules, cache, "vjp")
595}
596
597pub trait TracedTensorAdExt {
598    /// Gradient of a scalar output with respect to a traced input.
599    ///
600    /// For complex scalar outputs, tenferro returns the Hermitian-adjoint
601    /// cotangent. To compare seed-`1` scalar gradients with JAX's public
602    /// `grad` values, use the complex conjugate of this result. See
603    /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
604    ///
605    /// # Examples
606    ///
607    /// ```rust
608    /// use tenferro_ad::TracedTensorAdExt;
609    /// use tenferro_runtime::{TraceContext, GraphCompiler, Runtime, TracedTensor};
610    ///
611    /// fn eval(tensor: &TracedTensor) -> tenferro_runtime::Tensor {
612    ///     let mut compiler = GraphCompiler::new();
613    ///     let program = compiler.compile(tensor).unwrap();
614    ///     let mut engine = tenferro_cpu::CpuEngine::serial();
615    ///     let mut builder = Runtime::builder();
616    ///     builder
617    ///         .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
618    ///         .unwrap();
619    ///     let runtime = builder.build().unwrap();
620    ///     let target = tenferro_runtime::ExecutionEngine::target(&engine);
621    ///     let prepared = runtime.prepare(&program, &[], &[target]).unwrap();
622    ///     let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[]).unwrap();
623    ///     outputs.pop().unwrap().into_owned().unwrap()
624    /// }
625    ///
626    /// let trace = TraceContext::new();
627    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
628    /// let loss = (&x * &x).unwrap();
629    /// let dx = loss.grad(&x).unwrap();
630    ///
631    /// assert_eq!(eval(&dx).as_slice::<f64>().unwrap(), &[6.0]);
632    /// ```
633    ///
634    /// # Errors
635    ///
636    /// Returns [`tenferro_runtime::Error::NonScalarGrad`] for a non-scalar
637    /// output, [`tenferro_runtime::Error::UnsupportedAdRule`] when an AD rule
638    /// is unavailable, or a typed validation/backend/runtime-state error. An
639    /// inactive `wrt` returns [`Error::Validation`] with `argument: "wrt"`; use
640    /// [`grad_optional`](Self::grad_optional) to observe that state.
641    ///
642    /// # Deferred errors
643    ///
644    /// Symbolic shape constraints can later produce
645    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
646    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
647    /// or execution.
648    fn grad(&self, wrt: &TracedTensor) -> Result<TracedTensor>;
649
650    /// Like [`grad`](Self::grad), but returns `None` when `wrt` is inactive.
651    ///
652    /// # Examples
653    ///
654    /// ```rust
655    /// use tenferro_ad::TracedTensorAdExt;
656    /// use tenferro_runtime::{TraceContext, TracedTensor};
657    ///
658    /// let trace = TraceContext::new();
659    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
660    /// let y = trace.from_vec_col_major(vec![], vec![4.0_f64]).unwrap();
661    /// let loss = (&y * &y).unwrap();
662    ///
663    /// assert!(loss.grad_optional(&x).unwrap().is_none());
664    /// ```
665    ///
666    /// # Errors
667    ///
668    /// Returns [`tenferro_runtime::Error::NonScalarGrad`] for a non-scalar
669    /// output, [`Error::UnsupportedAdRule`] when an AD rule is unavailable, or
670    /// a typed validation/backend/runtime-state error.
671    ///
672    /// # Deferred errors
673    ///
674    /// Symbolic shape constraints can later produce
675    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
676    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
677    /// or execution.
678    fn grad_optional(&self, wrt: &TracedTensor) -> Result<Option<TracedTensor>>;
679
680    /// Evaluate this tensor and replace its graph with a concrete leaf while
681    /// preserving the previous graph for AD replay.
682    ///
683    /// # Examples
684    ///
685    /// ```rust
686    /// use tenferro_ad::TracedTensorAdExt;
687    /// use tenferro_runtime::{TraceContext, GraphCompiler, Runtime, TracedTensor};
688    ///
689    /// let mut compiler = GraphCompiler::new();
690    /// let backend = tenferro_cpu::CpuEngine::serial();
691    /// let mut builder = Runtime::builder();
692    /// builder
693    ///     .register_engine(tenferro_cpu::runtime_engine_registration(&backend).unwrap())
694    ///     .unwrap();
695    /// let runtime = builder.build().unwrap();
696    /// let trace = TraceContext::new();
697    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
698    /// let mut y = (&x * &x).unwrap();
699    ///
700    /// let mut engine = tenferro_cpu::CpuEngine::serial();
701    /// y.checkpoint(&mut compiler, &runtime, &mut engine).unwrap();
702    ///
703    /// let value = y.attached_value().unwrap();
704    /// let view = value
705    ///     .tensor_read()?
706    ///     .tensor_view()
707    ///     .ok_or("a checkpointed f64 value has a preset-scalar view")?;
708    /// let materialized = view.duplicate()?;
709    /// assert_eq!(materialized.as_slice::<f64>()?, &[9.0]);
710    /// # Ok::<(), Box<dyn std::error::Error>>(())
711    /// ```
712    ///
713    /// # Errors
714    ///
715    /// Returns [`tenferro_runtime::Error::Validation`] when checkpoint metadata
716    /// is invalid, [`Error::RuntimeState`] when graph metadata or runtime
717    /// state is unavailable, or a typed backend error from evaluation.
718    fn checkpoint(
719        &mut self,
720        compiler: &mut GraphCompiler,
721        runtime: &Runtime,
722        engine: &mut dyn ExecutionEngine,
723    ) -> Result<()>;
724
725    /// Forward-mode Jacobian-vector product.
726    ///
727    /// # Examples
728    ///
729    /// ```rust
730    /// use tenferro_ad::TracedTensorAdExt;
731    /// use tenferro_runtime::{TraceContext, GraphCompiler, Runtime, TracedTensor};
732    ///
733    /// fn eval(tensor: &TracedTensor) -> tenferro_runtime::Tensor {
734    ///     let mut compiler = GraphCompiler::new();
735    ///     let program = compiler.compile(tensor).unwrap();
736    ///     let mut engine = tenferro_cpu::CpuEngine::serial();
737    ///     let mut builder = Runtime::builder();
738    ///     builder
739    ///         .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
740    ///         .unwrap();
741    ///     let runtime = builder.build().unwrap();
742    ///     let target = tenferro_runtime::ExecutionEngine::target(&engine);
743    ///     let prepared = runtime.prepare(&program, &[], &[target]).unwrap();
744    ///     let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[]).unwrap();
745    ///     outputs.pop().unwrap().into_owned().unwrap()
746    /// }
747    ///
748    /// let trace = TraceContext::new();
749    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
750    /// let tangent = trace.from_vec_col_major(vec![], vec![2.0_f64]).unwrap();
751    /// let y = (&x * &x).unwrap();
752    /// let dy = y.jvp(&x, &tangent).unwrap();
753    ///
754    /// assert_eq!(eval(&dy).as_slice::<f64>().unwrap(), &[12.0]);
755    /// ```
756    ///
757    /// # Errors
758    ///
759    /// Returns [`tenferro_runtime::Error::UnsupportedAdRule`] when a JVP rule
760    /// is unavailable, [`Error::Validation`] for incompatible tangent metadata,
761    /// or a typed backend/runtime-state error. An inactive `wrt` returns
762    /// [`Error::Validation`] with `argument: "wrt"`; use
763    /// [`jvp_optional`](Self::jvp_optional) to observe that state.
764    ///
765    /// # Deferred errors
766    ///
767    /// Symbolic shape constraints can later produce
768    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
769    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
770    /// or execution.
771    fn jvp(&self, wrt: &TracedTensor, tangent: &TracedTensor) -> Result<TracedTensor>;
772
773    /// Like [`jvp`](Self::jvp), but returns `None` when `wrt` is inactive.
774    ///
775    /// # Examples
776    ///
777    /// ```rust
778    /// use tenferro_ad::TracedTensorAdExt;
779    /// use tenferro_runtime::{TraceContext, TracedTensor};
780    ///
781    /// let trace = TraceContext::new();
782    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
783    /// let y = trace.from_vec_col_major(vec![], vec![4.0_f64]).unwrap();
784    /// let tangent = trace.from_vec_col_major(vec![], vec![1.0_f64]).unwrap();
785    /// let loss = (&y * &y).unwrap();
786    ///
787    /// assert!(loss.jvp_optional(&x, &tangent).unwrap().is_none());
788    /// ```
789    ///
790    /// # Errors
791    ///
792    /// Returns [`tenferro_runtime::Error::UnsupportedAdRule`] when a JVP rule
793    /// is unavailable, [`Error::Validation`] for incompatible tangent metadata,
794    /// or a typed backend/runtime-state error.
795    ///
796    /// # Deferred errors
797    ///
798    /// Symbolic shape constraints can later produce
799    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
800    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
801    /// or execution.
802    fn jvp_optional(
803        &self,
804        wrt: &TracedTensor,
805        tangent: &TracedTensor,
806    ) -> Result<Option<TracedTensor>>;
807
808    /// Reverse-mode vector-Jacobian product.
809    ///
810    /// Complex cotangents use tenferro's Hermitian real-inner-product
811    /// convention. Non-real complex cotangent seeds therefore need an explicit
812    /// seed-convention comparison when matching JAX. See
813    /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
814    ///
815    /// # Examples
816    ///
817    /// ```rust
818    /// use tenferro_ad::TracedTensorAdExt;
819    /// use tenferro_runtime::{TraceContext, GraphCompiler, Runtime, TracedTensor};
820    ///
821    /// fn eval(tensor: &TracedTensor) -> tenferro_runtime::Tensor {
822    ///     let mut compiler = GraphCompiler::new();
823    ///     let program = compiler.compile(tensor).unwrap();
824    ///     let mut engine = tenferro_cpu::CpuEngine::serial();
825    ///     let mut builder = Runtime::builder();
826    ///     builder
827    ///         .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
828    ///         .unwrap();
829    ///     let runtime = builder.build().unwrap();
830    ///     let target = tenferro_runtime::ExecutionEngine::target(&engine);
831    ///     let prepared = runtime.prepare(&program, &[], &[target]).unwrap();
832    ///     let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[]).unwrap();
833    ///     outputs.pop().unwrap().into_owned().unwrap()
834    /// }
835    ///
836    /// let trace = TraceContext::new();
837    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
838    /// let cotangent = trace.from_vec_col_major(vec![], vec![0.5_f64]).unwrap();
839    /// let y = (&x * &x).unwrap();
840    /// let dx = y.vjp(&x, &cotangent).unwrap();
841    ///
842    /// assert_eq!(eval(&dx).as_slice::<f64>().unwrap(), &[3.0]);
843    /// ```
844    ///
845    /// # Errors
846    ///
847    /// Returns [`tenferro_runtime::Error::UnsupportedAdRule`] when a VJP rule
848    /// is unavailable, [`Error::Validation`] for incompatible cotangent
849    /// metadata, or a typed backend/runtime-state error. An inactive `wrt`
850    /// returns [`Error::Validation`] with `argument: "wrt"`; use
851    /// [`vjp_optional`](Self::vjp_optional) to observe that state.
852    ///
853    /// # Deferred errors
854    ///
855    /// Symbolic shape constraints can later produce
856    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
857    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
858    /// or execution.
859    fn vjp(&self, wrt: &TracedTensor, cotangent: &TracedTensor) -> Result<TracedTensor>;
860
861    /// Like [`vjp`](Self::vjp), but returns `None` when `wrt` is inactive.
862    ///
863    /// # Examples
864    ///
865    /// ```rust
866    /// use tenferro_ad::TracedTensorAdExt;
867    /// use tenferro_runtime::{TraceContext, TracedTensor};
868    ///
869    /// let trace = TraceContext::new();
870    /// let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
871    /// let y = trace.from_vec_col_major(vec![], vec![4.0_f64]).unwrap();
872    /// let cotangent = trace.from_vec_col_major(vec![], vec![1.0_f64]).unwrap();
873    /// let loss = (&y * &y).unwrap();
874    ///
875    /// assert!(loss.vjp_optional(&x, &cotangent).unwrap().is_none());
876    /// ```
877    ///
878    /// # Errors
879    ///
880    /// Returns [`tenferro_runtime::Error::UnsupportedAdRule`] when a VJP rule
881    /// is unavailable, [`Error::Validation`] for incompatible cotangent
882    /// metadata, or a typed backend/runtime-state error.
883    ///
884    /// # Deferred errors
885    ///
886    /// Symbolic shape constraints can later produce
887    /// [`tenferro_runtime::Error::ShapeConstraintViolation`] or
888    /// [`tenferro_runtime::Error::ShapeConstraintEvaluation`] during compile
889    /// or execution.
890    fn vjp_optional(
891        &self,
892        wrt: &TracedTensor,
893        cotangent: &TracedTensor,
894    ) -> Result<Option<TracedTensor>>;
895
896    /// Reverse-mode gradients for several leaves from one transform.
897    ///
898    /// One snapshot, one program-level transform and one import cover the whole
899    /// `wrt` set, so the backward is a single sweep instead of one per leaf.
900    ///
901    /// # Examples
902    ///
903    /// ```rust
904    /// use tenferro_ad::TracedTensorAdExt;
905    /// use tenferro_runtime::{TraceContext, DType};
906    ///
907    /// let trace = TraceContext::new();
908    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
909    /// let w = trace.from_vec_col_major(vec![2], vec![3.0_f64, 4.0])?;
910    /// let loss = (&(&x * &w)?).reduce_sum(None)?;
911    /// let grads = loss.grad_many(&[&x, &w])?;
912    /// assert_eq!(grads.len(), 2);
913    /// # Ok::<(), Box<dyn std::error::Error>>(())
914    /// ```
915    ///
916    /// # Errors
917    ///
918    /// Returns [`Error::NonScalarGrad`] for a non-scalar output,
919    /// [`Error::UnsupportedAdRule`] when a rule is unavailable, or a typed
920    /// validation/runtime-state error from the snapshot or the transform.
921    fn grad_many(&self, wrts: &[&TracedTensor]) -> Result<Vec<Option<TracedTensor>>>;
922
923    /// The scalar output together with reverse-mode gradients for several leaves.
924    ///
925    /// # Examples
926    ///
927    /// ```rust
928    /// use tenferro_ad::TracedTensorAdExt;
929    /// use tenferro_runtime::{TraceContext, DType};
930    ///
931    /// let trace = TraceContext::new();
932    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
933    /// let loss = (&(&x * &x)?).reduce_sum(None)?;
934    /// let (value, grads) = loss.value_and_grad(&[&x])?;
935    /// assert_eq!(value.rank(), 0);
936    /// assert!(grads[0].is_some());
937    /// # Ok::<(), Box<dyn std::error::Error>>(())
938    /// ```
939    ///
940    /// # Errors
941    ///
942    /// Returns [`Error::NonScalarGrad`] for a non-scalar output,
943    /// [`Error::UnsupportedAdRule`] when a rule is unavailable, or a typed
944    /// validation/runtime-state error from the snapshot or the transform; the
945    /// gradients follow [`grad_many`](Self::grad_many).
946    fn value_and_grad(
947        &self,
948        wrts: &[&TracedTensor],
949    ) -> Result<(TracedTensor, Vec<Option<TracedTensor>>)>;
950
951    /// Forward-mode JVPs for several leaves from one transform.
952    ///
953    /// # Examples
954    ///
955    /// ```rust
956    /// use tenferro_ad::TracedTensorAdExt;
957    /// use tenferro_runtime::{DType, TraceContext};
958    ///
959    /// let trace = TraceContext::new();
960    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
961    /// let dx = trace.from_vec_col_major(vec![2], vec![1.0_f64, 0.0])?;
962    /// let loss = (&(&x * &x)?).reduce_sum(None)?;
963    /// let tangent = loss.jvp_many(&[(&x, &dx)])?;
964    /// assert!(tangent.is_some());
965    /// # Ok::<(), Box<dyn std::error::Error>>(())
966    /// ```
967    ///
968    /// # Errors
969    ///
970    /// Returns [`Error::UnsupportedAdRule`] when a rule is unavailable, or a
971    /// typed validation/runtime-state error from the snapshot or the transform.
972    fn jvp_many(
973        &self,
974        wrt_tangents: &[(&TracedTensor, &TracedTensor)],
975    ) -> Result<Option<TracedTensor>>;
976
977    /// Reverse-mode VJPs for several leaves from one transform.
978    ///
979    /// # Examples
980    ///
981    /// ```rust
982    /// use tenferro_ad::TracedTensorAdExt;
983    /// use tenferro_runtime::{DType, TraceContext};
984    ///
985    /// let trace = TraceContext::new();
986    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
987    /// let loss = (&(&x * &x)?).reduce_sum(None)?;
988    /// let seed = trace.from_vec_col_major(vec![], vec![1.0_f64])?;
989    /// let grads = loss.vjp_many(&[&x], &seed)?;
990    /// assert!(grads[0].is_some());
991    /// # Ok::<(), Box<dyn std::error::Error>>(())
992    /// ```
993    ///
994    /// # Errors
995    ///
996    /// Returns [`Error::UnsupportedAdRule`] when a rule is unavailable, or a
997    /// typed validation/runtime-state error from the snapshot or the transform.
998    fn vjp_many(
999        &self,
1000        wrts: &[&TracedTensor],
1001        cotangent: &TracedTensor,
1002    ) -> Result<Vec<Option<TracedTensor>>>;
1003}
1004
1005impl TracedTensorAdExt for TracedTensor {
1006    fn grad(&self, wrt: &TracedTensor) -> Result<TracedTensor> {
1007        grad_with_rules_and_cache(self, wrt, &SemanticExtensionRuleSet::default(), None)
1008    }
1009
1010    fn grad_optional(&self, wrt: &TracedTensor) -> Result<Option<TracedTensor>> {
1011        grad_optional_with_rules_and_cache(self, wrt, &SemanticExtensionRuleSet::default(), None)
1012    }
1013
1014    fn checkpoint(
1015        &mut self,
1016        compiler: &mut GraphCompiler,
1017        runtime: &Runtime,
1018        engine: &mut dyn ExecutionEngine,
1019    ) -> Result<()> {
1020        let data = if let Some(data) = self.attached_value() {
1021            Arc::clone(data)
1022        } else {
1023            let program = compiler.compile(self)?;
1024            let target = engine.target();
1025            let prepared = runtime.prepare(&program, &[], std::slice::from_ref(&target))?;
1026            let outputs = crate::eager::run_prepared_on(runtime, engine, &prepared, &[])?;
1027            Arc::new(RetainedValue::from_tensor(single_runtime_output(
1028                outputs,
1029                "TracedTensorAdExt::checkpoint",
1030            )?))
1031        };
1032        let value = self
1033            .context()
1034            .checkpoint_value(self.trace_value(), Arc::clone(&data))
1035            .map_err(|source| {
1036                Error::runtime_state_source(
1037                    "TracedTensorAdExt::checkpoint",
1038                    ErrorPhase::GraphBuild,
1039                    source,
1040                )
1041            })?;
1042        self.rebind_bound(value, data)
1043    }
1044
1045    fn jvp(&self, wrt: &TracedTensor, tangent: &TracedTensor) -> Result<TracedTensor> {
1046        jvp_with_rules_and_cache(
1047            self,
1048            wrt,
1049            tangent,
1050            &SemanticExtensionRuleSet::default(),
1051            None,
1052        )
1053    }
1054
1055    fn jvp_optional(
1056        &self,
1057        wrt: &TracedTensor,
1058        tangent: &TracedTensor,
1059    ) -> Result<Option<TracedTensor>> {
1060        jvp_optional_with_rules_and_cache(
1061            self,
1062            wrt,
1063            tangent,
1064            &SemanticExtensionRuleSet::default(),
1065            None,
1066        )
1067    }
1068
1069    fn vjp(&self, wrt: &TracedTensor, cotangent: &TracedTensor) -> Result<TracedTensor> {
1070        vjp_with_rules_and_cache(
1071            self,
1072            wrt,
1073            cotangent,
1074            &SemanticExtensionRuleSet::default(),
1075            None,
1076        )
1077    }
1078
1079    fn vjp_optional(
1080        &self,
1081        wrt: &TracedTensor,
1082        cotangent: &TracedTensor,
1083    ) -> Result<Option<TracedTensor>> {
1084        vjp_optional_with_rules_and_cache(
1085            self,
1086            wrt,
1087            cotangent,
1088            &SemanticExtensionRuleSet::default(),
1089            None,
1090        )
1091    }
1092
1093    fn grad_many(&self, wrts: &[&TracedTensor]) -> Result<Vec<Option<TracedTensor>>> {
1094        if self.rank() != 0 {
1095            return Err(Error::NonScalarGrad {
1096                shape: error_shape_hint(self),
1097            });
1098        }
1099        let ones = ones_tensor(self.dtype(), vec![])?;
1100        let seed = self
1101            .context()
1102            .from_tensor_concrete_shape(ones)
1103            .map_err(|source| {
1104                Error::runtime_state_source("grad_many", ErrorPhase::GraphBuild, source)
1105            })?;
1106        vjp_many_impl(
1107            self,
1108            wrts,
1109            &seed,
1110            &SemanticExtensionRuleSet::default(),
1111            None,
1112            "grad_many",
1113        )
1114    }
1115
1116    fn value_and_grad(
1117        &self,
1118        wrts: &[&TracedTensor],
1119    ) -> Result<(TracedTensor, Vec<Option<TracedTensor>>)> {
1120        let gradients = self.grad_many(wrts)?;
1121        Ok((self.clone(), gradients))
1122    }
1123
1124    fn jvp_many(
1125        &self,
1126        wrt_tangents: &[(&TracedTensor, &TracedTensor)],
1127    ) -> Result<Option<TracedTensor>> {
1128        jvp_many_impl(
1129            self,
1130            wrt_tangents,
1131            &SemanticExtensionRuleSet::default(),
1132            None,
1133            "jvp_many",
1134        )
1135    }
1136
1137    fn vjp_many(
1138        &self,
1139        wrts: &[&TracedTensor],
1140        cotangent: &TracedTensor,
1141    ) -> Result<Vec<Option<TracedTensor>>> {
1142        vjp_many_with_rules_and_cache(
1143            self,
1144            wrts,
1145            cotangent,
1146            &SemanticExtensionRuleSet::default(),
1147            None,
1148        )
1149    }
1150}
1151
1152fn single_runtime_output(mut outputs: Vec<Tensor>, op: &'static str) -> Result<Tensor> {
1153    if outputs.len() != 1 {
1154        return Err(Error::Internal(format!(
1155            "{op}: expected exactly one execution output, got {}",
1156            outputs.len()
1157        )));
1158    }
1159    Ok(outputs.remove(0))
1160}
1161
1162fn semantic_transform_error(
1163    transform: &'static str,
1164) -> impl FnOnce(SemanticAdTransformError) -> Error {
1165    move |source| {
1166        semantic_transform_validation_error(transform, &source).unwrap_or_else(|| {
1167            Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source)
1168        })
1169    }
1170}
1171
1172fn semantic_transform_validation_error(
1173    transform: &'static str,
1174    source: &SemanticAdTransformError,
1175) -> Option<Error> {
1176    if let SemanticAdTransformError::Extension(
1177        SemanticAdError::Unsupported { family_id, .. }
1178        | SemanticAdError::MissingRule { family_id, .. },
1179    ) = source
1180    {
1181        return Some(Error::UnsupportedAdRule {
1182            transform,
1183            op: (*family_id).to_owned(),
1184        });
1185    }
1186
1187    let SemanticAdTransformError::Extension(SemanticAdError::Rule { source, .. }) = source else {
1188        return None;
1189    };
1190    let tenferro_ops::ad::ADRuleError::InvalidInput { op, message, .. } =
1191        source.downcast_ref::<tenferro_ops::ad::ADRuleError>()?
1192    else {
1193        return None;
1194    };
1195    Some(Error::invalid_argument(
1196        transform,
1197        ErrorPhase::GraphBuild,
1198        "semantic_ad_rule",
1199        format!("{op}: {message}"),
1200    ))
1201}
1202
1203fn validate_seed_tensor(
1204    transform: &'static str,
1205    input_index: usize,
1206    tensor: &RetainedValue,
1207    expected: &TensorMeta,
1208) -> Result<()> {
1209    let actual_dtype = tensor.dtype();
1210    if actual_dtype != expected.dtype {
1211        return Err(Error::invalid_argument(
1212            transform,
1213            ErrorPhase::GraphBuild,
1214            "seed",
1215            format!(
1216                "seed input {input_index} dtype mismatch: expected {:?}, got {:?}",
1217                expected.dtype, actual_dtype
1218            ),
1219        ));
1220    }
1221    let actual_shape = tensor.shape();
1222    if actual_shape.len() != expected.rank() {
1223        return Err(Error::invalid_argument(
1224            transform,
1225            ErrorPhase::GraphBuild,
1226            "seed",
1227            format!(
1228                "seed input {input_index} rank mismatch: expected {}, got {}",
1229                expected.rank(),
1230                actual_shape.len()
1231            ),
1232        ));
1233    }
1234    if let Some(expected_shape) = expected
1235        .exact_shape()
1236        .filter(|shape| shape.iter().all(|dim| dim.constant_value().is_some()))
1237        .map(|shape| {
1238            shape
1239                .into_iter()
1240                .map(|dim| dim.constant_value().expect("filtered constant shape"))
1241                .collect::<Vec<_>>()
1242        })
1243        && expected_shape != actual_shape
1244    {
1245        return Err(Error::invalid_argument(
1246            transform,
1247            ErrorPhase::GraphBuild,
1248            "seed",
1249            format!(
1250                "seed input {input_index} shape mismatch: expected {:?}, got {:?}",
1251                expected_shape, actual_shape
1252            ),
1253        ));
1254    }
1255    Ok(())
1256}
1257
1258#[cfg(test)]
1259mod semantic_transform_error_tests {
1260    use super::*;
1261    use crate::semantic_extension::SemanticAdRuleRole;
1262
1263    #[test]
1264    fn unsupported_semantic_rule_maps_to_public_transform_error() {
1265        let source = SemanticAdTransformError::Extension(SemanticAdError::Unsupported {
1266            family_id: "tenferro-tests.unsupported.v1",
1267            role: SemanticAdRuleRole::LinearTranspose,
1268            message: "unsupported test payload".into(),
1269        });
1270
1271        let error = semantic_transform_validation_error("vjp", &source)
1272            .expect("semantic rejection must map to a public unsupported-rule error");
1273
1274        assert!(matches!(
1275            error,
1276            Error::UnsupportedAdRule { transform: "vjp", ref op }
1277                if op == "tenferro-tests.unsupported.v1"
1278        ));
1279    }
1280
1281    #[test]
1282    fn missing_semantic_rule_maps_to_public_transform_error() {
1283        let source = SemanticAdTransformError::Extension(SemanticAdError::MissingRule {
1284            family_id: "tenferro-tests.missing.v1",
1285            role: SemanticAdRuleRole::Linearize,
1286        });
1287
1288        let error = semantic_transform_validation_error("jvp", &source)
1289            .expect("missing semantic rule must map to a public unsupported-rule error");
1290
1291        assert!(matches!(
1292            error,
1293            Error::UnsupportedAdRule { transform: "jvp", ref op }
1294                if op == "tenferro-tests.missing.v1"
1295        ));
1296    }
1297}