eager AD

pub struct EagerRuntime {
    id: ContextId,
    /// Prepared-program runtime. Engine kinds are registered on first use;
    /// the runtime never stores an engine.
    runtime: Runtime,
    /// Serializes runtime reconfiguration (engine-kind registration and
    /// extension-module installation).
    extension_install_lock: Mutex<()>,
    semantic_extension_rules: SemanticExtensionRuleSet,
    grad_slots: Mutex<HashMap<ValueKey<StdTensorOp>, WeakGradSlot>>,
    value_records: Mutex<HashMap<ValueKey<StdTensorOp>, Weak<EagerTensorRecord>>>,
    ad_transform_cache: Arc<AdTransformCache>,
    /// S2: prepared derivative programs keyed by semantic structure, wrt input,
    /// and concrete bound input metadata. Avoids re-running freeze+AD
    /// transform+compile_frozen on warm structure hits.
    prepared_derivative_cache: Mutex<PreparedDerivativeCache>,
}

    pub fn with_eager_session<T, E: From<Error>>(
        self: &Arc<Self>,
        engine: &mut dyn ExecutionEngine,
        f: impl FnOnce(&mut EagerSession<'_>) -> std::result::Result<T, E>,
    ) -> std::result::Result<T, E> {
        self.ensure_engine(engine).map_err(E::from)?;
        f(&mut EagerSession {
            runtime: self,
            engine,
        })
    }

error[E0277]: `?` couldn't convert the error to `tenferro_runtime::Error`
   --> src/bin/semantic_ad.rs:88:56
    |
 88 |       let out = s.einsum(&[&a, &b, &c], "ij,jk,kl->il")?;
    |                   -------------------------------------^ the trait `From<tenferro_einsum::Error>` is not implemented for `tenferro_runtime::Error`
    |                   |
    |                   this can't be annotated with `?` because it has type `Result<_, tenferro_einsum::Error>`

mixing runtimes:              Err(ContextMismatch { lhs: ContextId(1), rhs: ContextId(2) })

        let any_requires_grad = profile_eager_op_section("nary_op.requires_grad_scan", || {
            eager_grad_recording_enabled()
                && (eager_capture_active() || tensors.iter().any(|tensor| tensor.requires_grad))
        });
        if !any_requires_grad {
            // ... 在借来的 engine 上执行，返回一个不带 trace 的结果
            return result;
        }

    let mask = match op {
        StdTensorOp::Extension(op) => {
            let rules = &first.ctx.semantic_extension_rules;
            if let Some(rule) = rules.lookup_primal_vjp(op.family_id()) {
                rule.residual_mask()
            } else if let Some(rule) = rules.lookup_linear_transpose(op.family_id()) {
                rule.residual_mask()
            } else {
                ResidualSpec::none()
            }
        }
        _ => crate::semantic_transform::eager_core_residual_spec(op),
    };
    // ... 对每个被声明的输入 / 输出：
        // Leaf values are already bound by the semantic source.
        if semantic.input_key().is_some() {
            continue;
        }
        saved.push(SavedValue {
            trace: semantic.clone(),
            value: Arc::clone(&tensor._record.value),
        });

== 1. leaves
x.tracks_grad=true c.tracks_grad=false  grad_slots_len=1 value_records_len=2
h.tracks_grad=true  after 3 ops: grad_slots_len=4 value_records_len=5

pub(crate) fn untracked_fast_path_allowed(tensors: &[&EagerTensor]) -> bool {
    !eager_grad_recording_enabled()
        || (!eager_capture_active() && !tensors.iter().any(|tensor| tensor.requires_grad))
}

gelu untracked=[-0.10021080190328704, -0.0841480581121794, 0.0, 0.6305156811332827]
gelu tracked  =[-0.10021080190328704, -0.0841480581121794, 0.0, 0.6305156811332827]
max diff=0.0e0

        let candidate_keys = {
            let mut slots = self.ctx.lock_grad_slots()?;
            let mut keys = Vec::new();
            slots.retain(|key, slot| {
                if slot.upgrade().is_some() {
                    keys.push(key.clone());
                    true
                } else {
                    false
                }
            });
            keys
        };
        // ... 每个候选键找回它的 EagerTensor
        let wrts = targets.iter().map(|(_, wrt)| wrt).collect::<Vec<_>>();
        let gradients = semantic_eager_vjp_many(&self.ctx, engine, self, &wrts, &cotangent)?;
        // ... 把每个 Some(grad) 取成张量放进 cotangents
            self.ctx.store_grads(&cotangents, session)?;

    let output_trace = analyze_deferred_semantic_trace(raw_output_trace)?;
    let saved = output
        .trace
        .as_ref()
        .map(EagerTrace::collect)
        .unwrap_or_default();
    let mut source_outputs = vec![&output_trace];
    source_outputs.extend(saved.iter().map(|value| &value.trace));

    // Residual roots keep the semantic producers available to differentiation;
    // only the execution-only derivative replaces their numerical values.
    let mut compiler = GraphCompiler::new();
    let source =
        tenferro_runtime::ad_support::compile_ad_source_many(&mut compiler, &source_outputs)?;

== 2. backward once
Gradients.len() = 1
x.grad    = Some([20.0, 80.0, 180.0])
c.grad    = None
h.grad    = None
loss.grad = None
cache: CacheStats { entries: 1, retained_bytes: 1474, hits: 0, misses: 1, evictions: 0, clears: 0 }

x.clear_grad()?;
let dx = rt.grad(&mut engine, &loss, &x)?;
// ...
let s = rt.variable_from(Tensor::from_vec_col_major(vec![], vec![2.5_f64])?)?;
let cube = rt.with_eager_session(&mut engine, |ss| {
  let sq = ss.mul(&s, &s)?;
  ss.mul(&sq, &s)
})?;
let d1 = rt.grad(&mut engine, &cube, &s)?;
let d2 = rt.grad(&mut engine, &d1, &s)?;
let d3 = rt.grad(&mut engine, &d2, &s)?;
// ...
let jv = rt.jvp(&mut engine, &sq, &x, &t)?;
let y = {
  let _guard = rt.no_grad();
  rt.with_eager_session(&mut engine, |ss| ss.mul(&x, &x))?
};
let d = x.detach(&mut engine)?;

== 4. clear_grad, then functional grad
rt.grad   = [20.0, 80.0, 180.0]
x.grad    = None (slot untouched)
dx.tracks_grad = true
== 5. second order through the functional grad
f' = [18.75], f'' = [15.0], f''' = [6.0]
== 6. eager jvp
jvp = [-7.8]
== 7. no_grad and detach
no_grad result tracks_grad=false, detach tracks_grad=false

eager grad wrt intermediate:  Err(Validation { op: "grad", phase: GraphBuild, source: InvalidArgument { argument: "wrt", message: "grad is inactive for Input(User { id: 7 }); use grad_optional to observe the inactive state" } })
eager backward of non-scalar: Err(NonScalarGrad { shape: [3] })
eager grad wrt constant:      Err(Validation { op: "grad", phase: GraphBuild, source: InvalidArgument { argument: "wrt", message: "grad is inactive for Input(User { id: 10 }); use grad_optional to observe the inactive state" } })
eager grad_optional constant: Ok(false)

fn insert_pruning_dead<K: std::hash::Hash + Eq, V>(
    map: &mut HashMap<K, Weak<V>>,
    key: K,
    value: Weak<V>,
) {
    if map.len() == map.capacity() {
        map.retain(|_, entry| entry.strong_count() > 0);
    }
    map.insert(key, value);
}

== 8. what the runtime keeps alive
before drop: grad_slots_len=14 value_records_len=16
after drop:  grad_slots_len=14 value_records_len=16
after clear_grads: grad_slots_len=2 value_records_len=16

step     0: grad_slots_len=  2 value_records_len=    5 forward=   275.1us backward=   550.6us
step     1: grad_slots_len=  2 value_records_len=    5 forward=    77.1us backward=   140.9us
step    10: grad_slots_len=  2 value_records_len=    5 forward=    63.0us backward=    96.5us
step  100: grad_slots_len=  2 value_records_len=    5 forward=    74.5us backward=    91.6us
step  1000: grad_slots_len=  2 value_records_len=    5 forward=    62.8us backward=    86.9us
n=64: first backward 550.6us; warm backward min 81.6us median 88.2us; forward min 58.6us median 62.3us
max value_records_len over the run = 5
CacheStats { entries: 1, retained_bytes: 1538, hits: 1000, misses: 1, evictions: 0, clears: 0 }

== 3. backward again on the same loss (no clear_grad)
x.grad    = Some([40.0, 160.0, 360.0])
cache: CacheStats { entries: 1, retained_bytes: 1474, hits: 1, misses: 1, evictions: 0, clears: 0 }
== 3b. backward on a second engine
x.grad    = Some([20.0, 80.0, 180.0])
cache: CacheStats { entries: 1, retained_bytes: 1474, hits: 2, misses: 1, evictions: 0, clears: 0 }