Skip to main content

tenferro_ops/ad/
context.rs

1//! AD context for guard-based shape resolution and value metadata queries.
2//!
3//! During AD graph construction, linalg rules such as SVD, QR, and LU need
4//! concrete matrix dimensions to choose between structurally different
5//! subgraphs. `ShapeGuardContext` records those dimension comparisons as guards
6//! so cached AD graphs can later be invalidated when the observed shape
7//! relationship changes.
8
9use std::cmp::Ordering;
10use std::collections::HashMap;
11use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
12use std::sync::{Mutex, OnceLock};
13
14use computegraph::graph::Graph;
15use computegraph::types::{ValueKey, ValueRef};
16use tenferro_tensor::DType;
17
18#[cfg(feature = "autodiff")]
19use crate::ad::{ADRuleError, ADRuleKind};
20use crate::dim_expr::{DimExpr, DimExprEvalError};
21use crate::shape_extent::ShapeExtent;
22use crate::std_tensor_op::StdTensorOp;
23use crate::sym_dim::SymDim;
24
25type MetadataMap = HashMap<ValueKey<StdTensorOp>, TensorMeta>;
26
27type GlobalMetadataMap = HashMap<ValueKey<StdTensorOp>, GlobalMetadataEntry>;
28
29#[derive(Clone, Debug)]
30struct GlobalMetadataEntry {
31    stack: Vec<GlobalMetadataRegistration>,
32}
33
34#[derive(Clone, Debug)]
35struct GlobalMetadataRegistration {
36    token: u64,
37    meta: TensorMeta,
38}
39
40#[derive(Clone, Debug)]
41struct ScopedGlobalMetadataRegistration {
42    key: ValueKey<StdTensorOp>,
43    token: u64,
44}
45
46/// Error returned when the process-global AD metadata registry is unavailable.
47#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
48pub enum MetadataRegistryError {
49    /// A previous panic poisoned the global metadata mutex.
50    #[error("AD global metadata registry lock poisoned")]
51    LockPoisoned,
52}
53
54/// Error returned when shape-guard metadata cannot be resolved.
55///
56/// # Examples
57///
58/// ```
59/// use tenferro_ops::ShapeGuardError;
60///
61/// let error = ShapeGuardError::LocalWithoutAttachedGraph { local_id: 0 };
62/// assert!(error.to_string().contains("attached graph"));
63/// ```
64#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
65pub enum ShapeGuardError {
66    /// A local graph value was queried before a graph was attached.
67    #[error("cannot resolve local value {local_id} without an attached graph")]
68    LocalWithoutAttachedGraph {
69        /// Graph-local value id.
70        local_id: usize,
71    },
72    /// A local graph value id is outside the attached graph's value table.
73    #[error("local value {local_id} is out of bounds for the attached graph")]
74    LocalOutOfBounds {
75        /// Graph-local value id.
76        local_id: usize,
77    },
78    /// No metadata was registered for the resolved value key.
79    #[error("missing TensorMeta for {key:?}")]
80    MissingMetadata {
81        /// Resolved value key.
82        key: ValueKey<StdTensorOp>,
83    },
84    /// Metadata exists, but at least one axis is only bounded or unknown.
85    #[error("TensorMeta for {key:?} does not have an exact shape; query extents instead")]
86    NonExactShape {
87        /// Resolved value key.
88        key: ValueKey<StdTensorOp>,
89    },
90}
91
92/// Result type used by shape-guard metadata queries.
93///
94/// The error side preserves a [`ShapeGuardFailure`] wrapper so the original
95/// [`ShapeGuardError`] stays available through `typed_source()`.
96///
97/// # Examples
98///
99/// ```
100/// use tenferro_ops::ShapeGuardResult;
101///
102/// let result: ShapeGuardResult<()> = Ok(());
103/// assert!(result.is_ok());
104/// ```
105pub type ShapeGuardResult<T> = Result<T, ShapeGuardFailure>;
106
107#[cfg(feature = "autodiff")]
108impl From<ShapeGuardFailure> for ADRuleError {
109    fn from(err: ShapeGuardFailure) -> Self {
110        ADRuleError::invalid_input(
111            "tenferro.shape_guard",
112            ADRuleKind::Jvp,
113            err.typed_source().to_string(),
114        )
115    }
116}
117
118/// Error returned by a shape-guard metadata query.
119///
120/// The public [`ShapeGuardError`] remains the typed source.
121///
122/// # Examples
123///
124/// ```
125/// use computegraph::types::{ValueKey, ValueRef};
126/// use tenferro_ops::input_key::TensorInputKey;
127/// use tenferro_ops::std_tensor_op::StdTensorOp;
128/// use tenferro_ops::{ShapeGuardContext, ShapeGuardError};
129///
130/// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 8 });
131/// let value = ValueRef::External(key);
132/// let mut ctx = ShapeGuardContext::default();
133/// let failure = ctx.shape_of(&value).unwrap_err();
134/// assert!(matches!(
135///     failure.typed_source(),
136///     ShapeGuardError::MissingMetadata { .. }
137/// ));
138/// ```
139#[derive(Clone, Debug)]
140pub struct ShapeGuardFailure {
141    source: ShapeGuardError,
142}
143
144impl ShapeGuardFailure {
145    fn new(source: ShapeGuardError) -> Self {
146        Self { source }
147    }
148
149    /// Return the original typed shape-guard failure.
150    pub fn typed_source(&self) -> &ShapeGuardError {
151        &self.source
152    }
153
154    /// Consume this boundary error and return its original typed failure.
155    pub fn into_typed_source(self) -> ShapeGuardError {
156        self.source
157    }
158}
159
160impl std::fmt::Display for ShapeGuardFailure {
161    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
162        self.source.fmt(f)
163    }
164}
165
166impl std::error::Error for ShapeGuardFailure {
167    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
168        Some(&self.source)
169    }
170}
171
172impl PartialEq for ShapeGuardFailure {
173    fn eq(&self, other: &Self) -> bool {
174        self.source == other.source
175    }
176}
177
178impl Eq for ShapeGuardFailure {}
179
180/// Global metadata registry.
181///
182/// Stored as a tokenized stack per value key: duplicate scoped registrations
183/// shadow older metadata while they are live, and dropping scopes in any order
184/// removes only the matching token. `ShapeGuardContext::metadata_of` reaches into
185/// the registry lazily via [`lookup_global_metadata`] and caches the result into
186/// the context's local map.
187///
188/// Earlier designs either cloned the whole map up-front into each AD
189/// `ShapeGuardContext` or kept the map in an `Arc` and cloned on every write.
190/// Both variants were quadratic across the monotonically growing registry and
191/// dominated oracle_replay runtime.
192static GLOBAL_METADATA: OnceLock<Mutex<GlobalMetadataMap>> = OnceLock::new();
193static NEXT_GLOBAL_METADATA_TOKEN: AtomicU64 = AtomicU64::new(0);
194
195fn global_metadata_registry() -> &'static Mutex<GlobalMetadataMap> {
196    GLOBAL_METADATA.get_or_init(|| Mutex::new(HashMap::new()))
197}
198
199/// Lifetime token for graph-scoped global metadata.
200///
201/// Dropping the last frontend owner of a traced graph drops this scope and
202/// releases the metadata keys that were registered for that graph graph.
203#[doc(hidden)]
204#[derive(Debug)]
205pub struct GlobalMetadataScope {
206    registrations: Vec<ScopedGlobalMetadataRegistration>,
207}
208
209impl Drop for GlobalMetadataScope {
210    fn drop(&mut self) {
211        release_scoped_global_metadata(&self.registrations);
212    }
213}
214
215/// Per-value tensor metadata used by AD rules.
216///
217/// Shape information is stored as per-axis [`ShapeExtent`] values. Callers must
218/// explicitly choose whether they need an exact shape or only a known bound.
219///
220/// # Examples
221///
222/// ```
223/// use tenferro_ops::{SymDim, TensorMeta};
224/// use tenferro_tensor::DType;
225///
226/// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(2usize), SymDim::from(3usize)]);
227/// assert_eq!(meta.rank(), 2);
228/// ```
229#[derive(Clone, Debug, PartialEq, Eq)]
230pub struct TensorMeta {
231    /// Element dtype of the tensor value.
232    pub dtype: DType,
233    /// Per-axis shape guarantees.
234    pub extents: Vec<ShapeExtent<SymDim>>,
235    /// Canonical identity of an externally defined scalar, when the value carries one.
236    ///
237    /// A semantic program's identity must be reproducible across processes, while an
238    /// externally defined scalar's tag is a process-local `TypeId`, so a traced value
239    /// whose dtype is external declares the stable name here.
240    pub scalar_identity: Option<&'static str>,
241}
242
243impl TensorMeta {
244    /// Construct metadata whose every axis is exact.
245    ///
246    /// # Examples
247    ///
248    /// ```
249    /// use tenferro_ops::{SymDim, TensorMeta};
250    /// use tenferro_tensor::DType;
251    ///
252    /// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]);
253    /// assert_eq!(meta.exact_shape(), Some(vec![SymDim::from(4usize)]));
254    /// ```
255    pub fn exact(dtype: DType, shape: Vec<SymDim>) -> Self {
256        let extents = shape.iter().cloned().map(ShapeExtent::exact).collect();
257        Self {
258            dtype,
259            extents,
260            scalar_identity: None,
261        }
262    }
263
264    /// Construct metadata from per-axis extents.
265    ///
266    /// # Examples
267    ///
268    /// ```
269    /// use tenferro_ops::{ShapeExtent, SymDim, TensorMeta};
270    /// use tenferro_tensor::DType;
271    ///
272    /// let meta = TensorMeta::with_extents(
273    ///     DType::F64,
274    ///     vec![ShapeExtent::upper_bound(SymDim::from(8usize))],
275    /// );
276    /// assert_eq!(meta.exact_shape(), None);
277    /// ```
278    pub fn with_extents(dtype: DType, extents: Vec<ShapeExtent<SymDim>>) -> Self {
279        Self {
280            dtype,
281            extents,
282            scalar_identity: None,
283        }
284    }
285
286    /// Declare the canonical identity of an externally defined scalar.
287    ///
288    /// # Examples
289    ///
290    /// ```rust
291    /// use tenferro_ops::{SymDim, TensorMeta};
292    /// use tenferro_tensor::DType;
293    ///
294    /// let dtype = DType::External(std::any::TypeId::of::<f64>());
295    /// let meta = TensorMeta::exact(dtype, vec![SymDim::from(2usize)])
296    ///     .with_scalar_identity("example.scalar.v1");
297    /// assert_eq!(meta.scalar_identity(), Some("example.scalar.v1"));
298    /// ```
299    #[must_use]
300    pub fn with_scalar_identity(mut self, identity: &'static str) -> Self {
301        self.scalar_identity = Some(identity);
302        self
303    }
304
305    /// Return the declared identity of an externally defined scalar, if any.
306    ///
307    /// # Examples
308    ///
309    /// ```rust
310    /// use tenferro_ops::{SymDim, TensorMeta};
311    /// use tenferro_tensor::DType;
312    ///
313    /// let dtype = DType::External(std::any::TypeId::of::<f64>());
314    /// assert_eq!(TensorMeta::exact(dtype, vec![SymDim::from(1usize)]).scalar_identity(), None);
315    /// assert_eq!(
316    ///     TensorMeta::exact(dtype, vec![SymDim::from(1usize)])
317    ///         .with_scalar_identity("example.scalar.v1")
318    ///         .scalar_identity(),
319    ///     Some("example.scalar.v1")
320    /// );
321    /// ```
322    #[must_use]
323    pub const fn scalar_identity(&self) -> Option<&'static str> {
324        self.scalar_identity
325    }
326
327    /// Return the tensor rank known by this metadata record.
328    pub fn rank(&self) -> usize {
329        self.extents.len()
330    }
331
332    /// Return the per-axis shape guarantees.
333    ///
334    /// # Examples
335    ///
336    /// ```
337    /// use tenferro_ops::{SymDim, TensorMeta};
338    /// use tenferro_tensor::DType;
339    ///
340    /// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]);
341    /// assert_eq!(meta.extents().len(), 1);
342    /// ```
343    pub fn extents(&self) -> &[ShapeExtent<SymDim>] {
344        &self.extents
345    }
346
347    /// Return the shape only when every axis is exact.
348    ///
349    /// # Examples
350    ///
351    /// ```
352    /// use tenferro_ops::{ShapeExtent, SymDim, TensorMeta};
353    /// use tenferro_tensor::DType;
354    ///
355    /// let meta = TensorMeta::with_extents(
356    ///     DType::F64,
357    ///     vec![ShapeExtent::upper_bound(SymDim::from(8usize))],
358    /// );
359    /// assert_eq!(meta.exact_shape(), None);
360    /// ```
361    pub fn exact_shape(&self) -> Option<Vec<SymDim>> {
362        self.extents
363            .iter()
364            .map(|extent| extent.as_exact().cloned())
365            .collect()
366    }
367
368    /// Return one known bound per axis when every axis has a bound.
369    ///
370    /// This is intentionally separate from [`TensorMeta::exact_shape`]: a bound
371    /// is not proof of the runtime size.
372    pub fn bound_shape(&self) -> Option<Vec<SymDim>> {
373        self.extents
374            .iter()
375            .map(|extent| extent.bound_expr().cloned())
376            .collect()
377    }
378}
379
380/// A recorded dimension comparison made during AD graph construction.
381///
382/// # Examples
383///
384/// ```
385/// use std::cmp::Ordering;
386/// use tenferro_ops::ShapeGuard;
387///
388/// let guard = ShapeGuard {
389///     dim_a: 5,
390///     dim_b: 3,
391///     ordering: Ordering::Greater,
392/// };
393///
394/// assert_eq!(guard.ordering, Ordering::Greater);
395/// ```
396#[derive(Clone, Debug, PartialEq, Eq)]
397pub struct ShapeGuard {
398    /// First dimension value, such as `m`.
399    pub dim_a: usize,
400    /// Second dimension value, such as `n`.
401    pub dim_b: usize,
402    /// The observed ordering `dim_a.cmp(&dim_b)`.
403    pub ordering: Ordering,
404}
405
406/// AD context providing dimension resolution, guard recording, and value metadata.
407///
408/// # Examples
409///
410/// ```
411/// use tenferro_ops::ShapeGuardContext;
412///
413/// let ctx = ShapeGuardContext::default();
414/// assert!(ctx.guards().is_empty());
415/// ```
416#[derive(Clone, Debug, Default)]
417pub struct ShapeGuardContext {
418    guards: Vec<ShapeGuard>,
419    metadata: MetadataMap,
420    shape_sources: HashMap<u64, ValueKey<StdTensorOp>>,
421    use_global_registry: bool,
422    local_keys: Option<Vec<ValueKey<StdTensorOp>>>,
423    #[cfg(feature = "autodiff")]
424    active_value_keys: Option<std::sync::Arc<std::collections::HashSet<ValueKey<StdTensorOp>>>>,
425}
426
427impl ShapeGuardContext {
428    /// Create a context backed by the global metadata registry.
429    ///
430    /// Instead of cloning the entire global registry up-front (which used
431    /// to be O(N) per AD pass and quadratic across oracle_replay), the
432    /// context keeps a flag and lazily fetches entries from the shared
433    /// [`lookup_global_metadata`] on first miss, caching into its local
434    /// `metadata` map for subsequent reads within the same pass.
435    ///
436    /// # Examples
437    ///
438    /// ```
439    /// let ctx = tenferro_ops::ShapeGuardContext::with_global_metadata();
440    /// assert!(ctx.guards().is_empty());
441    /// ```
442    pub fn with_global_metadata() -> Self {
443        Self {
444            use_global_registry: true,
445            ..Self::default()
446        }
447    }
448
449    #[doc(hidden)]
450    pub fn insert_shape_source(&mut self, tensor_id: u64, key: ValueKey<StdTensorOp>) {
451        self.shape_sources.entry(tensor_id).or_insert(key);
452    }
453
454    #[doc(hidden)]
455    pub fn shape_source(&self, tensor_id: u64) -> Option<&ValueKey<StdTensorOp>> {
456        self.shape_sources.get(&tensor_id)
457    }
458
459    #[cfg(feature = "autodiff")]
460    pub fn with_linearize_active_values(
461        mut self,
462        keys: std::sync::Arc<std::collections::HashSet<ValueKey<StdTensorOp>>>,
463    ) -> Self {
464        self.active_value_keys = Some(keys);
465        self
466    }
467
468    /// Whether a primal value lies on a path from the current linearize targets.
469    ///
470    /// When no active set was attached, every value is treated as active so
471    /// existing callers keep the conservative full JVP graphs.
472    #[cfg(feature = "autodiff")]
473    pub fn is_value_active_in_linearize(&self, key: &ValueKey<StdTensorOp>) -> bool {
474        self.active_value_keys
475            .as_ref()
476            .is_none_or(|set| set.contains(key))
477    }
478
479    /// Returns the guards recorded so far.
480    ///
481    /// # Examples
482    ///
483    /// ```
484    /// use tenferro_ops::ShapeGuardContext;
485    ///
486    /// let ctx = ShapeGuardContext::default();
487    /// assert_eq!(ctx.guards(), &[]);
488    /// ```
489    pub fn guards(&self) -> &[ShapeGuard] {
490        &self.guards
491    }
492
493    /// Clears all recorded guards.
494    ///
495    /// # Examples
496    ///
497    /// ```
498    /// use tenferro_ops::ShapeGuardContext;
499    ///
500    /// let mut ctx = ShapeGuardContext::default();
501    /// ctx.clear_guards();
502    /// assert!(ctx.guards().is_empty());
503    /// ```
504    pub fn clear_guards(&mut self) {
505        self.guards.clear();
506    }
507
508    /// Return the shape metadata for a value reference.
509    ///
510    /// # Examples
511    ///
512    /// ```
513    /// use computegraph::types::{ValueKey, ValueRef};
514    /// use tenferro_ops::input_key::TensorInputKey;
515    /// use tenferro_ops::std_tensor_op::StdTensorOp;
516    /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
517    /// use tenferro_tensor::DType;
518    ///
519    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
520    /// let value = ValueRef::External(key.clone());
521    /// let mut ctx = ShapeGuardContext::default();
522    /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
523    ///
524    /// let shape = ctx.shape_of(&value).unwrap();
525    /// assert_eq!(shape, &[SymDim::from(4usize)]);
526    /// ```
527    ///
528    /// # Errors
529    ///
530    /// Returns [`ShapeGuardError`] when the value cannot be resolved, metadata
531    /// is missing, or the metadata does not describe an exact shape.
532    pub fn shape_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<Vec<SymDim>> {
533        let key = self.resolve_key(val)?.clone();
534        self.ensure_metadata_loaded(&key);
535        let meta = self.metadata.get(&key).ok_or_else(|| {
536            self.shape_guard_failure(ShapeGuardError::MissingMetadata { key: key.clone() })
537        })?;
538        meta.exact_shape()
539            .ok_or_else(|| self.shape_guard_failure(ShapeGuardError::NonExactShape { key }))
540    }
541
542    /// Return the rank for a value reference without requiring exact extents.
543    ///
544    /// Use this when an AD rule only needs axis count or needs to build
545    /// runtime-shape references. Calling [`ShapeGuardContext::shape_of`] in those
546    /// cases would reject valid values such as `DynamicTruncate` outputs whose
547    /// runtime extent is known only as an upper bound.
548    ///
549    /// # Examples
550    ///
551    /// ```
552    /// use computegraph::types::{ValueKey, ValueRef};
553    /// use tenferro_ops::input_key::TensorInputKey;
554    /// use tenferro_ops::std_tensor_op::StdTensorOp;
555    /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
556    /// use tenferro_tensor::DType;
557    ///
558    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
559    /// let value = ValueRef::External(key.clone());
560    /// let mut ctx = ShapeGuardContext::default();
561    /// ctx.insert_metadata(
562    ///     key,
563    ///     TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
564    /// );
565    ///
566    /// assert_eq!(ctx.rank_of(&value).unwrap(), 1);
567    /// ```
568    ///
569    /// # Errors
570    ///
571    /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
572    /// metadata is unavailable.
573    pub fn rank_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<usize> {
574        self.metadata_of(val).map(TensorMeta::rank)
575    }
576
577    /// Return per-axis shape guarantees for a value reference.
578    ///
579    /// # Examples
580    ///
581    /// ```
582    /// use computegraph::types::{ValueKey, ValueRef};
583    /// use tenferro_ops::input_key::TensorInputKey;
584    /// use tenferro_ops::std_tensor_op::StdTensorOp;
585    /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
586    /// use tenferro_tensor::DType;
587    ///
588    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
589    /// let value = ValueRef::External(key.clone());
590    /// let mut ctx = ShapeGuardContext::default();
591    /// ctx.insert_metadata(
592    ///     key,
593    ///     TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
594    /// );
595    ///
596    /// let extents = ctx.extents_of(&value).unwrap();
597    /// assert_eq!(extents[0], ShapeExtent::upper_bound(SymDim::from(8usize)));
598    /// ```
599    ///
600    /// # Errors
601    ///
602    /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
603    /// metadata is unavailable.
604    pub fn extents_of(
605        &mut self,
606        val: &ValueRef<StdTensorOp>,
607    ) -> ShapeGuardResult<&[ShapeExtent<SymDim>]> {
608        self.metadata_of(val).map(TensorMeta::extents)
609    }
610
611    /// Return the exact shape for a value reference, if all axes are exact.
612    ///
613    /// # Examples
614    ///
615    /// ```
616    /// use computegraph::types::{ValueKey, ValueRef};
617    /// use tenferro_ops::input_key::TensorInputKey;
618    /// use tenferro_ops::std_tensor_op::StdTensorOp;
619    /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
620    /// use tenferro_tensor::DType;
621    ///
622    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
623    /// let value = ValueRef::External(key.clone());
624    /// let mut ctx = ShapeGuardContext::default();
625    /// ctx.insert_metadata(
626    ///     key,
627    ///     TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
628    /// );
629    ///
630    /// let maybe_shape = ctx.exact_shape_of(&value).unwrap();
631    /// assert_eq!(maybe_shape, None);
632    /// ```
633    ///
634    /// # Errors
635    ///
636    /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
637    /// metadata is unavailable.
638    pub fn exact_shape_of(
639        &mut self,
640        val: &ValueRef<StdTensorOp>,
641    ) -> ShapeGuardResult<Option<Vec<SymDim>>> {
642        self.metadata_of(val).map(TensorMeta::exact_shape)
643    }
644
645    #[doc(hidden)]
646    pub fn shape_if_available(&mut self, val: &ValueRef<StdTensorOp>) -> Option<Vec<SymDim>> {
647        self.metadata_if_available(val)
648            .and_then(TensorMeta::exact_shape)
649    }
650
651    /// Return the dtype metadata for a value reference.
652    ///
653    /// # Examples
654    ///
655    /// ```
656    /// use computegraph::types::{ValueKey, ValueRef};
657    /// use tenferro_ops::input_key::TensorInputKey;
658    /// use tenferro_ops::std_tensor_op::StdTensorOp;
659    /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
660    /// use tenferro_tensor::DType;
661    ///
662    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
663    /// let value = ValueRef::External(key.clone());
664    /// let mut ctx = ShapeGuardContext::default();
665    /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
666    ///
667    /// let dtype = ctx.dtype_of(&value).unwrap();
668    /// assert_eq!(dtype, DType::F64);
669    /// ```
670    ///
671    /// # Errors
672    ///
673    /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
674    /// metadata is unavailable.
675    pub fn dtype_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<DType> {
676        self.metadata_of(val).map(|meta| meta.dtype)
677    }
678
679    /// Return the complete metadata record for a value reference.
680    ///
681    /// # Examples
682    ///
683    /// ```
684    /// use computegraph::types::{ValueKey, ValueRef};
685    /// use tenferro_ops::input_key::TensorInputKey;
686    /// use tenferro_ops::std_tensor_op::StdTensorOp;
687    /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
688    /// use tenferro_tensor::DType;
689    ///
690    /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
691    /// let value = ValueRef::External(key.clone());
692    /// let mut ctx = ShapeGuardContext::default();
693    /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
694    ///
695    /// let meta = ctx.metadata_of(&value).unwrap();
696    /// assert_eq!(meta.dtype, DType::F64);
697    /// ```
698    ///
699    /// # Errors
700    ///
701    /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
702    /// metadata is unavailable.
703    pub fn metadata_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<&TensorMeta> {
704        let key = self.resolve_key(val)?.clone();
705        self.ensure_metadata_loaded(&key);
706        self.metadata
707            .get(&key)
708            .ok_or_else(|| self.shape_guard_failure(ShapeGuardError::MissingMetadata { key }))
709    }
710
711    #[doc(hidden)]
712    pub fn metadata_if_available(&mut self, val: &ValueRef<StdTensorOp>) -> Option<&TensorMeta> {
713        let key = self.resolve_key_if_available(val)?.clone();
714        self.ensure_metadata_loaded(&key);
715        self.metadata.get(&key)
716    }
717
718    #[doc(hidden)]
719    pub fn attach_graph(&mut self, graph: &Graph<StdTensorOp>) {
720        self.local_keys = Some(graph.values().iter().map(|node| node.key.clone()).collect());
721    }
722
723    #[doc(hidden)]
724    pub fn insert_metadata(&mut self, key: ValueKey<StdTensorOp>, meta: TensorMeta) {
725        self.metadata.insert(key, meta);
726    }
727
728    fn resolve_key_if_available<'a>(
729        &'a self,
730        val: &'a ValueRef<StdTensorOp>,
731    ) -> Option<&'a ValueKey<StdTensorOp>> {
732        match val {
733            ValueRef::External(key) => Some(key),
734            ValueRef::Local(local_id) => self
735                .local_keys
736                .as_ref()
737                .and_then(|keys| keys.get(*local_id)),
738        }
739    }
740
741    fn resolve_key<'a>(
742        &'a self,
743        val: &'a ValueRef<StdTensorOp>,
744    ) -> ShapeGuardResult<&'a ValueKey<StdTensorOp>> {
745        match val {
746            ValueRef::External(key) => Ok(key),
747            ValueRef::Local(local_id) if self.local_keys.is_none() => Err(self
748                .shape_guard_failure(ShapeGuardError::LocalWithoutAttachedGraph {
749                    local_id: *local_id,
750                })),
751            ValueRef::Local(local_id) => self
752                .local_keys
753                .as_ref()
754                .and_then(|keys| keys.get(*local_id))
755                .ok_or_else(|| {
756                    self.shape_guard_failure(ShapeGuardError::LocalOutOfBounds {
757                        local_id: *local_id,
758                    })
759                }),
760        }
761    }
762
763    fn shape_guard_failure(&self, source: ShapeGuardError) -> ShapeGuardFailure {
764        ShapeGuardFailure::new(source)
765    }
766
767    fn ensure_metadata_loaded(&mut self, key: &ValueKey<StdTensorOp>) {
768        if !self.metadata.contains_key(key) && self.use_global_registry {
769            if let Ok(Some(meta)) = lookup_global_metadata(key) {
770                self.metadata.insert(key.clone(), meta);
771            }
772        }
773    }
774}
775
776/// Look up a single metadata entry from the global registry.
777///
778/// Locks the registry briefly for a single `HashMap::get` + clone.
779///
780/// # Examples
781///
782/// ```
783/// use computegraph::types::ValueKey;
784/// use tenferro_ops::ad::context::lookup_global_metadata;
785/// use tenferro_ops::input_key::TensorInputKey;
786/// use tenferro_ops::std_tensor_op::StdTensorOp;
787///
788/// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 99 });
789/// let meta = lookup_global_metadata(&key).unwrap();
790/// assert!(meta.is_none());
791/// ```
792///
793/// # Errors
794///
795/// Returns [`MetadataRegistryError::LockPoisoned`] when the global metadata
796/// registry lock is poisoned.
797pub fn lookup_global_metadata(
798    key: &ValueKey<StdTensorOp>,
799) -> Result<Option<TensorMeta>, MetadataRegistryError> {
800    let guard = global_metadata_registry()
801        .lock()
802        .map_err(|_| MetadataRegistryError::LockPoisoned)?;
803    Ok(guard
804        .get(key)
805        .and_then(|entry| entry.stack.last())
806        .map(|registration| registration.meta.clone()))
807}
808
809#[doc(hidden)]
810///
811/// # Errors
812///
813/// Returns [`MetadataRegistryError::LockPoisoned`] when the global metadata
814/// registry lock is poisoned.
815pub fn register_scoped_global_metadata_batch<I>(
816    entries: I,
817) -> Result<GlobalMetadataScope, MetadataRegistryError>
818where
819    I: IntoIterator<Item = (ValueKey<StdTensorOp>, TensorMeta)>,
820{
821    let mut guard = global_metadata_registry()
822        .lock()
823        .map_err(|_| MetadataRegistryError::LockPoisoned)?;
824    let mut registrations = Vec::new();
825    for (key, meta) in entries {
826        let token = NEXT_GLOBAL_METADATA_TOKEN.fetch_add(1, AtomicOrdering::Relaxed);
827        let entry = guard
828            .entry(key.clone())
829            .or_insert_with(|| GlobalMetadataEntry { stack: Vec::new() });
830        entry.stack.push(GlobalMetadataRegistration { token, meta });
831        registrations.push(ScopedGlobalMetadataRegistration { key, token });
832    }
833    Ok(GlobalMetadataScope { registrations })
834}
835
836fn release_scoped_global_metadata(registrations: &[ScopedGlobalMetadataRegistration]) {
837    let Ok(mut guard) = global_metadata_registry().lock() else {
838        // Drop cannot return an error. Failing closed here avoids reading or
839        // mutating data from a poisoned registry at the cost of leaking entries
840        // until process exit.
841        return;
842    };
843    for registration in registrations {
844        let should_remove = if let Some(entry) = guard.get_mut(&registration.key) {
845            if let Some(position) = entry
846                .stack
847                .iter()
848                .rposition(|candidate| candidate.token == registration.token)
849            {
850                entry.stack.remove(position);
851            }
852            entry.stack.is_empty()
853        } else {
854            false
855        };
856        if should_remove {
857            guard.remove(&registration.key);
858        }
859    }
860}
861
862/// Resolve a [`DimExpr`] to a concrete `usize`.
863#[doc(hidden)]
864pub fn resolve_dim(dim: &DimExpr) -> Result<usize, DimExprEvalError> {
865    dim.eval(&[])
866}
867
868/// Resolve matrix dimensions and record their ordering as a guard.
869#[doc(hidden)]
870pub fn resolve_and_guard(
871    m: &DimExpr,
872    n: &DimExpr,
873    ctx: &mut ShapeGuardContext,
874) -> Result<(usize, usize), DimExprEvalError> {
875    let m_size = resolve_dim(m)?;
876    let n_size = resolve_dim(n)?;
877    ctx.guards.push(ShapeGuard {
878        dim_a: m_size,
879        dim_b: n_size,
880        ordering: m_size.cmp(&n_size),
881    });
882    Ok((m_size, n_size))
883}