fandhe-ai 0.13.0

//! Keras `Sequential` 慣習のレイヤー積み上げビルダー（TASK-9.2a・
//! #95。TASK-9.4・#411 で `fandhe_ai_autodiff::compat` から本クレートへ移設）。
//! 数値ロジックは一切持たず、`fandhe_ai_autodiff::nn::Module` 実装
//! （`Linear`・`Relu`・`Sigmoid`・`Tanh`・`Silu`・`Hardswish`・
//! `LeakyRelu`・`Elu`〈イシュー #1714〉・`Dropout`〈イシュー #1603〉）を
//! メソッドチェーンで積み上げ、`forward`/`predict` で
//! `nn::Module::forward` へ委譲するだけの薄いビルダー（REQ-9）。対象
//! レイヤーは `docs/compat-api-scope.md` §1 の範囲拡張手続き（同 §5）を
//! 経て追加された集合限定（Linear・ReLU/Sigmoid/Tanh・Silu/Hardswish/
//! LeakyRelu/Elu/Dropout・Conv2d/Conv1d〈#1770〉・LayerNorm/RmsNorm/
//! BatchNorm1d/BatchNorm2d/Embedding/MultiheadAttention〈#1760〉・
//! MaxPool2d/MaxPool1d/AvgPool2d/AvgPool1d/AdaptiveAvgPool2d/
//! AdaptiveAvgPool1d〈#1957〉・AdaptiveMaxPool2d/AdaptiveMaxPool1d/
//! GlobalPool〈#2527〉・Dropout2d/AlphaDropout/EmbeddingBag〈#2528〉・
//! Mish/Hardtanh/Relu6/Glu/PRelu〈#2529〉・Softmax/LogSoftmax・
//! GELU（誤差関数版・tanh 近似版）/Softplus・Flatten〈#2065 で
//! `add_softmax`／`add_log_softmax`／`add_gelu`／`add_gelu_tanh`／
//! `add_softplus`／`add_flatten` として追加済み〉）。dropout 系（`Dropout`・`Dropout2d`・`AlphaDropout`〈#2528〉）は
//! 本クレート内実装で
//! 唯一 `set_training`／`training`（イシュー #1758）を実際に保持する
//! 層のため、`Sequential::set_training` の伝播がここで初めて実挙動差
//! を生む（`nn::Dropout` モジュール doc 参照）。
//!
//! **学習（勾配取得・パラメータ更新。#294 で対応済み）**: [`Sequential::bind`]
//! が返す [`SequentialVars`] を経由して `LinearVars`（勾配取得の入口。
//! `Tape::backward` 後に `Gradients::get(&vars.weight)` する経路）へ
//! アクセスできる。[`Sequential::trainable_parameters`]/
//! [`Sequential::apply_parameters`] と組み合わせ、[`crate::optim::Sgd`]・
//! [`crate::optim::AdamW`]／[`crate::optim::Adam`]（`fandhe_ai::optim`。
//! facade 公開面。イシュー #961・#1742）
//! の位置対応契約にそのまま渡せる。`facade` が唯一のサポートされる公開
//! API 面であり（`docs/compat-api-scope.md` §0）、利用者は内部クレート
//! `fandhe_ai_autodiff` へ直接依存する必要はない。適用順序契約
//! （`backward → clip → optimizer step`）の正は [`crate::optim`]
//! モジュール doc とする（イシュー #963）。AMP（[`crate::optim::GradScaler`]）
//! 使用時の順序（`scale_loss → backward → unscale → 非有限なら skip →
//! clip → step → update`）も同じく [`crate::optim`] モジュール doc「適用
//! 順序契約」節を正とする（イシュー #1722）。
//!
//! ```
//! use fandhe_ai::Tensor;
//! use fandhe_ai::compat::Sequential;
//! use fandhe_ai::optim::{Sgd, SgdConfig, clip_grad_norm};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let x = Tensor::new(vec![0.1_f32, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], &[2, 4])?;
//! let y = Tensor::new(vec![0.0_f32, 1.0, 1.0, 0.0], &[2, 2])?;
//!
//! let mut model = Sequential::new()
//!     .add_linear(4, 8, /* seed = */ 42)?
//!     .add_relu()
//!     .add_linear(8, 2, /* seed = */ 43)?;
//!
//! let mut sgd = Sgd::new(SgdConfig::new(0.01))?;
//!
//! // `SequentialVars`（`bound`）は `&model`／`&tape` を借用するため、
//! // `apply_parameters`（`&mut model`）を呼ぶ前にブロックを抜けて
//! // 借用を解放する。
//! let updated = {
//!     let tape = fandhe_ai::tape();
//!     let bound = model.bind(&tape);
//!     let x_var = tape.var(&x);
//!     let y_var = tape.var(&y);
//!
//!     let pred = bound.forward(&tape, &x_var)?;
//!     let loss = pred.mse_loss(&y_var)?;
//!
//!     let grads = tape.backward(&loss)?;
//!     let grad_refs = bound.trainable_grads(&grads)?;
//!     // 適用順序契約: backward → clip → optimizer step。
//!     let clipped = clip_grad_norm(&grad_refs, /* max_norm = */ 1.0)?;
//!     let clipped_grad_refs: Vec<&Tensor<f32>> = clipped.grads.iter().collect();
//!     let param_refs = model.trainable_parameters();
//!     sgd.step(&param_refs, &clipped_grad_refs)?
//! };
//! model.apply_parameters(updated)?;
//! # Ok(())
//! # }
//! ```
//!
//! **`predict` の既定結線（TASK-9.4・#411）**: `predict` は本クレートの
//! composition root（[`crate::tape`]。既定 CPU・`CpuBackendOps`・融合
//! 有効）で `Tape` を構築して forward する。旧 `fandhe_ai_autodiff::compat` 版が
//! 依存していた naive 参照実装（`fandhe_ai_autodiff::default_ops::naive_ops()`。
//! クレート非公開）は facade から到達できないため、この結線先の変更に
//! 伴い旧 `predict_with_ops`（任意 `BackendOps` 注入経路）は公開面から
//! 撤去した（REQ-12「任意 `BackendOps` 実装を注入できる公開 API を
//! 設けない」・`crates/facade/tests/api_surface.rs` の機械検査と整合。
//! `compat/mod.rs` モジュール doc 参照）。ops を明示的に選びたい内部用途
//! は [`Sequential::forward`]（[`crate::Tape`] を受け取るだけで
//! `BackendOps` は受け取らない）へ、呼び出し元が任意に構築した `Tape` を
//! 渡せば足りる。
//!
//! **公開シグネチャの型（codex-review PR #424 P1 是正）**: `forward`／
//! `bind`／`predict` 等は `fandhe_ai_autodiff::Tape` を直接引数に取らず、本クレート
//! 所有の newtype [`crate::Tape`] を取る（`crate::lib.rs` モジュール doc
//! 「`Tape`（composition root が構築する値）の扱い」参照）。`Var`・
//! `Gradients`・`AutodiffError`・`LinearVars`・`Tensor` は `crate::`
//! 経由（facade の正式な再エクスポート）で参照する。

use std::collections::HashMap;

use crate::data::{DataError, DataLoader, Dataset};
use crate::inference::PredictBatchInput;
use crate::inference::batch::{
    InferencePhase, NoopPhaseRecorder, PhaseRecorder, TimingPhaseRecorder,
    merge_inference_phase_stats,
};
use crate::{
    AutodiffError, BackendError, DeviceParamStore, EmbeddingBagMode, GlobalPoolMode, Gradients,
    InterpolateMode, LinearVars, ResidentLeaf, ResidentLoss, ResidentTensor, SgdConfig, Tape,
    Tensor, Var,
};
use fandhe_ai_autodiff::nn::activation::{
    Celu, Elu, Gelu, GeluTanh, Glu, Hardsigmoid, Hardswish, Hardtanh, LeakyRelu, LogSigmoid,
    LogSoftmax, Mish, PRelu, PReluVars, Relu, Relu6, Selu, Sigmoid, Silu, Softmax, Softplus,
    Softsign, Tanh,
};
use fandhe_ai_autodiff::nn::softmin_threshold::{RRelu, Softmin, Tanhshrink, Threshold};
use fandhe_ai_autodiff::nn::{
    AdaptiveAvgPool1d, AdaptiveAvgPool2d, AdaptiveMaxPool1d, AdaptiveMaxPool2d, AlphaDropout,
    AvgPool1d, AvgPool2d, AvgPool3d, BatchNorm1d, BatchNorm2d, BatchNormVars, Conv1d, Conv1dVars,
    Conv2d, Conv2dVars, Conv3d, Conv3dVars, ConvTranspose1d, ConvTranspose1dVars, ConvTranspose2d,
    ConvTranspose2dVars, ConvTranspose3d, ConvTranspose3dVars, Dropout, Dropout2d, Embedding,
    EmbeddingBag, EmbeddingBagVars, EmbeddingVars, FeedForwardActivation, Flatten, Fold,
    GlobalPool, GroupNorm, Identity, InstanceNorm, LAYER_NORM_DEFAULT_EPS, LayerNorm,
    LayerNormVars, Linear, LocalResponseNorm, MaxPool1d, MaxPool2d, MaxPool3d, Module,
    MultiheadAttention, MultiheadAttentionConfig, MultiheadAttentionVars, PixelShuffle,
    PixelUnshuffle, RmsNorm, RmsNormVars, Sequential as NnSequential, Transformer,
    TransformerConfig, TransformerDecoderLayer, TransformerDecoderLayerVars,
    TransformerEncoderLayer, TransformerEncoderLayerVars, TransformerVars, Unflatten, Unfold,
    Upsample, ZeroPad2d, conv2d_forward_low_precision, linear_forward_low_precision,
    multihead_attention_forward_low_precision,
};
use fandhe_ai_tensor_core::{Activation, BackendOps, ScalarDType};

/// `Sequential::train_step_resident` が学習チェーン本体として呼ぶ関数の型（イシュー #3254）。
/// 本番は `DeviceParamStore::train_step_device_chain` 固定で、テストだけが「バックエンドが部品を
/// 持たない（`Unsupported`）」を注入する差し替え点（公開面には出さない）。
type ResidentChainRunner = for<'a, 't> fn(
    &mut DeviceParamStore,
    &'t fandhe_ai_autodiff::Tape,
    &fandhe_ai_autodiff::optim::resident_input::ResidentInput,
    &fandhe_ai_autodiff::optim::resident_input::ResidentInput,
    &[(
        &'a ResidentLeaf<'t>,
        Option<&'a ResidentLeaf<'t>>,
        Activation,
    )],
    &SgdConfig,
) -> Result<
    fandhe_ai_autodiff::optim::resident_input::TrainStepLoss,
    BackendError,
>;

// イシュー #3251・#3254: 学習ステップのチェーン（autodiff 内部）と公開入口 `train_step_resident` の
// facade 側テスト。
#[cfg(test)]
mod train_step_chain_tests_3251;

/// Keras `Sequential` 慣習のレイヤー積み上げビルダー。`add_*` はメソッド
/// チェーン（`self` を消費し `Self` を返す）で層を追加し、`predict` で
/// 推論を実行する。層は `nn::Module`（`fandhe_ai_autodiff::nn::module`）実装として
/// 保持するため、種類の異なる層（`Linear` と活性化関数）を同じ列で
/// 扱える。
///
/// **イシュー #1759（親 #1617）での再構成**: 層の保持・走査・
/// train／eval モード・`named_parameters` の汎用ロジックは
/// `fandhe_ai_autodiff::nn::Sequential`（`NnSequential`。ネスト可能な
/// 汎用コンテナ。`docs/compat-api-scope.md` §1.2）へ移設し、本
/// `Sequential`（compat 層）はそれを `inner` として保持する薄い
/// ラッパーに徹する（REQ-9）。公開シグネチャ・数値挙動は不変
/// （`docs/compat-api-scope.md` §1 の対象レイヤー集合限定は変わらない）。
///
/// **ネストの制限**: [`Sequential::bind`]／[`Sequential::
/// trainable_parameters`]／[`Sequential::apply_parameters`]・デバイス
/// 常駐経路（[`Sequential::init_device_param_store`] 等）は最上位の
/// `as_linear()` のみを見る学習契約であり、この制限は本再構成でも
/// 変わらない（`fandhe_ai_autodiff::nn::container` モジュール doc
/// 「ネストの限界」参照。ただし compat 層は `NnSequential`／
/// `ModuleList` を構築する経路自体を公開していないため、ネストは
/// facade 経由では到達不能）。
///
/// **独自層（`add_module`。イシュー #2398）と学習契約**: [`Sequential::add_module`] で積んだ
/// facade `nn::Module` 実装が学習可能パラメータを持つ場合、`bind` はその層を追跡しない。
/// 学習されないまま成功する状態を作らないため、`fit` 系・`SequentialVars::forward`／
/// `trainable_grads`・デバイス常駐経路は型付き `Err` で拒否する（`bind` と
/// `SequentialVars::trainable_vars` は signature 上 `Err` を返せず、独自層を含まない短い列に
/// なりうる。直後の `forward`／`trainable_grads` が拒否する）。無状態の独自層は通過する。
pub struct Sequential {
    inner: NnSequential,
    /// Keras 風 `compile()`（イシュー #1761・`compat/training.rs`）で
    /// 設定される optimizer／loss の組。`fit`／`evaluate` はこれが
    /// `Some` であることを前提とする（未設定なら `InvalidArgument`）。
    /// `Compiled`（`OptimizerState` 経由で `crate::optim::{Sgd, AdamW,
    /// Adam, RmsProp, Adagrad, Lamb}`（イシュー #2170 で後 3 者を
    /// 追加）を保持）は本クレート内でのみ構築・参照する非公開型で、
    /// `Sequential` の他フィールドと同じく公開面には出さない。
    pub(super) compiled: Option<super::training::Compiled>,
    /// 各層の構成記録（`inner` の層と 1 対 1）。`compat::model_io::save_model`
    /// が manifest の層構成を導く唯一の根拠で、`add_*` が積むたびに push する
    /// （イシュー #2369・`docs/compat-model-io-decision.md` §5）。private
    /// フィールドのため公開 API は非破壊。
    specs: Vec<LayerSpec>,
}

/// `Sequential` に積んだ層の構成記録（`compat::model_io` 専用の内部型）。
///
/// `add_*` 50 メソッドの引数（`seed` を除く）をそのまま記録し、`load_model` が同じ
/// `add_*` を呼んで再構築する（イシュー #2369・#2370。`docs/compat-model-io-decision.md`
/// §5）。`add_*` の内部で固定している値（conv／linear の `bias=true`・pool の
/// `ceil_mode=false`・TE の活性化と eps 等）は記録しない（同じ `add_*` が再現するため）。
/// `seed` は保持しない: 初期化にしか使われず、重みは直後の `load_state_dict` で上書きされる
/// （#2369 が残した「#2370 で再判断」の結論）。[`LayerSpec::Unsupported`] は
/// [`Sequential::add_module`]（構成を記録できない利用者定義層）専用で、`save_model` が
/// `UnsupportedModel` で fail-closed にする。f32 を含むため `Eq` は実装しない。
#[derive(Debug, Clone, PartialEq)]
pub(super) enum LayerSpec {
    Linear {
        in_features: usize,
        out_features: usize,
    },
    Relu,
    Sigmoid,
    Tanh,
    Silu,
    Hardswish,
    Gelu,
    GeluTanh,
    LeakyRelu {
        negative_slope: f32,
    },
    Elu {
        alpha: f32,
    },
    Softmax {
        dim: usize,
    },
    LogSoftmax {
        dim: usize,
    },
    Softplus {
        beta: f32,
        threshold: f32,
    },
    Flatten {
        start_dim: usize,
        end_dim: usize,
    },
    Dropout {
        p: f32,
    },
    /// イシュー #2528。
    Dropout2d {
        p: f32,
    },
    /// イシュー #2528。
    AlphaDropout {
        p: f32,
    },
    Conv2d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
        groups: usize,
    },
    /// イシュー #2524。bias あり固定（`add_conv3d`）。
    Conv3d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 3],
        stride: [usize; 3],
        padding: [usize; 3],
        dilation: [usize; 3],
        groups: usize,
    },
    /// イシュー #2523。bias あり固定（`add_conv_transpose2d`）。
    ConvTranspose2d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        output_padding: [usize; 2],
        dilation: [usize; 2],
        groups: usize,
    },
    /// イシュー #3033。bias あり固定（`add_conv_transpose3d`。`seed` は保存しない）。
    ConvTranspose3d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 3],
        stride: [usize; 3],
        padding: [usize; 3],
        output_padding: [usize; 3],
        dilation: [usize; 3],
        groups: usize,
    },
    Conv1d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: usize,
        stride: usize,
        padding: usize,
        dilation: usize,
        groups: usize,
    },
    /// イシュー #3055。bias あり固定（`add_conv_transpose1d`）。
    ConvTranspose1d {
        in_channels: usize,
        out_channels: usize,
        kernel_size: usize,
        stride: usize,
        padding: usize,
        output_padding: usize,
        dilation: usize,
        groups: usize,
    },
    /// イシュー #3055。`sizes` は `add_unflatten` の `unflattened_size`。
    Unflatten {
        dim: usize,
        sizes: Vec<usize>,
    },
    LayerNorm {
        normalized_size: usize,
        eps: f32,
    },
    RmsNorm {
        normalized_size: usize,
        eps: f32,
    },
    BatchNorm1d {
        num_features: usize,
        eps: f32,
        momentum: f32,
    },
    BatchNorm2d {
        num_features: usize,
        eps: f32,
        momentum: f32,
    },
    Embedding {
        num_embeddings: usize,
        embedding_dim: usize,
        padding_idx: Option<usize>,
    },
    /// イシュー #2529。
    Mish,
    /// イシュー #3053。無引数（`params` は `{}`）。
    Selu,
    /// イシュー #3053。無引数。
    Softsign,
    /// イシュー #3053。無引数。
    Hardsigmoid,
    /// イシュー #3053。無引数。
    LogSigmoid,
    /// イシュー #3053。無引数。
    Tanhshrink,
    /// イシュー #3054。`alpha` のみ（学習パラメータなし）。
    Celu {
        alpha: f32,
    },
    /// イシュー #3054。`dim` のみ（範囲は forward 時の遅延検査）。
    Softmin {
        dim: usize,
    },
    /// イシュー #3054。`threshold`・`value`（構築時検査なし。非有限は保存時に拒否）。
    Threshold {
        threshold: f32,
        value: f32,
    },
    /// イシュー #3054。`lower`・`upper`（RNG 状態は保存しない。決定記録 #3052 §3）。
    RRelu {
        lower: f32,
        upper: f32,
    },
    /// イシュー #2529。
    Hardtanh {
        min_val: f32,
        max_val: f32,
    },
    /// イシュー #2529。
    Relu6,
    /// イシュー #2529。
    Glu {
        dim: usize,
    },
    /// イシュー #2529。`init` は初期化にしか使われず直後の `load_state_dict` で
    /// `weight` が上書きされるため記録しない（`seed` と同じ扱い）。
    PRelu {
        num_parameters: usize,
    },
    /// イシュー #2528。
    EmbeddingBag {
        num_embeddings: usize,
        embedding_dim: usize,
        mode: EmbeddingBagMode,
        padding_idx: Option<usize>,
    },
    MultiheadAttention {
        embed_dim: usize,
        num_heads: usize,
    },
    /// イシュー #2530。`add_multihead_attention_with_config` が積む。kdim/vdim は
    /// 追加時に `embed_dim` 固定へ制限されるため記録しない。既存 kind
    /// `multihead_attention` のスキーマを変えないための別 variant。
    MultiheadAttentionConfig {
        embed_dim: usize,
        num_heads: usize,
        bias: bool,
        batch_first: bool,
    },
    TransformerEncoder {
        d_model: usize,
        num_heads: usize,
        dim_feedforward: usize,
    },
    /// イシュー #2532。`add_transformer_decoder_layer` が積む（Relu・eps 既定固定のため
    /// 活性化・eps は記録しない）。
    TransformerDecoderLayer {
        d_model: usize,
        num_heads: usize,
        dim_feedforward: usize,
    },
    /// イシュー #2533。`add_transformer` が積む（活性化は Relu 限定のため記録しない。
    /// `eps` は `TransformerConfig::with_eps` で変えられるため保存・復元する）。
    Transformer {
        d_model: usize,
        num_heads: usize,
        num_encoder_layers: usize,
        num_decoder_layers: usize,
        dim_feedforward: usize,
        eps: f32,
    },
    MaxPool2d {
        kernel_size: [usize; 2],
        stride: Option<[usize; 2]>,
        padding: [usize; 2],
        dilation: [usize; 2],
    },
    MaxPool1d {
        kernel_size: usize,
        stride: Option<usize>,
        padding: usize,
        dilation: usize,
    },
    /// `nn::MaxPool3d`（イシュー #3029。`ceil_mode=false` 固定のため manifest へは書かない）。
    MaxPool3d {
        kernel_size: [usize; 3],
        stride: Option<[usize; 3]>,
        padding: [usize; 3],
        dilation: [usize; 3],
    },
    /// `nn::AvgPool3d`（イシュー #3029。`ceil_mode=false`・`dilation=[1,1,1]` 固定）。
    AvgPool3d {
        kernel_size: [usize; 3],
        stride: Option<[usize; 3]>,
        padding: [usize; 3],
        count_include_pad: bool,
    },
    AvgPool2d {
        kernel_size: [usize; 2],
        stride: Option<[usize; 2]>,
        padding: [usize; 2],
        count_include_pad: bool,
    },
    AvgPool1d {
        kernel_size: usize,
        stride: Option<usize>,
        padding: usize,
        count_include_pad: bool,
    },
    AdaptiveAvgPool2d {
        output_size: [usize; 2],
    },
    AdaptiveAvgPool1d {
        output_size: usize,
    },
    /// イシュー #2527。
    AdaptiveMaxPool2d {
        output_size: [usize; 2],
    },
    /// イシュー #2527。
    AdaptiveMaxPool1d {
        output_size: usize,
    },
    /// イシュー #2527。
    GlobalPool {
        mode: GlobalPoolMode,
        keepdims: bool,
    },
    Upsample {
        size: Vec<usize>,
        mode: InterpolateMode,
    },
    ZeroPad2d {
        padding: [usize; 4],
    },
    Identity,
    GroupNorm {
        groups: usize,
        eps: f32,
    },
    InstanceNorm {
        eps: f32,
    },
    /// イシュー #2526。
    PixelShuffle {
        upscale_factor: usize,
    },
    /// イシュー #2526。
    PixelUnshuffle {
        downscale_factor: usize,
    },
    /// イシュー #3041。無パラメータ層（`unfold` kind）。
    Unfold {
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
    },
    /// イシュー #3041。無パラメータ層（`fold` kind）。
    Fold {
        output_size: [usize; 2],
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
    },
    /// イシュー #3045。無パラメータ層（`local_response_norm` kind）。
    LocalResponseNorm {
        size: usize,
        alpha: f32,
        beta: f32,
        k: f32,
    },
    /// イシュー #3050。`parametrize_weight_norm`／`parametrize_spectral_norm` で再パラメータ化した層
    /// （Linear・Conv 6 種のみ。基底が他の層の場合は従来どおり [`LayerSpec::Unsupported`]）。
    /// `base` は再パラメータ化前の `add_*` の構成で、load が基底を `add_*` で組み直してから
    /// 同じ `parametrize_*` を再適用するために保持する（決定記録 §7）。
    Reparam {
        base: Box<LayerSpec>,
        reparam: ReparamSpec,
    },
    /// 保存対象外の層（`add_module` の利用者定義層と、manifest スキーマ未対応の組み込み層。
    /// `kind` はエラー文言で読む）。
    Unsupported {
        kind: &'static str,
    },
}

/// [`LayerSpec::Reparam`] の再パラメータ化の種別と引数（イシュー #3050。`compat::model_io` 専用）。
/// `spectral_norm` の `seed` は保持しない（初期 `u`／`v` は load が保存済みの値で上書きするため）。
#[derive(Debug, Clone, Copy, PartialEq)]
pub(super) enum ReparamSpec {
    WeightNorm { dim: Option<usize> },
    SpectralNorm { n_power_iterations: usize, eps: f32 },
}

/// `parametrize_*` の対象で、かつ `save_model` が基底構成から復元できる基底層か（Linear・Conv 6 種）。
/// それ以外（`add_module` 由来の `Unsupported` 等）は `Reparam` に包まず従来の `Unsupported` を保つ。
fn reparam_base_is_savable(spec: &LayerSpec) -> bool {
    matches!(
        spec,
        LayerSpec::Linear { .. }
            | LayerSpec::Conv1d { .. }
            | LayerSpec::Conv2d { .. }
            | LayerSpec::Conv3d { .. }
            | LayerSpec::ConvTranspose1d { .. }
            | LayerSpec::ConvTranspose2d { .. }
            | LayerSpec::ConvTranspose3d { .. }
    )
}

impl Default for Sequential {
    fn default() -> Self {
        Self::new()
    }
}

impl Sequential {
    pub fn new() -> Self {
        Sequential {
            inner: NnSequential::new(),
            compiled: None,
            specs: Vec::new(),
        }
    }

    /// 全結合層を追加する（bias あり既定。PyTorch `nn.Linear` の既定
    /// `bias=True` と揃える）。`Linear::new` が `Result` を返す
    /// （`in_features == 0` を拒否する。`fandhe_ai_autodiff::nn::linear` 参照）ため、
    /// 本メソッドも `Result<Self, AutodiffError>` を返し `?` で連鎖
    /// できるようにする。
    pub fn add_linear(
        mut self,
        in_features: usize,
        out_features: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let linear = Linear::new(in_features, out_features, true, seed)?;
        self.inner.push(Box::new(linear));
        self.specs.push(LayerSpec::Linear {
            in_features,
            out_features,
        });
        Ok(self)
    }

    /// 作成済みの `Linear`／`Conv1d`／`Conv2d`／`Conv3d`／`ConvTranspose1d`／`ConvTranspose2d`／
    /// `ConvTranspose3d` 層（`layer_index` 番目。活性化層を含む全層の位置）の重みを
    /// weight_norm（`w = g · v / ‖v‖`。PyTorch `torch.nn.utils.weight_norm` 相当）へ再パラメータ化する
    /// （イシュー #3048。決定記録 `docs/facade-weight-reparam-wiring-decision.md` §5 D-A (a)）。
    ///
    /// 本体は `fandhe_ai_autodiff::nn::Linear::parametrize_weight_norm` への薄い委譲（REQ-9）。
    /// `dim` は `None`／`Some(0)`（in 軸ごと）／`Some(1)`（out 軸ごと。PyTorch の `dim=0` 相当）。
    /// 適用直後の有効重みは元の重みと一致する。
    ///
    /// - `named_parameters`／`trainable_parameters` の並びは `parametrizations.weight.original0`（g）
    ///   → `parametrizations.weight.original1`（v）→ `bias`（`trainable_vars`／`trainable_grads`／
    ///   `apply_parameters` も同じ順序契約）。
    /// - 次はいずれも `InvalidArgument` で拒否する: 添字が範囲外・対象が `Linear` でない・二重適用・
    ///   `compile` 後（optimizer のパラメータ数が固定済みのため。compile 前に適用すること）。
    /// - 非対応（型付きエラーで拒否）: デバイス常駐経路（`init_device_param_store` 等は
    ///   `BackendError::Unsupported`）・低精度（AMP）forward・ONNX export。`predict` は tape 経路で有効重みを
    ///   再構成して動作する。
    /// - `save_model`／`load_model` に対応する（イシュー #3050。manifest kind は基底 7 種 × weight_norm／
    ///   spectral_norm の 14 種。spectral_norm の `u`／`v` は buffer として保存し bit のまま復元する）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new()
    ///     .add_linear(3, 2, /* seed = */ 7)?
    ///     .parametrize_weight_norm(0, Some(1))?;
    /// let names: Vec<String> = model.named_parameters().into_iter().map(|(n, _)| n).collect();
    /// assert_eq!(
    ///     names,
    ///     [
    ///         "0.parametrizations.weight.original0",
    ///         "0.parametrizations.weight.original1",
    ///         "0.bias",
    ///     ]
    /// );
    /// let x = Tensor::new(vec![0.1_f32, 0.2, 0.3], &[1, 3])?;
    /// assert_eq!(model.predict(&x)?.shape(), [1, 2]);
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// Conv 系 6 層（イシュー #3049）も同じ呼び出しで対象になる。`dim` は層種に依らず利用者指定
    /// （`None`／`Some(d)`、`d < weight の rank`。範囲外は型付きエラー）。ConvTranspose の weight は
    /// `[in, out/groups, k...]` のため、出力チャネル単位にしたい場合は `Some(1)`（PyTorch 既定の `dim=0`
    /// は入力チャネル軸）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new()
    ///     .add_conv2d(2, 3, [3, 3], [1, 1], [1, 1], [1, 1], 1, /* seed = */ 7)?
    ///     .parametrize_weight_norm(0, Some(0))?;
    /// let names: Vec<String> = model.named_parameters().into_iter().map(|(n, _)| n).collect();
    /// assert_eq!(
    ///     names,
    ///     [
    ///         "0.parametrizations.weight.original0",
    ///         "0.parametrizations.weight.original1",
    ///         "0.bias",
    ///     ]
    /// );
    /// let x = Tensor::new(vec![0.1_f32; 2 * 4 * 4], &[1, 2, 4, 4])?;
    /// assert_eq!(model.predict(&x)?.shape(), [1, 3, 4, 4]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn parametrize_weight_norm(
        mut self,
        layer_index: usize,
        dim: Option<usize>,
    ) -> Result<Self, AutodiffError> {
        self.check_parametrize_target("Sequential::parametrize_weight_norm", layer_index)?;
        let training = self.inner.training();
        let layer = self.parametrize_layer_mut(layer_index)?;
        let kind = if let Some(linear) = layer.as_linear_mut() {
            linear.parametrize_weight_norm(dim)?;
            "linear_weight_norm"
        } else if let Some(conv) = layer.as_conv2d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv2d_weight_norm"
        } else if let Some(conv) = layer.as_conv1d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv1d_weight_norm"
        } else if let Some(conv) = layer.as_conv3d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv3d_weight_norm"
        } else if let Some(conv) = layer.as_conv_transpose1d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv_transpose1d_weight_norm"
        } else if let Some(conv) = layer.as_conv_transpose2d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv_transpose2d_weight_norm"
        } else if let Some(conv) = layer.as_conv_transpose3d_mut() {
            conv.parametrize_weight_norm(dim)?;
            "conv_transpose3d_weight_norm"
        } else {
            return Err(parametrize_unsupported_layer_error(layer_index));
        };
        layer.set_training(training);
        self.wrap_reparam_spec(layer_index, kind, ReparamSpec::WeightNorm { dim });
        Ok(self)
    }

    /// 作成済みの対象層（`layer_index` 番目。対象は [`Sequential::parametrize_weight_norm`] と同じ）の重みを spectral_norm（`w = W / σ`。PyTorch
    /// `torch.nn.utils.spectral_norm` 相当）へ再パラメータ化する（イシュー #3048。決定記録 §5 D-A (a)）。
    ///
    /// 本体は `fandhe_ai_autodiff::nn::Linear::parametrize_spectral_norm` への薄い委譲。`u0`／`v0` は
    /// `seed` から決定的に導出し、予備反復 15 回を行う。`n_power_iterations >= 1`・`eps` が有限かつ非負。
    /// train モード（既定）の forward 1 回ごとに power iteration で状態が進み、`eval()` では進まない
    /// （同一 step で forward を複数回呼ぶとその回数だけ進む。PyTorch と同じ契約）。
    /// 並びは `parametrizations.weight.original` → `bias`。拒否条件・非対応経路は
    /// [`Sequential::parametrize_weight_norm`] と同じ。
    ///
    /// Conv 系 6 層（イシュー #3049）では行軸を層から導出する（Conv1d／2d／3d は 0、ConvTranspose1d／2d／3d は
    /// 1。PyTorch と一致）。`dim` の利用者指定はスコープ外。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new()
    ///     .add_conv_transpose2d(2, 3, [2, 2], [1, 1], [0, 0], [0, 0], [1, 1], 1, /* seed = */ 7)?
    ///     .parametrize_spectral_norm(0, 1, 1e-12, /* seed = */ 7)?;
    /// let names: Vec<String> = model.named_parameters().into_iter().map(|(n, _)| n).collect();
    /// assert_eq!(names, ["0.parametrizations.weight.original", "0.bias"]);
    /// let x = Tensor::new(vec![0.1_f32; 2 * 3 * 3], &[1, 2, 3, 3])?;
    /// assert_eq!(model.predict(&x)?.shape(), [1, 3, 4, 4]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn parametrize_spectral_norm(
        mut self,
        layer_index: usize,
        n_power_iterations: usize,
        eps: f32,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        self.check_parametrize_target("Sequential::parametrize_spectral_norm", layer_index)?;
        let training = self.inner.training();
        let layer = self.parametrize_layer_mut(layer_index)?;
        let kind = if let Some(linear) = layer.as_linear_mut() {
            linear.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "linear_spectral_norm"
        } else if let Some(conv) = layer.as_conv2d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv2d_spectral_norm"
        } else if let Some(conv) = layer.as_conv1d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv1d_spectral_norm"
        } else if let Some(conv) = layer.as_conv3d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv3d_spectral_norm"
        } else if let Some(conv) = layer.as_conv_transpose1d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv_transpose1d_spectral_norm"
        } else if let Some(conv) = layer.as_conv_transpose2d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv_transpose2d_spectral_norm"
        } else if let Some(conv) = layer.as_conv_transpose3d_mut() {
            conv.parametrize_spectral_norm(n_power_iterations, eps, seed)?;
            "conv_transpose3d_spectral_norm"
        } else {
            return Err(parametrize_unsupported_layer_error(layer_index));
        };
        layer.set_training(training);
        self.wrap_reparam_spec(
            layer_index,
            kind,
            ReparamSpec::SpectralNorm {
                n_power_iterations,
                eps,
            },
        );
        Ok(self)
    }

    /// `parametrize_*` 成功後の構成記録の更新（イシュー #3050）。基底が保存可能な 7 種なら
    /// `Reparam { base, reparam }` に包み（`save_model` が保存・`load_model` が基底を組み直して再適用）、
    /// それ以外は従来どおり `Unsupported { kind }`（`save_model` が `UnsupportedModel` で拒否）にする。
    fn wrap_reparam_spec(&mut self, layer_index: usize, kind: &'static str, reparam: ReparamSpec) {
        let slot = &mut self.specs[layer_index];
        let base = std::mem::replace(slot, LayerSpec::Unsupported { kind });
        if reparam_base_is_savable(&base) {
            *slot = LayerSpec::Reparam {
                base: Box::new(base),
                reparam,
            };
        }
    }

    /// 再パラメータ化済みの `layer_index` 番目の spectral_norm の `u`／`v` を保存済みの値へ bit のまま
    /// 復元する（`compat::model_io::build_model` 専用。イシュー #3050）。Linear・Conv 6 種のダウンキャストは
    /// `parametrize_*` と同型。対象外・未適用・長さ／有限性違反は型付きエラーで、状態は変わらない。
    pub(super) fn restore_spectral_norm_vectors(
        &mut self,
        layer_index: usize,
        u: &[f32],
        v: &[f32],
    ) -> Result<(), AutodiffError> {
        let layer = self.parametrize_layer_mut(layer_index)?;
        if let Some(l) = layer.as_linear_mut() {
            l.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv2d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv1d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv3d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv_transpose1d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv_transpose2d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else if let Some(c) = layer.as_conv_transpose3d_mut() {
            c.restore_spectral_norm_vectors(u, v)
        } else {
            Err(parametrize_unsupported_layer_error(layer_index))
        }
    }

    /// `parametrize_*` の共通の事前検査（イシュー #3048）。状態を変更する前に、添字範囲・対象が
    /// 未再パラメータ化の `Linear` であること・`compile` 前であることを確認する。
    fn check_parametrize_target(&self, ctx: &str, layer_index: usize) -> Result<(), AutodiffError> {
        if self.compiled.is_some() {
            return Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: compile 後は適用できない（optimizer のパラメータ数が固定済み。\
                 compile 前に適用すること）"
            )));
        }
        let layers = self.inner.layers();
        let Some(layer) = layers.get(layer_index) else {
            return Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: layer_index {layer_index} は範囲外（層数 {}）",
                layers.len()
            )));
        };
        match parametrize_state(layer.as_ref()) {
            None => Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: 層 {layer_index} は Linear／Conv1d／Conv2d／Conv3d／ConvTranspose1d／\
                 ConvTranspose2d／ConvTranspose3d のいずれでもない"
            ))),
            Some(true) => Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: 層 {layer_index} はすでに再パラメータ化済み"
            ))),
            Some(false) => Ok(()),
        }
    }

    /// `check_parametrize_target` 通過後の対象層の可変参照（到達しない範囲外は型付きエラー）。
    fn parametrize_layer_mut(
        &mut self,
        layer_index: usize,
    ) -> Result<&mut Box<dyn Module>, AutodiffError> {
        self.inner
            .layers_mut()
            .get_mut(layer_index)
            .ok_or_else(|| parametrize_unsupported_layer_error(layer_index))
    }

    /// ReLU 層を追加する（`nn::activation::Relu`。shape 不変の演算のため
    /// 構造的に失敗しえず `Result` を返さない）。
    pub fn add_relu(mut self) -> Self {
        self.inner.push(Box::new(Relu));
        self.specs.push(LayerSpec::Relu);
        self
    }

    /// シグモイド層を追加する（`nn::activation::Sigmoid`）。
    pub fn add_sigmoid(mut self) -> Self {
        self.inner.push(Box::new(Sigmoid));
        self.specs.push(LayerSpec::Sigmoid);
        self
    }

    /// 双曲線正接層を追加する（`nn::activation::Tanh`）。
    pub fn add_tanh(mut self) -> Self {
        self.inner.push(Box::new(Tanh));
        self.specs.push(LayerSpec::Tanh);
        self
    }

    /// SiLU／Swish 層を追加する（`nn::activation::Silu`。イシュー
    /// #1714）。`Sigmoid`／`Tanh` と同様 `Linear` との epilogue 融合は
    /// 行わない（`Module::as_relu` は既定 `false` のまま）。shape 不変
    /// の演算のため構造的に失敗しえず `Result` を返さない。
    pub fn add_silu(mut self) -> Self {
        self.inner.push(Box::new(Silu));
        self.specs.push(LayerSpec::Silu);
        self
    }

    /// Hardswish 層を追加する（`nn::activation::Hardswish`。イシュー
    /// #1714）。[`Sequential::add_silu`] と同様融合対象外。
    pub fn add_hardswish(mut self) -> Self {
        self.inner.push(Box::new(Hardswish));
        self.specs.push(LayerSpec::Hardswish);
        self
    }

    /// Leaky ReLU 層を追加する（`nn::activation::LeakyRelu`。イシュー
    /// #1714）。`negative_slope`（負領域の傾き）は検証せず IEEE の
    /// まま伝播する。[`Sequential::add_silu`] と同様融合対象外。
    pub fn add_leaky_relu(mut self, negative_slope: f32) -> Self {
        self.inner.push(Box::new(LeakyRelu::new(negative_slope)));
        self.specs.push(LayerSpec::LeakyRelu { negative_slope });
        self
    }

    /// ELU 層を追加する（`nn::activation::Elu`。イシュー #1714）。
    /// `alpha` は検証せず IEEE のまま伝播する。[`Sequential::add_silu`]
    /// と同様融合対象外。
    pub fn add_elu(mut self, alpha: f32) -> Self {
        self.inner.push(Box::new(Elu::new(alpha)));
        self.specs.push(LayerSpec::Elu { alpha });
        self
    }

    /// Softmax 層を追加する（`nn::activation::Softmax`。イシュー
    /// #2065）。`dim`（softmax を適用する軸）の範囲検査は構築時では
    /// なく forward 時（`Var::softmax` 内部）に行われるため
    /// （`Softmax::new` 自体が infallible）、[`Sequential::add_relu`]
    /// と同型の遅延検査契約として `Result` を返さず `Self` を返す。
    pub fn add_softmax(mut self, dim: usize) -> Self {
        self.inner.push(Box::new(Softmax::new(dim)));
        self.specs.push(LayerSpec::Softmax { dim });
        self
    }

    /// LogSoftmax 層を追加する（`nn::activation::LogSoftmax`。イシュー
    /// #2065）。[`Sequential::add_softmax`] と同じ遅延検査契約。
    pub fn add_log_softmax(mut self, dim: usize) -> Self {
        self.inner.push(Box::new(LogSoftmax::new(dim)));
        self.specs.push(LayerSpec::LogSoftmax { dim });
        self
    }

    /// GELU（誤差関数版）層を追加する（`nn::activation::Gelu`。
    /// イシュー #2065）。ユニット構造体のため構築時検査は無い。
    pub fn add_gelu(mut self) -> Self {
        self.inner.push(Box::new(Gelu));
        self.specs.push(LayerSpec::Gelu);
        self
    }

    /// GELU（tanh 近似版）層を追加する（`nn::activation::GeluTanh`。
    /// イシュー #2065）。[`Sequential::add_gelu`] と同型。
    pub fn add_gelu_tanh(mut self) -> Self {
        self.inner.push(Box::new(GeluTanh));
        self.specs.push(LayerSpec::GeluTanh);
        self
    }

    /// Softplus 層を追加する（`nn::activation::Softplus`。イシュー
    /// #2065）。`Softplus::new` が構築時に `beta`／`threshold` の
    /// 有限性・符号を検査し `Result` を返すため（`nn/activation.rs`
    /// 参照）、本メソッドも [`Sequential::add_dropout`]／
    /// [`Sequential::add_layer_norm`] と同型で
    /// `Result<Self, AutodiffError>` を返す。PyTorch `nn.Softplus` の
    /// 既定値は `beta=1.0`・`threshold=20.0`（`Softplus::default`）。
    pub fn add_softplus(mut self, beta: f32, threshold: f32) -> Result<Self, AutodiffError> {
        let layer = Softplus::new(beta, threshold)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Softplus { beta, threshold });
        Ok(self)
    }

    /// Mish 層を追加する（`nn::activation::Mish`。イシュー #2529）。
    /// `x * tanh(softplus(x))`。ユニット構造体のため構築時検査は無く、
    /// [`Sequential::add_silu`] と同様融合対象外。無状態層のため学習経路・常駐経路を通過する。
    pub fn add_mish(mut self) -> Self {
        self.inner.push(Box::new(Mish));
        self.specs.push(LayerSpec::Mish);
        self
    }

    /// Hardtanh 層を追加する（`nn::activation::Hardtanh`。イシュー #2529）。
    /// 入力を `[min_val, max_val]` へクランプする。`Hardtanh::new` が NaN と
    /// `min_val >= max_val` を構築時に拒否するため `Result` を返す
    /// （`±inf` は構築できるが `save_model` では拒否される）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_hardtanh(-1.0, 1.0)?;
    /// let x = Tensor::new(vec![-2.0, 0.5, 3.0], &[1, 3])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.host_slice().into_owned(), vec![-1.0, 0.5, 1.0]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_hardtanh(mut self, min_val: f32, max_val: f32) -> Result<Self, AutodiffError> {
        let layer = Hardtanh::new(min_val, max_val)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Hardtanh { min_val, max_val });
        Ok(self)
    }

    /// ReLU6 層を追加する（`nn::activation::Relu6`。イシュー #2529）。
    /// `min(max(x, 0), 6)`。ユニット構造体のため構築時検査は無い。
    pub fn add_relu6(mut self) -> Self {
        self.inner.push(Box::new(Relu6));
        self.specs.push(LayerSpec::Relu6);
        self
    }

    /// GLU 層を追加する（`nn::activation::Glu`。イシュー #2529）。`dim` 軸を 2 分割し
    /// `a * sigmoid(b)` を返す。軸の範囲・偶数長の検査は構築時ではなく forward 時に
    /// 行われるため（`Glu::new` は infallible）、[`Sequential::add_softmax`] と同型の
    /// 遅延検査契約として `Self` を返す。
    pub fn add_glu(mut self, dim: usize) -> Self {
        self.inner.push(Box::new(Glu::new(dim)));
        self.specs.push(LayerSpec::Glu { dim });
        self
    }

    /// PReLU 層を追加する（`nn::activation::PRelu`。イシュー #2529）。`num_parameters`
    /// 個のチャネル別傾き `weight`（shape `[num_parameters]`）を `init`（PyTorch 既定は
    /// `0.25`）で初期化する学習可能な活性化層。`num_parameters == 0` は構築時に
    /// `AutodiffError` で拒否する。`init` は検証せず IEEE のまま扱う。
    /// 学習経路（`bind`／`trainable_parameters`／`fit`）に対応するが、常駐経路
    /// （`init_device_param_store` 等）は fail-closed で拒否する。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_prelu(1, 0.25)?;
    /// let x = Tensor::new(vec![-4.0, 2.0], &[2, 1])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.host_slice().into_owned(), vec![-1.0, 2.0]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_prelu(mut self, num_parameters: usize, init: f32) -> Result<Self, AutodiffError> {
        let layer = PRelu::new(num_parameters, init)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::PRelu { num_parameters });
        Ok(self)
    }

    /// SELU 層を追加する（`nn::activation::Selu`。PyTorch `nn.SELU` 相当。イシュー #2679）。
    /// ユニット構造体のため構築時検査は無く、[`Sequential::add_silu`] と同様融合対象外。
    /// 無状態層のため学習経路・常駐経路を通過する。`save_model`／`load_model`
    /// は無引数 kind `selu`（`params` は `{}`）で往復できる（イシュー #3053）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_selu();
    /// let x = Tensor::new(vec![0.0, 1.0], &[1, 2])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.host_slice().into_owned()[0], 0.0);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_selu(mut self) -> Self {
        self.inner.push(Box::new(Selu));
        self.specs.push(LayerSpec::Selu);
        self
    }

    /// CELU 層を追加する（`nn::activation::Celu`。PyTorch `nn.CELU(alpha)` 相当。イシュー #2679）。
    /// `alpha == 0` と非有限は構築時に `AutodiffError::InvalidArgument` で拒否する
    /// （負は PyTorch と同じく受理）。融合・常駐経路の扱いは [`Sequential::add_selu`] と同じ。保存は kind `celu`
    /// （`params`: `alpha`）で往復できる（イシュー #3054。非有限は保存時に `UnsupportedModel`）。
    pub fn add_celu(mut self, alpha: f32) -> Result<Self, AutodiffError> {
        let layer = Celu::new(alpha)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Celu { alpha });
        Ok(self)
    }

    /// Softsign 層を追加する（`nn::activation::Softsign`。`x / (1 + |x|)`。PyTorch `nn.Softsign`
    /// 相当。イシュー #2679）。融合・常駐経路の扱いは [`Sequential::add_selu`] と同じ（保存は無引数 kind で対応。#3053）。
    pub fn add_softsign(mut self) -> Self {
        self.inner.push(Box::new(Softsign));
        self.specs.push(LayerSpec::Softsign);
        self
    }

    /// Hardsigmoid 層を追加する（`nn::activation::Hardsigmoid`。PyTorch `nn.Hardsigmoid` 相当。
    /// イシュー #2679）。融合・常駐経路の扱いは [`Sequential::add_selu`] と同じ（保存は無引数 kind で対応。#3053）。
    pub fn add_hardsigmoid(mut self) -> Self {
        self.inner.push(Box::new(Hardsigmoid));
        self.specs.push(LayerSpec::Hardsigmoid);
        self
    }

    /// LogSigmoid 層を追加する（`nn::activation::LogSigmoid`。`log(sigmoid(x))`。PyTorch
    /// `nn.LogSigmoid` 相当。イシュー #2679）。融合・常駐経路の扱いは
    /// [`Sequential::add_selu`] と同じ（保存は無引数 kind で対応。#3053）。
    pub fn add_log_sigmoid(mut self) -> Self {
        self.inner.push(Box::new(LogSigmoid));
        self.specs.push(LayerSpec::LogSigmoid);
        self
    }

    /// Softmin 層を追加する（`nn::softmin_threshold::Softmin`。PyTorch `nn.Softmin(dim)` 相当。
    /// イシュー #2679）。`dim` の範囲検査は forward 時（[`Sequential::add_softmax`] と同じ遅延検査契約）。
    /// 融合・常駐経路の扱いは [`Sequential::add_selu`] と同じ。保存は kind `softmin`
    /// （`params`: `dim`）で往復できる（イシュー #3054）。
    /// `forward_host` は未提供のため `predict` は tape 経路へフォールバックする。
    pub fn add_softmin(mut self, dim: usize) -> Self {
        self.inner.push(Box::new(Softmin::new(dim)));
        self.specs.push(LayerSpec::Softmin { dim });
        self
    }

    /// Tanhshrink 層を追加する（`nn::softmin_threshold::Tanhshrink`。`x - tanh(x)`。PyTorch
    /// `nn.Tanhshrink` 相当。イシュー #2679）。`save_model`／`load_model` は無引数 kind `tanhshrink` で往復できる（イシュー #3053）。
    pub fn add_tanhshrink(mut self) -> Self {
        self.inner.push(Box::new(Tanhshrink));
        self.specs.push(LayerSpec::Tanhshrink);
        self
    }

    /// Threshold 層を追加する（`nn::softmin_threshold::Threshold`。`x > threshold` ならそのまま、
    /// それ以外は `value`。PyTorch `nn.Threshold(threshold, value)` 相当。イシュー #2679）。
    /// 構築時検査は無い（`NaN` は IEEE のまま扱う）。保存は kind `threshold`
    /// （`params`: `threshold`・`value`）で往復でき、非有限は保存時に `UnsupportedModel`（イシュー #3054）。
    pub fn add_threshold(mut self, threshold: f32, value: f32) -> Self {
        self.inner.push(Box::new(Threshold::new(threshold, value)));
        self.specs.push(LayerSpec::Threshold { threshold, value });
        self
    }

    /// RReLU 層を追加する（`nn::softmin_threshold::RRelu`。PyTorch `nn.RReLU(lower, upper)` 相当。
    /// イシュー #2679）。`lower`／`upper` は有限かつ `lower <= upper`（違反は構築時に
    /// `AutodiffError::InvalidArgument`）。追加時点の `training` は `true` で、以後は
    /// [`Sequential::set_training`]／[`Sequential::eval`] の伝播で推論時の固定傾き
    /// `(lower + upper) / 2` へ切り替わる（[`Sequential::add_dropout`] と同じ）。学習時の傾きは
    /// グローバル RNG から引く。保存は kind `rrelu`（`params`: `lower`・`upper`）で往復でき、RNG 状態は
    /// 保存しない（eval で保存すれば決定的に往復。決定記録 #3052 §3。イシュー #3054）。
    pub fn add_rrelu(mut self, lower: f32, upper: f32) -> Result<Self, AutodiffError> {
        let layer = RRelu::new(lower, upper)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::RRelu { lower, upper });
        Ok(self)
    }

    /// Flatten 層を追加する（`nn::Flatten`。イシュー #2065）。
    /// `[start_dim, end_dim]`（両端含む）の連続軸を 1 軸へ潰す
    /// （`Var::flatten` への委譲。PyTorch `torch.flatten(start_dim,
    /// end_dim)` と同じ規約・負インデックスの糖衣構文は提供しない）。
    /// 典型例: CNN（`Conv2d`／pooling）の `[N, C, H, W]` 出力を
    /// `add_flatten(1, 3)` で `[N, C*H*W]` へ潰し `add_linear` へ渡す。
    /// shape 不整合は構築時ではなく forward 時に `AutodiffError::Shape`
    /// として現れるため、[`Sequential::add_softmax`] と同型の遅延検査
    /// 契約として `Result` を返さず `Self` を返す。
    pub fn add_flatten(mut self, start_dim: usize, end_dim: usize) -> Self {
        self.inner.push(Box::new(Flatten::new(start_dim, end_dim)));
        self.specs.push(LayerSpec::Flatten { start_dim, end_dim });
        self
    }

    /// Dropout 層を追加する（`nn::Dropout`。イシュー #1603）。`p`
    /// （drop 確率）が `[0, 1]` の範囲かつ有限であること（`Dropout::new`
    /// の検査。`add_linear` と同じく層構築の時点で早期に弾くため
    /// `Result` を返す）。追加時点の `training` は `true`（PyTorch
    /// `Module.training` の初期値と揃える）——以後は
    /// [`Sequential::set_training`]／[`Sequential::train`]／
    /// [`Sequential::eval`] でモデル全体のモードを切り替えると本層へ
    /// 伝播する（`Dropout` は本クレート内実装で唯一この伝播が実挙動差
    /// を生む層。モジュール doc 参照）。
    pub fn add_dropout(mut self, p: f32) -> Result<Self, AutodiffError> {
        let dropout = Dropout::new(p)?;
        self.inner.push(Box::new(dropout));
        self.specs.push(LayerSpec::Dropout { p });
        Ok(self)
    }

    /// チャネル単位 Dropout2d 層を追加する（`nn::Dropout2d`。イシュー #2528）。
    /// `[N, C, H, W]`（rank 4 限定）の `(n, c)` チャネルをまとめて確率 `p` で 0 に落とし、
    /// 残すチャネルは `1/(1-p)` 倍する。`p` は有限かつ `[0, 1]`（違反は `AutodiffError`）。
    /// rank 4 以外の入力は forward 時に `AutodiffError`（Shape）で拒否する。
    /// 追加時点の `training` は `true`。[`Sequential::set_training`]／[`Sequential::eval`]
    /// の伝播で恒等写像へ切り替わる（[`Sequential::add_dropout`] と同じ）。
    /// 学習可能パラメータを持たない無状態層のため学習経路・常駐経路をそのまま通過し、
    /// `save_model`／`load_model` に対応する。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut model = Sequential::new().add_dropout2d(0.5)?;
    /// model.eval();
    /// let x = Tensor::new((0..8).map(|v| v as f32).collect::<Vec<_>>(), &[1, 2, 2, 2])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.host_slice().into_owned(), x.host_slice().into_owned());
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_dropout2d(mut self, p: f32) -> Result<Self, AutodiffError> {
        let layer = Dropout2d::new(p)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Dropout2d { p });
        Ok(self)
    }

    /// AlphaDropout 層を追加する（`nn::AlphaDropout`。イシュー #2528）。SELU 系
    /// ネットワーク向けに、drop 後の出力が入力の平均・分散を保つようアフィン補正する。
    /// 入力 rank は任意。`p` の検査・`training` の扱い・学習／常駐／保存経路は
    /// [`Sequential::add_dropout2d`] と同じ。
    pub fn add_alpha_dropout(mut self, p: f32) -> Result<Self, AutodiffError> {
        let layer = AlphaDropout::new(p)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::AlphaDropout { p });
        Ok(self)
    }

    /// 2 次元畳み込み層を追加する（`nn::Conv2d`。イシュー #1770・親
    /// #1645。`docs/compat-api-scope.md` §5 手続き・親 #1645 コメント
    /// でユーザー承認済み）。bias あり既定（`add_linear` と同様。
    /// PyTorch `nn.Conv2d` の既定 `bias=True` と揃える）。`Conv2d::new`
    /// が `Result` を返す（`in_channels == 0`・groups 整合違反等を拒否。
    /// `nn/conv.rs` 参照）ため、本メソッドも `Result<Self, AutodiffError>`
    /// を返し `?` で連鎖できるようにする。
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.Conv2d` の全引数を受理する必要があるため（`add_linear` 系の先例と異なり dilation／groups を含むため 7 引数を超える）。
    pub fn add_conv2d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = Conv2d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::Conv2d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// 1 次元畳み込み層を追加する（`nn::Conv1d`。イシュー #1770）。
    /// [`Sequential::add_conv2d`] と同様 bias あり既定。
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.Conv1d` の全引数を受理する必要があるため。
    pub fn add_conv1d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: usize,
        stride: usize,
        padding: usize,
        dilation: usize,
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = Conv1d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::Conv1d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// 1 次元転置畳み込み層を追加する（`nn::ConvTranspose1d`。イシュー #2521・
    /// 親 #2520）。[`Sequential::add_conv1d`] に `output_padding` を加えた形で、
    /// bias あり固定。weight は `[in_channels, out_channels/groups, kernel_size]`。
    /// 出力長は PyTorch と同じ `(L-1)*stride - 2*padding + dilation*(k-1) +
    /// output_padding + 1`。`output_padding >= stride` や `groups` の割り切れ違反は
    /// `Err`。常駐経路は非対応（`BackendError::Unsupported`）、AMP 低精度は無視して
    /// f32 で forward する（Conv1d と同じ）。
    /// `save_model`／`load_model` は manifest kind `conv_transpose1d` で保存・復元できる
    /// （イシュー #3055）。
    ///
    /// # Examples
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::Tensor;
    ///
    /// let model = Sequential::new()
    ///     .add_conv_transpose1d(2, 3, 3, 2, 0, 0, 1, 1, 7)
    ///     .unwrap();
    /// let x = Tensor::new(vec![0.5_f32; 2 * 4], &[1, 2, 4]).unwrap();
    /// let y = model.predict(&x).unwrap();
    /// assert_eq!(y.shape(), &[1, 3, 9]);
    /// ```
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.ConvTranspose1d` の全引数を受理する必要があるため。
    pub fn add_conv_transpose1d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: usize,
        stride: usize,
        padding: usize,
        output_padding: usize,
        dilation: usize,
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = ConvTranspose1d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::ConvTranspose1d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// 3 次元畳み込み層を追加する（`nn::Conv3d`。NCDHW 固定。イシュー #2524・
    /// 親 #2520）。[`Sequential::add_conv2d`] の空間 3 軸版で、bias あり固定。
    /// weight は `[out_channels, in_channels/groups, kD, kH, kW]`。出力サイズは各軸
    /// `(D + 2*padding - dilation*(k-1) - 1) / stride + 1`。0 の stride／kernel・
    /// `in_channels == 0`・`groups` の割り切れ違反は `Err`。常駐経路は非対応
    /// （`BackendError::Unsupported`）、AMP 低精度は無視して f32 で forward する。
    /// `save_model`／`load_model` は manifest kind `conv3d` で保存・復元できる。
    ///
    /// # Examples
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::Tensor;
    ///
    /// let model = Sequential::new()
    ///     .add_conv3d(2, 3, [3, 3, 3], [1, 1, 1], [0, 0, 0], [1, 1, 1], 1, 7)
    ///     .unwrap();
    /// let x = Tensor::new(vec![0.5_f32; 2 * 4 * 4 * 4], &[1, 2, 4, 4, 4]).unwrap();
    /// let y = model.predict(&x).unwrap();
    /// assert_eq!(y.shape(), &[1, 3, 2, 2, 2]);
    /// ```
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.Conv3d` の全引数を受理する必要があるため。
    pub fn add_conv3d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 3],
        stride: [usize; 3],
        padding: [usize; 3],
        dilation: [usize; 3],
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = Conv3d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::Conv3d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// 2 次元転置畳み込み層を追加する（`nn::ConvTranspose2d`。イシュー #2523・
    /// 親 #2520）。[`Sequential::add_conv2d`] の `padding` の直後に `output_padding` を
    /// 加えた形で、bias あり固定。weight は `[in_channels, out_channels/groups, kH, kW]`
    /// （`Conv2d` と先頭 2 軸が逆）。出力サイズは PyTorch と同じ
    /// `(H-1)*stride - 2*padding + dilation*(k-1) + output_padding + 1`（各軸）。
    /// `output_padding >= stride`（意図的な PyTorch 非互換）・0 の stride／kernel・
    /// `groups` の割り切れ違反は `Err`。常駐経路は非対応（`BackendError::Unsupported`）、
    /// AMP 低精度は無視して f32 で forward する（`ConvTranspose1d` と同じ）。
    /// `save_model`／`load_model` は manifest kind `conv_transpose2d` で保存・復元できる。
    ///
    /// # Examples
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::Tensor;
    ///
    /// let model = Sequential::new()
    ///     .add_conv_transpose2d(2, 3, [3, 3], [2, 2], [0, 0], [0, 0], [1, 1], 1, 7)
    ///     .unwrap();
    /// let x = Tensor::new(vec![0.5_f32; 2 * 4 * 4], &[1, 2, 4, 4]).unwrap();
    /// let y = model.predict(&x).unwrap();
    /// assert_eq!(y.shape(), &[1, 3, 9, 9]);
    /// ```
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.ConvTranspose2d` の全引数を受理する必要があるため。
    pub fn add_conv_transpose2d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        output_padding: [usize; 2],
        dilation: [usize; 2],
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = ConvTranspose2d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::ConvTranspose2d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// 3 次元転置畳み込み層を追加する（`nn::ConvTranspose3d`。イシュー #3032・
    /// 親 #3018。公開形の正本は `docs/compat-sequential-3d-fold-lrn-layers-decision.md` §3）。
    /// [`Sequential::add_conv_transpose2d`] の 3 軸版で、bias あり固定。weight は
    /// `[in_channels, out_channels/groups, kD, kH, kW]`。出力サイズは PyTorch と同じ
    /// `(D-1)*stride - 2*padding + dilation*(k-1) + output_padding + 1`（各軸）。
    /// `output_padding >= stride`（意図的な PyTorch 非互換）・0 の stride／kernel・
    /// `groups` の割り切れ違反は `Err`。常駐経路は非対応（`BackendError::Unsupported`）、
    /// AMP 低精度は無視して f32 で forward する。`save_model`／`load_model` は kind
    /// `conv_transpose3d` として保存・復元できる（イシュー #3033。`seed` は保存しない）。
    ///
    /// # Examples
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::Tensor;
    ///
    /// let model = Sequential::new()
    ///     .add_conv_transpose3d(2, 3, [3, 3, 3], [2, 2, 2], [0, 0, 0], [0, 0, 0], [1, 1, 1], 1, 7)
    ///     .unwrap();
    /// let x = Tensor::new(vec![0.5_f32; 2 * 2 * 2 * 2], &[1, 2, 2, 2, 2]).unwrap();
    /// let y = model.predict(&x).unwrap();
    /// assert_eq!(y.shape(), &[1, 3, 5, 5, 5]);
    /// ```
    #[allow(clippy::too_many_arguments)] // PyTorch `nn.ConvTranspose3d` の全引数を受理する必要があるため。
    pub fn add_conv_transpose3d(
        mut self,
        in_channels: usize,
        out_channels: usize,
        kernel_size: [usize; 3],
        stride: [usize; 3],
        padding: [usize; 3],
        output_padding: [usize; 3],
        dilation: [usize; 3],
        groups: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let conv = ConvTranspose3d::new(
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
            true,
            seed,
        )?;
        self.inner.push(Box::new(conv));
        self.specs.push(LayerSpec::ConvTranspose3d {
            in_channels,
            out_channels,
            kernel_size,
            stride,
            padding,
            output_padding,
            dilation,
            groups,
        });
        Ok(self)
    }

    /// Unflatten 層を追加する（`nn::Unflatten`。イシュー #2521）。軸 `dim` を
    /// `unflattened_size` の複数軸へ展開する（[`Sequential::add_flatten`] の逆変換・
    /// `Var::unflatten` への委譲）。空の `unflattened_size` は `Unflatten::new` が
    /// 拒否するため `Result` を返す。`dim` 範囲・積の不一致は forward 時に
    /// `AutodiffError::Shape`。パラメータを持たず常駐経路も通過する。
    /// `save_model`／`load_model` は manifest kind `unflatten` で保存・復元できる
    /// （`sizes` は 1..=8 軸。固定キー `size_0`..`size_7`。イシュー #3055）。
    pub fn add_unflatten(
        mut self,
        dim: usize,
        unflattened_size: Vec<usize>,
    ) -> Result<Self, AutodiffError> {
        let layer = Unflatten::new(dim, unflattened_size.clone())?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Unflatten {
            dim,
            sizes: unflattened_size,
        });
        Ok(self)
    }

    /// LayerNorm 層を追加する（`nn::norm::LayerNorm`。イシュー #1760・
    /// 親 #1618）。affine あり既定（PyTorch `nn.LayerNorm` の既定
    /// `elementwise_affine=True` と揃える。affine なし構成を積みたい
    /// 場合は本 API では表現できず、対象外として `docs/compat-api-
    /// scope.md` へ記録する）。`normalized_size` は最終軸の要素数
    /// （`LayerNorm::new` の `hidden` 引数。最終軸限定契約は
    /// `docs/norm-ops-design.md` 参照）。`eps` は `LayerNorm::new` の
    /// 検査（有限・非負）に委ねる。
    pub fn add_layer_norm(
        mut self,
        normalized_size: usize,
        eps: f32,
    ) -> Result<Self, AutodiffError> {
        let layer = LayerNorm::new(normalized_size, eps)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::LayerNorm {
            normalized_size,
            eps,
        });
        Ok(self)
    }

    /// RMSNorm 層を追加する（`nn::norm::RmsNorm`。イシュー #1760）。
    /// [`Sequential::add_layer_norm`] と同様 affine あり既定・最終軸
    /// 限定契約。
    pub fn add_rms_norm(mut self, normalized_size: usize, eps: f32) -> Result<Self, AutodiffError> {
        let layer = RmsNorm::new(normalized_size, eps)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::RmsNorm {
            normalized_size,
            eps,
        });
        Ok(self)
    }

    /// GroupNorm 層を追加する（`nn::GroupNorm`。イシュー #2525・
    /// `docs/norm-ops-design.md` §11）。`[N, C, *S]` の C 軸を `groups` 個に分け、
    /// グループごと（グループ内チャネル × 空間）に平均 0・分散 1 へ正規化する。
    /// **affine（チャネルごとの weight／bias）は持たない**（f64 縮約契約との兼ね合いで
    /// 別 issue。`num_channels` 引数も内部層が保持しないため取らない）。
    /// `groups == 0`・非有限／負の `eps` は構築時に `AutodiffError::InvalidArgument`。
    /// `C % groups != 0` と rank < 2 は forward 時の遅延検査（[`Sequential::add_flatten`]
    /// と同型）。無状態層のため学習経路をそのまま通過し `save_model`／`load_model` に
    /// 対応する。デバイス常駐経路は未実測のため fail-closed で拒否する
    /// （`BackendError::Unsupported`）。ONNX export は `UnsupportedLayer`。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new()
    ///     .add_group_norm(2, 1e-5)?
    ///     .add_instance_norm(1e-5)?;
    /// let x = Tensor::new((0..36).map(|i| i as f32).collect::<Vec<_>>(), &[1, 4, 3, 3])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[1, 4, 3, 3]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_group_norm(mut self, groups: usize, eps: f32) -> Result<Self, AutodiffError> {
        let layer = GroupNorm::new(groups, eps)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::GroupNorm { groups, eps });
        Ok(self)
    }

    /// InstanceNorm 層を追加する（`nn::InstanceNorm`。イシュー #2525）。
    /// 各サンプル・各チャネルを空間軸ごとに独立に正規化する（`GroupNorm` の
    /// `groups == C` と bit 一致）。rank < 3 は forward 時の遅延検査。affine なし・
    /// 常駐経路拒否・保存対応は [`Sequential::add_group_norm`] と同じ。
    pub fn add_instance_norm(mut self, eps: f32) -> Result<Self, AutodiffError> {
        let layer = InstanceNorm::new(eps)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::InstanceNorm { eps });
        Ok(self)
    }

    /// BatchNorm1d 層を追加する（`nn::batch_norm::BatchNorm1d`。イシュー
    /// #1760）。affine あり既定（PyTorch `nn.BatchNorm1d` の既定
    /// `affine=True` と揃える）。受理する入力 rank は 2〈`[N, C]`〉／3
    /// 〈`[N, C, L]`〉（`docs/batch-norm-ops-design.md`）。`momentum` は
    /// `BatchNorm1d::new` の検査（`[0, 1]` かつ有限）に委ねる。
    ///
    /// **モードの注意**: `BatchNorm` は本クレート内で唯一 train／eval
    /// で挙動が変わる層（`Module::set_training` doc「モードの正は
    /// コンテナが保持するフラグ」契約参照）。追加直後は train モード
    /// （PyTorch `Module.training` の初期値と揃える）で、[`Sequential::
    /// predict`] が train モードのまま呼ばれると running stats が
    /// 呼び出しごとに更新される（決定的な推論には先に
    /// [`Sequential::eval`] を呼ぶこと）。
    pub fn add_batch_norm1d(
        mut self,
        num_features: usize,
        eps: f32,
        momentum: f32,
    ) -> Result<Self, AutodiffError> {
        let layer = BatchNorm1d::new(num_features, eps, momentum)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::BatchNorm1d {
            num_features,
            eps,
            momentum,
        });
        Ok(self)
    }

    /// BatchNorm2d 層を追加する（`nn::batch_norm::BatchNorm2d`。
    /// イシュー #1760）。[`Sequential::add_batch_norm1d`] と同様
    /// affine あり既定・モード契約。受理する入力 rank は 4
    /// 〈`[N, C, H, W]`〉のみ。
    pub fn add_batch_norm2d(
        mut self,
        num_features: usize,
        eps: f32,
        momentum: f32,
    ) -> Result<Self, AutodiffError> {
        let layer = BatchNorm2d::new(num_features, eps, momentum)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::BatchNorm2d {
            num_features,
            eps,
            momentum,
        });
        Ok(self)
    }

    /// `compat::model_io::load_model` 専用: running stats を持つ BatchNorm1d を積む
    /// （イシュー #2371）。`from_parameters` 経由で weight／bias／running stats を
    /// そのまま持つ層を作り、`LayerSpec` の `num_features` は `running_mean` の長さから決める。
    /// `num_batches_tracked` は復元されず 0 から始まる（forward の数値には影響しない）。
    /// 初期モードは train で、呼び出し側が直後に `set_training` で全層を揃える。
    pub(super) fn add_batch_norm1d_restored(
        mut self,
        weight: Tensor<f32>,
        bias: Tensor<f32>,
        running_mean: Tensor<f32>,
        running_var: Tensor<f32>,
        eps: f32,
        momentum: f32,
    ) -> Result<Self, AutodiffError> {
        let num_features = running_mean.shape().first().copied().unwrap_or(0);
        let layer = BatchNorm1d::from_parameters(
            Some(weight),
            Some(bias),
            running_mean,
            running_var,
            eps,
            momentum,
        )?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::BatchNorm1d {
            num_features,
            eps,
            momentum,
        });
        Ok(self)
    }

    /// [`Sequential::add_batch_norm1d_restored`] の BatchNorm2d 版（イシュー #2371）。
    pub(super) fn add_batch_norm2d_restored(
        mut self,
        weight: Tensor<f32>,
        bias: Tensor<f32>,
        running_mean: Tensor<f32>,
        running_var: Tensor<f32>,
        eps: f32,
        momentum: f32,
    ) -> Result<Self, AutodiffError> {
        let num_features = running_mean.shape().first().copied().unwrap_or(0);
        let layer = BatchNorm2d::from_parameters(
            Some(weight),
            Some(bias),
            running_mean,
            running_var,
            eps,
            momentum,
        )?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::BatchNorm2d {
            num_features,
            eps,
            momentum,
        });
        Ok(self)
    }

    /// Embedding 層を追加する（`nn::Embedding`。イシュー #1760）。
    /// 決定的シードで `N(0, 1)` 初期化する（`Embedding::new` 参照）。
    ///
    /// **入力契約（重要）**: `Module::forward` は f32 `Var` 入力契約
    /// だが embedding 本来の入力は整数クラス id であるため、本層を
    /// 通る [`Sequential::predict`]／学習 forward は入力の各要素を
    /// 厳格に整数 id へ変換する（`nn::embedding::EmbeddingVars::
    /// forward_from_var`。非有限・非整数・負・範囲外は
    /// `AutodiffError::InvalidArgument` で拒否——黙示の飽和・切り捨て
    /// 変換はしない。`.claude/rules/security.md` A03）。呼び出し側は
    /// id をあらかじめ `f32` として（例: `0.0, 3.0, 1.0, ...`）
    /// `Tensor<f32>` へ詰めて渡すこと。
    pub fn add_embedding(
        mut self,
        num_embeddings: usize,
        embedding_dim: usize,
        padding_idx: Option<usize>,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let layer = Embedding::new(num_embeddings, embedding_dim, padding_idx, seed)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Embedding {
            num_embeddings,
            embedding_dim,
            padding_idx,
        });
        Ok(self)
    }

    /// EmbeddingBag 層を追加する（`nn::EmbeddingBag`。イシュー #2528）。
    /// 長さの揃った bag（入力 `[B, L]`）の埋め込みを `mode`（`Sum`／`Mean`／`Max`）で
    /// 縮約して `[B, D]` を返す。決定的シードで `N(0, 1)` 初期化する
    /// （`EmbeddingBag::new` 参照。`num_embeddings == 0`・`padding_idx` の範囲外は
    /// `AutodiffError`）。
    ///
    /// **入力契約**: [`Sequential::add_embedding`] と同じく、入力は id を `f32` として
    /// 詰めた `Tensor<f32>`（各要素を厳格に整数 id へ変換する。非有限・非整数・負・範囲外は
    /// `AutodiffError::InvalidArgument`）。`padding_idx` に一致する id は縮約から除外する。
    /// 可変長 bag（offsets）は未公開。学習経路は `weight` を 1 件のパラメータとして
    /// 追跡する。常駐経路は `Unsupported` で fail-closed に拒否し、`save_model`／
    /// `load_model` に対応する（ONNX export は非対応）。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::{EmbeddingBagMode, Tensor};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_embedding_bag(8, 4, EmbeddingBagMode::Sum, None, 7)?;
    /// let ids = Tensor::new(vec![0.0_f32, 1.0, 2.0, 3.0, 4.0, 5.0], &[2, 3])?;
    /// let y = model.predict(&ids)?;
    /// assert_eq!(y.shape(), &[2, 4]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_embedding_bag(
        mut self,
        num_embeddings: usize,
        embedding_dim: usize,
        mode: EmbeddingBagMode,
        padding_idx: Option<usize>,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let layer = EmbeddingBag::new(num_embeddings, embedding_dim, mode, padding_idx, seed)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::EmbeddingBag {
            num_embeddings,
            embedding_dim,
            mode,
            padding_idx,
        });
        Ok(self)
    }

    /// MultiheadAttention 層を追加する（`nn::MultiheadAttention`。
    /// イシュー #1760）。`Module::forward` は self-attention
    /// （`q = k = v = input`・mask なし・非 causal。`nn/attention.rs`
    /// モジュール doc「`Module` trait との関係」参照）固定——
    /// cross-attention や `attn_mask`／causal 指定を本 API から渡す
    /// 経路は対象外。bias あり既定（`add_linear` と同様。PyTorch
    /// `nn.MultiheadAttention` の既定 `bias=True` と揃える）。
    /// `embed_dim % num_heads != 0` は `MultiheadAttention::new` が
    /// 拒否する。本メソッドは既定 config（`batch_first=true`・
    /// `kdim=vdim=embed_dim`）固定のまま——オプション指定版は
    /// [`Sequential::add_multihead_attention_with_config`]
    /// （イシュー #2530）を使う。
    pub fn add_multihead_attention(
        mut self,
        embed_dim: usize,
        num_heads: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let layer = MultiheadAttention::new(embed_dim, num_heads, true, seed)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::MultiheadAttention {
            embed_dim,
            num_heads,
        });
        Ok(self)
    }

    /// オプション指定付きの MultiheadAttention 層を追加する
    /// （`nn::MultiheadAttention::from_config`。イシュー #2530・ルート #2499。
    /// 承認記録は `docs/autodiff-mha-options-decision.md`）。
    ///
    /// `Module::forward` は self-attention（`q = k = v = input`・mask なし・
    /// 非 causal）固定のため、Sequential で選べるのは `bias` と `batch_first`
    /// のみ。`kdim`／`vdim` が `embed_dim` と異なる config は、`k_proj`／`v_proj`
    /// が `[.., embed_dim]` の入力を受けられず「使えないのに保存できる層」に
    /// なるため `AutodiffError::InvalidArgument` で fail-closed に拒否する。
    /// `key_padding_mask` は呼び出し時オプションで本 API の対象外。
    /// 0 次元・`embed_dim % num_heads != 0` は `from_config` が拒否する。
    /// `add_multihead_attention` の挙動・保存形式は変えない。
    ///
    /// `batch_first=false`（`[Len, B, E]`）の層を含むモデルは、`fit*`／`evaluate` が
    /// DataLoader の第 0 軸をサンプル軸として分割し系列を切断してしまうため
    /// `InvalidArgument` で拒否される（`predict`／forward は利用可能）。
    ///
    /// ```
    /// use fandhe_ai::compat::{MultiheadAttentionConfig, Sequential};
    ///
    /// let cfg = MultiheadAttentionConfig::new(8, 2).with_bias(false).with_batch_first(false);
    /// let model = Sequential::new().add_multihead_attention_with_config(cfg, 1).unwrap();
    /// assert_eq!(model.trainable_parameters().len(), 4);
    ///
    /// let bad = MultiheadAttentionConfig::new(8, 2).with_kdim(10);
    /// assert!(Sequential::new().add_multihead_attention_with_config(bad, 1).is_err());
    /// ```
    pub fn add_multihead_attention_with_config(
        mut self,
        config: MultiheadAttentionConfig,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        if config.kdim() != config.embed_dim() || config.vdim() != config.embed_dim() {
            return Err(AutodiffError::InvalidArgument(
                "add_multihead_attention_with_config: Sequential の self-attention では \
                 kdim/vdim = embed_dim 必須（kdim/vdim 指定は未対応）"
                    .to_string(),
            ));
        }
        let layer = MultiheadAttention::from_config(&config, seed)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::MultiheadAttentionConfig {
            embed_dim: config.embed_dim(),
            num_heads: config.num_heads(),
            bias: config.bias(),
            batch_first: config.batch_first(),
        });
        Ok(self)
    }

    /// TransformerEncoderLayer 層を追加する
    /// （`nn::TransformerEncoderLayer`。イシュー #2068・親 #2059）。
    /// self-attention（`q = k = v = current`・mask なし・非 causal）→
    /// residual → LayerNorm → FFN（`relu` 活性化固定）→ residual →
    /// LayerNorm の post-norm 合成（PyTorch `nn.TransformerEncoderLayer`
    /// の既定 `norm_first=False`・`activation="relu"` と揃える）。
    /// Dropout は結線しない（PyTorch 既定 `dropout=0.1` を省略。
    /// `nn/transformer_encoder_layer.rs` モジュール doc「対象外」参照）。
    /// `eps` は `nn::LAYER_NORM_DEFAULT_EPS`（PyTorch `nn.LayerNorm`
    /// 既定）固定。bias あり既定（`add_multihead_attention` と同様）。
    /// `d_model % num_heads != 0`・`dim_feedforward == 0` は
    /// `TransformerEncoderLayer::new` が拒否する。
    pub fn add_transformer_encoder(
        mut self,
        d_model: usize,
        num_heads: usize,
        dim_feedforward: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let layer = TransformerEncoderLayer::new(
            d_model,
            num_heads,
            dim_feedforward,
            FeedForwardActivation::Relu,
            LAYER_NORM_DEFAULT_EPS,
            seed,
        )?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::TransformerEncoder {
            d_model,
            num_heads,
            dim_feedforward,
        });
        Ok(self)
    }

    /// TransformerDecoderLayer 層を追加する
    /// （`nn::TransformerDecoderLayer`。イシュー #2532・親 #2531・ルート #2499 の
    /// 一括承認。`docs/autodiff-transformer-decoder-decision.md`）。
    /// self-attention → residual → LayerNorm → cross-attention → residual →
    /// LayerNorm → FFN（`relu` 活性化固定）→ residual → LayerNorm の post-norm 合成
    /// （PyTorch `nn.TransformerDecoderLayer` の既定 `norm_first=False`・
    /// `activation="relu"` と揃える）。
    ///
    /// `Sequential` は単一入力列のため `tgt = memory = 直前層の出力`・mask なし・
    /// 非 causal 固定で呼ぶ（cross-attention は自身の入力を参照する。
    /// `nn::Module for TransformerDecoderLayer::forward` と同じ意味論で、
    /// `predict` と `bind().forward` が bit 一致する）。`tgt`／`memory` を別々に
    /// 与える 2 入力 API・mask・causal 指定は本メソッドの対象外。Dropout は結線しない。
    /// `eps` は `nn::LAYER_NORM_DEFAULT_EPS` 固定。
    /// `d_model == 0`・`dim_feedforward == 0`・`d_model % num_heads != 0` は
    /// `TransformerDecoderLayer::new` が拒否する。デバイス常駐経路は未対応
    /// （`BackendError::Unsupported`）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_transformer_decoder_layer(4, 2, 8, 0)?;
    /// let x = Tensor::new(vec![0.1f32; 2 * 3 * 4], &[2, 3, 4])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[2, 3, 4]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_transformer_decoder_layer(
        mut self,
        d_model: usize,
        num_heads: usize,
        dim_feedforward: usize,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        let layer = TransformerDecoderLayer::new(
            d_model,
            num_heads,
            dim_feedforward,
            FeedForwardActivation::Relu,
            LAYER_NORM_DEFAULT_EPS,
            seed,
        )?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::TransformerDecoderLayer {
            d_model,
            num_heads,
            dim_feedforward,
        });
        Ok(self)
    }

    /// Transformer（encoder スタック＋decoder スタック。`nn::Transformer`）層を追加する
    /// （イシュー #2533・親 #2531・ルート #2499 の一括承認。
    /// `docs/autodiff-transformer-decoder-decision.md`）。
    /// encoder（TransformerEncoderLayer を `num_encoder_layers` 段 → 最終 LayerNorm）と
    /// decoder（TransformerDecoderLayer を `num_decoder_layers` 段 → 最終 LayerNorm）の
    /// post-norm 合成で、PyTorch `nn.Transformer`（`norm_first=False`・
    /// `activation="relu"`）と揃える。構成は `TransformerConfig`（`fandhe_ai::nn`）で与える。
    ///
    /// `Sequential` は単一入力列のため `src = tgt = 直前層の出力`・mask なし・
    /// 非 causal 固定で呼ぶ（`nn::Module for Transformer::forward` と同じ意味論で、
    /// `predict` と `bind().forward` が bit 一致する）。`src`／`tgt` を別々に与える
    /// 2 入力 API・mask・causal 指定は本メソッドの対象外。Dropout は結線しない。
    /// 活性化は `relu` のみ対応で、`TransformerConfig::with_activation` で他を指定した
    /// 場合は `InvalidArgument`（`FeedForwardActivation` は facade から到達できず、
    /// 保存 manifest にも活性化を持たせないため。fail-closed）。
    /// 層数 0・`d_model == 0`・`dim_feedforward == 0`・`d_model % num_heads != 0` は
    /// `Transformer::new` が拒否する。パラメータ数は
    /// `16 * num_encoder_layers + 2 + 26 * num_decoder_layers + 2`。デバイス常駐経路は
    /// 未対応（`BackendError::Unsupported`）。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::nn::TransformerConfig;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let config = TransformerConfig::new(4, 2)
    ///     .with_num_encoder_layers(1)
    ///     .with_num_decoder_layers(1)
    ///     .with_dim_feedforward(8);
    /// let model = Sequential::new().add_transformer(config, 0)?;
    /// let x = Tensor::new(vec![0.1f32; 2 * 3 * 4], &[2, 3, 4])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[2, 3, 4]);
    /// assert_eq!(model.trainable_parameters().len(), 16 + 2 + 26 + 2);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_transformer(
        mut self,
        config: TransformerConfig,
        seed: u64,
    ) -> Result<Self, AutodiffError> {
        if config.activation() != FeedForwardActivation::Relu {
            return Err(AutodiffError::InvalidArgument(
                "add_transformer: 活性化は relu のみ対応（保存 manifest に活性化を持たせないため。\
                 イシュー #2533）"
                    .to_string(),
            ));
        }
        let layer = Transformer::new(&config, seed)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Transformer {
            d_model: config.d_model(),
            num_heads: config.num_heads(),
            num_encoder_layers: config.num_encoder_layers(),
            num_decoder_layers: config.num_decoder_layers(),
            dim_feedforward: config.dim_feedforward(),
            eps: config.eps(),
        });
        Ok(self)
    }

    /// 2 次元 MaxPool 層を追加する（`nn::MaxPool2d`。イシュー #1957・
    /// 親 #1618。2026-09-17 ユーザー承認〈選択肢 A・6 メソッド一括
    /// 追加〉）。`ceil_mode=false` 固定（`MaxPool2d::new` doc 参照）。
    /// `stride` を省略（`None`）すると `kernel_size` と同じ値になる
    /// （PyTorch `nn.MaxPool2d` の既定と同じ）。入力は `NCHW`（rank 4）。
    /// 無状態層のため学習可能パラメータを持たない（`named_parameters`
    /// は空のまま。`nn/pooling.rs` モジュール doc 参照）。
    pub fn add_max_pool2d(
        mut self,
        kernel_size: [usize; 2],
        stride: Option<[usize; 2]>,
        padding: [usize; 2],
        dilation: [usize; 2],
    ) -> Result<Self, AutodiffError> {
        let layer = MaxPool2d::new(kernel_size, stride, padding, dilation)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::MaxPool2d {
            kernel_size,
            stride,
            padding,
            dilation,
        });
        Ok(self)
    }

    /// 1 次元 MaxPool 層を追加する（`nn::MaxPool1d`。イシュー #1957）。
    /// [`Sequential::add_max_pool2d`] と同様 `ceil_mode=false` 固定。
    /// 入力は `NCL`（rank 3）。
    pub fn add_max_pool1d(
        mut self,
        kernel_size: usize,
        stride: Option<usize>,
        padding: usize,
        dilation: usize,
    ) -> Result<Self, AutodiffError> {
        let layer = MaxPool1d::new(kernel_size, stride, padding, dilation)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::MaxPool1d {
            kernel_size,
            stride,
            padding,
            dilation,
        });
        Ok(self)
    }

    /// 2 次元 AvgPool 層を追加する（`nn::AvgPool2d`。イシュー #1957）。
    /// `ceil_mode=false` 固定・`dilation=[1,1]` 固定（`AvgPool2d::new`
    /// doc 参照）。`count_include_pad` は PyTorch `nn.AvgPool2d` の
    /// 同名引数と同じ意味（`true` で padding 領域も分母に含める）。
    /// 入力は `NCHW`（rank 4）。
    pub fn add_avg_pool2d(
        mut self,
        kernel_size: [usize; 2],
        stride: Option<[usize; 2]>,
        padding: [usize; 2],
        count_include_pad: bool,
    ) -> Result<Self, AutodiffError> {
        let layer = AvgPool2d::new(kernel_size, stride, padding, count_include_pad)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::AvgPool2d {
            kernel_size,
            stride,
            padding,
            count_include_pad,
        });
        Ok(self)
    }

    /// 3 次元 MaxPool 層を追加する（`nn::MaxPool3d`。PyTorch `nn.MaxPool3d` 相当。イシュー #3028・
    /// 公開形の正は `docs/compat-sequential-3d-fold-lrn-layers-decision.md` §3）。
    /// `ceil_mode=false` 固定。`stride` を省略（`None`）すると `kernel_size` と同じ値になる。
    /// 入力は `NCDHW`（rank 5）。無状態層で学習可能パラメータを持たず、値のみ返す（索引は返さない）。
    /// 不正引数（0 次元・`2*padding > kernel_size`）は `Pool3dParams::new` の検査で `Err` になり panic しない。
    /// 常駐経路は `is_pooling` 経由で `Unsupported`（fail-closed）。`save_model` は `max_pool3d` kind
    /// として保存・復元できる（イシュー #3029）。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// let model = Sequential::new().add_max_pool3d([2, 2, 2], None, [0, 0, 0], [1, 1, 1]);
    /// assert!(model.is_ok());
    /// ```
    pub fn add_max_pool3d(
        mut self,
        kernel_size: [usize; 3],
        stride: Option<[usize; 3]>,
        padding: [usize; 3],
        dilation: [usize; 3],
    ) -> Result<Self, AutodiffError> {
        let layer = MaxPool3d::new(kernel_size, stride, padding, dilation)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::MaxPool3d {
            kernel_size,
            stride,
            padding,
            dilation,
        });
        Ok(self)
    }

    /// 2 次元 Unfold 層を追加する（`nn::Unfold`。PyTorch `nn.Unfold` 相当。イシュー #3040・公開形の正は
    /// `docs/compat-sequential-3d-fold-lrn-layers-decision.md` §3）。
    /// 引数順は PyTorch（`dilation, padding, stride`）ではなく `kernel_size, stride, padding, dilation`
    /// （`docs/autodiff-fold-unfold-decision.md` §12.2）。入力 `[N, C, H, W]` → 出力 `[N, C·kH·kW, L]`
    /// （バッチなし入力は非対応）。無状態層で学習可能パラメータを持たない。
    /// 不正引数（0 次元・`2*padding` オーバーフロー）は `Unfold::new` の検査で `Err` になり panic しない。
    /// 常駐経路は未実測のため `Unsupported`（fail-closed。決定記録 §5）。`save_model` は kind `unfold`／`fold`
    /// として保存・復元できる（イシュー #3041）。ONNX export は `UnsupportedLayer`。AMP 低精度は無視して f32 で計算する。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// let model = Sequential::new().add_unfold([2, 2], [1, 1], [0, 0], [1, 1]);
    /// assert!(model.is_ok());
    /// ```
    pub fn add_unfold(
        mut self,
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
    ) -> Result<Self, AutodiffError> {
        let layer = Unfold::new(kernel_size, stride, padding, dilation)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Unfold {
            kernel_size,
            stride,
            padding,
            dilation,
        });
        Ok(self)
    }

    /// 2 次元 Fold 層を追加する（`nn::Fold`。PyTorch `nn.Fold` 相当。イシュー #3040）。
    /// [`Sequential::add_unfold`] の逆演算で、入力 `[N, C·kH·kW, L]` → 出力 `[N, C, oH, oW]`
    /// （`output_size = [oH, oW]`。重なる窓は加算）。引数順・常駐／保存／ONNX の扱いは
    /// [`Sequential::add_unfold`] と同じ。`output_size` の 0 も `Err`。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// let model = Sequential::new().add_fold([4, 4], [2, 2], [1, 1], [0, 0], [1, 1]);
    /// assert!(model.is_ok());
    /// let round = Sequential::new()
    ///     .add_unfold([2, 2], [1, 1], [0, 0], [1, 1])
    ///     .and_then(|m| m.add_fold([4, 4], [2, 2], [1, 1], [0, 0], [1, 1]));
    /// assert!(round.is_ok());
    /// ```
    pub fn add_fold(
        mut self,
        output_size: [usize; 2],
        kernel_size: [usize; 2],
        stride: [usize; 2],
        padding: [usize; 2],
        dilation: [usize; 2],
    ) -> Result<Self, AutodiffError> {
        let layer = Fold::new(output_size, kernel_size, stride, padding, dilation)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Fold {
            output_size,
            kernel_size,
            stride,
            padding,
            dilation,
        });
        Ok(self)
    }

    /// LocalResponseNorm 層を追加する（`nn::LocalResponseNorm`。PyTorch `nn.LocalResponseNorm` 相当。
    /// イシュー #3044・公開形の正は `docs/compat-sequential-3d-fold-lrn-layers-decision.md` §3）。
    /// 引数は `size, alpha, beta, k` を全て明示する（PyTorch の既定値は設けない）。入力は `[N, C, *]`
    /// （rank 3 以上）で、チャネル軸方向の局所応答正規化を行う。無状態層で学習可能パラメータを持たず、
    /// `size > C` も受理する。不正引数（`size == 0`・非有限な `alpha`／`beta`／`k`）は
    /// `LocalResponseNorm::new` の検査で `Err` になり panic しない。入力 rank が不正な場合は forward 時に `Err`。
    /// 常駐経路は未実測のため `Unsupported`（fail-closed。決定記録 §5）。kind `local_response_norm` として
    /// `save_model` で保存・復元できる（イシュー #3045）。ONNX export は `UnsupportedLayer`。AMP 低精度は無視して f32 で計算する。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// let model = Sequential::new().add_local_response_norm(3, 1e-4, 0.75, 1.0);
    /// assert!(model.is_ok());
    /// let zero = Sequential::new().add_local_response_norm(0, 1e-4, 0.75, 1.0);
    /// assert!(zero.is_err());
    /// ```
    pub fn add_local_response_norm(
        mut self,
        size: usize,
        alpha: f32,
        beta: f32,
        k: f32,
    ) -> Result<Self, AutodiffError> {
        let layer = LocalResponseNorm::new(size, alpha, beta, k)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::LocalResponseNorm {
            size,
            alpha,
            beta,
            k,
        });
        Ok(self)
    }

    /// 3 次元 AvgPool 層を追加する（`nn::AvgPool3d`。PyTorch `nn.AvgPool3d` 相当。イシュー #3028）。
    /// `ceil_mode=false`・`dilation=[1,1,1]` 固定。`count_include_pad` は PyTorch の同名引数と同じ意味。
    /// 入力は `NCDHW`（rank 5）。その他の契約（常駐は `Unsupported`・保存は後続 issue まで
    /// `UnsupportedModel`）は [`Sequential::add_max_pool3d`] と同じ。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// let model = Sequential::new().add_avg_pool3d([2, 2, 2], None, [0, 0, 0], true);
    /// assert!(model.is_ok());
    /// ```
    pub fn add_avg_pool3d(
        mut self,
        kernel_size: [usize; 3],
        stride: Option<[usize; 3]>,
        padding: [usize; 3],
        count_include_pad: bool,
    ) -> Result<Self, AutodiffError> {
        let layer = AvgPool3d::new(kernel_size, stride, padding, count_include_pad)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::AvgPool3d {
            kernel_size,
            stride,
            padding,
            count_include_pad,
        });
        Ok(self)
    }

    /// 1 次元 AvgPool 層を追加する（`nn::AvgPool1d`。イシュー #1957）。
    /// [`Sequential::add_avg_pool2d`] と同様 `ceil_mode=false` 固定。
    /// 入力は `NCL`（rank 3）。
    pub fn add_avg_pool1d(
        mut self,
        kernel_size: usize,
        stride: Option<usize>,
        padding: usize,
        count_include_pad: bool,
    ) -> Result<Self, AutodiffError> {
        let layer = AvgPool1d::new(kernel_size, stride, padding, count_include_pad)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::AvgPool1d {
            kernel_size,
            stride,
            padding,
            count_include_pad,
        });
        Ok(self)
    }

    /// 2 次元 AdaptiveAvgPool 層を追加する（`nn::AdaptiveAvgPool2d`。
    /// イシュー #1957）。`output_size` の各軸が `0` の場合は
    /// `AutodiffError::InvalidArgument`（`AdaptiveAvgPool2d::new`
    /// doc 参照）。入力は `NCHW`（rank 4）。
    pub fn add_adaptive_avg_pool2d(
        mut self,
        output_size: [usize; 2],
    ) -> Result<Self, AutodiffError> {
        let layer = AdaptiveAvgPool2d::new(output_size)?;
        self.inner.push(Box::new(layer));
        self.specs
            .push(LayerSpec::AdaptiveAvgPool2d { output_size });
        Ok(self)
    }

    /// 1 次元 AdaptiveAvgPool 層を追加する（`nn::AdaptiveAvgPool1d`。
    /// イシュー #1957）。`output_size` が `0` の場合は
    /// `AutodiffError::InvalidArgument`。入力は `NCL`（rank 3）。
    pub fn add_adaptive_avg_pool1d(mut self, output_size: usize) -> Result<Self, AutodiffError> {
        let layer = AdaptiveAvgPool1d::new(output_size)?;
        self.inner.push(Box::new(layer));
        self.specs
            .push(LayerSpec::AdaptiveAvgPool1d { output_size });
        Ok(self)
    }

    /// 2 次元 AdaptiveMaxPool 層を追加する（`nn::AdaptiveMaxPool2d`。イシュー #2527）。
    /// 入力 `[N, C, H, W]` → 出力 `[N, C, Hout, Wout]`（PyTorch `nn.AdaptiveMaxPool2d`
    /// 相当。forward は値のみを返し、索引が要る場合は [`crate::Var::adaptive_max_pool2d`]）。
    /// `output_size` に `0` を含む場合は `AutodiffError`。学習可能パラメータを持たない
    /// 無状態層のため学習経路をそのまま通過し、常駐経路は Pooling 層として `Unsupported`
    /// で fail-closed に拒否され、`save_model`／`load_model` に対応する。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_adaptive_max_pool2d([2, 2])?;
    /// let x = Tensor::new((0..16).map(|v| v as f32).collect::<Vec<_>>(), &[1, 1, 4, 4])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[1, 1, 2, 2]);
    /// assert_eq!(y.host_slice().into_owned(), [5.0, 7.0, 13.0, 15.0]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_adaptive_max_pool2d(
        mut self,
        output_size: [usize; 2],
    ) -> Result<Self, AutodiffError> {
        let layer = AdaptiveMaxPool2d::new(output_size)?;
        self.inner.push(Box::new(layer));
        self.specs
            .push(LayerSpec::AdaptiveMaxPool2d { output_size });
        Ok(self)
    }

    /// 1 次元 AdaptiveMaxPool 層を追加する（`nn::AdaptiveMaxPool1d`。イシュー #2527）。
    /// 入力は `NCL`（rank 3）。`output_size` が `0` の場合は `AutodiffError`。
    /// 学習・常駐・保存経路の扱いは [`Sequential::add_adaptive_max_pool2d`] と同じ。
    pub fn add_adaptive_max_pool1d(mut self, output_size: usize) -> Result<Self, AutodiffError> {
        let layer = AdaptiveMaxPool1d::new(output_size)?;
        self.inner.push(Box::new(layer));
        self.specs
            .push(LayerSpec::AdaptiveMaxPool1d { output_size });
        Ok(self)
    }

    /// GlobalPool 層を追加する（`nn::GlobalPool`。イシュー #2527）。空間軸全体を
    /// 単一値へ縮約する（Keras `GlobalAveragePooling*`／`GlobalMaxPooling*`・ONNX
    /// `GlobalAveragePool`／`GlobalMaxPool` 相当）。rank 3・rank 4 を受理し、
    /// `keepdims = true` は空間軸を `1` のまま残し（`[N,C,1]`／`[N,C,1,1]`）、
    /// `false` は `[N,C]` へ潰す。構築は失敗しないため `Self` を返す
    /// （[`Sequential::add_identity`] と同型）。rank の検査は forward 時に行う。
    /// 学習・常駐・保存経路の扱いは [`Sequential::add_adaptive_max_pool2d`] と同じ。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::{GlobalPoolMode, Tensor};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_global_pool(GlobalPoolMode::Max, false);
    /// let x = Tensor::new((0..8).map(|v| v as f32).collect::<Vec<_>>(), &[1, 2, 2, 2])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[1, 2]);
    /// assert_eq!(y.host_slice().into_owned(), [3.0, 7.0]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_global_pool(mut self, mode: GlobalPoolMode, keepdims: bool) -> Self {
        self.inner.push(Box::new(GlobalPool::new(mode, keepdims)));
        self.specs.push(LayerSpec::GlobalPool { mode, keepdims });
        self
    }

    /// Upsample 層を追加する（`nn::Upsample::with_size`。イシュー #2522・
    /// `docs/autodiff-spatial-layers-decision.md` §6）。出力の空間サイズ `size`
    /// を明示指定する形のみ公開する（`scale_factor` 指定は未公開。決定記録 §6 参照）。
    /// `size` が空なら構築時に `AutodiffError::InvalidArgument`。`mode` と空間軸数の
    /// 整合は forward 時に検査する遅延検査（[`Sequential::add_flatten`] と同型）。
    /// 学習可能パラメータを持たない無状態層のため学習経路・常駐経路をそのまま通過し、
    /// `save_model`／`load_model` に対応する。
    ///
    /// ```
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::{InterpolateMode, Tensor};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new()
    ///     .add_zero_pad2d([1, 1, 1, 1])
    ///     .add_upsample(vec![8, 8], InterpolateMode::Nearest)?
    ///     .add_identity();
    /// let x = Tensor::new(vec![1.0_f32; 9], &[1, 1, 3, 3])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[1, 1, 8, 8]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_upsample(
        mut self,
        size: Vec<usize>,
        mode: InterpolateMode,
    ) -> Result<Self, AutodiffError> {
        let layer = Upsample::with_size(size.clone(), mode)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::Upsample { size, mode });
        Ok(self)
    }

    /// ZeroPad2d 層を追加する（`nn::ZeroPad2d`。イシュー #2522）。`padding` は
    /// `[left, right, top, bottom]`（PyTorch `nn.ZeroPad2d` の 4-tuple と同順）で、
    /// 末尾 2 軸 `(H, W)` を 0 埋めする（`Var::pad` への委譲）。shape 不整合は
    /// forward 時の `AutodiffError::Shape`（遅延検査のため `Self` を返す）。
    /// 無状態層で、学習・常駐経路を通過し保存に対応する。
    pub fn add_zero_pad2d(mut self, padding: [usize; 4]) -> Self {
        self.inner.push(Box::new(ZeroPad2d::new(padding)));
        self.specs.push(LayerSpec::ZeroPad2d { padding });
        self
    }

    /// PixelShuffle 層を追加する（`nn::PixelShuffle`。イシュー #2526）。
    /// `[*, C*r*r, H, W]` を `[*, C, H*r, W*r]` へ並べ替える（`r = upscale_factor`・
    /// PyTorch `nn.PixelShuffle` 相当・`Var::pixel_shuffle` と同一の共有 forward）。`0` は即時
    /// `Err`（`AutodiffError::InvalidArgument`）で、rank 3 未満・チャネル軸の非整除は
    /// forward 時の `Err`（遅延検査）。無状態層で、学習・常駐経路を通過し保存に対応する。
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let model = Sequential::new().add_pixel_shuffle(2)?;
    /// let x = Tensor::new(vec![0.0_f32, 1.0, 2.0, 3.0], &[1, 4, 1, 1])?;
    /// let y = model.predict(&x)?;
    /// assert_eq!(y.shape(), &[1, 1, 2, 2]);
    /// # Ok(())
    /// # }
    /// ```
    pub fn add_pixel_shuffle(mut self, upscale_factor: usize) -> Result<Self, AutodiffError> {
        let layer = PixelShuffle::new(upscale_factor)?;
        self.inner.push(Box::new(layer));
        self.specs.push(LayerSpec::PixelShuffle { upscale_factor });
        Ok(self)
    }

    /// PixelUnshuffle 層を追加する（`nn::PixelUnshuffle`。イシュー #2526）。
    /// [`Sequential::add_pixel_shuffle`] の逆変換で、`[*, C, H*r, W*r]` を
    /// `[*, C*r*r, H, W]` へ並べ替える（`r = downscale_factor`）。エラー条件・無状態層としての
    /// 扱いは `add_pixel_shuffle` と同じ。
    pub fn add_pixel_unshuffle(mut self, downscale_factor: usize) -> Result<Self, AutodiffError> {
        let layer = PixelUnshuffle::new(downscale_factor)?;
        self.inner.push(Box::new(layer));
        self.specs
            .push(LayerSpec::PixelUnshuffle { downscale_factor });
        Ok(self)
    }

    /// Identity 層を追加する（`nn::Identity`。イシュー #2522）。入力をそのまま返す
    /// 無状態層（PyTorch `nn.Identity` 相当）。学習・常駐経路を通過し保存に対応する。
    pub fn add_identity(mut self) -> Self {
        self.inner.push(Box::new(Identity::new()));
        self.specs.push(LayerSpec::Identity);
        self
    }

    /// facade 独自の [`crate::nn::Module`] 実装（利用者が facade だけに依存して書いた独自層）を
    /// 末尾へ積む（イシュー #2398。#2338 承認事項 4・2026-09-29 ユーザー承認の唯一の公開入口。
    /// `docs/facade-nn-module-exposure-decision.md` §9 の「`add_module` はスコープ外」を上書きする）。
    /// 内部では crate 内専用アダプタ `FacadeModuleAdapter`（#2397）で autodiff 側 `Module` へ包む。
    ///
    /// - 推論: アダプタは `supports_forward_host() == false` のため [`Sequential::predict`] は
    ///   tape 経路で動く。`forward`／`state_dict`／`load_state_dict` も動き、`state_dict` の
    ///   キーは `"{index}.{name}"`（`index` は層の追加順）。
    /// - 学習契約（fail-closed）: 独自層が学習可能パラメータを持つ場合、[`Sequential::bind`] は
    ///   その層を追跡しない（facade `Module::forward` は forward 内で葉を登録するため、事前登録した
    ///   `Var` を差し込めず勾配を取り出せない）。学習されないまま成功する状態を作らないよう、
    ///   `fit` 系・`SequentialVars::forward`・`SequentialVars::trainable_grads` は
    ///   `AutodiffError::InvalidArgument`、デバイス常駐経路（`init_device_param_store`／
    ///   `forward_resident`／`predict_resident`）は `Unsupported` で型付き拒否する。
    ///   パラメータを持たない独自層は活性化層と同じ扱いで学習・常駐経路を通過する。
    ///   [`Sequential::apply_parameters`] は独自層の値も実際に更新する。
    /// - `push` 後にモードを同期しない（`add_dropout`・`NnSequential::push` と同じ契約）。
    pub fn add_module<M: crate::nn::Module + 'static>(mut self, m: M) -> Self {
        let boxed: Box<dyn crate::nn::Module> = Box::new(m);
        self.inner
            .push(Box::new(crate::nn::FacadeModuleAdapter(boxed)));
        self.specs.push(LayerSpec::Unsupported { kind: "module" });
        self
    }

    /// 積み上げた層を先頭から順に `Module::forward` へ委譲する。
    /// 呼び出し元が用意した `tape` 上で 1 回分の forward を計算する
    /// （`Linear::bind` がステップごとに葉ノードを登録し直す契約に従う。
    /// `fandhe_ai_autodiff::nn::module` 参照）。外部 `Tape` 上で呼ぶことで
    /// `Tape::backward` までグラフ記録がつながる（推論だけでなく
    /// grad check 等の用途にも使える）。
    ///
    /// **イシュー #1759 での再構成**: Linear→ReLU 融合先読み走査
    /// （旧イシュー #1044・`docs/kernel-fusion.md` §2.2「学習経路への
    /// 結線」）を含む本体は `fandhe_ai_autodiff::nn::Sequential::forward`
    /// へ移設済み。`nn::Module::forward` と同じく `tape.0`（`pub(crate)`
    /// フィールド）経由で内部の生 `Tape` を渡すだけの薄い委譲（本ファイル
    /// 冒頭 doc「公開シグネチャの型」参照）。
    pub fn forward<'t>(&self, tape: &'t Tape, input: &Var<'t>) -> Result<Var<'t>, AutodiffError> {
        self.inner.forward(&tape.0, input)
    }

    /// 推論の入口（受け入れ条件「Sequential でのモデル構築・推論が
    /// 動作する」を満たす API）。内部で [`crate::tape`]（本クレートの
    /// composition root。既定 CPU・`CpuBackendOps`・融合有効）で 1
    /// ステップ分の `Tape` を生成し `forward` を呼んだ後 `to_tensor()`
    /// で追跡を外した `Tensor<f32>` を返す（`Tape` はこの呼び出しの
    /// スコープ内で破棄される。`fandhe_ai_autodiff::nn::linear` の「`Tape` は
    /// ステップごとに生成・破棄される前提」と同じ運用）。
    ///
    /// **TASK-9.4（#411）**: 旧 `fandhe_ai_autodiff::compat` 版が持っていた
    /// `predict_with_ops`（任意 `BackendOps` 注入経路）は本移設で公開面
    /// から撤去した（モジュール doc 参照）。
    ///
    /// **イシュー #1028（`docs/inference-forward-fixed-cost-design.md`
    /// §3.1「段階 A」）**: 内部実装は tape 不要経路
    /// （`predict_tape_free`。非公開の内部メソッドのためリンクなし）
    /// を優先し、層構成が `Module::forward_host` 未対応
    /// （`BackendError::Unsupported`）の場合のみ旧経路
    /// （`predict_via_tape`。同じく非公開。`Tape::var` の葉
    /// クローン・ノード記録を伴う）へ fail-closed にフォールバックする。
    /// `docs/compat-api-scope.md` §1 の 3 種（Linear・ReLU/Sigmoid/Tanh）
    /// はいずれも tape 不要経路に対応済みのため（`nn/module.rs` の
    /// 各 `forward_host` オーバーライド）、通常はフォールバックへ
    /// 到達しない。公開シグネチャ・戻り値・数値結果は変更しない
    /// （新旧経路の bit 完全一致は `sequential_predict_tape_free_matches_via_tape_bit_exact`
    /// で検証）。
    ///
    /// **train／eval モードの扱い（イシュー #1603・#1758）**: 本メソッド
    /// は層の `training` フラグ（既定 `true`）を尊重する——
    /// [`Sequential::add_dropout`] を含むモデルに対し `eval()` を呼ばず
    /// に `predict` すると、PyTorch `model(x)` が `model.training` に
    /// 従うのと同じく `Dropout` はマスクを適用する。決定的な推論結果が
    /// 必要な場合は呼び出し側が先に [`Sequential::eval`] を呼ぶこと
    /// （`predict` 自体が暗黙に推論モードへ切り替えることはない。
    /// `nn::Dropout` モジュール doc「train／eval と `predict`／
    /// `forward_host` の整合」参照）。
    pub fn predict(&self, input: &Tensor<f32>) -> Result<Tensor<f32>, AutodiffError> {
        self.predict_recorded(input, &mut NoopPhaseRecorder)
    }

    /// [`Self::predict`] の本体（イシュー #2192・親 #2131。旧
    /// `Self::predict` 本体をここへ移設し、`predict` 自体は
    /// `NoopPhaseRecorder` を渡すだけの 1 行にした）。`rec` へ
    /// [`crate::inference::batch::InferencePhase::TapeBuild`]／
    /// `Forward` の計測点を差し込む——[`Self::predict`] は
    /// `NoopPhaseRecorder`（オーバーヘッドなし）を渡し、
    /// `Sequential::predict_batches`（`crate::inference::batch`）は
    /// `TimingPhaseRecorder` を渡してバッチ推論の内訳を集計する。
    /// 単一本体にすることで、両呼び出し元の分岐論理（tape 要否判定・
    /// フォールバック構造）が乖離しないことを構造で保証する。
    ///
    /// **フォールバック時の計測**: tape 不要経路が `Unsupported` を返し
    /// 旧経路（tape 経路）へフォールバックした場合、`Forward` は
    /// 実際に行った試行の回数として 2 回計上される（1 回目は
    /// `Unsupported` に終わった tape 不要経路の試行、2 回目は
    /// フォールバック先）。
    pub(crate) fn predict_recorded<R: PhaseRecorder>(
        &self,
        input: &Tensor<f32>,
        rec: &mut R,
    ) -> Result<Tensor<f32>, AutodiffError> {
        // イシュー #1760・Cursor Bugbot 指摘是正: tape 不要経路
        // （`predict_tape_free`）は層を先頭から順に `forward_host`
        // していくため、`Embedding`／`MultiheadAttention`（`forward_host`
        // 未実装で常に `Unsupported`）が途中に含まれると、それより
        // 手前の層（`Dropout` の RNG 消費・`BatchNorm` の running
        // stats 更新等、`forward_host` が副作用を伴う層）が実行された
        // *後* に `Unsupported` へ到達し、下の旧経路
        // フォールバック（`predict_via_tape`）が全層を最初から
        // 再実行してしまう。これは同じ副作用（RNG 消費・running
        // stats 更新）を 1 回の `predict` 呼び出しで二重に発生させる。
        //
        // 対策: 実際に層を 1 つも実行する前に、全層が
        // `Module::supports_forward_host()` を満たすかを事前判定する。
        // 1 層でも `false`（現状 `Embedding`・`MultiheadAttention` の
        // み）なら、tape 不要経路を**一切実行せず**最初から旧経路
        // （副作用も含め 1 回のみ実行される）を使う。全層が `true`
        // の場合の挙動・数値結果は本是正の前後で変わらない
        // （`Module::supports_forward_host` の trait doc も参照）。
        if !self
            .inner
            .layers()
            .iter()
            .all(|layer| layer.supports_forward_host())
        {
            return self.predict_via_tape(input, rec);
        }
        match self.predict_tape_free(input, rec) {
            Err(AutodiffError::Backend(BackendError::Unsupported(_))) => {
                self.predict_via_tape(input, rec)
            }
            other => other,
        }
    }

    /// 旧経路（`Tape` 上で `forward` を実行し `to_tensor()` で実体化する。
    /// TASK-9.4 当初実装）。[`Self::predict_recorded`] のフォールバック先。
    /// `TapeBuild` フェーズは `crate::tape()`（`Tape` 構築のみ）を、
    /// `Forward` フェーズは `tape.var(..)`・`forward`・`to_tensor()` を
    /// 一括で計測する（`Var<'_>` が `tape` を借用するため、`tape` の
    /// 構築とそれ以降を同一クロージャに収めると借用検査が通らない。
    /// `tape.var(..)` を `Forward` 側へ寄せることで各フェーズの
    /// `calls` が「呼び出し 1 回につき 1」の単純な意味論を保つ）。
    fn predict_via_tape<R: PhaseRecorder>(
        &self,
        input: &Tensor<f32>,
        rec: &mut R,
    ) -> Result<Tensor<f32>, AutodiffError> {
        let tape = rec.record(InferencePhase::TapeBuild, crate::tape);
        rec.record(InferencePhase::Forward, || {
            let input_var = tape.var(input);
            let output = self.forward(&tape, &input_var)?;
            Ok(output.to_tensor())
        })
    }

    /// tape 不要経路（イシュー #1028）。`Tape`／`Var` を一切構築せず、
    /// CPU 固定 `CpuBackendOps`（[`crate::tape`] が常に CPU バックエンドで
    /// `Tape` を構築するのと同じ構成であり、`predict` の既存の「CPU
    /// 固定」契約を変えない）を [`Self::predict_tape_free_with_ops`] へ
    /// 注入するだけの薄い委譲。`ops` を差し替え可能にしている理由は
    /// テスト側で `CountingOps`（本ファイル下部のテストモジュール）を
    /// 注入し、`Linear` → `ReLU` の融合結線が実際に `gemm_bias_act` を
    /// 呼んでいることを機械検証するため（公開シグネチャ自体は変えない。
    /// `predict_with_ops` を公開面へ復活させるものではない）。tape が
    /// 不要な経路のため `TapeBuild` は計測しない（`calls == 0` のまま）。
    fn predict_tape_free<R: PhaseRecorder>(
        &self,
        input: &Tensor<f32>,
        rec: &mut R,
    ) -> Result<Tensor<f32>, AutodiffError> {
        let ops = fandhe_ai_backend_cpu::CpuBackendOps::new();
        rec.record(InferencePhase::Forward, || {
            self.predict_tape_free_with_ops(&ops, input)
        })
    }

    /// [`Self::predict_tape_free`] の本体（イシュー #1218・`docs/perf/
    /// cpu-infer-predict-profile.md`）。`Sequential::forward`／
    /// `SequentialVars::forward`（学習 forward）と同じ「`Linear` 層に
    /// 出会うたび次層が `ReLU` かを先読みし、続く場合のみ
    /// `Linear::forward_host_with_activation(.., Activation::Relu)`
    /// （`ops.gemm_bias_act` 1 回・`nn/linear.rs`）へ結線して `ReLU` 層
    /// 自体をスキップする」方式を tape 不要経路へ適用する。
    ///
    /// **CPU 固定経路に限定する理由**: `Linear::forward_host_with_activation`
    /// の doc が明記するとおり、この融合は `ops.gemm_bias_act` の融合
    /// オーバーライドが非融合合成と bit 完全一致するバックエンドでのみ
    /// 安全（CPU は `crates/backend-cpu/tests/gemm_epilogue_parity.rs` で
    /// 確認済み）。本メソッドは `ops: &dyn BackendOps` を受け取るが、
    /// [`Self::predict_tape_free`] からは常に `CpuBackendOps` のみが渡る
    /// （呼び出し元がテスト以外で任意の `ops` を注入する経路は公開して
    /// いない）ため、この前提は保たれる。
    ///
    /// **末尾 `Linear` の bias のみ融合を行わない理由**: `ReLU` が続かない
    /// `Linear`（末尾層等）・`Sigmoid`／`Tanh` へ続く `Linear` は、
    /// `Sequential::forward` の #1044 レビュー限定（#1079・
    /// PRRT_kwDOTuUCJc6dgIt-）と同じ理由で従来どおり `forward_host`
    /// （非融合）へ委譲する（融合対象を `Linear` → `ReLU` に限定）。
    ///
    /// 1 層でも `Unsupported` を返した場合は途中結果を捨てて
    /// `Unsupported` をそのまま伝播し、[`Self::predict`] が旧経路へ
    /// 全体フォールバックする（部分的にホストフォールバックしない。
    /// `predict_tape_free` 移設前の docstring と同じ「黙示のフォール
    /// バックをしない」設計を維持する）。
    fn predict_tape_free_with_ops(
        &self,
        ops: &dyn BackendOps,
        input: &Tensor<f32>,
    ) -> Result<Tensor<f32>, AutodiffError> {
        let layers = self.inner.layers();
        let mut current = input.clone();
        let mut i = 0;
        while i < layers.len() {
            let layer = &layers[i];
            if let Some(linear) = layer.as_linear() {
                let fuse_relu = layers.get(i + 1).is_some_and(|next| next.as_relu());
                current = if fuse_relu {
                    linear.forward_host_with_activation(ops, &current, Activation::Relu)?
                } else {
                    linear.forward_host(ops, &current)?
                };
                i += if fuse_relu { 2 } else { 1 };
            } else {
                current = layer.forward_host(ops, &current)?;
                i += 1;
            }
        }
        Ok(current)
    }

    /// `DataLoader` を全バッチ反復して `predict` と同じ推論を行い、バッチごとの
    /// 出力を順に `Vec` へ蓄積して返す（イシュー #2192・#2582・親 #2131・
    /// #2581。決定記録 `docs/facade-predict-batches-phase-metrics-decision.md`
    /// §8.4 (a) の確定形）。呼び出しスレッドの累計 phase 計測値へ内訳（データ
    /// ロード・tape 構築・forward・デバイス転送）が加算され、
    /// [`crate::inference::get_phase_metrics`] で読める。
    ///
    /// 受け付けるのは [`DataLoader`] のみ（`D::Batch` は `Tensor<f32>`・
    /// `(Tensor<f32>, B)`・`(Tensor<f32>, B, C)` の 3 形。ラベルは無視する）。
    /// 他種のローダー向けは将来の別名メソッドで追加する方針で、本メソッドの
    /// シグネチャは不変。
    ///
    /// **モード切り替えなし**: [`Self::predict`] と同じく `training`
    /// フラグを暗黙に変更しない（バッチ単体の `predict` と bit 一致
    /// させるため。呼び出し側が必要なら先に [`Self::eval`] を呼ぶ）。
    ///
    /// **`shuffle=true` を拒否する理由**: 出力順がデータセット順と
    /// 対応しなくなるうえ、`Batches::next` がグローバル RNG を消費し
    /// 呼び出し元の RNG 状態を暗黙に変える。fail-closed に
    /// `InvalidArgument` を返し、RNG は消費しない。
    ///
    /// **出力 `Vec` の確保**: `Dataset::len()` は実装者が任意の値
    /// （`usize::MAX` を含む）を返しうる非信頼入力として扱う
    /// （`.claude/rules/security.md` A03）。`Vec::with_capacity` は
    /// capacity overflow で panic するため使わず、`Vec::new()` から
    /// 逐次 `try_reserve(1)`＋`push` する。確保失敗は `InvalidArgument`。
    ///
    /// **phase 計測**: `total` はこの呼び出し全体（成功・失敗いずれも）
    /// を計測し、途中で失敗した場合もそれまでの計測値を失わないよう
    /// 呼び出しスレッドの thread-local 累計へ merge してから返す。計測は
    /// スレッド単位で、他スレッドの計測とは混ざらない。
    ///
    /// # Errors
    ///
    /// - `shuffle=true` の `DataLoader`・`DataError`（データセットの検証・
    ///   バッチ生成の失敗）・出力 `Vec` の確保失敗は
    ///   [`AutodiffError::InvalidArgument`]
    /// - 各バッチの推論失敗は [`Self::predict`] と同じ
    ///
    /// # Examples
    ///
    /// ```
    /// use fandhe_ai::Tensor;
    /// use fandhe_ai::compat::Sequential;
    /// use fandhe_ai::data::{DataLoader, DataLoaderConfig, TensorDataset};
    ///
    /// let model = Sequential::new().add_linear(2, 1, 7).unwrap();
    /// let x = Tensor::<f32>::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[3, 2])
    ///     .unwrap();
    /// let loader = DataLoader::new(
    ///     TensorDataset::new(x.clone()).unwrap(),
    ///     DataLoaderConfig::new(2),
    /// )
    /// .unwrap();
    ///
    /// let outputs = model.predict_batches(&loader).unwrap();
    /// // 3 サンプルを batch_size=2 で反復すると 2 バッチ（2 件 + 端数 1 件）。
    /// assert_eq!(outputs.len(), 2);
    /// assert_eq!(outputs[0].shape(), &[2, 1]);
    /// assert_eq!(outputs[1].shape(), &[1, 1]);
    ///
    /// // 先頭バッチの出力は、同じ 2 行を単体 `predict` した結果と一致する。
    /// let first = Tensor::<f32>::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
    /// let expected = model.predict(&first).unwrap();
    /// assert_eq!(
    ///     outputs[0].contiguous().as_slice().unwrap(),
    ///     expected.contiguous().as_slice().unwrap()
    /// );
    /// ```
    pub fn predict_batches<D>(
        &self,
        loader: &DataLoader<D>,
    ) -> Result<Vec<Tensor<f32>>, AutodiffError>
    where
        D: Dataset,
        D::Batch: PredictBatchInput,
    {
        let started = std::time::Instant::now();
        let mut rec = TimingPhaseRecorder::default();
        let result = self.predict_batches_inner(loader, &mut rec);
        rec.record_total(started.elapsed());
        merge_inference_phase_stats(&rec.into_metrics());
        result
    }

    /// [`Self::predict_batches`] の本体（`total` フェーズの計測・
    /// thread-local への merge を外側に切り出すための分離）。
    fn predict_batches_inner<D>(
        &self,
        loader: &DataLoader<D>,
        rec: &mut TimingPhaseRecorder,
    ) -> Result<Vec<Tensor<f32>>, AutodiffError>
    where
        D: Dataset,
        D::Batch: PredictBatchInput,
    {
        if loader.config().shuffle {
            return Err(AutodiffError::InvalidArgument(
                "Sequential::predict_batches: shuffle=true の DataLoader は\
                 出力順の対応が崩れ暗黙に RNG を消費するため受理しない\
                 （shuffle=false の DataLoader を使うこと）"
                    .to_string(),
            ));
        }

        let to_invalid_arg = |e: DataError| {
            AutodiffError::InvalidArgument(format!("Sequential::predict_batches: {e}"))
        };

        let mut outputs: Vec<Tensor<f32>> = Vec::new();
        // `DataLoader::iter()` はサンプル順列（`order`。shuffle 時は
        // `shuffled_indices`、非 shuffle 時は `(0..n).collect()`）を
        // 構築するため、件数比例のコストを持つ（`fandhe_ai_tensor_core::
        // data::DataLoader::iter`）。設計記録 §2.1 は `DataLoad` フェーズ
        // の計測範囲を「`DataLoader::iter`／`Batches::next` の呼び出し」
        // と定義しているため、`iter()` 自体の呼び出しも計測区間へ含める
        // （codex-review 指摘・PR #2322。以前は `iter()` を計測開始前に
        // 呼んでおり、この構築コストが phase 集計から漏れていた）。
        let mut iter = rec.record(InferencePhase::DataLoad, || loader.iter());
        loop {
            let next = rec.record(InferencePhase::DataLoad, || iter.next());
            let Some(batch_result) = next else {
                break;
            };
            let batch = batch_result.map_err(to_invalid_arg)?;
            let input = batch.inference_input();
            // サンプル数は入力バッチの先頭軸（バッチ軸）から求める。
            // 出力の先頭軸は層構成（leading axis を変える層・rank-0
            // 出力を返す層等）に依存し、実際に消費した入力行数と食い
            // 違いうるため使わない（codex-review 指摘・PR #2322）。
            let samples = input.shape().first().copied().unwrap_or(1) as u64;
            let output = self.predict_recorded(input, rec)?;
            rec.record_batch(samples);
            if outputs.try_reserve(1).is_err() {
                return Err(AutodiffError::InvalidArgument(
                    "Sequential::predict_batches: 出力 Vec への確保に失敗した".to_string(),
                ));
            }
            outputs.push(output);
        }
        Ok(outputs)
    }

    /// 学習ステップの入口（#294）。このステップの `tape` へ全 `Linear`
    /// 層の `weight`/`bias` を葉ノードとして登録し（`Linear::bind` を
    /// 層順に呼ぶ）、学習用 forward・勾配取得の入口となる
    /// [`SequentialVars`] を返す。
    ///
    /// 返る `SequentialVars` は `&'m Sequential`（`self`）と `&'t Tape`
    /// の両方を借用する。このハンドルが生きている間は
    /// [`Sequential::apply_parameters`]（`&mut self` を要求）を呼べない
    /// （ステップ途中でのパラメータ書き換えを借用検査で静的に防ぐ設計。
    /// 呼び出し元は `bind` 以降の一連の処理をブロックスコープで囲み、
    /// スコープを抜けてから `apply_parameters` を呼ぶ運用とする。
    /// `crates/facade/tests/compat_sequential_train.rs` に実例がある）。
    ///
    /// `add_module`（#2398）で積んだパラメータ持ちの独自層は追跡されない（`bind` は
    /// `Result` を返さないため成功する）。返る [`SequentialVars`] の `forward`／
    /// `trainable_grads` が `InvalidArgument` で拒否する。
    pub fn bind<'m, 't>(&'m self, tape: &'t Tape) -> SequentialVars<'m, 't> {
        // `Linear::bind`／`Conv2d::bind`／`Conv1d::bind` はいずれも
        // `&fandhe_ai_autodiff::Tape` を要求する（`forward` と同じ理由。
        // `tape.0` 経由で取り出す）。3 種の学習可能層それぞれを層順
        // フィルタで独立に収集する（`SequentialVars::forward`／
        // `trainable_vars`／`trainable_grads` が `self.model.inner.
        // layers()` を再度層順に辿りながら、層種別ごとに対応する
        // カーソルから 1 件ずつ消費することで全体の層順対応を再構成
        // する。イシュー #1770・親 #1645）。
        let linears = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_linear())
            .map(|linear| linear.bind(&tape.0))
            .collect();
        // イシュー #3048: weight_norm 済み Linear の補助葉 g を `linears` と平行に保持する
        // （`LinearVars` へフィールドを足すと外部の struct リテラル構築を壊すため別ベクタ）。
        let linear_gs = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_linear())
            .map(|linear| linear.bind_weight_norm_g(&tape.0))
            .collect();
        let conv2ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv2d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        let conv1ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv1d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        let conv_transpose1ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv_transpose1d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        let conv3ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv3d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        let conv_transpose2ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv_transpose2d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        let conv_transpose3ds = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_conv_transpose3d())
            .map(|conv| conv.bind(&tape.0))
            .collect();
        // イシュー #3049: Conv 6 種共通の weight_norm 補助葉 g（Conv 層ごと 1 件・層順。
        // 型別ベクタの増殖を避けるため 1 本にまとめ、各 Conv 分岐が順に消費する）。
        let conv_gs = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| bind_conv_weight_norm_g(layer.as_ref(), &tape.0))
            .collect();
        // イシュー #1760: LayerNorm／RmsNorm／BatchNorm1d／BatchNorm2d／
        // Embedding／MultiheadAttention も同じ層順フィルタ方式で収集
        // する。`BatchNorm1d::bind`／`BatchNorm2d::bind` はいずれも同一
        // 具体型 `BatchNormVars<'t, '_>` を返す（rank 限定契約
        // 〈`accepted_ranks`〉だけが異なる）ため、1d／2d を区別せず単一
        // ベクタへ収集できる。
        let layer_norms = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_layer_norm())
            .map(|ln| ln.bind(&tape.0))
            .collect();
        let rms_norms = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_rms_norm())
            .map(|rn| rn.bind(&tape.0))
            .collect();
        let batch_norms = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| {
                if let Some(bn) = layer.as_batch_norm1d() {
                    Some(bn.bind(&tape.0))
                } else {
                    layer.as_batch_norm2d().map(|bn| bn.bind(&tape.0))
                }
            })
            .collect();
        let embeddings = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_embedding())
            .map(|emb| emb.bind(&tape.0))
            .collect();
        // イシュー #2528: EmbeddingBag も同じ層順フィルタ方式で収集する。
        let embedding_bags = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_embedding_bag())
            .map(|bag| bag.bind(&tape.0))
            .collect();
        // イシュー #2529: PRelu も同じ層順フィルタ方式で収集する。
        let prelus = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_prelu())
            .map(|p| p.bind(&tape.0))
            .collect();
        let mhas = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_multihead_attention())
            .map(|mha| mha.bind(&tape.0))
            .collect();
        let encoders = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_transformer_encoder_layer())
            .map(|enc| enc.bind(&tape.0))
            .collect();
        let decoders = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_transformer_decoder_layer())
            .map(|dec| dec.bind(&tape.0))
            .collect();
        let transformers = self
            .inner
            .layers()
            .iter()
            .filter_map(|layer| layer.as_transformer())
            .map(|t| t.bind(&tape.0))
            .collect();
        SequentialVars {
            model: self,
            linears,
            linear_gs,
            conv_gs,
            conv2ds,
            conv1ds,
            conv_transpose1ds,
            conv3ds,
            conv_transpose2ds,
            conv_transpose3ds,
            layer_norms,
            rms_norms,
            batch_norms,
            embeddings,
            embedding_bags,
            prelus,
            mhas,
            encoders,
            decoders,
            transformers,
        }
    }

    /// 学習可能パラメータ（`Linear`／`Conv2d`／`Conv1d` 層の
    /// `weight`/`bias`。イシュー #1770 で Conv 層を追加。`ConvTranspose1d` は
    /// イシュー #2521 で汎用の `named_parameters` 分岐により同じ順序契約で含む）への参照列を
    /// 層の追加順・各層内は weight → bias（`Some` の場合のみ）の順で
    /// 返す。[`crate::optim::Sgd::step`]／[`crate::optim::AdamW::step`]／
    /// [`crate::optim::Adam::step`]
    /// の位置対応契約にそのまま渡せる。この順序契約は
    /// [`SequentialVars::trainable_vars`]/[`SequentialVars::trainable_grads`]/
    /// [`Sequential::apply_parameters`] と共通（#294 の設計不変条件）。
    pub fn trainable_parameters(&self) -> Vec<&Tensor<f32>> {
        let mut out = Vec::new();
        for layer in self.inner.layers() {
            // イシュー #3048: 再パラメータ化済み Linear は汎用の `named_parameters` 分岐
            // （g → v → bias／original → bias）へ落とす。
            if let Some(linear) = layer.as_linear().filter(|l| !l.is_parametrized()) {
                out.push(linear.weight());
                if let Some(bias) = linear.bias() {
                    out.push(bias);
                }
            } else if let Some(conv) = layer.as_conv2d().filter(|c| !c.is_parametrized()) {
                // イシュー #3049: 再パラメータ化済み Conv は汎用の `named_parameters` 分岐へ落とす。
                out.push(conv.weight());
                if let Some(bias) = conv.bias() {
                    out.push(bias);
                }
            } else if let Some(conv) = layer.as_conv1d().filter(|c| !c.is_parametrized()) {
                out.push(conv.weight());
                if let Some(bias) = conv.bias() {
                    out.push(bias);
                }
            } else {
                // イシュー #1760: LayerNorm／RmsNorm／BatchNorm1d／
                // BatchNorm2d／Embedding／MultiheadAttention（と
                // イシュー #2521 の ConvTranspose1d・イシュー #2523 の ConvTranspose2d・イシュー #2524 の Conv3d）は
                // `Module::named_parameters` へ委譲する（各層が既に
                // 同じ順序契約〈weight → bias〉で実装済みのため
                // `Linear`／`Conv*` のように個別分岐を重複実装しない。
                // REQ-9「薄いラッパーに徹する」）。無状態層（活性化
                // 関数・`Dropout`）は空の `Vec` を返すため寄与しない。
                for (_, tensor) in layer.named_parameters() {
                    out.push(tensor);
                }
            }
        }
        out
    }

    /// `bind` が追跡する型付き層（EmbeddingBag〈#2528〉を含む）のどれでもなく、かつ学習可能パラメータ
    /// （`named_parameters()` が非空）を持つ最初の層の index を返す（イシュー #2398）。
    /// `add_module` で積んだパラメータ持ちの独自層がこれに当たる。
    /// `fit`／`SequentialVars::forward`／`trainable_grads`／常駐経路の入口検査から呼ばれる。
    /// `type_name()` の文字列一致ではなく型付きアクセサの有無で判定する（アダプタの
    /// `type_name` が将来内側の層へ委譲されても壊れないため）。
    pub(super) fn first_untracked_parametric_layer(&self) -> Option<usize> {
        self.inner.layers().iter().position(|layer| {
            layer.as_linear().is_none()
                && layer.as_conv2d().is_none()
                && layer.as_conv1d().is_none()
                && layer.as_conv_transpose1d().is_none()
                && layer.as_conv_transpose2d().is_none()
                && layer.as_conv3d().is_none()
                && layer.as_conv_transpose3d().is_none()
                && layer.as_layer_norm().is_none()
                && layer.as_rms_norm().is_none()
                && layer.as_batch_norm1d().is_none()
                && layer.as_batch_norm2d().is_none()
                && layer.as_embedding().is_none()
                && layer.as_embedding_bag().is_none()
                && layer.as_prelu().is_none()
                && layer.as_multihead_attention().is_none()
                && layer.as_transformer_encoder_layer().is_none()
                && layer.as_transformer_decoder_layer().is_none()
                && layer.as_transformer().is_none()
                && !layer.named_parameters().is_empty()
        })
    }

    /// [`Sequential::first_untracked_parametric_layer`] を `InvalidArgument` へ写す学習側の
    /// 入口検査（`ctx` は呼び出し元メソッド名）。学習側では `BackendError::Unsupported`
    /// （`predict_recorded` が「フォールバックの合図」として捕捉する）を使わない。
    pub(super) fn reject_untracked_parametric_layer(&self, ctx: &str) -> Result<(), AutodiffError> {
        match self.first_untracked_parametric_layer() {
            None => Ok(()),
            Some(i) => Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: 層 {i} は bind が追跡しない独自層（add_module）のパラメータを持ち、\
                 学習経路は非対応（イシュー #2398）"
            ))),
        }
    }

    /// `batch_first=false`（`[Len, B, E]` 系列先頭形式）の MultiheadAttention 層を持つ場合、
    /// 学習・評価経路（`fit*`／`evaluate`）を `InvalidArgument` で拒否する（イシュー #2530・
    /// PR #2724 レビュー指摘）。`fit`／`evaluate` は `TensorDataset`／`DataLoader` で第 0 軸を
    /// サンプル軸として分割・シャッフルするため、系列先頭形式では系列が切断され
    /// 教師データのバッチ軸と不整合になる。系列先頭形式対応の fit が入るまで fail-closed。
    pub(super) fn reject_seq_first_layer_for_fit(&self, ctx: &str) -> Result<(), AutodiffError> {
        let pos = self.inner.layers().iter().position(|layer| {
            layer
                .as_multihead_attention()
                .is_some_and(|m| !m.batch_first())
        });
        match pos {
            None => Ok(()),
            Some(i) => Err(AutodiffError::InvalidArgument(format!(
                "{ctx}: 層 {i} は batch_first=false（[Len, B, E]）の MultiheadAttention で、\
                 DataLoader は第 0 軸をサンプル軸として分割するため fit／evaluate は未対応\
                 （batch_first=true を使うこと。イシュー #2530）"
            ))),
        }
    }

    /// 常駐経路版の入口検査（`BackendError::Unsupported`。既存の
    /// `contains_resident_unsupported_layer` 拒否と同じ型・別メッセージ）。
    fn reject_untracked_parametric_layer_resident(&self, ctx: &str) -> Result<(), BackendError> {
        match self.first_untracked_parametric_layer() {
            None => Ok(()),
            Some(i) => Err(BackendError::Unsupported(format!(
                "{ctx}: 層 {i} は追跡対象外の独自層（add_module）のパラメータを持ち、\
                 デバイス常駐経路は非対応（イシュー #2398）"
            ))),
        }
    }

    /// `self.inner.layers()` にデバイス常駐経路（[`Sequential::
    /// init_device_param_store`]／[`Sequential::forward_resident`]／
    /// [`Sequential::predict_resident`]）が対応しない層種別が 1 つでも
    /// 含まれるかどうか（旧 `contains_conv_layer`。イシュー #1770 で
    /// `Conv2d`／`Conv1d` 向けに新設し、イシュー #1760 で LayerNorm／
    /// RmsNorm／BatchNorm1d／BatchNorm2d／Embedding／
    /// MultiheadAttention へ、イシュー #2532 で TransformerDecoderLayer を、イシュー #2533 で Transformer を追加、イシュー #2521 で ConvTranspose1d、イシュー #2523 で ConvTranspose2d、イシュー #2524 で Conv3d、イシュー #2525 で GroupNorm／InstanceNorm を追加、イシュー #1957 で Pooling（MaxPool／
    /// AvgPool／AdaptiveAvgPool の 1d／2d）へ対象を拡張・改名し、イシュー #3040 で Fold／Unfold を、イシュー #3044 で LocalResponseNorm を追加した）。
    /// これらの層は `forward_from_flat_leaves`（`Linear` 層のみを
    /// 消費する走査）の対象外のため、常駐経路の入口で明示的に拒否する
    /// （黙示フォールバックを作らない。`.claude/rules/security.md` A04）。
    fn contains_resident_unsupported_layer(&self) -> bool {
        self.inner.layers().iter().any(|layer| {
            // イシュー #3048: 再パラメータ化済み Linear は有効重みを device 常駐で再構成しない
            // （生の weight を有効重みと誤読して黙って誤る経路を作らない）。
            layer.as_linear().is_some_and(|l| l.is_parametrized())
                || layer.as_conv2d().is_some()
                || layer.as_conv1d().is_some()
                || layer.as_conv_transpose1d().is_some()
                || layer.as_conv_transpose2d().is_some()
                || layer.as_conv3d().is_some()
                || layer.as_conv_transpose3d().is_some()
                || layer.as_group_norm().is_some()
                || layer.as_instance_norm().is_some()
                || layer.as_layer_norm().is_some()
                || layer.as_rms_norm().is_some()
                || layer.as_batch_norm1d().is_some()
                || layer.as_batch_norm2d().is_some()
                || layer.as_embedding().is_some()
                || layer.as_embedding_bag().is_some()
                || layer.as_prelu().is_some()
                || layer.as_multihead_attention().is_some()
                || layer.as_transformer_encoder_layer().is_some()
                || layer.as_transformer_decoder_layer().is_some()
                || layer.as_transformer().is_some()
                || layer.as_unfold().is_some()
                || layer.as_fold().is_some()
                || layer.as_local_response_norm().is_some()
                || layer.is_pooling()
        })
    }

    /// train／eval モードを切り替え（イシュー #1758。PyTorch
    /// `Module.train()`／`Module.eval()`／`Module.training = ...` 相当）、
    /// 自身の [`Sequential::training`] フラグを更新したうえで**全子層へ
    /// 伝播**する（`nn::Module::set_training` を各 `layers` 要素へ順に
    /// 呼ぶ）。
    ///
    /// # 借用の注意
    ///
    /// `&mut self` を取るため、[`Sequential::bind`] が返す
    /// [`SequentialVars`]（`&self`／`&tape` を借用）が生きている間は
    /// 呼べない（[`Sequential::apply_parameters`] のドキュメント冒頭
    /// 「借用を解放してから呼ぶ」注意と同じ制約）。構築時（`add_*`
    /// ビルダー）の後・forward の合間に呼ぶ想定。
    ///
    /// `Linear`・活性化関数群等は全てモード非依存のため `layers` への
    /// 伝播は影響しないが、[`Sequential::add_dropout`]（イシュー #1603）
    /// で追加した層はこの伝播で実際に `training` フラグが更新され、
    /// forward の挙動（マスクの適用有無）が変わる（`nn::module` の
    /// trait doc「モードの正はコンテナが保持するフラグ」契約参照。
    /// `nn::Dropout` モジュール doc も参照）。
    pub fn set_training(&mut self, training: bool) {
        // `nn::Sequential::set_training`（`Module` 実装）が自身のモード
        // フラグ更新と全子層への伝播をまとめて担う（イシュー #1759 で
        // ここへ移設済み）。
        self.inner.set_training(training);
    }

    /// `set_training(true)` の別名（PyTorch `Module.train()` 相当）。
    pub fn train(&mut self) {
        self.set_training(true);
    }

    /// `set_training(false)` の別名（PyTorch `Module.eval()` 相当）。
    pub fn eval(&mut self) {
        self.set_training(false);
    }

    /// 現在のモード（`true` = train・`false` = eval）。**コンテナ自身の
    /// フラグ**を返す（`nn::Module::training` の既定実装〈常に
    /// `true`〉には委譲しない。本 `Sequential` がモードの正のため）。
    pub fn training(&self) -> bool {
        self.inner.training()
    }

    /// 「名前, パラメータ参照」列（PyTorch `Module.named_parameters()`
    /// 相当。イシュー #1758）を `layers` の index（活性化を含む全子の
    /// 位置。PyTorch `nn.Sequential` と同じ規約）を接頭辞にして返す。
    /// 各層は `nn::Module::named_parameters`（`Linear` 等）へ委譲する
    /// ため、無状態層（活性化関数）は寄与しない。
    ///
    /// # 順序契約
    ///
    /// 平坦化した tensor 列は [`Sequential::trainable_parameters`] と
    /// 完全に同じ順序（層順・各層内は weight → bias）になる
    /// （`docs/compat-api-scope.md` の位置対応契約と整合。イシュー
    /// #1758 のテストで固定）。
    pub fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)> {
        // `nn::Sequential::named_parameters`（`ModuleList::named_parameters`
        // への委譲）が同じ `"{index}.{name}"` 接頭辞契約で実装済みのため
        // そのまま委譲する（イシュー #1759）。
        self.inner.named_parameters()
    }

    /// [`Sequential::named_parameters`] のキー付きビュー（PyTorch
    /// `Module.state_dict()` 相当。イシュー #1752）。`self.inner`
    /// （`nn::Sequential`）の [`Module::state_dict`] 既定実装へ 1 行
    /// 委譲する（薄いラッパーに徹する。REQ-9）。キーは
    /// [`Sequential::named_parameters`] と同じ `"{index}.{name}"`
    /// （例: `Linear→ReLU→Linear` なら `0.weight`・`0.bias`・
    /// `2.weight`・`2.bias`）。
    pub fn state_dict(&self) -> HashMap<String, Tensor<f32>> {
        self.inner.state_dict()
    }

    /// [`Sequential::state_dict`] の逆（PyTorch
    /// `Module.load_state_dict(state_dict, strict=True)` 相当。イシュー
    /// #1752）。`self.inner` の [`Module::load_state_dict`] 既定実装
    /// （strict・two-pass + ベストエフォート・ロールバック。アトミック
    /// 性の正確な契約は `Module::load_state_dict` doc「アトミック性」
    /// 節を参照）へ 1 行委譲する。
    ///
    /// # 注意
    ///
    /// - `&mut self` を要求するため、[`Sequential::bind`] が返す
    ///   `SequentialVars` が生きている間は呼べない（`apply_parameters`
    ///   と同じ制約。メソッド doc「`apply_parameters`（`&mut model`）を
    ///   呼ぶ前にブロックを抜けて」節参照）。
    /// - ロード後は事前に構築した [`DeviceParamStore`] が stale になる
    ///   （`apply_parameters` と同じ。[`Sequential::init_device_param_store`]
    ///   の再実行が必要）。
    pub fn load_state_dict(
        &mut self,
        state: HashMap<String, Tensor<f32>>,
    ) -> Result<(), AutodiffError> {
        self.inner.load_state_dict(state)
    }

    /// `self.inner`（`nn::Sequential`）が保持する層列への読み取り専用
    /// アクセサ（イシュー #2037）。`crate::interop::onnx::OnnxModel::
    /// from_sequential` 専用の内部委譲入口であり `pub(crate)` に留める
    /// （公開面ではない。§15.5「薄い分解層」。`Sequential::layers` の
    /// ような `pub fn` を新設しない——`docs/compat-api-scope.md` §1 の
    /// 対象レイヤー集合限定・`api_surface.rs` の allowlist 契約を
    /// 増やさないため）。
    pub(crate) fn layers(&self) -> &[Box<dyn Module>] {
        self.inner.layers()
    }

    /// 層構成の記録への読み取り専用アクセサ（`compat::model_io` の
    /// `save_model` 専用。`layers()` と同じ長さを保つ不変条件は呼び出し側が
    /// fail-closed で検査する）。
    pub(super) fn specs(&self) -> &[LayerSpec] {
        &self.specs
    }

    /// optimizer（[`crate::optim::Sgd::step`]／[`crate::optim::AdamW::step`]／
    /// [`crate::optim::Adam::step`]）
    /// が返した更新後テンソル列を
    /// [`Sequential::trainable_parameters`] と同じ順序契約で各 `Linear`
    /// 層へ書き戻す。内部で `Linear::from_parameters`（`fandhe_ai_autodiff::nn::linear`）
    /// により層を再構築するため、compat 層自身は新パラメータ単体の内部
    /// 整合性検証ロジックを重複実装しない（REQ-9「薄いラッパーに徹する」）。
    /// ただし**置換前の層 shape との一致検証**（次段落）は
    /// `Linear::from_parameters` の責務範囲外（層の存在を知らない）なので、
    /// `apply_parameters` 自身の契約として本メソッドが担う（#426）。
    ///
    /// **置換前 shape との完全一致検証（#426。codex-review PR #420 P2 是正）**:
    /// 1 パス目で `Linear::from_parameters` を呼ぶ前に、各層の新
    /// `weight.shape()` が置換前の `weight.shape()` と完全一致することを
    /// 検査する（不一致なら層序数・expected/actual を含む
    /// `AutodiffError::InvalidArgument`）。bias 側の置換前一致は独立検査
    /// せず、`Linear::from_parameters` の bias 検証（`bias.shape() ==
    /// [weight.shape()[1]]`）に委譲する: weight が置換前と完全一致した
    /// 状態でこの bias 検証が通れば、bias の out_features 側も自動的に
    /// 置換前と一致するため（REQ-9「薄いラッパーに徹する」。独立実装は
    /// しない）。
    ///
    /// **層間整合は本検証に内包される**: 層 i の out_features と層 i+1 の
    /// in_features の整合は「置換前モデルが満たしていた水準」を shape 非
    /// 変更の更新が破り得ないことにより、置換前 shape との一致検証へ
    /// 帰着する。したがって隣接層比較を独立実装しない。**この検証により
    /// `apply_parameters` は shape を変えない optimizer 更新専用の契約と
    /// なる**: 層幅を変える意図的な「リサイズ」用途は本メソッドのサポート
    /// 対象外（そのような用途が必要になった場合は別 API として設計する）。
    ///
    /// # エラー
    /// - `updated` の要素数が `trainable_parameters()` の件数と不一致
    ///   → `AutodiffError::InvalidArgument`（fail-closed。位置対応契約が
    ///   崩れたまま一部の層だけ更新して黙って続行しない。`.claude/rules/
    ///   security.md` A03）
    /// - 新しい `weight` の shape が置換前の同一層の `weight` の shape と
    ///   不一致 → `AutodiffError::InvalidArgument`（#426。上記参照）
    /// - 個々のテンソルが `Linear::from_parameters` の内部整合性検証に
    ///   反する（例: bias の shape が対応する weight の out_features と
    ///   食い違う）→ `Linear::from_parameters` 由来の `AutodiffError::Shape`
    ///
    /// **アトミック性（two-pass）**: `updated` は 1 パス目で全層分を検証込みで
    /// `Linear::from_parameters` に通し、実際の代入（`self.layers` への
    /// 書き戻し）は全件の検証が成功した後の 2 パス目でまとめて行う。層ごとに
    /// 検証と代入を同時に行うと、途中の層（例: 2 層目）で shape 不整合エラーが
    /// 起きた際に、既に代入済みの前段の層は新パラメータのまま・未処理の後続層は
    /// 旧パラメータのままという不整合な混在状態がモデルに残ってしまう
    /// （呼び出し側は `Err` を受け取るにもかかわらず一部だけ更新されて
    /// 見える。fail-closed 違反。`.claude/rules/security.md` A03。
    /// review 指摘 #294）。two-pass にすることで、エラー時は呼び出し前の
    /// 状態を完全に維持する。#426 の shape 検証も同じ 1 パス目（代入前）に
    /// 置くため、この不変条件は変わらない。
    ///
    /// **独自層（`add_module`。#2398）の例外**: 独自層の `Module::set_parameter` は
    /// 任意実装で、1 パス目の検証後にも失敗し得る。その場合は適用済みの層を snapshot
    /// から書き戻して元エラーを返す（通常はモデル不変）。ただし書き戻し
    /// （`set_parameter`）自体が失敗した場合は不変を保証できないため、
    /// `AutodiffError::InvalidArgument`（元エラーと復元失敗の層・名前を含み
    /// 「部分更新が残り得る」旨を明示）を返す。この場合、呼び出し側はモデルを
    /// 破棄または再構築すること。
    pub fn apply_parameters(&mut self, updated: Vec<Tensor<f32>>) -> Result<(), AutodiffError> {
        /// 検証（#426。置換前 shape との完全一致）と `updated` からの
        /// weight／bias 取り出しを層種別（`Linear`／`Conv2d`／`Conv1d`）
        /// 間で共通化するヘルパー（イシュー #1770）。
        fn take_weight_bias(
            updated: &mut impl Iterator<Item = Tensor<f32>>,
            layer_index: usize,
            expected_weight_shape: &[usize],
            has_bias: bool,
        ) -> Result<(Tensor<f32>, Option<Tensor<f32>>), AutodiffError> {
            let new_weight = updated.next().ok_or_else(|| {
                AutodiffError::InvalidArgument(format!(
                    "Sequential::apply_parameters: updated has fewer elements than \
                     trainable_parameters() (weight missing at layer {layer_index})"
                ))
            })?;
            if new_weight.shape() != expected_weight_shape {
                return Err(AutodiffError::InvalidArgument(format!(
                    "Sequential::apply_parameters: layer {layer_index} weight shape changed \
                     from {expected_weight_shape:?} to {:?} (apply_parameters only supports \
                     shape-preserving updates; #426)",
                    new_weight.shape()
                )));
            }
            let new_bias = if has_bias {
                Some(updated.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(format!(
                        "Sequential::apply_parameters: updated has fewer elements than \
                         trainable_parameters() (bias missing at layer {layer_index})"
                    ))
                })?)
            } else {
                None
            };
            Ok((new_weight, new_bias))
        }

        /// パス 1 で検証込みに構築した新しい層本体（代入はまだしない。
        /// `Sequential` 自身は `Debug` を持たないため、この enum も
        /// `Debug` を派生しない）。
        enum Rebuilt {
            Linear(Linear),
            Conv2d(Conv2d),
            Conv1d(Conv1d),
        }

        /// LayerNorm／RmsNorm／BatchNorm1d／BatchNorm2d／Embedding／
        /// MultiheadAttention（イシュー #1760）向けの in-place 更新
        /// エントリ。`Linear`／`Conv2d`／`Conv1d`（`Rebuilt` 経由の層
        /// 丸ごと再構築方式。上記）とは異なり、`Module::set_parameter`
        /// による shape 保存置換のみで済ませる——`BatchNorm` の
        /// running stats／`num_batches_tracked`／`training` を
        /// `Linear::from_parameters` 相当の「層を作り直す」方式で更新
        /// すると失ってしまう罠を避けるため（`docs/compat-api-scope.md`
        /// §5「適用記録（経路 2。イシュー #1760）」参照）。
        struct GenericUpdate {
            layer_index: usize,
            /// `Module::named_parameters()` と同じ順の
            /// `(名前, 検証済み新しい値)`。
            values: Vec<(String, Tensor<f32>)>,
        }

        let mut updated = updated.into_iter();
        // 1 パス目: `self.inner.layers()`（不変借用）を層順に走査し、
        // 検証込みで新しい層本体を全件構築する（代入は未実施）。
        let mut rebuilt: Vec<Rebuilt> = Vec::new();
        let mut generic_updates: Vec<GenericUpdate> = Vec::new();
        for (layer_index, layer) in self.inner.layers().iter().enumerate() {
            // イシュー #3048: 再パラメータ化済み Linear は `Linear::from_parameters` で層を作り直す
            // と再パラメータ化が黙って消えるため、汎用（`set_parameter` の shape 保存置換）側へ回す。
            // 2b の条件と厳密に揃える（`rebuilt` 列がずれないように）。
            if let Some(linear) = layer.as_linear().filter(|l| !l.is_parametrized()) {
                let (new_weight, new_bias) = take_weight_bias(
                    &mut updated,
                    layer_index,
                    linear.weight().shape(),
                    linear.bias().is_some(),
                )?;
                rebuilt.push(Rebuilt::Linear(Linear::from_parameters(
                    new_weight, new_bias,
                )?));
            } else if let Some(conv) = layer.as_conv2d().filter(|c| !c.is_parametrized()) {
                // イシュー #3049: 再パラメータ化済み Conv は `from_parameters` で作り直すと再パラメータ化が
                // 黙って消えるため汎用側へ回す（2b の条件と厳密に揃える）。
                let (new_weight, new_bias) = take_weight_bias(
                    &mut updated,
                    layer_index,
                    conv.weight().shape(),
                    conv.bias().is_some(),
                )?;
                rebuilt.push(Rebuilt::Conv2d(Conv2d::from_parameters(
                    new_weight,
                    new_bias,
                    conv.stride(),
                    conv.padding(),
                    conv.dilation(),
                    conv.groups(),
                )?));
            } else if let Some(conv) = layer.as_conv1d().filter(|c| !c.is_parametrized()) {
                let (new_weight, new_bias) = take_weight_bias(
                    &mut updated,
                    layer_index,
                    conv.weight().shape(),
                    conv.bias().is_some(),
                )?;
                rebuilt.push(Rebuilt::Conv1d(Conv1d::from_parameters(
                    new_weight,
                    new_bias,
                    conv.stride(),
                    conv.padding(),
                    conv.dilation(),
                    conv.groups(),
                )?));
            } else {
                // イシュー #1760: LayerNorm／RmsNorm／BatchNorm1d／
                // BatchNorm2d／Embedding／MultiheadAttention と
                // ConvTranspose1d／ConvTranspose2d／Conv3d（イシュー #2521／#2523／#2524。`Rebuilt` を使わず
                // `set_parameter` で in-place 更新するため層別
                // `requires_grad` を保持する）は
                // `named_parameters()` の順（各層が独自に「weight →
                // bias」契約を守る。`Module::named_parameters` doc
                // 「命名契約」参照）で shape 検証しつつ取り出す。
                // 無状態層（活性化関数・`Dropout`）は空の `Vec` を
                // 返すため何も消費しない。
                let named = layer.named_parameters();
                if !named.is_empty() {
                    let mut values = Vec::with_capacity(named.len());
                    for (name, current) in named {
                        let new_value = updated.next().ok_or_else(|| {
                            AutodiffError::InvalidArgument(format!(
                                "Sequential::apply_parameters: updated has fewer elements \
                                 than trainable_parameters() ({name} missing at layer \
                                 {layer_index})"
                            ))
                        })?;
                        if new_value.shape() != current.shape() {
                            return Err(AutodiffError::InvalidArgument(format!(
                                "Sequential::apply_parameters: layer {layer_index} {name} \
                                 shape changed from {:?} to {:?} (apply_parameters only \
                                 supports shape-preserving updates; #426)",
                                current.shape(),
                                new_value.shape()
                            )));
                        }
                        values.push((name, new_value));
                    }
                    generic_updates.push(GenericUpdate {
                        layer_index,
                        values,
                    });
                }
            }
        }
        if updated.next().is_some() {
            return Err(AutodiffError::InvalidArgument(
                "Sequential::apply_parameters: updated has more elements than \
                 trainable_parameters()"
                    .to_string(),
            ));
        }
        // 2 パス目（2a）: `GenericUpdate`（イシュー #1760 の 6 層種別と `add_module`
        // #2398 の独自層）を `Module::set_parameter` で in-place 適用する。独自層の
        // `set_parameter` は任意実装で 1 パス目の検証後にも `Err` を返し得るため、
        // 適用前に各層の現在値を snapshot し、途中で失敗したら適用済みの層を
        // 逆順に元の値へ書き戻してからエラーを返す（エラー時はモデル不変。
        // 書き戻し自体も失敗した場合は不変を保証できないため型付きエラーで明示する）。
        // `Rebuilt`（`Linear`／`Conv2d`／`Conv1d`）の代入は失敗し得ないため、
        // 失敗し得る 2a を先に完了させてから 2b で行う（2a 失敗時は未着手のまま残す）。
        type LayerSnapshot = (usize, Vec<(String, Tensor<f32>)>);
        let mut applied: Vec<LayerSnapshot> = Vec::new();
        let mut failure: Option<AutodiffError> = None;
        'apply: for update in generic_updates {
            let layer = &mut self.inner.layers_mut()[update.layer_index];
            let snapshot: Vec<(String, Tensor<f32>)> = layer
                .named_parameters()
                .into_iter()
                .map(|(n, t)| (n, t.clone()))
                .collect();
            applied.push((update.layer_index, snapshot));
            for (name, value) in update.values {
                if let Err(e) = layer.set_parameter(&name, value) {
                    failure = Some(e);
                    break 'apply;
                }
            }
        }
        if let Some(e) = failure {
            // 書き戻し失敗を握りつぶさない（fail-closed。security.md A03）。独自層の
            // `set_parameter` は任意実装で復元時にも `Err` を返し得るため、失敗した層と
            // パラメータ名を集め、1 件でもあれば「部分更新が残り得る」ことを型付きエラー
            // （`InvalidArgument`）で明示する。
            let mut restore_failures: Vec<String> = Vec::new();
            for (layer_index, snapshot) in applied.into_iter().rev() {
                let layer = &mut self.inner.layers_mut()[layer_index];
                for (name, value) in snapshot {
                    if let Err(re) = layer.set_parameter(&name, value) {
                        restore_failures.push(format!("layer {layer_index} {name}: {re}"));
                    }
                }
            }
            if restore_failures.is_empty() {
                return Err(e);
            }
            return Err(AutodiffError::InvalidArgument(format!(
                "Sequential::apply_parameters: custom layer set_parameter failed ({e}) and \
                 rollback also failed; the model may be partially updated \
                 (restore failures: {})",
                restore_failures.join("; ")
            )));
        }
        // 2b: 検証済みの `Rebuilt` を同じ層順で代入する（失敗し得ない）。
        let mut rebuilt = rebuilt.into_iter();
        for layer in self.inner.layers_mut().iter_mut() {
            if let Some(linear) = layer.as_linear_mut().filter(|l| !l.is_parametrized()) {
                if let Some(Rebuilt::Linear(new_linear)) = rebuilt.next() {
                    *linear = new_linear;
                }
            } else if let Some(conv) = layer.as_conv2d_mut().filter(|c| !c.is_parametrized()) {
                if let Some(Rebuilt::Conv2d(new_conv)) = rebuilt.next() {
                    *conv = new_conv;
                }
            } else if let Some(conv) = layer.as_conv1d_mut().filter(|c| !c.is_parametrized())
                && let Some(Rebuilt::Conv1d(new_conv)) = rebuilt.next()
            {
                *conv = new_conv;
            }
        }
        Ok(())
    }

    /// デバイス上パラメータ更新（イシュー #935・
    /// `docs/device-resident-update-design.md`）の入口: `tape` のバック
    /// エンドへ全 `Linear` 層の `weight`／`bias` を [`Sequential::
    /// trainable_parameters`] と同一の順序契約（層順に weight → bias。
    /// `Some` の場合のみ）で 1 回だけアップロードし [`DeviceParamStore`]
    /// を構築する。
    ///
    /// 返る `DeviceParamStore` は `tape` とは独立した寿命を持つ（`Tape`
    /// はステップごとに使い捨てる運用のため。`fandhe_ai_autodiff::tape`
    /// モジュール doc「学習ループでの運用」参照）。以後の学習ステップは
    /// 新しい `tape`（`crate::tape_for` 等で構築）を [`Sequential::
    /// forward_resident`]／[`Tape::step_device_param_store`] へ渡しつつ、
    /// 同じ `DeviceParamStore` インスタンスを使い回す。
    pub fn init_device_param_store(&self, tape: &Tape) -> Result<DeviceParamStore, BackendError> {
        // イシュー #1770: `forward_from_flat_leaves`／`build_device_
        // chain_steps` は `Linear` 層（`as_linear()`）のみを消費する
        // 走査のため、`trainable_parameters()` が Conv 層の weight／
        // bias を含むようになった今、Conv 層を含むモデルを黙って
        // 通すと後段の forward（`Self::forward_resident`／
        // `Self::predict_resident`）で「leaves の要件超過」エラーへ
        // 迂遠に到達してしまう（`forward_from_flat_leaves` 末尾の
        // fail-closed 検査。メソッド doc 参照）。ここで入口を明示的に
        // 塞ぎ、原因が分かるメッセージで即座に拒否する（`.claude/rules/
        // security.md` A04「安全でない設計」: 黙示フォールバックを
        // 作らない）。
        if self.contains_resident_unsupported_layer() {
            return Err(BackendError::Unsupported(
                "Sequential::init_device_param_store: Conv／Norm／Embedding／Attention／Pooling／PReLU 層を \
                 含む Sequential はデバイス常駐経路非対応（イシュー #1770・#1760・#1957・#2529）"
                    .to_string(),
            ));
        }
        self.reject_untracked_parametric_layer_resident("Sequential::init_device_param_store")?;
        let params = self.trainable_parameters();
        DeviceParamStore::new(&tape.0, &params)
    }

    /// デバイス常駐パラメータでの学習用 forward（イシュー #935・
    /// #1022 でパラメータの毎 step D2H を排除）。
    ///
    /// `store.register_resident_params(&tape.0)` を 1 回呼び（forward 用
    /// 葉ノード登録。#1022 でホストへの download を撤去済み——
    /// `DeviceParamStore::register_resident_params` のドキュメント
    /// 参照）、返る [`ResidentLeaf`] 列から [`Sequential::forward`]
    /// （`SequentialVars::forward`）と同一の層イテレーション（`Linear`
    /// 層は `store.linear_forward`〈デバイス常駐 weight のまま forward〉・
    /// 活性化層は `Module::forward` 多態 dispatch）を辿る。`mem`／`ops`
    /// （`BackendOps`／`MemoryOps`）は一切表面に出さない（REQ-12）。
    ///
    /// 呼び出し元は本メソッドの戻り値（`loss` 計算に使う `Var`）から
    /// `tape.backward_device_param_store(...)`（素の `tape.backward` は
    /// `Op::LinearResident` を含むグラフに対し型付きエラーを返す。
    /// `DeviceParamStore::backward` doc 参照）→
    /// `tape.step_device_param_store(&mut store, &grads, &config)` と
    /// 繋げる（`crates/facade/tests/device_param_store_train.rs` に
    /// 実例がある）。
    ///
    /// **forward 失敗時の pending ロールバック（codex-review PR #954 P2
    /// 是正）**: `register_resident_params` で `store` を pending 状態へ
    /// 遷移させた後、`forward_from_flat_leaves`（層数不一致・バックエンド
    /// 演算エラー等）が失敗した場合、そのまま `Err` を返すと `store` は
    /// pending のまま残り、次回呼び出しの `register_resident_params` が
    /// `BackendError::PendingForwardUnconsumed` で拒否される
    /// （`DeviceParamStore` モジュール doc「状態機械」参照）。呼び出し元は
    /// forward の失敗を理由に `store` を破棄する義務を負わないため、公開
    /// ラッパーである本メソッド内で `store.abandon_pending_forward()` に
    /// より pending をロールバックしてから元のエラーを返す
    /// （`register_resident_params` 自体が失敗した場合は pending 状態へ
    /// 遷移していないため、`?` でそのまま伝播してよい）。
    pub fn forward_resident<'t>(
        &self,
        tape: &'t Tape,
        input: &Var<'t>,
        store: &mut DeviceParamStore,
    ) -> Result<Var<'t>, AutodiffError> {
        // イシュー #1770・#1760・#1957: `Self::init_device_param_store` の
        // ガードと同じ理由（`contains_resident_unsupported_layer` doc
        // 参照）。二重防御（呼び出し元が独自に構築した `store` を
        // 渡す誤用も想定した fail-closed）。
        if self.contains_resident_unsupported_layer() {
            return Err(AutodiffError::Backend(BackendError::Unsupported(
                "Sequential::forward_resident: Conv／Norm／Embedding／Attention／Pooling／PReLU 層を \
                 含む Sequential はデバイス常駐経路非対応（イシュー #1770・#1760・#1957・#2529）"
                    .to_string(),
            )));
        }
        self.reject_untracked_parametric_layer_resident("Sequential::forward_resident")
            .map_err(AutodiffError::Backend)?;
        let leaves = store.register_resident_params(&tape.0)?;
        match self.forward_from_flat_leaves(&tape.0, input, &leaves, store) {
            Ok(output) => Ok(output),
            Err(e) => {
                store.abandon_pending_forward();
                Err(e)
            }
        }
    }

    /// デバイス常駐パラメータでの推論（イシュー #935・#1022 でパラメータの
    /// download を撤去）。`store.device()` へ結線した新規 [`Tape`]
    /// （`crate::tape_for`）を内部で構築し、`store.
    /// snapshot_resident_params`（読み取り専用版。`pending` 状態を
    /// 変化させない。#1022 で download を撤去済み）で得た [`ResidentLeaf`]
    /// 列から forward する。`Tape` はこの呼び出しのスコープ内で破棄される
    /// （`Sequential::predict` と同じ運用。`fandhe_ai_autodiff::nn::linear`
    /// 「`Tape` はステップごとに生成・破棄される前提」参照）。
    ///
    /// **単一同期チェーン優先（イシュー #1688・親 #1581／#1580・
    /// `docs/inference-chain-single-sync-design.md`）**: `self.layers`
    /// が `Linear`（＋`ReLU` 融合）のみで構成できる場合、`build_device_
    /// chain_steps` で構築した `steps` を `DeviceParamStore::
    /// predict_device_chain`（入力側 `upload` 1 回・出力側 `download`
    /// 1 回にチェーン全体の同期点を集約する経路）へ渡す。バックエンドが
    /// 対応しない場合（`BackendError::Unsupported`）は下記の現行経路
    /// （`forward_from_flat_leaves`。層ごとに `linear_forward_with_
    /// activation` の戻り値〈ホスト `Tensor`〉を経由するため層境界ごとに
    /// 同期点が生じる）へ全体フォールバックする（設計文書決定 7。部分的
    /// にチェーンを進めた結果は使わない）。`Sigmoid`／`Tanh` 混在・
    /// `leaves` 過不足（不正な `DeviceParamStore` を渡した等）の場合も
    /// `build_device_chain_steps` が `None` を返し同様にフォールバック
    /// する。
    ///
    /// **chain 経路と現行経路の bit 同一契約について**: 両経路は異なる
    /// カーネル入口（`BackendOps::linear_forward_device_tracked` vs
    /// `gemm_resident_rhs_act`）を経由するため、`predict` との parity は
    /// 「`forward_from_flat_leaves` を共有する」という構造的保証ではなく、
    /// 各バックエンドの `linear_forward_device ≡ gemm_resident_rhs_act`
    /// 数値契約（CPU: 融合・非融合の推移的一致。`docs/perf/linear-
    /// forward-device-gpu.md`）に依存する。
    pub fn predict_resident(
        &self,
        store: &DeviceParamStore,
        input: &Tensor<f32>,
    ) -> Result<Tensor<f32>, AutodiffError> {
        // イシュー #1770・#1760・#1957: `Self::forward_resident` と同じ
        // ガード。
        if self.contains_resident_unsupported_layer() {
            return Err(AutodiffError::Backend(BackendError::Unsupported(
                "Sequential::predict_resident: Conv／Norm／Embedding／Attention／Pooling／PReLU 層を \
                 含む Sequential はデバイス常駐経路非対応（イシュー #1770・#1760・#1957・#2529）"
                    .to_string(),
            )));
        }
        self.reject_untracked_parametric_layer_resident("Sequential::predict_resident")
            .map_err(AutodiffError::Backend)?;
        let tape = crate::tape_for(store.device())?;
        let leaves = store.snapshot_resident_params(&tape.0)?;

        if let Some(steps) = self.build_device_chain_steps(&leaves) {
            match store.predict_device_chain(&tape.0, input, &steps) {
                Ok(output) => return Ok(output),
                Err(BackendError::Unsupported(_)) => {
                    // 決定 7（設計文書）: バックエンドがデバイス常駐
                    // チェーンに対応しない——全体を現行経路へフォール
                    // バックする。
                }
                Err(e) => return Err(AutodiffError::Backend(e)),
            }
        }

        let input_var = tape.var(input);
        let output = self.forward_from_flat_leaves(&tape.0, &input_var, &leaves, store)?;
        Ok(output.to_tensor())
    }

    /// [`Self::predict_resident`] の常駐入力版（イシュー #3250 P3）。入力を
    /// [`Tape::upload_resident`] で窓の外へ 1 回置いた [`ResidentTensor`] として受け、
    /// 窓の中は入力の H2D なし・出力の D2H 1 回だけで推論する。チェーン本体は
    /// ホスト入力版と同一（`DeviceParamStore::predict_device_chain_resident`）なので出力は
    /// [`Self::predict_resident`] と bit 一致する。
    ///
    /// **ホスト経路へは落とさない**: `Sigmoid`／`Tanh` 混在・層の過不足・空 `Sequential`
    /// （チェーンを組めない場合）や、バックエンドがデバイス常駐チェーンに対応しない場合は
    /// [`BackendError::Unsupported`] を返して止める（download してホスト経路へ回すと、
    /// 本 API が取り除く H2D が戻るため）。チェーンは `store` を書き換えないので状態は変わらない。
    /// 別 `store`・別デバイスのハンドルは型付きエラー（`InvalidArgument`・`DeviceMismatch`）。
    pub fn predict_resident_input(
        &self,
        store: &DeviceParamStore,
        input: &ResidentTensor,
    ) -> Result<Tensor<f32>, AutodiffError> {
        if self.contains_resident_unsupported_layer() {
            return Err(AutodiffError::Backend(BackendError::Unsupported(
                "Sequential::predict_resident_input: Conv／Norm／Embedding／Attention／Pooling／PReLU 層を \
                 含む Sequential はデバイス常駐経路非対応（イシュー #1770・#1760・#1957・#2529）"
                    .to_string(),
            )));
        }
        self.reject_untracked_parametric_layer_resident("Sequential::predict_resident_input")
            .map_err(AutodiffError::Backend)?;
        let tape = crate::tape_for(store.device())?;
        let leaves = store.snapshot_resident_params(&tape.0)?;
        let Some(steps) = self.build_device_chain_steps(&leaves) else {
            return Err(AutodiffError::Backend(BackendError::Unsupported(
                "Sequential::predict_resident_input: Linear（＋ReLU）以外の層を含む、または層が空の \
                 Sequential はデバイス常駐チェーン非対応（ホスト経路へは落とさない。イシュー #3250）"
                    .to_string(),
            )));
        };
        store
            .predict_device_chain_resident(&tape.0, &input.0, &steps)
            .map_err(AutodiffError::Backend)
    }

    /// 学習 1 step（forward・MSE（mean）・backward・SGD）を、常駐入力 `x`・`y` から**同期なし**で
    /// デバイスへ積み、loss ハンドルを返す（イシュー #3254 P5。公開形の決定は
    /// `docs/compat-resident-train-step-decision.md` §4・§5）。同期は [`ResidentLoss::read`] の
    /// 1 回だけ（読まなければ起きない）。
    ///
    /// - **対応範囲**: 全層が `Linear`（中間は `ReLU` 融合・最終層は活性なし）。損失は **MSE（mean）固定**・
    ///   最適化は **SGD 固定**（momentum・nesterov・weight decay 可）。他の損失・最適化は別の入口を
    ///   追加して扱い、本シグネチャは変えない。第 1 層の d_input は計算しない。
    /// - **範囲外は黙って別の計算をしない**: `Sigmoid`／`Tanh`・独立 `ReLU`・空 `Sequential`・最終層
    ///   `ReLU`・Conv 等の非対応層・空バッチ・出力幅 0・weight tying・形状不一致・別 `store`／別
    ///   デバイスの入力・未消費の forward・poison 済み `store` は、`store` を変更する前に型付き
    ///   エラー（`Unsupported`／`InvalidArgument`／`ShapeMismatch`／`DeviceMismatch` 等）で返す。
    /// - **バックエンドが部品を持たない場合だけ従来経路へフォールバック**: 事前検証を通った後、
    ///   チェーンが最初の書き込み前に `Unsupported` を返したとき（例: CUDA の TF32 系精度モード）は、
    ///   step 全体を Tape 経路（`x`・`y` を download → `forward_resident` → `mse_loss` →
    ///   `backward_device_param_store` → `step_device_param_store`）で実行する。この経路は D2H を伴うが、
    ///   loss・更新後パラメータはチェーンと bit 一致する。書き込み後の失敗は poison した上でエラーを返す。
    /// - **契約**: 同じバックエンドの Tape 経路と loss・更新後パラメータが bit 一致する（NaN はクラス一致）。
    ///   融合・カーネル選択・同期方式は利用者に選ばせない（REQ-12）。
    ///
    /// 内部で `store.device()` へ結線した [`Tape`] を作る。ハンドル（[`ResidentTensor`]・
    /// [`ResidentLoss`]）は `store` に束縛され tape には束縛されないため、tape を作り直しても
    /// 順序は保たれる（[`ResidentLoss::read`] 参照）。
    ///
    /// ```
    /// use fandhe_ai::{SgdConfig, Tensor, compat::Sequential};
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let tape = fandhe_ai::tape();
    /// let model = Sequential::new().add_linear(2, 4, 1)?.add_relu().add_linear(4, 1, 2)?;
    /// let mut store = model.init_device_param_store(&tape)?;
    /// // 窓の外で 1 回だけ upload。
    /// let x = tape.upload_resident(&store, &Tensor::new(vec![0.5_f32; 6], &[3, 2])?)?;
    /// let y = tape.upload_resident(&store, &Tensor::new(vec![1.0_f32; 3], &[3, 1])?)?;
    /// let config = SgdConfig::new(0.05);
    /// for _ in 0..3 {
    ///     // 窓の中: 同期なしで積む。
    ///     let _ = model.train_step_resident(&mut store, &x, &y, &config)?;
    /// }
    /// let last = model.train_step_resident(&mut store, &x, &y, &config)?;
    /// let loss = last.read(&mut store)?; // 唯一の D2H・同期
    /// assert!(loss.is_finite());
    /// # Ok(())
    /// # }
    /// ```
    pub fn train_step_resident(
        &self,
        store: &mut DeviceParamStore,
        x: &ResidentTensor,
        y: &ResidentTensor,
        config: &SgdConfig,
    ) -> Result<ResidentLoss, AutodiffError> {
        self.train_step_resident_with(
            store,
            x,
            y,
            config,
            DeviceParamStore::train_step_device_chain,
        )
    }

    /// [`Self::train_step_resident`] の本体。`run_chain` はチェーン実行部分の差し替え点（本番は
    /// `train_step_device_chain`。テストだけが第 2 段のフォールバックを `Unsupported` 注入で検証する）。
    fn train_step_resident_with(
        &self,
        store: &mut DeviceParamStore,
        x: &ResidentTensor,
        y: &ResidentTensor,
        config: &SgdConfig,
        run_chain: ResidentChainRunner,
    ) -> Result<ResidentLoss, AutodiffError> {
        const CTX: &str = "Sequential::train_step_resident";
        // 第 1 段（範囲外。フォールバックしない）: モデル構成。
        if self.contains_resident_unsupported_layer() {
            return Err(AutodiffError::Backend(BackendError::Unsupported(format!(
                "{CTX}: Conv／Norm／Embedding／Attention／Pooling／PReLU 層を含む Sequential は\
                 デバイス常駐経路非対応（イシュー #1770・#1760・#1957・#2529）"
            ))));
        }
        self.reject_untracked_parametric_layer_resident(CTX)
            .map_err(AutodiffError::Backend)?;
        let tape = crate::tape_for(store.device())?;
        let leaves = store.snapshot_resident_params(&tape.0)?;
        let Some(steps) = self.build_device_chain_steps(&leaves) else {
            return Err(AutodiffError::Backend(BackendError::Unsupported(format!(
                "{CTX}: Linear（＋ReLU）以外の層を含む、または層が空の Sequential は\
                 デバイス常駐チェーン非対応（Tape 経路へは落とさない。イシュー #3254）"
            ))));
        };
        // 第 1 段（範囲外）: チェーンの事前検証（副作用なし。ここのエラーはそのまま返す）。
        store.validate_train_step_device_chain(&tape.0, &x.0, &y.0, &steps, config)?;
        match run_chain(store, &tape.0, &x.0, &y.0, &steps, config) {
            Ok(loss) => Ok(ResidentLoss(loss, std::marker::PhantomData)),
            // 第 2 段: バックエンドが部品を持たない。最初の書き込み前の `Unsupported` は store を
            // 変えない（poison 済みなら以降の download／register が `StorePoisoned` で拒否する）。
            Err(BackendError::Unsupported(_)) => {
                drop(steps);
                drop(leaves);
                self.train_step_via_tape_path(store, &tape, x, y, config)
            }
            Err(e) => Err(AutodiffError::Backend(e)),
        }
    }

    /// 第 2 段のフォールバック: step 全体を Tape 経路で実行し、loss をホストで確定して
    /// `ResidentLoss` にする（イシュー #3254。D2H を伴う。チェーンと bit 一致する経路）。
    fn train_step_via_tape_path(
        &self,
        store: &mut DeviceParamStore,
        tape: &Tape,
        x: &ResidentTensor,
        y: &ResidentTensor,
        config: &SgdConfig,
    ) -> Result<ResidentLoss, AutodiffError> {
        let x_host = store.download_resident_input(&tape.0, &x.0)?;
        let y_host = store.download_resident_input(&tape.0, &y.0)?;
        let xv = tape.var_no_grad(&x_host);
        let yv = tape.var_no_grad(&y_host);
        let pred = self.forward_resident(tape, &xv, store)?;
        let result = (|| {
            let loss = pred.mse_loss(&yv)?;
            let loss_value = loss.to_tensor().get(&[]).ok_or_else(|| {
                AutodiffError::Backend(BackendError::InvalidArgument(
                    "Sequential::train_step_resident: loss is not a scalar (internal error)"
                        .to_string(),
                ))
            })?;
            let grads = tape.backward_device_param_store(&loss, store)?;
            tape.step_device_param_store(store, &grads, config)?;
            Ok::<f32, AutodiffError>(loss_value)
        })();
        let loss_value = match result {
            Ok(v) => v,
            Err(e) => {
                // forward が登録した pending を残さない（次の step が拒否されないように）。
                store.abandon_pending_forward();
                return Err(e);
            }
        };
        let handle = store.record_host_train_step_loss(&tape.0, loss_value)?;
        Ok(ResidentLoss(handle, std::marker::PhantomData))
    }

    /// `self.layers` を走査し、[`DeviceParamStore::predict_device_chain`]
    /// へ渡す steps（`(weight, bias, act)` の列）を構築する（イシュー
    /// #1688。`forward_from_flat_leaves` と同じ走査規則——`Linear` 層は
    /// 次層が `ReLU` なら融合し、`bias` は `Some` の場合のみ 1 要素
    /// 消費する——を共有する）。
    ///
    /// `Linear`（＋`ReLU` 融合）以外の層（`Sigmoid`／`Tanh`・独立した
    /// `ReLU` 等）に遭遇した場合、または `leaves` の過不足がある場合は
    /// `None` を返し、呼び出し元（`Self::predict_resident`）は現行経路
    /// （`forward_from_flat_leaves`）へ全体フォールバックする（設計文書
    /// 決定 7）。層が 1 つもない場合（空 `Sequential`）も `None` を返す
    /// （空チェーンのための無意味な upload/download を避ける）。
    fn build_device_chain_steps<'a, 't>(
        &'a self,
        leaves: &'a [ResidentLeaf<'t>],
    ) -> Option<
        Vec<(
            &'a ResidentLeaf<'t>,
            Option<&'a ResidentLeaf<'t>>,
            Activation,
        )>,
    > {
        let layers = self.inner.layers();
        if layers.is_empty() {
            return None;
        }
        let mut steps = Vec::new();
        let mut cursor = leaves.iter();
        let mut i = 0;
        while i < layers.len() {
            let layer = &layers[i];
            // `Linear` 以外の層（`Sigmoid`／`Tanh` 等）は chain 経路
            // 非対応のため `None` を返しフォールバックさせる。
            let linear = layer.as_linear()?;
            let weight = cursor.next()?;
            let bias = if linear.bias().is_some() {
                Some(cursor.next()?)
            } else {
                None
            };
            let act = if layers.get(i + 1).is_some_and(|next| next.as_relu()) {
                Activation::Relu
            } else {
                Activation::None
            };
            steps.push((weight, bias, act));
            i += if matches!(act, Activation::Relu) {
                2
            } else {
                1
            };
        }
        if cursor.next().is_some() {
            // `leaves` が `self.layers` の要求件数より多い（位置対応
            // 契約が崩れている）場合は chain 経路を使わずフォール
            // バックさせる（`forward_from_flat_leaves` の同種チェックと
            // 同じ理由。`.claude/rules/security.md` A03）。
            return None;
        }
        Some(steps)
    }

    /// `tape`（`self.layers` を辿る forward 用）と `leaves`（`self.layers`
    /// のうち `Linear` 層に対応する、層順に weight → bias〈`Some` の
    /// 場合のみ〉のフラットな [`ResidentLeaf`] 列。[`Sequential::
    /// trainable_parameters`] と同一の順序契約）・`store`（`leaves` の
    /// 発行元であり `linear_forward` の実行主体）から forward する共通
    /// ロジック。[`Sequential::forward_resident`]／[`Sequential::
    /// predict_resident`] の両方から呼ばれる（層イテレーションの二重実装
    /// を避ける。設計文書 §3.3c）。
    ///
    /// **#1022 による変更**: 旧実装は `Var` 列から [`LinearVars`] を
    /// 組み立てて `LinearVars::forward`（ホスト常駐 weight 前提の
    /// `matmul`／`add`）を呼んでいた。`register_resident_params`／
    /// `snapshot_resident_params` の戻り型が不透明な `ResidentLeaf`
    /// （ホスト値を持たない）へ変わったため、`Linear` 層は
    /// `store.linear_forward`（デバイス常駐のまま `BackendOps::
    /// gemm_resident_rhs` へ委譲）を呼ぶ形へ置き換える。
    fn forward_from_flat_leaves<'t>(
        &self,
        tape: &'t fandhe_ai_autodiff::Tape,
        input: &Var<'t>,
        leaves: &[ResidentLeaf<'t>],
        store: &DeviceParamStore,
    ) -> Result<Var<'t>, AutodiffError> {
        let layers = self.inner.layers();
        let mut current = *input;
        let mut cursor = leaves.iter();
        // `SequentialVars::forward`（`Sequential::forward` 経由）と同じ
        // 「次層が `ReLU` かを先読みして `Linear` 層へ結線する」方式
        // （イシュー #1044）。デバイス常駐版は `store.
        // linear_forward_with_activation`（`BackendOps::
        // gemm_resident_rhs_act` を経由）を使う。
        let mut i = 0;
        while i < layers.len() {
            let layer = &layers[i];
            if let Some(linear) = layer.as_linear() {
                let weight = cursor.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "Sequential::forward_from_flat_leaves: leaves has fewer elements than \
                         trainable_parameters() (weight missing)"
                            .to_string(),
                    )
                })?;
                let bias = if linear.bias().is_some() {
                    Some(cursor.next().ok_or_else(|| {
                        AutodiffError::InvalidArgument(
                            "Sequential::forward_from_flat_leaves: leaves has fewer elements \
                             than trainable_parameters() (bias missing)"
                                .to_string(),
                        )
                    })?)
                } else {
                    None
                };
                let act = if layers.get(i + 1).is_some_and(|next| next.as_relu()) {
                    Activation::Relu
                } else {
                    Activation::None
                };
                current = store
                    .linear_forward_with_activation(tape, &current, weight, bias, act)
                    .map_err(AutodiffError::Backend)?;
                i += if matches!(act, Activation::Relu) {
                    2
                } else {
                    1
                };
            } else {
                current = layer.forward(tape, &current)?;
                i += 1;
            }
        }
        // `leaves` が `self.layers` の要求件数より多い（より大きなモデルの
        // `DeviceParamStore` を誤って渡した等）場合、余剰要素を無視した
        // まま黙って forward が成功すると、位置対応契約（層順に
        // weight → bias）が崩れているにもかかわらず誤った推論結果を
        // 返してしまう（Review 指摘）。`cursor` を消費し切ったことを
        // ここで検査し、余剰があれば fail-closed に拒否する
        // （`.claude/rules/security.md` A03）。
        if cursor.next().is_some() {
            return Err(AutodiffError::InvalidArgument(
                "Sequential::forward_from_flat_leaves: leaves has more elements than \
                 trainable_parameters() requires (extra weight/bias ignored)"
                    .to_string(),
            ));
        }
        Ok(current)
    }

    /// テスト専用の内部コンストラクタ（イシュー #1759 再構成前の
    /// `Sequential { layers: vec![...], training: true }` struct
    /// literal に代わる経路）。公開 `add_*` はビルダー限定・bias 有無を
    /// 自由に混在できないため、本クレート内テストが `Linear::new` を
    /// 直接呼んで構成する既存パターンを維持するための薄いヘルパー。
    #[cfg(test)]
    fn from_boxed_layers(layers: Vec<Box<dyn Module>>) -> Self {
        let mut inner = NnSequential::new();
        let mut specs = Vec::with_capacity(layers.len());
        for layer in layers {
            inner.push(layer);
            specs.push(LayerSpec::Unsupported { kind: "test" });
        }
        Sequential {
            inner,
            compiled: None,
            specs,
        }
    }
}

/// [`Sequential::bind`] が返す、1 学習ステップ分のテープ登録済み
/// ハンドル。`model`（`&'m Sequential`）は layer の走査順（活性化層・
/// `Linear`・`Conv2d`／`Conv1d`〈イシュー #1770〉の混在列）を再現する
/// ため、`linears`／`conv2ds`／`conv1ds`（層種別ごとに層順に抽出した
/// `*Vars` 列）は `Vec<Box<dyn Module>>` の添字とは別に独立して保持
/// する。
pub struct SequentialVars<'m, 't> {
    model: &'m Sequential,
    linears: Vec<LinearVars<'t>>,
    /// イシュー #3048。`linears` と平行（Linear 層ごと 1 件）の weight_norm 補助葉 `g`。
    /// weight_norm 済みでない層は `None`。
    linear_gs: Vec<Option<Var<'t>>>,
    /// イシュー #3049。Conv 6 種共通（Conv 層ごと 1 件・層順）の weight_norm 補助葉 `g`。
    /// weight_norm 済みでない層は `None`。
    conv_gs: Vec<Option<Var<'t>>>,
    conv2ds: Vec<Conv2dVars<'t>>,
    conv1ds: Vec<Conv1dVars<'t>>,
    /// イシュー #2521。`ConvTranspose1d` 層の bind 結果（層順）。
    conv_transpose1ds: Vec<ConvTranspose1dVars<'t>>,
    /// イシュー #2524。`Conv3d` 層の bind 結果（層順）。
    conv3ds: Vec<Conv3dVars<'t>>,
    /// イシュー #2523。`ConvTranspose2d` 層の bind 結果（層順）。
    conv_transpose2ds: Vec<ConvTranspose2dVars<'t>>,
    /// イシュー #3032。`ConvTranspose3d` 層の bind 結果（層順）。
    conv_transpose3ds: Vec<ConvTranspose3dVars<'t>>,
    /// イシュー #1760。`layer_norms`／`rms_norms`／`embeddings`／`mhas`
    /// は `Var<'t>` のみを保持し `'m` を借用しない（`nn::norm::
    /// LayerNormVars`／`RmsNormVars`・`nn::embedding::EmbeddingVars`・
    /// `nn::attention::MultiheadAttentionVars` の定義参照）。
    layer_norms: Vec<LayerNormVars<'t>>,
    rms_norms: Vec<RmsNormVars<'t>>,
    /// `BatchNorm1d`／`BatchNorm2d` 層を単一ベクタへ層順で収集する
    /// （`Sequential::bind` doc 参照）。`BatchNormVars<'t, 'm>` は
    /// 自身が由来した `BatchNormCore`（`self.model.inner.layers()` の
    /// 一部）を `&'m` で借用する——`RefCell` の running stats を train
    /// forward の都度更新するため。
    batch_norms: Vec<BatchNormVars<'t, 'm>>,
    embeddings: Vec<EmbeddingVars<'t>>,
    /// イシュー #2528。`EmbeddingBag` 層の bind 結果（層順）。
    embedding_bags: Vec<EmbeddingBagVars<'t>>,
    /// イシュー #2529。`PRelu` 層の bind 結果（層順）。
    prelus: Vec<PReluVars<'t>>,
    mhas: Vec<MultiheadAttentionVars<'t>>,
    /// `TransformerEncoderLayer` 層（イシュー #2068）を層順で収集する。
    /// `TransformerEncoderLayerVars<'t>` は `mhas` 同様 `Var<'t>` のみを
    /// 保持し `'m` を借用しない（`nn::transformer_encoder_layer::
    /// TransformerEncoderLayerVars` の定義参照）。
    encoders: Vec<TransformerEncoderLayerVars<'t>>,
    /// `TransformerDecoderLayer` 層（イシュー #2532）を層順で収集する。`encoders` と同じく
    /// `Var<'t>` のみを保持し `'m` を借用しない。
    decoders: Vec<TransformerDecoderLayerVars<'t>>,
    /// `Transformer` 層（イシュー #2533）の bind 結果（層順）。
    transformers: Vec<TransformerVars<'t>>,
}

impl<'m, 't> SequentialVars<'m, 't> {
    /// 学習用 forward。`Linear` 層は [`Sequential::bind`] で既に
    /// 登録済みの `LinearVars`（`self.linears`。層出現順の添字対応）を
    /// 使い、活性化層は `Module::forward` へ委譲する。
    ///
    /// **`Linear::bind` を再度呼ばない理由**: `Module::forward`
    /// （`fandhe_ai_autodiff::nn::module`）の `Linear` 実装は呼び出しのたびに
    /// `self.bind(tape)` して新しい葉ノードを作る（推論用の使い捨て
    /// 契約）。学習用 forward がこの経路を使うと、`bind` 時点で
    /// 取得した `LinearVars`（[`SequentialVars::trainable_vars`]/
    /// [`SequentialVars::trainable_grads`] が参照する `Var`）が forward
    /// のテープ記録に含まれず、`Tape::backward` 後の `Gradients::get`
    /// が到達不能（`Ok(None)`）を返してしまう。そのため学習用 forward
    /// は必ず `self.linears` に保持済みの `LinearVars::forward` を使う。
    pub fn forward(&self, tape: &'t Tape, input: &Var<'t>) -> Result<Var<'t>, AutodiffError> {
        self.forward_with_precision(tape, input, None)
    }

    /// [`Self::forward`] の内部実装。`low_precision` が `Some(dtype)` の
    /// とき、`Linear`（epilogue 融合有無を問わず）・`Conv2d`・
    /// `MultiheadAttention` 層を、それぞれ `linear_forward_low_precision`
    /// （イシュー #1960）・`conv2d_forward_low_precision`・
    /// `multihead_attention_forward_low_precision`（いずれもイシュー
    /// #2071。f32 master weight・backward は常に f32）へ切り替える
    /// （イシュー #1961・#2071・`docs/autodiff-low-precision-linear-
    /// design.md` §7「facade 統合（#1961）」・§8「Conv2d・
    /// MultiheadAttention 拡張（#2071）」）。それ以外の層（活性化・
    /// `Conv1d`／`LayerNorm`／`TransformerEncoderLayer`／`TransformerDecoderLayer` 等）は
    /// `low_precision` の値に関わらず常に f32 のまま——各低精度自由関数
    /// 自体が対応する層 1 種の forward 計算のみを対象とする opt-in
    /// 経路であり、他層への拡張は本イシューのスコープ外（`docs/
    /// autodiff-low-precision-linear-design.md` §8「スコープ外」）。
    /// `low_precision = None` のときは本メソッドが行う分岐は
    /// `fuse_relu` の判定を含め [`Self::forward`] 移設前の実装と完全に
    /// 同一の演算列・戻り値になる（bit 同一契約。`compat::Sequential::
    /// compile_with_amp` 未使用時の既存 `Sequential::forward`／`fit`
    /// 経路を壊さないための唯一の要件）。
    pub(super) fn forward_with_precision(
        &self,
        tape: &'t Tape,
        input: &Var<'t>,
        low_precision: Option<ScalarDType>,
    ) -> Result<Var<'t>, AutodiffError> {
        self.model
            .reject_untracked_parametric_layer("SequentialVars::forward")?;
        let mut current = *input;
        // `self.linears` は `model.layers` から `Linear` 層のみを同じ順序で
        // 抽出したもの（`Sequential::bind` 参照）のため、`Linear` 層に
        // 出会うたびにイテレータから 1 件ずつ消費すれば `model.layers`
        // 側の走査順と対応が取れる。添字アクセス（`self.linears[i]`）では
        // なくイテレータの `next()` を使う理由: 両者の対応は `bind`/
        // `forward` が同じ `as_linear().is_some()` 述語で層を数えている
        // ことに依存する不変条件であり、この不変条件自体は `self.model`
        // が `bind` 時点の `&'m Sequential` を保持し続ける（借用が生きた
        // ままの `SequentialVars` からは `model.layers` を書き換えられない）
        // ため現状は構造的に破れない。したがってこの `ok_or_else` 分岐は
        // 現状のコード構成では到達しない防御コードである。将来この関数・
        // `bind` のいずれかを書き換えて上記の対応関係が崩れた場合に、
        // 添字アクセスが本番経路で panic するのを避け fail-closed
        // （`InvalidArgument`）にするための保険として残す
        // （`.claude/rules/coding-rust.md` 本番経路 panic 禁止方針）。
        // イシュー #1044（`docs/kernel-fusion.md` §2.2「学習経路への
        // 結線」）: `Sequential::forward`（推論・非学習経路）と同じ
        // 「次層が `ReLU` かを先読みして `Linear` 層へ結線する」方式。
        // `self.linears` の消費は従来どおりイテレータ（`linears.next()`）
        // に任せる（`Linear` 層に出会うたびに 1 件ずつ。ReLU をスキップ
        // しても `linears` 自体には ReLU 分の要素がないため対応関係は
        // 崩れない）。インデックス走査へ変えたのは `self.model.layers`
        // 側で「次層」を覗く必要があるため。**`ReLU` が実際に続く場合
        // のみ**融合する（レビュー指摘 #1079・PRRT_kwDOTuUCJc6dgIt-。
        // `Sequential::forward` と同じ理由で `Linear` 単体・`Linear` →
        // `Sigmoid`／`Tanh` は `LinearVars::forward`〈非融合〉のまま。
        // `docs/inference-forward-fixed-cost-design.md` §3.1 の
        // bit-exactness 契約を学習側でも壊さない）。
        let mut linears = self.linears.iter();
        let mut linear_gs = self.linear_gs.iter();
        let mut conv2ds = self.conv2ds.iter();
        let mut conv1ds = self.conv1ds.iter();
        let mut conv_transpose1ds = self.conv_transpose1ds.iter();
        let mut conv3ds = self.conv3ds.iter();
        let mut conv_transpose2ds = self.conv_transpose2ds.iter();
        let mut conv_transpose3ds = self.conv_transpose3ds.iter();
        let mut conv_gs = self.conv_gs.iter();
        let mut layer_norms = self.layer_norms.iter();
        let mut rms_norms = self.rms_norms.iter();
        let mut batch_norms = self.batch_norms.iter();
        let mut embeddings = self.embeddings.iter();
        let mut embedding_bags = self.embedding_bags.iter();
        let mut prelus = self.prelus.iter();
        let mut mhas = self.mhas.iter();
        let mut encoders = self.encoders.iter();
        let mut decoders = self.decoders.iter();
        let mut transformers = self.transformers.iter();
        let layers = self.model.inner.layers();
        let mut i = 0;
        while i < layers.len() {
            let layer = &layers[i];
            if let Some(linear) = layer.as_linear() {
                let vars = linears.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み LinearVars が model.layers の \
                         Linear 層数より少ない（bind/forward 間の Linear 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let fuse_relu = layers.get(i + 1).is_some_and(|next| next.as_relu());
                let act = if fuse_relu {
                    Activation::Relu
                } else {
                    Activation::None
                };
                let g = linear_gs.next().and_then(|g| g.as_ref());
                current = match low_precision {
                    Some(_) if linear.is_parametrized() => {
                        // イシュー #3048: 低精度経路は生の weight で計算して黙って誤るため拒否する
                        // （有効重みの低精度計算は本イシューのスコープ外）。
                        return Err(AutodiffError::InvalidArgument(
                            "SequentialVars::forward: 再パラメータ化済み Linear（weight_norm／\
                             spectral_norm）は低精度（AMP）forward 非対応（イシュー #3048）"
                                .to_string(),
                        ));
                    }
                    Some(dtype) => linear_forward_low_precision(vars, &current, act, dtype)?,
                    // 非再パラメータ化は従来の `forward`／`forward_with_activation` と bit 同一。
                    None => linear.forward_bound(vars, g, &current, fuse_relu)?,
                };
                i += if fuse_relu { 2 } else { 1 };
            } else if let Some(conv) = layer.as_conv2d() {
                // イシュー #1770: Conv2d 層は Linear→ReLU のような
                // epilogue 融合を行わない（`nn::Conv2dVars::forward` は
                // `Var::conv2d` への薄い委譲のみ）。
                let vars = conv2ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み Conv2dVars が model.layers の \
                         Conv2d 層数より少ない（bind/forward 間の Conv2d 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = match low_precision {
                    Some(_) if conv.is_parametrized() => {
                        // イシュー #3049: 低精度経路は生の weight で計算して黙って誤るため拒否する。
                        return Err(AutodiffError::InvalidArgument(
                            "SequentialVars::forward: 再パラメータ化済み Conv2d（weight_norm／\
                             spectral_norm）は低精度（AMP）forward 非対応（イシュー #3049）"
                                .to_string(),
                        ));
                    }
                    Some(dtype) => conv2d_forward_low_precision(vars, &current, dtype)?,
                    None => conv.forward_bound(vars, g, &current)?,
                };
                i += 1;
            } else if let Some(conv) = layer.as_conv1d() {
                let vars = conv1ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み Conv1dVars が model.layers の \
                         Conv1d 層数より少ない（bind/forward 間の Conv1d 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = conv.forward_bound(vars, g, &current)?;
                i += 1;
            } else if let Some(conv) = layer.as_conv_transpose1d() {
                // イシュー #2521: AMP 低精度は Conv1d と同じく無視して f32 で forward する。
                let vars = conv_transpose1ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み ConvTranspose1dVars が model.layers の \
                         ConvTranspose1d 層数より少ない（bind/forward 間の層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = conv.forward_bound(vars, g, &current)?;
                i += 1;
            } else if let Some(conv) = layer.as_conv3d() {
                // イシュー #2524: AMP 低精度 conv3d は存在しないため dtype を無視して f32 で forward する。
                let vars = conv3ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み Conv3dVars が model.layers の \
                         Conv3d 層数より少ない（bind/forward 間の層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = conv.forward_bound(vars, g, &current)?;
                i += 1;
            } else if let Some(conv) = layer.as_conv_transpose2d() {
                // イシュー #2523: AMP 低精度は ConvTranspose1d と同じく無視して f32 で forward する。
                let vars = conv_transpose2ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み ConvTranspose2dVars が model.layers の \
                         ConvTranspose2d 層数より少ない（bind/forward 間の層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = conv.forward_bound(vars, g, &current)?;
                i += 1;
            } else if let Some(conv) = layer.as_conv_transpose3d() {
                // イシュー #3032: AMP 低精度は無視して f32 で forward する。
                let vars = conv_transpose3ds.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み ConvTranspose3dVars が model.layers の \
                         ConvTranspose3d 層数より少ない（bind/forward 間の層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                let g = conv_gs.next().and_then(|g| g.as_ref());
                current = conv.forward_bound(vars, g, &current)?;
                i += 1;
            } else if layer.as_layer_norm().is_some() {
                // イシュー #1760: LayerNorm も Conv2d／Conv1d と同様
                // epilogue 融合を行わない（`LayerNormVars::forward` は
                // `Var::layer_norm` への薄い委譲のみ）。
                let vars = layer_norms.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み LayerNormVars が model.layers の \
                         LayerNorm 層数より少ない（bind/forward 間の LayerNorm 層数対応が \
                         崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current)?;
                i += 1;
            } else if layer.as_rms_norm().is_some() {
                let vars = rms_norms.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み RmsNormVars が model.layers の \
                         RmsNorm 層数より少ない（bind/forward 間の RmsNorm 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current)?;
                i += 1;
            } else if layer.as_batch_norm1d().is_some() || layer.as_batch_norm2d().is_some() {
                // `BatchNormVars::forward` は `accepted_ranks`（1d は
                // rank 2/3・2d は rank 4）を自身で検査する（`bind`
                // doc 参照）ため、ここでは 1d／2d を区別しない。
                let vars = batch_norms.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み BatchNormVars が model.layers の \
                         BatchNorm 層数より少ない（bind/forward 間の BatchNorm 層数対応が \
                         崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current)?;
                i += 1;
            } else if layer.as_embedding().is_some() {
                // `EmbeddingVars::forward_from_var` が f32 `Var` 入力
                // から厳格に整数 id へ変換してから embedding を呼ぶ
                // （`nn/embedding.rs` の doc 参照）。
                let vars = embeddings.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み EmbeddingVars が model.layers の \
                         Embedding 層数より少ない（bind/forward 間の Embedding 層数対応が \
                         崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward_from_var(&current)?;
                i += 1;
            } else if layer.as_embedding_bag().is_some() {
                // bind 済みの `EmbeddingBagVars` で forward する（`Module::forward` は
                // 新しい葉を作り直し勾配が失われるため使わない。イシュー #2528）。
                let vars = embedding_bags.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み EmbeddingBagVars が model.layers の \
                         EmbeddingBag 層数より少ない（bind/forward 間の EmbeddingBag 層数対応が \
                         崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward_from_var(&current)?;
                i += 1;
            } else if layer.as_prelu().is_some() {
                // bind 済みの `PReluVars` で forward する（`Module::forward` は新しい葉を
                // 作り直し勾配が失われるため使わない。イシュー #2529）。
                let vars = prelus.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み PReluVars が model.layers の \
                         PRelu 層数より少ない（bind/forward 間の PRelu 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current)?;
                i += 1;
            } else if layer.as_multihead_attention().is_some() {
                // self-attention 固定（`q = k = v = current`・mask
                // なし・非 causal。`nn/attention.rs` モジュール doc
                // 「`Module` trait との関係」・`Sequential::
                // add_multihead_attention` doc 参照）。
                let vars = mhas.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み MultiheadAttentionVars が \
                         model.layers の MultiheadAttention 層数より少ない（bind/forward 間の \
                         MultiheadAttention 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                current = match low_precision {
                    Some(dtype) => multihead_attention_forward_low_precision(
                        vars, &current, &current, &current, None, false, dtype,
                    )?,
                    None => vars.forward(&current, &current, &current, None, false)?,
                };
                i += 1;
            } else if layer.as_transformer_encoder_layer().is_some() {
                // self-attention 固定（mask なし・非 causal。
                // `nn/transformer_encoder_layer.rs` モジュール doc・
                // `Sequential::add_transformer_encoder` doc 参照）。
                let vars = encoders.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み TransformerEncoderLayerVars が \
                         model.layers の TransformerEncoderLayer 層数より少ない（bind/forward \
                         間の TransformerEncoderLayer 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current, None, false)?;
                i += 1;
            } else if layer.as_transformer_decoder_layer().is_some() {
                // `tgt = memory = current`・mask なし・非 causal 固定（イシュー #2532。
                // `Sequential::add_transformer_decoder_layer` doc・`nn::Module for
                // TransformerDecoderLayer::forward` と同一の意味論）。
                let vars = decoders.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み TransformerDecoderLayerVars が \
                         model.layers の TransformerDecoderLayer 層数より少ない（bind/forward \
                         間の TransformerDecoderLayer 層数対応が崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current, &current, None, None, false, false)?;
                i += 1;
            } else if layer.as_transformer().is_some() {
                // `src = tgt = current`・mask なし・非 causal 固定（イシュー #2533。
                // `Sequential::add_transformer` doc・`nn::Module for Transformer::forward`
                // と同一の意味論）。
                let vars = transformers.next().ok_or_else(|| {
                    AutodiffError::InvalidArgument(
                        "SequentialVars::forward: bind 済み TransformerVars が model.layers の \
                         Transformer 層数より少ない（bind/forward 間の Transformer 層数対応が \
                         崩れた）"
                            .to_string(),
                    )
                })?;
                current = vars.forward(&current, &current, None, None, None, false)?;
                i += 1;
            } else {
                // 活性化層は `nn::Module::forward` へ委譲する（`&fandhe_ai_autodiff::Tape`
                // が必要。`Sequential::forward` と同じ理由で `tape.0` 経由）。
                current = layer.forward(&tape.0, &current)?;
                i += 1;
            }
        }
        Ok(current)
    }

    /// bind 済み `LinearVars` 列（層順）。受け入れ条件 1
    /// （「Sequential から学習可能パラメータを取得する API」）の本体。
    pub fn linears(&self) -> &[LinearVars<'t>] {
        &self.linears
    }

    /// [`Sequential::trainable_parameters`] と同一の順序契約（層順に
    /// weight → bias〈`Some` の場合のみ〉。イシュー #1770 で `Conv2d`／
    /// `Conv1d` を含む）で `Var` 参照列を返す。`add_module`（#2398）の独自層のパラメータは含まれない
    /// （signature 上 `Vec` のまま。`forward`／`trainable_grads` が拒否するため損失を作れず、
    /// optimizer の件数検査も塞ぐ）。
    pub fn trainable_vars(&self) -> Vec<&Var<'t>> {
        let mut out = Vec::new();
        let mut linears = self.linears.iter();
        let mut linear_gs = self.linear_gs.iter();
        let mut conv2ds = self.conv2ds.iter();
        let mut conv1ds = self.conv1ds.iter();
        let mut conv_transpose1ds = self.conv_transpose1ds.iter();
        let mut conv3ds = self.conv3ds.iter();
        let mut conv_transpose2ds = self.conv_transpose2ds.iter();
        let mut conv_transpose3ds = self.conv_transpose3ds.iter();
        let mut conv_gs = self.conv_gs.iter();
        let mut layer_norms = self.layer_norms.iter();
        let mut rms_norms = self.rms_norms.iter();
        let mut batch_norms = self.batch_norms.iter();
        let mut embeddings = self.embeddings.iter();
        let mut embedding_bags = self.embedding_bags.iter();
        let mut prelus = self.prelus.iter();
        let mut mhas = self.mhas.iter();
        let mut encoders = self.encoders.iter();
        let mut decoders = self.decoders.iter();
        let mut transformers = self.transformers.iter();
        for layer in self.model.inner.layers() {
            if layer.as_linear().is_some() {
                let g = linear_gs.next().and_then(|g| g.as_ref());
                if let Some(vars) = linears.next() {
                    // イシュー #3048: 再パラメータ化は `named_parameters` と同じ順（g → v → bias）。
                    if let Some(g) = g {
                        out.push(g);
                    }
                    out.push(&vars.weight);
                    if let Some(bias) = &vars.bias {
                        out.push(bias);
                    }
                }
            } else if layer.as_conv2d().is_some() {
                if let Some(vars) = conv2ds.next() {
                    if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                        out.push(g);
                    }
                    out.push(&vars.weight);
                    if let Some(bias) = &vars.bias {
                        out.push(bias);
                    }
                }
            } else if layer.as_conv1d().is_some()
                && let Some(vars) = conv1ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    out.push(g);
                }
                out.push(&vars.weight);
                if let Some(bias) = &vars.bias {
                    out.push(bias);
                }
            } else if layer.as_conv_transpose1d().is_some()
                && let Some(vars) = conv_transpose1ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    out.push(g);
                }
                out.push(&vars.weight);
                if let Some(bias) = &vars.bias {
                    out.push(bias);
                }
            } else if layer.as_conv3d().is_some()
                && let Some(vars) = conv3ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    out.push(g);
                }
                out.push(&vars.weight);
                if let Some(bias) = &vars.bias {
                    out.push(bias);
                }
            } else if layer.as_conv_transpose2d().is_some()
                && let Some(vars) = conv_transpose2ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    out.push(g);
                }
                out.push(&vars.weight);
                if let Some(bias) = &vars.bias {
                    out.push(bias);
                }
            } else if layer.as_conv_transpose3d().is_some()
                && let Some(vars) = conv_transpose3ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    out.push(g);
                }
                out.push(&vars.weight);
                if let Some(bias) = &vars.bias {
                    out.push(bias);
                }
            } else if layer.as_layer_norm().is_some()
                && let Some(vars) = layer_norms.next()
            {
                if let Some(w) = &vars.weight {
                    out.push(w);
                }
                if let Some(b) = &vars.bias {
                    out.push(b);
                }
            } else if layer.as_rms_norm().is_some()
                && let Some(vars) = rms_norms.next()
                && let Some(w) = &vars.weight
            {
                out.push(w);
            } else if (layer.as_batch_norm1d().is_some() || layer.as_batch_norm2d().is_some())
                && let Some(vars) = batch_norms.next()
            {
                if let Some(w) = &vars.weight {
                    out.push(w);
                }
                if let Some(b) = &vars.bias {
                    out.push(b);
                }
            } else if layer.as_embedding().is_some()
                && let Some(vars) = embeddings.next()
            {
                out.push(&vars.weight);
            } else if layer.as_embedding_bag().is_some()
                && let Some(vars) = embedding_bags.next()
            {
                out.push(&vars.weight);
            } else if layer.as_prelu().is_some()
                && let Some(vars) = prelus.next()
            {
                out.push(&vars.weight);
            } else if layer.as_multihead_attention().is_some()
                && let Some(vars) = mhas.next()
            {
                out.push(&vars.q.weight);
                if let Some(b) = &vars.q.bias {
                    out.push(b);
                }
                out.push(&vars.k.weight);
                if let Some(b) = &vars.k.bias {
                    out.push(b);
                }
                out.push(&vars.v.weight);
                if let Some(b) = &vars.v.bias {
                    out.push(b);
                }
                out.push(&vars.out.weight);
                if let Some(b) = &vars.out.bias {
                    out.push(b);
                }
            } else if layer.as_transformer_encoder_layer().is_some()
                && let Some(vars) = encoders.next()
            {
                push_encoder_layer_vars(&mut out, vars);
            } else if layer.as_transformer_decoder_layer().is_some()
                && let Some(vars) = decoders.next()
            {
                push_decoder_layer_vars(&mut out, vars);
            } else if layer.as_transformer().is_some()
                && let Some(vars) = transformers.next()
            {
                push_transformer_vars(&mut out, vars);
            }
        }
        out
    }

    /// `Tape::backward` の結果 `grads` から、同じ順序契約
    /// （`trainable_vars`/`trainable_parameters` と共通）で勾配参照列を
    /// 収集する。
    ///
    /// 勾配が存在しないパラメータ（loss へ未到達。`Gradients::get` が
    /// `Ok(None)` を返す場合）は黙って除外せず `InvalidArgument` にする
    /// （fail-closed）: 除外してしまうと戻り値の件数が
    /// `trainable_parameters()` の件数より少なくなり、
    /// [`crate::optim::Sgd::step`]／[`crate::optim::AdamW::step`]／
    /// [`crate::optim::Adam::step`] の
    /// 位置対応契約（`params[i]` ↔ `grads[i]`）
    /// が呼び出し元の意図と無関係にずれて、誤ったパラメータへ誤った
    /// 勾配を適用しかねないため（`.claude/rules/security.md` A03）。
    pub fn trainable_grads<'g>(
        &self,
        grads: &'g Gradients,
    ) -> Result<Vec<&'g Tensor<f32>>, AutodiffError> {
        self.model
            .reject_untracked_parametric_layer("SequentialVars::trainable_grads")?;
        let mut out = Vec::new();
        let mut linears = self.linears.iter();
        let mut linear_gs = self.linear_gs.iter();
        let mut conv2ds = self.conv2ds.iter();
        let mut conv1ds = self.conv1ds.iter();
        let mut conv_transpose1ds = self.conv_transpose1ds.iter();
        let mut conv3ds = self.conv3ds.iter();
        let mut conv_transpose2ds = self.conv_transpose2ds.iter();
        let mut conv_transpose3ds = self.conv_transpose3ds.iter();
        let mut conv_gs = self.conv_gs.iter();
        let mut layer_norms = self.layer_norms.iter();
        let mut rms_norms = self.rms_norms.iter();
        let mut batch_norms = self.batch_norms.iter();
        let mut embeddings = self.embeddings.iter();
        let mut embedding_bags = self.embedding_bags.iter();
        let mut prelus = self.prelus.iter();
        let mut mhas = self.mhas.iter();
        let mut encoders = self.encoders.iter();
        let mut decoders = self.decoders.iter();
        let mut transformers = self.transformers.iter();
        for layer in self.model.inner.layers() {
            if layer.as_linear().is_some() {
                let g = linear_gs.next().and_then(|g| g.as_ref());
                if let Some(vars) = linears.next() {
                    // イシュー #3048: weight_norm の g の勾配を先に積む（順序は trainable_vars と同じ）。
                    if let Some(g) = g {
                        push_weight_bias(&mut out, grads, g, None)?;
                    }
                    push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
                }
            } else if layer.as_conv2d().is_some() {
                if let Some(vars) = conv2ds.next() {
                    if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                        push_weight_bias(&mut out, grads, g, None)?;
                    }
                    push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
                }
            } else if layer.as_conv1d().is_some()
                && let Some(vars) = conv1ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    push_weight_bias(&mut out, grads, g, None)?;
                }
                push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
            } else if layer.as_conv_transpose1d().is_some()
                && let Some(vars) = conv_transpose1ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    push_weight_bias(&mut out, grads, g, None)?;
                }
                push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
            } else if layer.as_conv3d().is_some()
                && let Some(vars) = conv3ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    push_weight_bias(&mut out, grads, g, None)?;
                }
                push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
            } else if layer.as_conv_transpose2d().is_some()
                && let Some(vars) = conv_transpose2ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    push_weight_bias(&mut out, grads, g, None)?;
                }
                push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
            } else if layer.as_conv_transpose3d().is_some()
                && let Some(vars) = conv_transpose3ds.next()
            {
                if let Some(g) = conv_gs.next().and_then(|g| g.as_ref()) {
                    push_weight_bias(&mut out, grads, g, None)?;
                }
                push_weight_bias(&mut out, grads, &vars.weight, vars.bias.as_ref())?;
            } else if layer.as_layer_norm().is_some()
                && let Some(vars) = layer_norms.next()
            {
                push_opt_weight_bias(&mut out, grads, vars.weight.as_ref(), vars.bias.as_ref())?;
            } else if layer.as_rms_norm().is_some()
                && let Some(vars) = rms_norms.next()
            {
                push_opt_weight_bias(&mut out, grads, vars.weight.as_ref(), None)?;
            } else if (layer.as_batch_norm1d().is_some() || layer.as_batch_norm2d().is_some())
                && let Some(vars) = batch_norms.next()
            {
                push_opt_weight_bias(&mut out, grads, vars.weight.as_ref(), vars.bias.as_ref())?;
            } else if layer.as_embedding().is_some()
                && let Some(vars) = embeddings.next()
            {
                push_weight_bias(&mut out, grads, &vars.weight, None)?;
            } else if layer.as_embedding_bag().is_some()
                && let Some(vars) = embedding_bags.next()
            {
                push_weight_bias(&mut out, grads, &vars.weight, None)?;
            } else if layer.as_prelu().is_some()
                && let Some(vars) = prelus.next()
            {
                push_weight_bias(&mut out, grads, &vars.weight, None)?;
            } else if layer.as_multihead_attention().is_some()
                && let Some(vars) = mhas.next()
            {
                push_weight_bias(&mut out, grads, &vars.q.weight, vars.q.bias.as_ref())?;
                push_weight_bias(&mut out, grads, &vars.k.weight, vars.k.bias.as_ref())?;
                push_weight_bias(&mut out, grads, &vars.v.weight, vars.v.bias.as_ref())?;
                push_weight_bias(&mut out, grads, &vars.out.weight, vars.out.bias.as_ref())?;
            } else if layer.as_transformer_encoder_layer().is_some()
                && let Some(vars) = encoders.next()
            {
                push_encoder_layer_grads(&mut out, grads, vars)?;
            } else if layer.as_transformer_decoder_layer().is_some()
                && let Some(vars) = decoders.next()
            {
                push_decoder_layer_grads(&mut out, grads, vars)?;
            } else if layer.as_transformer().is_some()
                && let Some(vars) = transformers.next()
            {
                push_transformer_grads(&mut out, grads, vars)?;
            }
        }
        Ok(out)
    }
}

// ---------------------------------------------------------------------
// trainable_vars / trainable_grads 共通の層別ヘルパー
// （イシュー #2533。`Transformer` が encoder／decoder 層を内包するため、
// 単体層の分岐と `Transformer` 分岐で同一の順序契約を共有する。順序の正は
// `nn::Module::named_parameters`。encoder 16・decoder 26 個）
// ---------------------------------------------------------------------

fn push_weight_bias<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    weight: &Var<'_>,
    bias: Option<&Var<'_>>,
) -> Result<(), AutodiffError> {
    let weight_grad = grads.get(weight)?.ok_or_else(|| {
        AutodiffError::InvalidArgument(
            "SequentialVars::trainable_grads: weight に到達する勾配がない \
             (loss へ未到達)"
                .to_string(),
        )
    })?;
    out.push(weight_grad);
    if let Some(bias) = bias {
        let bias_grad = grads.get(bias)?.ok_or_else(|| {
            AutodiffError::InvalidArgument(
                "SequentialVars::trainable_grads: bias に到達する勾配がない \
                 (loss へ未到達)"
                    .to_string(),
            )
        })?;
        out.push(bias_grad);
    }
    Ok(())
}

/// [`push_weight_bias`] の weight 自体が `Option`（`LayerNorm`
/// の bias・`RmsNorm`／`BatchNorm` の weight・bias。affine なし
/// 構成では `None`）な層向けの版（イシュー #1760）。
fn push_opt_weight_bias<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    weight: Option<&Var<'_>>,
    bias: Option<&Var<'_>>,
) -> Result<(), AutodiffError> {
    if let Some(w) = weight {
        push_weight_bias(out, grads, w, None)?;
    }
    if let Some(b) = bias {
        push_weight_bias(out, grads, b, None)?;
    }
    Ok(())
}

fn push_mha_vars<'a, 't>(out: &mut Vec<&'a Var<'t>>, mha: &'a MultiheadAttentionVars<'t>) {
    for lin in [&mha.q, &mha.k, &mha.v, &mha.out] {
        out.push(&lin.weight);
        if let Some(b) = &lin.bias {
            out.push(b);
        }
    }
}

fn push_linear_vars<'a, 't>(out: &mut Vec<&'a Var<'t>>, lin: &'a LinearVars<'t>) {
    out.push(&lin.weight);
    if let Some(b) = &lin.bias {
        out.push(b);
    }
}

fn push_layer_norm_vars<'a, 't>(out: &mut Vec<&'a Var<'t>>, norm: &'a LayerNormVars<'t>) {
    if let Some(w) = &norm.weight {
        out.push(w);
    }
    if let Some(b) = &norm.bias {
        out.push(b);
    }
}

/// `TransformerEncoderLayer::named_parameters` の順
/// （`self_attn` → `linear1` → `linear2` → `norm1` → `norm2`。16 個）。
fn push_encoder_layer_vars<'a, 't>(
    out: &mut Vec<&'a Var<'t>>,
    vars: &'a TransformerEncoderLayerVars<'t>,
) {
    push_mha_vars(out, &vars.self_attn);
    push_linear_vars(out, &vars.linear1);
    push_linear_vars(out, &vars.linear2);
    push_layer_norm_vars(out, &vars.norm1);
    push_layer_norm_vars(out, &vars.norm2);
}

/// `TransformerDecoderLayer::named_parameters` の順
/// （`self_attn` → `multihead_attn` → `linear1` → `linear2` → `norm1` → `norm2` →
/// `norm3`。26 個。イシュー #2532）。
fn push_decoder_layer_vars<'a, 't>(
    out: &mut Vec<&'a Var<'t>>,
    vars: &'a TransformerDecoderLayerVars<'t>,
) {
    push_mha_vars(out, &vars.self_attn);
    push_mha_vars(out, &vars.multihead_attn);
    push_linear_vars(out, &vars.linear1);
    push_linear_vars(out, &vars.linear2);
    push_layer_norm_vars(out, &vars.norm1);
    push_layer_norm_vars(out, &vars.norm2);
    push_layer_norm_vars(out, &vars.norm3);
}

/// `Transformer::named_parameters` の順（`encoder.layers.{i}` → `encoder.norm` →
/// `decoder.layers.{i}` → `decoder.norm`。イシュー #2533）。
fn push_transformer_vars<'a, 't>(out: &mut Vec<&'a Var<'t>>, vars: &'a TransformerVars<'t>) {
    for layer in vars.encoder_layers() {
        push_encoder_layer_vars(out, layer);
    }
    push_layer_norm_vars(out, &vars.encoder_norm);
    for layer in vars.decoder_layers() {
        push_decoder_layer_vars(out, layer);
    }
    push_layer_norm_vars(out, &vars.decoder_norm);
}

fn push_mha_grads<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    mha: &MultiheadAttentionVars<'_>,
) -> Result<(), AutodiffError> {
    for lin in [&mha.q, &mha.k, &mha.v, &mha.out] {
        push_weight_bias(out, grads, &lin.weight, lin.bias.as_ref())?;
    }
    Ok(())
}

fn push_encoder_layer_grads<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    vars: &TransformerEncoderLayerVars<'_>,
) -> Result<(), AutodiffError> {
    push_mha_grads(out, grads, &vars.self_attn)?;
    push_weight_bias(out, grads, &vars.linear1.weight, vars.linear1.bias.as_ref())?;
    push_weight_bias(out, grads, &vars.linear2.weight, vars.linear2.bias.as_ref())?;
    push_opt_weight_bias(
        out,
        grads,
        vars.norm1.weight.as_ref(),
        vars.norm1.bias.as_ref(),
    )?;
    push_opt_weight_bias(
        out,
        grads,
        vars.norm2.weight.as_ref(),
        vars.norm2.bias.as_ref(),
    )?;
    Ok(())
}

fn push_decoder_layer_grads<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    vars: &TransformerDecoderLayerVars<'_>,
) -> Result<(), AutodiffError> {
    push_mha_grads(out, grads, &vars.self_attn)?;
    push_mha_grads(out, grads, &vars.multihead_attn)?;
    push_weight_bias(out, grads, &vars.linear1.weight, vars.linear1.bias.as_ref())?;
    push_weight_bias(out, grads, &vars.linear2.weight, vars.linear2.bias.as_ref())?;
    push_opt_weight_bias(
        out,
        grads,
        vars.norm1.weight.as_ref(),
        vars.norm1.bias.as_ref(),
    )?;
    push_opt_weight_bias(
        out,
        grads,
        vars.norm2.weight.as_ref(),
        vars.norm2.bias.as_ref(),
    )?;
    push_opt_weight_bias(
        out,
        grads,
        vars.norm3.weight.as_ref(),
        vars.norm3.bias.as_ref(),
    )?;
    Ok(())
}

fn push_transformer_grads<'g>(
    out: &mut Vec<&'g Tensor<f32>>,
    grads: &'g Gradients,
    vars: &TransformerVars<'_>,
) -> Result<(), AutodiffError> {
    for layer in vars.encoder_layers() {
        push_encoder_layer_grads(out, grads, layer)?;
    }
    push_opt_weight_bias(
        out,
        grads,
        vars.encoder_norm.weight.as_ref(),
        vars.encoder_norm.bias.as_ref(),
    )?;
    for layer in vars.decoder_layers() {
        push_decoder_layer_grads(out, grads, layer)?;
    }
    push_opt_weight_bias(
        out,
        grads,
        vars.decoder_norm.weight.as_ref(),
        vars.decoder_norm.bias.as_ref(),
    )?;
    Ok(())
}

/// `parametrize_*` の対象層（`Linear`／Conv 6 種）なら、すでに再パラメータ化済みかを返す
/// （対象外の層は `None`。イシュー #3048・#3049）。`check_parametrize_target` から呼ばれる。
fn parametrize_state(layer: &dyn Module) -> Option<bool> {
    if let Some(l) = layer.as_linear() {
        Some(l.is_parametrized())
    } else if let Some(c) = layer.as_conv2d() {
        Some(c.is_parametrized())
    } else if let Some(c) = layer.as_conv1d() {
        Some(c.is_parametrized())
    } else if let Some(c) = layer.as_conv3d() {
        Some(c.is_parametrized())
    } else if let Some(c) = layer.as_conv_transpose1d() {
        Some(c.is_parametrized())
    } else if let Some(c) = layer.as_conv_transpose2d() {
        Some(c.is_parametrized())
    } else {
        layer.as_conv_transpose3d().map(|c| c.is_parametrized())
    }
}

/// `layer` が spectral_norm 適用済みの Linear／Conv 6 種なら現在の状態の複製を返す
/// （`save_model` が `u`／`v` を buffer として保存するための読み出し。イシュー #3050）。
/// 適用済みでない・対象外の層は `None`。
pub(super) fn spectral_state_of(
    layer: &dyn Module,
) -> Option<fandhe_ai_autodiff::weight_reparam_ops::SpectralNormState> {
    if let Some(l) = layer.as_linear() {
        l.spectral_norm_state()
    } else if let Some(c) = layer.as_conv2d() {
        c.spectral_norm_state()
    } else if let Some(c) = layer.as_conv1d() {
        c.spectral_norm_state()
    } else if let Some(c) = layer.as_conv3d() {
        c.spectral_norm_state()
    } else if let Some(c) = layer.as_conv_transpose1d() {
        c.spectral_norm_state()
    } else if let Some(c) = layer.as_conv_transpose2d() {
        c.spectral_norm_state()
    } else {
        layer
            .as_conv_transpose3d()
            .and_then(|c| c.spectral_norm_state())
    }
}

/// `check_parametrize_target` 通過後に対象層を取り出せなかった場合（到達しない内部不変条件違反）の
/// 型付きエラー。
fn parametrize_unsupported_layer_error(layer_index: usize) -> AutodiffError {
    AutodiffError::InvalidArgument(format!(
        "Sequential::parametrize: 層 {layer_index} は再パラメータ化の対象層ではない"
    ))
}

/// Conv 6 種のいずれかなら、その層の weight_norm 補助葉 `g`（未適用は `None`）を `Some(..)` で返す。
/// Conv 以外の層は `None`（`SequentialVars` の `conv_gs` が Conv 層ごと 1 件・層順で持つための
/// 収集関数。イシュー #3049）。
fn bind_conv_weight_norm_g<'t>(
    layer: &dyn Module,
    tape: &'t fandhe_ai_autodiff::Tape,
) -> Option<Option<Var<'t>>> {
    if let Some(c) = layer.as_conv2d() {
        Some(c.bind_weight_norm_g(tape))
    } else if let Some(c) = layer.as_conv1d() {
        Some(c.bind_weight_norm_g(tape))
    } else if let Some(c) = layer.as_conv3d() {
        Some(c.bind_weight_norm_g(tape))
    } else if let Some(c) = layer.as_conv_transpose1d() {
        Some(c.bind_weight_norm_g(tape))
    } else if let Some(c) = layer.as_conv_transpose2d() {
        Some(c.bind_weight_norm_g(tape))
    } else {
        layer
            .as_conv_transpose3d()
            .map(|c| c.bind_weight_norm_g(tape))
    }
}
#[cfg(test)]
mod tests {
    use super::*;
    use crate::data::{DataLoaderConfig, TensorDataset};

    const SEED1: u64 = 1001;
    const SEED2: u64 = 2002;

    /// テスト専用の連続化ヘルパー（`fandhe_ai_tensor_core::Tensor` の `pub` API
    /// のみを使用。旧 `fandhe_ai_autodiff::eval::dense_vec`〈クレート非公開〉の
    /// 代替。`compat/array.rs` のテストヘルパーと同型）。
    fn dense_vec(t: &Tensor<f32>) -> Vec<f32> {
        t.contiguous()
            .as_slice()
            .expect("contiguous() 直後は必ず as_slice() が Some を返す")
            .to_vec()
    }

    /// パラメータ持ちの独自層（#2398）。
    struct P(Tensor<f32>);
    impl crate::nn::Module for P {
        fn forward<'t>(
            &self,
            _tape: crate::TapeRef<'t>,
            input: &Var<'t>,
        ) -> Result<Var<'t>, AutodiffError> {
            Ok(*input)
        }
        fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)> {
            vec![("w".into(), &self.0)]
        }
    }
    /// 無状態の独自層（#2398）。
    struct S;
    impl crate::nn::Module for S {
        fn forward<'t>(
            &self,
            _tape: crate::TapeRef<'t>,
            input: &Var<'t>,
        ) -> Result<Var<'t>, AutodiffError> {
            Ok(*input)
        }
    }

    /// `set_parameter` を持つ独自層。`fail` が真なら常に `Err`（#2398 の部分更新防止テスト用）。
    struct Settable {
        w: Tensor<f32>,
        fail: bool,
    }
    impl crate::nn::Module for Settable {
        fn forward<'t>(
            &self,
            _tape: crate::TapeRef<'t>,
            input: &Var<'t>,
        ) -> Result<Var<'t>, AutodiffError> {
            Ok(*input)
        }
        fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)> {
            vec![("w".into(), &self.w)]
        }
        fn set_parameter(&mut self, name: &str, value: Tensor<f32>) -> Result<(), AutodiffError> {
            if self.fail || name != "w" {
                return Err(AutodiffError::InvalidArgument(
                    "set_parameter failed".into(),
                ));
            }
            self.w = value;
            Ok(())
        }
    }

    #[test]
    fn apply_parameters_rolls_back_when_custom_layer_set_parameter_fails() {
        let one = || Tensor::from_slice(&[1.0_f32], &[1]).unwrap();
        let mut model = Sequential::new()
            .add_linear(2, 2, SEED1)
            .unwrap()
            .add_module(Settable {
                w: one(),
                fail: false,
            })
            .add_module(Settable {
                w: one(),
                fail: true,
            });
        let before: Vec<Vec<f32>> = model
            .trainable_parameters()
            .iter()
            .map(|t| dense_vec(t))
            .collect();
        let updated: Vec<Tensor<f32>> = model
            .trainable_parameters()
            .iter()
            .map(|t| Tensor::new(vec![9.0_f32; t.numel()], t.shape()).unwrap())
            .collect();
        assert!(model.apply_parameters(updated).is_err());
        let after: Vec<Vec<f32>> = model
            .trainable_parameters()
            .iter()
            .map(|t| dense_vec(t))
            .collect();
        assert_eq!(before, after);
    }

    /// 更新は 1 回目のみ成功し以後は常に失敗する独自層（復元失敗の検出テスト用）。
    struct FailsAfterFirst {
        w: Tensor<f32>,
        calls: usize,
    }
    impl crate::nn::Module for FailsAfterFirst {
        fn forward<'t>(
            &self,
            _tape: crate::TapeRef<'t>,
            input: &Var<'t>,
        ) -> Result<Var<'t>, AutodiffError> {
            Ok(*input)
        }
        fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)> {
            vec![("w".into(), &self.w)]
        }
        fn set_parameter(&mut self, _name: &str, value: Tensor<f32>) -> Result<(), AutodiffError> {
            self.calls += 1;
            if self.calls > 1 {
                return Err(AutodiffError::InvalidArgument("boom".into()));
            }
            self.w = value;
            Ok(())
        }
    }

    #[test]
    fn apply_parameters_reports_partial_update_when_rollback_fails() {
        let one = || Tensor::from_slice(&[1.0_f32], &[1]).unwrap();
        let mut model = Sequential::new()
            .add_module(FailsAfterFirst { w: one(), calls: 0 })
            .add_module(Settable {
                w: one(),
                fail: true,
            });
        let updated: Vec<Tensor<f32>> = model
            .trainable_parameters()
            .iter()
            .map(|t| Tensor::new(vec![9.0_f32; t.numel()], t.shape()).unwrap())
            .collect();
        let err = model.apply_parameters(updated).unwrap_err();
        match err {
            AutodiffError::InvalidArgument(m) => assert!(m.contains("partially updated"), "{m}"),
            other => panic!("unexpected error: {other:?}"),
        }
    }

    #[test]
    fn first_untracked_parametric_layer_detects_only_custom_parametric_layers() {
        let tracked = Sequential::new()
            .add_linear(2, 2, SEED1)
            .unwrap()
            .add_relu()
            .add_module(S);
        assert_eq!(tracked.first_untracked_parametric_layer(), None);
        let with_param = tracked.add_module(P(Tensor::from_slice(&[1.0], &[1]).unwrap()));
        assert_eq!(with_param.first_untracked_parametric_layer(), Some(3));
    }

    /// イシュー #2529: `PRelu`（`weight` を持つ型付き追跡層）は独自層扱いされない。
    /// 除外が漏れると `fit`／`forward`／`trainable_grads` がすべて拒否される。
    #[test]
    fn first_untracked_parametric_layer_does_not_flag_prelu() {
        let model = Sequential::new()
            .add_linear(2, 2, SEED1)
            .unwrap()
            .add_prelu(2, 0.25)
            .unwrap()
            .add_mish();
        assert_eq!(model.first_untracked_parametric_layer(), None);
    }

    #[test]
    fn sequential_builds_and_predicts_two_layer_mlp() {
        // 受け入れ条件（#95）: Sequential でのモデル構築・推論が動作する。
        let model = Sequential::new()
            .add_linear(8, 16, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(16, 4, SEED2)
            .unwrap();

        let batch = 3;
        let input = Tensor::new(vec![0.1_f32; batch * 8], &[batch, 8]).unwrap();
        let output = model.predict(&input).unwrap();

        assert_eq!(output.shape(), &[batch, 4]);
    }

    #[test]
    fn sequential_forward_matches_manual_forward_bit_exact() {
        // 同一シード・同一演算列で組んだ手動 forward（nn::Linear +
        // nn::activation を直接呼ぶ経路）と Sequential::forward の出力が
        // ビット一致することを確認する（同一演算列のため tolerance は
        // 新設しない。coding-rust.md「許容誤差を単独で緩和しない」の
        // 趣旨に沿い、ここでは緩和ではなく完全一致で判定する）。
        let linear1 = Linear::new(8, 16, true, SEED1).unwrap();
        let linear2 = Linear::new(16, 4, true, SEED2).unwrap();

        let batch = 2;
        let input_data: Vec<f32> = (0..batch * 8).map(|i| i as f32 * 0.05).collect();
        let input_tensor = Tensor::new(input_data, &[batch, 8]).unwrap();

        // 手動経路: Linear -> ReLU -> Linear を直接組み立てる。
        // `Linear::bind` は `&fandhe_ai_autodiff::Tape` を要求するため `manual_tape.0`
        // （同一クレート内なので `pub(crate)` フィールドへアクセス可能）
        // 経由で内部の生 Tape を渡す。
        let manual_tape = crate::tape();
        let manual_input = manual_tape.var(&input_tensor);
        let h = linear1.bind(&manual_tape.0).forward(&manual_input).unwrap();
        let h = h.relu();
        let manual_output = linear2.bind(&manual_tape.0).forward(&h).unwrap();

        // Sequential 経路: 同じ Linear インスタンスを Module として積む。
        let model = Sequential::from_boxed_layers(vec![
            Box::new(linear1),
            Box::new(Relu),
            Box::new(linear2),
        ]);
        let seq_tape = crate::tape();
        let seq_input = seq_tape.var(&input_tensor);
        let seq_output = model.forward(&seq_tape, &seq_input).unwrap();

        assert_eq!(
            dense_vec(&manual_output.to_tensor()),
            dense_vec(&seq_output.to_tensor())
        );
    }

    #[test]
    fn sequential_forward_on_external_tape_supports_backward() {
        // グラフ記録の整合確認: Sequential::forward を外部 Tape 上で
        // 実行し、Tape::backward まで通ることを検証する。
        let model = Sequential::new()
            .add_linear(4, 3, SEED1)
            .unwrap()
            .add_sigmoid();

        let tape = crate::tape();
        let input = tape.var(&Tensor::new(vec![0.1_f32, 0.2, 0.3, 0.4], &[1, 4]).unwrap());
        let output = model.forward(&tape, &input).unwrap();
        let loss = output.sum(None).unwrap();

        let grads = tape.backward(&loss).unwrap();
        // 入力自身の勾配が取得できること（グラフが入力ノードまで
        // つながっていることの確認）。
        let input_grad = grads
            .get(&input)
            .unwrap()
            .expect("入力は loss に寄与している");
        assert_eq!(input_grad.shape(), input.to_tensor().shape());
    }

    #[test]
    fn add_linear_propagates_invalid_argument() {
        // in_features == 0 は Linear::new が拒否する
        // （1/sqrt(in_features) が非有限になるため。fandhe_ai_autodiff::nn::linear 参照）。
        // add_linear はこれをそのまま Result で伝播する。
        // `Sequential` は `Box<dyn Module>` を保持し `Debug` を実装しない
        // ため、`unwrap_err()`（`Ok` 側にも `Debug` を要求する）は使わず
        // `match` で値を取り出す。
        let result = Sequential::new().add_linear(0, 4, SEED1);
        match result {
            Err(err) => assert!(matches!(err, AutodiffError::InvalidArgument(_))),
            Ok(_) => panic!("in_features == 0 は拒否されるはず"),
        }
    }

    // =================================================================
    // イシュー #1028: 推論 forward の固定費削減（tape 不要経路）
    // =================================================================

    /// [`Sequential::predict`] の新経路（tape 不要。`predict_tape_free`）が
    /// 旧経路（`predict_via_tape`）と bit 完全一致することを、
    /// Linear・ReLU・Sigmoid・Tanh を混在させた層構成・複数バッチ・
    /// bias 有無混在で確認する（`docs/inference-forward-fixed-cost-
    /// design.md` §3.3 (b) の bit-exactness 契約）。
    #[test]
    fn sequential_predict_tape_free_matches_via_tape_bit_exact() {
        for batch in [1usize, 3, 8] {
            let model = Sequential::from_boxed_layers(vec![
                Box::new(Linear::new(8, 16, true, SEED1).unwrap()),
                Box::new(Relu),
                Box::new(Linear::new(16, 12, false, SEED2).unwrap()),
                Box::new(Sigmoid),
                Box::new(Linear::new(12, 4, true, SEED1 + SEED2).unwrap()),
                Box::new(Tanh),
            ]);
            let input_data: Vec<f32> = (0..batch * 8).map(|i| (i as f32) * 0.05 - 0.3).collect();
            let input = Tensor::new(input_data, &[batch, 8]).unwrap();

            let via_tape_fast = model.predict(&input).unwrap();
            let via_tape_slow = model
                .predict_via_tape(&input, &mut NoopPhaseRecorder)
                .unwrap();

            assert_eq!(
                via_tape_fast.shape(),
                via_tape_slow.shape(),
                "batch={batch}"
            );
            assert_eq!(
                dense_vec(&via_tape_fast),
                dense_vec(&via_tape_slow),
                "predict（tape 不要経路）は predict_via_tape（旧経路）と \
                 bit 完全一致するはず（batch={batch}）"
            );
        }
    }

    /// [`Sequential::predict`]（tape 不要経路）が [`Silu`]／
    /// [`Hardswish`]／[`LeakyRelu`]／[`Elu`]（イシュー #1714）を含む層
    /// 構成でも旧経路（`predict_via_tape`）と bit 完全一致すること
    /// （`sequential_predict_tape_free_matches_via_tape_bit_exact` の
    /// 対象層を拡張する。4 層とも `Module::forward_host` が
    /// `Var::scalar_unary` と同じ `grad::scalar_unary_with_fallback` を
    /// 呼ぶため bit-exactness が構造的に成立する）。
    #[test]
    fn sequential_predict_tape_free_matches_via_tape_bit_exact_with_1714_layers() {
        for batch in [1usize, 3] {
            let model = Sequential::from_boxed_layers(vec![
                Box::new(Linear::new(8, 16, true, SEED1).unwrap()),
                Box::new(Silu),
                Box::new(Linear::new(16, 12, false, SEED2).unwrap()),
                Box::new(Hardswish),
                Box::new(Linear::new(12, 8, true, SEED1 + SEED2).unwrap()),
                Box::new(LeakyRelu::new(0.2)),
                Box::new(Linear::new(8, 4, true, SEED2 + 1).unwrap()),
                Box::new(Elu::new(1.3)),
            ]);
            let input_data: Vec<f32> = (0..batch * 8).map(|i| (i as f32) * 0.05 - 0.3).collect();
            let input = Tensor::new(input_data, &[batch, 8]).unwrap();

            let via_tape_fast = model.predict(&input).unwrap();
            let via_tape_slow = model
                .predict_via_tape(&input, &mut NoopPhaseRecorder)
                .unwrap();

            assert_eq!(
                via_tape_fast.shape(),
                via_tape_slow.shape(),
                "batch={batch}"
            );
            assert_eq!(
                dense_vec(&via_tape_fast),
                dense_vec(&via_tape_slow),
                "predict（tape 不要経路）は predict_via_tape（旧経路）と \
                 bit 完全一致するはず（batch={batch}）"
            );
        }
    }

    /// [`Sequential::predict`] は `add_linear`（bias あり既定）で構築した
    /// 通常の `Sequential::new()` 経由モデルでも新旧経路が一致すること
    /// （`layers` を直接構築するテスト専用経路だけでなく、公開 API の
    /// 通常経路でも成立することの確認）。
    #[test]
    fn sequential_predict_public_builder_tape_free_matches_via_tape() {
        let model = Sequential::new()
            .add_linear(4, 6, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(6, 2, SEED2)
            .unwrap();
        let input = Tensor::new(vec![0.1_f32, -0.2, 0.3, -0.4], &[1, 4]).unwrap();

        let fast = model.predict(&input).unwrap();
        let slow = model
            .predict_via_tape(&input, &mut NoopPhaseRecorder)
            .unwrap();

        assert_eq!(dense_vec(&fast), dense_vec(&slow));
    }

    /// イシュー #1218（`docs/perf/cpu-infer-predict-profile.md`）:
    /// `predict`（`Linear`→`ReLU` を `gemm_bias_act` へ結線した後の tape
    /// 不要経路）が、手動で組んだ非融合合成（`CpuBackendOps` の
    /// `gemm`→`add`→`relu`→`gemm`→`add`）と **bit 完全一致**することを
    /// 直接検証する（`Module::forward_host` doc の bit-exactness 契約は
    /// `crates/backend-cpu/tests/gemm_epilogue_parity.rs` が汎用形状で
    /// 保証済みだが、本テストは `predict` の Linear→ReLU 先読み結線
    /// ロジック自体〈`predict_tape_free_with_ops`〉が非融合合成と
    /// 一致する出力を組み立てていることを回帰検証する）。framework-compare
    /// の推論形状（784→256→ReLU→10）に加え、`gemv` 専用経路に触れる
    /// batch=1・BLIS のタイル境界（MR/NR）を跨ぐ batch=65/129 も検証する。
    #[test]
    fn sequential_predict_matches_manual_unfused_composition_bit_exact() {
        let ops = fandhe_ai_backend_cpu::CpuBackendOps::new();
        for batch in [1usize, 3, 65, 129] {
            let l1 = Linear::new(784, 256, true, SEED1).unwrap();
            let l2 = Linear::new(256, 10, true, SEED2).unwrap();
            let input_data: Vec<f32> = (0..batch * 784)
                .map(|i| ((i % 97) as f32) * 0.01 - 0.5)
                .collect();
            let input = Tensor::new(input_data, &[batch, 784]).unwrap();

            // 手動非融合合成: gemm -> add -> relu -> gemm -> add。
            let h = ops.gemm(&input, l1.weight()).unwrap();
            let h = ops.add(&h, l1.bias().unwrap()).unwrap();
            let h = ops.relu(&h).unwrap();
            let y = ops.gemm(&h, l2.weight()).unwrap();
            let expected = ops.add(&y, l2.bias().unwrap()).unwrap();

            let model =
                Sequential::from_boxed_layers(vec![Box::new(l1), Box::new(Relu), Box::new(l2)]);
            let actual = model.predict(&input).unwrap();

            assert_eq!(actual.shape(), expected.shape(), "batch={batch}");
            assert_eq!(
                dense_vec(&actual),
                dense_vec(&expected),
                "predict（Linear→ReLU 融合結線）は手動非融合合成と bit 完全一致するはず \
                 （batch={batch}）"
            );
        }
    }

    /// 上記と対称の否定形: `ReLU` が続かない構成（`Linear`→`Sigmoid`→
    /// `Linear`）では融合しないため、`predict` は末尾を除き手動非融合
    /// 合成とそのまま一致する（`Sigmoid` は `Activation` に対応する
    /// variant を持たないため融合対象外。`nn/module.rs::as_relu` doc
    /// 参照）。
    #[test]
    fn sequential_predict_linear_sigmoid_linear_matches_manual_composition() {
        let ops = fandhe_ai_backend_cpu::CpuBackendOps::new();
        let l1 = Linear::new(6, 5, true, SEED1).unwrap();
        let l2 = Linear::new(5, 3, false, SEED2).unwrap();
        let input = Tensor::new(vec![0.1_f32, -0.2, 0.3, -0.4, 0.5, -0.6], &[1, 6]).unwrap();

        let h = ops.gemm(&input, l1.weight()).unwrap();
        let h = ops.add(&h, l1.bias().unwrap()).unwrap();
        let h = Sigmoid.forward_host(&ops, &h).unwrap();
        let expected = ops.gemm(&h, l2.weight()).unwrap();

        let model =
            Sequential::from_boxed_layers(vec![Box::new(l1), Box::new(Sigmoid), Box::new(l2)]);
        let actual = model.predict(&input).unwrap();

        assert_eq!(dense_vec(&actual), dense_vec(&expected));
    }

    /// イシュー #1218: `predict_tape_free_with_ops` が実際に
    /// `Linear`→`ReLU` を `gemm_bias_act` 1 回へ結線し、末尾 `Linear`
    /// （`ReLU` が続かない）は非融合合成（`gemm`→`add`）のまま・別ノードの
    /// `relu` が発生しないことを `CountingOps`（本ファイル下部の
    /// `#1044` 学習 forward 検証と共用するカウンタ実装）で機械検証する。
    #[test]
    fn sequential_predict_tape_free_fuses_linear_relu_into_single_gemm_bias_act_call() {
        let model = Sequential::new()
            .add_linear(4, 8, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(8, 2, SEED2)
            .unwrap();

        let counters = Counters::default();
        let ops = CountingOps::new(counters.clone());
        let input = Tensor::new(vec![0.25_f32; 3 * 4], &[3, 4]).unwrap();

        model.predict_tape_free_with_ops(&ops, &input).unwrap();

        assert_eq!(
            Counters::get(&counters.gemm_bias_act),
            1,
            "Linear -> ReLU に融合された 1 個目の Linear のみ gemm_bias_act が 1 回呼ばれるはず"
        );
        assert_eq!(
            Counters::get(&counters.gemm),
            1,
            "ReLU が続かない 2 個目の Linear は非融合合成（gemm）のままのはず"
        );
        assert_eq!(
            Counters::get(&counters.add),
            1,
            "2 個目の Linear の bias 加算は非融合合成（add）のままのはず（tape 不要経路は \
             Var::add の遅延がなく即時実行されるため、学習側テストと異なり 1 回計上される）"
        );
        assert_eq!(
            Counters::get(&counters.relu),
            0,
            "ReLU は Linear へ融合され、別ノードとしての relu 呼び出しは発生しないはず"
        );
    }

    /// `Linear`→`Sigmoid`→`Linear` 構成では `gemm_bias_act` が一切
    /// 呼ばれないこと（融合対象は `Linear`→`ReLU` に限定）を確認する。
    #[test]
    fn sequential_predict_tape_free_does_not_fuse_non_relu_activation() {
        let model = Sequential::new()
            .add_linear(4, 5, SEED1)
            .unwrap()
            .add_sigmoid()
            .add_linear(5, 2, SEED2)
            .unwrap();

        let counters = Counters::default();
        let ops = CountingOps::new(counters.clone());
        let input = Tensor::new(vec![0.1_f32; 3 * 4], &[3, 4]).unwrap();

        model.predict_tape_free_with_ops(&ops, &input).unwrap();

        assert_eq!(
            Counters::get(&counters.gemm_bias_act),
            0,
            "Sigmoid は Activation に対応する variant を持たないため融合対象外のはず"
        );
    }

    // =================================================================
    // #294: 学習 API（optimizer 接続）
    // =================================================================

    #[test]
    fn bind_returns_linear_vars_in_layer_order_with_mixed_bias() {
        // bias 有無混在（第 1 層 bias あり・第 2 層 bias なし）で bind が
        // 層順どおり LinearVars を返すことを確認する。
        let l1 = Linear::new(4, 3, true, SEED1).unwrap();
        let l2 = Linear::new(3, 2, false, SEED2).unwrap();
        let model = Sequential::from_boxed_layers(vec![Box::new(l1), Box::new(Relu), Box::new(l2)]);

        let tape = crate::tape();
        let bound = model.bind(&tape);

        assert_eq!(bound.linears().len(), 2);
        assert!(bound.linears()[0].bias.is_some());
        assert!(bound.linears()[1].bias.is_none());
    }

    #[test]
    fn sequential_vars_forward_matches_manual_forward_bit_exact() {
        // SequentialVars::forward の出力が既存 Sequential::forward
        // （Module 経路）とビット一致することを検証する（tolerance は
        // 新設しない。既存 `sequential_forward_matches_manual_forward_bit_exact`
        // と同じ判定様式）。
        let batch = 2;
        let input_data: Vec<f32> = (0..batch * 8).map(|i| i as f32 * 0.05).collect();
        let input_tensor = Tensor::new(input_data, &[batch, 8]).unwrap();

        // Module 経路（既存の推論用 forward）。
        let module_model = Sequential::from_boxed_layers(vec![
            Box::new(Linear::new(8, 16, true, SEED1).unwrap()),
            Box::new(Relu),
            Box::new(Linear::new(16, 4, true, SEED2).unwrap()),
        ]);
        let module_tape = crate::tape();
        let module_input = module_tape.var(&input_tensor);
        let module_output = module_model.forward(&module_tape, &module_input).unwrap();

        // SequentialVars 経路（学習用 forward）。
        let train_model = Sequential::from_boxed_layers(vec![
            Box::new(Linear::new(8, 16, true, SEED1).unwrap()),
            Box::new(Relu),
            Box::new(Linear::new(16, 4, true, SEED2).unwrap()),
        ]);
        let train_tape = crate::tape();
        let bound = train_model.bind(&train_tape);
        let train_input = train_tape.var(&input_tensor);
        let train_output = bound.forward(&train_tape, &train_input).unwrap();

        assert_eq!(
            dense_vec(&module_output.to_tensor()),
            dense_vec(&train_output.to_tensor())
        );
    }

    #[test]
    fn trainable_parameters_order_contract_weight_then_bias_per_layer() {
        let model = Sequential::new()
            .add_linear(4, 3, SEED1) // bias あり
            .unwrap()
            .add_relu()
            .add_linear(3, 2, SEED2) // bias あり
            .unwrap();

        let params = model.trainable_parameters();
        // 層 1: weight, bias / 層 2: weight, bias の 4 件。
        assert_eq!(params.len(), 4);
        assert_eq!(params[0].shape(), &[4, 3]); // l1.weight
        assert_eq!(params[1].shape(), &[3]); // l1.bias
        assert_eq!(params[2].shape(), &[3, 2]); // l2.weight
        assert_eq!(params[3].shape(), &[2]); // l2.bias
    }

    #[test]
    fn apply_parameters_rejects_element_count_mismatch() {
        let mut model = Sequential::new().add_linear(4, 3, SEED1).unwrap();
        // trainable_parameters() は [weight, bias] の 2 件を要求するが
        // 1 件しか渡さない。
        let updated = vec![Tensor::new(vec![0.0f32; 12], &[4, 3]).unwrap()];
        let err = model.apply_parameters(updated).unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));
    }

    #[test]
    fn apply_parameters_propagates_bias_shape_mismatch() {
        let mut model = Sequential::new().add_linear(4, 3, SEED1).unwrap();
        // weight は rank 2 の妥当な shape（[4, 3]）だが、bias の shape が
        // weight.shape()[1]（out_features=3）と食い違う（[5]）ケース。
        // `Linear::from_parameters` の bias 検証（`fandhe_ai_autodiff::nn::linear`）
        // がこれを拒否することを確認する（`apply_parameters` は新パラメータ
        // 単体の内部整合性検証を重複実装せず委譲する、という設計の裏付け。
        // 置換前 shape との一致検証〈#426〉は本テストの weight 側では
        // 通過するため、ここで拒否されるのは委譲先の bias 検証由来）。
        let weight = Tensor::new(vec![0.0f32; 12], &[4, 3]).unwrap();
        let bad_bias = Tensor::new(vec![0.0f32; 5], &[5]).unwrap();
        let err = model.apply_parameters(vec![weight, bad_bias]).unwrap_err();
        assert!(matches!(err, AutodiffError::Shape(_)));
    }

    #[test]
    fn apply_parameters_leaves_model_unchanged_on_excess_element_count() {
        // two-pass 化の回帰テスト（review 指摘 #294 の Medium 項目、後半）:
        // 修正前は `if updated.next().is_some()` の超過件数チェックが
        // 全層への代入完了「後」に走っていたため、この分岐で `Err` を
        // 返すケースでも実際には全層が新パラメータへ更新済みという
        // 不整合（呼び出し側はエラー扱いなのにモデルは書き換わっている）
        // があった。two-pass では代入前に検証（超過チェックを含む）が
        // 完了するため、この場合もモデルは元の値のまま残ることを確認する。
        let mut model = Sequential::new().add_linear(2, 1, SEED1).unwrap();
        let original_params: Vec<Tensor<f32>> =
            model.trainable_parameters().into_iter().cloned().collect();

        // trainable_parameters() は [weight, bias] の 2 件を要求するが
        // 3 件目（余剰）を渡す。
        let weight = Tensor::new(vec![9.0f32, 9.0], &[2, 1]).unwrap();
        let bias = Tensor::new(vec![9.0f32], &[1]).unwrap();
        let extra = Tensor::new(vec![9.0f32], &[1]).unwrap();
        let err = model
            .apply_parameters(vec![weight, bias, extra])
            .unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));

        let after_params = model.trainable_parameters();
        assert_eq!(original_params.len(), after_params.len());
        for (before, after) in original_params.iter().zip(after_params.iter()) {
            assert_eq!(dense_vec(before), dense_vec(after));
        }
    }

    #[test]
    fn apply_parameters_updates_weights_used_by_subsequent_predict() {
        // apply_parameters で書き戻した値が実際に以後の forward に
        // 反映されることを確認する（薄いラッパー性の実証: compat 層は
        // Linear::from_parameters への委譲のみで独自状態を持たない）。
        let mut model = Sequential::new().add_linear(2, 1, SEED1).unwrap();
        let zero_weight = Tensor::new(vec![0.0f32, 0.0], &[2, 1]).unwrap();
        let zero_bias = Tensor::new(vec![7.0f32], &[1]).unwrap();
        model
            .apply_parameters(vec![zero_weight, zero_bias])
            .unwrap();

        let input = Tensor::new(vec![1.0f32, 2.0], &[1, 2]).unwrap();
        let output = model.predict(&input).unwrap();
        // weight=0 のため matmul 項は 0、bias=7.0 のみが出力される。
        assert!((output.get(&[0, 0]).unwrap() - 7.0).abs() < 1e-6);
    }

    #[test]
    fn apply_parameters_updates_bias_less_layer() {
        // `apply_parameters` の has_bias == false 分岐（bias を渡さず
        // weight のみ消費する経路）を直接カバーする。`Sequential::add_linear`
        // は常に bias ありの層しか組み立てられないため（公開 API からは
        // 到達不能。review 指摘 #294）、bias なし `Linear::new` を内部
        // コンストラクタ（`Sequential { layers: ... }`。同一クレート内の
        // テストのみ使用可能）で直接組み込んで検証する。
        let linear = Linear::new(2, 1, false, SEED1).unwrap();
        let mut model = Sequential::from_boxed_layers(vec![Box::new(linear)]);

        // has_bias == false のため trainable_parameters()/apply_parameters()
        // は weight 1 件のみを要求する。
        assert_eq!(model.trainable_parameters().len(), 1);

        let zero_weight = Tensor::new(vec![0.0f32, 0.0], &[2, 1]).unwrap();
        model.apply_parameters(vec![zero_weight]).unwrap();

        let input = Tensor::new(vec![1.0f32, 2.0], &[1, 2]).unwrap();
        let output = model.predict(&input).unwrap();
        // weight=0・bias なしのため出力は 0.0。
        assert!((output.get(&[0, 0]).unwrap()).abs() < 1e-6);
    }

    #[test]
    fn apply_parameters_leaves_model_unchanged_on_mid_sequence_shape_error() {
        // two-pass 化（review 指摘 #294 の Medium 項目）の回帰テスト:
        // 2 層目で shape 不整合エラーが起きても、検証は代入前に全件完了する
        // ため 1 層目（先に走査される層）はエラー前の値のまま保持される
        // （部分適用によるモデルの不整合な混在状態を防ぐ。
        // `.claude/rules/security.md` A03）。
        let mut model = Sequential::new()
            .add_linear(2, 3, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(3, 1, SEED2)
            .unwrap();

        let original_params: Vec<Tensor<f32>> =
            model.trainable_parameters().into_iter().cloned().collect();

        // 1 層目（weight, bias）は妥当な shape、2 層目の bias は
        // out_features=1 と食い違う shape（[5]）にして拒否させる。
        let l1_weight = Tensor::new(vec![9.0f32; 6], &[2, 3]).unwrap();
        let l1_bias = Tensor::new(vec![9.0f32; 3], &[3]).unwrap();
        let l2_weight = Tensor::new(vec![9.0f32; 3], &[3, 1]).unwrap();
        let l2_bad_bias = Tensor::new(vec![9.0f32; 5], &[5]).unwrap();

        let err = model
            .apply_parameters(vec![l1_weight, l1_bias, l2_weight, l2_bad_bias])
            .unwrap_err();
        assert!(matches!(err, AutodiffError::Shape(_)));

        // 1 層目を含め全パラメータがエラー前の値のまま残っていること。
        let after_params = model.trainable_parameters();
        assert_eq!(original_params.len(), after_params.len());
        for (before, after) in original_params.iter().zip(after_params.iter()) {
            assert_eq!(dense_vec(before), dense_vec(after));
        }
    }

    // =================================================================
    // #426: apply_parameters の置換前 shape 一致検証
    // =================================================================

    #[test]
    fn apply_parameters_rejects_weight_shape_change() {
        // 新 weight（[3, 3]）は `Linear::from_parameters` の単体検証
        // （rank 2・in_features > 0・bias 整合）は通過するが、置換前の
        // weight shape（[4, 3]）とは一致しない。#426 の検証がこれを
        // 拒否し、モデルは不変のまま残ることを確認する。
        let mut model = Sequential::new().add_linear(4, 3, SEED1).unwrap();
        let original_params: Vec<Tensor<f32>> =
            model.trainable_parameters().into_iter().cloned().collect();

        let new_weight = Tensor::new(vec![0.0f32; 9], &[3, 3]).unwrap();
        let new_bias = Tensor::new(vec![0.0f32; 3], &[3]).unwrap();
        let err = model
            .apply_parameters(vec![new_weight, new_bias])
            .unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));

        let after_params = model.trainable_parameters();
        assert_eq!(original_params.len(), after_params.len());
        for (before, after) in original_params.iter().zip(after_params.iter()) {
            assert_eq!(dense_vec(before), dense_vec(after));
        }
    }

    #[test]
    fn apply_parameters_rejects_interlayer_consistent_resize() {
        // 層間整合（層 1 の out_features == 層 2 の in_features）は
        // 保たれているが、置換前の層幅（2→3→1）自体を変える更新
        // （2→4→1）を渡すケース。#426 の設計判断
        // （「層間整合は置換前 shape 一致に内包される。リサイズは非
        // サポート」）どおり拒否されることを固定する。
        let mut model = Sequential::new()
            .add_linear(2, 3, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(3, 1, SEED2)
            .unwrap();

        let l1_weight = Tensor::new(vec![0.0f32; 8], &[2, 4]).unwrap();
        let l1_bias = Tensor::new(vec![0.0f32; 4], &[4]).unwrap();
        let l2_weight = Tensor::new(vec![0.0f32; 4], &[4, 1]).unwrap();
        let l2_bias = Tensor::new(vec![0.0f32; 1], &[1]).unwrap();

        let err = model
            .apply_parameters(vec![l1_weight, l1_bias, l2_weight, l2_bias])
            .unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));
    }

    #[test]
    fn apply_parameters_leaves_model_unchanged_on_mid_sequence_weight_shape_error() {
        // #426 の two-pass 非退行確認: 2 層目の weight shape のみ不一致に
        // した場合でも、1 層目（先に走査される層）を含む全パラメータが
        // エラー前の値のまま保持されることを確認する
        // （既存 `..._on_mid_sequence_shape_error` と同型。#294 の
        // 設計不変条件が #426 の検証にも及ぶことの回帰テスト）。
        let mut model = Sequential::new()
            .add_linear(2, 3, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(3, 1, SEED2)
            .unwrap();

        let original_params: Vec<Tensor<f32>> =
            model.trainable_parameters().into_iter().cloned().collect();

        // 1 層目（weight, bias）は妥当な shape、2 層目の weight のみ
        // 置換前 shape（[3, 1]）と食い違う shape（[3, 2]）にする。
        let l1_weight = Tensor::new(vec![9.0f32; 6], &[2, 3]).unwrap();
        let l1_bias = Tensor::new(vec![9.0f32; 3], &[3]).unwrap();
        let l2_weight = Tensor::new(vec![9.0f32; 6], &[3, 2]).unwrap();
        let l2_bias = Tensor::new(vec![9.0f32; 2], &[2]).unwrap();

        let err = model
            .apply_parameters(vec![l1_weight, l1_bias, l2_weight, l2_bias])
            .unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));

        let after_params = model.trainable_parameters();
        assert_eq!(original_params.len(), after_params.len());
        for (before, after) in original_params.iter().zip(after_params.iter()) {
            assert_eq!(dense_vec(before), dense_vec(after));
        }
    }

    /// イシュー #1044「Linear の epilogue 融合（bias + ReLU）が学習
    /// forward / backward 経路で適用されることを検証・修正する」の
    /// 機械検証本体。`fandhe_ai_backend_cpu::CpuBackendOps` を包み、
    /// `BackendOps` の各メソッド呼び出し回数を `AtomicUsize` で数える
    /// （`gemm_bias_act`／`gemm_resident_rhs_act` が実際に呼ばれ、
    /// 非融合合成〈`gemm`／`add`〉や別ノードの `relu` が呼ばれていない
    /// ことを検証する。値そのものは `CpuBackendOps` へ委譲するため
    /// 数値は変わらない）。`Tape::new_with_ops`（`pub(crate)`）を直接
    /// 呼べるのはこのクレート内（本ファイル）に限るため、この
    /// カウンタ検証は facade の統合テスト（`tests/*.rs`。別クレート
    /// コンパイル単位）ではなくここに置く。
    /// `CountingOps` の呼び出し回数カウンタ。`CountingOps` 自体は
    /// `Box<dyn BackendOps>` として `Tape` の所有物になり `Tape::ops()`
    /// は `&dyn BackendOps`（ダウンキャスト不能。`BackendOps` は
    /// `std::any::Any` を要求しない）しか返さないため、`Tape` 構築前に
    /// `Arc<AtomicUsize>` の複製をこちら側に残しておき、forward 後は
    /// この複製から読む。
    #[derive(Clone, Default)]
    struct Counters {
        gemm: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        add: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        relu: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        gemm_bias_act: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        run_fused: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        gemm_resident_rhs: std::sync::Arc<std::sync::atomic::AtomicUsize>,
        gemm_resident_rhs_act: std::sync::Arc<std::sync::atomic::AtomicUsize>,
    }

    impl Counters {
        fn get(counter: &std::sync::atomic::AtomicUsize) -> usize {
            counter.load(std::sync::atomic::Ordering::SeqCst)
        }
    }

    struct CountingOps {
        inner: fandhe_ai_backend_cpu::CpuBackendOps,
        counters: Counters,
    }

    impl CountingOps {
        fn new(counters: Counters) -> Self {
            Self {
                inner: fandhe_ai_backend_cpu::CpuBackendOps::new(),
                counters,
            }
        }
    }

    impl fandhe_ai_tensor_core::BackendOps for CountingOps {
        fn device(&self) -> fandhe_ai_tensor_core::device::Device {
            self.inner.device()
        }

        fn gemm(
            &self,
            a: &Tensor<f32>,
            b: &Tensor<f32>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .gemm
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.gemm(a, b)
        }

        fn add(
            &self,
            a: &Tensor<f32>,
            b: &Tensor<f32>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .add
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.add(a, b)
        }

        fn mul(
            &self,
            a: &Tensor<f32>,
            b: &Tensor<f32>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.inner.mul(a, b)
        }

        fn relu(
            &self,
            a: &Tensor<f32>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .relu
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.relu(a)
        }

        fn exp(&self, a: &Tensor<f32>) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.inner.exp(a)
        }

        fn tanh(
            &self,
            a: &Tensor<f32>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.inner.tanh(a)
        }

        fn sum(
            &self,
            a: &Tensor<f32>,
            dim: Option<usize>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.inner.sum(a, dim)
        }

        fn max(
            &self,
            a: &Tensor<f32>,
            dim: Option<usize>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.inner.max(a, dim)
        }

        fn gemm_bias_act(
            &self,
            a: &Tensor<f32>,
            b: &Tensor<f32>,
            bias: Option<&Tensor<f32>>,
            act: Activation,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .gemm_bias_act
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.gemm_bias_act(a, b, bias, act)
        }

        fn gemm_resident_rhs(
            &self,
            a: &Tensor<f32>,
            w: fandhe_ai_tensor_core::DeviceBufferView<'_>,
            bias: Option<fandhe_ai_tensor_core::DeviceBufferView<'_>>,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .gemm_resident_rhs
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.gemm_resident_rhs(a, w, bias)
        }

        fn gemm_resident_rhs_act(
            &self,
            a: &Tensor<f32>,
            w: fandhe_ai_tensor_core::DeviceBufferView<'_>,
            bias: Option<fandhe_ai_tensor_core::DeviceBufferView<'_>>,
            act: Activation,
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .gemm_resident_rhs_act
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.gemm_resident_rhs_act(a, w, bias, act)
        }

        fn run_fused(
            &self,
            plan: &fandhe_ai_tensor_core::FusionPlan,
            leaves: &[&Tensor<f32>],
        ) -> Result<Tensor<f32>, fandhe_ai_tensor_core::BackendError> {
            self.counters
                .run_fused
                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            self.inner.run_fused(plan, leaves)
        }
    }

    #[test]
    fn sequential_forward_fuses_linear_relu_into_single_gemm_bias_act_launch() {
        // 受け入れ条件 1（イシュー #1044。レビュー指摘 #1079・
        // PRRT_kwDOTuUCJc6dgIt- で融合対象を `Linear` → `ReLU` に限定する
        // よう修正）: `Linear` → `ReLU` の層あたりカーネル起動数が 1
        // （`gemm_bias_act`）になり、別ノードの `relu` が発生しないことを
        // 機械検証する。`ReLU` が続かない 2 個目の `Linear` は
        // bit-exactness 契約（`docs/inference-forward-fixed-cost-design.md`
        // §3.1）を守るため従来どおり非融合合成（`gemm` → `add`）のまま
        // であることも合わせて検証する。
        let model = Sequential::new()
            .add_linear(4, 8, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(8, 2, SEED2)
            .unwrap();

        // `counters`（`Arc` 共有）は `CountingOps` を `Box<dyn BackendOps>`
        // として `Tape` へ move した後もこちら側から読める（`Tape::ops()`
        // は `&dyn BackendOps` しか返さずダウンキャスト手段を持たない
        // ため、move 前に複製を残しておく設計）。
        let counters = Counters::default();
        let ops = CountingOps::new(counters.clone());
        let tape = Tape(fandhe_ai_autodiff::Tape::new_with_ops(Box::new(ops)));
        let input = Tensor::new(vec![0.25_f32; 3 * 4], &[3, 4]).unwrap();
        let input_var = tape.var(&input);

        let vars = model.bind(&tape);
        vars.forward(&tape, &input_var).unwrap();

        assert_eq!(
            Counters::get(&counters.gemm_bias_act),
            1,
            "Linear -> ReLU に融合された 1 個目の Linear のみ gemm_bias_act が \
             1 回呼ばれるはず"
        );
        assert_eq!(
            Counters::get(&counters.gemm),
            1,
            "ReLU が続かない 2 個目の Linear は非融合合成（gemm）のままのはず"
        );
        assert_eq!(
            Counters::get(&counters.add),
            0,
            "2 個目の Linear の bias 加算（Var::add）は遅延ノードのまま実体化されない \
             （本テストは to_tensor() 等で結果を実体化しないため Op::Add は記録されるのみで \
             BackendOps::add は呼ばれない。Var::add の遅延契約は var.rs 参照）"
        );
        assert_eq!(
            Counters::get(&counters.relu),
            0,
            "ReLU は Linear へ融合され、別ノードとしての relu 呼び出しは発生しないはず"
        );
        assert_eq!(
            Counters::get(&counters.run_fused),
            0,
            "本経路は run_fused（elementwise 融合）を経由しないはず"
        );
    }

    /// イシュー #1044 の backward 側検証: `Op::LinearAct` の VJP
    /// （`grad.rs`）が非融合合成（`Op::MatMul` → `Op::Add` → `Op::Relu`）
    /// の VJP と同じ勾配をパラメータへ返すことを、`Tape::backward` を
    /// 通した実測でビット一致検証する（`out_value` からの ReLU マスク
    /// 復元が既存 `Op::Relu` の劣勾配規約〈`x > 0`〉と一致することの
    /// 統合確認。単体の規約一致自体は `grad.rs` 側で `out_value > 0` と
    /// `Op::Relu` の `v > 0.0` が同値であることをコード上の理由として
    /// 既に記録している）。
    #[test]
    fn sequential_vars_forward_with_activation_grad_matches_manual_composition() {
        let linear1 = Linear::new(4, 8, true, SEED1).unwrap();
        let linear2 = Linear::new(8, 2, true, SEED2).unwrap();

        let batch = 3;
        let input_data: Vec<f32> = (0..batch * 4).map(|i| i as f32 * 0.07 - 0.5).collect();
        let input_tensor = Tensor::new(input_data, &[batch, 4]).unwrap();

        // 融合経路: `LinearVars::forward_with_activation` を直接呼ぶ
        // （`Sequential::bind().forward()` が内部で辿るのと同じ 1 ノード
        // 経路）。
        let fused_tape = crate::tape();
        let fused_input = fused_tape.var(&input_tensor);
        let fused_vars1 = linear1.bind(&fused_tape.0);
        let fused_vars2 = linear2.bind(&fused_tape.0);
        let h = fused_vars1
            .forward_with_activation(&fused_input, Activation::Relu)
            .unwrap();
        let out = fused_vars2
            .forward_with_activation(&h, Activation::None)
            .unwrap();
        let loss = out.sum(None).unwrap();
        let fused_grads = fused_tape.backward(&loss).unwrap();

        // 非融合経路: `matmul` → `add` → `relu` を明示的に合成する
        // （`LinearVars::forward` + `Var::relu`）。
        let manual_tape = crate::tape();
        let manual_input = manual_tape.var(&input_tensor);
        let manual_vars1 = linear1.bind(&manual_tape.0);
        let manual_vars2 = linear2.bind(&manual_tape.0);
        let h = manual_vars1.forward(&manual_input).unwrap();
        let h = h.relu();
        let out = manual_vars2.forward(&h).unwrap();
        let loss = out.sum(None).unwrap();
        let manual_grads = manual_tape.backward(&loss).unwrap();

        for (label, fused_var, manual_var) in [
            ("linear1.weight", &fused_vars1.weight, &manual_vars1.weight),
            ("linear2.weight", &fused_vars2.weight, &manual_vars2.weight),
        ] {
            let fused_g = fused_grads.get(fused_var).unwrap().unwrap();
            let manual_g = manual_grads.get(manual_var).unwrap().unwrap();
            assert_eq!(
                dense_vec(fused_g),
                dense_vec(manual_g),
                "{label}: 融合経路（Op::LinearAct）と非融合合成の勾配がビット一致しない"
            );
        }
        for (label, fused_var, manual_var) in [
            (
                "linear1.bias",
                fused_vars1.bias.as_ref().unwrap(),
                manual_vars1.bias.as_ref().unwrap(),
            ),
            (
                "linear2.bias",
                fused_vars2.bias.as_ref().unwrap(),
                manual_vars2.bias.as_ref().unwrap(),
            ),
        ] {
            let fused_g = fused_grads.get(fused_var).unwrap().unwrap();
            let manual_g = manual_grads.get(manual_var).unwrap().unwrap();
            assert_eq!(
                dense_vec(fused_g),
                dense_vec(manual_g),
                "{label}: 融合経路（Op::LinearAct）と非融合合成の勾配がビット一致しない"
            );
        }
    }

    /// `Linear`（bias 付き）→`ReLU`→`Linear`（bias 付き）の
    /// `build_device_chain_steps` が `Some` を返し、`ReLU` 融合
    /// （`Activation::Relu`）が 1 層目にのみ適用されることを検証する
    /// （イシュー #1688）。
    #[test]
    fn build_device_chain_steps_fuses_linear_relu() {
        let model = Sequential::new()
            .add_linear(4, 8, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(8, 2, SEED2)
            .unwrap();
        let tape = crate::tape();
        let store = model.init_device_param_store(&tape).unwrap();
        let leaves = store.snapshot_resident_params(&tape.0).unwrap();

        let steps = model
            .build_device_chain_steps(&leaves)
            .expect("Linear+ReLU+Linear は chain 経路対応のはず");

        assert_eq!(steps.len(), 2);
        assert!(matches!(steps[0].2, Activation::Relu));
        assert!(matches!(steps[1].2, Activation::None));
        assert!(
            steps[0].1.is_some(),
            "1 層目の bias が steps へ含まれていない"
        );
        assert!(
            steps[1].1.is_some(),
            "2 層目の bias が steps へ含まれていない"
        );
    }

    /// `Linear`→`Sigmoid` の構成では `Sigmoid` が chain 経路非対応の
    /// ため `None`（フォールバック対象）を返すことを検証する（イシュー
    /// #1688）。
    #[test]
    fn build_device_chain_steps_returns_none_for_sigmoid_mix() {
        let model = Sequential::new()
            .add_linear(4, 8, SEED1)
            .unwrap()
            .add_sigmoid();
        let tape = crate::tape();
        let store = model.init_device_param_store(&tape).unwrap();
        let leaves = store.snapshot_resident_params(&tape.0).unwrap();

        assert!(model.build_device_chain_steps(&leaves).is_none());
    }

    /// `leaves` が `self.layers` の要求件数より少ない・多いいずれの場合も
    /// `None`（フォールバック対象）を返すことを検証する（イシュー
    /// #1688。`forward_from_flat_leaves` の同種検査と同じ位置対応契約）。
    #[test]
    fn build_device_chain_steps_returns_none_for_leaf_count_mismatch() {
        let model = Sequential::new()
            .add_linear(4, 8, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(8, 2, SEED2)
            .unwrap();
        let tape = crate::tape();
        let store = model.init_device_param_store(&tape).unwrap();
        let leaves = store.snapshot_resident_params(&tape.0).unwrap();

        // 過少: 末尾（2 層目の bias）を切り詰める。
        let too_few = &leaves[..leaves.len() - 1];
        assert!(model.build_device_chain_steps(too_few).is_none());

        // 過剰: `ResidentLeaf` は `Clone` なので複製して水増しする。
        let mut too_many = leaves.clone();
        too_many.push(leaves[0].clone());
        assert!(model.build_device_chain_steps(&too_many).is_none());
    }

    /// 空 `Sequential`（層が 1 つもない）の場合は `None` を返すことを
    /// 検証する（イシュー #1688。空チェーンのための無意味な
    /// upload/download を避けるための早期リターン）。
    #[test]
    fn build_device_chain_steps_returns_none_for_empty_sequential() {
        let model = Sequential::new();
        let tape = crate::tape();
        let store = model.init_device_param_store(&tape).unwrap();
        let leaves = store.snapshot_resident_params(&tape.0).unwrap();

        assert!(leaves.is_empty());
        assert!(model.build_device_chain_steps(&leaves).is_none());
    }

    /// `Linear`（bias なし）→`Linear`（bias あり）の構成で
    /// `build_device_chain_steps` が `bias: None` を正しく含む steps を
    /// 返すことを検証する（イシュー #1688。`Sequential::add_linear`
    /// 〈唯一の公開層追加 API〉は常に bias あり `Linear` を積むため
    /// （`Sequential::add_linear` doc 参照）、bias なし層は公開 API から
    /// 構成できず、本テスト〈同一クレート内・`Linear::new` を直接呼ぶ〉
    /// でのみカバー可能。`crates/facade/tests/
    /// predict_device_chain_cpu_bit_exact.rs` の bit 完全一致テストは
    /// 公開 API 経由で構成可能な bias あり構成のみを対象とする旨も
    /// 同ファイル冒頭に明記済み）。
    #[test]
    fn build_device_chain_steps_includes_none_bias_for_no_bias_linear() {
        let linear_no_bias = Linear::new(4, 8, false, SEED1).unwrap();
        let linear_with_bias = Linear::new(8, 2, true, SEED2).unwrap();
        let model = Sequential::from_boxed_layers(vec![
            Box::new(linear_no_bias),
            Box::new(linear_with_bias),
        ]);
        let tape = crate::tape();
        let store = model.init_device_param_store(&tape).unwrap();
        let leaves = store.snapshot_resident_params(&tape.0).unwrap();

        let steps = model
            .build_device_chain_steps(&leaves)
            .expect("bias なし Linear + bias あり Linear は chain 経路対応のはず");

        assert_eq!(steps.len(), 2);
        assert!(steps[0].1.is_none(), "1 層目（bias なし）が None ではない");
        assert!(steps[1].1.is_some(), "2 層目（bias あり）が Some ではない");
        // 位置対応契約: leaves は weight のみ（1 層目）+ weight/bias
        // （2 層目）の 3 要素のはず。
        assert_eq!(leaves.len(), 3);
    }

    // =====================================================================
    // `predict_batches`（イシュー #2192・#2582・親 #2131）: 公開経路の振る舞い
    // テストは `tests/inference_predict_batches.rs` に置く。ここには crate 内
    // 限定の `global_rng_test_lock`（非公開）に依存する RNG 非消費の確認だけを
    // 残す。
    // =====================================================================

    fn mlp_model() -> Sequential {
        Sequential::new()
            .add_linear(4, 6, SEED1)
            .unwrap()
            .add_relu()
            .add_linear(6, 2, SEED2)
            .unwrap()
    }

    fn make_features(n: usize) -> Tensor<f32> {
        let data: Vec<f32> = (0..n * 4).map(|i| (i as f32) * 0.01 - 0.2).collect();
        Tensor::new(data, &[n, 4]).unwrap()
    }

    /// (e): `shuffle=true` を `InvalidArgument` で拒否し、RNG を消費
    /// しないこと。
    #[test]
    fn predict_batches_rejects_shuffle_without_consuming_rng() {
        let _guard = crate::compat::global_rng_test_lock()
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());

        fandhe_ai_tensor_core::rng::manual_seed(42);
        let before: Vec<f32> = fandhe_ai_tensor_core::rng::rand(&[4])
            .unwrap()
            .host_slice()
            .to_vec();

        fandhe_ai_tensor_core::rng::manual_seed(42);
        let model = mlp_model();
        let features = make_features(4);
        let dataset = TensorDataset::new(features).unwrap();
        let loader = DataLoader::new(dataset, DataLoaderConfig::new(2).shuffle(true)).unwrap();
        let err = model.predict_batches(&loader).unwrap_err();
        assert!(matches!(err, AutodiffError::InvalidArgument(_)));

        let after: Vec<f32> = fandhe_ai_tensor_core::rng::rand(&[4])
            .unwrap()
            .host_slice()
            .to_vec();
        assert_eq!(
            before, after,
            "shuffle=true の拒否経路がグローバル RNG を消費してはならない"
        );
    }
}