Skip to main content

tenferro_ad/
eager.rs

1use std::cell::{Cell, RefCell};
2use std::cmp::Reverse;
3use std::collections::HashMap;
4use std::env;
5use std::fmt;
6use std::marker::PhantomData;
7use std::mem::{size_of, size_of_val};
8use std::rc::Rc;
9#[cfg(test)]
10use std::sync::atomic::{AtomicUsize, Ordering};
11use std::sync::{Arc, Mutex, MutexGuard, OnceLock, Weak};
12use std::time::{Duration, Instant};
13
14use lru::LruCache;
15use num_complex::Complex64;
16
17use crate::extension::{
18    validate_eager_extension_target, EagerExtensionBackendKind, EagerExtensionTarget,
19};
20
21#[cfg(test)]
22use computegraph::graph::Graph;
23use computegraph::ValueKey;
24#[cfg(test)]
25use computegraph::ValueRef;
26use tenferro_ops::dim_expr::DimExpr;
27#[cfg(test)]
28use tenferro_ops::input_key::TensorInputKey;
29use tenferro_ops::{std_tensor_op::StdTensorOp, SymDim, TensorMeta};
30use tenferro_runtime::ad_support::{ones_tensor, RetainedValue};
31use tenferro_runtime::program::{ProgramValueMetadata, SemanticFingerprint, SemanticProgram};
32use tenferro_runtime::{
33    CompiledGraph, EngineId, EngineTarget, ErrorPhase, ExecutionContextIdentity, ExecutionEngine,
34    ExtensionModule, GraphCompiler, Prepared, Runtime, RuntimeConfigError, RuntimeEpoch,
35};
36use tenferro_tensor::Engine;
37#[cfg(test)]
38use tenferro_tensor::TypedTensor;
39use tenferro_tensor::{
40    AllocationGroup, CacheStats, CompareDir, DType, DescriptorSlot, DotGeneralConfig, GatherConfig,
41    GroupError, IntoShapeVec, PadConfig, ScatterConfig, SliceConfig, Tensor, TensorRead,
42    TensorScalar, TensorValue, TensorView,
43};
44
45use crate::eager_backend::{
46    cpu_host_owned_read, engine_kind_registration, unregisterable_engine_error,
47};
48#[cfg(test)]
49use crate::eager_exec::exec_standard_op_on_tensor_reads_in_session;
50use crate::eager_exec::{eager_input_promotion_plan, exec_extension_op_on_tensor_reads};
51use crate::error::{ContextId, Error, Result};
52use crate::semantic_extension::SemanticExtensionRuleSet;
53use crate::transform_cache::{AdTransformCache, AdTransformCacheLimits};
54use tenferro_runtime::ad_support::next_input_key;
55use tenferro_runtime::ad_support::tensor_meta_from_tensor;
56
57use crate::AdContext;
58
59pub(crate) type GradSlot = Arc<Mutex<Option<Arc<AdValueRecord>>>>;
60pub(crate) type WeakGradSlot = Weak<Mutex<Option<Arc<AdValueRecord>>>>;
61
62mod composite;
63mod residuals;
64mod semantic;
65pub(crate) use residuals::{finish_residuals, EagerTrace};
66use semantic::{replay, SemanticValue};
67
68#[derive(Debug, Default, Clone)]
69struct EagerOpProfileEntry {
70    calls: usize,
71    total_time: Duration,
72}
73
74thread_local! {
75    static EAGER_OP_PROFILE_STATE: RefCell<HashMap<&'static str, EagerOpProfileEntry>> =
76        RefCell::new(HashMap::new());
77    static EAGER_NO_GRAD_DEPTH: Cell<usize> = const { Cell::new(0) };
78    static EAGER_CAPTURE_DEPTH: Cell<usize> = const { Cell::new(0) };
79    #[cfg(test)]
80    static EAGER_OP_PROFILE_ENABLED_OVERRIDE: RefCell<Option<bool>> = const { RefCell::new(None) };
81    #[cfg(test)]
82    static EAGER_OP_PROFILE_PRINT_EVERY_OVERRIDE: RefCell<Option<Option<usize>>> = const { RefCell::new(None) };
83}
84
85#[cfg(test)]
86pub(crate) static EAGER_SEMANTIC_VJP_EXECUTIONS: AtomicUsize = AtomicUsize::new(0);
87
88pub(crate) fn eager_grad_recording_enabled() -> bool {
89    EAGER_NO_GRAD_DEPTH.with(|depth| depth.get() == 0)
90}
91
92pub(crate) fn eager_capture_active() -> bool {
93    EAGER_CAPTURE_DEPTH.with(|depth| depth.get() > 0)
94}
95
96/// Scope guard that temporarily disables eager operation recording.
97///
98/// Values computed while this guard is alive are concrete eager tensors, but
99/// they do not participate in reverse-mode gradient tracking.
100///
101/// # Examples
102///
103/// ```
104/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
105///
106/// let ctx = EagerRuntime::new()?;
107/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap())?;
108/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
109///     let _guard = ctx.no_grad();
110///     s.mul(&x, &x)
111/// })?;
112/// assert!(!y.tracks_grad());
113/// # Ok::<(), tenferro_ad::Error>(())
114/// ```
115#[derive(Debug)]
116pub struct EagerNoGradGuard {
117    active: bool,
118    // Thread-local depth guard: must not be Send so it cannot be moved to and
119    // dropped on another thread (which would corrupt the creator's depth).
120    _not_send: PhantomData<Rc<()>>,
121}
122
123impl Drop for EagerNoGradGuard {
124    fn drop(&mut self) {
125        if !self.active {
126            return;
127        }
128        EAGER_NO_GRAD_DEPTH.with(|depth| {
129            depth.set(depth.get().saturating_sub(1));
130        });
131        self.active = false;
132    }
133}
134
135/// Scope guard that keeps semantic recording active for untracked
136/// intermediates.
137///
138/// Under active-edge semantics (issue #1665 Def 1), an operation whose inputs
139/// are all untracked produces no autograd nodes and drops its semantic value.
140/// Inside this guard, such operations still record it, so a later functional
141/// JVP/VJP can differentiate with respect to an untracked or detached leaf.
142/// This replaces the pre-Def-1 implicit recording.
143///
144/// # Examples
145///
146/// ```
147/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
148///
149/// let ctx = EagerRuntime::new()?;
150/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
151/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
152///     let _capture = ctx.capture_trace();
153///     s.mul(&x, &x)
154/// })?;
155/// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0]).unwrap())?;
156/// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.vjp(&y, &x, &seed))?;
157/// assert_eq!(dx.value()?.as_slice::<f64>().unwrap(), &[2.0, 4.0]);
158/// # Ok::<(), tenferro_ad::Error>(())
159/// ```
160#[derive(Debug)]
161pub struct EagerTraceCaptureGuard {
162    active: bool,
163    // Thread-local depth guard: must not be Send so it cannot be moved to and
164    // dropped on another thread (which would corrupt the creator's depth).
165    _not_send: PhantomData<Rc<()>>,
166}
167
168impl Drop for EagerTraceCaptureGuard {
169    fn drop(&mut self) {
170        if !self.active {
171            return;
172        }
173        EAGER_CAPTURE_DEPTH.with(|depth| {
174            depth.set(depth.get().saturating_sub(1));
175        });
176        self.active = false;
177    }
178}
179
180pub(crate) fn eager_op_profile_enabled() -> bool {
181    #[cfg(test)]
182    if let Some(value) = EAGER_OP_PROFILE_ENABLED_OVERRIDE.with(|state| *state.borrow()) {
183        return value;
184    }
185
186    static ENABLED: OnceLock<bool> = OnceLock::new();
187    *ENABLED.get_or_init(|| env::var("TENFERRO_PROFILE_EAGER_OP_AGG").is_ok())
188}
189
190pub(crate) fn eager_op_profile_start() -> Option<Instant> {
191    eager_op_profile_enabled().then(Instant::now)
192}
193
194pub(crate) fn record_eager_op_profile(section: &'static str, elapsed: Duration) {
195    if !eager_op_profile_enabled() {
196        return;
197    }
198    EAGER_OP_PROFILE_STATE.with(|state| {
199        let mut state = state.borrow_mut();
200        let entry = state.entry(section).or_default();
201        entry.calls += 1;
202        entry.total_time += elapsed;
203    });
204}
205
206pub(crate) fn profile_eager_op_section<T>(section: &'static str, f: impl FnOnce() -> T) -> T {
207    if !eager_op_profile_enabled() {
208        return f();
209    }
210    let started = Instant::now();
211    let result = f();
212    record_eager_op_profile(section, started.elapsed());
213    result
214}
215
216pub(crate) fn maybe_print_eager_op_profile() {
217    if !eager_op_profile_enabled() {
218        return;
219    }
220    let Some(print_every) = eager_op_profile_print_every() else {
221        return;
222    };
223    if print_every == 0 {
224        return;
225    }
226
227    let should_print = EAGER_OP_PROFILE_STATE.with(|state| {
228        state
229            .borrow()
230            .get("nary_op.total")
231            .is_some_and(|entry| entry.calls % print_every == 0)
232    });
233    if should_print {
234        print_and_reset_eager_op_profile();
235    }
236}
237
238fn eager_op_profile_print_every() -> Option<usize> {
239    #[cfg(test)]
240    if let Some(value) = EAGER_OP_PROFILE_PRINT_EVERY_OVERRIDE.with(|state| *state.borrow()) {
241        return value;
242    }
243
244    env::var("TENFERRO_PROFILE_EAGER_OP_PRINT_EVERY")
245        .ok()?
246        .parse()
247        .ok()
248}
249
250pub(crate) fn print_and_reset_eager_op_profile() {
251    EAGER_OP_PROFILE_STATE.with(|state| {
252        let mut entries: Vec<_> = state
253            .borrow()
254            .iter()
255            .map(|(section, entry)| (*section, entry.clone()))
256            .collect();
257        state.borrow_mut().clear();
258        entries.sort_by_key(|(_, entry)| Reverse(entry.total_time));
259
260        eprintln!("=== tenferro eager op profile ===");
261        for (section, entry) in entries {
262            let Some(per_call_us) = eager_op_profile_per_call_us(&entry) else {
263                continue;
264            };
265            eprintln!(
266                "{section}: calls={} total={:.6}ms per_call={:.3}us",
267                entry.calls,
268                entry.total_time.as_secs_f64() * 1.0e3,
269                per_call_us,
270            );
271        }
272    });
273}
274
275fn eager_op_profile_per_call_us(entry: &EagerOpProfileEntry) -> Option<f64> {
276    (entry.calls != 0).then(|| entry.total_time.as_secs_f64() * 1.0e6 / entry.calls as f64)
277}
278
279fn runtime_config_error(op: &'static str, source: RuntimeConfigError) -> Error {
280    Error::runtime_state_source(op, ErrorPhase::Execution, source)
281}
282
283fn runtime_state_source<E>(op: &'static str, source: E) -> Error
284where
285    E: std::error::Error + Send + Sync + 'static,
286{
287    Error::runtime_state_source(op, ErrorPhase::Execution, source)
288}
289
290/// Run `prepared` on `engine` and return owned compact outputs.
291pub(crate) fn run_prepared_on(
292    runtime: &Runtime,
293    engine: &mut dyn ExecutionEngine,
294    prepared: &Prepared,
295    inputs: &[TensorRead<'_>],
296) -> Result<Vec<Tensor>> {
297    let outputs = runtime.run(&mut [&mut *engine], prepared, inputs)?;
298    outputs
299        .into_iter()
300        .map(|output| output.into_tensor(&mut *engine).map_err(Error::from))
301        .collect()
302}
303
304/// Run a session-capable prepared extension executor on `engine`, lending it
305/// the engine's extension caches for the call.
306pub(crate) fn execute_prepared_extension_on(
307    engine: &mut dyn ExecutionEngine,
308    executor: &dyn tenferro_runtime::PreparedOperationExecutor,
309    inputs: &[TensorRead<'_>],
310) -> Result<Vec<Tensor>> {
311    with_lent_extension_caches(engine, |engine, caches| {
312        executor.execute_in_session(engine, caches, inputs)
313    })
314}
315
316/// Lend `engine`'s extension caches to `callback` and restore them on every
317/// exit path, including unwind.
318///
319/// A callback panic also marks the engine broken before it is resumed: the
320/// caches may be half updated, so the engine must not accept more work.
321pub(crate) fn with_lent_extension_caches<R>(
322    engine: &mut dyn ExecutionEngine,
323    callback: impl FnOnce(&mut dyn ExecutionEngine, &mut tenferro_runtime::ExtensionCacheStore) -> R,
324) -> R {
325    let mut caches = engine.take_extension_caches();
326    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
327        callback(&mut *engine, &mut caches)
328    }));
329    engine.restore_extension_caches(caches);
330    match result {
331        Ok(value) => value,
332        Err(payload) => {
333            engine.mark_broken();
334            std::panic::resume_unwind(payload)
335        }
336    }
337}
338
339/// The eager extension backend kind of an engine target, or `None` for an
340/// engine type without eager extension support.
341pub(crate) fn eager_extension_backend_kind(
342    target: &EngineTarget,
343) -> Option<EagerExtensionBackendKind> {
344    if target.context_identity() == ExecutionContextIdentity::of::<tenferro_cpu::CpuEngine>() {
345        return Some(EagerExtensionBackendKind::Cpu);
346    }
347    #[cfg(feature = "cuda")]
348    if target.context_identity() == ExecutionContextIdentity::of::<tenferro_gpu::cuda::CudaEngine>()
349    {
350        return Some(EagerExtensionBackendKind::Cuda);
351    }
352    None
353}
354
355/// Stats for caches owned by an [`EagerRuntime`].
356///
357/// `retained_bytes` fields are logical payload estimates, not process RSS.
358#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
359pub struct EagerRuntimeCacheStats {
360    /// Eager AD transform memoization cache.
361    pub ad_transforms: CacheStats,
362    /// Prepared eager derivative program cache.
363    pub prepared_derivatives: CacheStats,
364}
365
366#[cfg(test)]
367pub(crate) struct EagerGraphExecution {
368    pub(crate) outputs: Vec<Tensor>,
369}
370
371/// A read-only value view retained by an eager tensor record.
372///
373/// The guard borrows the record's allocation group. It never owns a tensor and
374/// cannot be converted into a mutable view.
375///
376/// # Examples
377///
378/// ```
379/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
380///
381/// let ctx = EagerRuntime::new()?;
382/// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
383/// let view = value.value()?;
384/// assert_eq!(view.shape(), &[2]);
385/// # Ok::<(), tenferro_ad::Error>(())
386/// ```
387#[derive(Debug)]
388pub struct ValueGuard<'a> {
389    view: TensorView<'a>,
390}
391
392impl<'a> ValueGuard<'a> {
393    /// Return the scalar dtype of the retained value.
394    pub fn dtype(&self) -> DType {
395        self.view.dtype()
396    }
397
398    /// Return the logical shape of the retained value.
399    pub fn shape(&self) -> &[usize] {
400        self.view.shape()
401    }
402
403    /// Borrow the dtype-erased tensor view.
404    pub fn as_tensor_view(&self) -> &TensorView<'_> {
405        &self.view
406    }
407
408    /// Borrow compact host bytes through the tensor's explicit scalar type.
409    ///
410    /// Backend-resident values return the backend's typed host-access error;
411    /// this method does not download storage implicitly.
412    ///
413    /// # Errors
414    ///
415    /// Returns [`tenferro_tensor::ValidationError::DTypeMismatch`] when
416    /// `T` does not match the view dtype, [`tenferro_tensor::ValidationError::NonContiguousViewAsSlice`]
417    /// for a non-contiguous view, or [`tenferro_tensor::Error::HostAccess`]
418    /// when backend storage cannot be mapped as a host slice.
419    pub fn as_slice<T: TensorScalar>(&self) -> tenferro_tensor::Result<&'a [T]> {
420        self.view.as_slice()
421    }
422
423    fn duplicate_host_tensor(&self) -> tenferro_tensor::Result<Tensor> {
424        match &self.view {
425            TensorView::F32(view) => {
426                <f32 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
427            }
428            TensorView::F64(view) => {
429                <f64 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
430            }
431            TensorView::I32(view) => {
432                <i32 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
433            }
434            TensorView::I64(view) => {
435                <i64 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
436            }
437            TensorView::Bool(view) => <bool as TensorScalar>::into_tensor(
438                view.shape().to_vec(),
439                view.as_slice()?.to_vec(),
440            ),
441            TensorView::C32(view) => <num_complex::Complex32 as TensorScalar>::into_tensor(
442                view.shape().to_vec(),
443                view.as_slice()?.to_vec(),
444            ),
445            TensorView::C64(view) => <num_complex::Complex64 as TensorScalar>::into_tensor(
446                view.shape().to_vec(),
447                view.as_slice()?.to_vec(),
448            ),
449        }
450    }
451}
452
453/// Read-only retained gradient value.
454///
455/// # Examples
456///
457/// ```
458/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
459///
460/// let ctx = EagerRuntime::new()?;
461/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
462/// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
463///     let squared = s.mul(&x, &x)?;
464///     s.reduce_sum(&squared, Some(&[0]))
465/// })?;
466/// let _gradients = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
467/// let gradient = x.grad()?.expect("tracked leaf has a gradient");
468/// assert_eq!(gradient.shape(), &[2]);
469/// # Ok::<(), tenferro_ad::Error>(())
470/// ```
471#[derive(Clone, Debug)]
472pub struct GradientValue {
473    record: Arc<AdValueRecord>,
474}
475
476impl GradientValue {
477    /// Return the scalar dtype of the gradient.
478    pub fn dtype(&self) -> DType {
479        self.record.dtype()
480    }
481
482    /// Return the logical shape of the gradient.
483    pub fn shape(&self) -> &[usize] {
484        self.record.shape()
485    }
486
487    /// Borrow the gradient's value guard.
488    ///
489    /// # Errors
490    ///
491    /// Returns [`Error::RuntimeState`] when the retained gradient record is
492    /// unavailable or its allocation-group descriptor is invalid.
493    pub fn value(&self) -> Result<ValueGuard<'_>> {
494        self.record.value("GradientValue::value")
495    }
496
497    /// Borrow the gradient as a dtype-erased read target.
498    ///
499    /// # Errors
500    ///
501    /// Returns [`Error::RuntimeState`] when the retained gradient record or
502    /// its allocation-group descriptor is unavailable.
503    pub fn tensor_read(&self) -> Result<TensorRead<'_>> {
504        self.record.tensor_read("GradientValue::tensor_read")
505    }
506
507    /// Borrow a compact host slice without downloading backend storage.
508    ///
509    /// # Errors
510    ///
511    /// Returns [`Error::RuntimeState`] when the retained value is unavailable,
512    /// [`tenferro_tensor::ValidationError::DTypeMismatch`] when `T` does
513    /// not match the gradient dtype, or [`tenferro_tensor::Error::HostAccess`]
514    /// when backend storage cannot be mapped as a host slice.
515    pub fn as_slice<T: TensorScalar>(&self) -> tenferro_tensor::Result<&[T]> {
516        self.record
517            .value("GradientValue::as_slice")
518            .map_err(|error| {
519                tenferro_tensor::Error::runtime_state_source("GradientValue::as_slice", error)
520            })?
521            .as_slice()
522    }
523
524    /// Explicitly copy a host-resident gradient into a standalone tensor.
525    ///
526    /// # Errors
527    ///
528    /// Returns [`Error::RuntimeState`] when the retained value or execution
529    /// session is unavailable, or a typed backend/host-access error when the
530    /// gradient cannot be materialized as a contiguous tensor.
531    pub fn to_tensor(&self, engine: &mut dyn Engine) -> Result<Tensor> {
532        let value = self
533            .record
534            .value("GradientValue::to_tensor")
535            .map_err(|error| {
536                Error::runtime_state_source(
537                    "GradientValue::to_tensor",
538                    ErrorPhase::Execution,
539                    error,
540                )
541            })?;
542        match value.duplicate_host_tensor() {
543            Ok(tensor) => Ok(tensor),
544            Err(_) => {
545                let read = self.record.tensor_read("GradientValue::to_tensor")?;
546                engine.to_contiguous_read(read).map_err(Error::from)
547            }
548        }
549    }
550}
551
552/// Move-only accumulated gradient bundle backed by one allocation group.
553///
554/// # Examples
555///
556/// ```
557/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
558///
559/// let ctx = EagerRuntime::new()?;
560/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
561/// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
562///     let squared = s.mul(&x, &x)?;
563///     s.reduce_sum(&squared, Some(&[0]))
564/// })?;
565/// let gradients = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
566/// assert!(!gradients.is_empty());
567/// # Ok::<(), tenferro_ad::Error>(())
568/// ```
569#[derive(Debug)]
570pub struct Gradients {
571    group: AllocationGroup,
572    slots: HashMap<ValueKey<StdTensorOp>, DescriptorSlot>,
573}
574
575impl Gradients {
576    fn from_tensors(tensors: HashMap<ValueKey<StdTensorOp>, Tensor>) -> Result<Self> {
577        if tensors.is_empty() {
578            return Err(Error::runtime_state(
579                "backward",
580                ErrorPhase::Execution,
581                "no gradients were produced for reachable tracked leaves; use EagerSession::grad_optional or EagerSession::vjp_optional to observe inactive differentiation",
582            ));
583        }
584        let (keys, values): (Vec<_>, Vec<_>) = tensors.into_iter().unzip();
585        let (group, bindings) = AllocationGroup::from_tensors(values).map_err(|error| {
586            Error::runtime_state_source("Gradients::from_tensors", ErrorPhase::Execution, error)
587        })?;
588        let slots = keys.into_iter().zip(bindings).collect();
589        Ok(Self { group, slots })
590    }
591
592    /// Return the number of retained gradient descriptors.
593    pub fn len(&self) -> usize {
594        self.slots.len()
595    }
596
597    /// Return whether no gradient was produced.
598    pub fn is_empty(&self) -> bool {
599        self.slots.is_empty()
600    }
601
602    /// Borrow one gradient view by its local value key.
603    pub fn grad(&self, key: &ValueKey<StdTensorOp>) -> Option<TensorView<'_>> {
604        let slot = self.slots.get(key).copied()?;
605        let mut reads = self.group.read_views(std::slice::from_ref(&slot)).ok()?;
606        match reads.pop()? {
607            TensorRead::View(view) => Some(view),
608            TensorRead::Tensor(_) => None,
609        }
610    }
611
612    /// Consume one gradient owner while leaving the bundle unchanged on failure.
613    ///
614    /// # Errors
615    ///
616    /// Returns [`tenferro_tensor::Error::RuntimeState`] when the descriptor is
617    /// invalid or its allocation is aliased. A missing key is reported as
618    /// `Ok(None)`.
619    pub fn take_grad(
620        &mut self,
621        key: &ValueKey<StdTensorOp>,
622    ) -> tenferro_tensor::Result<Option<Tensor>> {
623        let Some(&slot) = self.slots.get(key) else {
624            return Ok(None);
625        };
626        let tensor = self.group.take_tensor(slot).map_err(|error| {
627            tenferro_tensor::Error::runtime_state_source("Gradients::take_grad", error)
628        })?;
629        self.slots.remove(key);
630        Ok(Some(tensor))
631    }
632}
633
634/// Error returned when a value cannot be consumed without changing its owner.
635///
636/// # Examples
637///
638/// ```
639/// use tenferro_ad::{EagerRuntime, EagerTensor, IntoValueError, Tensor};
640///
641/// let ctx = EagerRuntime::new()?;
642/// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
643/// let _shared = value.clone();
644/// assert!(matches!(
645///     value.into_value(),
646///     Err(IntoValueError::NotUnique(_))
647/// ));
648/// # Ok::<(), tenferro_ad::Error>(())
649/// ```
650#[derive(Debug)]
651pub enum IntoValueError<H> {
652    /// Another eager handle, tape record, or checkpoint retains the value.
653    NotUnique(H),
654    /// Group extraction failed after the handle was uniquely acquired.
655    Extract { value: H, error: GroupError },
656}
657
658impl<H> std::fmt::Display for IntoValueError<H> {
659    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
660        match self {
661            Self::NotUnique(_) => formatter.write_str("eager value is retained by another handle"),
662            Self::Extract { error, .. } => {
663                write!(formatter, "eager value extraction failed: {error}")
664            }
665        }
666    }
667}
668
669impl<H: std::fmt::Debug + Send + Sync + 'static> std::error::Error for IntoValueError<H> {}
670
671/// What one direct retention container holds.
672// The pooled variant owns an allocation group inline; boxing it would add an
673// allocation to every retained value on the hot path.
674#[allow(clippy::large_enum_variant)]
675#[derive(Debug)]
676enum RetentionContainer {
677    /// Pooled storage owned through an allocation group and one descriptor slot.
678    Pooled {
679        group: AllocationGroup,
680        slot: DescriptorSlot,
681    },
682    /// A caller-owned value the runtime retains without taking pool ownership.
683    ///
684    /// The value returns to its owner when the record drops, and the runtime never
685    /// substitutes it for pooled storage. A caller-owned payload has no typed
686    /// descriptor view, so only its read and consume paths are available.
687    CallerOwned {
688        /// Boxed because a tensor value is much larger than the pooled variant.
689        tensor: Box<Tensor>,
690    },
691    /// An untracked result held directly.
692    ///
693    /// No AD group, residual or gradient will share it, so it needs no
694    /// allocation group: the tensor's own storage returns to its pool when the
695    /// record drops, and a unique handle hands the tensor back unchanged.
696    Owned { tensor: Tensor },
697}
698
699/// Read-only descriptor record used by eager handles and the AD registries.
700#[derive(Debug)]
701pub(crate) struct AdValueRecord {
702    container: Arc<RetentionContainer>,
703    dtype: DType,
704    shape: Box<[usize]>,
705}
706
707impl AdValueRecord {
708    fn from_group(
709        group: AllocationGroup,
710        slot: DescriptorSlot,
711        dtype: DType,
712        shape: Vec<usize>,
713    ) -> Arc<Self> {
714        Arc::new(Self {
715            container: Arc::new(RetentionContainer::Pooled { group, slot }),
716            dtype,
717            shape: shape.into_boxed_slice(),
718        })
719    }
720
721    fn from_tensor(tensor: Tensor, op: &'static str) -> Result<Arc<Self>> {
722        let dtype = tensor.dtype();
723        let shape = tensor.shape().to_vec();
724        if matches!(dtype, DType::External(_)) {
725            // A caller-owned payload is retained directly: it owns no pooled
726            // storage, so there is no group to build and nothing to return to a
727            // pool when the record drops.
728            return Ok(Arc::new(Self {
729                container: Arc::new(RetentionContainer::CallerOwned {
730                    tensor: Box::new(tensor),
731                }),
732                dtype,
733                shape: shape.into_boxed_slice(),
734            }));
735        }
736        let (group, bindings) = AllocationGroup::from_tensors(vec![tensor])
737            .map_err(|error| Error::runtime_state_source(op, ErrorPhase::Execution, error))?;
738        let slot = bindings.first().copied().ok_or_else(|| {
739            Error::runtime_state(op, ErrorPhase::Execution, "empty allocation-group binding")
740        })?;
741        Ok(Self::from_group(group, slot, dtype, shape))
742    }
743
744    /// Retain an untracked result without building an allocation group.
745    fn from_untracked_tensor(tensor: Tensor, op: &'static str) -> Result<Arc<Self>> {
746        if matches!(tensor.dtype(), DType::External(_)) {
747            return Self::from_tensor(tensor, op);
748        }
749        let dtype = tensor.dtype();
750        let shape = tensor.shape().to_vec().into_boxed_slice();
751        Ok(Arc::new(Self {
752            container: Arc::new(RetentionContainer::Owned { tensor }),
753            dtype,
754            shape,
755        }))
756    }
757
758    fn tensor_read(&self, op: &'static str) -> Result<TensorRead<'_>> {
759        match self.container.as_ref() {
760            RetentionContainer::Pooled { group, slot } => group.read_view(*slot).map_err(|error| {
761                // One slot, so no `Vec` and no empty-result case: the single-slot
762                // accessor is the whole request (#2079).
763                Error::runtime_state_source(op, ErrorPhase::Execution, error)
764            }),
765            RetentionContainer::CallerOwned { tensor } => Ok(TensorRead::from_tensor(tensor)),
766            RetentionContainer::Owned { tensor } => Ok(TensorRead::from_tensor(tensor)),
767        }
768    }
769
770    fn value(&self, op: &'static str) -> Result<ValueGuard<'_>> {
771        if let RetentionContainer::Owned { tensor } = self.container.as_ref() {
772            // `from_untracked_tensor` routes a caller-owned payload away from
773            // `Owned`, so this has a preset view; a missing one is reported, not
774            // asserted.
775            let view = TensorRead::from_tensor(tensor)
776                .tensor_view()
777                .ok_or_else(|| {
778                    Error::runtime_state(
779                        op,
780                        ErrorPhase::Execution,
781                        "an owned caller-owned payload has no typed borrowed view",
782                    )
783                })?;
784            return Ok(ValueGuard { view });
785        }
786        match self.tensor_read(op)? {
787            TensorRead::View(view) => Ok(ValueGuard { view }),
788            // A caller-owned payload has no typed descriptor view, so a path that
789            // needs one fails explicitly instead of borrowing the payload as bytes.
790            TensorRead::Tensor(_) => Err(Error::runtime_state(
791                op,
792                ErrorPhase::Execution,
793                "allocation-group value did not produce a borrowed descriptor view",
794            )),
795        }
796    }
797
798    fn dtype(&self) -> DType {
799        self.dtype
800    }
801
802    fn shape(&self) -> &[usize] {
803        &self.shape
804    }
805}
806
807/// Shared eager execution context for tensors on a backend.
808///
809/// Reusing one context lets eager tensors share backend state, extension
810/// runtime caches, and gradient storage across a computation.
811///
812/// # Examples
813///
814/// ```
815/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
816///
817/// let ctx = EagerRuntime::new()?;
818/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
819/// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
820/// let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.add(&x, &y)).unwrap();
821///
822/// assert_eq!(z.value().unwrap().as_slice::<f64>().unwrap(), &[3.0]);
823/// # Ok::<(), tenferro_ad::Error>(())
824/// ```
825pub struct EagerRuntime {
826    id: ContextId,
827    /// Prepared-program runtime. Engine kinds are registered on first use;
828    /// the runtime never stores an engine.
829    runtime: Runtime,
830    /// Serializes runtime reconfiguration (engine-kind registration and
831    /// extension-module installation).
832    extension_install_lock: Mutex<()>,
833    semantic_extension_rules: SemanticExtensionRuleSet,
834    grad_slots: Mutex<HashMap<ValueKey<StdTensorOp>, WeakGradSlot>>,
835    value_records: Mutex<HashMap<ValueKey<StdTensorOp>, Weak<EagerTensorRecord>>>,
836    ad_transform_cache: Arc<AdTransformCache>,
837    /// S2: prepared derivative programs keyed by semantic structure, wrt input,
838    /// and concrete bound input metadata. Avoids re-running freeze+AD
839    /// transform+compile_frozen on warm structure hits.
840    prepared_derivative_cache: Mutex<PreparedDerivativeCache>,
841    /// Test-only count of semantic replays performed for this runtime.
842    #[cfg(test)]
843    semantic_replays: AtomicUsize,
844}
845
846/// An eager runtime and its borrowed backend session for one execution boundary.
847///
848/// Obtain this only through [`EagerRuntime::with_eager_session`]. It rejects
849/// tensors from another eager runtime even if both runtimes use the same backend
850/// type, and it cannot escape the boundary closure.
851///
852/// # Examples
853///
854/// ```rust
855/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
856///
857/// let ctx = EagerRuntime::new()?;
858/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
859/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.neg(&x))?;
860/// assert_eq!(y.value()?.as_slice::<f64>()?, &[-3.0]);
861/// # Ok::<(), tenferro_ad::Error>(())
862/// ```
863///
864/// The borrowed session cannot escape its execution boundary:
865///
866/// ```compile_fail
867/// use tenferro_ad::EagerRuntime;
868/// let ctx = EagerRuntime::new().unwrap();
869/// let escaped = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session).unwrap();
870/// let _ = escaped;
871/// ```
872pub struct EagerSession<'a> {
873    runtime: &'a Arc<EagerRuntime>,
874    engine: &'a mut dyn ExecutionEngine,
875}
876
877impl fmt::Debug for EagerSession<'_> {
878    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
879        f.debug_struct("EagerSession")
880            .field("runtime_id", &self.runtime.id())
881            .finish_non_exhaustive()
882    }
883}
884
885impl EagerSession<'_> {
886    /// Negate an eager tensor inside the caller's execution boundary.
887    ///
888    /// # Examples
889    ///
890    /// ```rust
891    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
892    ///
893    /// let ctx = EagerRuntime::new()?;
894    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
895    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.neg(&x))?;
896    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-4.0]);
897    /// # Ok::<(), tenferro_ad::Error>(())
898    /// ```
899    ///
900    /// # Errors
901    ///
902    /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
903    /// or a typed eager/backend error from the selected operation.
904    pub fn neg(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
905        self.run_unary(input, StdTensorOp::Neg)
906    }
907
908    /// Compute the elementwise exponential inside this eager session.
909    ///
910    /// # Examples
911    ///
912    /// ```rust
913    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
914    /// let ctx = EagerRuntime::new()?;
915    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
916    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.exp(&x))?;
917    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
918    /// # Ok::<(), tenferro_ad::Error>(())
919    /// ```
920    ///
921    /// # Errors
922    ///
923    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
924    /// unsupported/backend error for the input dtype.
925    pub fn exp(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
926        self.run_unary(input, StdTensorOp::Exp)
927    }
928
929    /// Compute the elementwise absolute value inside this eager session.
930    ///
931    /// # Examples
932    ///
933    /// ```rust
934    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
935    /// let ctx = EagerRuntime::new()?;
936    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![-2.0_f64])?)?;
937    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.abs(&x))?;
938    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
939    /// # Ok::<(), tenferro_ad::Error>(())
940    /// ```
941    ///
942    /// # Errors
943    ///
944    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
945    /// unsupported/backend error for the input dtype.
946    pub fn abs(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
947        self.run_unary(input, StdTensorOp::Abs)
948    }
949
950    /// Compute the elementwise conjugate inside this eager session.
951    ///
952    /// # Examples
953    ///
954    /// ```rust
955    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
956    /// let ctx = EagerRuntime::new()?;
957    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
958    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.conj(&x))?;
959    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
960    /// # Ok::<(), tenferro_ad::Error>(())
961    /// ```
962    ///
963    /// # Errors
964    ///
965    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
966    /// unsupported/backend error for the input dtype.
967    pub fn conj(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
968        self.run_unary(input, StdTensorOp::Conj)
969    }
970
971    /// Compute the elementwise sign on this borrowed session.
972    ///
973    /// # Examples
974    /// ```rust
975    /// use tenferro_ad::{EagerRuntime, Tensor};
976    /// let ctx = EagerRuntime::new()?;
977    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
978    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![-2.0_f64])?)?;
979    ///     s.sign(&x)
980    /// })?;
981    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0]);
982    /// # Ok::<(), tenferro_ad::Error>(())
983    /// ```
984    /// # Errors
985    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
986    pub fn sign(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
987        self.run_unary(input, StdTensorOp::Sign)
988    }
989
990    /// Compute the elementwise natural logarithm on this borrowed session.
991    ///
992    /// # Examples
993    /// ```rust
994    /// use tenferro_ad::{EagerRuntime, Tensor};
995    /// let ctx = EagerRuntime::new()?;
996    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
997    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
998    ///     s.log(&x)
999    /// })?;
1000    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1001    /// # Ok::<(), tenferro_ad::Error>(())
1002    /// ```
1003    /// # Errors
1004    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1005    pub fn log(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1006        self.run_unary(input, StdTensorOp::Log)
1007    }
1008
1009    /// Compute the elementwise square root on this borrowed session.
1010    ///
1011    /// # Examples
1012    /// ```rust
1013    /// use tenferro_ad::{EagerRuntime, Tensor};
1014    /// let ctx = EagerRuntime::new()?;
1015    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1016    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
1017    ///     s.sqrt(&x)
1018    /// })?;
1019    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
1020    /// # Ok::<(), tenferro_ad::Error>(())
1021    /// ```
1022    /// # Errors
1023    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1024    pub fn sqrt(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1025        self.run_unary(input, StdTensorOp::Sqrt)
1026    }
1027
1028    /// Compute the elementwise reciprocal square root on this borrowed session.
1029    ///
1030    /// # Examples
1031    /// ```rust
1032    /// use tenferro_ad::{EagerRuntime, Tensor};
1033    /// let ctx = EagerRuntime::new()?;
1034    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1035    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
1036    ///     s.rsqrt(&x)
1037    /// })?;
1038    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.5]);
1039    /// # Ok::<(), tenferro_ad::Error>(())
1040    /// ```
1041    /// # Errors
1042    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1043    pub fn rsqrt(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1044        self.run_unary(input, StdTensorOp::Rsqrt)
1045    }
1046
1047    /// Compute the elementwise sine on this borrowed session.
1048    ///
1049    /// # Examples
1050    /// ```rust
1051    /// use tenferro_ad::{EagerRuntime, Tensor};
1052    /// let ctx = EagerRuntime::new()?;
1053    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1054    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1055    ///     s.sin(&x)
1056    /// })?;
1057    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1058    /// # Ok::<(), tenferro_ad::Error>(())
1059    /// ```
1060    /// # Errors
1061    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1062    pub fn sin(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1063        self.run_unary(input, StdTensorOp::Sin)
1064    }
1065
1066    /// Compute the elementwise cosine on this borrowed session.
1067    ///
1068    /// # Examples
1069    /// ```rust
1070    /// use tenferro_ad::{EagerRuntime, Tensor};
1071    /// let ctx = EagerRuntime::new()?;
1072    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1073    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1074    ///     s.cos(&x)
1075    /// })?;
1076    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
1077    /// # Ok::<(), tenferro_ad::Error>(())
1078    /// ```
1079    /// # Errors
1080    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1081    pub fn cos(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1082        self.run_unary(input, StdTensorOp::Cos)
1083    }
1084
1085    /// Compute the elementwise hyperbolic tangent on this borrowed session.
1086    ///
1087    /// # Examples
1088    /// ```rust
1089    /// use tenferro_ad::{EagerRuntime, Tensor};
1090    /// let ctx = EagerRuntime::new()?;
1091    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1092    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1093    ///     s.tanh(&x)
1094    /// })?;
1095    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1096    /// # Ok::<(), tenferro_ad::Error>(())
1097    /// ```
1098    /// # Errors
1099    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1100    pub fn tanh(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1101        self.run_unary(input, StdTensorOp::Tanh)
1102    }
1103
1104    /// Compute `exp(x) - 1` elementwise on this borrowed session.
1105    ///
1106    /// # Examples
1107    /// ```rust
1108    /// use tenferro_ad::{EagerRuntime, Tensor};
1109    /// let ctx = EagerRuntime::new()?;
1110    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1111    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1112    ///     s.expm1(&x)
1113    /// })?;
1114    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1115    /// # Ok::<(), tenferro_ad::Error>(())
1116    /// ```
1117    /// # Errors
1118    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1119    pub fn expm1(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1120        self.run_unary(input, StdTensorOp::Expm1)
1121    }
1122
1123    /// Compute `log(1 + x)` elementwise on this borrowed session.
1124    ///
1125    /// # Examples
1126    /// ```rust
1127    /// use tenferro_ad::{EagerRuntime, Tensor};
1128    /// let ctx = EagerRuntime::new()?;
1129    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1130    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1131    ///     s.log1p(&x)
1132    /// })?;
1133    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1134    /// # Ok::<(), tenferro_ad::Error>(())
1135    /// ```
1136    /// # Errors
1137    /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1138    pub fn log1p(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1139        self.run_unary(input, StdTensorOp::Log1p)
1140    }
1141
1142    /// Compute the error function `erf(x)` elementwise on this borrowed session.
1143    ///
1144    /// Defined for real `F32`/`F64` tensors; `erf(+-0) = +-0`,
1145    /// `erf(+-inf) = +-1`, and `NaN` stays `NaN`. The derivative is
1146    /// `2/sqrt(pi) * exp(-x^2)`.
1147    ///
1148    /// # Examples
1149    /// ```rust
1150    /// use tenferro_ad::{EagerRuntime, Tensor};
1151    /// let ctx = EagerRuntime::new()?;
1152    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1153    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![0.0_f64, 1.0])?)?;
1154    ///     s.erf(&x)
1155    /// })?;
1156    /// let y = y.value()?;
1157    /// let y = y.as_slice::<f64>()?;
1158    /// assert_eq!(y[0], 0.0);
1159    /// assert!((y[1] - 0.842_700_792_949_714_9).abs() < 1.0e-15);
1160    /// # Ok::<(), tenferro_ad::Error>(())
1161    /// ```
1162    /// # Errors
1163    /// Returns a typed foreign-runtime error, a typed unsupported-dtype error
1164    /// for complex, integer, or `Bool` input, or a backend error.
1165    pub fn erf(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1166        self.run_unary(input, StdTensorOp::Erf)
1167    }
1168
1169    /// Convert a tensor under the checked dtype-promotion lattice.
1170    /// Use [`Self::cast`] for intentional lossy projection.
1171    ///
1172    /// # Examples
1173    ///
1174    /// ```rust
1175    /// use tenferro_ad::{DType, EagerRuntime, Tensor};
1176    /// let ctx = EagerRuntime::new()?;
1177    /// let converted = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1178    ///     let x = session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1179    ///     session.convert(&x, DType::C64)
1180    /// })?;
1181    /// assert_eq!(converted.dtype(), DType::C64);
1182    /// # Ok::<(), tenferro_ad::Error>(())
1183    /// ```
1184    ///
1185    /// # Errors
1186    ///
1187    /// Returns [`Error::ContextMismatch`] for a foreign runtime or a typed
1188    /// unsupported dtype conversion/backend error.
1189    pub fn convert(&mut self, input: &EagerTensor, to: DType) -> Result<EagerTensor> {
1190        self.ensure_runtime(input)?;
1191        tenferro_tensor::validate::validate_convert_dtype(
1192            "EagerTensor::convert",
1193            input.dtype(),
1194            to,
1195        )
1196        .map_err(Error::TensorRuntime)?;
1197        self.cast(input, to)
1198    }
1199
1200    /// Cast a tensor to a dtype, permitting explicitly lossy projections.
1201    ///
1202    /// # Examples
1203    ///
1204    /// ```rust
1205    /// use tenferro_ad::{DType, EagerRuntime, Tensor};
1206    /// let ctx = EagerRuntime::new()?;
1207    /// let casted = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1208    ///     let x = session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.8_f64])?)?;
1209    ///     session.cast(&x, DType::I32)
1210    /// })?;
1211    /// assert_eq!(casted.value()?.as_slice::<i32>()?, &[2]);
1212    /// # Ok::<(), tenferro_ad::Error>(())
1213    /// ```
1214    ///
1215    /// # Errors
1216    ///
1217    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1218    /// unsupported projection/backend error.
1219    pub fn cast(&mut self, input: &EagerTensor, to: DType) -> Result<EagerTensor> {
1220        self.run_unary(
1221            input,
1222            StdTensorOp::Convert {
1223                from: input.dtype(),
1224                to,
1225            },
1226        )
1227    }
1228
1229    /// Permute the axes of an eager tensor while preserving independent ownership.
1230    ///
1231    /// # Examples
1232    ///
1233    /// ```rust
1234    /// use tenferro_ad::{EagerRuntime, Tensor};
1235    /// let ctx = EagerRuntime::new()?;
1236    /// let copied = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1237    ///     let x = session.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1238    ///     let y = session.transpose(&x, &[1, 0])?;
1239    ///     session.duplicate_value(&y)
1240    /// })?;
1241    /// assert_eq!(copied.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
1242    /// # Ok::<(), tenferro_ad::Error>(())
1243    /// ```
1244    ///
1245    /// # Errors
1246    ///
1247    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1248    /// axis/backend error for an invalid permutation or copy.
1249    pub fn transpose(&mut self, input: &EagerTensor, perm: &[isize]) -> Result<EagerTensor> {
1250        self.ensure_runtime(input)?;
1251        let perm = &crate::shape_packing::normalize_existing_axes(
1252            "EagerSession::transpose",
1253            perm,
1254            input.shape().len(),
1255        )?[..];
1256        input.transpose_in_session(perm, &mut *self.engine)
1257    }
1258
1259    /// Reshape an eager tensor while retaining a separate result owner.
1260    ///
1261    /// # Examples
1262    ///
1263    /// ```rust
1264    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1265    /// let ctx = EagerRuntime::new()?;
1266    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1267    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.reshape(&x, [1, 2]))?;
1268    /// assert_eq!(y.shape(), &[1, 2]);
1269    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1270    /// # Ok::<(), tenferro_ad::Error>(())
1271    /// ```
1272    ///
1273    /// # Errors
1274    ///
1275    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1276    /// validation/backend error when the target shape is incompatible.
1277    pub fn reshape(
1278        &mut self,
1279        input: &EagerTensor,
1280        shape: impl IntoShapeVec,
1281    ) -> Result<EagerTensor> {
1282        self.ensure_runtime(input)?;
1283        input.reshape_in_session(&shape.into_shape_vec(), &mut *self.engine)
1284    }
1285
1286    /// Slice an eager tensor with explicit start, limit, and stride per axis.
1287    ///
1288    /// # Examples
1289    ///
1290    /// ```rust
1291    /// use tenferro_ad::{EagerRuntime, SliceConfig, Tensor};
1292    /// let ctx = EagerRuntime::new()?;
1293    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1294    ///     let x = session.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1295    ///     session.slice(&x, SliceConfig { starts: vec![1], limits: vec![3], strides: vec![1] })
1296    /// })?;
1297    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
1298    /// # Ok::<(), tenferro_ad::Error>(())
1299    /// ```
1300    ///
1301    /// # Errors
1302    ///
1303    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1304    /// axis/stride/backend error for an invalid slice or copy.
1305    pub fn slice(&mut self, input: &EagerTensor, config: SliceConfig) -> Result<EagerTensor> {
1306        self.ensure_runtime(input)?;
1307        input.slice_in_session(config, &mut *self.engine)
1308    }
1309
1310    /// Broadcast an eager tensor into a larger shape on this session.
1311    ///
1312    /// # Examples
1313    ///
1314    /// ```rust
1315    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1316    /// let ctx = EagerRuntime::new()?;
1317    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1318    /// let copy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1319    ///     let y = session.broadcast_in_dim(&x, &[2, 2], &[0])?;
1320    ///     session.duplicate_value(&y)
1321    /// })?;
1322    /// assert_eq!(copy.as_slice::<f64>()?, &[1.0, 2.0, 1.0, 2.0]);
1323    /// # Ok::<(), tenferro_ad::Error>(())
1324    /// ```
1325    ///
1326    /// # Errors
1327    ///
1328    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1329    /// validation/backend error for an invalid broadcast mapping.
1330    pub fn broadcast_in_dim(
1331        &mut self,
1332        input: &EagerTensor,
1333        shape: &[usize],
1334        dims: &[usize],
1335    ) -> Result<EagerTensor> {
1336        self.ensure_runtime(input)?;
1337        input.broadcast_in_dim_in_session(shape, dims, &mut *self.engine)
1338    }
1339
1340    /// Keep the lower triangle of a matrix on this borrowed session.
1341    ///
1342    /// # Examples
1343    /// ```rust
1344    /// use tenferro_ad::{EagerRuntime, Tensor};
1345    /// let ctx = EagerRuntime::new()?;
1346    /// let lower = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1347    ///     let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1348    ///     s.tril(&matrix, 0)
1349    /// })?;
1350    /// assert_eq!(lower.value()?.as_slice::<f64>()?, &[1.0, 2.0, 0.0, 4.0]);
1351    /// # Ok::<(), tenferro_ad::Error>(())
1352    /// ```
1353    /// # Errors
1354    /// Returns a typed foreign-runtime, rank, unsupported-dtype, or backend error.
1355    pub fn tril(&mut self, input: &EagerTensor, k: i64) -> Result<EagerTensor> {
1356        self.run_unary(input, StdTensorOp::Tril { k })
1357    }
1358
1359    /// Keep the upper triangle of a matrix on this borrowed session.
1360    ///
1361    /// # Examples
1362    /// ```rust
1363    /// use tenferro_ad::{EagerRuntime, Tensor};
1364    /// let ctx = EagerRuntime::new()?;
1365    /// let upper = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1366    ///     let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1367    ///     s.triu(&matrix, 0)
1368    /// })?;
1369    /// assert_eq!(upper.value()?.as_slice::<f64>()?, &[1.0, 0.0, 3.0, 4.0]);
1370    /// # Ok::<(), tenferro_ad::Error>(())
1371    /// ```
1372    /// # Errors
1373    /// Returns a typed foreign-runtime, rank, unsupported-dtype, or backend error.
1374    pub fn triu(&mut self, input: &EagerTensor, k: i64) -> Result<EagerTensor> {
1375        self.run_unary(input, StdTensorOp::Triu { k })
1376    }
1377
1378    /// Pad an eager tensor with zeros on this borrowed session.
1379    ///
1380    /// # Examples
1381    /// ```rust
1382    /// use tenferro_ad::{EagerRuntime, PadConfig, Tensor};
1383    /// let ctx = EagerRuntime::new()?;
1384    /// let padded = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1385    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1386    ///     s.pad(&x, PadConfig {
1387    ///         edge_padding_low: vec![1],
1388    ///         edge_padding_high: vec![1],
1389    ///         interior_padding: vec![1],
1390    ///     })
1391    /// })?;
1392    /// assert_eq!(padded.value()?.as_slice::<f64>()?, &[0.0, 1.0, 0.0, 2.0, 0.0]);
1393    /// # Ok::<(), tenferro_ad::Error>(())
1394    /// ```
1395    /// # Errors
1396    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
1397    /// runtime, a validation error with
1398    /// `ValidationError::InvalidArgument` for a padding configuration whose
1399    /// length or extents do not match the input rank, or
1400    /// [`Error::TensorRuntime`] for a typed backend failure.
1401    pub fn pad(&mut self, input: &EagerTensor, config: PadConfig) -> Result<EagerTensor> {
1402        self.run_unary(input, StdTensorOp::Pad(config))
1403    }
1404
1405    /// Reverse the elements along selected axes on this borrowed session.
1406    ///
1407    /// # Examples
1408    /// ```rust
1409    /// use tenferro_ad::{EagerRuntime, Tensor};
1410    /// let ctx = EagerRuntime::new()?;
1411    /// let reversed = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1412    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
1413    ///     s.reverse(&x, &[0])
1414    /// })?;
1415    /// assert_eq!(reversed.value()?.as_slice::<f64>()?, &[3.0, 2.0, 1.0]);
1416    /// # Ok::<(), tenferro_ad::Error>(())
1417    /// ```
1418    /// # Errors
1419    /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1420    pub fn reverse(&mut self, input: &EagerTensor, axes: &[isize]) -> Result<EagerTensor> {
1421        self.ensure_runtime(input)?;
1422        let axes = &crate::shape_packing::normalize_existing_axes(
1423            "EagerSession::reverse",
1424            axes,
1425            input.shape().len(),
1426        )?[..];
1427        crate::eager_ops::validate_eager_axes("EagerSession::reverse", input.shape().len(), axes)?;
1428        self.run_unary(
1429            input,
1430            StdTensorOp::Reverse {
1431                axes: axes.to_vec(),
1432            },
1433        )
1434    }
1435
1436    /// Slice an eager tensor using runtime start indices in this borrowed session.
1437    ///
1438    /// # Examples
1439    /// ```rust
1440    /// use tenferro_ad::{EagerRuntime, Tensor};
1441    /// let ctx = EagerRuntime::new()?;
1442    /// let selected = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1443    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1444    ///     let starts = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1_i64])?)?;
1445    ///     s.dynamic_slice(&x, &starts, &[2])
1446    /// })?;
1447    /// assert_eq!(selected.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
1448    /// # Ok::<(), tenferro_ad::Error>(())
1449    /// ```
1450    /// # Errors
1451    /// Returns a typed foreign-runtime, invalid-index or slice-shape, or backend error.
1452    pub fn dynamic_slice(
1453        &mut self,
1454        input: &EagerTensor,
1455        starts: &EagerTensor,
1456        sizes: &[usize],
1457    ) -> Result<EagerTensor> {
1458        self.ensure_runtime(input)?;
1459        self.ensure_runtime(starts)?;
1460        EagerTensor::nary_op_in_session(
1461            &[input, starts],
1462            StdTensorOp::DynamicSlice {
1463                slice_sizes: sizes.to_vec(),
1464            },
1465            &mut *self.engine,
1466        )
1467    }
1468
1469    /// Gather elements of an eager tensor in this borrowed session.
1470    ///
1471    /// # Examples
1472    /// ```rust
1473    /// use tenferro_ad::{EagerRuntime, GatherConfig, Tensor};
1474    /// let ctx = EagerRuntime::new()?;
1475    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1476    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![10.0_f64, 20.0, 30.0])?)?;
1477    ///     let indices = s.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![2_i64, 0])?)?;
1478    ///     s.gather(&x, &indices, GatherConfig {
1479    ///         offset_dims: vec![], collapsed_slice_dims: vec![0],
1480    ///         start_index_map: vec![0], index_vector_dim: 1,
1481    ///         slice_sizes: vec![1],
1482    ///     })
1483    /// })?;
1484    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[30.0, 10.0]);
1485    /// # Ok::<(), tenferro_ad::Error>(())
1486    /// ```
1487    /// # Errors
1488    /// Returns a typed foreign-runtime, invalid-index/configuration, or backend error.
1489    pub fn gather(
1490        &mut self,
1491        input: &EagerTensor,
1492        indices: &EagerTensor,
1493        config: GatherConfig,
1494    ) -> Result<EagerTensor> {
1495        self.ensure_runtime(input)?;
1496        self.ensure_runtime(indices)?;
1497        EagerTensor::nary_op_in_session(
1498            &[input, indices],
1499            StdTensorOp::Gather(config),
1500            &mut *self.engine,
1501        )
1502    }
1503
1504    /// Concatenate eager tensors along one axis in this borrowed session.
1505    ///
1506    /// # Examples
1507    /// ```rust
1508    /// use tenferro_ad::{EagerRuntime, Tensor};
1509    /// let ctx = EagerRuntime::new()?;
1510    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1511    ///     let a = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
1512    ///     let b = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1513    ///     s.concatenate(&[&a, &b], 0)
1514    /// })?;
1515    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1516    /// # Ok::<(), tenferro_ad::Error>(())
1517    /// ```
1518    /// # Errors
1519    /// Returns a typed empty-input, foreign-runtime, invalid-axis/shape, or backend error.
1520    pub fn concatenate(&mut self, inputs: &[&EagerTensor], axis: isize) -> Result<EagerTensor> {
1521        for input in inputs {
1522            self.ensure_runtime(input)?;
1523        }
1524        // An empty list is reported by the operation itself (as before #2552);
1525        // only a non-empty list has a rank to normalize the axis against.
1526        let axis = match inputs.first() {
1527            Some(first) => crate::shape_packing::normalize_existing_axis(
1528                "EagerSession::concatenate",
1529                axis,
1530                first.shape().len(),
1531            )?,
1532            None => 0,
1533        };
1534        EagerTensor::nary_op_in_session(
1535            inputs,
1536            StdTensorOp::Concatenate {
1537                axis,
1538                input_count: inputs.len(),
1539            },
1540            &mut *self.engine,
1541        )
1542    }
1543
1544    /// Scatter updates into an eager tensor within this borrowed session.
1545    ///
1546    /// # Examples
1547    /// ```rust
1548    /// use tenferro_ad::{EagerRuntime, ScatterConfig, Tensor};
1549    /// let ctx = EagerRuntime::new()?;
1550    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1551    ///     let input = s.constant_from(Tensor::from_vec_col_major(vec![4], vec![0.0_f64; 4])?)?;
1552    ///     let indices = s.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![1_i64, 3])?)?;
1553    ///     let updates = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![5.0_f64, 7.0])?)?;
1554    ///     s.scatter(&input, &indices, &updates, ScatterConfig {
1555    ///         update_window_dims: vec![],
1556    ///         inserted_window_dims: vec![0],
1557    ///         scatter_dims_to_operand_dims: vec![0],
1558    ///         index_vector_dim: 1,
1559    ///     })
1560    /// })?;
1561    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[0.0, 5.0, 0.0, 7.0]);
1562    /// # Ok::<(), tenferro_ad::Error>(())
1563    /// ```
1564    /// # Errors
1565    /// Returns a typed foreign-runtime, invalid-index/configuration, or backend error.
1566    pub fn scatter(
1567        &mut self,
1568        input: &EagerTensor,
1569        indices: &EagerTensor,
1570        updates: &EagerTensor,
1571        config: ScatterConfig,
1572    ) -> Result<EagerTensor> {
1573        self.ensure_runtime(input)?;
1574        self.ensure_runtime(indices)?;
1575        self.ensure_runtime(updates)?;
1576        EagerTensor::nary_op_in_session(
1577            &[input, indices, updates],
1578            StdTensorOp::Scatter(config),
1579            &mut *self.engine,
1580        )
1581    }
1582
1583    /// Extract a diagonal along two axes in this borrowed session.
1584    ///
1585    /// # Examples
1586    /// ```rust
1587    /// use tenferro_ad::{EagerRuntime, Tensor};
1588    /// let ctx = EagerRuntime::new()?;
1589    /// let diagonal = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1590    ///     let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1591    ///     s.extract_diag(&matrix, 0, 1)
1592    /// })?;
1593    /// assert_eq!(diagonal.value()?.as_slice::<f64>()?, &[1.0, 4.0]);
1594    /// # Ok::<(), tenferro_ad::Error>(())
1595    /// ```
1596    /// # Errors
1597    /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1598    pub fn extract_diag(
1599        &mut self,
1600        input: &EagerTensor,
1601        axis_a: isize,
1602        axis_b: isize,
1603    ) -> Result<EagerTensor> {
1604        self.ensure_runtime(input)?;
1605        let rank = input.shape().len();
1606        let axis_a = crate::shape_packing::normalize_existing_axis(
1607            "EagerSession::extract_diag",
1608            axis_a,
1609            rank,
1610        )?;
1611        let axis_b = crate::shape_packing::normalize_existing_axis(
1612            "EagerSession::extract_diag",
1613            axis_b,
1614            rank,
1615        )?;
1616        self.run_unary(input, StdTensorOp::ExtractDiag { axis_a, axis_b })
1617    }
1618
1619    /// Embed the input along a diagonal in this borrowed session.
1620    ///
1621    /// # Examples
1622    /// ```rust
1623    /// use tenferro_ad::{EagerRuntime, Tensor};
1624    /// let ctx = EagerRuntime::new()?;
1625    /// let matrix = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1626    ///     let diagonal = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1627    ///     s.embed_diag(&diagonal, 0, 1)
1628    /// })?;
1629    /// assert_eq!(matrix.value()?.as_slice::<f64>()?, &[1.0, 0.0, 0.0, 2.0]);
1630    /// # Ok::<(), tenferro_ad::Error>(())
1631    /// ```
1632    /// # Errors
1633    /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1634    pub fn embed_diag(
1635        &mut self,
1636        input: &EagerTensor,
1637        axis_a: isize,
1638        axis_b: isize,
1639    ) -> Result<EagerTensor> {
1640        self.ensure_runtime(input)?;
1641        let rank = input.shape().len();
1642        let axis_a = crate::shape_packing::normalize_existing_axis(
1643            "EagerSession::embed_diag",
1644            axis_a,
1645            rank,
1646        )?;
1647        let axis_b =
1648            crate::shape_packing::normalize_insert_axis("EagerSession::embed_diag", axis_b, rank)?;
1649        self.run_unary(input, StdTensorOp::EmbedDiag { axis_a, axis_b })
1650    }
1651
1652    /// Reduce an eager tensor over selected axes within this borrowed session.
1653    /// `None` reduces all axes, while `Some(&[])` retains the input shape.
1654    ///
1655    /// # Examples
1656    ///
1657    /// ```rust
1658    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1659    /// let ctx = EagerRuntime::new()?;
1660    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1661    /// let sum = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.reduce_sum(&x, None))?;
1662    /// assert_eq!(sum.value()?.as_slice::<f64>()?, &[3.0]);
1663    /// # Ok::<(), tenferro_ad::Error>(())
1664    /// ```
1665    ///
1666    /// # Errors
1667    ///
1668    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1669    /// validation/backend error for invalid axes or unsupported dtypes.
1670    pub fn reduce_sum(
1671        &mut self,
1672        input: &EagerTensor,
1673        axes: Option<&[isize]>,
1674    ) -> Result<EagerTensor> {
1675        self.ensure_runtime(input)?;
1676        let axes = axes
1677            .map(|axes| {
1678                crate::shape_packing::normalize_existing_axes(
1679                    "EagerTensor::reduce_sum",
1680                    axes,
1681                    input.shape().len(),
1682                )
1683            })
1684            .transpose()?;
1685        input.reduce_sum_in_session(axes.as_deref(), &mut *self.engine)
1686    }
1687
1688    /// Sum elementwise squares over the selected axes in this borrowed session.
1689    /// Only `f32` and `f64` are supported. `None` reduces every axis, like the
1690    /// rest of the reduction family; `Some(&[])` squares each value.
1691    ///
1692    /// # Examples
1693    /// ```rust
1694    /// use tenferro_ad::{EagerRuntime, Tensor};
1695    /// let ctx = EagerRuntime::new()?;
1696    /// let (sum, all) = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1697    ///     let input = s.constant_from(Tensor::from_vec_col_major([2], vec![3.0_f64, 4.0])?)?;
1698    ///     Ok::<_, tenferro_ad::Error>((
1699    ///         s.reduce_sum_squares(&input, Some(&[0]))?,
1700    ///         s.reduce_sum_squares(&input, None)?,
1701    ///     ))
1702    /// })?;
1703    /// assert_eq!(sum.value()?.as_slice::<f64>()?, &[25.0]);
1704    /// assert_eq!(all.value()?.as_slice::<f64>()?, &[25.0]);
1705    /// # Ok::<(), tenferro_ad::Error>(())
1706    /// ```
1707    /// # Errors
1708    /// Returns typed foreign-runtime, invalid-axis, unsupported-dtype, or backend errors.
1709    pub fn reduce_sum_squares(
1710        &mut self,
1711        input: &EagerTensor,
1712        axes: Option<&[isize]>,
1713    ) -> Result<EagerTensor> {
1714        self.ensure_runtime(input)?;
1715        let axes = match axes {
1716            Some(axes) => crate::shape_packing::normalize_existing_axes(
1717                "EagerSession::reduce_sum_squares",
1718                axes,
1719                input.shape().len(),
1720            )?,
1721            None => (0..input.shape().len()).collect(),
1722        };
1723        crate::eager_ops::validate_eager_axes(
1724            "EagerSession::reduce_sum_squares",
1725            input.shape().len(),
1726            &axes,
1727        )?;
1728        self.run_unary(input, StdTensorOp::ReduceSumSquares { axes })
1729    }
1730
1731    /// Reduce the product of selected axes in this borrowed session.
1732    /// `None` reduces every axis.
1733    ///
1734    /// # Examples
1735    /// ```rust
1736    /// use tenferro_ad::{EagerRuntime, Tensor};
1737    /// let ctx = EagerRuntime::new()?;
1738    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1739    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1740    ///     s.reduce_prod(&x, None)
1741    /// })?;
1742    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
1743    /// # Ok::<(), tenferro_ad::Error>(())
1744    /// ```
1745    /// # Errors
1746    /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1747    pub fn reduce_prod(
1748        &mut self,
1749        input: &EagerTensor,
1750        axes: Option<&[isize]>,
1751    ) -> Result<EagerTensor> {
1752        self.ensure_runtime(input)?;
1753        let axes = match axes {
1754            Some(axes) => crate::shape_packing::normalize_existing_axes(
1755                "EagerSession::reduce_prod",
1756                axes,
1757                input.shape().len(),
1758            )?,
1759            None => (0..input.shape().len()).collect(),
1760        };
1761        crate::eager_ops::validate_eager_axes(
1762            "EagerSession::reduce_prod",
1763            input.shape().len(),
1764            &axes,
1765        )?;
1766        self.run_unary(input, StdTensorOp::ReduceProd { axes })
1767    }
1768
1769    /// Reduce the maximum over selected axes in this borrowed session.
1770    /// `None` reduces every axis.
1771    ///
1772    /// # Examples
1773    /// ```rust
1774    /// use tenferro_ad::{EagerRuntime, Tensor};
1775    /// let ctx = EagerRuntime::new()?;
1776    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1777    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1778    ///     s.reduce_max(&x, None)
1779    /// })?;
1780    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[3.0]);
1781    /// # Ok::<(), tenferro_ad::Error>(())
1782    /// ```
1783    /// # Errors
1784    /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1785    pub fn reduce_max(
1786        &mut self,
1787        input: &EagerTensor,
1788        axes: Option<&[isize]>,
1789    ) -> Result<EagerTensor> {
1790        self.ensure_runtime(input)?;
1791        let axes = match axes {
1792            Some(axes) => crate::shape_packing::normalize_existing_axes(
1793                "EagerSession::reduce_max",
1794                axes,
1795                input.shape().len(),
1796            )?,
1797            None => (0..input.shape().len()).collect(),
1798        };
1799        crate::eager_ops::validate_eager_axes(
1800            "EagerSession::reduce_max",
1801            input.shape().len(),
1802            &axes,
1803        )?;
1804        self.run_unary(input, StdTensorOp::ReduceMax { axes })
1805    }
1806
1807    /// Reduce the minimum over selected axes in this borrowed session.
1808    /// `None` reduces every axis.
1809    ///
1810    /// # Examples
1811    /// ```rust
1812    /// use tenferro_ad::{EagerRuntime, Tensor};
1813    /// let ctx = EagerRuntime::new()?;
1814    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1815    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1816    ///     s.reduce_min(&x, None)
1817    /// })?;
1818    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
1819    /// # Ok::<(), tenferro_ad::Error>(())
1820    /// ```
1821    /// # Errors
1822    /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1823    pub fn reduce_min(
1824        &mut self,
1825        input: &EagerTensor,
1826        axes: Option<&[isize]>,
1827    ) -> Result<EagerTensor> {
1828        self.ensure_runtime(input)?;
1829        let axes = match axes {
1830            Some(axes) => crate::shape_packing::normalize_existing_axes(
1831                "EagerSession::reduce_min",
1832                axes,
1833                input.shape().len(),
1834            )?,
1835            None => (0..input.shape().len()).collect(),
1836        };
1837        crate::eager_ops::validate_eager_axes(
1838            "EagerSession::reduce_min",
1839            input.shape().len(),
1840            &axes,
1841        )?;
1842        self.run_unary(input, StdTensorOp::ReduceMin { axes })
1843    }
1844
1845    /// Duplicate an eager value into an independent tensor within the caller's
1846    /// borrowed session, preserving its dtype and placement.
1847    ///
1848    /// # Examples
1849    ///
1850    /// ```rust
1851    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1852    /// let ctx = EagerRuntime::new()?;
1853    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1854    /// let copy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.duplicate_value(&x))?;
1855    /// assert_eq!(copy.as_slice::<f64>()?, &[2.0]);
1856    /// # Ok::<(), tenferro_ad::Error>(())
1857    /// ```
1858    ///
1859    /// # Errors
1860    ///
1861    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1862    /// runtime/backend error when the retained value cannot be duplicated.
1863    pub fn duplicate_value(&mut self, input: &EagerTensor) -> Result<Tensor> {
1864        self.ensure_runtime(input)?;
1865        input.duplicate_value_in_session(&mut *self.engine)
1866    }
1867
1868    /// Import an untracked leaf within this borrowed session.
1869    ///
1870    /// `tensor` must already be usable by this runtime's backend: a host
1871    /// tensor on a CPU runtime, or a tensor already on the device of a CUDA
1872    /// or WebGPU runtime. No host/device transfer happens here. To import host
1873    /// data into a device runtime, use [`Self::constant_from_host`], which
1874    /// uploads first; on a CPU runtime the two are equivalent.
1875    ///
1876    /// # Examples
1877    ///
1878    /// ```rust
1879    /// use tenferro_ad::{EagerRuntime, Tensor};
1880    /// let ctx = EagerRuntime::new()?;
1881    /// let c = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1882    ///     session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)
1883    /// })?;
1884    /// assert_eq!(c.value()?.as_slice::<f64>()?, &[2.0]);
1885    /// # Ok::<(), tenferro_ad::Error>(())
1886    /// ```
1887    ///
1888    /// # Errors
1889    ///
1890    /// Returns [`Error::TensorRuntime`] for a typed backend failure when the value cannot be
1891    /// registered in the session, or [`Error::RuntimeState`] when the runtime's
1892    /// value registry is unavailable.
1893    pub fn constant_from(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1894        EagerTensor::new_leaf_in_session(Arc::clone(self.runtime), tensor, false, &mut *self.engine)
1895    }
1896
1897    /// Upload a host tensor and import it as an untracked leaf in this session.
1898    ///
1899    /// Unlike [`Self::constant_from`], this explicitly crosses the host/device
1900    /// boundary: the host `tensor` is uploaded to this runtime's backend
1901    /// (a host copy on a CPU runtime) and the uploaded value becomes the leaf.
1902    /// Use it whenever the source data lives on the host and the runtime may
1903    /// be a device runtime; use [`Self::constant_from`] for a tensor that is
1904    /// already resident on the backend.
1905    ///
1906    /// # Examples
1907    /// ```rust
1908    /// use tenferro_ad::{EagerRuntime, Tensor};
1909    /// let ctx = EagerRuntime::new()?;
1910    /// let c = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1911    ///     s.constant_from_host(Tensor::from_vec_col_major([1], vec![2.0_f64])?)
1912    /// })?;
1913    /// assert_eq!(c.value()?.as_slice::<f64>()?, &[2.0]);
1914    /// # Ok::<(), tenferro_ad::Error>(())
1915    /// ```
1916    /// # Errors
1917    /// Returns [`Error::TensorRuntime`] for a typed backend failure, including a host-tensor
1918    /// upload failure, or [`Error::RuntimeState`] when the runtime's value
1919    /// registry is unavailable.
1920    pub fn constant_from_host(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1921        let uploaded = self
1922            .engine
1923            .upload_host_tensor(TensorRead::from_tensor(&tensor))
1924            .map_err(Error::from)?;
1925        self.constant_from(uploaded)
1926    }
1927
1928    /// Import a trainable leaf within this borrowed session.
1929    ///
1930    /// # Examples
1931    ///
1932    /// ```rust
1933    /// use tenferro_ad::{EagerRuntime, Tensor};
1934    /// let ctx = EagerRuntime::new()?;
1935    /// let x = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1936    ///     session.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)
1937    /// })?;
1938    /// assert!(x.tracks_grad());
1939    /// # Ok::<(), tenferro_ad::Error>(())
1940    /// ```
1941    ///
1942    /// # Errors
1943    ///
1944    /// Returns [`Error::TensorRuntime`] for a typed backend failure when the value cannot be
1945    /// registered, or [`Error::RuntimeState`] when the runtime's value or
1946    /// gradient registry is unavailable.
1947    pub fn variable_from(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1948        EagerTensor::new_leaf_in_session(Arc::clone(self.runtime), tensor, true, &mut *self.engine)
1949    }
1950
1951    /// Detach an eager tensor from the reverse graph within this session.
1952    ///
1953    /// The result keeps the concrete value, belongs to the same runtime and
1954    /// contributes no gradients to the graph that produced `input`. To move a
1955    /// value into another eager runtime, duplicate it here with
1956    /// [`Self::duplicate_value`] and import the owned tensor in the target
1957    /// runtime's session with [`Self::constant_from`].
1958    ///
1959    /// # Examples
1960    ///
1961    /// ```rust
1962    /// use tenferro_ad::{EagerRuntime, Tensor};
1963    ///
1964    /// let ctx = EagerRuntime::new()?;
1965    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1966    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.detach(&x))?;
1967    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1968    /// assert!(!y.tracks_grad());
1969    /// # Ok::<(), tenferro_ad::Error>(())
1970    /// ```
1971    ///
1972    /// # Errors
1973    ///
1974    /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
1975    /// [`Error::TensorRuntime`] when the engine cannot materialize the
1976    /// retained value, or [`Error::RuntimeState`] when the value record or its
1977    /// allocation-group descriptor is unavailable.
1978    pub fn detach(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1979        self.ensure_runtime(input)?;
1980        input.detach_in_session(&mut *self.engine)
1981    }
1982
1983    /// Gradient of a scalar eager output with respect to an eager tensor.
1984    ///
1985    /// Functional eager gradients return ordinary eager tensors and do not
1986    /// write into `grad()` slots. The returned tensor keeps a trace when the
1987    /// derivative computation depends on tracked eager values, so it can be
1988    /// differentiated again (higher-order derivatives).
1989    ///
1990    /// # Examples
1991    ///
1992    /// ```rust
1993    /// use tenferro_ad::{EagerRuntime, Tensor};
1994    ///
1995    /// let ctx = EagerRuntime::new()?;
1996    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
1997    /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1998    ///     let loss = s.mul(&x, &x)?;
1999    ///     s.grad(&loss, &x)
2000    /// })?;
2001    /// assert_eq!(dx.value()?.as_slice::<f64>()?, &[6.0]);
2002    /// # Ok::<(), tenferro_ad::Error>(())
2003    /// ```
2004    ///
2005    /// # Errors
2006    ///
2007    /// Returns [`Error::ContextMismatch`] when `output` or `wrt` belongs to
2008    /// another runtime (checked before anything is materialized),
2009    /// [`Error::NonScalarGrad`] for a non-scalar output,
2010    /// [`Error::UnsupportedAdRule`] when an AD rule is unavailable, or a typed
2011    /// validation/backend error from eager execution. An inactive `wrt`
2012    /// returns [`Error::Validation`] with `argument: "wrt"`; use
2013    /// [`Self::grad_optional`] to observe that state.
2014    pub fn grad(&mut self, output: &EagerTensor, wrt: &EagerTensor) -> Result<EagerTensor> {
2015        self.grad_optional(output, wrt)?
2016            .ok_or_else(|| crate::traced::inactive_wrt_error("grad", &wrt.key))
2017    }
2018
2019    /// Gradient that returns `None` when `wrt` is inactive.
2020    ///
2021    /// # Examples
2022    ///
2023    /// ```rust
2024    /// use tenferro_ad::{EagerRuntime, Tensor};
2025    ///
2026    /// let ctx = EagerRuntime::new()?;
2027    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2028    /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2029    /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2030    ///     let loss = s.mul(&y, &y)?;
2031    ///     s.grad_optional(&loss, &x)
2032    /// })?;
2033    /// assert!(dx.is_none());
2034    /// # Ok::<(), tenferro_ad::Error>(())
2035    /// ```
2036    ///
2037    /// # Errors
2038    ///
2039    /// Returns [`Error::ContextMismatch`] when `output` or `wrt` belongs to
2040    /// another runtime (checked before the seed is built),
2041    /// [`Error::NonScalarGrad`] for a non-scalar output, or a typed
2042    /// validation/backend/runtime-state error from eager execution.
2043    pub fn grad_optional(
2044        &mut self,
2045        output: &EagerTensor,
2046        wrt: &EagerTensor,
2047    ) -> Result<Option<EagerTensor>> {
2048        self.ensure_runtime(output)?;
2049        self.ensure_runtime(wrt)?;
2050        let seed = self.unit_seed(output)?;
2051        let seed =
2052            EagerTensor::new_result(Arc::clone(self.runtime), eager_val_key(), seed, false, None)?;
2053        self.vjp_optional(output, wrt, &seed)
2054    }
2055
2056    /// Reverse-mode vector-Jacobian product for eager tensors.
2057    ///
2058    /// # Examples
2059    ///
2060    /// ```rust
2061    /// use tenferro_ad::{EagerRuntime, Tensor};
2062    ///
2063    /// let ctx = EagerRuntime::new()?;
2064    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
2065    /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0])?)?;
2066    /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2067    ///     let y = s.mul(&x, &x)?;
2068    ///     s.vjp(&y, &x, &seed)
2069    /// })?;
2070    /// assert_eq!(dx.value()?.as_slice::<f64>()?, &[4.0, 6.0]);
2071    /// # Ok::<(), tenferro_ad::Error>(())
2072    /// ```
2073    ///
2074    /// # Errors
2075    ///
2076    /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `cotangent`
2077    /// belongs to another runtime, [`Error::Validation`] when the cotangent
2078    /// shape or dtype does not match the output, [`Error::UnsupportedAdRule`]
2079    /// when a rule is not registered, or a typed backend/runtime-state error.
2080    /// An inactive `wrt` returns [`Error::Validation`] with `argument: "wrt"`;
2081    /// use [`Self::vjp_optional`] to observe that state.
2082    pub fn vjp(
2083        &mut self,
2084        output: &EagerTensor,
2085        wrt: &EagerTensor,
2086        cotangent: &EagerTensor,
2087    ) -> Result<EagerTensor> {
2088        self.vjp_optional(output, wrt, cotangent)?
2089            .ok_or_else(|| crate::traced::inactive_wrt_error("vjp", &wrt.key))
2090    }
2091
2092    /// Reverse-mode vector-Jacobian product that returns `None` for inactive inputs.
2093    ///
2094    /// `None` means the input is disconnected, its eager computation was not
2095    /// recorded, or the semantic derivative has no cotangent flow (for example,
2096    /// real `sign` or an integer conversion). A present numerical zero is still
2097    /// returned as `Some`. Missing rules and execution failures return errors;
2098    /// semantic differentiation cannot be disabled by an environment variable.
2099    ///
2100    /// # Examples
2101    ///
2102    /// ```rust
2103    /// use tenferro_ad::{EagerRuntime, Tensor};
2104    ///
2105    /// let ctx = EagerRuntime::new()?;
2106    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2107    /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
2108    /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2109    /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2110    ///     let loss = s.mul(&y, &y)?;
2111    ///     s.vjp_optional(&loss, &x, &seed)
2112    /// })?;
2113    /// assert!(dx.is_none());
2114    /// # Ok::<(), tenferro_ad::Error>(())
2115    /// ```
2116    ///
2117    /// # Errors
2118    ///
2119    /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `cotangent`
2120    /// belongs to another runtime, [`Error::Validation`] when the cotangent
2121    /// shape or dtype does not match the output, [`Error::UnsupportedAdRule`]
2122    /// when a rule is not registered, or a typed backend/runtime-state error.
2123    pub fn vjp_optional(
2124        &mut self,
2125        output: &EagerTensor,
2126        wrt: &EagerTensor,
2127        cotangent: &EagerTensor,
2128    ) -> Result<Option<EagerTensor>> {
2129        self.ensure_runtime(output)?;
2130        self.ensure_runtime(wrt)?;
2131        self.ensure_runtime(cotangent)?;
2132        validate_seed_tensor("vjp", output, cotangent)?;
2133        Ok(
2134            semantic_eager_vjp_many(self.runtime, &mut *self.engine, output, &[wrt], cotangent)?
2135                .pop()
2136                .flatten(),
2137        )
2138    }
2139
2140    /// Forward-mode Jacobian-vector product for eager tensors.
2141    ///
2142    /// # Examples
2143    ///
2144    /// ```rust
2145    /// use tenferro_ad::{EagerRuntime, Tensor};
2146    ///
2147    /// let ctx = EagerRuntime::new()?;
2148    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2149    /// let tangent = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2150    /// let dy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2151    ///     let y = s.mul(&x, &x)?;
2152    ///     s.jvp(&y, &x, &tangent)
2153    /// })?;
2154    /// assert_eq!(dy.value()?.as_slice::<f64>()?, &[6.0]);
2155    /// # Ok::<(), tenferro_ad::Error>(())
2156    /// ```
2157    ///
2158    /// # Errors
2159    ///
2160    /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `tangent`
2161    /// belongs to another runtime, [`Error::Validation`] when the tangent
2162    /// shape or dtype does not match `wrt`, [`Error::UnsupportedAdRule`] when
2163    /// a rule is unavailable, or a typed backend/runtime-state error. An
2164    /// inactive `wrt` returns [`Error::Validation`] with `argument: "wrt"`;
2165    /// use [`Self::jvp_optional`] to observe that state.
2166    pub fn jvp(
2167        &mut self,
2168        output: &EagerTensor,
2169        wrt: &EagerTensor,
2170        tangent: &EagerTensor,
2171    ) -> Result<EagerTensor> {
2172        self.jvp_optional(output, wrt, tangent)?
2173            .ok_or_else(|| crate::traced::inactive_wrt_error("jvp", &wrt.key))
2174    }
2175
2176    /// Forward-mode Jacobian-vector product that returns `None` for inactive outputs.
2177    ///
2178    /// `None` means `wrt` is disconnected, its eager computation was not
2179    /// recorded, or the semantic derivative has no tangent flow (for example,
2180    /// real `sign` or an integer conversion). A present numerical zero is still
2181    /// returned as `Some`. Missing rules and execution failures return errors;
2182    /// semantic differentiation cannot be disabled by an environment variable.
2183    ///
2184    /// # Examples
2185    ///
2186    /// ```rust
2187    /// use tenferro_ad::{EagerRuntime, Tensor};
2188    ///
2189    /// let ctx = EagerRuntime::new()?;
2190    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2191    /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
2192    /// let tangent = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2193    /// let dy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2194    ///     let loss = s.mul(&y, &y)?;
2195    ///     s.jvp_optional(&loss, &x, &tangent)
2196    /// })?;
2197    /// assert!(dy.is_none());
2198    /// # Ok::<(), tenferro_ad::Error>(())
2199    /// ```
2200    ///
2201    /// # Errors
2202    ///
2203    /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `tangent`
2204    /// belongs to another runtime, [`Error::Validation`] when the tangent
2205    /// shape or dtype does not match `wrt`, [`Error::UnsupportedAdRule`] when
2206    /// a rule is unavailable, or a typed backend/runtime-state error.
2207    pub fn jvp_optional(
2208        &mut self,
2209        output: &EagerTensor,
2210        wrt: &EagerTensor,
2211        tangent: &EagerTensor,
2212    ) -> Result<Option<EagerTensor>> {
2213        self.ensure_runtime(output)?;
2214        self.ensure_runtime(wrt)?;
2215        self.ensure_runtime(tangent)?;
2216        validate_seed_tensor("jvp", wrt, tangent)?;
2217        semantic_eager_jvp_optional(self.runtime, &mut *self.engine, output, wrt, tangent)
2218    }
2219
2220    /// Run reverse-mode AD from a scalar eager output.
2221    ///
2222    /// Returns the full cotangent map produced by the reverse pass and also
2223    /// accumulates into `grad()` for tracked eager leaves reachable from
2224    /// `output`; repeated calls add to the stored gradients until they are
2225    /// cleared. A pass with no gradients is an error, not an empty successful
2226    /// bundle. If a reachable leaf has no cotangent flow, the pass fails before
2227    /// accumulating any gradients; use [`Self::vjp_optional`] to observe absent
2228    /// flow explicitly.
2229    ///
2230    /// For complex scalar outputs, cotangents use tenferro's Hermitian
2231    /// real-inner-product convention. See
2232    /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
2233    ///
2234    /// # Examples
2235    ///
2236    /// ```rust
2237    /// use tenferro_ad::{EagerRuntime, Tensor};
2238    ///
2239    /// let ctx = EagerRuntime::new()?;
2240    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
2241    /// for _ in 0..2 {
2242    ///     ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2243    ///         let doubled = s.add(&x, &x)?;
2244    ///         let loss = s.reduce_sum(&doubled, Some(&[0]))?;
2245    ///         s.backward(&loss)
2246    ///     })?;
2247    /// }
2248    /// assert_eq!(x.grad()?.expect("tracked leaf").as_slice::<f64>()?, &[4.0, 4.0, 4.0]);
2249    /// # Ok::<(), Box<dyn std::error::Error>>(())
2250    /// ```
2251    ///
2252    /// # Errors
2253    ///
2254    /// Returns [`Error::ContextMismatch`] when `output` belongs to another
2255    /// runtime (checked before any gradient slot is written),
2256    /// [`Error::NonScalarGrad`] when `output` is not scalar,
2257    /// [`Error::Validation`] when a reachable tracked leaf has no cotangent,
2258    /// [`Error::RuntimeState`] when no tracked leaf produces a gradient,
2259    /// [`Error::UnsupportedAdRule`] when a graph operation lacks a reverse
2260    /// rule, or a typed validation/backend/runtime-state error during the
2261    /// reverse pass.
2262    pub fn backward(&mut self, output: &EagerTensor) -> Result<Gradients> {
2263        self.ensure_runtime(output)?;
2264        let seed = self.unit_seed(output)?;
2265        output.backward_from_seed(&mut *self.engine, seed)
2266    }
2267
2268    /// Run reverse-mode AD from an eager output with an explicit cotangent seed.
2269    ///
2270    /// The seed is an operand, not an options value: this is the registry's
2271    /// documented seeded form of [`Self::backward`]. Like `backward`, it
2272    /// rejects absent cotangents for reachable tracked leaves before
2273    /// accumulation, accumulates into the reachable leaves' `grad()` slots and
2274    /// never returns an empty successful bundle. Use [`Self::vjp`] when the
2275    /// VJP result should be a composable eager tensor that touches no
2276    /// gradient slot.
2277    ///
2278    /// # Examples
2279    ///
2280    /// ```rust
2281    /// use tenferro_ad::{EagerRuntime, Tensor};
2282    ///
2283    /// let ctx = EagerRuntime::new()?;
2284    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
2285    /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2286    /// ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2287    ///     let y = s.mul(&x, &x)?;
2288    ///     s.backward_with(&y, &seed)
2289    /// })?;
2290    /// assert_eq!(x.grad()?.expect("tracked leaf").as_slice::<f64>()?, &[4.0, 12.0]);
2291    /// # Ok::<(), Box<dyn std::error::Error>>(())
2292    /// ```
2293    ///
2294    /// # Errors
2295    ///
2296    /// Returns [`Error::ContextMismatch`] when `output` or `cotangent` belongs
2297    /// to another runtime (checked before the seed is materialized or any
2298    /// gradient slot is written), [`Error::Validation`] when the seed's shape
2299    /// or dtype does not match `output` or a reachable tracked leaf has no
2300    /// cotangent, [`Error::RuntimeState`] when no tracked leaf produces a
2301    /// gradient, [`Error::UnsupportedAdRule`] for an unavailable reverse rule,
2302    /// or a typed backend/runtime-state error during execution.
2303    pub fn backward_with(
2304        &mut self,
2305        output: &EagerTensor,
2306        cotangent: &EagerTensor,
2307    ) -> Result<Gradients> {
2308        self.ensure_runtime(output)?;
2309        self.ensure_runtime(cotangent)?;
2310        validate_seed_tensor("backward", output, cotangent)?;
2311        let seed = cotangent.duplicate_value_in_session(&mut *self.engine)?;
2312        output.backward_from_seed(&mut *self.engine, seed)
2313    }
2314
2315    /// The all-ones seed of a scalar output, after the runtime checks.
2316    fn unit_seed(&mut self, output: &EagerTensor) -> Result<Tensor> {
2317        if !output.shape().is_empty() {
2318            return Err(Error::NonScalarGrad {
2319                shape: output.shape().to_vec(),
2320            });
2321        }
2322        let value = output.duplicate_value_in_session(&mut *self.engine)?;
2323        one_like_tensor(&value, &mut *self.engine)
2324    }
2325
2326    /// Add eager tensors with the same broadcast and AD rules as the eager
2327    /// operation surface, reusing this borrowed execution session.
2328    ///
2329    /// # Examples
2330    ///
2331    /// ```rust
2332    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2333    /// let ctx = EagerRuntime::new()?;
2334    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2335    /// let scalar = ctx.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2336    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.add(&x, &scalar))?;
2337    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[4.0, 5.0]);
2338    /// # Ok::<(), tenferro_ad::Error>(())
2339    /// ```
2340    ///
2341    /// # Errors
2342    ///
2343    /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
2344    /// or a typed broadcast/backend error for the operands.
2345    pub fn add(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2346        self.run_binary("add", lhs, rhs, StdTensorOp::Add)
2347    }
2348
2349    /// Subtract eager tensors within this borrowed session.
2350    ///
2351    /// # Examples
2352    ///
2353    /// ```rust
2354    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2355    /// let ctx = EagerRuntime::new()?;
2356    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2357    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.sub(&x, &x))?;
2358    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
2359    /// # Ok::<(), tenferro_ad::Error>(())
2360    /// ```
2361    ///
2362    /// # Errors
2363    ///
2364    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
2365    /// broadcast/backend error for the operands.
2366    pub fn sub(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2367        self.run_binary("sub", lhs, rhs, StdTensorOp::Sub)
2368    }
2369
2370    /// Multiply eager tensors within this borrowed session.
2371    ///
2372    /// # Examples
2373    ///
2374    /// ```rust
2375    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2376    /// let ctx = EagerRuntime::new()?;
2377    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2378    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.mul(&x, &x))?;
2379    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[9.0]);
2380    /// # Ok::<(), tenferro_ad::Error>(())
2381    /// ```
2382    ///
2383    /// # Errors
2384    ///
2385    /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
2386    /// broadcast/backend error for the operands.
2387    pub fn mul(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2388        self.run_binary("mul", lhs, rhs, StdTensorOp::Mul)
2389    }
2390
2391    /// Divide eager tensors elementwise with broadcast rules.
2392    ///
2393    /// # Examples
2394    /// ```rust
2395    /// use tenferro_ad::{EagerRuntime, Tensor};
2396    /// let ctx = EagerRuntime::new()?;
2397    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2398    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![6.0_f64])?)?;
2399    ///     let divisor = s.constant_from(Tensor::from_vec_col_major(vec![], vec![2.0_f64])?)?;
2400    ///     s.div(&x, &divisor)
2401    /// })?;
2402    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2403    /// # Ok::<(), tenferro_ad::Error>(())
2404    /// ```
2405    /// # Errors
2406    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2407    /// runtime, a validation error with
2408    /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2409    /// [`Error::TensorRuntime`] for a typed backend failure (including integer division by
2410    /// zero).
2411    pub fn div(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2412        self.run_binary("div", lhs, rhs, StdTensorOp::Div)
2413    }
2414
2415    /// Compute the elementwise remainder with broadcast rules.
2416    ///
2417    /// # Examples
2418    /// ```rust
2419    /// use tenferro_ad::{EagerRuntime, Tensor};
2420    /// let ctx = EagerRuntime::new()?;
2421    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2422    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![5.0_f64])?)?;
2423    ///     let divisor = s.constant_from(Tensor::from_vec_col_major(vec![], vec![2.0_f64])?)?;
2424    ///     s.rem(&x, &divisor)
2425    /// })?;
2426    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
2427    /// # Ok::<(), tenferro_ad::Error>(())
2428    /// ```
2429    /// # Errors
2430    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2431    /// runtime, a validation error with
2432    /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2433    /// [`Error::TensorRuntime`] for a typed backend failure (including an integer remainder by
2434    /// zero).
2435    pub fn rem(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2436        self.run_binary("rem", lhs, rhs, StdTensorOp::Rem)
2437    }
2438
2439    /// Raise eager tensor elements to broadcast exponents.
2440    ///
2441    /// # Examples
2442    /// ```rust
2443    /// use tenferro_ad::{EagerRuntime, Tensor};
2444    /// let ctx = EagerRuntime::new()?;
2445    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2446    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2447    ///     let exponent = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2448    ///     s.pow(&x, &exponent)
2449    /// })?;
2450    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[8.0]);
2451    /// # Ok::<(), tenferro_ad::Error>(())
2452    /// ```
2453    /// # Errors
2454    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2455    /// runtime, a validation error with
2456    /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2457    /// [`Error::TensorRuntime`] for a typed backend failure (including a negative integer
2458    /// exponent).
2459    pub fn pow(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2460        self.run_binary("pow", lhs, rhs, StdTensorOp::Pow)
2461    }
2462
2463    /// Compute the elementwise maximum under broadcast rules.
2464    ///
2465    /// # Examples
2466    /// ```rust
2467    /// use tenferro_ad::{EagerRuntime, Tensor};
2468    /// let ctx = EagerRuntime::new()?;
2469    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2470    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2471    ///     let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2472    ///     s.maximum(&x, &bound)
2473    /// })?;
2474    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2475    /// # Ok::<(), tenferro_ad::Error>(())
2476    /// ```
2477    /// # Errors
2478    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2479    pub fn maximum(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2480        self.run_binary("maximum", lhs, rhs, StdTensorOp::Maximum)
2481    }
2482
2483    /// Compute the elementwise minimum under broadcast rules.
2484    ///
2485    /// # Examples
2486    /// ```rust
2487    /// use tenferro_ad::{EagerRuntime, Tensor};
2488    /// let ctx = EagerRuntime::new()?;
2489    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2490    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2491    ///     let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2492    ///     s.minimum(&x, &bound)
2493    /// })?;
2494    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
2495    /// # Ok::<(), tenferro_ad::Error>(())
2496    /// ```
2497    /// # Errors
2498    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2499    pub fn minimum(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2500        self.run_binary("minimum", lhs, rhs, StdTensorOp::Minimum)
2501    }
2502
2503    /// Compare eager tensors elementwise under broadcast rules.
2504    ///
2505    /// # Examples
2506    /// ```rust
2507    /// use tenferro_ad::{CompareDir, EagerRuntime, Tensor};
2508    /// let ctx = EagerRuntime::new()?;
2509    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2510    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2511    ///     let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![1.0_f64])?)?;
2512    ///     s.compare(&x, &bound, CompareDir::Gt)
2513    /// })?;
2514    /// assert_eq!(y.value()?.as_slice::<bool>()?, &[true]);
2515    /// # Ok::<(), tenferro_ad::Error>(())
2516    /// ```
2517    /// # Errors
2518    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2519    pub fn compare(
2520        &mut self,
2521        lhs: &EagerTensor,
2522        rhs: &EagerTensor,
2523        dir: CompareDir,
2524    ) -> Result<EagerTensor> {
2525        self.run_binary("compare", lhs, rhs, StdTensorOp::Compare(dir))
2526    }
2527
2528    /// Select eager values elementwise using a broadcast boolean condition.
2529    ///
2530    /// # Examples
2531    /// ```rust
2532    /// use tenferro_ad::{EagerRuntime, Tensor};
2533    /// let ctx = EagerRuntime::new()?;
2534    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2535    ///     let condition = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![true, false])?)?;
2536    ///     let yes = s.constant_from(Tensor::from_vec_col_major(vec![], vec![10.0_f64])?)?;
2537    ///     let no = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2538    ///     s.where_select(&condition, &yes, &no)
2539    /// })?;
2540    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[10.0, 2.0]);
2541    /// # Ok::<(), tenferro_ad::Error>(())
2542    /// ```
2543    /// # Errors
2544    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2545    pub fn where_select(
2546        &mut self,
2547        condition: &EagerTensor,
2548        on_true: &EagerTensor,
2549        on_false: &EagerTensor,
2550    ) -> Result<EagerTensor> {
2551        self.run_ternary(
2552            "where_select",
2553            condition,
2554            on_true,
2555            on_false,
2556            StdTensorOp::Select,
2557        )
2558    }
2559
2560    /// Alias for [`Self::where_select`] with the same borrowed-session semantics.
2561    ///
2562    /// # Examples
2563    /// ```rust
2564    /// use tenferro_ad::{EagerRuntime, Tensor};
2565    /// let ctx = EagerRuntime::new()?;
2566    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2567    ///     let predicate = s.constant_from(Tensor::from_vec_col_major(vec![], vec![true])?)?;
2568    ///     let yes = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2569    ///     let no = s.constant_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2570    ///     s.select(&predicate, &yes, &no)
2571    /// })?;
2572    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2573    /// # Ok::<(), tenferro_ad::Error>(())
2574    /// ```
2575    /// # Errors
2576    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2577    pub fn select(
2578        &mut self,
2579        condition: &EagerTensor,
2580        on_true: &EagerTensor,
2581        on_false: &EagerTensor,
2582    ) -> Result<EagerTensor> {
2583        self.where_select(condition, on_true, on_false)
2584    }
2585
2586    /// Clamp eager values elementwise between broadcast lower and upper bounds.
2587    ///
2588    /// # Examples
2589    /// ```rust
2590    /// use tenferro_ad::{EagerRuntime, Tensor};
2591    /// let ctx = EagerRuntime::new()?;
2592    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2593    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![-2.0_f64, 5.0])?)?;
2594    ///     let lo = s.constant_from(Tensor::from_vec_col_major(vec![], vec![-1.0_f64])?)?;
2595    ///     let hi = s.constant_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2596    ///     s.clamp(&x, &lo, &hi)
2597    /// })?;
2598    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0, 4.0]);
2599    /// # Ok::<(), tenferro_ad::Error>(())
2600    /// ```
2601    /// # Errors
2602    /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2603    pub fn clamp(
2604        &mut self,
2605        input: &EagerTensor,
2606        lower: &EagerTensor,
2607        upper: &EagerTensor,
2608    ) -> Result<EagerTensor> {
2609        self.run_ternary("clamp", input, lower, upper, StdTensorOp::Clamp)
2610    }
2611
2612    /// Contract eager tensors according to a dot-general dimension mapping.
2613    ///
2614    /// The output layout is `[lhs free..., rhs free..., batch...]`: batch axes
2615    /// come last (see [`DotGeneralConfig`](tenferro_runtime::DotGeneralConfig)).
2616    ///
2617    /// # Examples
2618    ///
2619    /// ```rust
2620    /// use tenferro_ad::{DotGeneralConfig, EagerRuntime, Tensor};
2621    /// let ctx = EagerRuntime::new()?;
2622    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2623    ///     let lhs = session.variable_from(Tensor::from_vec_col_major(vec![1, 2], vec![2.0_f64, 3.0])?)?;
2624    ///     let rhs = session.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![4.0_f64, 5.0])?)?;
2625    ///     session.dot_general(&lhs, &rhs, DotGeneralConfig {
2626    ///         lhs_contracting_dims: [1].as_slice().into(),
2627    ///         rhs_contracting_dims: [0].as_slice().into(),
2628    ///         lhs_batch_dims: [].as_slice().into(),
2629    ///         rhs_batch_dims: [].as_slice().into(),
2630    ///     })
2631    /// })?;
2632    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[23.0]);
2633    /// # Ok::<(), tenferro_ad::Error>(())
2634    /// ```
2635    ///
2636    /// # Errors
2637    ///
2638    /// Returns [`Error::ContextMismatch`] for a foreign eager runtime,
2639    /// a typed validation error for incompatible contraction dimensions,
2640    /// or the backend's typed execution error.
2641    pub fn dot_general(
2642        &mut self,
2643        lhs: &EagerTensor,
2644        rhs: &EagerTensor,
2645        config: DotGeneralConfig,
2646    ) -> Result<EagerTensor> {
2647        self.ensure_runtime(lhs)?;
2648        self.ensure_runtime(rhs)?;
2649        config
2650            .validate_dims_with_ranks(lhs.shape().len(), rhs.shape().len())
2651            .map_err(Error::TensorRuntime)?;
2652        EagerTensor::nary_op_in_session(
2653            &[lhs, rhs],
2654            StdTensorOp::DotGeneral { config },
2655            &mut *self.engine,
2656        )
2657    }
2658
2659    /// Scale an eager tensor by a real scalar in this borrowed session.
2660    /// Integer factors are rounded; finite zero maps to `false` for boolean inputs.
2661    ///
2662    /// # Examples
2663    /// ```rust
2664    /// use tenferro_ad::{EagerRuntime, Tensor};
2665    /// let ctx = EagerRuntime::new()?;
2666    /// let scaled = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2667    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2668    ///     s.scale_real(&x, 2.0)
2669    /// })?;
2670    /// assert_eq!(scaled.value()?.as_slice::<f64>()?, &[2.0, 4.0]);
2671    /// # Ok::<(), tenferro_ad::Error>(())
2672    /// ```
2673    /// # Errors
2674    /// Returns a typed foreign-runtime, invalid-factor/dtype, or backend error.
2675    pub fn scale_real(&mut self, input: &EagerTensor, factor: f64) -> Result<EagerTensor> {
2676        self.ensure_runtime(input)?;
2677        let scalar = tenferro_runtime::scale::real_scale_scalar(input.dtype(), factor)?;
2678        let scalar = self.constant_from_host(scalar)?;
2679        self.mul(input, &scalar)
2680    }
2681
2682    /// Scale a complex eager tensor by a complex scalar in this borrowed session.
2683    ///
2684    /// # Examples
2685    /// ```rust
2686    /// use num_complex::Complex64;
2687    /// use tenferro_ad::{EagerRuntime, Tensor};
2688    /// let ctx = EagerRuntime::new()?;
2689    /// let scaled = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2690    ///     let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![Complex64::new(1.0, 2.0)])?)?;
2691    ///     s.scale_complex(&x, Complex64::new(0.0, 1.0))
2692    /// })?;
2693    /// assert_eq!(scaled.value()?.as_slice::<Complex64>()?, &[Complex64::new(-2.0, 1.0)]);
2694    /// # Ok::<(), tenferro_ad::Error>(())
2695    /// ```
2696    /// # Errors
2697    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2698    /// runtime, [`Error::TensorRuntime`] containing
2699    /// `ValidationError::InvalidArgument` when the input dtype is not complex,
2700    /// or [`Error::TensorRuntime`] for a typed backend failure.
2701    pub fn scale_complex(&mut self, input: &EagerTensor, factor: Complex64) -> Result<EagerTensor> {
2702        self.ensure_runtime(input)?;
2703        let scalar = tenferro_runtime::scale::complex_scale_scalar(input.dtype(), factor)?;
2704        let scalar = self.constant_from_host(scalar)?;
2705        self.mul(input, &scalar)
2706    }
2707
2708    /// Multiply two rank-2 eager tensors in this borrowed session.
2709    ///
2710    /// # Examples
2711    /// ```rust
2712    /// use tenferro_ad::{EagerRuntime, Tensor};
2713    /// let ctx = EagerRuntime::new()?;
2714    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2715    ///     let a = s.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![2.0_f64])?)?;
2716    ///     let b = s.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![3.0_f64])?)?;
2717    ///     s.matmul(&a, &b)
2718    /// })?;
2719    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
2720    /// # Ok::<(), tenferro_ad::Error>(())
2721    /// ```
2722    /// # Errors
2723    /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2724    /// runtime, a validation error with
2725    /// `ValidationError::RankMismatch` or `ValidationError::ShapeMismatch` when
2726    /// the operands are not rank-2 with matching inner dimensions, a dtype
2727    /// mismatch between the operands, or [`Error::TensorRuntime`] for a typed backend failure.
2728    pub fn matmul(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2729        self.ensure_runtime(lhs)?;
2730        self.ensure_runtime(rhs)?;
2731        let lhs_shape = lhs.shape();
2732        let rhs_shape = rhs.shape();
2733        if lhs_shape.len() != 2 {
2734            return Err(tenferro_tensor::Error::rank_mismatch("matmul", 2, lhs_shape.len()).into());
2735        }
2736        if rhs_shape.len() != 2 {
2737            return Err(tenferro_tensor::Error::rank_mismatch("matmul", 2, rhs_shape.len()).into());
2738        }
2739        if lhs_shape[1] != rhs_shape[0] {
2740            return Err(
2741                tenferro_tensor::Error::shape_mismatch("matmul", lhs_shape, rhs_shape).into(),
2742            );
2743        }
2744        self.dot_general(
2745            lhs,
2746            rhs,
2747            DotGeneralConfig {
2748                lhs_contracting_dims: [1].as_slice().into(),
2749                rhs_contracting_dims: [0].as_slice().into(),
2750                lhs_batch_dims: [].as_slice().into(),
2751                rhs_batch_dims: [].as_slice().into(),
2752            },
2753        )
2754    }
2755
2756    /// Contract eagerly with optional conjugation of either operand.
2757    /// Untracked operands use the backend's conjugating contraction directly;
2758    /// tracked operands record explicit conjugations for reverse-mode AD.
2759    ///
2760    /// # Examples
2761    ///
2762    /// ```rust
2763    /// use tenferro_ad::{DotGeneralConfig, EagerRuntime, Tensor};
2764    /// let ctx = EagerRuntime::new()?;
2765    /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2766    ///     let lhs = session.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![2.0_f64])?)?;
2767    ///     let rhs = session.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![3.0_f64])?)?;
2768    ///     let conj_lhs = tenferro_tensor::DotGeneralOptions::default().lhs(tenferro_tensor::Conj::Yes);
2769    ///     session.dot_general_with(&lhs, &rhs, DotGeneralConfig {
2770    ///         lhs_contracting_dims: [1].as_slice().into(),
2771    ///         rhs_contracting_dims: [0].as_slice().into(),
2772    ///         lhs_batch_dims: [].as_slice().into(),
2773    ///         rhs_batch_dims: [].as_slice().into(),
2774    ///     }, &conj_lhs)
2775    /// })?;
2776    /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
2777    /// # Ok::<(), tenferro_ad::Error>(())
2778    /// ```
2779    ///
2780    /// # Errors
2781    ///
2782    /// Returns [`Error::ContextMismatch`] for a foreign eager runtime,
2783    /// a typed validation error for invalid dimensions, or a backend error.
2784    pub fn dot_general_with(
2785        &mut self,
2786        lhs: &EagerTensor,
2787        rhs: &EagerTensor,
2788        config: DotGeneralConfig,
2789        options: &tenferro_tensor::DotGeneralOptions,
2790    ) -> Result<EagerTensor> {
2791        let (lhs_conj, rhs_conj) = (options.lhs.is_yes(), options.rhs.is_yes());
2792        self.ensure_runtime(lhs)?;
2793        self.ensure_runtime(rhs)?;
2794        config
2795            .validate_dims_with_ranks(lhs.shape().len(), rhs.shape().len())
2796            .map_err(Error::TensorRuntime)?;
2797        if !lhs.requires_grad && !rhs.requires_grad {
2798            let output = crate::eager_exec::exec_dot_general_with_conj_on_tensor_reads_in_session(
2799                lhs.tensor_read(),
2800                rhs.tensor_read(),
2801                &config,
2802                lhs_conj,
2803                rhs_conj,
2804                &mut *self.engine,
2805            )?;
2806            return EagerTensor::new_untracked_result(Arc::clone(self.runtime), output);
2807        }
2808        let lhs = if lhs_conj {
2809            self.conj(lhs)?
2810        } else {
2811            lhs.clone()
2812        };
2813        let rhs = if rhs_conj {
2814            self.conj(rhs)?
2815        } else {
2816            rhs.clone()
2817        };
2818        self.dot_general(&lhs, &rhs, config)
2819    }
2820
2821    fn run_binary(
2822        &mut self,
2823        name: &'static str,
2824        lhs: &EagerTensor,
2825        rhs: &EagerTensor,
2826        op: StdTensorOp,
2827    ) -> Result<EagerTensor> {
2828        self.ensure_runtime(lhs)?;
2829        self.ensure_runtime(rhs)?;
2830        let (lhs, rhs) = crate::eager_ops::broadcast_binary_in_session(name, lhs, rhs, self)?;
2831        EagerTensor::nary_op_in_session(&[lhs.as_ref(), rhs.as_ref()], op, &mut *self.engine)
2832    }
2833
2834    fn run_ternary(
2835        &mut self,
2836        name: &'static str,
2837        first: &EagerTensor,
2838        second: &EagerTensor,
2839        third: &EagerTensor,
2840        op: StdTensorOp,
2841    ) -> Result<EagerTensor> {
2842        self.ensure_runtime(first)?;
2843        self.ensure_runtime(second)?;
2844        self.ensure_runtime(third)?;
2845        let (first, second, third) =
2846            crate::eager_ops::broadcast_ternary_in_session(name, first, second, third, self)?;
2847        EagerTensor::nary_op_in_session(&[&first, &second, &third], op, &mut *self.engine)
2848    }
2849
2850    /// Apply one standard tensor op in this borrowed session and record it
2851    /// for AD when needed.
2852    ///
2853    /// Extension crates use this when an extension-level eager operation
2854    /// expands into ordinary `StdTensorOp` nodes instead of a custom extension
2855    /// primitive: all of them run in this one backend session.
2856    ///
2857    /// # Examples
2858    ///
2859    /// ```rust
2860    /// use tenferro_ad::{EagerRuntime, Tensor};
2861    /// use tenferro_ops::std_tensor_op::StdTensorOp;
2862    ///
2863    /// let ctx = EagerRuntime::new()?;
2864    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2865    ///     let x = s.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2866    ///     let negated = s.apply_standard_op(StdTensorOp::Neg, &[&x])?;
2867    ///     s.apply_standard_op(StdTensorOp::Mul, &[&negated, &x])
2868    /// })?;
2869    /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0, -4.0]);
2870    /// assert!(y.tracks_grad());
2871    /// # Ok::<(), tenferro_ad::Error>(())
2872    /// ```
2873    ///
2874    /// # Errors
2875    ///
2876    /// Returns [`Error::TensorRuntime`] containing
2877    /// [`tenferro_tensor::ValidationError::InvalidArgument`] for an extension
2878    /// op, [`Error::ContextMismatch`] for a tensor from another runtime, a
2879    /// typed input-count error, or the backend's typed execution error.
2880    pub fn apply_standard_op(
2881        &mut self,
2882        op: StdTensorOp,
2883        inputs: &[&EagerTensor],
2884    ) -> Result<EagerTensor> {
2885        if matches!(op, StdTensorOp::Extension(_)) {
2886            return Err(Error::invalid_argument(
2887                "EagerSession::apply_standard_op",
2888                ErrorPhase::Execution,
2889                "op",
2890                "Extension ops must be passed to apply_eager",
2891            ));
2892        }
2893        for input in inputs {
2894            self.ensure_runtime(input)?;
2895        }
2896        EagerTensor::nary_op_in_session(inputs, op, &mut *self.engine)
2897    }
2898
2899    /// Borrow the engine this eager session runs on.
2900    ///
2901    /// # Examples
2902    ///
2903    /// ```rust
2904    /// use tenferro_ad::EagerRuntime;
2905    /// use tenferro_cpu::CpuEngine;
2906    ///
2907    /// let ctx = EagerRuntime::new()?;
2908    /// let mut engine = CpuEngine::serial();
2909    /// let id = ctx.with_eager_session(&mut engine, |s| {
2910    ///     Ok::<_, tenferro_ad::Error>(s.engine().target().engine_id().clone())
2911    /// })?;
2912    /// assert_eq!(id, tenferro_cpu::runtime_engine_id()?);
2913    /// # Ok::<(), Box<dyn std::error::Error>>(())
2914    /// ```
2915    pub fn engine(&mut self) -> &mut dyn ExecutionEngine {
2916        &mut *self.engine
2917    }
2918
2919    fn run_unary(&mut self, input: &EagerTensor, op: StdTensorOp) -> Result<EagerTensor> {
2920        self.ensure_runtime(input)?;
2921        EagerTensor::nary_op_in_session(&[input], op, &mut *self.engine)
2922    }
2923
2924    pub(crate) fn record_outputs(
2925        &mut self,
2926        op: &StdTensorOp,
2927        outputs: &[&Tensor],
2928        inputs: &[&EagerTensor],
2929    ) -> Result<RecordedEagerOutputs> {
2930        record_eager_outputs_in_session(op, outputs, inputs, &mut *self.engine)
2931    }
2932
2933    pub(crate) fn ensure_runtime(&self, input: &EagerTensor) -> Result<()> {
2934        if !Arc::ptr_eq(self.runtime, &input.ctx) {
2935            return Err(Error::ContextMismatch {
2936                lhs: self.runtime.id(),
2937                rhs: input.ctx_id(),
2938            });
2939        }
2940        Ok(())
2941    }
2942
2943    pub(crate) fn runtime(&self) -> &Arc<EagerRuntime> {
2944        self.runtime
2945    }
2946
2947    /// Run `f` on this runtime's extension cache store from inside the
2948    /// session.
2949    ///
2950    /// Operation families use this for their own prepared-plan caches without
2951    /// reopening the runtime: the eager owner is already locked, and the cache
2952    /// lock is taken second, as in every extension execution region.
2953    ///
2954    /// # Examples
2955    ///
2956    /// ```rust
2957    /// use tenferro_ad::EagerRuntime;
2958    ///
2959    /// let ctx = EagerRuntime::new()?;
2960    /// let entries = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2961    ///     session.with_extension_caches(|caches| caches.len())
2962    /// })?;
2963    /// assert_eq!(entries, 0);
2964    /// # Ok::<(), tenferro_ad::Error>(())
2965    /// ```
2966    ///
2967    /// # Errors
2968    ///
2969    /// Returns a runtime-state error when the extension cache lock is
2970    /// poisoned.
2971    pub fn with_extension_caches<R>(
2972        &mut self,
2973        f: impl FnOnce(&mut tenferro_runtime::ExtensionCacheStore) -> R,
2974    ) -> Result<R> {
2975        let result = with_lent_extension_caches(self.engine, |_, caches| f(caches));
2976        Ok(result)
2977    }
2978}
2979
2980impl fmt::Debug for EagerRuntime {
2981    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2982        let mut debug = f.debug_struct("EagerRuntime");
2983        debug.field("id", &self.id);
2984        debug.field("runtime_id", &self.runtime.id());
2985        debug.field("runtime_epoch", &self.runtime.epoch().ok());
2986        match self.extension_install_lock.try_lock() {
2987            Ok(_) => {
2988                debug.field("extension_install_lock", &"<unlocked>");
2989            }
2990            Err(_) => {
2991                debug.field("extension_install_lock", &"<locked>");
2992            }
2993        }
2994        debug.field("semantic_extension_rules", &self.semantic_extension_rules);
2995        match self.grad_slots.try_lock() {
2996            Ok(slots) => {
2997                debug.field("grad_slots_len", &slots.len());
2998            }
2999            Err(_) => {
3000                debug.field("grad_slots_len", &"<locked>");
3001            }
3002        }
3003        match self.value_records.try_lock() {
3004            Ok(records) => {
3005                debug.field("value_records_len", &records.len());
3006            }
3007            Err(_) => {
3008                debug.field("value_records_len", &"<locked>");
3009            }
3010        }
3011        match self.ad_transform_cache.stats() {
3012            Ok(stats) => {
3013                debug.field("ad_transform_cache_stats", &stats);
3014            }
3015            Err(err) => {
3016                debug.field("ad_transform_cache_stats", &format_args!("{err}"));
3017            }
3018        }
3019        match self.prepared_derivative_cache.try_lock() {
3020            Ok(cache) => {
3021                debug.field("prepared_derivative_cache_stats", &cache.stats());
3022            }
3023            Err(_) => {
3024                debug.field("prepared_derivative_cache_stats", &"<locked>");
3025            }
3026        }
3027        debug.finish_non_exhaustive()
3028    }
3029}
3030
3031impl EagerRuntime {
3032    fn lock_extension_install(&self) -> Result<MutexGuard<'_, ()>> {
3033        self.extension_install_lock.lock().map_err(|_| {
3034            Error::runtime_state(
3035                "eager_extension_install",
3036                ErrorPhase::Execution,
3037                "lock poisoned",
3038            )
3039        })
3040    }
3041
3042    fn lock_prepared_derivative_cache(&self) -> Result<MutexGuard<'_, PreparedDerivativeCache>> {
3043        self.prepared_derivative_cache.lock().map_err(|_| {
3044            Error::runtime_state(
3045                "prepared_derivative_cache",
3046                ErrorPhase::Execution,
3047                "lock poisoned",
3048            )
3049        })
3050    }
3051
3052    fn lock_grad_slots(
3053        &self,
3054    ) -> Result<MutexGuard<'_, HashMap<ValueKey<StdTensorOp>, WeakGradSlot>>> {
3055        self.grad_slots.lock().map_err(|_| {
3056            Error::runtime_state(
3057                "eager_gradient_slots",
3058                ErrorPhase::Execution,
3059                "lock poisoned",
3060            )
3061        })
3062    }
3063
3064    fn lock_value_records(
3065        &self,
3066    ) -> Result<MutexGuard<'_, HashMap<ValueKey<StdTensorOp>, Weak<EagerTensorRecord>>>> {
3067        self.value_records.lock().map_err(|_| {
3068            Error::runtime_state(
3069                "eager_value_registry",
3070                ErrorPhase::Execution,
3071                "lock poisoned",
3072            )
3073        })
3074    }
3075
3076    fn with_rules_and_cache(
3077        semantic_extension_rules: SemanticExtensionRuleSet,
3078        ad_transform_cache: Arc<AdTransformCache>,
3079    ) -> Result<Self> {
3080        let runtime = Runtime::builder()
3081            .build()
3082            .map_err(|source| runtime_config_error("EagerRuntime::new", source))?;
3083        Ok(Self {
3084            id: ContextId::fresh(),
3085            runtime,
3086            extension_install_lock: Mutex::new(()),
3087            semantic_extension_rules,
3088            grad_slots: Mutex::new(HashMap::new()),
3089            value_records: Mutex::new(HashMap::new()),
3090            ad_transform_cache,
3091            prepared_derivative_cache: Mutex::new(PreparedDerivativeCache::default()),
3092            #[cfg(test)]
3093            semantic_replays: AtomicUsize::new(0),
3094        })
3095    }
3096
3097    /// Create a shared eager execution context.
3098    ///
3099    /// The context stores no engine: every operation runs on the engine the
3100    /// caller passes in.
3101    ///
3102    /// # Examples
3103    ///
3104    /// ```
3105    /// use tenferro_ad::EagerRuntime;
3106    ///
3107    /// let ctx = EagerRuntime::new()?;
3108    /// assert_eq!(std::sync::Arc::strong_count(&ctx), 1);
3109    /// # Ok::<(), tenferro_ad::Error>(())
3110    /// ```
3111    ///
3112    /// # Errors
3113    ///
3114    /// Returns [`Error::RuntimeStateSource`] when the prepared-program runtime
3115    /// cannot be configured, preserving the underlying [`RuntimeConfigError`].
3116    pub fn new() -> Result<Arc<Self>> {
3117        Ok(Arc::new(Self::with_rules_and_cache(
3118            SemanticExtensionRuleSet::default(),
3119            Arc::new(AdTransformCache::new()),
3120        )?))
3121    }
3122
3123    /// Create a shared eager execution context that uses the semantic
3124    /// extension rules and AD transform cache of `ad`.
3125    ///
3126    /// # Examples
3127    ///
3128    /// ```
3129    /// use tenferro_ad::{AdContext, EagerRuntime};
3130    ///
3131    /// let ad = AdContext::builder().build().unwrap();
3132    /// let ctx = EagerRuntime::with_ad_context(&ad)?;
3133    /// assert_eq!(std::sync::Arc::strong_count(&ctx), 1);
3134    /// # Ok::<(), tenferro_ad::Error>(())
3135    /// ```
3136    ///
3137    /// # Errors
3138    ///
3139    /// Returns [`Error::RuntimeStateSource`] when the prepared-program runtime
3140    /// cannot be configured.
3141    pub fn with_ad_context(ad: &AdContext) -> Result<Arc<Self>> {
3142        Ok(Arc::new(Self::with_rules_and_cache(
3143            ad.semantic_extension_rules().clone(),
3144            ad.ad_transform_cache(),
3145        )?))
3146    }
3147
3148    /// Register the kind of `engine` with this runtime if it is not registered
3149    /// yet, and return its target.
3150    pub(crate) fn ensure_engine(&self, engine: &mut dyn ExecutionEngine) -> Result<EngineTarget> {
3151        let target = engine.target();
3152        let snapshot = self
3153            .runtime
3154            .snapshot()
3155            .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3156        if let Some(registered) = snapshot.engine(target.engine_id()) {
3157            if registered.context_identity() != target.context_identity() {
3158                return Err(Error::unsupported(
3159                    "EagerRuntime::ensure_engine",
3160                    ErrorPhase::Execution,
3161                    format!(
3162                        "engine id {:?} is registered for a different engine type",
3163                        target.engine_id()
3164                    ),
3165                ));
3166            }
3167            return Ok(target);
3168        }
3169        let registration = engine_kind_registration(engine)
3170            .ok_or_else(|| unregisterable_engine_error(target.engine_id()))?;
3171        let registration = registration
3172            .map_err(|source| runtime_config_error("EagerRuntime::ensure_engine", source))?;
3173        let _install_guard = self.lock_extension_install()?;
3174        let snapshot = self
3175            .runtime
3176            .snapshot()
3177            .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3178        if snapshot.engine(target.engine_id()).is_none() {
3179            self.runtime
3180                .reconfigure(|edit| {
3181                    edit.register_engine(registration)?;
3182                    Ok(())
3183                })
3184                .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3185        }
3186        Ok(target)
3187    }
3188
3189    /// Return an opaque identifier for this context.
3190    ///
3191    /// # Examples
3192    ///
3193    /// ```
3194    /// use tenferro_ad::{EagerRuntime};
3195    ///
3196    /// let ctx = EagerRuntime::new()?;
3197    /// assert_ne!(ctx.id(), EagerRuntime::new()?.id());
3198    /// # Ok::<(), tenferro_ad::Error>(())
3199    /// ```
3200    pub fn id(&self) -> ContextId {
3201        self.id
3202    }
3203
3204    /// Disable eager operation recording on the current thread until the guard is dropped.
3205    ///
3206    /// This is useful for optimizer updates, metric calculations, and other
3207    /// eager computations that should not become part of the AD tape.
3208    ///
3209    /// # Examples
3210    ///
3211    /// ```
3212    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3213    ///
3214    /// let ctx = EagerRuntime::new()?;
3215    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64]).unwrap())?;
3216    /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3217    ///     let _guard = ctx.no_grad();
3218    ///     s.mul(&x, &x)
3219    /// })?;
3220    /// assert!(!y.tracks_grad());
3221    /// # Ok::<(), tenferro_ad::Error>(())
3222    /// ```
3223    pub fn no_grad(&self) -> EagerNoGradGuard {
3224        EAGER_NO_GRAD_DEPTH.with(|depth| {
3225            depth.set(depth.get().saturating_add(1));
3226        });
3227        EagerNoGradGuard {
3228            active: true,
3229            _not_send: PhantomData,
3230        }
3231    }
3232
3233    /// Keep semantic-trace recording active for untracked intermediates.
3234    ///
3235    /// See [`EagerTraceCaptureGuard`] for the full contract and an example.
3236    pub fn capture_trace(&self) -> EagerTraceCaptureGuard {
3237        EAGER_CAPTURE_DEPTH.with(|depth| {
3238            depth.set(depth.get().saturating_add(1));
3239        });
3240        EagerTraceCaptureGuard {
3241            active: true,
3242            _not_send: PhantomData,
3243        }
3244    }
3245
3246    /// Install or replace one extension module on this eager context's runtime.
3247    ///
3248    /// Eager extension wrappers call this as an idempotent "ensure installed"
3249    /// step. When the exact module instance (same module ID and allocation) is
3250    /// already installed, this is a read-only no-op that returns the current
3251    /// runtime epoch without acquiring the install lock or reconfiguring. The
3252    /// cold or replacement paths keep the transactional install-or-replace
3253    /// behavior, serialized so parallel first-use of the same extension family
3254    /// cannot publish over another thread's base snapshot.
3255    ///
3256    /// # Errors
3257    ///
3258    /// Returns [`tenferro_runtime::Error::RuntimeState`] when runtime
3259    /// reconfiguration fails or the extension module transaction is invalid.
3260    pub fn install_extension_module(
3261        &self,
3262        module: Arc<dyn ExtensionModule>,
3263    ) -> Result<RuntimeEpoch> {
3264        let snapshot = self.runtime.snapshot().map_err(|source| {
3265            runtime_state_source("EagerRuntime::install_extension_module", source)
3266        })?;
3267        if snapshot.has_extension_module_identical(&module) {
3268            return Ok(snapshot.epoch());
3269        }
3270        let _install_guard = self.lock_extension_install()?;
3271        self.runtime
3272            .reconfigure(|edit| {
3273                edit.replace_extension_module(module)?;
3274                Ok(())
3275            })
3276            .map_err(|source| {
3277                runtime_state_source("EagerRuntime::install_extension_module", source)
3278            })
3279    }
3280
3281    pub(crate) fn ensure_extension_module_for_engine(
3282        &self,
3283        module: Arc<dyn ExtensionModule>,
3284        family_id: &'static str,
3285        engine_id: &EngineId,
3286    ) -> Result<RuntimeEpoch> {
3287        let snapshot = self.runtime.snapshot().map_err(|source| {
3288            runtime_state_source("EagerRuntime::ensure_extension_module_for_engine", source)
3289        })?;
3290        if snapshot.has_extension_module_engine(module.module_id(), family_id, engine_id) {
3291            return Ok(snapshot.epoch());
3292        }
3293        let _install_guard = self.lock_extension_install()?;
3294        self.runtime
3295            .reconfigure(|edit| {
3296                edit.ensure_extension_module_for_engine(module, family_id, engine_id)?;
3297                Ok(())
3298            })
3299            .map_err(|source| {
3300                runtime_state_source("EagerRuntime::ensure_extension_module_for_engine", source)
3301            })
3302    }
3303
3304    pub(crate) fn runtime(&self) -> &Runtime {
3305        &self.runtime
3306    }
3307
3308    /// The extension target for `engine`, registering its kind first.
3309    pub(crate) fn eager_extension_target(
3310        &self,
3311        engine: &mut dyn ExecutionEngine,
3312    ) -> Result<EagerExtensionTarget> {
3313        let target = self.ensure_engine(engine)?;
3314        let backend_kind = eager_extension_backend_kind(&target).ok_or_else(|| {
3315            Error::unsupported(
3316                "EagerRuntime::eager_extension_target",
3317                ErrorPhase::Execution,
3318                "this engine kind has no eager extension target",
3319            )
3320        })?;
3321        let target = EagerExtensionTarget {
3322            engine_id: target.engine_id().clone(),
3323            backend_kind,
3324        };
3325        validate_eager_extension_target(&self.runtime, &target)?;
3326        Ok(target)
3327    }
3328
3329    /// Clear every cache owned by this eager context.
3330    ///
3331    /// # Examples
3332    ///
3333    /// ```
3334    /// use tenferro_ad::{EagerRuntime};
3335    ///
3336    /// let ctx = EagerRuntime::new()?;
3337    /// ctx.clear_caches()?;
3338    /// assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);
3339    /// assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);
3340    /// # Ok::<(), tenferro_ad::Error>(())
3341    /// ```
3342    ///
3343    /// # Errors
3344    ///
3345    /// Returns [`tenferro_runtime::Error::RuntimeState`] when either the
3346    /// extension cache or AD-transform cache is poisoned.
3347    pub fn clear_caches(&self) -> Result<()> {
3348        self.clear_ad_transform_caches()?;
3349        self.clear_prepared_derivative_cache()?;
3350        Ok(())
3351    }
3352
3353    /// Clear prepared derivative program cache entries.
3354    ///
3355    /// # Examples
3356    ///
3357    /// ```rust
3358    /// use tenferro_ad::EagerRuntime;
3359    ///
3360    /// let ctx = EagerRuntime::new()?;
3361    /// ctx.clear_prepared_derivative_cache()?;
3362    /// assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);
3363    /// # Ok::<(), tenferro_ad::Error>(())
3364    /// ```
3365    ///
3366    /// # Errors
3367    ///
3368    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3369    /// derivative cache lock is poisoned.
3370    pub fn clear_prepared_derivative_cache(&self) -> Result<()> {
3371        self.lock_prepared_derivative_cache()?.clear();
3372        Ok(())
3373    }
3374
3375    /// Return eager runtime cache-entry and retained-byte stats.
3376    ///
3377    /// # Examples
3378    ///
3379    /// ```
3380    /// use tenferro_ad::{EagerRuntime};
3381    ///
3382    /// let ctx = EagerRuntime::new()?;
3383    /// let stats = ctx.cache_stats()?;
3384    /// assert_eq!(stats.ad_transforms.entries, 0);
3385    /// assert_eq!(stats.prepared_derivatives.entries, 0);
3386    /// # Ok::<(), tenferro_ad::Error>(())
3387    /// ```
3388    ///
3389    /// # Errors
3390    ///
3391    /// Returns [`tenferro_runtime::Error::RuntimeState`] when a cache or
3392    /// AD-transform cache lock is poisoned.
3393    pub fn cache_stats(&self) -> Result<EagerRuntimeCacheStats> {
3394        Ok(EagerRuntimeCacheStats {
3395            ad_transforms: self.ad_transform_cache.stats()?,
3396            prepared_derivatives: self.lock_prepared_derivative_cache()?.stats(),
3397        })
3398    }
3399
3400    /// Return the AD transform cache retention limits.
3401    ///
3402    /// # Examples
3403    ///
3404    /// ```
3405    /// use tenferro_ad::EagerRuntime;
3406    ///
3407    /// let ctx = EagerRuntime::new()?;
3408    /// assert!(ctx.ad_transform_cache_limits()?.max_entries().get() > 0);
3409    /// # Ok::<(), tenferro_ad::Error>(())
3410    /// ```
3411    ///
3412    /// # Errors
3413    ///
3414    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3415    /// cache lock is poisoned.
3416    pub fn ad_transform_cache_limits(&self) -> Result<AdTransformCacheLimits> {
3417        self.ad_transform_cache.limits()
3418    }
3419
3420    /// Replace AD transform cache retention limits.
3421    ///
3422    /// # Examples
3423    ///
3424    /// ```
3425    /// use std::num::NonZeroUsize;
3426    /// use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
3427    ///
3428    /// let ctx = EagerRuntime::new()?;
3429    /// let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
3430    /// ctx.set_ad_transform_cache_limits(limits)?;
3431    /// assert_eq!(ctx.ad_transform_cache_limits()?, limits);
3432    /// # Ok::<(), tenferro_ad::Error>(())
3433    /// ```
3434    ///
3435    /// # Errors
3436    ///
3437    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3438    /// cache lock is poisoned while updating limits.
3439    pub fn set_ad_transform_cache_limits(&self, limits: AdTransformCacheLimits) -> Result<()> {
3440        self.ad_transform_cache.set_limits(limits)
3441    }
3442
3443    /// Clear AD transform cache entries visible through this eager runtime.
3444    ///
3445    /// # Examples
3446    ///
3447    /// ```
3448    /// use tenferro_ad::EagerRuntime;
3449    ///
3450    /// let ctx = EagerRuntime::new()?;
3451    /// ctx.clear_ad_transform_caches()?;
3452    /// assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);
3453    /// # Ok::<(), tenferro_ad::Error>(())
3454    /// ```
3455    ///
3456    /// # Errors
3457    ///
3458    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3459    /// cache lock is poisoned while clearing entries.
3460    pub fn clear_ad_transform_caches(&self) -> Result<()> {
3461        self.ad_transform_cache.clear()
3462    }
3463
3464    /// Return prepared derivative cache retention limits.
3465    ///
3466    /// # Examples
3467    ///
3468    /// ```rust
3469    /// use tenferro_ad::EagerRuntime;
3470    ///
3471    /// let ctx = EagerRuntime::new()?;
3472    /// assert!(ctx.prepared_derivative_cache_limits()?.max_entries().get() > 0);
3473    /// # Ok::<(), tenferro_ad::Error>(())
3474    /// ```
3475    ///
3476    /// # Errors
3477    ///
3478    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3479    /// derivative cache lock is poisoned.
3480    pub fn prepared_derivative_cache_limits(&self) -> Result<AdTransformCacheLimits> {
3481        Ok(self.lock_prepared_derivative_cache()?.limits())
3482    }
3483
3484    /// Replace prepared derivative cache retention limits.
3485    ///
3486    /// # Examples
3487    ///
3488    /// ```rust
3489    /// use std::num::NonZeroUsize;
3490    /// use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
3491    ///
3492    /// let ctx = EagerRuntime::new()?;
3493    /// let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
3494    /// ctx.set_prepared_derivative_cache_limits(limits)?;
3495    /// assert_eq!(ctx.prepared_derivative_cache_limits()?, limits);
3496    /// # Ok::<(), tenferro_ad::Error>(())
3497    /// ```
3498    ///
3499    /// # Errors
3500    ///
3501    /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3502    /// derivative cache lock is poisoned.
3503    pub fn set_prepared_derivative_cache_limits(
3504        &self,
3505        limits: AdTransformCacheLimits,
3506    ) -> Result<()> {
3507        self.lock_prepared_derivative_cache()?.set_limits(limits);
3508        Ok(())
3509    }
3510
3511    /// Run eager operations on `engine`.
3512    ///
3513    /// The callback receives an [`EagerSession`] that pairs this runtime with
3514    /// the borrowed engine; operations recorded through it are differentiable.
3515    /// Nothing is entered or locked: the engine is simply borrowed for the
3516    /// callback.
3517    ///
3518    /// # Examples
3519    ///
3520    /// ```
3521    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3522    /// use tenferro_cpu::CpuEngine;
3523    ///
3524    /// let ctx = EagerRuntime::new()?;
3525    /// let mut engine = CpuEngine::serial();
3526    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
3527    /// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
3528    /// let z = ctx.with_eager_session(&mut engine, |s| s.add(&x, &y))?;
3529    /// assert_eq!(z.value()?.as_slice::<f64>()?, &[3.0]);
3530    /// # Ok::<(), tenferro_ad::Error>(())
3531    /// ```
3532    ///
3533    /// # Errors
3534    ///
3535    /// Returns [`Error::Unsupported`] when the engine kind cannot be registered
3536    /// with this runtime or its context identity conflicts with the existing
3537    /// registration, [`Error::RuntimeStateSource`] when the runtime snapshot or
3538    /// engine registration state is unavailable, and the callback's own error
3539    /// unchanged.
3540    pub fn with_eager_session<T, E: From<Error>>(
3541        self: &Arc<Self>,
3542        engine: &mut dyn ExecutionEngine,
3543        f: impl FnOnce(&mut EagerSession<'_>) -> std::result::Result<T, E>,
3544    ) -> std::result::Result<T, E> {
3545        self.ensure_engine(engine).map_err(E::from)?;
3546        f(&mut EagerSession {
3547            runtime: self,
3548            engine,
3549        })
3550    }
3551
3552    /// Run a compiled program on `engine` through this runtime.
3553    pub(crate) fn run_program(
3554        &self,
3555        engine: &mut dyn ExecutionEngine,
3556        program: &CompiledGraph,
3557        inputs: &[TensorRead<'_>],
3558    ) -> Result<Vec<Tensor>> {
3559        let target = self.ensure_engine(engine)?;
3560        let prepared = self
3561            .runtime
3562            .prepare(program, inputs, std::slice::from_ref(&target))?;
3563        run_prepared_on(&self.runtime, engine, &prepared, inputs)
3564    }
3565
3566    pub(crate) fn exec_extension_outputs_read(
3567        &self,
3568        engine: &mut dyn ExecutionEngine,
3569        op: &Arc<dyn tenferro_ops::ext_op::ExtensionOp>,
3570        inputs: &[TensorRead<'_>],
3571    ) -> Result<Vec<Tensor>> {
3572        self.ensure_engine(engine)?;
3573        profile_eager_op_section("exec_extension_outputs_read.exec_op", || {
3574            exec_extension_op_on_tensor_reads(op, inputs, engine, &self.runtime)
3575        })
3576    }
3577
3578    #[cfg(test)]
3579    pub(crate) fn exec_standard_graph_outputs(
3580        &self,
3581        engine: &mut dyn ExecutionEngine,
3582        graph: &Graph<StdTensorOp>,
3583        initial_data: HashMap<ValueKey<StdTensorOp>, Tensor>,
3584    ) -> Result<EagerGraphExecution> {
3585        let mut all_values = initial_data;
3586
3587        profile_eager_op_section("exec_graph.run", || {
3588            let exec: &mut dyn Engine = engine;
3589            (|| -> Result<()> {
3590                for op_node in graph.operations() {
3591                    let outputs = {
3592                        let input_values = op_node
3593                            .inputs
3594                            .iter()
3595                            .map(|input| {
3596                                let key = match input {
3597                                    ValueRef::Local(local_id) => &graph.values()[*local_id].key,
3598                                    ValueRef::External(key) => key,
3599                                };
3600                                all_values.get(key).ok_or_else(|| {
3601                                    Error::Internal(format!(
3602                                        "standard graph eager execution missing value for {key:?}"
3603                                    ))
3604                                })
3605                            })
3606                            .collect::<Result<Vec<_>>>()?;
3607                        let input_reads = input_values
3608                            .iter()
3609                            .map(|value| TensorRead::from_tensor(value))
3610                            .collect::<Vec<_>>();
3611                        exec_standard_op_on_tensor_reads_in_session(
3612                            &op_node.operation,
3613                            &input_reads,
3614                            exec,
3615                        )?
3616                    };
3617
3618                    if outputs.len() != op_node.outputs.len() {
3619                        return Err(Error::Internal(format!(
3620                            "standard graph eager execution expected {} outputs for {:?}, got {}",
3621                            op_node.outputs.len(),
3622                            op_node.operation,
3623                            outputs.len()
3624                        )));
3625                    }
3626
3627                    for (output_id, output) in op_node.outputs.iter().zip(outputs) {
3628                        let key = graph.values()[*output_id].key.clone();
3629                        all_values.insert(key, output);
3630                    }
3631                }
3632                Ok(())
3633            })()
3634        })?;
3635
3636        let outputs = graph
3637            .outputs()
3638            .iter()
3639            .map(|&output_id| {
3640                let key = &graph.values()[output_id].key;
3641                all_values
3642                    .get(key)
3643                    .ok_or_else(|| {
3644                        Error::Internal(format!(
3645                            "standard graph eager execution missing graph output {key:?}"
3646                        ))
3647                    })?
3648                    .duplicate()
3649                    .map_err(Error::from)
3650            })
3651            .collect::<Result<Vec<_>>>()?;
3652
3653        Ok(EagerGraphExecution { outputs })
3654    }
3655
3656    pub(crate) fn try_register_grad_slot(
3657        &self,
3658        key: &ValueKey<StdTensorOp>,
3659        slot: &GradSlot,
3660    ) -> Result<()> {
3661        insert_pruning_dead(
3662            &mut *self.lock_grad_slots()?,
3663            key.clone(),
3664            Arc::downgrade(slot),
3665        );
3666        Ok(())
3667    }
3668
3669    pub(crate) fn try_register_value_record(
3670        &self,
3671        key: &ValueKey<StdTensorOp>,
3672        record: &Arc<EagerTensorRecord>,
3673    ) -> Result<()> {
3674        insert_pruning_dead(
3675            &mut *self.lock_value_records()?,
3676            key.clone(),
3677            Arc::downgrade(record),
3678        );
3679        Ok(())
3680    }
3681
3682    pub(crate) fn value_record(
3683        &self,
3684        key: &ValueKey<StdTensorOp>,
3685    ) -> Result<Option<Arc<EagerTensorRecord>>> {
3686        let mut records = self.lock_value_records()?;
3687        let Some(record) = records.get(key).cloned() else {
3688            return Ok(None);
3689        };
3690        match record.upgrade() {
3691            Some(record) => Ok(Some(record)),
3692            None => {
3693                records.remove(key);
3694                Ok(None)
3695            }
3696        }
3697    }
3698
3699    /// Clear all live gradient slots tracked by this context.
3700    ///
3701    /// This resets the stored gradients to `None` without unregistering the
3702    /// tensors, so future `EagerSession::backward` calls can accumulate again.
3703    ///
3704    /// # Examples
3705    ///
3706    /// ```
3707    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3708    ///
3709    /// let ctx = EagerRuntime::new()?;
3710    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
3711    /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
3712    /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3713    ///     let product = s.mul(&x, &y)?;
3714    ///     s.reduce_sum(&product, Some(&[0]))
3715    /// })?;
3716    /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
3717    ///
3718    /// ctx.clear_grads()?;
3719    ///
3720    /// assert!(x.grad()?.is_none());
3721    /// assert!(y.grad()?.is_none());
3722    /// # Ok::<(), tenferro_ad::Error>(())
3723    /// ```
3724    ///
3725    /// # Errors
3726    ///
3727    /// Returns [`tenferro_runtime::Error::RuntimeState`] if a gradient-slot
3728    /// lock is poisoned while clearing live gradients.
3729    pub fn clear_grads(&self) -> Result<()> {
3730        let live_slots = {
3731            let mut live_slots = Vec::new();
3732            self.lock_grad_slots()?.retain(|_, slot| {
3733                if let Some(slot) = slot.upgrade() {
3734                    live_slots.push(slot);
3735                    true
3736                } else {
3737                    false
3738                }
3739            });
3740            live_slots
3741        };
3742
3743        let mut poisoned_slot = false;
3744        for slot in live_slots {
3745            match slot.lock() {
3746                Ok(mut current) => {
3747                    *current = None;
3748                }
3749                Err(_) => {
3750                    poisoned_slot = true;
3751                }
3752            }
3753        }
3754        if poisoned_slot {
3755            return Err(Error::runtime_state(
3756                "eager_gradient_slot",
3757                ErrorPhase::Execution,
3758                "lock poisoned",
3759            ));
3760        }
3761        Ok(())
3762    }
3763
3764    /// Import a concrete tensor into this context as an untracked constant.
3765    ///
3766    /// The returned tensor does not participate in gradient tracking.
3767    /// Use this for fixed masks, quadrature weights, physical constants,
3768    /// and other data that should not receive gradients. Like
3769    /// [`EagerSession::constant_from`], it performs no host/device transfer;
3770    /// use [`EagerSession::constant_from_host`] to upload host data into a
3771    /// device runtime.
3772    ///
3773    /// # Examples
3774    ///
3775    /// ```
3776    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3777    ///
3778    /// let ctx = EagerRuntime::new()?;
3779    /// let c = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
3780    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap())?;
3781    /// let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.add(&x, &c))?;
3782    ///
3783    /// assert_eq!(z.value()?.as_slice::<f64>().unwrap(), &[4.0, 6.0]);
3784    /// # Ok::<(), tenferro_ad::Error>(())
3785    /// ```
3786    ///
3787    /// # Errors
3788    ///
3789    /// Returns [`tenferro_runtime::Error::RuntimeState`] when metadata cannot
3790    /// be registered or the backend lock is poisoned.
3791    pub fn constant_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor> {
3792        EagerTensor::new_leaf(Arc::clone(self), tensor, false)
3793    }
3794
3795    /// Import a concrete tensor into this context as a trainable variable.
3796    ///
3797    /// The returned tensor participates in gradient tracking; its gradient
3798    /// slot is registered in this context.
3799    ///
3800    /// # Examples
3801    ///
3802    /// ```
3803    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3804    ///
3805    /// let ctx = EagerRuntime::new()?;
3806    /// let p = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
3807    /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3808    ///     let y = s.exp(&p)?;
3809    ///     s.reduce_sum(&y, Some(&[0]))
3810    /// })?;
3811    /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
3812    ///
3813    /// let grad = p.grad().unwrap().unwrap();
3814    /// assert_eq!(grad.shape(), &[2]);
3815    /// # Ok::<(), tenferro_ad::Error>(())
3816    /// ```
3817    ///
3818    /// # Errors
3819    ///
3820    /// Returns [`tenferro_runtime::Error::RuntimeState`] when gradient metadata
3821    /// or the eager backend state cannot be registered.
3822    pub fn variable_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor> {
3823        EagerTensor::new_leaf(Arc::clone(self), tensor, true)
3824    }
3825
3826    fn store_grads(
3827        &self,
3828        cotangents: &HashMap<ValueKey<StdTensorOp>, Tensor>,
3829        session: &mut dyn Engine,
3830    ) -> Result<()> {
3831        let mut updates = Vec::new();
3832
3833        {
3834            let mut slots = self.lock_grad_slots()?;
3835            slots.retain(|key, slot| {
3836                let Some(slot) = slot.upgrade() else {
3837                    return false;
3838                };
3839
3840                if let Some(incoming) = cotangents.get(key) {
3841                    updates.push((slot, incoming));
3842                }
3843
3844                true
3845            });
3846        }
3847
3848        for (slot, incoming) in updates {
3849            let mut current = slot.lock().map_err(|_| {
3850                Error::runtime_state(
3851                    "eager_gradient_slot",
3852                    ErrorPhase::Execution,
3853                    "lock poisoned",
3854                )
3855            })?;
3856            let next = match current.as_ref() {
3857                Some(existing) => {
3858                    let existing_read = existing.tensor_read("EagerRuntime::store_grads")?;
3859                    let incoming_read = TensorRead::from_tensor(incoming);
3860                    let tensor = session
3861                        .add_read(existing_read, incoming_read)
3862                        .map_err(Error::from)?;
3863                    AdValueRecord::from_tensor(tensor, "EagerRuntime::store_grads")?
3864                }
3865                None => {
3866                    let duplicate = session
3867                        .to_contiguous_read(TensorRead::from_tensor(incoming))
3868                        .map_err(Error::from)?;
3869                    AdValueRecord::from_tensor(duplicate, "EagerRuntime::store_grads")?
3870                }
3871            };
3872            *current = Some(next);
3873        }
3874
3875        Ok(())
3876    }
3877}
3878
3879#[derive(Clone, Debug, PartialEq, Eq, Hash)]
3880struct PreparedDerivativeCacheKey {
3881    /// Engines with the same target share prepared derivative programs.
3882    target: EngineTarget,
3883    semantic_fingerprint: SemanticFingerprint,
3884    runtime_epoch: RuntimeEpoch,
3885    active_inputs: Box<[bool]>,
3886    input_metadata: Box<[ProgramValueMetadata]>,
3887}
3888
3889/// Cached prepared derivative: program + index metadata.
3890#[derive(Debug)]
3891struct PreparedDerivative {
3892    program: Arc<CompiledGraph>,
3893    execution_program: Arc<CompiledGraph>,
3894    saved_input_indices: Vec<usize>,
3895    prepared: Arc<Prepared>,
3896    seed_input_index: usize,
3897    derivative_output_indices: Box<[Option<usize>]>,
3898}
3899
3900#[derive(Debug)]
3901struct PreparedDerivativeCache {
3902    limits: AdTransformCacheLimits,
3903    entries: LruCache<PreparedDerivativeCacheKey, PreparedDerivativeCacheEntry>,
3904    stats: CacheStats,
3905}
3906
3907impl PreparedDerivativeCache {
3908    fn limits(&self) -> AdTransformCacheLimits {
3909        self.limits
3910    }
3911
3912    fn set_limits(&mut self, limits: AdTransformCacheLimits) {
3913        self.limits = limits;
3914        self.evict_to_limits();
3915    }
3916
3917    fn clear(&mut self) {
3918        let clears = self.stats.clears.saturating_add(1);
3919        self.entries.clear();
3920        self.stats = CacheStats {
3921            clears,
3922            ..CacheStats::empty()
3923        };
3924    }
3925
3926    fn stats(&self) -> CacheStats {
3927        self.stats
3928    }
3929
3930    fn get(&mut self, key: &PreparedDerivativeCacheKey) -> Option<Arc<PreparedDerivative>> {
3931        match self.entries.get(key) {
3932            Some(entry) => {
3933                self.stats.hits = self.stats.hits.saturating_add(1);
3934                Some(Arc::clone(&entry.value))
3935            }
3936            None => {
3937                self.stats.misses = self.stats.misses.saturating_add(1);
3938                None
3939            }
3940        }
3941    }
3942
3943    fn insert(&mut self, key: PreparedDerivativeCacheKey, value: Arc<PreparedDerivative>) {
3944        let retained_bytes = prepared_derivative_cache_entry_retained_bytes(&key, value.as_ref());
3945        let entry = PreparedDerivativeCacheEntry {
3946            value,
3947            retained_bytes,
3948        };
3949        self.stats.retained_bytes = self.stats.retained_bytes.saturating_add(retained_bytes);
3950        if let Some((_old_key, old_entry)) = self.entries.push(key, entry) {
3951            self.stats.retained_bytes = self
3952                .stats
3953                .retained_bytes
3954                .saturating_sub(old_entry.retained_bytes);
3955        }
3956        self.stats.entries = self.entries.len();
3957        self.evict_to_limits();
3958    }
3959
3960    fn evict_to_limits(&mut self) {
3961        while self.entries.len() > self.limits.max_entries().get()
3962            || self
3963                .limits
3964                .max_retained_bytes()
3965                .is_some_and(|limit| self.stats.retained_bytes > limit.get())
3966        {
3967            let Some((_key, entry)) = self.entries.pop_lru() else {
3968                break;
3969            };
3970            self.stats.retained_bytes = self
3971                .stats
3972                .retained_bytes
3973                .saturating_sub(entry.retained_bytes);
3974            self.stats.evictions = self.stats.evictions.saturating_add(1);
3975        }
3976        self.stats.entries = self.entries.len();
3977    }
3978}
3979
3980impl Default for PreparedDerivativeCache {
3981    fn default() -> Self {
3982        Self {
3983            limits: AdTransformCacheLimits::default(),
3984            entries: LruCache::unbounded(),
3985            stats: CacheStats::empty(),
3986        }
3987    }
3988}
3989
3990#[derive(Debug)]
3991struct PreparedDerivativeCacheEntry {
3992    value: Arc<PreparedDerivative>,
3993    retained_bytes: usize,
3994}
3995
3996fn prepared_derivative_cache_entry_retained_bytes(
3997    key: &PreparedDerivativeCacheKey,
3998    value: &PreparedDerivative,
3999) -> usize {
4000    size_of::<PreparedDerivativeCacheKey>()
4001        .saturating_add(size_of_val(key.active_inputs.as_ref()))
4002        .saturating_add(size_of_val(value.derivative_output_indices.as_ref()))
4003        .saturating_add(size_of_val(value.saved_input_indices.as_slice()))
4004        .saturating_add(compiled_graph_retained_bytes(
4005            value.execution_program.as_ref(),
4006        ))
4007        .saturating_add(
4008            key.input_metadata
4009                .len()
4010                .saturating_mul(size_of::<ProgramValueMetadata>()),
4011        )
4012        .saturating_add(size_of::<PreparedDerivative>())
4013        .saturating_add(compiled_graph_retained_bytes(value.program.as_ref()))
4014        .saturating_add(prepared_compiled_graph_retained_bytes(
4015            value.prepared.as_ref(),
4016            value.program.as_ref(),
4017        ))
4018}
4019
4020fn prepared_compiled_graph_retained_bytes(
4021    prepared: &Prepared,
4022    derivative_program: &CompiledGraph,
4023) -> usize {
4024    size_of_val(prepared).saturating_add(compiled_graph_retained_bytes(derivative_program))
4025}
4026
4027fn compiled_graph_retained_bytes(program: &CompiledGraph) -> usize {
4028    size_of::<CompiledGraph>()
4029        .saturating_add(size_of_val(program.input_keys()))
4030        .saturating_add(program.bindings().len().saturating_mul(size_of::<usize>()))
4031        .saturating_add(semantic_program_retained_bytes(program.program()))
4032}
4033
4034fn semantic_program_retained_bytes(program: &SemanticProgram) -> usize {
4035    size_of::<SemanticProgram>()
4036        .saturating_add(size_of_val(program.inputs()))
4037        .saturating_add(size_of_val(program.outputs()))
4038        .saturating_add(
4039            program
4040                .operations()
4041                .len()
4042                .saturating_mul(size_of::<usize>()),
4043        )
4044        .saturating_add(
4045            program
4046                .shape_guards()
4047                .len()
4048                .saturating_mul(size_of::<usize>()),
4049        )
4050}
4051
4052fn semantic_eager_vjp_many(
4053    ctx: &Arc<EagerRuntime>,
4054    engine: &mut dyn ExecutionEngine,
4055    output: &EagerTensor,
4056    wrts: &[&EagerTensor],
4057    cotangent: &EagerTensor,
4058) -> Result<Vec<Option<EagerTensor>>> {
4059    if wrts.is_empty() {
4060        return Ok(Vec::new());
4061    }
4062    let Some(output_semantic) = output.semantic.as_ref() else {
4063        return Ok(vec![None; wrts.len()]);
4064    };
4065    let saved = output
4066        .trace
4067        .as_ref()
4068        .map(EagerTrace::collect)
4069        .unwrap_or_default();
4070    // One replay for this backward pass. Residual roots keep the semantic
4071    // producers available to differentiation; only the execution-only
4072    // derivative replaces their numerical values.
4073    let mut roots = Vec::with_capacity(1 + saved.len());
4074    roots.push(output_semantic.clone());
4075    roots.extend(saved.iter().map(|value| value.semantic.clone()));
4076    let source = replay(&roots)?;
4077    #[cfg(test)]
4078    ctx.semantic_replays.fetch_add(1, Ordering::Relaxed);
4079    if source.outputs().len() != roots.len()
4080        || source.leaf_data().len() != source.frozen().program.inputs().len()
4081    {
4082        return Err(Error::Internal(
4083            "semantic eager VJP source has inconsistent inputs or outputs".into(),
4084        ));
4085    }
4086    let wrt_input_indices = wrts
4087        .iter()
4088        .map(|wrt| {
4089            wrt.semantic
4090                .as_ref()
4091                .and_then(|semantic| source.input_index_of(semantic))
4092        })
4093        .collect::<Vec<_>>();
4094    let mut active_inputs = vec![false; source.leaves().len()];
4095    for &index in wrt_input_indices.iter().flatten() {
4096        active_inputs[index] = true;
4097    }
4098    if !active_inputs.iter().any(|&active| active) {
4099        return Ok(vec![None; wrts.len()]);
4100    }
4101
4102    // One transform and execution for the complete active set shares primal
4103    // work and cotangents between leaves instead of replaying them per target.
4104    // S2: check prepared-derivative cache before AD transform + compile_frozen.
4105    let mut compiler = GraphCompiler::new();
4106    let target = ctx.ensure_engine(engine)?;
4107    let cache_key = PreparedDerivativeCacheKey {
4108        target: target.clone(),
4109        semantic_fingerprint: source.frozen().program.semantic_fingerprint(),
4110        runtime_epoch: ctx.runtime.epoch().map_err(|source| {
4111            Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::Execution, source)
4112        })?,
4113        active_inputs: active_inputs.clone().into_boxed_slice(),
4114        input_metadata: source.frozen().input_metadata_with_bound_shapes(),
4115    };
4116    let prepared = { ctx.lock_prepared_derivative_cache()?.get(&cache_key) };
4117    let (
4118        seed_input_index,
4119        derivative_output_indices,
4120        derivative_program,
4121        execution_program,
4122        saved_input_indices,
4123        prepared_runtime,
4124    ) = if let Some(prepared) = prepared {
4125        (
4126            prepared.seed_input_index,
4127            prepared.derivative_output_indices.clone(),
4128            Arc::clone(&prepared.program),
4129            Arc::clone(&prepared.execution_program),
4130            prepared.saved_input_indices.clone(),
4131            Some(Arc::clone(&prepared.prepared)),
4132        )
4133    } else {
4134        let mut active_outputs = vec![false; source.outputs().len()];
4135        active_outputs[0] = true;
4136        let ad = AdContext::with_rules_and_transform_cache(
4137            ctx.semantic_extension_rules.clone(),
4138            Arc::clone(&ctx.ad_transform_cache),
4139        );
4140        let derivative = ad
4141            .vjp_program(source.frozen(), &active_inputs, &active_outputs)
4142            .map_err(|source| {
4143                Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::GraphBuild, source)
4144            })?;
4145        let seed_input_index = derivative
4146            .derivative_input_indices()
4147            .first()
4148            .copied()
4149            .flatten();
4150        let Some(seed_input_index) = seed_input_index else {
4151            return Ok(vec![None; wrts.len()]);
4152        };
4153        let derivative_output_indices = derivative
4154            .derivative_output_indices()
4155            .to_vec()
4156            .into_boxed_slice();
4157        let program = Arc::new(compiler.compile_frozen_program(derivative.frozen())?);
4158        let (execution_program, saved_input_indices) = if saved.is_empty() {
4159            (Arc::clone(&program), Vec::new())
4160        } else {
4161            let (execution, indices) = crate::semantic_transform::semantic_vjp_with_saved_outputs(
4162                source.frozen(),
4163                &active_inputs,
4164                &active_outputs,
4165                &ctx.semantic_extension_rules,
4166                &(1..source.outputs().len()).collect::<Vec<_>>(),
4167            )
4168            .map_err(|source| {
4169                Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::GraphBuild, source)
4170            })?;
4171            (
4172                Arc::new(compiler.compile_frozen_program(execution.frozen())?),
4173                indices,
4174            )
4175        };
4176        (
4177            seed_input_index,
4178            derivative_output_indices,
4179            program,
4180            execution_program,
4181            saved_input_indices,
4182            None,
4183        )
4184    };
4185
4186    let cotangent_tensor = Arc::new(RetainedValue::from_tensor(
4187        cotangent.duplicate_value_in_session(&mut *engine)?,
4188    ));
4189    let input_count = execution_program.input_count();
4190    let mut owned_inputs: Vec<Option<Tensor>> = (0..input_count).map(|_| None).collect();
4191    // Residuals, primal bindings and the seed are staged on the caller's engine.
4192    (|| -> Result<()> {
4193        let session: &mut dyn Engine = &mut *engine;
4194        for (value, &index) in saved.iter().zip(&saved_input_indices) {
4195            let read = value.value.tensor_read("eager residual")?;
4196            let Some(slot) = owned_inputs.get_mut(index) else {
4197                return Err(Error::Internal(format!(
4198                    "semantic eager VJP residual index {index} is outside {input_count} inputs"
4199                )));
4200            };
4201            *slot = Some(session.to_contiguous_read(read)?);
4202        }
4203        for (source_input_index, data) in source.leaf_data().iter().enumerate() {
4204            let Some(slot) = owned_inputs.get_mut(source_input_index) else {
4205                return Err(Error::Internal(format!(
4206                    "semantic eager VJP derivative program has no primal input slot {source_input_index}"
4207                )));
4208            };
4209            *slot = Some(copy_value_in_session(session, data)?);
4210        }
4211        let Some(slot) = owned_inputs.get_mut(seed_input_index) else {
4212            return Err(Error::Internal(format!(
4213                "semantic eager VJP seed input index {seed_input_index} is outside {input_count} inputs"
4214            )));
4215        };
4216        *slot = Some(copy_value_in_session(session, cotangent_tensor.as_ref())?);
4217        Ok(())
4218    })()?;
4219    let input_refs = owned_inputs
4220        .iter()
4221        .enumerate()
4222        .map(|(index, tensor)| {
4223            tensor.as_ref().ok_or_else(|| {
4224                Error::Internal(format!(
4225                    "semantic eager VJP derivative input {index} was not populated"
4226                ))
4227            })
4228        })
4229        .collect::<Result<Vec<_>>>()?;
4230    let input_reads = input_refs
4231        .iter()
4232        .map(|tensor| TensorRead::from_tensor(tensor))
4233        .collect::<Vec<_>>();
4234    let prepared_runtime = if let Some(prepared_runtime) = prepared_runtime {
4235        prepared_runtime
4236    } else {
4237        let prepared_runtime = Arc::new(ctx.runtime.prepare(
4238            &execution_program,
4239            &input_reads,
4240            std::slice::from_ref(&target),
4241        )?);
4242        let entry = Arc::new(PreparedDerivative {
4243            program: Arc::clone(&derivative_program),
4244            execution_program: Arc::clone(&execution_program),
4245            saved_input_indices: saved_input_indices.clone(),
4246            prepared: Arc::clone(&prepared_runtime),
4247            seed_input_index,
4248            derivative_output_indices: derivative_output_indices.clone(),
4249        });
4250        ctx.lock_prepared_derivative_cache()?
4251            .insert(cache_key, entry);
4252        prepared_runtime
4253    };
4254    let mut outputs = run_prepared_on(&ctx.runtime, engine, &prepared_runtime, &input_reads)?
4255        .into_iter()
4256        .map(Some)
4257        .collect::<Vec<_>>();
4258    let cotangent_semantic = SemanticValue::leaf(
4259        next_input_key(),
4260        cotangent_tensor.dtype(),
4261        cotangent_tensor.shape().len(),
4262        Arc::clone(&cotangent_tensor),
4263    );
4264    let derivative_frozen = Arc::new(derivative_program.frozen_program().clone());
4265
4266    #[cfg(test)]
4267    EAGER_SEMANTIC_VJP_EXECUTIONS.fetch_add(1, Ordering::Relaxed);
4268
4269    wrts.iter()
4270        .zip(wrt_input_indices)
4271        .map(|(_wrt, input_index)| {
4272            let Some(derivative_output_index) = input_index
4273                .and_then(|index| derivative_output_indices.get(index).copied().flatten())
4274            else {
4275                return Ok(None);
4276            };
4277            let result = outputs
4278                .get_mut(derivative_output_index)
4279                .and_then(Option::take)
4280                .ok_or_else(|| {
4281                    Error::Internal(format!(
4282                "semantic eager VJP derivative output {derivative_output_index} unavailable"
4283            ))
4284                })?;
4285            let semantic = derivative_semantic(
4286                &derivative_frozen,
4287                &source,
4288                &[(seed_input_index, cotangent_semantic.clone())],
4289                derivative_output_index,
4290                "semantic_eager_vjp",
4291            )?;
4292            Ok(Some(EagerTensor::new_result_with_semantic(
4293                Arc::clone(ctx),
4294                eager_val_key(),
4295                result,
4296                true,
4297                output.trace.clone(),
4298                Some(semantic),
4299            )?))
4300        })
4301        .collect()
4302}
4303
4304fn semantic_eager_jvp_optional(
4305    ctx: &Arc<EagerRuntime>,
4306    engine: &mut dyn ExecutionEngine,
4307    output: &EagerTensor,
4308    wrt: &EagerTensor,
4309    tangent: &EagerTensor,
4310) -> Result<Option<EagerTensor>> {
4311    let (Some(output_semantic), Some(wrt_semantic)) =
4312        (output.semantic.as_ref(), wrt.semantic.as_ref())
4313    else {
4314        return Ok(None);
4315    };
4316    if !wrt_semantic.is_leaf() {
4317        return Ok(None);
4318    }
4319
4320    // One replay for this forward-mode pass; it also answers whether `wrt` is an
4321    // input of the output's program.
4322    let source = replay(std::slice::from_ref(output_semantic))?;
4323    #[cfg(test)]
4324    ctx.semantic_replays.fetch_add(1, Ordering::Relaxed);
4325    if source.outputs().len() != 1
4326        || source.leaf_data().len() != source.frozen().program.inputs().len()
4327    {
4328        return Err(Error::Internal(
4329            "semantic eager JVP source has inconsistent inputs or outputs".into(),
4330        ));
4331    }
4332    let Some(wrt_input_index) = source.input_index_of(wrt_semantic) else {
4333        return Ok(None);
4334    };
4335
4336    let mut active_inputs = vec![false; source.leaves().len()];
4337    if let Some(active) = active_inputs.get_mut(wrt_input_index) {
4338        *active = true;
4339    } else {
4340        return Err(Error::Internal(
4341            "semantic eager JVP input index is outside the source inputs".into(),
4342        ));
4343    }
4344    let ad = AdContext::with_rules_and_transform_cache(
4345        ctx.semantic_extension_rules.clone(),
4346        Arc::clone(&ctx.ad_transform_cache),
4347    );
4348    let derivative = ad
4349        .jvp_program(source.frozen(), &active_inputs)
4350        .map_err(|source| {
4351            Error::runtime_state_source("semantic_eager_jvp", ErrorPhase::GraphBuild, source)
4352        })?;
4353    // derivative_input_indices maps source input → derivative seed input.
4354    let Some(seed_input_index) = derivative
4355        .derivative_input_indices()
4356        .get(wrt_input_index)
4357        .copied()
4358        .flatten()
4359    else {
4360        return Ok(None);
4361    };
4362    // derivative_output_indices maps source output → derivative output.
4363    // There is always exactly one source output (guarded above).
4364    let Some(derivative_output_index) = derivative
4365        .derivative_output_indices()
4366        .first()
4367        .copied()
4368        .flatten()
4369    else {
4370        return Ok(None);
4371    };
4372
4373    let mut compiler = GraphCompiler::new();
4374    let derivative_program = compiler.compile_frozen_program(derivative.frozen())?;
4375    let tangent_tensor = Arc::new(RetainedValue::from_tensor(
4376        tangent.duplicate_value_in_session(&mut *engine)?,
4377    ));
4378    let input_count = derivative_program.input_count();
4379    let mut owned_inputs: Vec<Option<Tensor>> = (0..input_count).map(|_| None).collect();
4380    // Primal bindings and the seed are staged on the caller's engine.
4381    (|| -> Result<()> {
4382        let session: &mut dyn Engine = &mut *engine;
4383        for (source_input_index, data) in source.leaf_data().iter().enumerate() {
4384            let Some(slot) = owned_inputs.get_mut(source_input_index) else {
4385                return Err(Error::Internal(format!(
4386                    "semantic eager JVP derivative program has no primal input slot {source_input_index}"
4387                )));
4388            };
4389            *slot = Some(copy_value_in_session(session, data)?);
4390        }
4391        let Some(slot) = owned_inputs.get_mut(seed_input_index) else {
4392            return Err(Error::Internal(format!(
4393                "semantic eager JVP seed input index {seed_input_index} is outside {input_count} inputs"
4394            )));
4395        };
4396        *slot = Some(copy_value_in_session(session, tangent_tensor.as_ref())?);
4397        Ok(())
4398    })()?;
4399    let input_refs = owned_inputs
4400        .iter()
4401        .enumerate()
4402        .map(|(index, tensor)| {
4403            tensor.as_ref().ok_or_else(|| {
4404                Error::Internal(format!(
4405                    "semantic eager JVP derivative input {index} was not populated"
4406                ))
4407            })
4408        })
4409        .collect::<Result<Vec<_>>>()?;
4410    let input_reads = input_refs
4411        .iter()
4412        .map(|tensor| TensorRead::from_tensor(tensor))
4413        .collect::<Vec<_>>();
4414    let outputs = ctx.run_program(engine, &derivative_program, &input_reads)?;
4415    let output_count = outputs.len();
4416    let Some(result) = outputs.into_iter().nth(derivative_output_index) else {
4417        return Err(Error::Internal(format!(
4418            "semantic eager JVP derivative output index {derivative_output_index} is outside {} outputs",
4419            output_count
4420        )));
4421    };
4422    let tangent_semantic = SemanticValue::leaf(
4423        next_input_key(),
4424        tangent_tensor.dtype(),
4425        tangent_tensor.shape().len(),
4426        Arc::clone(&tangent_tensor),
4427    );
4428    let derivative_frozen = Arc::new(derivative.frozen().clone());
4429    let semantic = derivative_semantic(
4430        &derivative_frozen,
4431        &source,
4432        &[(seed_input_index, tangent_semantic)],
4433        derivative_output_index,
4434        "semantic_eager_jvp",
4435    )?;
4436
4437    Ok(Some(EagerTensor::new_result_with_semantic(
4438        Arc::clone(ctx),
4439        eager_val_key(),
4440        result,
4441        true,
4442        None,
4443        Some(semantic),
4444    )?))
4445}
4446
4447/// Record a derivative value over a frozen derivative program.
4448///
4449/// The derivative program's inputs are the source program's inputs followed by
4450/// the seed inputs the transform introduced, so the recorded edges are the
4451/// replayed leaves plus the seed values.
4452fn derivative_semantic(
4453    derivative_frozen: &Arc<tenferro_runtime::program::FrozenProgram>,
4454    source: &crate::eager::semantic::ReplayedProgram,
4455    seeds: &[(usize, SemanticValue)],
4456    derivative_output_index: usize,
4457    transform: &'static str,
4458) -> Result<SemanticValue> {
4459    let input_count = derivative_frozen.program.inputs().len();
4460    let source_input_count = source.leaves().len();
4461    let mut inputs: Vec<Option<SemanticValue>> = vec![None; input_count];
4462    for (index, leaf) in source.leaves().iter().enumerate() {
4463        if let Some(slot) = inputs.get_mut(index) {
4464            *slot = Some(leaf.clone());
4465        }
4466    }
4467    for (seed_input_index, seed) in seeds {
4468        if *seed_input_index < source_input_count {
4469            return Err(Error::Internal(format!(
4470                "{transform} derivative seed input {seed_input_index} overlaps the {source_input_count} source inputs"
4471            )));
4472        }
4473        let Some(slot) = inputs.get_mut(*seed_input_index) else {
4474            return Err(Error::Internal(format!(
4475                "{transform} derivative seed input {seed_input_index} is outside {input_count} inputs"
4476            )));
4477        };
4478        *slot = Some(seed.clone());
4479    }
4480    let inputs = inputs
4481        .into_iter()
4482        .enumerate()
4483        .map(|(index, value)| {
4484            value.ok_or_else(|| {
4485                Error::Internal(format!(
4486                    "{transform} derivative input {index} has no recorded semantic edge"
4487                ))
4488            })
4489        })
4490        .collect::<Result<Vec<_>>>()?;
4491    if derivative_output_index >= derivative_frozen.program.outputs().len() {
4492        return Err(Error::Internal(format!(
4493            "{transform} derivative output index {derivative_output_index} is outside {} outputs",
4494            derivative_frozen.program.outputs().len()
4495        )));
4496    }
4497    Ok(SemanticValue::program(
4498        Arc::clone(derivative_frozen),
4499        derivative_output_index,
4500        inputs.into_boxed_slice(),
4501    ))
4502}
4503
4504fn copy_value_in_session(session: &mut dyn Engine, value: &RetainedValue) -> Result<Tensor> {
4505    let read = value.tensor_read().map_err(|error| {
4506        Error::runtime_state_source("copy_value_for_runtime", ErrorPhase::Execution, error)
4507    })?;
4508    session.to_contiguous_read(read).map_err(Error::from)
4509}
4510
4511fn validate_seed_tensor(op: &'static str, primal: &EagerTensor, seed: &EagerTensor) -> Result<()> {
4512    if primal.dtype() != seed.dtype() {
4513        return Err(
4514            tenferro_tensor::Error::dtype_mismatch(op, primal.dtype(), seed.dtype()).into(),
4515        );
4516    }
4517    if primal.shape() != seed.shape() {
4518        return Err(
4519            tenferro_tensor::Error::shape_mismatch(op, primal.shape(), seed.shape()).into(),
4520        );
4521    }
4522    Ok(())
4523}
4524
4525/// Eager tensor with reverse-mode autodiff over concrete tensor values.
4526///
4527/// This executes each primitive immediately and records a lightweight reverse
4528/// DAG for `EagerSession::backward`. Gradients accumulate across repeated `EagerSession::backward`
4529/// calls until they are cleared explicitly.
4530///
4531/// # Examples
4532///
4533/// ```
4534/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
4535///
4536/// let ctx = EagerRuntime::new()?;
4537/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap())?;
4538/// for _ in 0..2 {
4539///     let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
4540///         let squared = s.mul(&x, &x)?;
4541///         s.reduce_sum(&squared, Some(&[0]))
4542///     })?;
4543///     loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
4544/// }
4545///
4546/// assert_eq!(x.grad()?.unwrap().as_slice::<f64>().unwrap(), &[4.0, 8.0, 12.0]);
4547/// x.clear_grad()?;
4548///
4549/// assert!(x.grad().unwrap().is_none());
4550/// # Ok::<(), tenferro_ad::Error>(())
4551/// ```
4552#[derive(Clone)]
4553pub struct EagerTensor {
4554    pub(crate) key: ValueKey<StdTensorOp>,
4555    pub(crate) trace: Option<EagerTrace>,
4556    pub(crate) semantic: Option<SemanticValue>,
4557    pub(crate) requires_grad: bool,
4558    grad_slot: GradSlot,
4559    pub(crate) ctx: Arc<EagerRuntime>,
4560    _record: Arc<EagerTensorRecord>,
4561}
4562
4563pub(crate) struct EagerTensorRecord {
4564    value: Arc<AdValueRecord>,
4565    key: ValueKey<StdTensorOp>,
4566    trace: Option<EagerTrace>,
4567    semantic: Option<SemanticValue>,
4568    requires_grad: bool,
4569    grad_slot: GradSlot,
4570    ctx: Arc<EagerRuntime>,
4571}
4572
4573struct EagerTensorParts {
4574    ctx: Arc<EagerRuntime>,
4575    key: ValueKey<StdTensorOp>,
4576    requires_grad: bool,
4577    trace: Option<EagerTrace>,
4578    semantic: Option<SemanticValue>,
4579    value: Arc<AdValueRecord>,
4580    register_value: bool,
4581}
4582
4583impl fmt::Debug for EagerTensor {
4584    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4585        f.debug_struct("EagerTensor")
4586            .field("dtype", &self.dtype())
4587            .field("shape", &self.shape())
4588            .field("key", &self.key)
4589            .field("requires_grad", &self.requires_grad)
4590            .field("has_trace", &self.trace.is_some())
4591            .field("has_semantic", &self.semantic.is_some())
4592            .field("ctx_id", &self.ctx_id())
4593            .finish_non_exhaustive()
4594    }
4595}
4596
4597impl EagerTensor {
4598    pub(crate) fn new_leaf(
4599        ctx: Arc<EagerRuntime>,
4600        tensor: Tensor,
4601        requires_grad: bool,
4602    ) -> Result<Self> {
4603        Self::new_leaf_with_session(ctx, tensor, requires_grad, None)
4604    }
4605
4606    pub(crate) fn new_leaf_in_session(
4607        ctx: Arc<EagerRuntime>,
4608        tensor: Tensor,
4609        requires_grad: bool,
4610        session: &mut dyn Engine,
4611    ) -> Result<Self> {
4612        Self::new_leaf_with_session(ctx, tensor, requires_grad, Some(session))
4613    }
4614
4615    fn new_leaf_with_session(
4616        ctx: Arc<EagerRuntime>,
4617        tensor: Tensor,
4618        requires_grad: bool,
4619        session: Option<&mut dyn Engine>,
4620    ) -> Result<Self> {
4621        let key = eager_val_key();
4622        // A host-placement tensor needs no backend session: the CPU backend only
4623        // copies the host buffer for it, so entering a session would add
4624        // admission, provider exclusion, and session construction without doing
4625        // any provider work (#1704). Views and backend-family reads keep the
4626        // session path, and device runtimes keep it for every read.
4627        let read = TensorRead::from_tensor(&tensor);
4628        let semantic_tensor =
4629            match session {
4630                Some(session) => session.to_contiguous_read(read).map_err(Error::from)?,
4631                None => match cpu_host_owned_read(&read) {
4632                    Some(materialized) => materialized.map_err(Error::from)?,
4633                    None => return Err(Error::unsupported(
4634                        "EagerTensor::new_leaf",
4635                        ErrorPhase::Execution,
4636                        "this tensor needs an engine to become an eager leaf; create it through \
4637                         EagerSession::constant_from or EagerSession::variable_from",
4638                    )),
4639                },
4640            };
4641        let semantic_value = Arc::new(RetainedValue::from_tensor(semantic_tensor));
4642        let semantic = SemanticValue::leaf(
4643            next_input_key(),
4644            semantic_value.dtype(),
4645            semantic_value.shape().len(),
4646            semantic_value,
4647        );
4648        let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_leaf")?;
4649        Self::from_parts(EagerTensorParts {
4650            ctx,
4651            key,
4652            requires_grad,
4653            trace: None,
4654            semantic: Some(semantic),
4655            value,
4656            register_value: true,
4657        })
4658    }
4659
4660    pub(crate) fn new_result(
4661        ctx: Arc<EagerRuntime>,
4662        key: ValueKey<StdTensorOp>,
4663        tensor: Tensor,
4664        requires_grad: bool,
4665        trace: Option<EagerTrace>,
4666    ) -> Result<Self> {
4667        Self::new_result_with_semantic(ctx, key, tensor, requires_grad, trace, None)
4668    }
4669
4670    pub(crate) fn new_result_with_semantic(
4671        ctx: Arc<EagerRuntime>,
4672        key: ValueKey<StdTensorOp>,
4673        tensor: Tensor,
4674        requires_grad: bool,
4675        trace: Option<EagerTrace>,
4676        semantic: Option<SemanticValue>,
4677    ) -> Result<Self> {
4678        let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_result")?;
4679        Self::from_parts(EagerTensorParts {
4680            ctx,
4681            key,
4682            requires_grad,
4683            trace,
4684            semantic,
4685            value,
4686            register_value: true,
4687        })
4688    }
4689
4690    pub(crate) fn new_unregistered_result_with_semantic(
4691        ctx: Arc<EagerRuntime>,
4692        key: ValueKey<StdTensorOp>,
4693        tensor: Tensor,
4694        requires_grad: bool,
4695        trace: Option<EagerTrace>,
4696        semantic: Option<SemanticValue>,
4697    ) -> Result<Self> {
4698        let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_unregistered_result")?;
4699        Self::from_parts(EagerTensorParts {
4700            ctx,
4701            key,
4702            requires_grad,
4703            trace,
4704            semantic,
4705            value,
4706            register_value: false,
4707        })
4708    }
4709
4710    pub(crate) fn new_result_value(
4711        ctx: Arc<EagerRuntime>,
4712        key: ValueKey<StdTensorOp>,
4713        value: TensorValue,
4714        requires_grad: bool,
4715        trace: Option<EagerTrace>,
4716        semantic: Option<SemanticValue>,
4717    ) -> Result<Self> {
4718        let (group, slot, dtype, shape) = value.try_into_group_parts().map_err(|_| {
4719            Error::runtime_state(
4720                "EagerTensor::new_result_value",
4721                ErrorPhase::Execution,
4722                "a TensorValue could not be transferred into its allocation group",
4723            )
4724        })?;
4725        let value = AdValueRecord::from_group(group, slot, dtype, shape);
4726        Self::from_parts(EagerTensorParts {
4727            ctx,
4728            key,
4729            requires_grad,
4730            trace,
4731            semantic,
4732            value,
4733            register_value: true,
4734        })
4735    }
4736
4737    fn from_parts(parts: EagerTensorParts) -> Result<Self> {
4738        let EagerTensorParts {
4739            ctx,
4740            key,
4741            requires_grad,
4742            trace,
4743            semantic,
4744            value,
4745            register_value,
4746        } = parts;
4747        let grad_slot = Arc::new(Mutex::new(None));
4748        if requires_grad {
4749            ctx.try_register_grad_slot(&key, &grad_slot)?;
4750        }
4751        let record = Arc::new(EagerTensorRecord {
4752            value: Arc::clone(&value),
4753            key: key.clone(),
4754            trace: trace.clone(),
4755            semantic: semantic.clone(),
4756            requires_grad,
4757            grad_slot: Arc::clone(&grad_slot),
4758            ctx: Arc::clone(&ctx),
4759        });
4760        if register_value {
4761            ctx.try_register_value_record(&key, &record)?;
4762        }
4763
4764        Ok(Self {
4765            key,
4766            trace,
4767            semantic,
4768            requires_grad,
4769            grad_slot,
4770            ctx,
4771            _record: record,
4772        })
4773    }
4774
4775    pub(crate) fn new_untracked_result(ctx: Arc<EagerRuntime>, tensor: Tensor) -> Result<Self> {
4776        let value =
4777            AdValueRecord::from_untracked_tensor(tensor, "EagerTensor::new_untracked_result")?;
4778        Ok(Self::new_untracked_value_record(ctx, value, None))
4779    }
4780
4781    pub(crate) fn new_untracked_value_result(
4782        ctx: Arc<EagerRuntime>,
4783        value: TensorValue,
4784    ) -> Result<Self> {
4785        Self::new_untracked_value_result_with_semantic(ctx, value, None)
4786    }
4787
4788    pub(crate) fn new_untracked_value_result_with_semantic(
4789        ctx: Arc<EagerRuntime>,
4790        value: TensorValue,
4791        semantic: Option<SemanticValue>,
4792    ) -> Result<Self> {
4793        let (group, slot, dtype, shape) = value.try_into_group_parts().map_err(|_| {
4794            Error::runtime_state(
4795                "EagerTensor::new_untracked_value_result",
4796                ErrorPhase::Execution,
4797                "a TensorValue could not be transferred into its allocation group",
4798            )
4799        })?;
4800        let value = AdValueRecord::from_group(group, slot, dtype, shape);
4801        Ok(Self::new_untracked_value_record(ctx, value, semantic))
4802    }
4803
4804    fn new_untracked_value_record(
4805        ctx: Arc<EagerRuntime>,
4806        value: Arc<AdValueRecord>,
4807        semantic: Option<SemanticValue>,
4808    ) -> Self {
4809        let key = eager_val_key();
4810        let grad_slot = Arc::new(Mutex::new(None));
4811        let record = Arc::new(EagerTensorRecord {
4812            value,
4813            key: key.clone(),
4814            trace: None,
4815            semantic: semantic.clone(),
4816            requires_grad: false,
4817            grad_slot: Arc::clone(&grad_slot),
4818            ctx: Arc::clone(&ctx),
4819        });
4820        Self {
4821            key,
4822            trace: None,
4823            semantic,
4824            requires_grad: false,
4825            grad_slot,
4826            ctx,
4827            _record: record,
4828        }
4829    }
4830
4831    pub(crate) fn from_record(record: Arc<EagerTensorRecord>) -> Self {
4832        Self {
4833            key: record.key.clone(),
4834            trace: record.trace.clone(),
4835            semantic: record.semantic.clone(),
4836            requires_grad: record.requires_grad,
4837            grad_slot: Arc::clone(&record.grad_slot),
4838            ctx: Arc::clone(&record.ctx),
4839            _record: record,
4840        }
4841    }
4842
4843    /// Borrow the retained value without creating an owner or copy.
4844    ///
4845    /// # Errors
4846    ///
4847    /// Returns [`Error::RuntimeState`] when the retained allocation-group
4848    /// descriptor is unavailable or invalid.
4849    pub fn value(&self) -> Result<ValueGuard<'_>> {
4850        self._record.value.value("EagerTensor::value")
4851    }
4852
4853    fn duplicate_host_value(&self) -> Option<Tensor> {
4854        // A pooled value duplicates through its descriptor view; a caller-owned
4855        // payload has no such view and duplicates through its own read path, which
4856        // copies the value while keeping its element type.
4857        self.value().ok()?.duplicate_host_tensor().ok()
4858    }
4859
4860    /// Detach this value from its graph: same value and runtime, a fresh
4861    /// untracked semantic leaf. The caller has checked the runtime.
4862    fn detach_in_session(&self, session: &mut dyn Engine) -> Result<Self> {
4863        let tensor = self.duplicate_value_in_session(session)?;
4864        let data = Arc::new(RetainedValue::from_tensor(tensor));
4865        let semantic =
4866            SemanticValue::leaf(next_input_key(), data.dtype(), data.shape().len(), data);
4867        Ok(Self::new_untracked_value_record(
4868            self.ctx.clone(),
4869            Arc::clone(&self._record.value),
4870            Some(semantic),
4871        ))
4872    }
4873
4874    pub(crate) fn duplicate_value_in_session(&self, session: &mut dyn Engine) -> Result<Tensor> {
4875        if let Some(tensor) = self.duplicate_host_value() {
4876            return Ok(tensor);
4877        }
4878        let read = self
4879            ._record
4880            .value
4881            .tensor_read("EagerTensor::duplicate_value")?;
4882        session.to_contiguous_read(read).map_err(Error::from)
4883    }
4884
4885    // INVARIANT: the error variants return the unchanged eager handle so a
4886    // caller can retry ownership extraction without an implicit copy.
4887    #[allow(clippy::result_large_err)]
4888    /// Consume this handle and structurally extract its retained allocation.
4889    ///
4890    /// A shared handle is returned unchanged as [`IntoValueError::NotUnique`].
4891    /// Group extraction failures return the unchanged handle and typed group
4892    /// error; no copy or fallback materialization is attempted.
4893    ///
4894    /// # Errors
4895    ///
4896    /// Returns [`IntoValueError::NotUnique`] when another handle retains the
4897    /// value, or [`IntoValueError::Extract`] when structural group extraction
4898    /// fails because the allocation is aliased or its descriptor is invalid.
4899    ///
4900    /// # Examples
4901    ///
4902    /// ```
4903    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
4904    ///
4905    /// let ctx = EagerRuntime::new()?;
4906    /// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
4907    /// let owner = value
4908    ///     .into_value()
4909    ///     .expect("a uniquely owned value should be extractable");
4910    /// assert_eq!(owner.as_slice::<f64>()?, &[3.0]);
4911    /// # Ok::<(), tenferro_ad::Error>(())
4912    /// ```
4913    pub fn into_value(self) -> std::result::Result<Tensor, IntoValueError<Self>> {
4914        if Arc::strong_count(&self._record) != 1 {
4915            return Err(IntoValueError::NotUnique(self));
4916        }
4917        let Self { _record, .. } = self;
4918        let record = match Arc::try_unwrap(_record) {
4919            Ok(record) => record,
4920            Err(record) => return Err(IntoValueError::NotUnique(Self::from_record(record))),
4921        };
4922        let EagerTensorRecord {
4923            value,
4924            key,
4925            trace,
4926            semantic,
4927            requires_grad,
4928            grad_slot,
4929            ctx,
4930        } = record;
4931        let value = match Arc::try_unwrap(value) {
4932            Ok(value) => value,
4933            Err(value) => {
4934                let record = Arc::new(EagerTensorRecord {
4935                    value,
4936                    key,
4937                    trace,
4938                    semantic,
4939                    requires_grad,
4940                    grad_slot,
4941                    ctx,
4942                });
4943                return Err(IntoValueError::NotUnique(Self::from_record(record)));
4944            }
4945        };
4946        let AdValueRecord {
4947            container,
4948            dtype,
4949            shape,
4950        } = value;
4951        let container = match Arc::try_unwrap(container) {
4952            Ok(container) => container,
4953            Err(container) => {
4954                let record = Arc::new(EagerTensorRecord {
4955                    value: Arc::new(AdValueRecord {
4956                        container,
4957                        dtype,
4958                        shape,
4959                    }),
4960                    key,
4961                    trace,
4962                    semantic,
4963                    requires_grad,
4964                    grad_slot,
4965                    ctx,
4966                });
4967                return Err(IntoValueError::NotUnique(Self::from_record(record)));
4968            }
4969        };
4970        let (group, slot) = match container {
4971            // A caller-owned payload is handed back to its owner unchanged.
4972            RetentionContainer::CallerOwned { tensor } => return Ok(*tensor),
4973            RetentionContainer::Owned { tensor } => return Ok(tensor),
4974            RetentionContainer::Pooled { group, slot } => (group, slot),
4975        };
4976        match group.into_tensor(slot) {
4977            Ok(tensor) => Ok(tensor),
4978            Err((group, error)) => {
4979                let record = Arc::new(EagerTensorRecord {
4980                    value: Arc::new(AdValueRecord {
4981                        container: Arc::new(RetentionContainer::Pooled { group, slot }),
4982                        dtype,
4983                        shape,
4984                    }),
4985                    key,
4986                    trace,
4987                    semantic,
4988                    requires_grad,
4989                    grad_slot,
4990                    ctx,
4991                });
4992                Err(IntoValueError::Extract {
4993                    value: Self::from_record(record),
4994                    error,
4995                })
4996            }
4997        }
4998    }
4999
5000    /// Return this tensor's scalar dtype without materializing through
5001    /// [`value`](Self::value).
5002    pub fn dtype(&self) -> DType {
5003        self._record.value.dtype()
5004    }
5005
5006    /// Return this tensor's logical shape without materializing through
5007    /// [`value`](Self::value).
5008    pub fn shape(&self) -> &[usize] {
5009        self._record.value.shape()
5010    }
5011
5012    /// Borrow this tensor value as a [`TensorRead`].
5013    ///
5014    /// This is the preferred borrowed input boundary for executor calls. It
5015    /// preserves the option to replace eager storage with non-contiguous views
5016    /// without forcing callers through [`value`](Self::value).
5017    ///
5018    /// # Panics
5019    ///
5020    /// Panics if a validated eager value record becomes unavailable, which
5021    /// indicates an internal invariant violation.
5022    pub fn tensor_read(&self) -> TensorRead<'_> {
5023        self._record
5024            .value
5025            .tensor_read("EagerTensor::tensor_read")
5026            .expect("validated eager value record")
5027    }
5028
5029    /// Return the accumulated gradient currently stored for this tensor.
5030    ///
5031    /// The stored gradient accumulates across repeated `EagerSession::backward` calls
5032    /// until it is cleared explicitly.
5033    ///
5034    /// For complex scalar losses, stored gradients use tenferro's
5035    /// Hermitian-adjoint cotangent convention. See
5036    /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
5037    ///
5038    /// # Examples
5039    ///
5040    /// ```
5041    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5042    ///
5043    /// let ctx = EagerRuntime::new()?;
5044    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
5045    /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
5046    ///     let y = s.exp(&x)?;
5047    ///     s.reduce_sum(&y, Some(&[0]))
5048    /// })?;
5049    /// let _cotangents = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
5050    ///
5051    /// let grad = x.grad()?.unwrap();
5052    /// assert_eq!(grad.shape(), &[2]);
5053    /// # Ok::<(), tenferro_ad::Error>(())
5054    /// ```
5055    ///
5056    /// # Errors
5057    ///
5058    /// Returns [`Error::RuntimeState`] if the gradient slot is poisoned or no
5059    /// longer available.
5060    pub fn grad(&self) -> Result<Option<GradientValue>> {
5061        self.grad_slot
5062            .lock()
5063            .map_err(|_| {
5064                Error::runtime_state(
5065                    "eager_gradient_slot",
5066                    ErrorPhase::Execution,
5067                    "lock poisoned",
5068                )
5069            })
5070            .map(|slot| {
5071                slot.as_ref().map(|record| GradientValue {
5072                    record: Arc::clone(record),
5073                })
5074            })
5075    }
5076
5077    /// Clear the accumulated gradient stored for this tensor.
5078    ///
5079    /// This only affects this tensor's gradient slot. Other tensors in the
5080    /// same context retain their gradients until they are cleared explicitly or
5081    /// overwritten by later accumulation.
5082    ///
5083    /// # Examples
5084    ///
5085    /// ```
5086    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5087    ///
5088    /// let ctx = EagerRuntime::new()?;
5089    /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
5090    /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
5091    /// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
5092    ///     let product = s.mul(&x, &y)?;
5093    ///     s.reduce_sum(&product, Some(&[0]))
5094    /// })?;
5095    /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
5096    ///
5097    /// x.clear_grad()?;
5098    ///
5099    /// assert!(x.grad()?.is_none());
5100    /// assert!(y.grad()?.is_some());
5101    /// # Ok::<(), tenferro_ad::Error>(())
5102    /// ```
5103    ///
5104    /// # Errors
5105    ///
5106    /// Returns [`Error::RuntimeState`] if the gradient slot lock is poisoned.
5107    pub fn clear_grad(&self) -> Result<()> {
5108        *self.grad_slot.lock().map_err(|_| {
5109            Error::runtime_state(
5110                "eager_gradient_slot",
5111                ErrorPhase::Execution,
5112                "lock poisoned",
5113            )
5114        })? = None;
5115        Ok(())
5116    }
5117
5118    /// Report whether this tensor participates in gradient tracking.
5119    ///
5120    /// Tracked tensors keep a gradient slot in their eager context; untracked
5121    /// tensors and detached tensors do not.
5122    ///
5123    /// # Examples
5124    ///
5125    /// ```
5126    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5127    ///
5128    /// let ctx = EagerRuntime::new()?;
5129    /// let plain = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
5130    /// let tracked = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap()).unwrap();
5131    /// let detached = tracked.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.detach(&tracked)).unwrap();
5132    ///
5133    /// assert!(!plain.tracks_grad());
5134    /// assert!(tracked.tracks_grad());
5135    /// assert!(!detached.tracks_grad());
5136    /// # Ok::<(), tenferro_ad::Error>(())
5137    /// ```
5138    pub fn tracks_grad(&self) -> bool {
5139        self.requires_grad
5140    }
5141
5142    #[cfg(test)]
5143    fn debug_trace_saved_value_count(&self) -> Option<usize> {
5144        None
5145    }
5146
5147    /// Return the opaque identifier of the context this tensor belongs to.
5148    ///
5149    /// # Examples
5150    ///
5151    /// ```
5152    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5153    ///
5154    /// let ctx = EagerRuntime::new()?;
5155    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
5156    ///
5157    /// assert_eq!(x.ctx_id(), ctx.id());
5158    /// # Ok::<(), tenferro_ad::Error>(())
5159    /// ```
5160    pub fn ctx_id(&self) -> ContextId {
5161        self.ctx.id()
5162    }
5163
5164    /// Borrow the eager runtime context that owns this tensor.
5165    pub fn runtime(&self) -> &Arc<EagerRuntime> {
5166        &self.ctx
5167    }
5168
5169    /// Check whether two tensors belong to the same eager context.
5170    ///
5171    /// # Examples
5172    ///
5173    /// ```
5174    /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5175    ///
5176    /// let ctx = EagerRuntime::new()?;
5177    /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
5178    /// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
5179    ///
5180    /// assert!(x.same_context(&y));
5181    /// # Ok::<(), tenferro_ad::Error>(())
5182    /// ```
5183    pub fn same_context(&self, other: &Self) -> bool {
5184        self.ctx_id() == other.ctx_id()
5185    }
5186
5187    #[cfg(test)]
5188    pub(crate) fn standard_graph_op(
5189        engine: &mut dyn ExecutionEngine,
5190        inputs: &[&Self],
5191        build_graph: impl FnOnce(&[TensorInputKey]) -> Result<Arc<Graph<StdTensorOp>>>,
5192    ) -> Result<Vec<Self>> {
5193        let Some(first) = inputs.first() else {
5194            return Err(Error::Internal(
5195                "standard eager graph op requires at least one input tensor".to_string(),
5196            ));
5197        };
5198        let ctx = Arc::clone(&first.ctx);
5199        for tensor in inputs.iter().skip(1) {
5200            if !first.same_context(tensor) {
5201                return Err(Error::ContextMismatch {
5202                    lhs: first.ctx_id(),
5203                    rhs: tensor.ctx_id(),
5204                });
5205            }
5206        }
5207
5208        let graph_input_keys = (0..inputs.len())
5209            .map(|_| next_input_key())
5210            .collect::<Vec<_>>();
5211        let graph = build_graph(&graph_input_keys)?;
5212        let initial_data = graph_input_keys
5213            .iter()
5214            .zip(inputs.iter())
5215            .map(|(key, tensor)| {
5216                Ok((
5217                    ValueKey::Input(key.clone()),
5218                    tensor.duplicate_value_in_session(&mut *engine)?,
5219                ))
5220            })
5221            .collect::<Result<HashMap<_, _>>>()?;
5222        let execution = ctx.exec_standard_graph_outputs(engine, graph.as_ref(), initial_data)?;
5223        if execution.outputs.len() != graph.outputs().len() {
5224            return Err(Error::Internal(format!(
5225                "standard eager graph op expected {} graph outputs, got {}",
5226                graph.outputs().len(),
5227                execution.outputs.len()
5228            )));
5229        }
5230
5231        if !eager_grad_recording_enabled() || !inputs.iter().any(|input| input.requires_grad) {
5232            return execution
5233                .outputs
5234                .into_iter()
5235                .map(|output| {
5236                    Self::new_unregistered_result_with_semantic(
5237                        Arc::clone(&ctx),
5238                        eager_val_key(),
5239                        output,
5240                        false,
5241                        None,
5242                        None,
5243                    )
5244                })
5245                .collect();
5246        }
5247
5248        let recorded = record_eager_graph_outputs(
5249            graph.as_ref(),
5250            &graph_input_keys,
5251            &execution.outputs,
5252            inputs,
5253        )?;
5254        if recorded.traces.len() != execution.outputs.len() {
5255            return Err(Error::Internal(format!(
5256                "standard eager graph op expected {} eager traces, got {}",
5257                execution.outputs.len(),
5258                recorded.traces.len()
5259            )));
5260        }
5261
5262        recorded
5263            .traces
5264            .into_iter()
5265            .zip(recorded.semantic_values)
5266            .zip(execution.outputs)
5267            .map(|((trace, semantic), output)| {
5268                Self::new_result_with_semantic(
5269                    Arc::clone(&ctx),
5270                    trace.key,
5271                    output,
5272                    trace.requires_grad,
5273                    trace.trace,
5274                    semantic,
5275                )
5276            })
5277            .collect()
5278    }
5279
5280    fn backward_from_seed(
5281        &self,
5282        engine: &mut dyn ExecutionEngine,
5283        seed: Tensor,
5284    ) -> Result<Gradients> {
5285        let cotangent =
5286            EagerTensor::new_result(Arc::clone(&self.ctx), eager_val_key(), seed, false, None)?;
5287        let reachable_leaves = self
5288            .semantic
5289            .as_ref()
5290            .map(crate::eager::semantic::reachable_leaf_nodes)
5291            .unwrap_or_default();
5292        let candidate_keys = {
5293            let mut slots = self.ctx.lock_grad_slots()?;
5294            let mut keys = Vec::new();
5295            slots.retain(|key, slot| {
5296                if slot.upgrade().is_some() {
5297                    keys.push(key.clone());
5298                    true
5299                } else {
5300                    false
5301                }
5302            });
5303            keys
5304        };
5305
5306        let mut targets = Vec::new();
5307        for key in candidate_keys {
5308            let Some(record) = self.ctx.value_record(&key)? else {
5309                continue;
5310            };
5311            if !record.requires_grad {
5312                continue;
5313            }
5314            // Intermediate and unrelated values also have slots; only request
5315            // reachable leaves.
5316            let Some(leaf_id) = record
5317                .semantic
5318                .as_ref()
5319                .filter(|semantic| semantic.is_leaf())
5320                .map(SemanticValue::node_id)
5321            else {
5322                continue;
5323            };
5324            if !reachable_leaves.contains(&leaf_id) {
5325                continue;
5326            }
5327            targets.push((key, EagerTensor::from_record(record)));
5328        }
5329        let wrts = targets.iter().map(|(_, wrt)| wrt).collect::<Vec<_>>();
5330        let gradients = semantic_eager_vjp_many(&self.ctx, engine, self, &wrts, &cotangent)?;
5331        let cotangents = (|| {
5332            let session: &mut dyn Engine = &mut *engine;
5333            let mut cotangents = HashMap::new();
5334            for ((key, _), grad) in targets.into_iter().zip(gradients) {
5335                let grad = grad.ok_or_else(|| {
5336                    Error::invalid_argument(
5337                        "backward",
5338                        ErrorPhase::GraphBuild,
5339                        "wrt",
5340                        format!(
5341                            "no cotangent flow for reachable tracked leaf {key:?}; use EagerSession::vjp_optional to observe absent differentiation"
5342                        ),
5343                    )
5344                })?;
5345                let tensor = match grad.into_value() {
5346                    Ok(tensor) => tensor,
5347                    Err(IntoValueError::NotUnique(handle)) => {
5348                        handle.duplicate_value_in_session(session)?
5349                    }
5350                    // A gradient whose retained layout is a view (for example a
5351                    // transpose) cannot be extracted as an owned tensor; copy
5352                    // it to a compact tensor instead.
5353                    Err(IntoValueError::Extract { value, .. }) => {
5354                        value.duplicate_value_in_session(session)?
5355                    }
5356                };
5357                cotangents.insert(key, tensor);
5358            }
5359            self.ctx.store_grads(&cotangents, session)?;
5360            Ok::<_, Error>(cotangents)
5361        })()?;
5362        Gradients::from_tensors(cotangents)
5363    }
5364}
5365
5366/// Insert a weak registry entry, first dropping dead entries when the insert
5367/// would otherwise grow the table.
5368///
5369/// Dead entries are otherwise removed only when their own key is looked up, so
5370/// a long-running runtime would keep one entry per value it ever created.
5371/// Pruning at the growth point keeps the cost amortized O(1) per insert: a
5372/// sweep runs at most once per capacity doubling.
5373fn insert_pruning_dead<K: std::hash::Hash + Eq, V>(
5374    map: &mut HashMap<K, Weak<V>>,
5375    key: K,
5376    value: Weak<V>,
5377) {
5378    if map.len() == map.capacity() {
5379        map.retain(|_, entry| entry.strong_count() > 0);
5380    }
5381    map.insert(key, value);
5382}
5383
5384#[cfg(test)]
5385impl EagerRuntime {
5386    /// Return how many semantic replays this runtime performed.
5387    pub(crate) fn semantic_replay_count(&self) -> usize {
5388        self.semantic_replays.load(Ordering::Relaxed)
5389    }
5390}
5391
5392pub(crate) fn eager_val_key() -> ValueKey<StdTensorOp> {
5393    ValueKey::Input(next_input_key())
5394}
5395
5396pub(crate) struct RecordedEagerTrace {
5397    pub(crate) key: ValueKey<StdTensorOp>,
5398    pub(crate) trace: Option<EagerTrace>,
5399    pub(crate) requires_grad: bool,
5400}
5401
5402pub(crate) struct RecordedEagerOutputs {
5403    pub(crate) traces: Vec<RecordedEagerTrace>,
5404    pub(crate) semantic_values: Vec<Option<SemanticValue>>,
5405}
5406
5407pub(crate) fn record_eager_outputs_in_session(
5408    op: &StdTensorOp,
5409    outputs: &[&Tensor],
5410    inputs: &[&EagerTensor],
5411    session: &mut dyn Engine,
5412) -> Result<RecordedEagerOutputs> {
5413    let metadata = outputs
5414        .iter()
5415        .map(|output| tensor_meta_from_tensor(output))
5416        .collect();
5417    record_eager_outputs_inner(op, metadata, inputs, Some(session))
5418}
5419
5420pub(crate) fn record_eager_value_outputs_in_session(
5421    op: &StdTensorOp,
5422    outputs: &[&TensorValue],
5423    inputs: &[&EagerTensor],
5424    session: &mut dyn Engine,
5425) -> Result<RecordedEagerOutputs> {
5426    let metadata = outputs
5427        .iter()
5428        .map(|output| tensor_meta_from_value(output))
5429        .collect();
5430    record_eager_outputs_inner(op, metadata, inputs, Some(session))
5431}
5432
5433fn record_eager_outputs_inner(
5434    op: &StdTensorOp,
5435    output_metadata: Vec<TensorMeta>,
5436    inputs: &[&EagerTensor],
5437    session: Option<&mut dyn Engine>,
5438) -> Result<RecordedEagerOutputs> {
5439    let semantic_values = record_semantic_eager_outputs(op, &output_metadata, inputs, session)?;
5440    record_eager_outputs_from_metadata(output_metadata, semantic_values, inputs)
5441}
5442
5443fn record_semantic_eager_outputs(
5444    op: &StdTensorOp,
5445    output_metadata: &[TensorMeta],
5446    inputs: &[&EagerTensor],
5447    mut session: Option<&mut dyn Engine>,
5448) -> Result<Vec<Option<SemanticValue>>> {
5449    // Materialize a constant semantic leaf for any untracked input that lost its
5450    // implicit semantic value on the active-edge fast path. This keeps
5451    // "untracked constant feeds tracked AD" working (PyTorch-style: untracked
5452    // = constant leaf, no gradient flows to it) without re-recording every
5453    // untracked op at creation time.
5454    let mut owned_constants = Vec::<SemanticValue>::new();
5455    for input in inputs {
5456        if input.semantic.is_none() {
5457            let value = match session.as_deref_mut() {
5458                Some(session) => input.duplicate_value_in_session(session)?,
5459                None => input.duplicate_host_value().ok_or_else(|| {
5460                    Error::unsupported(
5461                        "record_semantic_eager_outputs",
5462                        ErrorPhase::Execution,
5463                        "a non-host untracked input needs an engine to become a constant leaf",
5464                    )
5465                })?,
5466            };
5467            let data = Arc::new(RetainedValue::from_tensor(value));
5468            owned_constants.push(SemanticValue::leaf(
5469                next_input_key(),
5470                data.dtype(),
5471                data.shape().len(),
5472                data,
5473            ));
5474        }
5475    }
5476    let mut constants = owned_constants.into_iter();
5477    let semantic_inputs: Vec<SemanticValue> = inputs
5478        .iter()
5479        .map(|input| {
5480            input
5481                .semantic
5482                .clone()
5483                .unwrap_or_else(|| constants.next().expect("materialized constant"))
5484        })
5485        .collect();
5486    let promotion_plan =
5487        eager_input_promotion_plan(op, inputs.len(), |index| inputs[index].dtype());
5488    // Mirror eager execution in the record only. The concrete tensors have
5489    // already been promoted at the execution boundary, so these casts add
5490    // semantic nodes without an eager copy or backend kernel.
5491    let semantic_inputs: Vec<SemanticValue> = semantic_inputs
5492        .into_iter()
5493        .enumerate()
5494        .map(|(index, semantic)| {
5495            let from = inputs[index].dtype();
5496            let target = promotion_plan.target_dtype(index, from);
5497            if from == target {
5498                semantic
5499            } else {
5500                let concrete = semantic.is_concrete_shape();
5501                SemanticValue::op_with_concreteness(
5502                    StdTensorOp::Convert { from, to: target },
5503                    vec![semantic].into_boxed_slice(),
5504                    1,
5505                    concrete,
5506                )
5507            }
5508        })
5509        .collect();
5510    // `Concatenate` needs runtime-extent inputs: its recorded inputs carry
5511    // symbolic extents, so the semantic value is exactified to the concrete
5512    // eager shape unless it is already concretely shaped.
5513    let semantic_inputs: Vec<SemanticValue> = if matches!(op, StdTensorOp::Concatenate { .. }) {
5514        semantic_inputs
5515            .into_iter()
5516            .zip(inputs)
5517            .map(|(semantic, input)| {
5518                if semantic.is_concrete_shape() {
5519                    semantic
5520                } else {
5521                    let to_shape: Vec<DimExpr> = input
5522                        .shape()
5523                        .iter()
5524                        .map(|&size| DimExpr::Const(size))
5525                        .collect();
5526                    SemanticValue::op_with_concreteness(
5527                        StdTensorOp::Reshape { to_shape },
5528                        vec![semantic].into_boxed_slice(),
5529                        1,
5530                        true,
5531                    )
5532                }
5533            })
5534            .collect()
5535    } else {
5536        semantic_inputs
5537    };
5538    let output_count = output_metadata.len();
5539    let node = SemanticValue::op(op.clone(), semantic_inputs.into_boxed_slice(), output_count);
5540    Ok((0..output_count)
5541        .map(|index| Some(node.at_output(index as u8)))
5542        .collect())
5543}
5544
5545#[cfg(test)]
5546fn record_eager_graph_outputs(
5547    graph: &Graph<StdTensorOp>,
5548    graph_input_keys: &[TensorInputKey],
5549    outputs: &[Tensor],
5550    inputs: &[&EagerTensor],
5551) -> Result<RecordedEagerOutputs> {
5552    let semantic_values = record_semantic_eager_graph_outputs(graph, graph_input_keys, inputs)?;
5553    let output_metadata = outputs.iter().map(tensor_meta_from_tensor);
5554    record_eager_outputs_from_metadata(output_metadata, semantic_values, inputs)
5555}
5556
5557#[cfg(test)]
5558fn record_semantic_eager_graph_outputs(
5559    graph: &Graph<StdTensorOp>,
5560    graph_input_keys: &[TensorInputKey],
5561    inputs: &[&EagerTensor],
5562) -> Result<Vec<Option<SemanticValue>>> {
5563    let Some(semantic_inputs) = inputs
5564        .iter()
5565        .map(|input| input.semantic.as_ref())
5566        .collect::<Option<Vec<_>>>()
5567    else {
5568        return Ok(vec![None; graph.outputs().len()]);
5569    };
5570    if graph_input_keys.len() != semantic_inputs.len() {
5571        return Err(Error::Internal(format!(
5572            "semantic graph recording expected {} input keys, got {}",
5573            semantic_inputs.len(),
5574            graph_input_keys.len()
5575        )));
5576    }
5577
5578    let mut values: HashMap<ValueKey<StdTensorOp>, SemanticValue> = HashMap::new();
5579    for (key, semantic) in graph_input_keys.iter().zip(semantic_inputs) {
5580        values.insert(ValueKey::Input(key.clone()), semantic.clone());
5581    }
5582
5583    for op_node in graph.operations() {
5584        let input_values = op_node
5585            .inputs
5586            .iter()
5587            .map(|input| {
5588                let key = match input {
5589                    ValueRef::Local(local_id) => &graph.values()[*local_id].key,
5590                    ValueRef::External(key) => key,
5591                };
5592                values.get(key).cloned().ok_or_else(|| {
5593                    Error::Internal(format!(
5594                        "semantic graph recording missing value for {key:?}"
5595                    ))
5596                })
5597            })
5598            .collect::<Result<Vec<_>>>()?;
5599        let node = SemanticValue::op(
5600            op_node.operation.clone(),
5601            input_values.into_boxed_slice(),
5602            op_node.outputs.len(),
5603        );
5604        for (index, output_id) in op_node.outputs.iter().copied().enumerate() {
5605            values.insert(
5606                graph.values()[output_id].key.clone(),
5607                node.at_output(index as u8),
5608            );
5609        }
5610    }
5611
5612    graph
5613        .outputs()
5614        .iter()
5615        .map(|&output_id| {
5616            let key = &graph.values()[output_id].key;
5617            values.get(key).cloned().map(Some).ok_or_else(|| {
5618                Error::Internal(format!(
5619                    "semantic graph recording missing output for {key:?}"
5620                ))
5621            })
5622        })
5623        .collect()
5624}
5625
5626fn record_eager_outputs_from_metadata(
5627    output_metadata: impl IntoIterator<Item = TensorMeta>,
5628    semantic_values: Vec<Option<SemanticValue>>,
5629    inputs: &[&EagerTensor],
5630) -> Result<RecordedEagerOutputs> {
5631    let output_metadata = output_metadata.into_iter().collect::<Vec<_>>();
5632    if semantic_values.len() != output_metadata.len() {
5633        return Err(Error::Internal(format!(
5634            "eager recording expected {} semantic traces, got {}",
5635            output_metadata.len(),
5636            semantic_values.len()
5637        )));
5638    }
5639    let requires_grad =
5640        eager_grad_recording_enabled() && inputs.iter().any(|input| input.requires_grad);
5641    let trace_count = output_metadata.len();
5642    let residual_trace = EagerTrace::new(inputs);
5643    let traces = (0..trace_count)
5644        .map(|_| RecordedEagerTrace {
5645            key: eager_val_key(),
5646            trace: Some(residual_trace.clone()),
5647            requires_grad,
5648        })
5649        .collect();
5650
5651    Ok(RecordedEagerOutputs {
5652        traces,
5653        semantic_values,
5654    })
5655}
5656
5657fn tensor_meta_from_value(value: &TensorValue) -> TensorMeta {
5658    TensorMeta::exact(
5659        value.dtype(),
5660        value.shape().iter().copied().map(SymDim::from).collect(),
5661    )
5662}
5663
5664#[cfg(test)]
5665pub(crate) fn zero_like_tensor(input: &Tensor, backend: &mut dyn Engine) -> Result<Tensor> {
5666    let host = match input.dtype() {
5667        // A caller-owned payload has no zero-like runtime tensor.
5668        DType::External(type_id) => {
5669            return Err(Error::unsupported(
5670                "zero_like_tensor",
5671                ErrorPhase::GraphBuild,
5672                format!(
5673                    "an externally defined payload ({:?}) has no zero-like runtime tensor",
5674                    DType::External(type_id)
5675                ),
5676            ));
5677        }
5678        DType::F32 => Tensor::from_typed::<f32>(TypedTensor::zeros(input.shape().to_vec())?),
5679        DType::F64 => Tensor::from_typed::<f64>(TypedTensor::zeros(input.shape().to_vec())?),
5680        DType::I32 => Tensor::from_typed::<i32>(TypedTensor::zeros(input.shape().to_vec())?),
5681        DType::I64 => Tensor::from_typed::<i64>(TypedTensor::zeros(input.shape().to_vec())?),
5682        DType::Bool => Tensor::from_typed::<bool>(TypedTensor::from_vec_col_major(
5683            input.shape().to_vec(),
5684            vec![false; input.shape().iter().product()],
5685        )?),
5686        DType::C32 => Tensor::from_typed::<tenferro_tensor::Complex32>(TypedTensor::zeros(
5687            input.shape().to_vec(),
5688        )?),
5689        DType::C64 => Tensor::from_typed::<tenferro_tensor::Complex64>(TypedTensor::zeros(
5690            input.shape().to_vec(),
5691        )?),
5692    };
5693    backend
5694        .upload_host_tensor(TensorRead::from_tensor(&host))
5695        .map_err(Error::from)
5696}
5697
5698pub(crate) fn one_like_tensor(input: &Tensor, session: &mut dyn Engine) -> Result<Tensor> {
5699    let host = ones_tensor(input.dtype(), input.shape().to_vec())?;
5700    session
5701        .upload_host_tensor(TensorRead::from_tensor(&host))
5702        .map_err(Error::from)
5703}
5704
5705#[cfg(test)]
5706mod tests;