franken_ocr 0.10.0

//! Model-architecture descriptors — the foundation of the multi-model "model zoo"
//! (epic `bd-3jo6`, task A1).
//!
//! This is the FIRST, deliberately **additive** step of the multi-model
//! generalization: it describes each model's identity + graph shape + decode
//! contract + tokenizer + tasks as plain data behind a [`ModelArch`] trait, and a
//! [`registry`] that maps a model id to its descriptor — WITHOUT yet rewiring the
//! live forward. So the Baidu Unlimited-OCR engine stays byte-identical (its
//! goldens, CER, and `robot selftest` are unchanged); nothing here is on the hot
//! path. Later foundation tasks (A2 `.focrq` v2 + registry, A3 `convert`, A4
//! `pull`, A5 the multi-task CLI, A6 tokenizers, A7 the shared decoder) dispatch
//! real behavior through this descriptor.
//!
//! The Unlimited-OCR descriptor's values are asserted against the live engine
//! constants (`FOCR_MODEL_LICENSE_NOTICE`, `DEFAULT_MODEL_PATH`,
//! `sampler::DecodeParams::default()`) in the unit tests, so the description can
//! never silently drift from the real model.

/// The vision-encoder family a model uses. Only [`VisionEncoder::SamClip`] (the
/// Baidu Unlimited-OCR tower) is implemented today; the rest are the zoo targets,
/// declared so the registry + `focr models` can describe them before they land.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum VisionEncoder {
    /// SAM-ViT-B → 16× conv token-compressor → CLIP-L/14 (Baidu Unlimited-OCR).
    SamClip,
    /// SAM / VitDet-style ViT (GOT-OCR2.0, OneChart). [planned: B3/D3]
    SamVit,
    /// SigLIP ViT (SmolVLM2). [planned: C3]
    Siglip,
    /// ResNet stem + ViT (Polyphonic-TrOMR, pix2tex). [planned: E3/F2]
    ResNetVit,
    /// BEiT / DeiT ViT (TrOCR). [planned: F1]
    BeitVit,
}

/// The autoregressive-decoder family a model uses.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Decoder {
    /// DeepSeek-V2 MoE (64 routed + 2 shared experts, top-6) with R-SWA
    /// (Reference Sliding Window Attention, window 128) — the Baidu decoder.
    DeepSeekV2MoeRswa,
    /// The same DeepSeek-V2 MoE with SR-SWA (routed sparse page-block
    /// attention, page2d RoPE) — Unlimited-OCR-2. [planned: U2-B]
    DeepSeekV2MoeSrSwa,
    /// Qwen2 dense (GOT-OCR2.0). [shared engine A7]
    Qwen2Dense,
    /// SmolLM2 / Llama-style dense (SmolVLM2). [A7]
    LlamaDense,
    /// OPT-125M dense (OneChart, D-census §4: pre-LN, ReLU fc1/fc2, learned
    /// absolute positions offset-2, NO RoPE, all-linears-biased, tied head).
    /// [planned: D4 on A7]
    OptDense,
    /// mBART / RoBERTa-style seq2seq decoder (TrOCR, pix2tex). [planned: A7]
    Seq2SeqDense,
}

/// The tokenizer family a model uses.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum TokenizerKind {
    /// DeepSeek BPE over the committed `tokenizer.json` (Baidu Unlimited-OCR).
    DeepSeekBpe,
    /// Qwen2 BPE (GOT-OCR2.0). [A6/B6]
    Qwen2Bpe,
    /// SmolLM2 BPE (SmolVLM2). [A6/C6]
    SmolLm2Bpe,
    /// OPT / GPT-2 byte-level BPE over `vocab.json`+`merges.txt` (OneChart —
    /// D-census §7: NOT tiktoken, NOT Qwen). [planned: D9]
    Gpt2Bpe,
    /// A music-symbol vocabulary (Polyphonic-TrOMR). [planned: A6/E6]
    MusicVocab,
    /// SentencePiece / BART (TrOCR, pix2tex). [planned: A6/F]
    SentencePiece,
}

/// A task a model can serve — the routing key for the multi-task CLI (A5).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Task {
    /// Document text → markdown (the default `focr ocr`).
    Ocr,
    /// Math / formula → LaTeX.
    Formula,
    /// Tables → structured markdown / TEDS.
    Tables,
    /// Chart / graph → structured data.
    Chart,
    /// Molecular structure → SMILES.
    Molecular,
    /// Geometry → tikz.
    Geometry,
    /// Sheet music → MusicXML / **kern.
    Music,
    /// Photo description / captioning.
    Describe,
    /// Visual question answering.
    Vqa,
    /// Handwriting recognition.
    Handwriting,
}

/// The greedy-decode contract a model ships with — a plain-data mirror of the
/// load-bearing knobs in [`sampler::DecodeParams`] (so a descriptor needs no
/// runtime). Asserted equal to the live `DecodeParams::default()` in tests.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct DecodeContract {
    /// Sampling temperature; `0.0` ⇒ greedy argmax.
    pub temperature: f32,
    /// EOS token id.
    pub eos_token_id: u32,
    /// No-repeat n-gram size; `0` disables.
    pub no_repeat_ngram_size: usize,
    /// Sliding window for the no-repeat n-gram processor.
    pub ngram_window: usize,
    /// The ids the n-gram ban reads.
    pub ngram_domain: NgramDomain,
    /// How one decode carries several pages, for a model whose prompt and
    /// output mark them with a token; `None` otherwise (v1's multi-page
    /// output is split on the marker's text, in postprocess).
    pub pages: Option<PageContract>,
}

/// The ids a no-repeat n-gram ban reads (D10).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NgramDomain {
    /// The prompt and the generated ids: v1's live sampler.
    PromptAndGenerated,
    /// The generated ids only: Unlimited-OCR-2 (vLLM's processor,
    /// `modeling_unlimitedocr.py:608-622`).
    Generated,
}

/// A paged decode contract (U2-B6): one `<PAGE>` token opens each page in the
/// prompt, and the output must carry one per page.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PageContract {
    /// The page-marker token id.
    pub marker_id: u32,
    /// Whether the page-count guard runs ([`super::sampler::PageGuard`]).
    pub guard: bool,
    /// The guard's default per-page token cap; `0` means none.
    pub max_page_tokens: usize,
    /// How the output is split into pages.
    pub split: PageSplit,
}

/// How decoded output is split into pages.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PageSplit {
    /// On the marker's token id in the generated ids (D20).
    TokenId,
}

/// How far along an architecture is (`focr models` shows it).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Maturity {
    /// Registered as a roadmap target; every inference path refuses it.
    Planned,
    /// Runs, with a caveat: not yet certified against its reference.
    Experimental,
    /// Runs and is certified.
    Ready,
}

impl Maturity {
    /// The `focr models` status word.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Planned => "planned",
            Self::Experimental => "experimental",
            Self::Ready => "ready",
        }
    }
}

/// The quantization policy (doctrine #2): which tensor groups are int8 vs kept
/// high-precision. Every franken_ocr arch shares the SAME validated policy —
/// decoder GEMMs int8, the entire vision tower + projector + router + embed + ALL
/// norms high-precision — but each declares it explicitly so `focr convert` (A3)
/// is data-driven rather than hardcoded per model.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct QuantPolicy {
    /// Decoder FFN / expert / projection GEMMs are int8.
    pub decoder_gemms_int8: bool,
    /// Vision tower, projector, router gate, `embed_tokens`, and ALL norms stay
    /// BF16/F32 (quantizing the vision path wrecks accuracy — CER 0.37).
    pub vision_high_precision: bool,
    /// `lm_head` int8 is BEYOND the validated set — it ships only behind a
    /// measured-CER kill-switch (doctrine #2 / OQ-14), never assumed lossless.
    pub lm_head_int8_killswitched: bool,
}

impl QuantPolicy {
    /// The fixed, validated franken_ocr quant policy (doctrine #2). Every arch
    /// uses this shape.
    pub const DOCTRINE: Self = Self {
        decoder_gemms_int8: true,
        vision_high_precision: true,
        lm_head_int8_killswitched: true,
    };
}

/// The id of the Baidu Unlimited-OCR v1 model (R-SWA), fixed forever.
///
/// It is also the identity of every artifact that declares **no** `model_id`:
/// the `.focrq` writer omits the field for this model only, so all shipped v1
/// artifacts carry none. Absent therefore means v1 permanently, never "whatever
/// [`default_arch`] is today", or a later default change would load v1 bytes as
/// another model.
pub const UNLIMITED_OCR_V1_ID: &str = "unlimited-ocr";

/// The id of Baidu Unlimited-OCR-2 (SR-SWA). Its artifacts always declare it.
pub const UNLIMITED_OCR_V2_ID: &str = "unlimited-ocr-2";

/// Which Unlimited-OCR generation an arch is. Forward routing matches on this
/// exhaustively, so a new generation cannot fall through to another's kernels.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum UnlimitedVariant {
    /// Unlimited-OCR v1: R-SWA decoder attention (window 128).
    V1Rswa,
    /// Unlimited-OCR-2: SR-SWA decoder attention (routed page blocks).
    V2SrSwa,
}

/// An exact embedded tensor census a raw checkpoint is identified by.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TensorCensus {
    /// The pinned 2,710-tensor Unlimited-OCR v1 shard
    /// (`unlimited_ocr_census`).
    UnlimitedOcrV1,
    /// The pinned two-shard Unlimited-OCR-2 checkpoint: v1's census plus the
    /// embedded 109-tensor delta (`unlimited_ocr_census`, plan D22).
    UnlimitedOcrV2,
}

/// Exact recipe for the published GOT-OCR2 int8 artifact.
pub const GOT_OCR2_INT8_RECIPE: &str = "got-ocr2-decoder-int8-lmhead-omitted-tied-v1";
/// Exact recipe for the published SmolVLM2 int8 artifact.
pub const SMOLVLM2_INT8_RECIPE: &str = "smolvlm2-decoder-int8-lmhead-bf16-v1";
/// Exact recipe for the published OneChart int8 artifact.
pub const ONECHART_INT8_RECIPE: &str = "onechart-decoder-int8-lmhead-omitted-tied-v1";
/// Exact recipe for the published TrOMR int8 artifact.
pub const TROMR_INT8_RECIPE: &str = "tromr-decoder-int8-v1";
/// Exact recipe for the published TrOMR f32 reference artifact.
pub const TROMR_F32_RECIPE: &str = "tromr-f32-v1";

/// SHA-256 of the Baidu Unlimited-OCR v1 `tokenizer.json` (9,979,544 bytes),
/// the one sidecar every shipped v1 install carries (`models/manifest*.json`,
/// `docs/truth-pack/SOURCE_HASHES.md`).
const UNLIMITED_OCR_V1_TOKENIZER_SHA256: &str =
    "a02f8fd5228c90256bb4f6554c34a579d48f909e5beb232dc4afad870b55a8b4";

/// The added tokens the v1 prompt and parser depend on, as `(id, content)`.
const UNLIMITED_OCR_V1_TOKENS: &[(u32, &str)] = &[
    (crate::tokenizer::special::EOS, "<｜end▁of▁sentence｜>"),
    (crate::tokenizer::special::IMAGE, "<image>"),
    (crate::tokenizer::special::REF, "<|ref|>"),
    (crate::tokenizer::special::REF_END, "<|/ref|>"),
    (crate::tokenizer::special::DET, "<|det|>"),
    (crate::tokenizer::special::DET_END, "<|/det|>"),
    (crate::tokenizer::special::GROUNDING, "<|grounding|>"),
    (crate::tokenizer::special::USER, "<|User|>"),
    (crate::tokenizer::special::ASSISTANT, "<|Assistant|>"),
];

/// SHA-256 of the Unlimited-OCR-2 `tokenizer.json` (9,980,278 bytes): v1's file
/// plus the four non-special added tokens `<PAGE>`, `<BLOCK>`, `<FORK>`,
/// `<CHILD>` (ids 128827..=128830); every other section is byte-identical
/// (U2-A4, `docs/truth-pack/oq/tokenizer.md`).
pub(crate) const UNLIMITED_OCR_V2_TOKENIZER_SHA256: &str =
    "c55c165e32c5a67830362a53e1f548c8930dcc8469efa30ff3252a982799c589";

/// The added tokens the v2 prompt and page split depend on, as `(id, content)`.
pub(crate) const UNLIMITED_OCR_V2_TOKENS: &[(u32, &str)] = &[
    (crate::tokenizer::special::BOS, "<｜begin▁of▁sentence｜>"),
    (crate::tokenizer::special::EOS, "<｜end▁of▁sentence｜>"),
    (crate::tokenizer::special::IMAGE, "<image>"),
    (crate::tokenizer::special::PAGE, "<PAGE>"),
];

/// A model-architecture descriptor — the foundation `ModelArch` of the zoo. A
/// descriptor is pure metadata (no weights, no runtime); the forward dispatch is
/// wired through it in later A-tasks. `Send + Sync` so a `&'static dyn ModelArch`
/// can live in the process-global registry.
pub trait ModelArch: Send + Sync {
    /// Stable model id — the cache subdir, the `--model` value, and the manifest
    /// key, e.g. `"unlimited-ocr"`.
    fn id(&self) -> &'static str;
    /// Human display name, e.g. `"Baidu Unlimited-OCR"`.
    fn display_name(&self) -> &'static str;
    /// The redistribution / license notice that must travel with the model's
    /// `.focrq` and appear on agent-facing provenance surfaces.
    fn license_notice(&self) -> &'static str;
    /// The default `.focrq` basename in the cache, e.g. `"unlimited-ocr.focrq"`.
    fn default_artifact_basename(&self) -> &'static str;
    /// The vision-encoder family.
    fn vision_encoder(&self) -> VisionEncoder;
    /// The decoder family.
    fn decoder(&self) -> Decoder;
    /// The tokenizer family.
    fn tokenizer(&self) -> TokenizerKind;
    /// The quant policy (defaults to the doctrine policy; every arch uses it).
    fn quant_policy(&self) -> QuantPolicy {
        QuantPolicy::DOCTRINE
    }
    /// The greedy-decode contract this model ships with.
    fn decode_contract(&self) -> DecodeContract;
    /// The tasks this model serves (the CLI routes these to this arch).
    fn tasks(&self) -> &'static [Task];
    /// How far along this arch is.
    fn maturity(&self) -> Maturity;
    /// Whether this arch's forward runs TODAY (vs a planned zoo target the
    /// registry merely describes): every maturity but [`Maturity::Planned`].
    fn implemented(&self) -> bool {
        self.maturity() != Maturity::Planned
    }
    /// Whether `lm_head.weight` is a tied byte-alias of `model.embed_tokens.weight`
    /// and should therefore be **omitted** from the `.focrq` (the loader reuses the
    /// stored embedding for the output projection). `false` (the default) means the
    /// converter stores `lm_head` as its own tensor, as Unlimited-OCR does. GOT-OCR2
    /// ties (verified byte-identical — `docs/zoo/got-ocr2-spec.md` §12).
    fn tie_word_embeddings(&self) -> bool {
        false
    }
    /// The `.focrq` tensor-name prefix for this arch's SAM-family vision tower.
    /// Baidu Unlimited-OCR (default) uses `model.sam_model`; GOT-OCR2 uses
    /// `model.vision_tower_high` (identical leaf names + geometry, different prefix).
    fn vision_tower_prefix(&self) -> &'static str {
        "model.sam_model"
    }
    /// The tensor-name prefix of this arch's autoregressive-decoder transformer
    /// layers — the subtree `focr convert` classifies for the doctrine-#2 int8
    /// GEMM set. Baidu Unlimited-OCR + GOT-OCR2 put the LM at the model top
    /// (`model.layers.`); SmolVLM2's Idefics3 splice nests it under
    /// `model.text_model.layers.` (census: `docs/zoo/smolvlm2-spec.md` §12).
    /// Making the prefix an arch fact keeps the converter's classification
    /// arch-aware instead of name-coincidence: a SigLIP vision block named
    /// `model.vision_model.encoder.layers.{i}.self_attn.q_proj.weight` must
    /// NEVER match the decoder int8 set.
    fn decoder_layers_prefix(&self) -> &'static str {
        "model.layers."
    }
    /// When `lm_head.weight` is stored (i.e. NOT tied/omitted): does the
    /// converter quantize it int8? Default `false`: Unlimited-OCR and SmolVLM2
    /// keep their untied heads high precision per doctrine #2. An architecture
    /// may opt in only after its independent quality gate is certified.
    fn lm_head_stored_int8(&self) -> bool {
        false
    }
    /// The token-embedding tensor name — the untied-`lm_head` convert-time
    /// verification compares `lm_head.weight` bytes against this tensor.
    /// Default `model.embed_tokens.weight`; SmolVLM2 nests it under
    /// `model.text_model.embed_tokens.weight`.
    fn embed_tokens_name(&self) -> &'static str {
        "model.embed_tokens.weight"
    }
    /// The exact `packing_manifest.quant_recipe` a published artifact of this
    /// model at manifest quant `quant` (`"int8"`, `"f32"`) must declare; `None`
    /// when this runtime has no contract for that pair.
    fn required_quant_recipe(&self, quant: &str) -> Option<&'static str>;
    /// Which Unlimited-OCR generation this is; `None` for every zoo model.
    fn unlimited_variant(&self) -> Option<UnlimitedVariant> {
        None
    }
    /// The embedded exact census a raw checkpoint of this model is identified
    /// by; `None` when the model has none (it is then never inferred from a
    /// raw shard).
    fn tensor_census(&self) -> Option<TensorCensus> {
        None
    }
    /// The release version in this model's versioned artifact filename
    /// (`<stem>.v<version>.<quant>.focrq`).
    fn artifact_version(&self) -> &'static str {
        crate::UNLIMITED_OCR_ARTIFACT_VERSION
    }
    /// SHA-256 (lowercase hex) of the one `tokenizer.json` this model runs
    /// with; `None` when no sidecar hash is pinned.
    fn tokenizer_sha256(&self) -> Option<&'static str> {
        None
    }
    /// Added tokens the model's prompts and parsers depend on, as
    /// `(id, content)`. The sidecar must map every id to exactly its content.
    fn required_token_ids(&self) -> &'static [(u32, &'static str)] {
        &[]
    }
    /// Where the pinned `tokenizer.json` comes from when `focr pull` does not
    /// publish this model yet; `None` once it does. A refused sidecar's
    /// remediation names this source instead of `focr pull`.
    fn tokenizer_source(&self) -> Option<&'static str> {
        None
    }
}

impl std::fmt::Debug for dyn ModelArch + '_ {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.id())
    }
}

/// The Baidu Unlimited-OCR architecture — the FIRST [`ModelArch`] implementation
/// and the project default (`focr ocr`). Its descriptor values are asserted
/// against the live engine constants in tests, so the description cannot drift.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnlimitedOcr;

impl ModelArch for UnlimitedOcr {
    fn id(&self) -> &'static str {
        UNLIMITED_OCR_V1_ID
    }
    fn display_name(&self) -> &'static str {
        "Baidu Unlimited-OCR"
    }
    fn license_notice(&self) -> &'static str {
        crate::FOCR_MODEL_LICENSE_NOTICE
    }
    fn default_artifact_basename(&self) -> &'static str {
        "unlimited-ocr.focrq"
    }
    fn vision_encoder(&self) -> VisionEncoder {
        VisionEncoder::SamClip
    }
    fn decoder(&self) -> Decoder {
        Decoder::DeepSeekV2MoeRswa
    }
    fn tokenizer(&self) -> TokenizerKind {
        TokenizerKind::DeepSeekBpe
    }
    fn decode_contract(&self) -> DecodeContract {
        // The frozen single-image greedy contract (plan §6.10 / SPEC-100..103);
        // asserted equal to `sampler::DecodeParams::default()` in the tests.
        DecodeContract {
            temperature: 0.0,
            eos_token_id: 1,
            no_repeat_ngram_size: 35,
            ngram_window: 128,
            ngram_domain: NgramDomain::PromptAndGenerated,
            pages: None,
        }
    }
    fn tasks(&self) -> &'static [Task] {
        &[Task::Ocr]
    }
    fn maturity(&self) -> Maturity {
        Maturity::Ready
    }
    fn required_quant_recipe(&self, quant: &str) -> Option<&'static str> {
        (quant == "int8").then_some(crate::quant::convert::UNLIMITED_OCR_INT8_RECIPE_ID)
    }
    fn unlimited_variant(&self) -> Option<UnlimitedVariant> {
        Some(UnlimitedVariant::V1Rswa)
    }
    fn tensor_census(&self) -> Option<TensorCensus> {
        Some(TensorCensus::UnlimitedOcrV1)
    }
    fn tokenizer_sha256(&self) -> Option<&'static str> {
        Some(UNLIMITED_OCR_V1_TOKENIZER_SHA256)
    }
    fn required_token_ids(&self) -> &'static [(u32, &'static str)] {
        UNLIMITED_OCR_V1_TOKENS
    }
}

/// The one process-global Unlimited-OCR descriptor instance.
static UNLIMITED_OCR: UnlimitedOcr = UnlimitedOcr;

/// Baidu Unlimited-OCR-2: v1's vision tower and MoE decoder with SR-SWA
/// attention and page2d RoPE. Registered so its checkpoints and artifacts are
/// identified, census-checked and reported. [`Maturity::Ready`] since its
/// int8 artifact was certified (U2-C4) and published (U2-E4); it runs single
/// pages and documents of any length, in windows.
#[derive(Clone, Copy, Debug, Default)]
pub struct UnlimitedOcr2;

impl ModelArch for UnlimitedOcr2 {
    fn id(&self) -> &'static str {
        UNLIMITED_OCR_V2_ID
    }
    fn display_name(&self) -> &'static str {
        "Baidu Unlimited-OCR-2"
    }
    fn license_notice(&self) -> &'static str {
        // The GitHub LICENSE text; the HF v2 repo ships no LICENSE file.
        "Baidu Unlimited-OCR-2 - Copyright (c) 2026 Baidu, MIT License"
    }
    fn default_artifact_basename(&self) -> &'static str {
        "unlimited-ocr-2.focrq"
    }
    fn vision_encoder(&self) -> VisionEncoder {
        VisionEncoder::SamClip
    }
    fn decoder(&self) -> Decoder {
        Decoder::DeepSeekV2MoeSrSwa
    }
    fn tokenizer(&self) -> TokenizerKind {
        TokenizerKind::DeepSeekBpe
    }
    fn decode_contract(&self) -> DecodeContract {
        // Plan D10/D11/D20: greedy, EOS 1, n-gram 35 over the generated ids
        // (a 128 window for one page; the document loop widens it to 1024),
        // and the page contract: `<PAGE>` per page, the page-count guard with
        // its 20,000-token per-page cap, output split on the marker's id.
        DecodeContract {
            temperature: 0.0,
            eos_token_id: crate::tokenizer::special::EOS,
            no_repeat_ngram_size: 35,
            ngram_window: 128,
            ngram_domain: NgramDomain::Generated,
            pages: Some(PageContract {
                marker_id: crate::tokenizer::special::PAGE,
                guard: true,
                max_page_tokens: super::sampler::UOCR2_DEFAULT_MAX_PAGE_TOKENS,
                split: PageSplit::TokenId,
            }),
        }
    }
    fn tasks(&self) -> &'static [Task] {
        &[Task::Ocr]
    }
    fn maturity(&self) -> Maturity {
        Maturity::Ready
    }
    fn required_quant_recipe(&self, quant: &str) -> Option<&'static str> {
        (quant == "int8").then_some(crate::quant::convert::UNLIMITED_OCR_2_INT8_RECIPE_ID)
    }
    fn unlimited_variant(&self) -> Option<UnlimitedVariant> {
        Some(UnlimitedVariant::V2SrSwa)
    }
    fn tensor_census(&self) -> Option<TensorCensus> {
        Some(TensorCensus::UnlimitedOcrV2)
    }
    fn artifact_version(&self) -> &'static str {
        "0.1.0"
    }
    fn tokenizer_sha256(&self) -> Option<&'static str> {
        Some(UNLIMITED_OCR_V2_TOKENIZER_SHA256)
    }
    fn required_token_ids(&self) -> &'static [(u32, &'static str)] {
        UNLIMITED_OCR_V2_TOKENS
    }
}

/// The one process-global Unlimited-OCR-2 descriptor instance.
static UNLIMITED_OCR_2: UnlimitedOcr2 = UnlimitedOcr2;

/// A data-driven [`ModelArch`] for a PLANNED zoo model (epic bd-3jo6): described in
/// the registry — so `focr models` shows the roadmap — but with `implemented()` =
/// false until its forward lands. The graph-shape fields are confidently known
/// from the model survey; the exact decode contract + per-config values are filled
/// in (and the type upgraded to a real impl like [`UnlimitedOcr`]) when the model's
/// sub-epic ships. For a planned model the decode contract is informational and is
/// never used for inference.
pub struct PlannedArch {
    id: &'static str,
    display_name: &'static str,
    license_notice: &'static str,
    default_artifact_basename: &'static str,
    vision_encoder: VisionEncoder,
    decoder: Decoder,
    tokenizer: TokenizerKind,
    /// The greedy-decode contract, where known from the model's config/census
    /// (e.g. GOT-OCR2 from `docs/zoo/got-ocr2-spec.md`); `PLACEHOLDER_CONTRACT`
    /// until censused. Informational for a planned model (never used for inference).
    decode_contract: DecodeContract,
    tasks: &'static [Task],
    /// Whether the model ties `lm_head` to `embed_tokens` (so the converter omits
    /// `lm_head.weight`); see [`ModelArch::tie_word_embeddings`].
    tie_word_embeddings: bool,
    /// The SAM-family vision tower `.focrq` tensor-name prefix; see
    /// [`ModelArch::vision_tower_prefix`].
    vision_tower_prefix: &'static str,
    /// The AR-decoder transformer-layers tensor-name prefix (the int8 GEMM
    /// subtree); see [`ModelArch::decoder_layers_prefix`].
    decoder_layers_prefix: &'static str,
    /// Whether a STORED (untied) `lm_head.weight` joins this architecture's
    /// separately certified int8 set; see [`ModelArch::lm_head_stored_int8`].
    lm_head_stored_int8: bool,
    /// The token-embedding tensor name; see [`ModelArch::embed_tokens_name`].
    embed_tokens_name: &'static str,
    /// How far along this arch is (`focr models` status). GOT-OCR2 and the
    /// other shipped zoo models are ready; the rest are still descriptors.
    maturity: Maturity,
    /// `(manifest quant, recipe)` pairs for the published artifacts; see
    /// [`ModelArch::required_quant_recipe`].
    quant_recipes: &'static [(&'static str, &'static str)],
}

/// A not-yet-determined greedy contract for a planned model whose config has not
/// been censused (temperature 0 = greedy; the rest zeroed).
const PLACEHOLDER_CONTRACT: DecodeContract = DecodeContract {
    temperature: 0.0,
    eos_token_id: 0,
    no_repeat_ngram_size: 0,
    ngram_window: 0,
    ngram_domain: NgramDomain::PromptAndGenerated,
    pages: None,
};

impl ModelArch for PlannedArch {
    fn id(&self) -> &'static str {
        self.id
    }
    fn display_name(&self) -> &'static str {
        self.display_name
    }
    fn license_notice(&self) -> &'static str {
        self.license_notice
    }
    fn default_artifact_basename(&self) -> &'static str {
        self.default_artifact_basename
    }
    fn vision_encoder(&self) -> VisionEncoder {
        self.vision_encoder
    }
    fn decoder(&self) -> Decoder {
        self.decoder
    }
    fn tokenizer(&self) -> TokenizerKind {
        self.tokenizer
    }
    fn decode_contract(&self) -> DecodeContract {
        self.decode_contract
    }
    fn tasks(&self) -> &'static [Task] {
        self.tasks
    }
    fn maturity(&self) -> Maturity {
        self.maturity
    }
    fn tie_word_embeddings(&self) -> bool {
        self.tie_word_embeddings
    }
    fn vision_tower_prefix(&self) -> &'static str {
        self.vision_tower_prefix
    }
    fn decoder_layers_prefix(&self) -> &'static str {
        self.decoder_layers_prefix
    }
    fn lm_head_stored_int8(&self) -> bool {
        self.lm_head_stored_int8
    }
    fn embed_tokens_name(&self) -> &'static str {
        self.embed_tokens_name
    }
    fn required_quant_recipe(&self, quant: &str) -> Option<&'static str> {
        self.quant_recipes
            .iter()
            .find(|(q, _)| *q == quant)
            .map(|(_, recipe)| *recipe)
    }
}

// ── the planned zoo models (descriptors only; forwards land in sub-epics B-F) ──
// GOT-OCR2.0 — censused (docs/zoo/got-ocr2-spec.md, bd-3jo6.2.1): SAM-ViT-B encoder
// + Linear(1024→1024) connector + Qwen1.5/Qwen2-arch 0.5B DENSE decoder; the
// tokenizer is the original Qwen tiktoken BPE (qwen.tiktoken), not a HF tokenizer.json.
static GOT_OCR2: PlannedArch = PlannedArch {
    id: "got-ocr2",
    display_name: "GOT-OCR2.0",
    license_notice: "GOT-OCR2.0 (StepFun) - Apache-2.0",
    default_artifact_basename: "got-ocr2.focrq",
    vision_encoder: VisionEncoder::SamVit,
    decoder: Decoder::Qwen2Dense,
    tokenizer: TokenizerKind::Qwen2Bpe,
    // Real config (census): greedy, eos=151643 (<|endoftext|>), no_repeat_ngram=20
    // (HF builtin/global, window 0), max_new 4096, stop "<|im_end|>".
    decode_contract: DecodeContract {
        temperature: 0.0,
        eos_token_id: 151_643,
        no_repeat_ngram_size: 20,
        ngram_window: 0,
        ngram_domain: NgramDomain::PromptAndGenerated,
        pages: None,
    },
    tasks: &[
        Task::Ocr,
        Task::Formula,
        Task::Tables,
        Task::Chart,
        Task::Molecular,
        Task::Geometry,
        Task::Music,
    ],
    // Verified byte-identical lm_head == embed_tokens (spec §12) → omit lm_head.
    tie_word_embeddings: true,
    vision_tower_prefix: "model.vision_tower_high",
    decoder_layers_prefix: "model.layers.", // Qwen2 LM at the model top (spec §13a)
    lm_head_stored_int8: true,              // moot — tied lm_head is omitted entirely
    embed_tokens_name: "model.embed_tokens.weight",
    maturity: Maturity::Ready, // full pipeline + KV-cache decode ship (B1-B9,B11); focr ocr runs it
    quant_recipes: &[("int8", GOT_OCR2_INT8_RECIPE)],
};
// SmolVLM2-500M — censused (docs/zoo/smolvlm2-spec.md, bd-3jo6.3.1): SigLIP-B/16@512²
// encoder + pixel-shuffle×4 + Linear(12288→960) connector + SmolLM2-360M Llama-dense
// decoder (32L, hidden 960, GQA 15q/5kv, UNTIED lm_head — byte-verified, spec §12).
// The Idefics3 splice nests the LM under `model.text_model.*` and the SigLIP tower
// under `model.vision_model.*` (exact tensor names: spec §12).
static SMOLVLM2: PlannedArch = PlannedArch {
    id: "smolvlm2",
    display_name: "SmolVLM2-500M",
    license_notice: "SmolVLM2-500M-Video-Instruct (HuggingFaceTB) - Apache-2.0",
    default_artifact_basename: "smolvlm2.focrq",
    vision_encoder: VisionEncoder::Siglip,
    decoder: Decoder::LlamaDense,
    tokenizer: TokenizerKind::SmolLm2Bpe,
    // Real config (census §8): greedy, eos=49279 (<end_of_utterance>), and NO
    // repetition guard upstream (`no_repeat_ngram_size` absent ⇒ 0, window 0).
    decode_contract: DecodeContract {
        temperature: 0.0,
        eos_token_id: 49_279,
        no_repeat_ngram_size: 0,
        ngram_window: 0,
        ngram_domain: NgramDomain::PromptAndGenerated,
        pages: None,
    },
    tasks: &[Task::Describe, Task::Vqa],
    // Censused UNTIED (top-level `tie_word_embeddings: false`; lm_head vs
    // embed_tokens byte-verified DISTINCT — spec §12). The converter stores BOTH.
    tie_word_embeddings: false,
    vision_tower_prefix: "model.vision_model", // SigLIP tower (census §12)
    decoder_layers_prefix: "model.text_model.layers.", // Idefics3-nested LM (census §12)
    // Doctrine #2 / spec §11 (OQ-6): the untied lm_head [49280,960] stays
    // high-precision; int8-lm_head only behind a measured quality kill-switch.
    lm_head_stored_int8: false,
    embed_tokens_name: "model.text_model.embed_tokens.weight",
    // C1-C9 shipped: convert (C2), decoder (C5), tokenizer (C6), SigLIP +
    // pixel-shuffle connector (C3/C4, cert cos 1.0), prompt/preprocess (C7,
    // L0b maxabs 0.0 + L0c id-exact), `--task describe` routing (C9).
    maturity: Maturity::Ready,
    quant_recipes: &[("int8", SMOLVLM2_INT8_RECIPE)],
};
static ONECHART: PlannedArch = PlannedArch {
    id: "onechart",
    display_name: "OneChart",
    license_notice: "OneChart (kppkkp) - Apache-2.0",
    default_artifact_basename: "onechart.focrq",
    // CENSUSED (docs/zoo/onechart-spec.md, D1): SAM-ViT-B tower (GOT/Vary
    // lineage, prefix `model.vision_tower.` — NOT `vision_tower_high`), a
    // Linear(1024→768,bias) projector, an OPT-125M decoder (§4: pre-LN, ReLU
    // fc1/fc2, learned absolute positions offset-2, NO RoPE, MHA 12/12, all
    // linears biased), and the novel `num_decoder` number head (§8).
    vision_encoder: VisionEncoder::SamVit,
    decoder: Decoder::OptDense,
    tokenizer: TokenizerKind::Gpt2Bpe,
    // §10: greedy, eos 2 (`</s>`), NO upstream repetition guard; hard cap
    // total-seq ≤ 4096 (the learned position table, §4/OQ-D7).
    decode_contract: DecodeContract {
        temperature: 0.0,
        eos_token_id: 2,
        no_repeat_ngram_size: 0,
        ngram_window: 0,
        ngram_domain: NgramDomain::PromptAndGenerated,
        pages: None,
    },
    tasks: &[Task::Chart],
    // §4: `lm_head.weight` and `model.decoder.embed_tokens.weight` are stored
    // byte-identical (SHA-proven) — TIED; the `.focrq` keeps ONE copy (the
    // GOT precedent; convert byte-verifies the tie before dropping).
    tie_word_embeddings: true,
    vision_tower_prefix: "model.vision_tower",
    decoder_layers_prefix: "model.decoder.layers.",
    // Tied head via embed_tokens stays high-precision until a measured
    // kill-switched int8 lever lands (doctrine #2).
    lm_head_stored_int8: false,
    embed_tokens_name: "model.decoder.embed_tokens.weight",
    // D1-D9 shipped: convert (D2), tokenizer (D9), vision (D3), OPT decoder
    // both paths (D4), number head + self-verify + recognize (D5),
    // `--task chart-data` routing (D7).
    maturity: Maturity::Ready,
    quant_recipes: &[("int8", ONECHART_INT8_RECIPE)],
};
static TROMR: PlannedArch = PlannedArch {
    id: "tromr",
    display_name: "Polyphonic-TrOMR",
    license_notice: "Polyphonic-TrOMR (NetEase) - Apache-2.0",
    default_artifact_basename: "tromr.focrq",
    vision_encoder: VisionEncoder::ResNetVit,
    decoder: Decoder::Seq2SeqDense,
    tokenizer: TokenizerKind::MusicVocab,
    // CENSUSED (docs/zoo/tromr-spec.md §5/§9, E2): greedy argmax-forced (the
    // E8 oracle plan; upstream's top-k sampling is the OQ-T6 kill-switch),
    // stop on the RHYTHM stream's `[EOS]` = 2 (pad 0, bos 1, max_seq_len 256).
    decode_contract: DecodeContract {
        temperature: 0.0,
        eos_token_id: 2,
        no_repeat_ngram_size: 0,
        ngram_window: 0,
        ngram_domain: NgramDomain::PromptAndGenerated,
        pages: None,
    },
    tasks: &[Task::Music],
    // §12: NO `lm_head.weight` at all — FOUR untied per-stream heads
    // (`decoder.net.to_logits_{lift,pitch,rhythm,note}`), each Linear+bias.
    tie_word_embeddings: false,
    // §12: the whole tower (ResNetV2 stem + hybrid ViT) lives under `encoder.`
    // (WS is FOLDED into the stored conv weights at export — no runtime WS).
    vision_tower_prefix: "encoder.",
    // §12: flat x-transformers layout, `i%3` ⇒ 0=self-attn 1=cross-attn 2=ff.
    decoder_layers_prefix: "decoder.net.attn_layers.layers.",
    // §11: heads are tiny ([260/71/7/2]×256 Linear+bias) — always HP; the 40
    // decoder GEMMs are int8 CANDIDATES behind a measured-lossless gate only
    // (default f32; see quant::convert::is_decoder_int8_tensor_for).
    lm_head_stored_int8: false,
    // §12: THREE input embeddings summed per step (lift/pitch/rhythm) — no
    // single embed_tokens. The rhythm stream is primary (drives EOS); the
    // untie-verify never fires (no `lm_head.weight` exists).
    embed_tokens_name: "decoder.net.rhythm_emb.emb.weight",
    // E2-E7+E9 shipped: convert (E2), tokenizer (E6), encoder cos 1.0 (E3),
    // decoder token-exact (E4), merge+MusicXML (E7), `--task music` routing.
    maturity: Maturity::Ready,
    quant_recipes: &[("int8", TROMR_INT8_RECIPE), ("f32", TROMR_F32_RECIPE)],
};
static TROCR: PlannedArch = PlannedArch {
    id: "trocr",
    display_name: "TrOCR",
    license_notice: "TrOCR (Microsoft) - MIT",
    default_artifact_basename: "trocr.focrq",
    vision_encoder: VisionEncoder::BeitVit,
    decoder: Decoder::Seq2SeqDense,
    tokenizer: TokenizerKind::SentencePiece,
    decode_contract: PLACEHOLDER_CONTRACT,
    tasks: &[Task::Handwriting],
    tie_word_embeddings: false, // placeholder until censused (sub-epic F)
    vision_tower_prefix: "model.sam_model", // BeiT/ResNet; placeholder
    decoder_layers_prefix: "model.layers.", // placeholder until censused (sub-epic F)
    lm_head_stored_int8: true,  // placeholder until censused (sub-epic F)
    embed_tokens_name: "model.embed_tokens.weight",
    maturity: Maturity::Planned,
    quant_recipes: &[],
};
static PIX2TEX: PlannedArch = PlannedArch {
    id: "pix2tex",
    display_name: "pix2tex (LaTeX-OCR)",
    license_notice: "pix2tex / LaTeX-OCR - MIT",
    default_artifact_basename: "pix2tex.focrq",
    vision_encoder: VisionEncoder::ResNetVit,
    decoder: Decoder::Seq2SeqDense,
    tokenizer: TokenizerKind::SentencePiece,
    decode_contract: PLACEHOLDER_CONTRACT,
    tasks: &[Task::Formula],
    tie_word_embeddings: false, // placeholder until censused (sub-epic F)
    vision_tower_prefix: "model.sam_model", // BeiT/ResNet; placeholder
    decoder_layers_prefix: "model.layers.", // placeholder until censused (sub-epic F)
    lm_head_stored_int8: true,  // placeholder until censused (sub-epic F)
    embed_tokens_name: "model.embed_tokens.weight",
    maturity: Maturity::Planned,
    quant_recipes: &[],
};

/// The model registry, in priority order (the default first, then its successor
/// Unlimited-OCR-2, then the zoo). This is the single place models register.
/// Planned descriptors (`implemented() == false`) are shown by `focr models` and
/// upgraded as their sub-epics land.
static REGISTRY: &[&dyn ModelArch] = &[
    &UNLIMITED_OCR,
    &UNLIMITED_OCR_2,
    &GOT_OCR2,
    &SMOLVLM2,
    &ONECHART,
    &TROMR,
    &TROCR,
    &PIX2TEX,
];

/// The model registry slice (see [`static@REGISTRY`]).
#[must_use]
pub fn registry() -> &'static [&'static dyn ModelArch] {
    REGISTRY
}

/// Look up an architecture by its stable id; `None` if unknown.
#[must_use]
pub fn arch_by_id(id: &str) -> Option<&'static dyn ModelArch> {
    registry().iter().copied().find(|a| a.id() == id)
}

/// Resolve the `model_id` an artifact declares: absent (`""`) is
/// [`UNLIMITED_OCR_V1_ID`] forever, whatever the default model is; an unknown
/// non-empty id is `None`.
#[must_use]
pub fn arch_for_declared_id(declared: &str) -> Option<&'static dyn ModelArch> {
    arch_by_id(if declared.is_empty() {
        UNLIMITED_OCR_V1_ID
    } else {
        declared
    })
}

/// The default architecture (`focr ocr`): the Baidu Unlimited-OCR model.
///
/// This answers "which model does a command use when none is named" and
/// nothing else. An artifact's identity comes from what it declares
/// ([`arch_for_declared_id`]) and model-specific behavior from the
/// capability methods, so changing the default changes no loaded model.
#[must_use]
pub fn default_arch() -> &'static dyn ModelArch {
    #[cfg(test)]
    if let Some(arch) = test_default::current() {
        return arch;
    }
    &UNLIMITED_OCR
}

/// Test-only: simulate a different default model on the current thread.
#[cfg(test)]
pub(crate) mod test_default {
    use std::cell::Cell;

    use super::ModelArch;

    thread_local! {
        static OVERRIDE: Cell<Option<&'static dyn ModelArch>> = const { Cell::new(None) };
    }

    pub(crate) fn current() -> Option<&'static dyn ModelArch> {
        OVERRIDE.with(Cell::get)
    }

    /// Make `arch` the default on this thread until the guard drops.
    pub(crate) fn flip(arch: &'static dyn ModelArch) -> Guard {
        OVERRIDE.with(|cell| cell.set(Some(arch)));
        Guard
    }

    pub(crate) struct Guard;

    impl Drop for Guard {
        fn drop(&mut self) {
            OVERRIDE.with(|cell| cell.set(None));
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::native_engine::sampler;
    use crate::{DEFAULT_MODEL_PATH, FOCR_MODEL_LICENSE_NOTICE};

    #[test]
    fn registry_lists_the_default_first_then_the_planned_zoo() {
        let archs = registry();
        // The default (Unlimited-OCR) is first + implemented.
        assert_eq!(archs[0].id(), "unlimited-ocr");
        assert!(archs[0].implemented());
        // The IMPLEMENTED set: Unlimited-OCR (fast plain OCR) + GOT-OCR2
        // (specialized structured OCR) + SmolVLM2 (photo describe/VQA, C1-C9)
        // — all run today via `focr ocr`.
        let mut implemented: Vec<&str> = archs
            .iter()
            .filter(|a| a.implemented())
            .map(|a| a.id())
            .collect();
        implemented.sort_unstable();
        assert_eq!(
            implemented,
            [
                "got-ocr2",
                "onechart",
                "smolvlm2",
                "tromr",
                "unlimited-ocr",
                UNLIMITED_OCR_V2_ID
            ]
        );
        // Every model that runs is Ready (v2 since U2-E4 published its
        // certified artifact), and the remaining descriptors are Planned;
        // `implemented()` is exactly "not Planned" for each.
        for a in archs {
            let want = match a.id() {
                "trocr" | "pix2tex" => Maturity::Planned,
                _ => Maturity::Ready,
            };
            assert_eq!(a.maturity(), want, "{}", a.id());
            assert_eq!(a.implemented(), want != Maturity::Planned, "{}", a.id());
        }
        // Every registered id is unique (a registry invariant the zoo relies on).
        let mut ids: Vec<&str> = archs.iter().map(|a| a.id()).collect();
        ids.sort_unstable();
        ids.dedup();
        assert_eq!(ids.len(), archs.len(), "model ids must be unique");
    }

    #[test]
    fn tromr_descriptor_is_the_censused_shape() {
        // E2 (bd-3jo6.5.2): the descriptor carries the tromr-spec §5/§9/§11/§12
        // census, not placeholders. Convert-critical fields first.
        let a = arch_by_id("tromr").expect("tromr registered");
        assert!(a.implemented(), "E2-E9 shipped (model #5)");
        assert_eq!(a.decoder(), Decoder::Seq2SeqDense);
        assert_eq!(a.tokenizer(), TokenizerKind::MusicVocab);
        // §12: no lm_head.weight exists — four untied per-stream heads; the
        // artifact stores everything high-precision by default (§11).
        assert!(
            !a.tie_word_embeddings(),
            "4 untied heads, no lm_head at all"
        );
        assert!(
            !a.lm_head_stored_int8(),
            "heads are tiny Linear+bias — always HP"
        );
        assert_eq!(a.vision_tower_prefix(), "encoder.");
        assert_eq!(a.decoder_layers_prefix(), "decoder.net.attn_layers.layers.");
        assert_eq!(a.embed_tokens_name(), "decoder.net.rhythm_emb.emb.weight");
        // §9: greedy argmax-forced, rhythm-stream EOS 2, no ngram guard.
        let c = a.decode_contract();
        assert_eq!(c.eos_token_id, 2, "rhythm [EOS]");
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.no_repeat_ngram_size, 0);
        assert_eq!(
            a.license_notice(),
            "Polyphonic-TrOMR (NetEase) - Apache-2.0"
        );
    }

    #[test]
    fn absent_model_id_is_v1_whatever_the_default_is() {
        let got = arch_by_id("got-ocr2").expect("got-ocr2 registered");
        let flip = test_default::flip(got);
        assert_eq!(
            default_arch().id(),
            "got-ocr2",
            "the seam flips the default"
        );
        assert_eq!(
            arch_for_declared_id("").map(ModelArch::id),
            Some(UNLIMITED_OCR_V1_ID)
        );
        assert_eq!(
            arch_for_declared_id("got-ocr2").map(ModelArch::id),
            Some("got-ocr2")
        );
        assert!(arch_for_declared_id("unlimited-ocr-9").is_none());
        drop(flip);
        assert_eq!(default_arch().id(), UNLIMITED_OCR_V1_ID);
    }

    #[test]
    fn capabilities_pin_v1_and_leave_the_zoo_unpinned() {
        let v1 = arch_by_id(UNLIMITED_OCR_V1_ID).expect("v1 registered");
        assert_eq!(v1.unlimited_variant(), Some(UnlimitedVariant::V1Rswa));
        assert_eq!(v1.tensor_census(), Some(TensorCensus::UnlimitedOcrV1));
        assert_eq!(
            v1.tokenizer_sha256(),
            Some("a02f8fd5228c90256bb4f6554c34a579d48f909e5beb232dc4afad870b55a8b4")
        );
        assert_eq!(
            v1.required_quant_recipe("int8"),
            Some("unlimited-ocr-ffn-int8-attn-bf16-lmhead-bf16-v1")
        );
        assert_eq!(v1.required_quant_recipe("int4"), None);
        assert!(v1.required_token_ids().contains(&(128815, "<image>")));
        assert!(
            v1.required_token_ids().iter().all(|&(id, _)| id != 128827),
            "the v1 tokenizer has no <PAGE> token"
        );
        for arch in registry() {
            if arch.unlimited_variant().is_some() {
                continue;
            }
            assert_eq!(
                arch.artifact_version(),
                crate::UNLIMITED_OCR_ARTIFACT_VERSION
            );
            assert_eq!(arch.unlimited_variant(), None, "{}", arch.id());
            assert_eq!(arch.tensor_census(), None, "{}", arch.id());
            assert_eq!(arch.tokenizer_sha256(), None, "{}", arch.id());
            assert!(arch.required_token_ids().is_empty(), "{}", arch.id());
            assert_eq!(arch.tokenizer_source(), None, "{}", arch.id());
        }
        assert_eq!(v1.artifact_version(), crate::UNLIMITED_OCR_ARTIFACT_VERSION);
        assert_eq!(v1.tokenizer_source(), None, "focr pull publishes v1");
    }

    #[test]
    fn unlimited_ocr_2_is_registered_with_its_capabilities_and_ready() {
        let v2 = arch_by_id(UNLIMITED_OCR_V2_ID).expect("unlimited-ocr-2 registered");
        assert_eq!(
            v2.maturity(),
            Maturity::Ready,
            "U2-C4 certified the artifact and U2-E4 published it"
        );
        assert!(v2.implemented(), "the U2-B6 document loop runs it");
        assert_eq!(v2.display_name(), "Baidu Unlimited-OCR-2");
        assert_eq!(v2.vision_encoder(), VisionEncoder::SamClip);
        assert_eq!(v2.decoder(), Decoder::DeepSeekV2MoeSrSwa);
        assert_eq!(v2.tokenizer(), TokenizerKind::DeepSeekBpe);
        assert_eq!(v2.tasks(), &[Task::Ocr]);
        assert!(v2.license_notice().contains("Copyright (c) 2026 Baidu"));
        assert!(v2.license_notice().contains("MIT License"));
        assert_ne!(
            v2.license_notice(),
            FOCR_MODEL_LICENSE_NOTICE,
            "its own notice"
        );
        assert_eq!(v2.unlimited_variant(), Some(UnlimitedVariant::V2SrSwa));
        assert_eq!(v2.tensor_census(), Some(TensorCensus::UnlimitedOcrV2));
        assert_eq!(
            v2.required_quant_recipe("int8"),
            Some("unlimited-ocr-2-ffn-int8-attn-bf16-lmhead-bf16-v1")
        );
        assert_eq!(v2.required_quant_recipe("int4"), None);
        assert_eq!(v2.artifact_version(), "0.1.0");
        assert_ne!(v2.artifact_version(), crate::UNLIMITED_OCR_ARTIFACT_VERSION);
        assert_eq!(
            v2.tokenizer_sha256(),
            Some("c55c165e32c5a67830362a53e1f548c8930dcc8469efa30ff3252a982799c589")
        );
        for required in [
            (0, "<｜begin▁of▁sentence｜>"),
            (1, "<｜end▁of▁sentence｜>"),
            (128815, "<image>"),
            (128827, "<PAGE>"),
        ] {
            assert!(v2.required_token_ids().contains(&required), "{required:?}");
        }
        assert_eq!(
            v2.tokenizer_source(),
            None,
            "focr pull publishes v2 (U2-E4)"
        );
        let c = v2.decode_contract();
        assert_eq!(
            (
                c.temperature,
                c.eos_token_id,
                c.no_repeat_ngram_size,
                c.ngram_window
            ),
            (0.0, 1, 35, 128)
        );
        assert_eq!(v2.default_artifact_basename(), "unlimited-ocr-2.focrq");
        assert_eq!(v2.quant_policy(), QuantPolicy::DOCTRINE);
        assert!(!v2.tie_word_embeddings());
        assert!(!v2.lm_head_stored_int8());
        assert_eq!(v2.vision_tower_prefix(), "model.sam_model");
        assert_eq!(v2.decoder_layers_prefix(), "model.layers.");
        assert_eq!(
            arch_for_declared_id(UNLIMITED_OCR_V2_ID).map(ModelArch::id),
            Some(UNLIMITED_OCR_V2_ID)
        );
    }

    #[test]
    fn lookup_and_default_resolve() {
        assert_eq!(default_arch().id(), "unlimited-ocr");
        assert!(default_arch().implemented());
        assert!(
            !default_arch().lm_head_stored_int8(),
            "Unlimited-OCR keeps its untied lm_head high precision by default"
        );
        assert_eq!(
            arch_by_id("unlimited-ocr").map(ModelArch::id),
            Some("unlimited-ocr")
        );
        // GOT-OCR2 resolves and is now implemented (full pipeline + KV-cache decode ship).
        let got = arch_by_id("got-ocr2").expect("got-ocr2 is a registered arch");
        assert_eq!(got.id(), "got-ocr2");
        assert!(got.implemented());
        assert_eq!(got.decoder(), Decoder::Qwen2Dense);
        assert_eq!(got.tokenizer(), TokenizerKind::Qwen2Bpe);
        // An unknown id resolves to nothing.
        assert!(arch_by_id("does-not-exist").is_none());
    }

    /// The GOT-OCR2 descriptor matches the census (docs/zoo/got-ocr2-spec.md).
    #[test]
    fn got_ocr2_descriptor_matches_the_census() {
        let got = arch_by_id("got-ocr2").expect("got-ocr2 registered");
        assert!(got.implemented());
        assert_eq!(got.vision_encoder(), VisionEncoder::SamVit);
        assert_eq!(got.decoder(), Decoder::Qwen2Dense);
        assert_eq!(got.tokenizer(), TokenizerKind::Qwen2Bpe);
        // Real config from the census: greedy, eos=<|endoftext|>(151643), ngram 20.
        let c = got.decode_contract();
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.eos_token_id, 151_643);
        assert_eq!(c.no_repeat_ngram_size, 20);
        // Same doctrine-#2 quant policy (vision high-precision; decoder GEMMs int8).
        assert!(got.quant_policy().vision_high_precision);
        assert!(got.quant_policy().decoder_gemms_int8);
    }

    /// The SmolVLM2 descriptor matches the census (docs/zoo/smolvlm2-spec.md,
    /// bd-3jo6.3.1) — the C2 convert path keys its whole quant classification
    /// off these facts, so they are pinned here.
    #[test]
    fn smolvlm2_descriptor_matches_the_census() {
        let a = arch_by_id("smolvlm2").expect("smolvlm2 registered");
        assert!(a.implemented(), "sub-epic C shipped C1-C9 (describe/VQA)");
        assert_eq!(a.vision_encoder(), VisionEncoder::Siglip);
        assert_eq!(a.decoder(), Decoder::LlamaDense);
        assert_eq!(a.tokenizer(), TokenizerKind::SmolLm2Bpe);
        assert_eq!(a.tasks(), &[Task::Describe, Task::Vqa]);
        assert!(a.license_notice().contains("Apache-2.0"));
        assert!(a.license_notice().contains("HuggingFaceTB"));
        // Real config (census §8): greedy, eos=<end_of_utterance>(49279), and NO
        // upstream repetition guard (ngram 0 / window 0).
        let c = a.decode_contract();
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.eos_token_id, 49_279);
        assert_eq!(c.no_repeat_ngram_size, 0);
        assert_eq!(c.ngram_window, 0);
        // UNTIED lm_head (byte-verified, spec §12): stored AND high-precision,
        // matching Unlimited-OCR's conservative default; GOT ties and omits it.
        assert!(!a.tie_word_embeddings());
        assert!(!a.lm_head_stored_int8());
        // Idefics3-nested tensor namespaces (spec §12) — the arch-aware convert
        // classification hangs off these prefixes.
        assert_eq!(a.vision_tower_prefix(), "model.vision_model");
        assert_eq!(a.decoder_layers_prefix(), "model.text_model.layers.");
        assert_eq!(
            a.embed_tokens_name(),
            "model.text_model.embed_tokens.weight"
        );
        // Same doctrine-#2 quant policy shape as every arch.
        assert_eq!(a.quant_policy(), QuantPolicy::DOCTRINE);
    }

    /// The historical Qwen-shaped architectures share the original namespace
    /// layout and explicitly retain their certified int8 stored-head policy.
    /// Unlimited-OCR shares the namespace but its conservative high-precision
    /// head is pinned separately in `lookup_and_default_resolve`.
    #[test]
    fn arch_namespace_defaults_are_the_historical_layout() {
        for id in ["got-ocr2", "trocr", "pix2tex"] {
            let a = arch_by_id(id).expect("registered");
            assert_eq!(a.decoder_layers_prefix(), "model.layers.", "{id}");
            assert!(a.lm_head_stored_int8(), "{id}");
            assert_eq!(a.embed_tokens_name(), "model.embed_tokens.weight", "{id}");
        }
    }

    /// The OneChart descriptor matches the census (docs/zoo/onechart-spec.md,
    /// bd-3jo6.4.1) — the D2 convert classification hangs off these facts.
    #[test]
    fn onechart_descriptor_matches_the_census() {
        let a = arch_by_id("onechart").expect("onechart registered");
        assert!(a.implemented(), "sub-epic D shipped D1-D9 (chart-data)");
        assert_eq!(a.vision_encoder(), VisionEncoder::SamVit);
        assert_eq!(a.decoder(), Decoder::OptDense);
        assert_eq!(a.tokenizer(), TokenizerKind::Gpt2Bpe);
        assert_eq!(a.tasks(), &[Task::Chart]);
        assert!(a.license_notice().contains("Apache-2.0"));
        // §10: greedy, eos 2 (`</s>`), no upstream repetition guard.
        let c = a.decode_contract();
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.eos_token_id, 2);
        assert_eq!(c.no_repeat_ngram_size, 0);
        // §4: TIED head (both source tensors byte-identical, SHA-proven) —
        // the `.focrq` keeps ONE high-precision copy.
        assert!(a.tie_word_embeddings());
        assert!(!a.lm_head_stored_int8());
        // §13: OPT namespaces — the vision tower is `model.vision_tower.`
        // (NOT GOT's `vision_tower_high`), the LM nests under `model.decoder.`.
        assert_eq!(a.vision_tower_prefix(), "model.vision_tower");
        assert_eq!(a.decoder_layers_prefix(), "model.decoder.layers.");
        assert_eq!(a.embed_tokens_name(), "model.decoder.embed_tokens.weight");
    }

    /// The descriptor must match the LIVE engine constants, so it can never drift.
    #[test]
    fn unlimited_ocr_descriptor_matches_the_live_engine() {
        let a = UnlimitedOcr;
        // License notice is the single source of truth in lib.rs.
        assert_eq!(a.license_notice(), FOCR_MODEL_LICENSE_NOTICE);
        // The default artifact basename matches the resolved DEFAULT_MODEL_PATH.
        let want_basename = std::path::Path::new(DEFAULT_MODEL_PATH)
            .file_name()
            .and_then(|s| s.to_str())
            .unwrap();
        assert_eq!(a.default_artifact_basename(), want_basename);
        // Graph shape + tasks.
        assert_eq!(a.vision_encoder(), VisionEncoder::SamClip);
        assert_eq!(a.decoder(), Decoder::DeepSeekV2MoeRswa);
        assert_eq!(a.tokenizer(), TokenizerKind::DeepSeekBpe);
        assert_eq!(a.tasks(), &[Task::Ocr]);
        // Quant policy is the fixed doctrine policy.
        assert_eq!(a.quant_policy(), QuantPolicy::DOCTRINE);
        assert!(a.quant_policy().vision_high_precision);
        assert!(a.quant_policy().decoder_gemms_int8);
    }

    /// The descriptor's decode contract must equal the live frozen
    /// `DecodeParams::default()` — the contract the AR loop actually runs.
    #[test]
    fn unlimited_ocr_decode_contract_matches_sampler_default() {
        let c = UnlimitedOcr.decode_contract();
        let d = sampler::DecodeParams::default();
        assert_eq!(c.temperature, d.temperature);
        assert_eq!(c.eos_token_id, d.eos_token_id);
        assert_eq!(c.no_repeat_ngram_size, d.no_repeat_ngram_size);
        assert_eq!(c.ngram_window, d.ngram_window);
        // And the documented frozen values.
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.eos_token_id, 1);
        assert_eq!(c.no_repeat_ngram_size, 35);
        assert_eq!(c.ngram_window, 128);
    }
}