franken_ocr 0.10.0

//! The `focr` clap-derive CLI surface (plan §7.2).
//!
//! The diagnostics (`robot schema/health/backends`) work today; `ocr` routes
//! through the native model resolver/engine; `convert` writes real `.focrq`
//! artifacts (`--quant int8` conservative recipe, `--quant int4` the wasm
//! experts-int4 recipe); `doctor` is the live detect-only doctor. Anything
//! still unimplemented returns a clear `NotImplemented` error pointing at the
//! plan phase that lands it. PDF input is handled natively:
//! `focr ocr file.pdf` rasterizes each page (the pure-Rust [`crate::pdf`] scanned-
//! image fast path) and feeds it through the same pipeline an image takes.
//!
//! This module lives in the **library** so the single CLI entrypoint
//! ([`cli_main`]) is shared by both binaries (`focr` and `franken_ocr`) without
//! either `src/main.rs` appearing in two build targets — each `[[bin]]` now
//! points at its own thin shim that just calls [`cli_main`]. See AGENTS.md
//! doctrine #9.

use crate::batch_events::{BatchEvents, BatchMode, BatchRun};
use crate::native_engine::Half;
use crate::page_source::{PageEvent, PageItem, PageSource, PageStep};
use crate::{
    FOCR_MODEL_LICENSE_NOTICE, FOCR_PROJECT_LICENSE_NOTICE, FocrError, FocrResult, OcrEngine, dist,
    native_engine, pdf, progress, quant, robot, simd,
};
use clap::{Args, Parser, Subcommand, ValueEnum};
use std::ffi::OsString;
use std::io::{IsTerminal as _, Read as _};
use std::path::{Path, PathBuf};
use std::process::ExitCode;
use std::sync::Arc;

// Debug/test-only producer seam for process-level exit-code conformance while
// the Phase-1 forward is not able to naturally emit every terminal error kind.
#[cfg(debug_assertions)]
const FORCE_TEST_ERROR_ENV: &str = "FOCR_TEST_FORCE_ERROR";

/// The shared process entrypoint for both binaries (`focr` and `franken_ocr`).
///
/// `fn main()` in each shim is **synchronous by design** (plan §3.3, §7.1): the
/// asupersync runtime is owned BELOW here, inside `OcrEngine`, never spanning
/// the whole process. This parses, dispatches, and maps errors to the stable
/// exit codes documented in [`crate::error`].
pub fn cli_main() -> ExitCode {
    if is_exact_long_version_request(std::env::args_os()) {
        let report = long_version_report();
        let mut lines = report.lines();
        if let Some(version_line) = lines.next() {
            println!("{version_line}");
        }
        for license_line in lines {
            eprintln!("{license_line}");
        }
        return ExitCode::SUCCESS;
    }

    // Cooperative Ctrl+C (bd-223.2): the first signal requests shutdown —
    // every decode-step/page checkpoint aborts with Cancelled (exit 6) at its
    // next boundary, and an Unlimited-OCR-2 document writes the pages it
    // completed before it exits 6 (U2-E2); a second signal hard-exits 130
    // (the shell convention) for a wedged stage. Installation failure (e.g.
    // no signal handling in odd sandboxes) is non-fatal: the engine still
    // works, just without graceful interrupt.
    let _ = ctrlc::set_handler(|| {
        if crate::shutdown_requested() {
            std::process::exit(130);
        }
        crate::request_shutdown();
        progress::suppress_for_interrupt();
        let _ = std::thread::Builder::new()
            .name("focr-interrupt-notice".into())
            .spawn(|| {
                progress::stderr_message(format_args!(
                    "focr: interrupt received — finishing the current step then aborting \
                     (Ctrl+C again to force)"
                ));
            });
    });

    let cli = Cli::parse();
    let error_mode = ErrorMode::from_cli(&cli);
    match run(cli) {
        Ok(()) => ExitCode::SUCCESS,
        Err(err) => exit_code_from_error(&err, error_mode),
    }
}

#[derive(Parser)]
#[command(
    name = "focr",
    version,
    about = "Pure-Rust, CPU-hyper-optimized runner for the Baidu Unlimited-OCR model",
    after_help = "Agent orientation: `focr robot triage` (one JSON object: quick reference, live \
                  health, next commands, exit codes)\nMachine contract: `focr robot schema` | \
                  Kernel proof on this CPU: `focr robot selftest`\nModel zoo + pull status: \
                  `focr models --json` | Self-check/repair: `focr doctor`"
)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Command,
}

fn is_exact_long_version_request<I>(mut args: I) -> bool
where
    I: Iterator<Item = OsString>,
{
    let _program = args.next();
    matches!(
        (args.next().as_deref(), args.next()),
        (Some(arg), None) if arg == "--version"
    )
}

/// Long, attribution-bearing version report. The short `-V` surface remains
/// Clap's script-friendly `focr <semver>` output. The model-license notice is
/// read from the default model's [`crate::model_arch::ModelArch`] descriptor (the
/// source of truth as the model zoo grows); today that is byte-identical to
/// [`FOCR_MODEL_LICENSE_NOTICE`].
///
/// Emission contract (GH #13): only the first line (`focr <semver>`) goes to
/// stdout so `focr --version | <parse>` stays machine-safe; the license lines
/// go to stderr, which keeps the attribution visible on a terminal without
/// polluting pipelines.
#[must_use]
pub fn long_version_report() -> String {
    format!(
        "focr {}\nsource_license: {}\nmodel_license: {}\n",
        env!("CARGO_PKG_VERSION"),
        FOCR_PROJECT_LICENSE_NOTICE,
        crate::model_arch::default_arch().license_notice()
    )
}

#[derive(Subcommand)]
pub enum Command {
    /// Parse a document image into structured markdown (or `--json`).
    ///
    /// `-o FILE` writes the result to a file instead of stdout: a `.json` path
    /// emits structured JSON (markdown + per-span bounding boxes), any other
    /// extension (e.g. `.md`) emits markdown; `--json` forces JSON.
    /// `--extract-figures` additionally saves figure/image regions the model does
    /// not transcribe into a subfolder, referenced from the markdown/JSON.
    Ocr(OcrArgs),
    /// OCR many images in ONE process — load the 6.2 GB weights + build the int8
    /// decoder cache ONCE, then stream a result per image (the throughput path).
    OcrBatch(OcrBatchArgs),
    /// Offline weight transformation: safetensors → `.focrq` (plan §5).
    Convert(ConvertArgs),
    /// Download the model weights (int8 `.focrq` + tokenizer) into the cache.
    Pull(PullArgs),
    /// List the models this build can run (the "model zoo"): id, tasks, status.
    Models(ModelsArgs),
    /// Agent-facing diagnostics and the machine contract.
    Robot {
        #[command(subcommand)]
        cmd: RobotCmd,
    },
    /// Query durable run history (fsqlite-backed store lands with plan §7.2).
    Runs(RunsArgs),
    /// Export/import the append-only run audit stream.
    Sync(SyncArgs),
    /// Idempotent self-check / repair.
    Doctor(DoctorArgs),
    /// INTERNAL: the resident warm-model daemon (spawned automatically by
    /// `focr ocr`; not for direct use). Holds the loaded model in memory and
    /// exits after the idle period (default 10 minutes).
    #[command(hide = true)]
    ResidentDaemon(ResidentDaemonArgs),
}

#[derive(Clone, Debug, Args)]
pub struct ResidentDaemonArgs {
    /// The resolved model artifact path this daemon serves (its identity key).
    #[arg(long)]
    pub model_root: PathBuf,
}

#[derive(Clone, Debug, Args)]
pub struct OcrArgs {
    #[command(flatten)]
    pub request: OcrRequestArgs,
    /// Emit machine-readable JSON instead of human markdown.
    #[arg(long)]
    pub json: bool,
    /// Write the result to FILE instead of stdout. The format follows the
    /// extension: `.json` emits structured JSON (markdown + bounding boxes),
    /// any other extension (e.g. `.md`) emits markdown. `--json` forces JSON.
    #[arg(short = 'o', long)]
    pub output: Option<PathBuf>,
    /// Save figure/image regions the model sees but does not transcribe to a
    /// subfolder (default `<output-stem>_figures/`), referenced from the
    /// markdown/JSON. Each figure is a PNG (line-art) or JPG (photo) chosen by
    /// content. Requires `-o` (or `--figures-dir` for a stdout run).
    #[arg(long)]
    pub extract_figures: bool,
    /// Directory to save extracted figures into (implies `--extract-figures`).
    /// Relative paths are taken relative to the output file's directory (or the
    /// current directory for a stdout run) and used verbatim in references.
    #[arg(long, value_name = "DIR")]
    pub figures_dir: Option<PathBuf>,
    /// Stream NDJSON robot events as pages complete.
    #[arg(long)]
    pub robot: bool,
    /// Check the run without running it: the arguments, the input's header or
    /// page list, the `--pages` spec, the model's header and tokenizer, and
    /// the output's directory, in about a second. Reads no weights and decodes
    /// no pixels, exits with the code the run would fail with, and records
    /// nothing in `focr runs`. A truncated image or a page that will not
    /// rasterize passes here and fails in the run.
    #[arg(long)]
    pub check: bool,
    /// Output the decode as the model wrote it, grounding markers included
    /// (`<|det|>…<|/det|>` spans, or Unlimited-OCR-2's `<BLOCK>…<FORK>`
    /// prefixes), in place of the markdown. With `--json` it adds a
    /// `raw` field beside the markdown and to each page, and with `--robot`
    /// to `run_complete`. Its boxes stay on the model's 0–999 grid, per page
    /// or tall-image strip.
    #[arg(long)]
    pub raw: bool,
}

#[derive(Clone, Debug, Args)]
pub struct OcrBatchArgs {
    /// Input document image paths. The model + int8 decoder cache are built once
    /// and reused across all of them (load-once batch throughput).
    #[arg(required_unless_present = "inputs_from")]
    pub images: Vec<PathBuf>,
    /// Read more image paths from FILE, one per line, after any named above
    /// (`-` reads stdin). Lines are taken as written apart from the line
    /// terminator; blank lines are skipped, and a relative path resolves
    /// against the current directory, not the list's.
    #[arg(long, value_name = "FILE")]
    pub inputs_from: Option<PathBuf>,
    /// Write each image's markdown to DIR/<stem>.md as it ends, in place of
    /// printing it, so a long batch keeps what it finished if it is stopped.
    /// Two inputs with the same stem are refused before any work.
    #[arg(long, value_name = "DIR")]
    pub output_dir: Option<PathBuf>,
    /// Stop at the first image that fails and exit with its code. By default
    /// the batch goes on, and fails only when no image was read.
    #[arg(long)]
    pub fail_fast: bool,
    /// Model artifact path or model id. Default (unset) = the FAST plain-text
    /// OCR model (unlimited-ocr). Pass a `got-ocr2.int8.focrq` for SPECIALIZED
    /// structured output — math (LaTeX), tables, charts, molecular, geometry,
    /// sheet music (heavier per page). `focr pull got-ocr2` first. With
    /// `--multi-page`, `unlimited-ocr-2` (`focr pull unlimited-ocr-2`) reads
    /// long documents; see `focr models`.
    #[arg(long)]
    pub model: Option<PathBuf>,
    /// Emit one machine-readable JSON object when the run ends: every image's
    /// result, then the run's timing.
    #[arg(long)]
    pub json: bool,
    /// Use the experimental all-int8 decoder. This also requires
    /// `FOCR_INT8_ATTN=1` and `FOCR_INT8_LMHEAD=1`; the default follows the
    /// conservative recipe and keeps attention plus `lm_head` high precision.
    #[arg(long)]
    pub experimental_full_int8: bool,
    /// Treat the images as ONE multi-page document (the Unlimited-OCR
    /// `infer_multi` contract): a cross-page parse where page N can reference
    /// the pages before it, emitting one markdown with `<PAGE>` separators.
    /// Without this flag each image is parsed independently. Unlimited-OCR
    /// only; v1 reads the document in one pass over 32,768 positions shared
    /// by prompt and output (≈29 dense pages); longer documents stop early
    /// and report `finish_reason: length` with a `v1_truncated` warning.
    /// unlimited-ocr-2 reads it in windows of 10 pages, where a page sees the
    /// pages before it in its window, so any length fits; a document that
    /// stops early prints its pages, then exits 5.
    #[arg(long)]
    pub multi_page: bool,
    /// Write one JSON object per line to PATH (`-` for stderr) as the run
    /// goes: the resolved threads, model and backend, then each image or page
    /// as it ends with the measured pages per hour and an estimate of the time
    /// left, then how the run ended. stdout does not change. `focr robot
    /// schema` lists the events under `batch_progress`.
    #[arg(long, value_name = "PATH")]
    pub progress_events: Option<PathBuf>,
    /// The kernel thread budget for this run; outranks FOCR_THREADS. Default:
    /// physical cores, on an Apple-silicon Mac its fastest core tier only.
    #[arg(long, value_name = "N")]
    pub threads: Option<std::num::NonZeroUsize>,
    /// Print nested stage timings to stderr, as FOCR_TIMING=1 does.
    #[arg(long)]
    pub timing: bool,
}

#[derive(Clone, Debug, Args)]
pub struct ModelsArgs {
    /// Emit a machine-readable JSON list instead of a human table.
    #[arg(long)]
    pub json: bool,
}

#[derive(Clone, Debug, Args)]
pub struct PullArgs {
    /// Model id to fetch (e.g. `got-ocr2`). Defaults to the default model
    /// (`unlimited-ocr`).
    pub model: Option<String>,
    /// Quant tag to fetch (defaults to `int8`; available tags vary by model).
    #[arg(long, default_value = dist::DEFAULT_QUANT)]
    pub quant: String,
    /// Manifest source — a local path or an HTTPS URL. Defaults to
    /// `$FOCR_MANIFEST_URL`, else the release-bound embedded manifest.
    #[arg(long)]
    pub manifest: Option<String>,
    /// Emit a single JSON result object on stdout, and each pull step (part
    /// SHA-256s, the install transaction) as an NDJSON line on stderr, instead
    /// of human progress lines.
    #[arg(long)]
    pub json: bool,
}

#[derive(Clone, Debug, Args)]
pub struct RobotRunArgs {
    #[command(flatten)]
    pub request: OcrRequestArgs,
}

#[derive(Clone, Debug, Args)]
pub struct OcrRequestArgs {
    /// Input document path — an image (PNG/JPG/…), a PDF (each page is
    /// rasterized natively and OCR'd as one document), or a directory of page
    /// images (read in natural order, `p2` before `p10`, as one document;
    /// other files are left out with an `ignored_files` warning). `-` reads an
    /// image or a PDF from stdin (a file named `-` is `./-`).
    pub image: PathBuf,
    /// The model to run: a model id (`unlimited-ocr`, `unlimited-ocr-2`, …)
    /// found in the model directories, or an artifact path. Default: the
    /// mode's default, unlimited-ocr for every mode today. unlimited-ocr-2 is
    /// Baidu's long-document successor (`focr pull unlimited-ocr-2`): use it
    /// for documents and long documents (a PDF or directory, with
    /// `--multi-page`). Single pages work with either. unlimited-ocr stays the
    /// default until unlimited-ocr-2 passes its default gates; see `focr
    /// models`.
    #[arg(long)]
    pub model: Option<PathBuf>,
    /// Global-view edge length. Default: the model's (1024, the reference
    /// `infer(..., base_size=1024)`). Like every tuning flag below, an explicit
    /// value always reaches the model, even one equal to a default.
    #[arg(long)]
    pub base_size: Option<i64>,
    /// Local tile edge length for `--crop-mode gundam`. Default: the model's
    /// (640, the reference `infer(..., image_size=640)`).
    #[arg(long)]
    pub image_size: Option<i64>,
    /// Vision preprocessing mode (unlimited-ocr and unlimited-ocr-2 — got-ocr2
    /// always uses its own fixed squash-1024 preprocess). `base` (the default)
    /// is the certified single 1024-pixel global view — the mode every oracle
    /// cert and golden was produced under, and what the engine has always
    /// actually run. `gundam` selects the reference dynamic-resolution tiling
    /// (a 1024 global view plus 640 local tiles); its connector path is
    /// unit-tested but has no e2e oracle certification yet. An unlimited-ocr-2
    /// page read in gundam mode carries an `uncertified_crop_mode` warning, and
    /// an unlimited-ocr-2 `--multi-page` document refuses gundam (it reads
    /// every page as a base view). (Until bd-1e9n this flag was parsed and
    /// silently dropped with a `gundam` default label the engine never honored;
    /// the default now states the real, certified behavior.)
    #[arg(long, value_enum)]
    pub crop_mode: Option<CropMode>,
    /// Maximum generated sequence length. Default: the model's (32768 for
    /// unlimited-ocr).
    #[arg(long)]
    pub max_length: Option<i64>,
    /// Decode temperature. Only 0 (greedy, the default) is accepted: every
    /// model here decodes greedily, and a run asking for sampling is refused
    /// before a model loads.
    #[arg(long)]
    pub temperature: Option<f32>,
    /// No-repeat n-gram size (env override: FOCR_NO_REPEAT_NGRAM; 0 disables).
    /// Default: the model's. For unlimited-ocr this is the sliding-window guard
    /// (35, with --ngram-window); for got-ocr2 it overrides the model's global
    /// guard (default 20).
    #[arg(long, env = "FOCR_NO_REPEAT_NGRAM")]
    pub no_repeat_ngram: Option<i64>,
    /// Sliding no-repeat n-gram lookback window. Default: the model's (128 for
    /// unlimited-ocr). (got-ocr2's guard is global.)
    #[arg(long)]
    pub ngram_window: Option<i64>,
    /// Generated-token cap per page for unlimited-ocr-2. Default: the model's
    /// (20,000). 0 lifts this cap only: `--max-length` and the position limit
    /// still apply. Models without pages ignore it.
    #[arg(long)]
    pub max_page_tokens: Option<i64>,
    /// GOT-OCR2 structured output: use the model's `OCR with format:` mode instead
    /// of plain text, emitting Mathpix-Markdown (.mmd) — inline LaTeX math, Markdown
    /// tables, TikZ geometry, SMILES molecules, and `**kern` sheet music (the model
    /// auto-selects the formalism from the image). Only affects the `got-ocr2` model
    /// (`--model got-ocr2…`); a no-op for the default unlimited-ocr model.
    #[arg(long)]
    pub format: bool,
    /// Task selector — convenience routing over the model zoo (`focr models`).
    /// `ocr` (the default) is today's behavior, unchanged. The specialized tasks
    /// are served by got-ocr2's `OCR with format:` mode, so they imply `--format`
    /// (an explicit `--format` composes idempotently) and need a got-ocr2 model:
    /// `focr pull got-ocr2`, then `--model got-ocr2.int8.focrq`. `describe`
    /// (photo description / VQA) is served by smolvlm2: `--model
    /// smolvlm2.int8.focrq --task describe [--question "…"]`.
    #[arg(long, value_enum, default_value_t = OcrTask::Ocr)]
    pub task: OcrTask,
    /// The natural-language question for `--task describe` (smolvlm2 VQA) —
    /// SmolVLM2 has no instruction modes; the task IS the question. Defaults
    /// to the model-card caption prompt ("Can you describe this image?").
    /// Requires `--task describe`.
    #[arg(long)]
    pub question: Option<String>,
    /// GOT-OCR2 fine-grained OCR: read only the text inside this box, in pixels
    /// of the input image, as `x1,y1,x2,y2` (top left, bottom right), or at a
    /// point `x,y`. The model sees it on its 0-1000 grid, as upstream
    /// `chat(ocr_box=…)` builds it. Needs a got-ocr2 model and composes with
    /// `--format`, but not with `--task chart` or `--task formula`, which pad
    /// the image first.
    #[arg(long = "box", value_name = "X1,Y1,X2,Y2")]
    pub region_box: Option<String>,
    /// GOT-OCR2 fine-grained OCR: read only the text inside a frame of this
    /// colour drawn on the image, as upstream `chat(ocr_color=…)` does. Needs a
    /// got-ocr2 model and composes with `--format`.
    #[arg(long, value_enum, value_name = "COLOR", conflicts_with = "region_box")]
    pub color: Option<RegionColor>,
    /// Page selection: a comma list of 1-based pages and inclusive ranges
    /// ("3", "3-7", "1,5-9,218"). PDF and directory inputs only — on an image
    /// input this is a usage error. Out-of-range pages error naming the
    /// document's page count; pages run in source order, deduplicated.
    #[arg(long)]
    pub pages: Option<String>,
    /// Split two-page book spreads (PDF and directory inputs only): when a
    /// page is much wider than tall AND a near-blank vertical gutter sits
    /// near the center, OCR the left and right halves as separate logical
    /// pages (labelled `"half": "left"|"right"` in JSON / robot page events).
    /// Off by default; a page with no detectable gutter passes through
    /// unsplit.
    #[arg(long)]
    pub split_spreads: bool,
    /// A cross-page parse of the whole document (PDF and directory inputs
    /// only; the Unlimited-OCR `infer_multi` contract): page N can reference
    /// the pages before it, output is one markdown with `<PAGE>` separators.
    /// Pages are read as the parse needs them, so a long document never
    /// holds every raster. Composes with `--pages`. v1 reads the document in
    /// one pass over 32,768 positions shared by prompt and output (≈29 dense
    /// pages); longer documents stop early and report `finish_reason: length`
    /// with a `v1_truncated` warning. unlimited-ocr-2 reads it in windows of
    /// 10 pages, where a page sees the pages before it in its window, so any
    /// length fits; a document that stops early writes its pages, then exits
    /// 5. Without this flag each page is parsed independently.
    #[arg(long)]
    pub multi_page: bool,
    /// How unlimited-ocr-2 splits a `--multi-page` document into decode
    /// windows: N pages each (at most 102; the default is 10), `auto` for the
    /// largest window whose estimated memory fits FOCR_MEMORY_BUDGET, or
    /// `off` for one pass over every page, which keeps no checkpoint and can
    /// stop at the position limit with its pages written and exit 5.
    #[arg(long, value_name = "N|auto|off")]
    pub page_window: Option<native_engine::PageWindow>,
    /// Continue an interrupted unlimited-ocr-2 `--multi-page` document from
    /// its last completed window: the result is byte-identical to an
    /// uninterrupted run. Re-running the same command does the same.
    /// `--resume=recompute` keeps the completed pages and recomputes the next
    /// window when the run cannot continue exactly (its settings changed, or
    /// its checkpoint is damaged); later pages can differ, and a
    /// `resume_recompute` warning says so.
    #[arg(
        long,
        value_enum,
        value_name = "MODE",
        num_args = 0..=1,
        require_equals = true,
        default_missing_value = "matching"
    )]
    pub resume: Option<ResumeMode>,
    /// Keep a windowed document's checkpoint when it finishes. Its journal
    /// is removed either way.
    #[arg(long)]
    pub keep_checkpoint: bool,
    /// Disable the resident warm-model daemon for this run (env analog:
    /// FOCR_NO_RESIDENT=1). By default, eligible single-image runs are served
    /// by a per-model background process that keeps the loaded weights in RAM
    /// and exits after 10 idle minutes (FOCR_RESIDENT_IDLE_SECS), so
    /// back-to-back invocations skip the multi-gigabyte artifact load.
    #[arg(long)]
    pub no_resident: bool,
    /// The kernel thread budget for this run; outranks FOCR_THREADS. Default:
    /// physical cores, on an Apple-silicon Mac its fastest core tier only. The
    /// run loads its own model: a resident daemon keeps the budget it started
    /// with.
    #[arg(long, value_name = "N")]
    pub threads: Option<std::num::NonZeroUsize>,
    /// Print nested stage timings to stderr, as FOCR_TIMING=1 does. The run
    /// loads its own model and shows no progress bar.
    #[arg(long)]
    pub timing: bool,
    /// Fail (exit 8, `low_yield`) when a large input produces almost no
    /// recognized text, instead of the default warning. A page-sized capture
    /// yielding a handful of characters is the silent-failure signature of
    /// tall or low-DPI screenshots (GH #15); robot consumers can instead
    /// watch for `low_yield: true` on `run_complete`.
    #[arg(long)]
    pub fail_on_low_yield: bool,
}

#[derive(Clone, Debug)]
pub struct OcrRequest {
    pub image: PathBuf,
    pub model: Option<PathBuf>,
    /// The tuning flags, each `None` unless given (the model's default).
    pub base_size: Option<u32>,
    pub image_size: Option<u32>,
    pub crop_mode: Option<CropMode>,
    pub max_length: Option<u32>,
    pub temperature: Option<f32>,
    pub no_repeat_ngram: Option<u32>,
    pub ngram_window: Option<u32>,
    pub max_page_tokens: Option<u32>,
    pub format: bool,
    /// Pad the image to a square before GOT sees it (per [`OcrTask::pads_got_image`]).
    pub square_pad: bool,
    /// The region GOT reads, from `--box` or `--color`.
    pub region: Option<native_engine::got::Region>,
    pub question: Option<String>,
    pub pages: Option<String>,
    pub split_spreads: bool,
    pub multi_page: bool,
    pub page_window: Option<native_engine::PageWindow>,
    pub resume: Option<ResumeMode>,
    pub keep_checkpoint: bool,
    pub no_resident: bool,
}

impl OcrArgs {
    fn to_request(&self) -> FocrResult<OcrRequest> {
        self.request.to_request()
    }
}

impl RobotRunArgs {
    fn into_ocr_args(self) -> OcrArgs {
        OcrArgs {
            request: self.request,
            json: false,
            output: None,
            extract_figures: false,
            figures_dir: None,
            robot: true,
            check: false,
            raw: false,
        }
    }
}

/// Map the request's preprocess tuning flags onto engine
/// [`native_engine::PreprocessOverrides`] (bd-1e9n): every flag given becomes
/// an override, as in [`decode_overrides_from`].
fn preprocess_overrides_from(request: &OcrRequest) -> native_engine::PreprocessOverrides {
    native_engine::PreprocessOverrides {
        base_size: request.base_size.map(|v| v as usize),
        image_size: request.image_size.map(|v| v as usize),
        gundam: request.crop_mode.map(|mode| mode == CropMode::Gundam),
    }
}

/// Map the request's decode tuning flags onto engine
/// [`native_engine::DecodeOverrides`]. Every flag given becomes an override,
/// even one equal to a default, because another model's defaults differ
/// (U2-E1); an untouched flag keeps the model's default and leaves env
/// overrides (e.g. `FOCR_MAX_NEW_TOKENS`) in force.
fn decode_overrides_from(request: &OcrRequest) -> native_engine::DecodeOverrides {
    native_engine::DecodeOverrides {
        max_length: request.max_length.map(|v| v as usize),
        temperature: request.temperature,
        no_repeat_ngram: request.no_repeat_ngram.map(|v| v as usize),
        ngram_window: request.ngram_window.map(|v| v as usize),
        max_page_tokens: request.max_page_tokens.map(|v| v as usize),
    }
}

impl OcrRequestArgs {
    fn to_request(&self) -> FocrResult<OcrRequest> {
        validate_task_selection(self.task, self.effective_model_spec().as_deref())?;
        if self.question.is_some() && self.task != OcrTask::Describe {
            return Err(FocrError::Usage(
                "--question is the smolvlm2 VQA prompt and requires --task describe".into(),
            ));
        }
        let region = self.region()?;
        if let Some(region) = region {
            validate_region(region, self.task, self.effective_model_spec().as_deref())?;
        }
        Ok(OcrRequest {
            image: self.image.clone(),
            model: self.model.clone(),
            base_size: self
                .base_size
                .map(|v| positive_u32("base-size", v))
                .transpose()?,
            image_size: self
                .image_size
                .map(|v| positive_u32("image-size", v))
                .transpose()?,
            crop_mode: self.crop_mode,
            max_length: self
                .max_length
                .map(|v| positive_u32("max-length", v))
                .transpose()?,
            temperature: self.temperature.map(greedy_temperature).transpose()?,
            no_repeat_ngram: self
                .no_repeat_ngram
                .map(|v| non_negative_u32("no-repeat-ngram", v))
                .transpose()?,
            ngram_window: self
                .ngram_window
                .map(|v| non_negative_u32("ngram-window", v))
                .transpose()?,
            max_page_tokens: self
                .max_page_tokens
                .map(|v| non_negative_u32("max-page-tokens", v))
                .transpose()?,
            // `--format` and a format-implying `--task` compose OR-wise: an
            // explicit `--format` wins / is idempotent alongside `--task`.
            format: self.format || self.task.implies_got_format(),
            square_pad: self.task.pads_got_image(),
            region,
            question: self.question.clone(),
            pages: self.pages.clone(),
            split_spreads: self.split_spreads,
            multi_page: self.multi_page,
            page_window: self.page_window,
            resume: self.resume,
            keep_checkpoint: self.keep_checkpoint,
            no_resident: self.no_resident,
        })
    }

    /// The model spec this run would use, for CLI-level `--task` guidance ONLY:
    /// the explicit `--model`, else the `FOCR_MODEL_PATH` env override, else
    /// `None` — the engine's default resolution, which is always an
    /// unlimited-ocr artifact (bd-3u6x).
    fn effective_model_spec(&self) -> Option<PathBuf> {
        self.model
            .clone()
            .or_else(|| std::env::var_os(crate::MODEL_PATH_ENV).map(PathBuf::from))
    }

    /// The region `--box` or `--color` names (clap refuses both at once).
    fn region(&self) -> FocrResult<Option<native_engine::got::Region>> {
        if let Some(color) = self.color {
            return Ok(Some(native_engine::got::Region::Color(color.frame())));
        }
        self.region_box.as_deref().map(parse_region_box).transpose()
    }
}

/// `--box`: `x1,y1,x2,y2` or a point `x,y`, in pixels, brackets optional.
fn parse_region_box(text: &str) -> FocrResult<native_engine::got::Region> {
    use native_engine::got::Region;
    let usage = |why: String| {
        FocrError::Usage(format!(
            "--box {text:?}: {why}. It takes x1,y1,x2,y2 (top left, bottom right) or a point \
             x,y, in pixels of the input image"
        ))
    };
    let values = text
        .trim()
        .trim_start_matches('[')
        .trim_end_matches(']')
        .split(',')
        .map(|v| {
            v.trim()
                .parse::<f64>()
                .ok()
                .filter(|v| v.is_finite() && *v >= 0.0)
        })
        .collect::<Option<Vec<f64>>>()
        .ok_or_else(|| usage("every value must be a non-negative number".into()))?;
    match values[..] {
        [x, y] => Ok(Region::Point([x, y])),
        [x1, y1, x2, y2] if x1 < x2 && y1 < y2 => Ok(Region::Box([x1, y1, x2, y2])),
        [_, _, _, _] => Err(usage(
            "the second corner must be below and to the right of the first".into(),
        )),
        _ => Err(usage(format!("{} values, not 4 or 2", values.len()))),
    }
}

/// `--box` and `--color` are got-ocr2's: refuse them where another model would
/// run, and refuse a box where GOT would see a padded image, not the image the
/// box was measured on. A colour frame survives the pad.
fn validate_region(
    region: native_engine::got::Region,
    task: OcrTask,
    model_spec: Option<&Path>,
) -> FocrResult<()> {
    if task.pads_got_image() && !matches!(region, native_engine::got::Region::Color(_)) {
        return Err(FocrError::Usage(format!(
            "--box names pixels of the image as given, and --task {task} pads it to a square \
             first. Use --format for a region's structured output"
        )));
    }
    if let Some(models) = task_models(task).filter(|models| !models.contains(&"got-ocr2")) {
        return Err(FocrError::Usage(format!(
            "--box and --color are got-ocr2's fine-grained OCR, and --task {task} runs {}",
            models.join(" or ")
        )));
    }
    if model_spec_is_knowably_not_got(model_spec) {
        return Err(FocrError::Usage(
            "--box and --color are got-ocr2's fine-grained OCR, but this run would use the \
             plain-text unlimited-ocr model. Run `focr pull got-ocr2`, then re-run with \
             `--model got-ocr2.int8.focrq` (see `focr models`)"
                .into(),
        ));
    }
    Ok(())
}

/// Refuse `--box` or `--color` for a model that is not got-ocr2, judged by its
/// header, as [`validate_task_for_header`] does for a task.
fn validate_region_for_header(request: &OcrRequest) -> FocrResult<()> {
    if request.region.is_none() {
        return Ok(());
    }
    let spec = request.model.clone().unwrap_or_else(OcrEngine::model_path);
    match native_engine::model_id_at(&spec) {
        Some(id) if id != "got-ocr2" => Err(FocrError::Usage(format!(
            "--box and --color are got-ocr2's fine-grained OCR, but {} holds {id}. Re-run \
             with `--model got-ocr2.int8.focrq` (see `focr models`)",
            spec.display()
        ))),
        _ => Ok(()),
    }
}

/// CLI-level `--task` feasibility check (best-effort: no model file is opened
/// here — the engine's `.focrq` arch tag stays the real dispatcher).
///
/// * `describe` (smolvlm2, C9) whose model spec is KNOWABLY not smolvlm2 gets
///   the pull/model guidance now, before any weights load.
/// * a got-only task whose model spec is KNOWABLY not got-ocr2 (see
///   [`model_spec_is_knowably_not_got`]) gets the pull/model guidance now.
/// * an ambiguous explicit spec passes through: mislabeling would reject real
///   artifacts, and the engine's arch tag makes the final call.
fn validate_task_selection(task: OcrTask, model_spec: Option<&Path>) -> FocrResult<()> {
    if task == OcrTask::ChartData && model_spec_is_knowably_not_onechart(model_spec) {
        return Err(FocrError::Usage(
            "--task chart-data (chart→dict + number-head self-verify) needs the onechart \
             model, but this run would use a different model. Re-run with \
             `--model onechart.int8.focrq` (see `focr models`)"
                .into(),
        ));
    }
    if task == OcrTask::Describe && model_spec_is_knowably_not_smolvlm2(model_spec) {
        return Err(FocrError::Usage(
            "--task describe (photo description/VQA) needs the smolvlm2 model, but this \
             run would use a different model. Re-run with `--model smolvlm2.int8.focrq` \
             (see `focr models`)"
                .into(),
        ));
    }
    if task == OcrTask::Music {
        // Music is served by TWO lanes: tromr (native OMR -> MusicXML, the
        // specialist) and got-ocr2 (sheet-music format mode). Reject only
        // when the model is knowably NEITHER.
        if model_spec_is_knowably_not_got(model_spec)
            && model_spec_is_knowably_not_tromr(model_spec)
        {
            return Err(FocrError::Usage(
                "--task music needs the tromr (native OMR -> MusicXML) or got-ocr2 \
                 (sheet-music format mode) model, but this run would use a different \
                 model. Re-run with `--model tromr.focrq` (see `focr models`)"
                    .into(),
            ));
        }
        return Ok(());
    }
    if task.implies_got_format() && model_spec_is_knowably_not_got(model_spec) {
        return Err(FocrError::Usage(format!(
            "--task {task} needs the got-ocr2 model, but this run would use the plain-text \
             unlimited-ocr model. Run `focr pull got-ocr2`, then re-run with \
             `--model got-ocr2.int8.focrq` (see `focr models`)"
        )));
    }
    Ok(())
}

/// True when the model spec is KNOWABLY not a smolvlm2 artifact: no spec at
/// all (the default resolution is always unlimited-ocr) or a file name naming
/// another family without `smolvlm`. An ambiguous name passes through to the
/// engine's arch tag.
/// The models that serve `task`; `None` when any model does.
fn task_models(task: OcrTask) -> Option<&'static [&'static str]> {
    match task {
        OcrTask::Ocr => None,
        OcrTask::Describe => Some(&["smolvlm2"]),
        OcrTask::ChartData => Some(&["onechart"]),
        OcrTask::Music => Some(&["tromr", "got-ocr2"]),
        OcrTask::Formula
        | OcrTask::Tables
        | OcrTask::Chart
        | OcrTask::Molecular
        | OcrTask::Geometry => Some(&["got-ocr2"]),
    }
}

/// Refuse a task the model in hand does not serve, judged by its header. The
/// name guard in [`validate_task_selection`] passes a file whose name says
/// nothing, and a model given a task it has no mode for returns plain text
/// with exit 0. A spec that does not resolve passes: the load reports that.
fn validate_task_for_header(task: OcrTask, request: &OcrRequest) -> FocrResult<()> {
    let Some(models) = task_models(task) else {
        return Ok(());
    };
    let spec = request.model.clone().unwrap_or_else(OcrEngine::model_path);
    match native_engine::model_id_at(&spec) {
        Some(id) if !models.contains(&id) => Err(FocrError::Usage(format!(
            "--task {task} needs {}, but {} holds {id}. Re-run with a model that serves it \
             (see `focr models`)",
            models.join(" or "),
            spec.display()
        ))),
        _ => Ok(()),
    }
}

/// True when the model spec is KNOWABLY not a onechart artifact (mirrors
/// [`model_spec_is_knowably_not_smolvlm2`]).
fn model_spec_is_knowably_not_onechart(spec: Option<&Path>) -> bool {
    let Some(path) = spec else {
        return true;
    };
    let Some(name) = path.file_name() else {
        return false;
    };
    let name = name.to_string_lossy().to_ascii_lowercase();
    !name.contains("onechart")
        && (name.contains("unlimited") || name.contains("got") || name.contains("smolvlm"))
}

/// True when the model spec is KNOWABLY not a tromr artifact (mirrors
/// [`model_spec_is_knowably_not_smolvlm2`]).
fn model_spec_is_knowably_not_tromr(spec: Option<&Path>) -> bool {
    let Some(path) = spec else {
        return true;
    };
    let Some(name) = path.file_name() else {
        return false;
    };
    let name = name.to_string_lossy().to_ascii_lowercase();
    !name.contains("tromr")
        && (name.contains("unlimited")
            || name.contains("got")
            || name.contains("smolvlm")
            || name.contains("onechart"))
}

fn model_spec_is_knowably_not_smolvlm2(spec: Option<&Path>) -> bool {
    let Some(path) = spec else {
        return true;
    };
    let Some(name) = path.file_name() else {
        return false;
    };
    let name = name.to_string_lossy().to_ascii_lowercase();
    !name.contains("smolvlm") && (name.contains("unlimited") || name.contains("got"))
}

/// True when the model spec is KNOWABLY not a got-ocr2 artifact: no spec at all
/// (the default resolution is always unlimited-ocr) or a file name carrying
/// `unlimited`. A name carrying `got` — or naming neither family — passes.
fn model_spec_is_knowably_not_got(spec: Option<&Path>) -> bool {
    let Some(path) = spec else {
        return true;
    };
    let Some(name) = path.file_name() else {
        return false;
    };
    let name = name.to_string_lossy().to_ascii_lowercase();
    name.contains("unlimited") && !name.contains("got")
}

/// How `--resume` continues an interrupted document (U2-D4).
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum ResumeMode {
    /// From a checkpoint whose settings match, byte-identically.
    Matching,
    /// From the completed pages, recomputing the next window.
    Recompute,
}

/// The frame colours `--color` takes: the ones GOT's fine-grained OCR was
/// trained on.
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum RegionColor {
    Red,
    Green,
    Blue,
}

impl RegionColor {
    fn frame(self) -> native_engine::got::FrameColor {
        match self {
            Self::Red => native_engine::got::FrameColor::Red,
            Self::Green => native_engine::got::FrameColor::Green,
            Self::Blue => native_engine::got::FrameColor::Blue,
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum CropMode {
    /// Reference dynamic-resolution tiling (`crop_mode=true`).
    Gundam,
    /// Single global view (`crop_mode=false`).
    Base,
}

impl std::fmt::Display for CropMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Gundam => "gundam",
            Self::Base => "base",
        })
    }
}

/// `--task` selector: route a run to the model/mode serving that task (the
/// model-zoo convenience surface, bd-3jo6.1.5). Values mirror the registry's
/// task names (`focr models`); the engine's `.focrq` arch tag stays the real
/// dispatcher — this only picks the prompt mode and validates the combination.
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum OcrTask {
    /// Plain document text → markdown (the default; today's behavior).
    Ocr,
    /// Math / formulas → LaTeX (got-ocr2; implies `--format`).
    Formula,
    /// Tables → structured markdown (got-ocr2; implies `--format`).
    Tables,
    /// Charts → structured output (got-ocr2; implies `--format`).
    Chart,
    /// Molecular structures → SMILES (got-ocr2; implies `--format`).
    Molecular,
    /// Geometry → TikZ (got-ocr2; implies `--format`).
    Geometry,
    /// Sheet music → `**kern` (got-ocr2; implies `--format`).
    Music,
    /// Photo description / VQA (smolvlm2; `--question` asks about the image).
    Describe,
    /// Chart → structured python-dict data + number-head self-verify
    /// (onechart; needs `--model onechart.int8.focrq`). Distinct from
    /// `chart`, which is GOT-OCR2's format-mode rendering.
    ChartData,
}

impl OcrTask {
    /// The six GOT-OCR2 structured tasks all run the model's `OCR with format:`
    /// mode — the same engine switch as `--format` (the model auto-selects the
    /// formalism from the image, so one switch serves all six).
    fn implies_got_format(self) -> bool {
        matches!(
            self,
            Self::Formula
                | Self::Tables
                | Self::Chart
                | Self::Molecular
                | Self::Geometry
                | Self::Music
        )
    }

    /// The tasks GOT reads better from a square-padded image, measured in
    /// `artifacts/accuracy/bd-kd75/`. `tables` must stay off this list: a padded
    /// table is read as SMILES. `molecular` and `geometry` were not measured apart
    /// from one already-square molecule, and `music` misreads either way.
    fn pads_got_image(self) -> bool {
        matches!(self, Self::Chart | Self::Formula)
    }
}

impl std::fmt::Display for OcrTask {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Ocr => "ocr",
            Self::Formula => "formula",
            Self::Tables => "tables",
            Self::Chart => "chart",
            Self::Molecular => "molecular",
            Self::Geometry => "geometry",
            Self::Music => "music",
            Self::Describe => "describe",
            Self::ChartData => "chart-data",
        })
    }
}

#[derive(Clone, Debug, Args)]
pub struct ConvertArgs {
    /// Source `model-00001-of-000001.safetensors`.
    pub input: PathBuf,
    /// Destination `.focrq`.
    #[arg(short, long)]
    pub output: PathBuf,
    /// Quantization target.
    #[arg(long, value_enum, default_value_t = QuantTarget::Int8)]
    pub quant: QuantTarget,
    /// Offline pre-packing target recorded in the `.focrq` header.
    #[arg(long, value_enum, default_value_t = ArchTarget::Generic)]
    pub arch: ArchTarget,
    /// Target model-architecture id the `.focrq` self-declares (the loader selects
    /// it from the registry). Omitted: the model whose tensor census the source
    /// matches (`unlimited-ocr` or `unlimited-ocr-2`). Required for the other
    /// models, e.g. `got-ocr2` (omits the tied `lm_head`, writes the Apache-2.0
    /// notice). An id that a different census matches is refused. See
    /// `focr models`.
    #[arg(long)]
    pub model_id: Option<String>,
    /// Activation-calibration JSON from a `FOCR_CALIB_OUT` run (bd-50wo stages
    /// B/C). Only honored by `--quant int4`: the expert/attention scales are then
    /// chosen by an importance-weighted clip search plus an AWQ channel-scale
    /// fold instead of plain round-to-nearest. The STORAGE FORMAT and the
    /// declared recipe id are unchanged — only the quantized values differ.
    /// Omitted ⇒ the byte-for-byte frozen uncalibrated artifact.
    #[arg(long, value_name = "FILE")]
    pub calib: Option<PathBuf>,
    /// Emit machine-readable scaffold JSON before the Phase-2 NotImplemented.
    #[arg(long)]
    pub json: bool,
}

#[derive(Clone, Debug, Args)]
pub struct RunsArgs {
    /// Specific run id to inspect.
    #[arg(long)]
    pub id: Option<String>,
    /// Maximum number of runs to list.
    #[arg(long, default_value_t = 20)]
    pub limit: i64,
    /// Output format for run history.
    #[arg(long, value_enum, default_value_t = OutputFormat::Plain)]
    pub format: OutputFormat,
    /// Alias for `--format json`.
    #[arg(long)]
    pub json: bool,
}

#[derive(Clone, Debug, Args)]
pub struct SyncArgs {
    /// Report the result as one JSON object on stdout (subcommand, store,
    /// file, records).
    #[arg(long, global = true)]
    pub json: bool,
    #[command(subcommand)]
    pub cmd: SyncCmd,
}

#[derive(Clone, Debug, Args)]
pub struct DoctorArgs {
    /// Emit the findings/report as one JSON object on stdout.
    #[arg(long)]
    pub json: bool,
    /// Apply the SAFE repairs (backup-first, hash-logged, reversible).
    /// Exit: 0 all fixed, 2 partial, 3 failed+rolled-back, 4 refused, 5 lock held.
    #[arg(long)]
    pub fix: bool,
    /// Disclose the worst-case blast radius without mutating anything.
    #[arg(long)]
    pub dry_run: bool,
    /// One-round-trip triage: {summary, findings, actions_planned,
    /// recommended_command} in one JSON object.
    #[arg(long)]
    pub robot_triage: bool,
    #[command(subcommand)]
    pub cmd: Option<DoctorCmd>,
}

#[derive(Clone, Debug, Eq, PartialEq, Subcommand)]
pub enum DoctorCmd {
    /// Restore a past --fix run byte-for-byte from its backups (hash-verified,
    /// fails closed on any missing backup).
    Undo {
        /// The run id printed by `doctor --fix` (also the dir name under
        /// `.doctor/runs/`).
        run_id: String,
    },
    /// The full doctor contract (detectors, fixers, exit codes, env), from
    /// the tool itself.
    Capabilities,
    /// Paste-ready agent handbook on stdout.
    RobotDocs,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum OutputFormat {
    Plain,
    Json,
    Ndjson,
}

impl std::fmt::Display for OutputFormat {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Plain => "plain",
            Self::Json => "json",
            Self::Ndjson => "ndjson",
        })
    }
}

#[derive(Clone, Debug, Eq, PartialEq, Subcommand)]
pub enum SyncCmd {
    /// Export run-state audit records as JSONL (atomic, locked, idempotent).
    /// Export is the CANONICAL one-way direction of the audit contract
    /// (tests/fixtures/runs_schema.json): identical history re-exports
    /// byte-identically; a crash never leaves a torn file.
    ExportJsonl {
        /// Output path (default: `<run store>.jsonl`).
        #[arg(long)]
        file: Option<std::path::PathBuf>,
    },
    /// Import (replay) run-state audit records from JSONL — additive and
    /// restorative, keyed by run_id. NEVER a bidirectional merge: import
    /// restores an audit trail, it does not sync one.
    ImportJsonl {
        /// Input JSONL path.
        #[arg(long)]
        file: std::path::PathBuf,
    },
}

#[derive(Subcommand)]
pub enum RobotCmd {
    /// Stream OCR pipeline events as NDJSON.
    Run(Box<RobotRunArgs>),
    /// Self-describing event/contract schema (versioned).
    Schema,
    /// Diagnostics: model present? arch features? threads?
    Health,
    /// Detected SIMD tiers (SMMLA/SDOT/VNNI/AMX/scalar) + core count.
    Backends,
    /// Verify the dispatched int8 kernel is bit-identical to the scalar oracle
    /// on THIS host's silicon (exit 1 on any divergence). `FOCR_FORCE_ARCH`
    /// selects which available tier to verify.
    Selftest,
    /// One-round-trip agent triage: quick_ref + live health + state-aware
    /// recommendations + copy-pasteable command templates + the exit-code
    /// dictionary, in a single JSON object (the mega-command an agent runs
    /// FIRST).
    Triage,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum QuantTarget {
    Int8,
    Int4,
}

impl QuantTarget {
    fn as_str(self) -> &'static str {
        match self {
            Self::Int8 => "int8",
            Self::Int4 => "int4",
        }
    }
}

impl std::fmt::Display for QuantTarget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum ArchTarget {
    Generic,
    Aarch64Smmla,
    X86Vnni,
    X86Amx,
}

impl ArchTarget {
    fn as_str(self) -> &'static str {
        match self {
            Self::Generic => "generic",
            Self::Aarch64Smmla => "aarch64-smmla",
            Self::X86Vnni => "x86-vnni",
            Self::X86Amx => "x86-amx",
        }
    }

    /// The `.focrq` header packing byte (`0` Generic … `3` X86Amx — the order the
    /// `FocrqBuilder`/reader fix for `arch_target`).
    fn packing_byte(self) -> u8 {
        match self {
            Self::Generic => 0,
            Self::Aarch64Smmla => 1,
            Self::X86Vnni => 2,
            Self::X86Amx => 3,
        }
    }
}

impl std::fmt::Display for ArchTarget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Dispatch a parsed CLI invocation.
pub fn run(cli: Cli) -> FocrResult<()> {
    match cli.command {
        Command::Robot {
            cmd: RobotCmd::Run(args),
        } => {
            emit(&robot::run_start_event("ocr"));
            run_ocr((*args).into_ocr_args(), true)
        }
        Command::Robot {
            cmd: RobotCmd::Schema,
        } => {
            emit(&robot::robot_schema());
            Ok(())
        }
        Command::Robot {
            cmd: RobotCmd::Health,
        } => {
            emit(&robot_health_payload());
            Ok(())
        }
        Command::Robot {
            cmd: RobotCmd::Backends,
        } => {
            emit(&robot_backends_payload());
            Ok(())
        }
        Command::Robot {
            cmd: RobotCmd::Selftest,
        } => run_robot_selftest(),
        Command::Robot {
            cmd: RobotCmd::Triage,
        } => {
            emit(&robot_triage_payload());
            Ok(())
        }
        Command::Ocr(args) if args.robot => {
            emit(&robot::run_start_event("ocr"));
            run_ocr(args, true)
        }
        Command::Ocr(args) => run_ocr(args, false),
        Command::OcrBatch(args) => run_ocr_batch(args),
        Command::Convert(args) => run_convert(&args),
        Command::Pull(args) => run_pull(&args),
        Command::Models(args) => run_models(&args),
        Command::Runs(args) => run_runs(&args),
        Command::Sync(args) => run_sync(&args),
        Command::Doctor(args) => run_doctor(&args),
        Command::ResidentDaemon(args) => crate::resident::run_daemon(&args.model_root),
    }
}

/// The result of one OCR run — a single image, or a multi-page PDF or directory
/// of page images — unified so the output layer (markdown vs JSON-with-boxes,
/// file vs stdout) is written once, identically, regardless of which input path
/// produced it.
enum Recognition {
    Single(native_engine::RecognizedDocument),
    Document(DocumentRecognition),
}

impl Recognition {
    /// The rendered markdown document (pages already joined by blank lines).
    fn markdown(&self) -> &str {
        match self {
            Recognition::Single(doc) => &doc.markdown,
            Recognition::Document(document) => &document.markdown,
        }
    }

    /// The decode as the model wrote it, grounding markers included.
    fn raw(&self) -> &str {
        match self {
            Recognition::Single(doc) => &doc.raw,
            Recognition::Document(document) => &document.raw,
        }
    }

    /// What a text output holds: `--raw`'s decode, else the markdown.
    fn text(&self, raw: bool) -> &str {
        if raw { self.raw() } else { self.markdown() }
    }

    /// The robot `page` events that carry a run's text when its pages did not
    /// stream: a single image is page 1, and a page-by-page document has one
    /// per page. A cross-page parse streamed its pages as it read them.
    fn unstreamed_page_events(&self) -> Vec<serde_json::Value> {
        match self {
            Recognition::Single(doc) => vec![robot::page_decoded_event(1, doc.raw.trim())],
            Recognition::Document(document) => match &document.pages {
                DocumentPageList::Layouts(pages) => pages
                    .iter()
                    .map(|page| {
                        let mut event = robot::page_decoded_event(page.page, page.raw.trim());
                        if let Some(half) = page.half {
                            event["half"] = half.into();
                        }
                        event
                    })
                    .collect(),
                DocumentPageList::Read(_) => Vec::new(),
            },
        }
    }

    /// The structured JSON form. Always carries `schema_version` + `markdown`; a
    /// single image adds a top-level `layout` array, a document adds a `pages`
    /// array of `{page, layout}` (plus `half` on a split spread's halves). A
    /// `--multi-page` document's pages also carry `run_index` and `text`, and
    /// `tokens` and `finish` when the model counts them
    /// ([`native_engine::PageResult::to_json`], U2-E3). Every `layout` is a list
    /// of `{label, boxes}` (plus `level` and `text` when the span has them), and
    /// each box is `[x1, y1, x2, y2]` in source-image pixels (top-left origin).
    /// With `raw`, a `raw` string sits beside the markdown and in each page.
    /// When figures were extracted, a top-level `figures` array of
    /// `{label, page, bbox, path}` (plus `half`) is appended (each `path` is the
    /// saved file, also referenced from the markdown).
    fn to_json(&self, figures: &[WrittenFigure], raw: bool) -> serde_json::Value {
        let mut value = match self {
            Recognition::Single(doc) => serde_json::json!({
                "schema_version": robot::ROBOT_SCHEMA_VERSION,
                "markdown": doc.markdown,
                "layout": layout_to_json(&doc.layout),
            }),
            Recognition::Document(document) => {
                let pages: Vec<serde_json::Value> = match &document.pages {
                    DocumentPageList::Layouts(layouts) => layouts
                        .iter()
                        .map(|p| {
                            let mut page = serde_json::json!({
                                "page": p.page,
                                "layout": layout_to_json(&p.layout),
                            });
                            // Split-spread halves carry their side; unsplit
                            // pages keep the exact pre-bd-av64.11 shape (no key).
                            if let Some(half) = p.half {
                                page["half"] = serde_json::json!(half);
                            }
                            if raw {
                                page["raw"] = p.raw.as_str().into();
                            }
                            page
                        })
                        .collect(),
                    DocumentPageList::Read(pages) => pages
                        .iter()
                        .map(|p| {
                            let mut page = p.to_json();
                            if raw {
                                page["raw"] = p.raw.as_str().into();
                            }
                            page
                        })
                        .collect(),
                };
                serde_json::json!({
                    "schema_version": robot::ROBOT_SCHEMA_VERSION,
                    "markdown": document.markdown,
                    "pages": pages,
                })
            }
        };
        if raw {
            value["raw"] = self.raw().into();
        }
        if !figures.is_empty()
            && let Some(obj) = value.as_object_mut()
        {
            let arr: Vec<serde_json::Value> = figures
                .iter()
                .map(|f| {
                    let mut figure = serde_json::json!({
                        "label": f.label,
                        "page": f.page,
                        "bbox": f.bbox,
                        "path": f.path,
                    });
                    if let Some(half) = f.half {
                        figure["half"] = half.as_str().into();
                    }
                    figure
                })
                .collect();
            obj.insert("figures".to_string(), serde_json::Value::Array(arr));
        }
        value
    }
}

/// Serialize a page's layout spans as a JSON array of `{label, boxes}` (plus
/// `level` on a leveled Unlimited-OCR-2 title), where each box is the
/// `[x1, y1, x2, y2]` pixel rectangle the model grounded that span to.
fn layout_to_json(layout: &[native_engine::LayoutSpan]) -> serde_json::Value {
    serde_json::Value::Array(
        layout
            .iter()
            .map(native_engine::LayoutSpan::to_json)
            .collect(),
    )
}

/// True when the OCR result should be emitted as JSON. An output path ending in
/// `.json` selects JSON even without `--json` (a `.md`/other extension stays
/// markdown); the explicit `--json` flag is handled by the caller.
fn output_is_json(output: Option<&Path>) -> bool {
    output
        .and_then(Path::extension)
        .is_some_and(|ext| ext.eq_ignore_ascii_case("json"))
}

/// What a run outputs: JSON or text, with the raw decode or without.
#[derive(Clone, Copy)]
struct OutputShape {
    json: bool,
    raw: bool,
}

impl OutputShape {
    /// The confirmation line's name for this output.
    fn name(self) -> &'static str {
        match (self.json, self.raw) {
            (true, _) => "json",
            (false, true) => "raw decode",
            (false, false) => "markdown",
        }
    }
}

/// Write the recognition result to `path` as pretty JSON (with per-span bounding
/// boxes + any extracted `figures`, and the `model` that ran) when `shape.json`,
/// else as the rendered markdown, or the raw decode under `shape.raw`. Both
/// forms end with a trailing newline so the file is well-formed for downstream
/// tools.
fn write_ocr_output(
    path: &Path,
    rec: &Recognition,
    shape: OutputShape,
    figures: &[WrittenFigure],
    extras: RunExtras<'_>,
) -> FocrResult<()> {
    let contents = if shape.json {
        let mut value = rec.to_json(figures, shape.raw);
        extras.merge_into(&mut value);
        let mut s = serde_json::to_string_pretty(&value).map_err(|e| {
            FocrError::Other(anyhow::anyhow!(
                "serializing OCR JSON for {}: {e}",
                path.display()
            ))
        })?;
        s.push('\n');
        s
    } else {
        let text = rec.text(shape.raw);
        if text.ends_with('\n') {
            text.to_string()
        } else {
            format!("{text}\n")
        }
    };
    std::fs::write(path, contents).map_err(|e| {
        FocrError::Other(anyhow::anyhow!(
            "writing OCR output to {}: {e}",
            path.display()
        ))
    })
}

// ── figure extraction (`--extract-figures`) ─────────────────────────────────

/// The encoding chosen for one extracted figure by [`choose_figure_format`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum FigureFormat {
    /// Lossless — for line-art / charts / screenshots (sharp edges, flat regions).
    Png,
    /// Lossy q85 — for photographic regions (smaller, ringing is imperceptible).
    Jpeg,
}

impl FigureFormat {
    fn ext(self) -> &'static str {
        match self {
            FigureFormat::Png => "png",
            FigureFormat::Jpeg => "jpg",
        }
    }
}

/// Pick a format for a cropped figure by content (the user's "auto" choice):
/// photographic regions have MANY distinct colors → JPG (small, lossy is fine);
/// line-art / charts / screenshots cluster into a few flat colors → PNG (lossless,
/// no ringing on sharp lines or embedded text). A grid sample of up to ~4096
/// pixels is quantized to 5 bits/channel and the distinct-color count + ratio
/// decide. Deterministic; defaults to PNG (the safe, lossless choice) on any
/// degenerate input.
fn choose_figure_format(img: &image::DynamicImage) -> FigureFormat {
    let rgb = img.to_rgb8();
    let total = u64::from(rgb.width()) * u64::from(rgb.height());
    if total == 0 {
        return FigureFormat::Png;
    }
    let step = total.div_ceil(4096).max(1) as usize;
    let mut seen = std::collections::HashSet::new();
    let mut sampled = 0u64;
    for px in rgb.pixels().step_by(step) {
        let [r, g, b] = px.0;
        let key = (u32::from(r >> 3) << 10) | (u32::from(g >> 3) << 5) | u32::from(b >> 3);
        seen.insert(key);
        sampled += 1;
    }
    if sampled == 0 {
        return FigureFormat::Png;
    }
    let ratio = seen.len() as f64 / sampled as f64;
    // Few distinct colors OR a low unique-color ratio ⇒ line-art ⇒ PNG.
    if seen.len() <= 64 || ratio < 0.10 {
        FigureFormat::Png
    } else {
        FigureFormat::Jpeg
    }
}

/// Encode `img` to `path` in the chosen format — JPG at quality 85, PNG lossless.
fn write_figure(img: &image::DynamicImage, path: &Path, fmt: FigureFormat) -> FocrResult<()> {
    let file = std::fs::File::create(path)
        .map_err(|e| FocrError::Other(anyhow::anyhow!("create figure {}: {e}", path.display())))?;
    let mut writer = std::io::BufWriter::new(file);
    let enc = |e: image::ImageError| {
        FocrError::Other(anyhow::anyhow!("encode figure {}: {e}", path.display()))
    };
    match fmt {
        FigureFormat::Jpeg => {
            image::codecs::jpeg::JpegEncoder::new_with_quality(&mut writer, 85)
                .encode_image(img)
                .map_err(enc)?;
        }
        FigureFormat::Png => {
            img.write_to(&mut writer, image::ImageFormat::Png)
                .map_err(enc)?;
        }
    }
    Ok(())
}

/// One figure written to disk, for the JSON `figures` array.
struct WrittenFigure {
    /// The model's ref label (`image`).
    label: String,
    /// 1-based source page (1 for a single image).
    page: usize,
    /// The half of a split spread the figure is on.
    half: Option<Half>,
    /// Source-pixel box `[x1, y1, x2, y2]` the figure was cropped from.
    bbox: [i64; 4],
    /// The reference path written into the markdown/JSON (relative to the output).
    path: String,
}

/// Where extracted figures are written and how they are referenced — resolved
/// from `--extract-figures` / `--figures-dir` + the `-o` path BEFORE any forward,
/// so a usage error fires immediately.
#[derive(Debug)]
struct FigurePlan {
    /// Filesystem directory figures are written into.
    dir: PathBuf,
    /// Prefix prepended to each figure filename in references (ends with `/`).
    ref_prefix: String,
}

impl FigurePlan {
    /// `Ok(None)` when figure extraction is off; `Ok(Some(plan))` otherwise.
    /// Usage error if `--extract-figures` is set with neither `-o` nor
    /// `--figures-dir` (no way to place the subfolder).
    fn resolve(args: &OcrArgs) -> FocrResult<Option<FigurePlan>> {
        if !args.extract_figures && args.figures_dir.is_none() {
            return Ok(None);
        }
        let output = args.output.as_deref();
        let plan = if let Some(dir_arg) = args.figures_dir.as_deref() {
            // Explicit dir: used verbatim in references; resolved against the
            // output file's dir (or the cwd for a stdout run) when relative.
            let ref_prefix = with_trailing_slash(&dir_arg.to_string_lossy());
            let dir = if dir_arg.is_absolute() {
                dir_arg.to_path_buf()
            } else {
                output_parent(output).join(dir_arg)
            };
            FigurePlan { dir, ref_prefix }
        } else {
            // `--extract-figures`: derive `<output-stem>_figures/` next to `-o`.
            let Some(out) = output else {
                return Err(FocrError::Usage(
                    "--extract-figures needs -o/--output to derive the figures \
                     subfolder; pass --figures-dir DIR for a stdout run"
                        .to_string(),
                ));
            };
            let stem = out
                .file_stem()
                .map_or_else(|| "ocr".to_string(), |s| s.to_string_lossy().into_owned());
            let dirname = format!("{stem}_figures");
            let dir = output_parent(output).join(&dirname);
            FigurePlan {
                dir,
                ref_prefix: format!("{dirname}/"),
            }
        };
        Ok(Some(plan))
    }

    fn writer(&self) -> FigureWriter {
        FigureWriter {
            dir: self.dir.clone(),
            ref_prefix: self.ref_prefix.clone(),
            created: false,
            written: Vec::new(),
        }
    }
}

/// The output file's parent directory, or `.` (cwd) for a bare filename / stdout.
fn output_parent(output: Option<&Path>) -> PathBuf {
    output
        .and_then(Path::parent)
        .filter(|p| !p.as_os_str().is_empty())
        .map_or_else(|| PathBuf::from("."), Path::to_path_buf)
}

fn with_trailing_slash(s: &str) -> String {
    if s.is_empty() || s.ends_with('/') {
        s.to_string()
    } else {
        format!("{s}/")
    }
}

/// Writes a run's figures to disk (creating the dir lazily on the first one) and
/// rewrites each page's `![](images/…)` token to a real `![figure N](path)`,
/// accumulating the [`WrittenFigure`] records for the JSON output.
struct FigureWriter {
    dir: PathBuf,
    ref_prefix: String,
    created: bool,
    written: Vec<WrittenFigure>,
}

impl FigureWriter {
    fn ensure_dir(&mut self) -> FocrResult<()> {
        if !self.created {
            std::fs::create_dir_all(&self.dir).map_err(|e| {
                FocrError::Other(anyhow::anyhow!(
                    "create figures dir {}: {e}",
                    self.dir.display()
                ))
            })?;
            self.created = true;
        }
        Ok(())
    }

    /// Write one page's figures and return its markdown with each figure token
    /// rewritten to point at the saved file. `page` is 1-based (1 for a single
    /// image); figures are named `page{page}_figure_{n}.{ext}` (n 1-based, matching
    /// the page-local markdown index), and a spread's halves
    /// `page{page}l_figure_{n}` and `page{page}r_figure_{n}` (U2-E3).
    fn process_page(
        &mut self,
        page: usize,
        half: Option<Half>,
        markdown: &str,
        figures: Vec<native_engine::ExtractedFigure>,
    ) -> FocrResult<String> {
        let mut md = markdown.to_string();
        let side = half
            .map(Half::initial)
            .map(String::from)
            .unwrap_or_default();
        for fig in figures {
            let fignum = fig.index + 1;
            let fmt = choose_figure_format(&fig.image);
            let name = format!("page{page}{side}_figure_{fignum}.{}", fmt.ext());
            self.ensure_dir()?;
            write_figure(&fig.image, &self.dir.join(&name), fmt)?;
            let rel = format!("{}{name}", self.ref_prefix);
            md = md.replace(&fig.markdown_ref, &format!("![figure {fignum}]({rel})"));
            self.written.push(WrittenFigure {
                label: fig.label,
                page,
                half,
                bbox: fig.bbox,
                path: rel,
            });
        }
        Ok(md)
    }

    fn into_written(self) -> Vec<WrittenFigure> {
        self.written
    }
}

/// `--threads` and `--timing`, before anything reads the budget.
fn apply_tuning(threads: Option<std::num::NonZeroUsize>, timing: bool) -> FocrResult<()> {
    if let Some(threads) = threads {
        crate::set_thread_budget(threads)?;
    }
    if timing {
        crate::enable_timing();
    }
    Ok(())
}

fn run_ocr(args: OcrArgs, robot_mode: bool) -> FocrResult<()> {
    // Best-effort run telemetry (bd-223.4): capture the logging fields before
    // the args move, record the outcome after — a store failure NEVER fails
    // the user's run (stderr note only).
    let telemetry_input = args.request.image.display().to_string();
    let telemetry_model = args
        .request
        .model
        .as_ref()
        .map_or_else(|| "default".to_owned(), |p| p.display().to_string());
    let started = crate::storage::now_millis();
    let mut ran = None;
    let check = args.check;
    apply_tuning(args.request.threads, args.request.timing)?;
    let outcome = run_ocr_inner(args, robot_mode, &mut ran);
    // A preflight is not a run: `focr runs` is the recognition history.
    if check {
        return outcome;
    }
    let quant = if telemetry_model.contains("int8") {
        "int8"
    } else if telemetry_model.contains("int4") {
        "int4"
    } else {
        "f32-or-default"
    };
    let (status, exit_code) = match &outcome {
        Ok(()) => ("ok", 0i64),
        Err(FocrError::Cancelled) => ("cancelled", 6),
        Err(e) => ("error", i64::from(e.exit_code())),
    };
    let record = crate::storage::RunRecord {
        run_id: uuid::Uuid::new_v4().to_string(),
        started_at: started,
        finished_at: Some(crate::storage::now_millis()),
        input_path: telemetry_input,
        mode: "ocr".into(),
        quant: quant.into(),
        // `<model_id>@<source_sha256>` for the model that ran (U2-E1, D25);
        // `unknown` when the run ended before one loaded.
        model_version_tag: ran.as_ref().map_or_else(
            || "unknown".to_owned(),
            native_engine::ModelIdentity::version_tag,
        ),
        exit_code,
        status: status.into(),
    };
    if let Err(e) = crate::storage::RunStore::default_path()
        .and_then(|p| crate::storage::RunStore::open(&p))
        .and_then(|store| store.insert_run(&record))
    {
        // Robot mode contracts for a machine-readable stream and NOTHING else
        // on stderr, so the human note is dropped there rather than corrupting
        // a consumer's parse. The store is best-effort telemetry either way,
        // and the run's own outcome is already reported as a `run_error`
        // event with the same exit code.
        //
        // This is reachable on any user whose `~/.cache/franken_ocr/runs.db`
        // is unhealthy — an empty `_meta` is enough — which is a property of
        // the machine, not of the run being recorded.
        if !robot_mode {
            let _ = progress::try_stderr_message(format_args!(
                "[focr] run-store note (telemetry only, run unaffected): {e}"
            ));
        }
    }
    outcome
}

/// The input path that means stdin.
const STDIN_INPUT: &str = "-";

/// `focr ocr -`: the input copied from stdin into a private directory, which
/// goes when the run ends. Every reader takes a path, the resident daemon's
/// among them, and takes an image's format from the file's extension.
struct StdinInput {
    dir: PathBuf,
    file: PathBuf,
}

impl StdinInput {
    fn capture() -> FocrResult<Self> {
        let stdin = std::io::stdin();
        if stdin.is_terminal() {
            return Err(FocrError::Usage(
                "`focr ocr -` reads an image or a PDF from stdin, and nothing is piped in".into(),
            ));
        }
        let dir =
            std::env::temp_dir().join(format!("focr-stdin-{}", uuid::Uuid::new_v4().simple()));
        let unwritable = |e: std::io::Error| {
            FocrError::Other(anyhow::anyhow!("saving stdin under {}: {e}", dir.display()))
        };
        let mut builder = std::fs::DirBuilder::new();
        #[cfg(unix)]
        std::os::unix::fs::DirBuilderExt::mode(&mut builder, 0o700);
        builder.create(&dir).map_err(unwritable)?;
        let mut input = Self {
            file: dir.join("stdin"),
            dir: dir.clone(),
        };
        let mut file = std::fs::File::create_new(&input.file).map_err(unwritable)?;
        let bytes = std::io::copy(&mut stdin.lock(), &mut file).map_err(unwritable)?;
        drop(file);
        if bytes == 0 {
            return Err(FocrError::InputDecode(
                "stdin is empty: pipe an image or a PDF into `focr ocr -`".into(),
            ));
        }
        let mut head = [0u8; 64];
        let read = std::fs::File::open(&input.file)
            .and_then(|mut file| file.read(&mut head))
            .map_err(unwritable)?;
        let extension = if pdf::looks_like_pdf_bytes(&head[..read]) {
            "pdf"
        } else {
            image::guess_format(&head[..read])
                .ok()
                .and_then(|format| format.extensions_str().first().copied())
                .ok_or_else(|| {
                    FocrError::InputDecode(
                        "stdin holds neither a PDF nor an image format focr reads".into(),
                    )
                })?
        };
        let named = input.file.with_extension(extension);
        std::fs::rename(&input.file, &named).map_err(unwritable)?;
        input.file = named;
        Ok(input)
    }
}

impl Drop for StdinInput {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.dir);
    }
}

/// What `focr ocr --check` says about the input: a single image from its
/// header, a document from its page list. `named` is the input as given.
fn check_input(
    named: &Path,
    request: &OcrRequest,
    source: Option<&PageSource>,
) -> FocrResult<serde_json::Value> {
    let path = &request.image;
    if let Some(source) = source {
        let kind = if path.is_dir() { "directory" } else { "pdf" };
        return Ok(serde_json::json!({
            "path": named,
            "kind": kind,
            "pages": source.len(),
            "source_pages": source.source_len(),
        }));
    }
    let (width, height) = image::image_dimensions(path)
        .map_err(|e| FocrError::InputDecode(format!("{}: {e}", named.display())))?;
    Ok(serde_json::json!({
        "path": named,
        "kind": "image",
        "width": width,
        "height": height,
    }))
}

/// Refuse `-o` when the run could not write its result, so a long decode does
/// not end in a failed write.
fn check_output(output: &Path) -> FocrResult<()> {
    let parent = output
        .parent()
        .filter(|parent| !parent.as_os_str().is_empty())
        .unwrap_or_else(|| Path::new("."));
    if output.is_dir() {
        return Err(FocrError::Usage(format!(
            "-o {} is a directory: name a file",
            output.display()
        )));
    }
    if !parent.is_dir() {
        return Err(FocrError::Usage(format!(
            "-o {}: {} is not a directory",
            output.display(),
            parent.display()
        )));
    }
    Ok(())
}

/// Finish `focr ocr --check`: the run's own argument checks have passed, so
/// check what is left before a decode and report it. A failure returns the
/// error the run would return.
fn report_check(
    args: &OcrArgs,
    request: &OcrRequest,
    source: Option<&PageSource>,
    warnings: &[native_engine::RunWarning],
) -> FocrResult<()> {
    // A run loads the model before it reads the image, so a request wrong in
    // both ways fails on the model here too.
    let model = request.model.clone().unwrap_or_else(OcrEngine::model_path);
    let (artifact, model_id) = native_engine::preflight_model(&model).map_err(|e| match e {
        FocrError::ModelNotFound(msg) => {
            FocrError::ModelNotFound(with_pull_hint(&msg, request.model.as_deref()))
        }
        other => other,
    })?;
    let input = check_input(&args.request.image, request, source)?;
    if let Some(output) = args.output.as_deref() {
        check_output(output)?;
    }
    if args.json {
        let mut value = serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "ocr.check",
            "ok": true,
            "input": input,
            "model": { "id": model_id, "path": artifact },
            "output": args.output,
            "threads": crate::thread_budget(),
            "timing": crate::timing_enabled(),
        });
        merge_run_warnings(&mut value, warnings);
        println!("{value}");
    } else {
        let described = match (input["kind"].as_str(), input["pages"].as_u64()) {
            (Some(kind), Some(pages)) => format!("{kind}, {pages} pages to read"),
            _ => format!("image, {}x{}", input["width"], input["height"]),
        };
        println!(
            "ok: {} ({described}); {model_id} from {}",
            args.request.image.display(),
            artifact.display()
        );
    }
    Ok(())
}

/// One `focr ocr` run. `ran` is set to the model that served it as soon as the
/// recognition returns, so the run store records it even when the run then
/// fails (a partial document, a low yield).
fn run_ocr_inner(
    args: OcrArgs,
    robot_mode: bool,
    ran: &mut Option<native_engine::ModelIdentity>,
) -> FocrResult<()> {
    if args.check && robot_mode {
        return Err(FocrError::Usage(
            "--check reports once and streams no events: pass --json instead of --robot".into(),
        ));
    }
    let mut request = args.to_request()?;
    let stdin_input = (request.image.as_os_str() == STDIN_INPUT)
        .then(StdinInput::capture)
        .transpose()?;
    if let Some(input) = &stdin_input {
        request.image.clone_from(&input.file);
    }
    // GOT-OCR2 `--format` (.mmd) mode and the decode tuning flags (`--max-length`,
    // `--temperature`, `--no-repeat-ngram`, `--ngram-window`) are threaded to the
    // leaf via process-globals (the shared OcrEngine/OcrModel signatures stay
    // frozen for the Baidu path). `request.format` already carries `--format` OR a
    // format-implying `--task` (folded in `to_request`). MUST precede
    // `OcrEngine::new()`: the decode params are resolved at model load.
    native_engine::force_got_format(request.format);
    native_engine::force_got_square_pad(request.square_pad);
    native_engine::set_got_region(request.region);
    native_engine::set_smolvlm2_question(request.question.clone());
    native_engine::set_decode_overrides(decode_overrides_from(&request));
    native_engine::set_preprocess_overrides(preprocess_overrides_from(&request));
    if let Some(err) = forced_test_error()? {
        return Err(err);
    }
    native_engine::validate_test_max_positions()?;
    // Resolve the figure-extraction policy BEFORE the forward so a usage error
    // (e.g. `--extract-figures` without a place to put the subfolder) fires fast.
    let figure_plan = FigurePlan::resolve(&args)?;

    let engine = OcrEngine::new()?;
    // A `.pdf` (or `%PDF-`-magic) input or a directory of page images is a
    // document: its pages are read one at a time from a [`PageSource`] and
    // OCR'd as one document (U2-D0). Everything else is a single decoded image.
    // Both funnel through `recognize_with_autodownload` so model resolution +
    // the first-run download offer behave identically. Both recognize WITH
    // layout so the JSON output can carry bounding boxes — the layout parse is
    // negligible next to the forward pass, and markdown-only consumers simply
    // ignore it. With `--extract-figures` the figure-aware variants additionally
    // crop the `![](images/…)` regions out of the source and rewrite the
    // markdown references to the saved files.
    let is_document = pdf::looks_like_pdf(&request.image) || request.image.is_dir();
    // Human-mode progress (GH #2): a stderr-only bar for the long per-page
    // document drivers. NEVER in robot/`--json` mode — those stdout contracts
    // are machine-consumed — and `progress::Progress` additionally
    // self-disables when stderr is not an interactive TTY, so piped runs are
    // byte-identical.
    let show_progress = !robot_mode && !args.json;
    if !is_document && (request.pages.is_some() || request.split_spreads || request.multi_page) {
        return Err(FocrError::Usage(format!(
            "--pages/--split-spreads/--multi-page operate on the pages of a PDF or of a \
             directory of page images, but {} is neither (for an image list, use `focr \
             ocr-batch --multi-page`)",
            request.image.display()
        )));
    }
    // The mode default (D25): an installed non-v1 default names the model; a
    // missing one leaves v1 serving with a pull hint.
    let mode = RunMode::of_ocr(&request, is_document);
    let pull_hint = apply_mode_default(&mut request.model, mode, &MODE_DEFAULTS);
    validate_task_for_header(args.request.task, &request)?;
    validate_region_for_header(&request)?;
    // A model that splits a document into pages exactly (Unlimited-OCR-2,
    // U2-E3) gives one cross-page pass real pages, so its document mode
    // composes with --split-spreads and --extract-figures. v1 merges pages.
    let paged_model = is_document.then(|| paged_model_id(&request)).flatten();
    let paged_document = request.multi_page && paged_model.is_some();
    if request.multi_page && !paged_document && (request.split_spreads || figure_plan.is_some()) {
        return Err(FocrError::Usage(
            "--multi-page is one cross-page pass over whole pages; it does not compose \
             with --split-spreads or --extract-figures (run those per-page passes \
             separately, or pass --model unlimited-ocr-2, whose pages are exact)"
                .into(),
        ));
    }
    if request.split_spreads && figure_plan.is_some() && !paged_document {
        return Err(FocrError::Usage(
            "--split-spreads does not compose with --extract-figures yet (figure \
             naming is per source page; splitting would collide the indices) — \
             run the passes separately, or with --model unlimited-ocr-2 add \
             --multi-page"
                .into(),
        ));
    }
    if request.page_window.is_some() && !request.multi_page {
        return Err(FocrError::Usage(
            "--page-window splits a document read as one: pass --multi-page".into(),
        ));
    }
    let unwindowed = request.page_window == Some(native_engine::PageWindow::Off);
    if unwindowed && (request.resume.is_some() || request.keep_checkpoint) {
        return Err(FocrError::Usage(
            "--page-window off reads the document in one pass, which has no window to resume \
             from: drop --resume and --keep-checkpoint, or choose a window"
                .into(),
        ));
    }
    if (request.resume.is_some() || request.keep_checkpoint) && !paged_document {
        return Err(FocrError::Usage(
            "--resume and --keep-checkpoint continue a windowed document: pass --multi-page \
             with --model unlimited-ocr-2"
                .into(),
        ));
    }
    let run_files = if paged_document && !unwindowed {
        document_run_files(&request, args.output.as_deref())?
    } else {
        None
    };
    // A document's pages, opened once here so a bad `--pages` spec or a
    // directory without page images fails before the model loads. Files a
    // directory leaves out are reported now, and again on `run_complete`,
    // after the pull hint.
    let source = is_document
        .then(|| open_page_source(&request))
        .transpose()?;
    let mut early_warnings: Vec<native_engine::RunWarning> = pull_hint.into_iter().collect();
    early_warnings.extend(
        source
            .as_ref()
            .map(PageSource::warnings)
            .unwrap_or_default(),
    );
    if !robot_mode {
        early_warnings.iter().for_each(print_run_warning);
    }
    if args.check {
        return report_check(&args, &request, source.as_ref(), &early_warnings);
    }
    // A resident run decodes in the daemon, which reports its decode report
    // (U2-X2, bd-u77k) and model (U2-E1) in the reply; inline runs leave both
    // on this engine's model.
    let mut resident_report: Option<native_engine::DecodeReport> = None;
    let mut resident_model: Option<native_engine::ModelIdentity> = None;
    let mut resident_music: Option<native_engine::MusicPageMeta> = None;
    let mut resident_chart: Option<native_engine::ChartPageMeta> = None;
    let stages = robot_mode.then(|| Arc::new(robot::StageClock::start()));
    if let Some(stages) = &stages {
        let stages = Arc::clone(stages);
        engine.set_stage_sink(Some(Box::new(move |name, budget| {
            emit(&stages.entered(name, budget));
        })));
    }
    let mut document_outcome = DocumentOutcome::default();
    let (recognition, figures): (Recognition, Vec<WrittenFigure>) = match (&figure_plan, source) {
        (plan, Some(source)) if request.multi_page => {
            let (document, figs, outcome) = recognize_document_multi_page(
                &engine,
                &request,
                source,
                DocumentRun {
                    robot_mode,
                    show_progress,
                    paged_model,
                },
                plan.as_ref(),
                run_files.as_ref(),
            )?;
            document_outcome = outcome;
            (Recognition::Document(document), figs)
        }
        (Some(plan), Some(source)) => {
            let (pages, figs) = recognize_document_pages_with_figures(
                &engine,
                &request,
                source,
                DocumentRun {
                    robot_mode,
                    show_progress,
                    paged_model,
                },
                plan,
            )?;
            (Recognition::Document(pages), figs)
        }
        (Some(plan), None) => {
            let (mut doc, raw) =
                recognize_with_autodownload(&request, robot_mode, |model| match model {
                    Some(m) => engine.recognize_with_figures_model(m, &request.image),
                    None => engine.recognize_with_figures(&request.image),
                })?;
            let mut writer = plan.writer();
            doc.markdown = writer.process_page(1, None, &doc.markdown, raw)?;
            (Recognition::Single(doc), writer.into_written())
        }
        (None, Some(source)) => (
            Recognition::Document(recognize_document_pages(
                &engine,
                &request,
                source,
                DocumentRun {
                    robot_mode,
                    show_progress,
                    paged_model,
                },
            )?),
            Vec::new(),
        ),
        (None, None) => {
            // Tall-capture routing (GH #15): a single pass over an
            // extreme-aspect image squashes glyphs below legibility and
            // returns near-empty markdown with exit 0. Route such images
            // through smart-cut horizontal strips instead (document-OCR task
            // only — specialty outputs are not line-concatenable).
            let tall_dims = (args.request.task == OcrTask::Ocr)
                .then(|| image::image_dimensions(&request.image).ok())
                .flatten()
                .filter(|&(w, h)| crate::tall::is_tall(w, h));
            if let Some((width, height)) = tall_dims {
                let doc = recognize_tall_capture(&engine, &request, robot_mode, width, height)?;
                (Recognition::Single(doc), Vec::new())
            } else {
                // The resident warm-model path (GH #9): serve eligible
                // single-image runs from a per-model background daemon that keeps
                // the weights loaded across invocations. `Ok(None)` — daemon
                // unavailable, ineligible, or any transport-shaped failure —
                // falls through to the classic in-process load; the observable
                // output contract is identical either way.
                let doc = match resident_recognition(&args, &request, stages.as_deref())? {
                    Some(reply) => {
                        resident_report = reply.report;
                        resident_model = reply.model;
                        resident_music = reply.music;
                        resident_chart = reply.chart;
                        reply.document
                    }
                    None => {
                        recognize_with_autodownload(&request, robot_mode, |model| match model {
                            Some(m) => engine.recognize_with_layout_model(m, &request.image),
                            None => engine.recognize_with_layout(&request.image),
                        })?
                    }
                };
                (Recognition::Single(doc), Vec::new())
            }
        }
    };

    // How the run's decodes ended (U2-X2): the run-level finish_reason and
    // the v1 multi-page truncation / page-merge warnings, after the input's
    // own warnings. Absent when the model's arm records no decode report (the
    // zoo models).
    let decode_report = resident_report.or_else(|| engine.take_last_decode_report());
    let finish_reason = decode_report
        .as_ref()
        .map(native_engine::DecodeReport::run_finish_reason);
    let model = resident_model.or_else(|| engine.loaded_model_identity());
    ran.clone_from(&model);
    let mut run_warnings = early_warnings;
    run_warnings.extend(
        decode_report
            .as_ref()
            .map(native_engine::decode_warnings)
            .unwrap_or_default(),
    );
    run_warnings.extend(document_outcome.warnings);
    let chart_meta = resident_chart.or_else(|| engine.take_chart_page_meta());
    run_warnings.extend(chart_meta.as_ref().and_then(native_engine::chart_warning));
    let resumed_from = document_outcome.resumed_from;
    // An Unlimited-OCR-2 document that stopped at its position limit or
    // stage budget writes what it produced below, then exits 5 (U2-B6). A
    // decode report comes with the model that ran it, here or in the daemon,
    // so `model` is known whenever there is one. Its journal and checkpoint
    // stay (U2-D4).
    let partial = decode_report
        .as_ref()
        .zip(model.as_ref())
        .and_then(|(report, model)| native_engine::partial_output(report, &run_warnings, model))
        .map(|stopped| with_resume_fields(stopped, run_files.as_ref(), resumed_from));
    if !robot_mode {
        print_run_warnings(&run_warnings);
    }

    // Staff-level metadata from a TrOMR music forward (bd-av64.2): consumed
    // once per run; None for every non-music run.
    let music_meta = resident_music.or_else(|| engine.take_music_page_meta());
    if robot_mode && let Some(meta) = &music_meta {
        let total = meta.staves.len() + meta.skips.len();
        for (index, bbox) in &meta.staves {
            emit(&robot::staff_event(*index, total, *bbox, "ok", None));
        }
        for skip in &meta.skips {
            emit(&robot::staff_event(
                skip.index,
                total,
                skip.bbox,
                "skipped",
                Some(&skip.reason),
            ));
        }
        for w in &meta.warnings {
            emit(&robot::music_warning_event(
                w.kind, w.part, w.measure, &w.detail,
            ));
        }
    }
    if !robot_mode
        && let Some(meta) = &music_meta
        && !meta.warnings.is_empty()
    {
        eprintln!(
            "[focr] {} musical-sanity warning(s) — annotated in the MusicXML; \
             re-run with --robot for machine-readable detail",
            meta.warnings.len()
        );
    }

    let markdown = recognition.markdown();

    // Low-yield guard (GH #15): a page-sized single image whose "successful"
    // run produced almost no text is the silent-failure signature of tall or
    // low-DPI captures. Flag it on `run_complete` (robot) / stderr (human),
    // and with --fail-on-low-yield fail BEFORE any output is written so a
    // gating pipeline never records the run as good. Judged only for the
    // plain document-OCR task — a VQA answer is legitimately short.
    let low_yield = if is_document || args.request.task != OcrTask::Ocr {
        None
    } else {
        image::image_dimensions(&request.image)
            .ok()
            .and_then(|(w, h)| crate::tall::low_yield_assessment(markdown, w, h))
    };
    if let Some(assessment) = &low_yield {
        if args.request.fail_on_low_yield {
            return Err(FocrError::LowYield(format!(
                "{:.2} MP input produced only {} character(s) of text (< {} chars/MP)",
                assessment.input_megapixels,
                assessment.yield_chars,
                crate::tall::LOW_YIELD_CHARS_PER_MEGAPIXEL
            )));
        }
        if !robot_mode {
            eprintln!(
                "[focr] warning: low yield — {:.2} MP input produced only {} character(s) of \
                 recognized text. If this is a full-page capture, re-capture at higher \
                 resolution: very tall images are tiled automatically, but glyphs below \
                 ~12px are unrecoverable by any OCR engine.",
                assessment.input_megapixels, assessment.yield_chars
            );
        }
    }

    // `--json` forces JSON; a `.json` output path selects it implicitly. (When no
    // `-o` is given, `output_is_json(None)` is false, so stdout behavior is exactly
    // the legacy `args.json` choice.)
    let shape = OutputShape {
        json: args.json || output_is_json(args.output.as_deref()),
        raw: args.raw,
    };
    let extras = RunExtras {
        finish_reason,
        music: music_meta.as_ref(),
        chart: chart_meta.as_ref(),
        warnings: &run_warnings,
        model: model.as_ref(),
    };

    // An `-o/--output FILE` writes the result to disk (markdown or JSON-with-boxes)
    // regardless of mode, and is written FIRST so the file already exists when a
    // robot consumer sees the completion event below.
    if let Some(path) = args.output.as_deref() {
        write_ocr_output(path, &recognition, shape, &figures, extras)?;
    }
    // The document is out, so what could have resumed it is done with. A
    // file left behind costs disk, not the result.
    if partial.is_none()
        && let Some(files) = &run_files
        && let Err(e) = files.remove(request.keep_checkpoint)
    {
        eprintln!("[focr] warning: {e}");
    }

    if robot_mode {
        // The terminal success event carries the recognized markdown so a machine
        // consumer actually receives the OCR result on the NDJSON stream (the
        // human / `--json` modes print it below instead). A partial run ends
        // on its `run_error` instead, never after a `run_complete`.
        if partial.is_none() {
            let mut event = robot::run_complete_event_assessed(
                markdown,
                low_yield.as_ref(),
                finish_reason,
                &run_warnings,
                model.as_ref(),
            );
            if args.raw {
                event["raw"] = recognition.raw().into();
            }
            if let Some(page) = resumed_from {
                event["resumed_from"] = page.into();
            }
            if let Some(meta) = &chart_meta {
                event["chart"] = chart_meta_to_json(meta);
            }
            if let Some(counts) = &document_outcome.counts {
                event["pages_out"] = counts.pages_out.into();
                event["pages_skipped"] = counts.pages_skipped.into();
                event["windows"] = counts.windows.into();
                event["extra_markers"] = counts.extra_markers.into();
            }
            emit(&event);
        } else if matches!(&partial, Some(FocrError::Partial(p)) if p.finish_reason == "runaway") {
            // A v1 decode the runaway guard stopped streamed no page, so the
            // text before the stop goes out as `page` events before the
            // run_error (bd-gftg).
            for event in recognition.unstreamed_page_events() {
                emit(&event);
            }
        }
    } else if let Some(path) = args.output.as_deref() {
        // Result already went to the file; don't also echo it to stdout. Confirm
        // on stderr so stdout stays empty/clean for any wrapping pipeline.
        let figs = if figures.is_empty() {
            String::new()
        } else {
            format!(", {} figure(s)", figures.len())
        };
        eprintln!("[focr] wrote {} ({}{figs})", path.display(), shape.name());
    } else if args.json {
        let mut value = recognition.to_json(&figures, args.raw);
        extras.merge_into(&mut value);
        emit(&value);
    } else {
        println!("{}", recognition.text(args.raw));
    }
    // The pages are out; a partial run now fails with exit 5.
    partial.map_or(Ok(()), Err)
}

/// What a JSON result carries beside the recognition itself.
#[derive(Clone, Copy, Default)]
struct RunExtras<'a> {
    finish_reason: Option<native_engine::FinishReason>,
    music: Option<&'a native_engine::MusicPageMeta>,
    chart: Option<&'a native_engine::ChartPageMeta>,
    warnings: &'a [native_engine::RunWarning],
    model: Option<&'a native_engine::ModelIdentity>,
}

impl RunExtras<'_> {
    fn merge_into(self, value: &mut serde_json::Value) {
        if let Some(reason) = self.finish_reason {
            value["finish_reason"] = reason.as_str().into();
        }
        if let Some(meta) = self.music {
            value["staves"] = music_meta_to_json(meta);
            value["warnings"] = music_warnings_to_json(meta);
        }
        if let Some(meta) = self.chart {
            value["chart"] = chart_meta_to_json(meta);
        }
        merge_run_warnings(value, self.warnings);
        if let Some(model) = self.model {
            model.merge_into(value);
        }
    }
}

/// The JSON `chart` object for a OneChart run (bd-a7zs): the number head, and
/// the verdict on the text, null when the text gave no values to check. Absent
/// on every other run, and present whether or not the run warned.
fn chart_meta_to_json(meta: &native_engine::ChartPageMeta) -> serde_json::Value {
    serde_json::json!({
        "pred_locs": meta.pred_locs,
        "reliable_distance": meta.reliable_distance,
        "reliable": meta.reliable,
    })
}

/// Merge the run's decode warnings (U2-X2) into a `--json` value's
/// `warnings` array, after any music entries. No key is added when there are
/// none, so healthy runs keep their shape.
fn merge_run_warnings(value: &mut serde_json::Value, warnings: &[native_engine::RunWarning]) {
    if warnings.is_empty() {
        return;
    }
    let entries: Vec<serde_json::Value> = warnings
        .iter()
        .map(native_engine::RunWarning::to_json)
        .collect();
    match value
        .get_mut("warnings")
        .and_then(serde_json::Value::as_array_mut)
    {
        Some(existing) => existing.extend(entries),
        None => value["warnings"] = serde_json::Value::Array(entries),
    }
}

/// The human stderr line per decode warning (U2-X2).
fn print_run_warnings(warnings: &[native_engine::RunWarning]) {
    warnings
        .iter()
        .filter(|w| !printed_early(w))
        .for_each(print_run_warning);
}

/// Whether `warning` reached stderr before the decode: the model's admission
/// prints its `ignored_lever` warnings at load, and the run its `pull_hint`
/// and the page source its `ignored_files` warning before the model loads.
fn printed_early(warning: &native_engine::RunWarning) -> bool {
    matches!(
        warning.kind,
        "ignored_lever" | "ignored_files" | "pull_hint"
    )
}

/// One run warning's human stderr line.
fn print_run_warning(warning: &native_engine::RunWarning) {
    eprintln!("[focr] warning: {} — {}", warning.message, warning.recovery);
}

/// The `--json` `staves` array for a music run (bd-av64.2): one entry per
/// DETECTED staff in detection order — recognized staves as `status: "ok"`,
/// failed ones as `status: "skipped"` with the reason. Absent entirely for
/// non-music runs, so every existing consumer's shape is unchanged.
/// The `--json` `warnings` array for a music run (bd-av64.5): annotate-only
/// musical-sanity observations, machine-stable kinds. Absent for non-music
/// runs.
fn music_warnings_to_json(meta: &native_engine::MusicPageMeta) -> serde_json::Value {
    serde_json::Value::Array(
        meta.warnings
            .iter()
            .map(|w| {
                serde_json::json!({
                    "kind": w.kind,
                    "part": w.part,
                    "measure": w.measure,
                    "detail": w.detail,
                })
            })
            .collect(),
    )
}

fn music_meta_to_json(meta: &native_engine::MusicPageMeta) -> serde_json::Value {
    let mut entries: Vec<(usize, serde_json::Value)> = meta
        .staves
        .iter()
        .map(|(index, bbox)| {
            (
                *index,
                serde_json::json!({
                    "staff": index + 1,
                    "bbox": [bbox.0, bbox.1, bbox.2, bbox.3],
                    "status": "ok",
                }),
            )
        })
        .chain(meta.skips.iter().map(|skip| {
            (
                skip.index,
                serde_json::json!({
                    "staff": skip.index + 1,
                    "bbox": [skip.bbox.0, skip.bbox.1, skip.bbox.2, skip.bbox.3],
                    "status": "skipped",
                    "reason": skip.reason,
                }),
            )
        }))
        .collect();
    entries.sort_by_key(|(index, _)| *index);
    serde_json::Value::Array(entries.into_iter().map(|(_, v)| v).collect())
}

/// How a run reads its input, the key of the mode-default table (D25).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RunMode {
    /// `focr ocr <image>`.
    SinglePage,
    /// `focr ocr <pdf>`, page by page.
    PdfDocument,
    /// `focr ocr <dir>`, page by page.
    DirectoryDocument,
    /// `focr ocr <pdf|dir> --multi-page`.
    MultiPage,
    /// `focr ocr-batch`.
    Batch,
    /// `focr ocr-batch --multi-page`.
    BatchMultiPage,
    /// `focr pull` without a model, and the first-run download offer.
    Pull,
}

impl RunMode {
    /// The mode of a `focr ocr` run.
    fn of_ocr(request: &OcrRequest, is_document: bool) -> Self {
        if !is_document {
            Self::SinglePage
        } else if request.multi_page {
            Self::MultiPage
        } else if request.image.is_dir() {
            Self::DirectoryDocument
        } else {
            Self::PdfDocument
        }
    }

    fn as_str(self) -> &'static str {
        match self {
            Self::SinglePage => "single-page",
            Self::PdfDocument => "pdf",
            Self::DirectoryDocument => "directory",
            Self::MultiPage => "multi-page",
            Self::Batch => "ocr-batch",
            Self::BatchMultiPage => "ocr-batch --multi-page",
            Self::Pull => "pull",
        }
    }
}

/// The model each mode runs when neither `--model` nor `FOCR_MODEL_PATH`
/// names one (D25). Every entry is Unlimited-OCR v1 until a default gate
/// passes; U2-E5a and U2-E5b only edit this table.
const MODE_DEFAULTS: [(RunMode, &str); 7] = [
    (
        RunMode::SinglePage,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::PdfDocument,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::DirectoryDocument,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::MultiPage,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::Batch,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::BatchMultiPage,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
    (
        RunMode::Pull,
        native_engine::model_arch::UNLIMITED_OCR_V1_ID,
    ),
];

/// `table`'s model for `mode`; v1 when the table has no entry.
fn mode_default(table: &[(RunMode, &'static str)], mode: RunMode) -> &'static str {
    table
        .iter()
        .find(|(entry, _)| *entry == mode)
        .map_or(native_engine::model_arch::UNLIMITED_OCR_V1_ID, |(_, id)| id)
}

/// Where a run's model comes from (D25): `--model` > `FOCR_MODEL_PATH` >
/// the mode default > v1.
#[derive(Debug, PartialEq, Eq)]
enum ModelChoice {
    /// `--model` or `FOCR_MODEL_PATH` names the model; resolution is unchanged.
    Named,
    /// The mode default is v1: the engine's own default resolution.
    V1Default,
    /// The mode default, installed: the run resolves its registry id.
    ModeDefault(&'static str),
    /// The mode default is not installed, so v1 serves with a pull hint.
    MissingDefault(&'static str),
}

/// Choose a run's model. `named` is whether `--model` or `FOCR_MODEL_PATH`
/// gave one; `installed` is asked only about a non-v1 default.
fn choose_model(
    named: bool,
    default_id: &'static str,
    installed: impl FnOnce(&str) -> bool,
) -> ModelChoice {
    if named {
        ModelChoice::Named
    } else if default_id == native_engine::model_arch::UNLIMITED_OCR_V1_ID {
        ModelChoice::V1Default
    } else if installed(default_id) {
        ModelChoice::ModeDefault(default_id)
    } else {
        ModelChoice::MissingDefault(default_id)
    }
}

/// Whether the model `id` names is installed: the registry id resolves, and
/// the bounded header probe finds that model there.
fn model_installed(id: &str) -> bool {
    native_engine::model_id_at(Path::new(id)) == Some(id)
}

/// Whether `FOCR_MODEL_PATH` names the run's model, exactly as
/// [`OcrEngine::model_path`] reads it.
fn model_path_env_set() -> bool {
    std::env::var_os(crate::MODEL_PATH_ENV).is_some()
}

/// The run's model id when that model splits a document into pages exactly
/// (a page contract, as Unlimited-OCR-2's, U2-E3), by the bounded header
/// probe of the model `--model` names, else `FOCR_MODEL_PATH` or the default.
/// `None` when the model is not installed or merges pages as v1 does.
fn paged_model_id(request: &OcrRequest) -> Option<&'static str> {
    let path = request.model.clone().unwrap_or_else(OcrEngine::model_path);
    let id = native_engine::model_id_at(&path)?;
    native_engine::model_arch::arch_by_id(id)?
        .decode_contract()
        .pages
        .map(|_| id)
}

/// Apply the mode default to `model` (D25): an installed non-v1 default
/// becomes the run's model; a missing one leaves v1 serving and returns the
/// `pull_hint` warning to report once.
fn apply_mode_default(
    model: &mut Option<PathBuf>,
    mode: RunMode,
    table: &[(RunMode, &'static str)],
) -> Option<native_engine::RunWarning> {
    let named = model.is_some() || model_path_env_set();
    match choose_model(named, mode_default(table, mode), model_installed) {
        ModelChoice::Named | ModelChoice::V1Default => None,
        ModelChoice::ModeDefault(id) => {
            *model = Some(PathBuf::from(id));
            None
        }
        ModelChoice::MissingDefault(id) => Some(pull_hint(mode, id)),
    }
}

/// The `pull_hint` warning for a mode whose default `id` is not installed.
fn pull_hint(mode: RunMode, id: &'static str) -> native_engine::RunWarning {
    let mut fields = serde_json::Map::new();
    fields.insert("model_id".into(), id.into());
    fields.insert("mode".into(), mode.as_str().into());
    native_engine::RunWarning {
        kind: "pull_hint",
        message: format!(
            "the {} default is {id}, which is not installed; {} served this run (`focr pull \
             {id}` installs it)",
            mode.as_str(),
            native_engine::model_arch::UNLIMITED_OCR_V1_ID
        ),
        recovery: native_engine::warning_recovery(native_engine::WarningKind::PullHint),
        fields,
    }
}

/// The model the first-run download offer names (D25): the bare-`focr pull`
/// default, when `manifest` carries a compatible pull of it.
fn first_run_offer(
    table: &[(RunMode, &'static str)],
    manifest: &dist::Manifest,
) -> Option<&'static str> {
    let id = mode_default(table, RunMode::Pull);
    let available = !pull_availability(Some(manifest), id).compatible.is_empty();
    available.then_some(id)
}

/// Try to serve an eligible single-image recognition from the resident
/// warm-model daemon (GH #9). `Ok(None)` = run inline (never an error).
///
/// Eligibility: single non-PDF image, no figure extraction (both enforced by
/// the caller's match arm), resident not disabled, no `--threads` (the daemon
/// keeps the budget it started with) and no timing trace (its stderr rows would
/// print invisibly in the daemon). The model spec is resolved client-side first,
/// so an unresolvable model keeps the inline path's download-offer / exit-3
/// contract byte-for-byte.
fn resident_recognition(
    args: &OcrArgs,
    request: &OcrRequest,
    stages: Option<&robot::StageClock>,
) -> FocrResult<Option<crate::resident::ResidentReply>> {
    if !crate::resident::enabled(request.no_resident)
        || args.request.threads.is_some()
        || crate::timing_enabled()
    {
        return Ok(None);
    }
    let spec = request
        .model
        .clone()
        .unwrap_or_else(crate::OcrEngine::model_path);
    let Ok(model) = native_engine::OcrModel::resolve_model(&spec) else {
        return Ok(None);
    };
    let on_stage = |name: &str, budget: Option<std::time::Duration>| {
        if let Some(stages) = stages {
            emit(&stages.entered(name, budget));
        }
    };
    crate::resident::try_recognize(&crate::resident::ResidentRequest {
        image: &request.image,
        model,
        decode: decode_overrides_from(request),
        preprocess: preprocess_overrides_from(request),
        format: request.format,
        square_pad: request.square_pad,
        region: request.region,
        question: request.question.as_deref(),
        on_stage: Some(&on_stage),
    })
}

/// Run one recognition, transparently offering the first-run model download once
/// and retrying against the freshly-fetched model.
///
/// `recog(model)` performs a full recognition: `Some(path)` pins that artifact,
/// `None` uses the engine default. The download offer fires only when the user
/// did NOT pin an explicit `--model`, we are on an interactive TTY, and not in
/// robot mode (robots never prompt/fetch — they get the clean model-not-found
/// error + pull hint). Both the single-image and PDF paths funnel through here so
/// model resolution and the auto-download behave identically.
fn recognize_with_autodownload<T, F>(
    request: &OcrRequest,
    robot_mode: bool,
    recog: F,
) -> FocrResult<T>
where
    F: Fn(Option<&Path>) -> FocrResult<T>,
{
    match recog(request.model.as_deref()) {
        Ok(md) => Ok(md),
        Err(FocrError::ModelNotFound(msg)) => {
            if request.model.is_none() && !robot_mode && is_interactive() {
                // A failed recognition retires its progress renderer without
                // waiting. Synchronize the generic terminal line before the
                // interactive download prompt is allowed to render.
                progress::clear_active_line();
                match offer_first_run_download()? {
                    Some(outcome) => recog(Some(&outcome.focrq_path)),
                    None => Err(FocrError::ModelNotFound(with_pull_hint(&msg, None))),
                }
            } else {
                Err(FocrError::ModelNotFound(with_pull_hint(
                    &msg,
                    request.model.as_deref(),
                )))
            }
        }
        Err(e) => Err(e),
    }
}

/// Tall-capture strip recognition (GH #15): cut an extreme-aspect image into
/// smart-cut horizontal strips (see [`crate::tall`] for the geometry), OCR
/// each strip, and merge the documents (markdown in reading order, layout
/// boxes translated back into source-image pixel space). Model resolution —
/// including the first-run download offer — behaves exactly like the
/// one-pass path because the strip loop runs inside
/// [`recognize_with_autodownload`].
fn recognize_tall_capture(
    engine: &OcrEngine,
    request: &OcrRequest,
    robot_mode: bool,
    width: u32,
    height: u32,
) -> FocrResult<native_engine::RecognizedDocument> {
    let img = image::open(&request.image).map_err(|e| {
        FocrError::InputDecode(format!("failed to decode {}: {e}", request.image.display()))
    })?;
    let profile = crate::tall::ink_profile(&img);
    let plan = crate::tall::plan_strips(width, height, &profile);
    crate::native_engine::timing_log(&format!(
        "tall capture {}x{} (aspect {:.2}): OCR as {} strips",
        width,
        height,
        f64::from(height) / f64::from(width),
        plan.len()
    ));
    let strips = crate::tall::cut_strips(&img, &plan);
    recognize_with_autodownload(request, robot_mode, |model| {
        let mut parts = Vec::with_capacity(strips.len());
        for (strip, bounds) in strips.iter().zip(&plan) {
            let doc = match model {
                Some(m) => engine.recognize_dynamic_with_layout_model(m, strip.clone())?,
                None => engine.recognize_dynamic_with_layout(strip.clone())?,
            };
            parts.push((doc, bounds.top));
        }
        Ok(crate::tall::merge_documents(parts))
    })
}

/// The page source of a document input (a PDF or a directory of page
/// images), narrowed to `--pages` (the grammar of
/// [`select_pages`](crate::page_source::select_pages),
/// shared with the library, the iOS app and the browser playground) and
/// splitting spreads under `--split-spreads` (bd-av64.11).
///
/// # Errors
/// The source's open error, or [`FocrError::Usage`] for a bad `--pages`
/// spec (naming the document's page count).
fn open_page_source(request: &OcrRequest) -> FocrResult<PageSource> {
    Ok(PageSource::open(&request.image)?
        .select(request.pages.as_deref())?
        .split_spreads(request.split_spreads))
}

/// The page source for one recognition attempt: the one opened up front, or
/// a fresh one when a first-run download retries the attempt, since the
/// first attempt consumed its own.
fn attempt_source(
    opened: &std::cell::Cell<Option<PageSource>>,
    request: &OcrRequest,
) -> FocrResult<PageSource> {
    match opened.take() {
        Some(source) => Ok(source),
        None => open_page_source(request),
    }
}

/// How a skipped page is named on stderr: "PDF page 3", or "page 3" of a
/// directory.
fn page_noun(request: &OcrRequest) -> &'static str {
    if request.image.is_dir() {
        "page"
    } else {
        "PDF page"
    }
}

/// How a document run reports its pages.
#[derive(Debug, Clone, Copy)]
struct DocumentRun {
    /// NDJSON `page` events, not stderr lines.
    robot_mode: bool,
    /// The human-mode progress bar (GH #2).
    show_progress: bool,
    /// The model's id when it splits pages exactly (U2-E3): its `page`
    /// events name the source page.
    paged_model: Option<&'static str>,
}

/// Surface a skipped page where the caller reads: a robot `page` event with
/// `status: "skipped"`, else a human stderr line that does not tear `bar`.
fn report_skipped_page(
    run: DocumentRun,
    bar: &progress::Progress,
    noun: &str,
    page: usize,
    err: &FocrError,
) {
    if run.robot_mode {
        emit(&match run.paged_model {
            Some(model_id) => robot::document_page_skipped_event(page, err, model_id),
            None => robot::page_skipped_event(page, err),
        });
    } else {
        bar.note(&format!("[focr] {noun} {page} skipped: {err}"));
    }
}

/// A per-page run's observer: its progress bar, where a spread's two halves
/// share one step, and each skip on the stream the caller reads, so a machine
/// consumer can tell the document is missing pages.
fn page_progress<'a>(
    run: DocumentRun,
    bar: &'a progress::Progress,
    noun: &'a str,
    page_count: usize,
) -> impl FnMut(PageEvent<'_>) + 'a {
    let finished = |page: PageStep| {
        if page.half != Some(Half::Left) {
            bar.complete_item();
        }
    };
    move |event| match event {
        PageEvent::Started(page) => {
            if page.half != Some(Half::Right) {
                bar.start_item(format!("page {}/{page_count}", page.source_page));
            }
        }
        PageEvent::Done(page) => finished(page),
        PageEvent::Skipped(page, error) => {
            report_skipped_page(run, bar, noun, page.source_page, error);
            finished(page);
        }
    }
}

/// One successfully-OCR'd document page's structured layout (for the JSON
/// output).
struct DocumentPageLayout {
    /// 1-based page number in the source document.
    page: usize,
    /// `Some("left"|"right")` when this entry is one half of a split spread.
    half: Option<&'static str>,
    /// The page's decode as the model wrote it.
    raw: String,
    /// The page's parsed layout spans (labels + pixel bounding boxes).
    layout: Vec<crate::native_engine::LayoutSpan>,
}

/// What a document's run adds to its report (U2-D4, U2-D5).
#[derive(Debug, Default)]
struct DocumentOutcome {
    /// The run page decoding started at, when the run picked up an
    /// interrupted one.
    resumed_from: Option<usize>,
    /// The warnings of the run rather than its decode.
    warnings: Vec<native_engine::RunWarning>,
    /// An Unlimited-OCR-2 document's counts, for `run_complete`.
    counts: Option<DocumentCounts>,
}

/// How an Unlimited-OCR-2 document went (U2-D5).
#[derive(Debug)]
struct DocumentCounts {
    pages_out: usize,
    pages_skipped: usize,
    windows: usize,
    extra_markers: usize,
}

/// Where a windowed document keeps its journal and checkpoint (U2-D4): beside
/// `output`, or for a stdout run under `<cache_root>/document-runs/`, in the
/// directory its key names, so the same command finds it again. `None` when
/// there is neither.
fn document_run_files(
    request: &OcrRequest,
    output: Option<&std::path::Path>,
) -> FocrResult<Option<native_engine::checkpoint::RunFiles>> {
    use native_engine::checkpoint::{INPUT_FIELD, ResumeKey, RunFiles, SELECTION_FIELD};
    let key = ResumeKey::new()
        .with(
            INPUT_FIELD,
            crate::page_source::input_sha256(&request.image)?,
        )
        .with(
            SELECTION_FIELD,
            format!(
                "pages={} split_spreads={}",
                request.pages.as_deref().unwrap_or("all"),
                request.split_spreads
            ),
        )
        .with(
            "decode_flags",
            format!("{:?}", decode_overrides_from(request)),
        );
    let files = match (output, crate::dist::cache_root()) {
        (Some(path), _) => RunFiles::beside(path, key),
        (None, Some(root)) => RunFiles::keyed(&root.join("document-runs"), key),
        (None, None) => return Ok(None),
    };
    Ok(Some(files.with_command(resume_command())))
}

/// This process's command line, quoted for a POSIX shell, for `focr doctor`
/// to report: re-running it continues the document.
fn resume_command() -> String {
    let quoted = std::env::args().skip(1).map(|arg| {
        let plain = !arg.is_empty()
            && arg
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || "-_./=:,@%+".contains(c));
        if plain {
            arg
        } else {
            format!("'{}'", arg.replace('\'', r"'\''"))
        }
    });
    std::iter::once("focr".to_owned())
        .chain(quoted)
        .collect::<Vec<_>>()
        .join(" ")
}

/// `error` with what a later run continues from, when a document stopped.
fn with_resume_fields(
    mut error: FocrError,
    files: Option<&native_engine::checkpoint::RunFiles>,
    resumed_from: Option<usize>,
) -> FocrError {
    if let FocrError::Partial(partial) = &mut error {
        partial.resumed_from = resumed_from;
        partial.checkpoint = files
            .filter(|files| files.has_checkpoint())
            .map(|files| files.checkpoint.display().to_string());
    }
    error
}

/// A document's JSON `pages`.
enum DocumentPageList {
    /// Page-by-page passes: each decoded page's layout.
    Layouts(Vec<DocumentPageLayout>),
    /// One cross-page pass (U2-E3): the pages it read, empty when v1 merged
    /// them.
    Read(Vec<native_engine::PageResult>),
}

/// A recognized document: the concatenated markdown plus per-page layout for
/// the pages that decoded (skipped pages are absent from `pages`, as from the
/// markdown).
struct DocumentRecognition {
    markdown: String,
    /// The decode as the model wrote it, pages joined as the markdown's are.
    raw: String,
    pages: DocumentPageList,
}

/// `--multi-page` (bd-2z0y): a cross-page parse of the selected pages of a
/// PDF or a directory of page images (the Unlimited-OCR `infer_multi`
/// contract, bd-1gv.25) — page N attends to the pages before it; the output
/// is one markdown with `<PAGE>` separators. v1 reads the document in one
/// pass; Unlimited-OCR-2 reads it in windows of 10 pages (U2-D1b), one pass
/// when it fits one. The JSON `pages` are the pages the parse read (U2-E3):
/// every page for a model that splits pages exactly, and for v1 only when
/// its text holds one body per page; otherwise `pages: []`, which the run's
/// `v1_page_merge` or `v1_extra_pages` warning explains.
///
/// The pages are read lazily (U2-D0): the forward stage rasterizes each one,
/// preprocesses it and drops the raster before reading the next, so a long
/// book never holds every raster (a windowed parse reads each window's pages
/// as the window starts). A page that fails to RASTER is skipped with the
/// same surfaced page event as the per-page path (the parse runs over the
/// pages that rendered); decode errors are whole-document by construction.
///
/// With `figures` (a page-splitting model's run only), each page with figure
/// boxes is rasterized again ([`PageSource::fetch`]) after the parse, when
/// no other raster is held. Its figures are cropped, written as
/// `page{N}[l|r]_figure_{M}` and referenced from its markdown, once, outside
/// the retryable parse.
///
/// With `files` (a windowed model's run), each window's pages and boundary
/// are written there, and the run continues an interrupted one it finds
/// (U2-D4): `--resume=recompute` from its completed pages, otherwise exactly,
/// or not at all when its settings differ.
fn recognize_document_multi_page(
    engine: &OcrEngine,
    request: &OcrRequest,
    source: PageSource,
    run: DocumentRun,
    figures: Option<&FigurePlan>,
    files: Option<&native_engine::checkpoint::RunFiles>,
) -> FocrResult<(DocumentRecognition, Vec<WrittenFigure>, DocumentOutcome)> {
    let DocumentRun {
        robot_mode,
        show_progress,
        paged_model,
    } = run;
    let opened = std::cell::Cell::new(Some(source));
    let noun = page_noun(request);
    let recompute = request.resume == Some(ResumeMode::Recompute);
    let mut options = match files {
        Some(files) => {
            if files.journal.exists() {
                eprintln!(
                    "[focr] {} the interrupted run in {}",
                    if recompute {
                        "recomputing"
                    } else {
                        "continuing"
                    },
                    files.journal.display()
                );
            }
            native_engine::DocumentOptions::default()
                .resume(if recompute {
                    native_engine::ResumePolicy::Recompute
                } else {
                    native_engine::ResumePolicy::IfMatching
                })
                .run(files.clone())
        }
        None => native_engine::DocumentOptions::default(),
    };
    options.page_window = request.page_window;
    options.reread_capped = native_engine::reread_capped_requested();
    let document = recognize_with_autodownload(request, robot_mode, |model| {
        let source = attempt_source(&opened, request)?;
        let model_path = model
            .map(std::path::Path::to_path_buf)
            .unwrap_or_else(OcrEngine::model_path);
        let (page_count, selected) = (source.source_len(), source.len());
        // Human-mode progress (GH #2): for v1 two bars in turn, `raster` while
        // the pages are read, then `ocr` over the pages that rendered while
        // the document decodes. A model that reads pages between its window
        // decodes has the `ocr` bar alone, so the line stays on the window
        // that ended instead of on the last page read. Stderr-only;
        // self-disabled off-TTY.
        let decode_bar =
            std::sync::Arc::new(progress::Progress::new("ocr", selected, show_progress));
        let raster_bar = paged_model
            .is_none()
            .then(|| progress::Progress::new("raster", selected, show_progress));
        let on_item: Box<dyn FnMut(&PageItem) + Send> = {
            let decode_bar = std::sync::Arc::clone(&decode_bar);
            let mut failed = 0usize;
            Box::new(move |item: &PageItem| {
                let status = format!("page {}/{page_count}", item.source_page);
                match &raster_bar {
                    Some(bar) => bar.start_item(status),
                    None => decode_bar.reading_item(format!("read {status}")),
                }
                if let Err(e) = &item.raster {
                    failed += 1;
                    let bar = raster_bar.as_ref().unwrap_or(&decode_bar);
                    report_skipped_page(run, bar, noun, item.source_page, e);
                }
                if let Some(bar) = &raster_bar
                    && item.half != Some(Half::Left)
                {
                    bar.complete_item();
                }
                // Counted from the walk, which a resumed run joins part way.
                let rendered = item.index + 1 - failed;
                let walked = item.walk.next - usize::from(item.walk.held);
                if walked == selected {
                    decode_bar.set_total(rendered);
                    if let Some(bar) = &raster_bar {
                        bar.finish();
                        if rendered > 0 {
                            decode_bar.start_item(format!("page 1/{rendered}"));
                        }
                    }
                }
            })
        };
        // Robot mode streams a `page` event per crossed <PAGE> boundary
        // (bd-2z0y), naming the source page when the model splits pages
        // exactly (U2-E3), and a `window` event as each window ends (U2-D5);
        // the terminal run_complete still carries the assembled markdown. A
        // human TTY advances the decode bar instead; off-TTY (or
        // FOCR_NO_PROGRESS) the pass streams nothing, and its markdown is the
        // same either way.
        let on_event: Option<crate::DocumentSink> = if robot_mode {
            let mut eta = progress::PageEta::default();
            Some(Box::new(move |event: &crate::DocumentEvent<'_>| {
                emit(&match event {
                    crate::DocumentEvent::Page(streamed) => match streamed.page {
                        Some(page) => robot::document_page_decoded_event(page, streamed.body),
                        None => robot::page_decoded_event(streamed.index, streamed.body),
                    },
                    crate::DocumentEvent::Window(window) => {
                        eta.add_window(window.pages.len(), window.elapsed_ms);
                        let left = selected.saturating_sub(window.pages.end);
                        robot::window_event(window, eta.remaining_ms(left))
                    }
                });
            }))
        } else if decode_bar.is_enabled() {
            Some(decode_bar.document_sink())
        } else {
            None
        };
        let out = engine.recognize_document(&model_path, source, &options, on_item, on_event);
        if out.is_ok() {
            decode_bar.finish();
        } else {
            decode_bar.retire();
        }
        out
    })?;
    // The run's finish_reason and decode warnings come from the engine's
    // decode report, as for every other run; its skipped pages were reported
    // as they were read.
    let counts = paged_model.map(|_| DocumentCounts {
        pages_out: document.pages_out,
        pages_skipped: document.skipped.len(),
        windows: document.windows.len(),
        extra_markers: document.extra_markers,
    });
    let native_engine::DocumentResult {
        mut markdown,
        raw,
        mut pages,
        resumed_from,
        warnings,
        ..
    } = document;
    let written = match figures {
        Some(plan) => write_page_figures(request, &mut pages, plan)?,
        None => Vec::new(),
    };
    if !written.is_empty() {
        markdown = native_engine::postprocess::join_page_texts(pages.iter().map(|p| &p.text));
    }
    Ok((
        DocumentRecognition {
            markdown,
            raw,
            pages: DocumentPageList::Read(pages),
        },
        written,
        DocumentOutcome {
            resumed_from,
            warnings: warnings
                .into_iter()
                .filter(|w| {
                    matches!(
                        w.kind,
                        "v2_page_reread" | "resume_recompute" | "checkpoint_failed"
                    )
                })
                .collect(),
            counts,
        },
    ))
}

/// Write the figures of a document's `pages` (U2-E3): each page with figure
/// boxes is rasterized again from the run's source ([`PageSource::fetch`]),
/// its figures are cropped and written as `page{N}[l|r]_figure_{M}`, and its
/// markdown is rewritten to reference them. Opens the source only when a
/// page has a figure.
///
/// # Errors
/// The source's open or a page's re-fetch error, or a write error.
fn write_page_figures(
    request: &OcrRequest,
    pages: &mut [native_engine::PageResult],
    plan: &FigurePlan,
) -> FocrResult<Vec<WrittenFigure>> {
    if pages.iter().all(|p| p.figures.is_empty()) {
        return Ok(Vec::new());
    }
    let rasters = open_page_source(request)?;
    let mut writer = plan.writer();
    for page in pages.iter_mut().filter(|p| !p.figures.is_empty()) {
        let raster = rasters.fetch(page.source_page, page.half)?;
        let crops = native_engine::crop_figure_refs(&page.figures, &raster);
        page.text = writer.process_page(page.source_page, page.half, &page.text, crops)?;
    }
    Ok(writer.into_written())
}

/// Recognize every page of a PDF or a directory of page images, concatenating
/// the per-page markdown into one document (successful pages joined by a blank
/// line) and collecting each decoded page's layout spans for the JSON output.
///
/// Each page is read from the [`PageSource`] — a PDF page rasterized in-memory
/// by [`pdf`], no out-of-band `pdftoppm` — and fed through the identical OCR
/// pipeline a PNG takes. Pages render lazily, one at a time, so a long book
/// never holds every raster at once.
///
/// **Per-page resilience (mirrors the `ocr-batch` path):** a page that cannot be
/// rendered or recognized — an unsupported codec (`JPXDecode`/`JBIG2Decode`), a
/// vector/text page, a per-page decode or timeout error — is SKIPPED, so one bad
/// page never discards (nor wastes the compute already spent on) the OCR of every
/// other page. The skip is surfaced so it is never silent: a structured `page`
/// NDJSON event ([`robot::page_skipped_event`]) in robot mode, else a human stderr
/// warning. The **whole-run** conditions are propagated
/// immediately instead of being swallowed per-page:
/// * [`FocrError::ModelNotFound`] — lets [`recognize_with_autodownload`] offer the
///   first-run download and retry the whole document;
/// * [`FocrError::Cancelled`] — a Ctrl+C / cooperative cancel must abort the run,
///   not log a skip per remaining page and keep churning;
/// * [`FocrError::FormatMismatch`] — a bad/incompatible model artifact fails every
///   page identically, so surface it once rather than N times.
///
/// If NOT ONE page decodes, the first per-page failure is surfaced as a clean
/// error instead of an empty document.
fn recognize_document_pages(
    engine: &OcrEngine,
    request: &OcrRequest,
    source: PageSource,
    run: DocumentRun,
) -> FocrResult<DocumentRecognition> {
    let DocumentRun {
        robot_mode,
        show_progress,
        ..
    } = run;
    let opened = std::cell::Cell::new(Some(source));
    let noun = page_noun(request);
    recognize_with_autodownload(request, robot_mode, |model| {
        let mut source = attempt_source(&opened, request)?;
        let page_count = source.source_len();
        // Per-page progress bar (GH #2): stderr-only, never in robot/--json
        // mode, self-disabled off-TTY (see `progress`). Built per ATTEMPT so a
        // ModelNotFound retires it without waiting; the autodownload wrapper
        // synchronizes the terminal line before its first-run prompt renders.
        let bar = progress::Progress::new("ocr", source.len(), show_progress);
        let read = source.read_pages(
            |image| match model {
                Some(m) => engine.recognize_dynamic_with_layout_model(m, image),
                None => engine.recognize_dynamic_with_layout(image),
            },
            &mut page_progress(run, &bar, noun, page_count),
        )?;
        bar.finish();
        Ok(DocumentRecognition {
            markdown: read.markdown(),
            raw: read.raw(),
            pages: DocumentPageList::Layouts(
                read.pages
                    .into_iter()
                    .map(|page| DocumentPageLayout {
                        page: page.source_page,
                        half: page.half.map(Half::as_str),
                        raw: page.value.raw,
                        layout: page.value.layout,
                    })
                    .collect(),
            ),
        })
    })
}

/// [`recognize_document_pages`] + figure extraction — the `--extract-figures`
/// document path. Same per-page resilience and whole-run abort rules, but each
/// page is recognized WITH its figure crops. The recognition pass is retryable
/// (first-run model download), so it does NO file I/O — it only collects each
/// decodable page's number, doc, and crops; the figures are written ONCE
/// afterward and every page's markdown references are rewritten to the saved
/// files (page-namespaced so per-page `images/0.jpg` tokens never collide
/// across pages).
fn recognize_document_pages_with_figures(
    engine: &OcrEngine,
    request: &OcrRequest,
    source: PageSource,
    run: DocumentRun,
    plan: &FigurePlan,
) -> FocrResult<(DocumentRecognition, Vec<WrittenFigure>)> {
    let DocumentRun {
        robot_mode,
        show_progress,
        ..
    } = run;
    let opened = std::cell::Cell::new(Some(source));
    let noun = page_noun(request);
    let read = recognize_with_autodownload(request, robot_mode, |model| {
        let mut source = attempt_source(&opened, request)?;
        let page_count = source.source_len();
        // Same per-page progress bar as `recognize_document_pages` (GH #2):
        // stderr-only, disabled in robot mode and off-TTY, per-attempt lifetime.
        // `--split-spreads` is refused with figures, so every item is a page.
        let bar = progress::Progress::new("ocr", source.len(), show_progress);
        let read = source.read_pages(
            |image| match model {
                Some(m) => engine.recognize_dynamic_with_figures_model(m, image),
                None => engine.recognize_dynamic_with_figures(image),
            },
            &mut page_progress(run, &bar, noun, page_count),
        )?;
        bar.finish();
        Ok(read)
    })?;

    // Write pass — runs ONCE: write each page's figures and rewrite its markdown,
    // then concatenate exactly as `recognize_document_pages` does (trim_end +
    // blank-line join).
    let mut writer = plan.writer();
    let mut document = String::new();
    let mut raws: Vec<String> = Vec::new();
    let mut page_layouts: Vec<DocumentPageLayout> = Vec::new();
    for (i, page) in read.pages.into_iter().enumerate() {
        let (doc, figs) = page.value;
        let md = writer.process_page(page.source_page, None, &doc.markdown, figs)?;
        if i > 0 {
            document.push_str("\n\n");
        }
        document.push_str(md.trim_end());
        raws.push(doc.raw.clone());
        page_layouts.push(DocumentPageLayout {
            page: page.source_page,
            half: None,
            raw: doc.raw,
            layout: doc.layout,
        });
    }
    Ok((
        DocumentRecognition {
            markdown: document,
            raw: raws.join("\n\n"),
            pages: DocumentPageList::Layouts(page_layouts),
        },
        writer.into_written(),
    ))
}

/// How one `ocr-batch` image's decode ended, in the terms `focr ocr` reports
/// for a run (bd-hntz).
#[derive(Default)]
struct PageEnd {
    finish_reason: Option<native_engine::FinishReason>,
    warnings: Vec<native_engine::RunWarning>,
    chart: Option<native_engine::ChartPageMeta>,
    /// The page stopped early: its text is out, and it failed all the same.
    partial: Option<FocrError>,
}

impl PageEnd {
    /// Consume what `engine`'s last decode recorded.
    fn take(engine: &OcrEngine) -> Self {
        Self::from_report(
            engine.take_last_decode_report(),
            engine.take_chart_page_meta(),
            engine,
        )
    }

    /// How a page ended, from its decode `report` and `chart` page; the
    /// spine driver has one of each per image (bd-iv8d, bd-v37k).
    fn from_report(
        report: Option<native_engine::DecodeReport>,
        chart: Option<native_engine::ChartPageMeta>,
        engine: &OcrEngine,
    ) -> Self {
        let mut warnings = report
            .as_ref()
            .map(native_engine::decode_warnings)
            .unwrap_or_default();
        warnings.extend(chart.as_ref().and_then(native_engine::chart_warning));
        let partial = report
            .as_ref()
            .zip(engine.loaded_model_identity().as_ref())
            .and_then(|(report, model)| native_engine::partial_output(report, &warnings, model));
        Self {
            finish_reason: report
                .as_ref()
                .map(native_engine::DecodeReport::run_finish_reason),
            warnings,
            chart,
            partial,
        }
    }
}

/// Emit ONE batch image's outcome in the shared `ocr-batch` shape — a JSON object
/// pushed to `results` (with `--json`) or the `[focr] … =====` markdown block on
/// stdout/stderr, or under `--output-dir` the line naming its `saved` file.
/// Factored so the sequential and spine drivers render byte-for-byte
/// identically; only the source of `outcome` and `end` differs between them.
/// Returns the image's failure, once reported.
fn emit_batch_result(
    json: bool,
    image: &std::path::Path,
    secs: f64,
    outcome: FocrResult<String>,
    saved: Option<&Path>,
    end: PageEnd,
    results: &mut Vec<serde_json::Value>,
) -> Option<FocrError> {
    match outcome {
        Ok(markdown) => {
            if json {
                let mut result = serde_json::json!({
                    "image": image.display().to_string(),
                    "ok": end.partial.is_none(),
                    "seconds": secs,
                    "markdown": markdown,
                });
                if let Some(saved) = saved {
                    result["output"] = saved.display().to_string().into();
                }
                if let Some(err) = &end.partial {
                    result["error"] = err.to_string().into();
                }
                RunExtras {
                    finish_reason: end.finish_reason,
                    chart: end.chart.as_ref(),
                    warnings: &end.warnings,
                    ..RunExtras::default()
                }
                .merge_into(&mut result);
                results.push(result);
            } else {
                print_run_warnings(&end.warnings);
                if let Some(saved) = saved {
                    eprintln!(
                        "[focr] {} ({secs:.2}s) -> {}",
                        image.display(),
                        saved.display()
                    );
                } else {
                    eprintln!("[focr] {} ({secs:.2}s)", image.display());
                    println!("===== {} =====", image.display());
                    println!("{markdown}");
                }
            }
            end.partial
        }
        Err(err) => {
            if json {
                results.push(serde_json::json!({
                    "image": image.display().to_string(),
                    "ok": false,
                    "seconds": secs,
                    "error": err.to_string(),
                }));
            } else {
                eprintln!("[focr] {} FAILED ({secs:.2}s): {err}", image.display());
            }
            Some(err)
        }
    }
}

/// The batch's inputs: every image named, then each line of `--inputs-from`.
fn batch_inputs(args: &OcrBatchArgs) -> FocrResult<Vec<PathBuf>> {
    let mut images = args.images.clone();
    if let Some(list) = &args.inputs_from {
        let text = if list == Path::new("-") {
            std::io::read_to_string(std::io::stdin())
        } else {
            std::fs::read_to_string(list)
        }
        .map_err(|e| FocrError::Usage(format!("--inputs-from {}: {e}", list.display())))?;
        images.extend(parse_input_list(&text));
    }
    if images.is_empty() {
        return Err(FocrError::Usage(
            "ocr-batch has no images to read: --inputs-from listed none".into(),
        ));
    }
    Ok(images)
}

/// An `--inputs-from` list's paths: each line as written (a leading UTF-8 BOM
/// is ignored), blank lines skipped.
fn parse_input_list(text: &str) -> impl Iterator<Item = PathBuf> + '_ {
    text.strip_prefix('\u{feff}')
        .unwrap_or(text)
        .lines()
        .filter(|line| !line.is_empty())
        .map(PathBuf::from)
}

/// Each image's `--output-dir` file, `DIR/<stem>.md`. Two images that would
/// write one file are refused, ignoring case: macOS and Windows disks do.
fn batch_output_paths(dir: &Path, images: &[PathBuf]) -> FocrResult<Vec<PathBuf>> {
    let mut seen: std::collections::HashMap<String, &Path> = std::collections::HashMap::new();
    images
        .iter()
        .map(|image| {
            let Some(stem) = image.file_stem() else {
                return Err(FocrError::Usage(format!(
                    "--output-dir names each file after its input, and {} has no file name",
                    image.display()
                )));
            };
            if let Some(first) = seen.insert(stem.to_string_lossy().to_lowercase(), image) {
                return Err(FocrError::Usage(format!(
                    "--output-dir would write {} and {} to one file: rename one, or run them \
                     separately",
                    first.display(),
                    image.display()
                )));
            }
            let mut name = stem.to_os_string();
            name.push(".md");
            Ok(dir.join(name))
        })
        .collect()
}

/// Save `markdown` where `--output-dir` puts this image, before the image is
/// reported as done.
fn save_batch_markdown(saved: Option<&Path>, markdown: &str) -> FocrResult<()> {
    let Some(path) = saved else {
        return Ok(());
    };
    std::fs::write(path, markdown).map_err(|e| {
        FocrError::Other(anyhow::anyhow!(
            "writing OCR output to {}: {e}",
            path.display()
        ))
    })
}

/// Load-once batch OCR: reuse one model across every image in the process. The
/// conservative quant recipe is the default. `--experimental-full-int8` arms
/// the legacy all-int8 cache only when both independent accuracy gates are also
/// enabled. With the continuous-batch spine armed (`FOCR_BATCH_SPINE`) all pages
/// decode together through the scheduler; otherwise the proven sequential
/// per-image loop runs.
fn run_ocr_batch(args: OcrBatchArgs) -> FocrResult<()> {
    if let Some(err) = forced_test_error()? {
        return Err(err);
    }
    apply_tuning(args.threads, args.timing)?;
    let images = batch_inputs(&args)?;
    let spine = !args.multi_page && native_engine::batch_scheduler::spine_enabled();
    if args.multi_page && (args.output_dir.is_some() || args.fail_fast) {
        return Err(FocrError::Usage(
            "--output-dir and --fail-fast work image by image, and --multi-page reads one \
             document: use -o on `focr ocr`, or drop --multi-page"
                .into(),
        ));
    }
    if spine && (args.progress_events.is_some() || args.fail_fast) {
        return Err(FocrError::Usage(
            "--progress-events and --fail-fast act as each image ends, and FOCR_BATCH_SPINE \
             decodes them together: unset it for this run"
                .into(),
        ));
    }
    let saved = match &args.output_dir {
        Some(dir) => {
            let paths = batch_output_paths(dir, &images)?;
            std::fs::create_dir_all(dir)
                .map_err(|e| FocrError::Usage(format!("--output-dir {}: {e}", dir.display())))?;
            paths.into_iter().map(Some).collect()
        }
        None => vec![None; images.len()],
    };
    let events = args
        .progress_events
        .as_deref()
        .map(BatchEvents::open)
        .transpose()?;
    let outcome = run_batch_images(&args, &images, &saved, spine, events.as_ref());
    if let Some(events) = &events {
        events.end(&outcome);
    }
    outcome
}

/// [`run_ocr_batch`]'s run over `images`, each `saved` to its `--output-dir`
/// file, reporting to `events`. An image that fails does not fail the batch
/// unless none was read (as a document's, D24) or `--fail-fast` is set.
fn run_batch_images(
    args: &OcrBatchArgs,
    images: &[PathBuf],
    saved: &[Option<PathBuf>],
    spine: bool,
    events: Option<&BatchEvents>,
) -> FocrResult<()> {
    if args.experimental_full_int8 {
        native_engine::force_int8_decode(true)?;
    }
    native_engine::validate_experimental_full_int8_decode()?;
    native_engine::validate_test_max_positions()?;
    let experimental_full_int8 = native_engine::experimental_full_int8_decode_requested();
    let decode_mode = if experimental_full_int8 {
        "experimental_full_int8"
    } else {
        "conservative_recipe"
    };
    // ocr-batch has no per-flag tuning surface, but the README-documented
    // FOCR_NO_REPEAT_NGRAM mitigation (int8 table-repetition) must work here
    // too (fresh-eyes fix — it previously reached only the clap env fallback
    // on `focr ocr`/`robot run` and was silently ignored by batch runs).
    if let Some(n) = std::env::var("FOCR_NO_REPEAT_NGRAM")
        .ok()
        .and_then(|v| v.trim().parse::<usize>().ok())
    {
        native_engine::set_decode_overrides(native_engine::DecodeOverrides {
            no_repeat_ngram: Some(n),
            ..Default::default()
        });
    }
    let engine = OcrEngine::new()?;
    let mut model = args.model.clone();
    // The mode default (D25), its pull hint reported once.
    let mode = if args.multi_page {
        RunMode::BatchMultiPage
    } else {
        RunMode::Batch
    };
    let pull_hint = apply_mode_default(&mut model, mode, &MODE_DEFAULTS);
    if let Some(hint) = &pull_hint {
        print_run_warning(hint);
    }
    let count = images.len();
    let total = std::time::Instant::now();
    let mut results: Vec<serde_json::Value> = Vec::with_capacity(count);
    // A model with a lever policy is admitted once here, so its refusal is
    // the run's exit code (U2-A7); held, it serves every image below.
    let _policed = native_engine::load_if_policed(
        &model.clone().unwrap_or_else(crate::OcrEngine::model_path),
    )?;
    if let Some(events) = events {
        let model_path = model.clone().unwrap_or_else(OcrEngine::model_path);
        events.start(&BatchRun {
            mode: if args.multi_page {
                BatchMode::Document
            } else {
                BatchMode::Images
            },
            total: count,
            threads: crate::thread_budget(),
            model_path: &model_path,
            model_id: native_engine::model_id_at(&model_path),
            backend: simd::effective_dense_route().tag(),
            decode_mode,
        });
    }

    if args.multi_page {
        // A cross-page document parse (bd-1gv.25): page N attends to the
        // pages before it (in its window, for Unlimited-OCR-2, U2-D1b);
        // output is one assembled markdown with <PAGE> separators. An image
        // that does not decode is left out of the parse and reported (D24);
        // the run fails only when none decodes.
        let model_path = model.clone().unwrap_or_else(OcrEngine::model_path);
        let document = engine.recognize_document(
            &model_path,
            PageSource::images(images.to_vec())?,
            &native_engine::DocumentOptions::default()
                .reread_capped(native_engine::reread_capped_requested()),
            events.map_or_else(
                || Box::new(|_: &PageItem| {}) as Box<dyn FnMut(&PageItem) + Send>,
                |events| events.page_read_sink(images.to_vec()),
            ),
            events.map(|events| events.document_sink(images.to_vec())),
        )?;
        let markdown = document.markdown;
        let skipped: Vec<serde_json::Value> = document
            .skipped
            .iter()
            .map(|skip| {
                let image = images[skip.page - 1].display().to_string();
                eprintln!(
                    "[focr] image {} ({image}) skipped: {}",
                    skip.page, skip.reason
                );
                serde_json::json!({"page": skip.page, "image": image, "reason": skip.reason})
            })
            .collect();
        let elapsed = total.elapsed().as_secs_f64();
        let report = engine.take_last_decode_report();
        let ran = engine.loaded_model_identity();
        let mut run_warnings: Vec<native_engine::RunWarning> = pull_hint.into_iter().collect();
        run_warnings.extend(
            report
                .as_ref()
                .map(native_engine::decode_warnings)
                .unwrap_or_default(),
        );
        // The capped pages' re-read (bd-yrr1) is the run's, not the decode's.
        run_warnings.extend(
            document
                .warnings
                .into_iter()
                .filter(|w| w.kind == "v2_page_reread"),
        );
        let partial = report
            .as_ref()
            .zip(ran.as_ref())
            .and_then(|(report, ran)| native_engine::partial_output(report, &run_warnings, ran));
        print_run_warnings(&run_warnings);
        if args.json {
            let mut value = serde_json::json!({
                "schema_version": robot::ROBOT_SCHEMA_VERSION,
                "command": "batch.multi_page",
                "pages": count,
                "seconds": elapsed,
                "decode_mode": decode_mode,
                "markdown": markdown,
            });
            if let Some(report) = &report {
                value["finish_reason"] = report.run_finish_reason().as_str().into();
            }
            if !skipped.is_empty() {
                value["skipped"] = skipped.into();
            }
            merge_run_warnings(&mut value, &run_warnings);
            if let Some(ran) = &ran {
                ran.merge_into(&mut value);
            }
            emit(&value);
        } else {
            println!("{markdown}");
            let read = count - document.skipped.len();
            let parse = match document.windows.len() {
                0 => "one cross-page pass".to_string(),
                windows => format!(
                    "{windows} windows ({} recomputed)",
                    document
                        .windows
                        .iter()
                        .filter(|w| w.fallback_reason.is_some())
                        .count()
                ),
            };
            eprintln!("[focr] multi-page: {read} of {count} pages in {parse}, {elapsed:.2}s");
        }
        // The pages are out; a v2 document that stopped early fails with
        // exit 5 (U2-B6).
        return partial.map_or(Ok(()), Err);
    }

    let mut stopped = None;
    let mut failed = 0;
    let mut first_failure = None;
    if spine {
        // Continuous-batch decode spine (FOCR_BATCH_SPINE=1): prefill + decode
        // every page TOGETHER. The per-page markdown is byte-identical to the
        // sequential loop below (bd-1azu.13), only throughput differs. A
        // batch-level failure (ModelNotFound / timeout) propagates as the run's
        // exit code rather than being folded into per-image results.
        let image_refs: Vec<&std::path::Path> =
            images.iter().map(std::path::PathBuf::as_path).collect();
        let batch = match model.as_deref() {
            Some(m) => engine.recognize_batch_with_model(m, &image_refs),
            None => engine.recognize_batch(&image_refs),
        }?;
        let per_image = total.elapsed().as_secs_f64() / (count.max(1) as f64);
        // One decode report and chart verdict per image, so a page the
        // runaway guard stopped is written and fails, and an unverified chart
        // warns, as in the sequential loop (bd-iv8d, bd-v37k).
        let mut reports = engine.take_batch_decode_reports().into_iter();
        let mut charts = engine.take_batch_chart_page_metas().into_iter();
        for ((image, outcome), saved) in images.iter().zip(batch).zip(saved) {
            let saved = saved.as_deref();
            let outcome = outcome.and_then(|markdown| {
                save_batch_markdown(saved, &markdown)?;
                Ok(markdown)
            });
            let end =
                PageEnd::from_report(reports.next().flatten(), charts.next().flatten(), &engine);
            if let Some(err) = emit_batch_result(
                args.json,
                image,
                per_image,
                outcome,
                saved,
                end,
                &mut results,
            ) {
                failed += 1;
                first_failure.get_or_insert(err);
            }
        }
    } else {
        // Sequential per-image loop — the proven oracle path (FOCR_BATCH_SPINE=0),
        // byte-for-byte what it has always been. The progress bar (GH #2) is
        // stderr-only, disabled under `--json`, and self-disabled off-TTY; it
        // is suspended around each result block so the bar never fuses to the
        // per-image markdown/summary output. A Ctrl+C ends the run at the
        // image it interrupted: the images before it are still reported.
        let bar = progress::Progress::new("batch", count, !args.json);
        for (i, (image, saved)) in images.iter().zip(saved).enumerate() {
            let saved = saved.as_deref();
            let name = image.file_name().map_or_else(
                || image.display().to_string(),
                |n| n.to_string_lossy().into_owned(),
            );
            bar.start_item(format!("image {}/{count}: {name}", i + 1));
            let started = std::time::Instant::now();
            let outcome = match (forced_image_error(i + 1), model.as_deref()) {
                (Some(err), _) => Err(err),
                (None, Some(m)) => engine.recognize_with_model(m, image),
                (None, None) => engine.recognize(image),
            };
            let outcome = outcome.and_then(|markdown| {
                save_batch_markdown(saved, &markdown)?;
                Ok(markdown)
            });
            let secs = started.elapsed().as_secs_f64();
            let end = PageEnd::take(&engine);
            bar.complete_item();
            bar.suspend();
            if let Some(events) = events {
                let failure = outcome.as_ref().err().or(end.partial.as_ref());
                events.image_ended(i + 1, image, failure);
            }
            if matches!(outcome, Err(FocrError::Cancelled)) {
                stopped = Some("cancelled");
                first_failure = Some(FocrError::Cancelled);
                break;
            }
            if let Some(err) =
                emit_batch_result(args.json, image, secs, outcome, saved, end, &mut results)
            {
                failed += 1;
                first_failure.get_or_insert(err);
                if args.fail_fast {
                    stopped = Some("image_failed");
                    break;
                }
            }
        }
        bar.finish();
    }

    let elapsed = total.elapsed().as_secs_f64();
    let ended = if stopped.is_some() {
        results.len()
    } else {
        count
    };
    let per_image = elapsed / (ended.max(1) as f64);
    if args.json {
        let mut value = serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "ocr-batch",
            "count": count,
            "decode_mode": decode_mode,
            "experimental_full_int8": experimental_full_int8,
            "seconds_total": elapsed,
            "seconds_per_image": per_image,
            "results": results,
        });
        if let Some(stopped) = stopped {
            value["stopped"] = stopped.into();
        }
        emit(&value);
    } else if stopped.is_some() {
        eprintln!("[focr] batch stopped after {elapsed:.2}s");
    } else {
        eprintln!(
            "[focr] batch complete: {count} images in {elapsed:.2}s \
             ({per_image:.2}s/image, decode_mode={decode_mode})"
        );
    }
    match first_failure {
        Some(err) if stopped.is_some() || failed == count => Err(err),
        _ => Ok(()),
    }
}

/// Offline weight transform: raw bf16 safetensors → a self-contained `.focrq`
/// (plan §5). `--quant int8` is the validated conservative recipe (decoder
/// FFN/expert GEMMs int8; attention q/k/v/o, `lm_head`, vision, projector,
/// `embed_tokens`, router, and norms high precision). `--quant int4` emits the
/// explicitly NON-DEFAULT wasm/browser Unlimited-OCR recipe (bd-50wo stage 1):
/// expert/dense FFN int4 per-group, attention + `lm_head` + `embed_tokens`
/// int8, everything else high precision — an artifact the model resolver never
/// auto-selects (explicit `--model` path only).
fn run_convert(args: &ConvertArgs) -> FocrResult<()> {
    // int4 targets the wasm runtime: offline SMMLA/VNNI/AMX prepacking is a
    // native-host concern the wasm runtime never consumes. Refuse BEFORE any
    // file I/O so the outcome is deterministic regardless of input existence
    // (the same pre-I/O determinism the old int4 scaffold guaranteed).
    if args.quant == QuantTarget::Int4 && args.arch != ArchTarget::Generic {
        return Err(FocrError::Usage(format!(
            "focr convert --quant int4 emits the wasm recipe and supports only \
             --arch generic, got --arch {}",
            args.arch.as_str()
        )));
    }

    // Resolve the input the way `ocr` resolves a model: a `.safetensors` file
    // as-is, or a directory's shard index (or its single registered shard).
    let resolved = native_engine::OcrModel::resolve_model(&args.input)?;
    let source = native_engine::shards::SourceShards::open(&resolved)?;
    let shard_count = source.files().len();
    let convert_quant = match args.quant {
        QuantTarget::Int8 => quant::convert::ConvertQuant::Int8,
        QuantTarget::Int4 => quant::convert::ConvertQuant::Int4,
    };
    // An explicit `--model-id` without an int4 recipe is refused before any
    // header is read.
    let int4_refusal = |arch: &dyn native_engine::model_arch::ModelArch| -> FocrResult<()> {
        if convert_quant == quant::convert::ConvertQuant::Int4 {
            quant::convert::ensure_int4_recipe(arch)?;
        }
        Ok(())
    };
    let explicit = match args.model_id.as_deref() {
        None => None,
        Some(id) => {
            let arch = native_engine::model_arch::arch_by_id(id).ok_or_else(|| {
                FocrError::Usage(format!(
                    "unknown --model-id {id:?} (see `focr models` for the registry)"
                ))
            })?;
            int4_refusal(arch)?;
            Some(arch)
        }
    };

    // The bounded header pass: every shard's header is validated and checked
    // against the index before a single payload byte is read. The census then
    // picks (or cross-checks) the target arch, so a disagreeing `--model-id`
    // is named before the census's pinned shard count or digests are judged
    // (U2-C3).
    let (headers, prefixes) = native_engine::read_source_headers(&source)?;
    let arch = native_engine::conversion_arch(explicit, &headers)?;
    if explicit.is_none() {
        int4_refusal(arch)?;
    }
    let census = arch.tensor_census();
    if let Some(census) = census {
        native_engine::unlimited_ocr_census::validate_conversion_shard_count(census, shard_count)?;
    }
    if convert_quant == quant::convert::ConvertQuant::Int4 && shard_count != 1 {
        return Err(FocrError::NotImplemented(format!(
            "focr convert --quant int4 (the wasm recipe) needs a single-shard source; {} has \
             {shard_count} shards",
            resolved.display()
        )));
    }

    // `--calib`: load the activation statistics BEFORE the (long) conversion so a
    // bad path fails fast, and report the coverage the artifact was built with.
    let calib = match &args.calib {
        None => None,
        Some(path) => {
            let text = std::fs::read_to_string(path).map_err(|e| {
                FocrError::ModelNotFound(format!(
                    "cannot read --calib JSON at {}: {e}",
                    path.display()
                ))
            })?;
            Some(quant::calib::CalibStats::from_json(&text)?)
        }
    };

    // Any I64 tensor is checked against the arch's census, still before a
    // single payload byte is read.
    let int64_rules = native_engine::shards::int64_rules(Some(arch));
    native_engine::shards::check_int64_entries(&headers.int64, int64_rules, arch.id())?;
    native_engine::shards::check_int64_rules_present(&headers.int64, int64_rules, arch.id())?;

    // Stream shard by shard, in index order: read each shard once, hashing it
    // in the same pass, check it against the arch's pin, convert its tensors,
    // and drop it before the next one is read.
    let omit_lm_head = arch.tie_word_embeddings();
    let mut int8 = (convert_quant == quant::convert::ConvertQuant::Int8)
        .then(|| quant::convert::Int8Conversion::new(arch, args.arch.packing_byte()));
    let mut int4_blob = None;
    let mut digests = Vec::with_capacity(shard_count);
    let mut tensor_count = 0usize;
    // `tensors_quantized` counts every LOSSY record the artifact will carry:
    // the conservative int8 set for --quant int8, or the wasm recipe's
    // int4 + int8 union for --quant int4.
    let mut quantized_int8 = 0usize;
    let mut quantized_int4 = 0usize;
    let mut calib_coverage: Option<((usize, usize), (usize, usize))> = None;
    for (position, (name, path)) in source.files().iter().enumerate() {
        let (bytes, digest) = native_engine::shards::read_shard(name, path)?;
        if !bytes.starts_with(&prefixes[position]) {
            return Err(FocrError::FormatMismatch(format!(
                "{} changed between its header check and its conversion",
                path.display()
            )));
        }
        if let Some(census) = census {
            native_engine::unlimited_ocr_census::validate_conversion_source_shard(
                census,
                position,
                &digest.sha256,
            )?;
        }
        let weights = native_engine::weights::Weights::from_source_shard(bytes, arch)?;
        tensor_count += weights.len();
        match convert_quant {
            quant::convert::ConvertQuant::Int8 => {
                quantized_int8 += weights
                    .names()
                    .filter(|name| quant::convert::is_decoder_int8_tensor_for(name, arch))
                    .filter(|name| !(omit_lm_head && *name == "lm_head.weight"))
                    .count();
            }
            quant::convert::ConvertQuant::Int4 => {
                for name in weights.names() {
                    match quant::recipe::classify_wasm_experts_int4(name) {
                        quant::recipe::WasmInt4Policy::ExpertInt4 => quantized_int4 += 1,
                        quant::recipe::WasmInt4Policy::Int8 => quantized_int8 += 1,
                        quant::recipe::WasmInt4Policy::KeepHighPrecision => {}
                    }
                }
            }
        }
        if let Some(stats) = &calib {
            let ((i4c, i4t), (i8c, i8t)) = quant::convert::calib_coverage(&weights, stats);
            let ((c4, t4), (c8, t8)) = calib_coverage.unwrap_or_default();
            calib_coverage = Some(((c4 + i4c, t4 + i4t), (c8 + i8c, t8 + i8t)));
        }
        match int8.as_mut() {
            Some(conversion) => conversion.add_shard(&weights)?,
            // int4 is single-shard (checked above), so this shard is the source.
            None => {
                int4_blob = Some(quant::convert::safetensors_to_focrq_calibrated(
                    &weights,
                    convert_quant,
                    args.arch.packing_byte(),
                    digest.sha256,
                    arch,
                    calib.as_ref(),
                )?);
            }
        }
        digests.push(digest);
    }
    let source_sha256 = native_engine::shards::source_sha256(&digests);
    let input_bytes: u64 = digests.iter().map(|digest| digest.size).sum();
    let quantized = quantized_int8 + quantized_int4;
    let blob = match (int8, int4_blob) {
        (Some(conversion), _) => conversion.finish(
            source_sha256,
            native_engine::shards::provenance_json(&digests),
        )?,
        (None, Some(blob)) => blob,
        (None, None) => {
            return Err(FocrError::Other(anyhow::anyhow!(
                "convert produced no artifact for {}",
                resolved.display()
            )));
        }
    };
    let output_bytes = blob.len();
    let output_sha256 = hex_encode32(&quant::convert::sha256_of_bytes(&blob));
    std::fs::write(&args.output, &blob).map_err(|e| {
        FocrError::Other(anyhow::anyhow!(
            "writing .focrq to {}: {e}",
            args.output.display()
        ))
    })?;

    let sha_hex = hex_encode32(&source_sha256);
    let quant_recipe = quant::convert::stamped_quant_recipe(arch, convert_quant);
    if args.json {
        emit(&serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "convert",
            "status": "ok",
            "implemented": true,
            "input": resolved,
            "output": args.output,
            "quant": args.quant.as_str(),
            "arch": args.arch.as_str(),
            "model_id": arch.id(),
            "quant_recipe": quant_recipe,
            "source_sha256": sha_hex,
            "source_shards": digests
                .iter()
                .map(|digest| serde_json::json!({
                    "name": digest.name,
                    "size": digest.size,
                    "sha256": digest.sha256_hex(),
                }))
                .collect::<Vec<_>>(),
            "tensors": tensor_count,
            "tensors_quantized": quantized,
            "tensors_int8": quantized_int8,
            "tensors_int4": quantized_int4,
            "input_bytes": input_bytes,
            "output_bytes": output_bytes,
            "output_sha256": output_sha256,
            "calib": args.calib,
            "calib_covered_int4": calib_coverage.map(|((c, _), _)| c),
            "calib_total_int4": calib_coverage.map(|((_, t), _)| t),
            "calib_covered_int8": calib_coverage.map(|(_, (c, _))| c),
            "calib_total_int8": calib_coverage.map(|(_, (_, t))| t),
        }));
    } else {
        eprintln!(
            "[focr] convert: wrote {} ({} quant {}: {tensor_count} tensors, \
             {quantized_int8} int8 + {quantized_int4} int4, \
             {input_bytes} -> {output_bytes} bytes) source_sha256={sha_hex} \
             output_sha256={output_sha256}{}",
            args.output.display(),
            args.arch.as_str(),
            args.quant.as_str(),
            quant_recipe.map_or_else(String::new, |id| format!(" quant_recipe={id}")),
        );
        if let Some(((i4c, i4t), (i8c, i8t))) = calib_coverage {
            eprintln!(
                "[focr] convert: calibration-aware quantization (bd-50wo B+C): \
                 int4 coverage {i4c}/{i4t} tensors, int8 coverage {i8c}/{i8t} tensors \
                 (uncovered tensors fall back to uniform importance)"
            );
        }
    }
    Ok(())
}

/// Lowercase-hex-encode the 32-byte source digest for human/robot display.
fn hex_encode32(bytes: &[u8; 32]) -> String {
    use std::fmt::Write as _;
    let mut s = String::with_capacity(64);
    for &b in bytes {
        let _ = write!(s, "{b:02x}");
    }
    s
}

fn run_runs(args: &RunsArgs) -> FocrResult<()> {
    let limit = i64::from(non_negative_u32("limit", args.limit)?);
    let store = crate::storage::RunStore::open(&crate::storage::RunStore::default_path()?)?;
    let records = store.query(args.id.as_deref(), limit)?;
    let format = if args.json {
        OutputFormat::Json
    } else {
        args.format
    };
    let record_json = |r: &crate::storage::RunRecord| {
        serde_json::json!({
            "schema_version": crate::storage::SCHEMA_VERSION,
            "run_id": r.run_id,
            "started_at": r.started_at,
            "finished_at": r.finished_at,
            "input_path": r.input_path,
            "mode": r.mode,
            "quant": r.quant,
            "model_version_tag": r.model_version_tag,
            "exit_code": r.exit_code,
            "status": r.status,
        })
    };
    match format {
        OutputFormat::Json => emit(&serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "runs",
            "store": store.path(),
            "count": records.len(),
            "runs": records.iter().map(record_json).collect::<Vec<_>>(),
        })),
        OutputFormat::Ndjson => {
            for r in &records {
                emit(&record_json(r));
            }
        }
        OutputFormat::Plain => {
            if records.is_empty() {
                println!("no recorded runs ({})", store.path().display());
            }
            for r in &records {
                println!(
                    "{}  {}  {}  exit {}  {}  {}",
                    r.run_id, r.status, r.mode, r.exit_code, r.quant, r.input_path
                );
            }
        }
    }
    Ok(())
}

fn run_sync(args: &SyncArgs) -> FocrResult<()> {
    let store = crate::storage::RunStore::open(&crate::storage::RunStore::default_path()?)?;
    let (subcommand, file, n) = match &args.cmd {
        SyncCmd::ExportJsonl { file } => {
            let out = file.clone().unwrap_or_else(|| {
                let mut p = store.path().to_path_buf();
                p.set_extension("jsonl");
                p
            });
            let n = crate::storage::export_jsonl(&store, &out)?;
            ("export-jsonl", out, n)
        }
        SyncCmd::ImportJsonl { file } => {
            let n = crate::storage::import_jsonl(&store, file)?;
            ("import-jsonl", file.clone(), n)
        }
    };
    if args.json {
        emit(&serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "sync",
            "subcommand": subcommand,
            "store": store.path(),
            "file": file,
            "records": n,
        }));
    } else {
        eprintln!(
            "[focr] sync {subcommand}: {n} records via {}",
            file.display()
        );
    }
    Ok(())
}

/// A stable lowercase name for a [`crate::model_arch::Task`] (the machine
/// contract for `focr models --json`).
fn task_name(t: crate::model_arch::Task) -> &'static str {
    use crate::model_arch::Task;
    match t {
        Task::Ocr => "ocr",
        Task::Formula => "formula",
        Task::Tables => "tables",
        Task::Chart => "chart",
        Task::Molecular => "molecular",
        Task::Geometry => "geometry",
        Task::Music => "music",
        Task::Describe => "describe",
        Task::Vqa => "vqa",
        Task::Handwriting => "handwriting",
    }
}

/// Render one model-architecture descriptor as a JSON object for `focr models
/// --json`.
fn model_arch_json(a: &dyn crate::model_arch::ModelArch) -> serde_json::Value {
    serde_json::json!({
        "id": a.id(),
        "display_name": a.display_name(),
        "implemented": a.implemented(),
        "status": a.maturity().as_str(),
        "tasks": a.tasks().iter().map(|t| task_name(*t)).collect::<Vec<_>>(),
        "vision_encoder": format!("{:?}", a.vision_encoder()),
        "decoder": format!("{:?}", a.decoder()),
        "tokenizer": format!("{:?}", a.tokenizer()),
        "default_artifact": a.default_artifact_basename(),
        "recipe": a.required_quant_recipe("int8"),
        "license": a.license_notice(),
    })
}

#[derive(Debug, Default)]
struct PullAvailability {
    in_manifest: bool,
    compatible: Vec<(String, String)>,
    blocked: Vec<(String, String)>,
}

fn pull_availability(manifest: Option<&dist::Manifest>, model_id: &str) -> PullAvailability {
    let Some(manifest) = manifest else {
        return PullAvailability::default();
    };
    let quants = if manifest.model == model_id {
        Some(&manifest.quants)
    } else {
        manifest.models.get(model_id).map(|entry| &entry.quants)
    };
    let Some(quants) = quants else {
        return PullAvailability::default();
    };

    let mut availability = PullAvailability {
        in_manifest: true,
        ..PullAvailability::default()
    };
    for (quant, entry) in quants {
        let item = (quant.clone(), entry.recipe.clone());
        if dist::quant_recipe_is_compatible(model_id, quant, &entry.recipe) {
            availability.compatible.push(item);
        } else {
            availability.blocked.push(item);
        }
    }
    availability
}

/// `focr models` — list the model architectures this build can run (the "model
/// zoo", epic bd-3jo6). A human table by default; `--json` for a machine-readable
/// list. Runtime readiness and artifact compatibility are separate fields so a
/// mismatched external manifest remains visible without being advertised as
/// pullable.
fn run_models(args: &ModelsArgs) -> FocrResult<()> {
    let archs = crate::model_arch::registry();
    // The embedded manifest supplies offline provenance and exact runtime recipe
    // compatibility. Keep reporting blocked entries defensively for external or
    // future manifests that drift from the runtime contract.
    let manifest = dist::builtin_manifest()?;
    if args.json {
        let models: Vec<serde_json::Value> = archs
            .iter()
            .map(|a| {
                let mut j = model_arch_json(*a);
                j["installed"] = model_installed(a.id()).into();
                let pull = pull_availability(Some(&manifest), a.id());
                j["pull"] = serde_json::json!({
                    "in_manifest": pull.in_manifest,
                    "available": !pull.compatible.is_empty(),
                    "quants": pull.compatible.iter().map(|(quant, _)| quant).collect::<Vec<_>>(),
                    "recipes": pull.compatible.iter().map(|(quant, recipe)| serde_json::json!({
                        "quant": quant,
                        "recipe": recipe,
                    })).collect::<Vec<_>>(),
                    "blocked": pull.blocked.iter().map(|(quant, recipe)| serde_json::json!({
                        "quant": quant,
                        "recipe": recipe,
                        "required_recipe": a.required_quant_recipe(quant),
                    })).collect::<Vec<_>>(),
                });
                j
            })
            .collect();
        emit(&serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "models": models,
            "guidance": {
                "unlimited-ocr": "default runtime; FAST plain-text OCR; `focr pull` installs the conservative exact-recipe int8 artifact",
                "unlimited-ocr-2": "best for documents and long documents: Baidu's long-document successor (SR-SWA); `focr pull unlimited-ocr-2` installs its certified int8 artifact, then `--model unlimited-ocr-2` reads single pages and documents of any length (`--multi-page`, in windows of 10 pages); `--model <dir>` also runs a raw checkpoint; unlimited-ocr stays the default until unlimited-ocr-2 passes its default gates",
                "got-ocr2": "specialized structured output the default can't produce — math (LaTeX), tables, charts, molecular (SMILES), geometry, sheet music; heavier per page, use when you need FORMAT not plain text; shorthand: `focr ocr --task formula|tables|chart|molecular|geometry|music` (implies `--format`)"
            },
        }));
    } else {
        // TASKS last: its width varies per model (GOT-OCR2 serves seven), so a
        // fixed-width column would misalign — keep it trailing.
        println!(
            "{:<16}  {:<12}  {:<12}  {:<5}  {:<22}  TASKS",
            "ID", "STATUS", "PULL", "LOCAL", "MODEL"
        );
        for a in archs {
            let tasks = a
                .tasks()
                .iter()
                .map(|t| task_name(*t))
                .collect::<Vec<_>>()
                .join(",");
            let status = a.maturity().as_str();
            let availability = pull_availability(Some(&manifest), a.id());
            let pull = if !availability.compatible.is_empty() {
                availability
                    .compatible
                    .iter()
                    .map(|(quant, _)| quant.as_str())
                    .collect::<Vec<_>>()
                    .join(",")
            } else if !availability.blocked.is_empty() {
                "blocked".to_owned()
            } else if a.implemented() {
                "local".to_owned()
            } else {
                "-".to_owned()
            };
            println!(
                "{:<16}  {:<12}  {:<12}  {:<5}  {:<22}  {}",
                a.id(),
                status,
                pull,
                if model_installed(a.id()) { "yes" } else { "-" },
                a.display_name(),
                tasks
            );
        }
        println!();
        println!("Choosing a model:");
        println!("  unlimited-ocr (default)  FAST plain-text OCR. `focr pull` installs the");
        println!("                           conservative exact-recipe int8 artifact.");
        println!("  unlimited-ocr-2          Best for documents and long documents");
        println!("                           (`--multi-page` over a PDF or a directory of pages).");
        println!("                           `focr pull unlimited-ocr-2`, then");
        println!("                           `--model unlimited-ocr-2`. unlimited-ocr stays the");
        println!("                           default until it passes its default gates.");
        println!(
            "  got-ocr2                 SPECIALIZED structured output the default can't produce:"
        );
        println!("                           math (LaTeX), tables, charts, molecular (SMILES),");
        println!(
            "                           geometry, sheet music. Heavier per page — use it when you"
        );
        println!(
            "                           need FORMAT, not for plain text. `focr pull got-ocr2`,"
        );
        println!("                           then `focr ocr --model got-ocr2.int8.focrq <image>`.");
        println!(
            "                           Add `--format` for structured .mmd output (LaTeX/tables/…),"
        );
        println!(
            "                           or `--task formula|tables|chart|molecular|geometry|music`"
        );
        println!(
            "                           to select the format mode by task (implies `--format`)."
        );
    }
    Ok(())
}

fn run_doctor(args: &DoctorArgs) -> FocrResult<()> {
    use crate::doctor;

    // Contract sub-surfaces first: they never touch disk.
    match &args.cmd {
        Some(DoctorCmd::Capabilities) => {
            emit(&doctor::capabilities());
            return Ok(());
        }
        Some(DoctorCmd::RobotDocs) => {
            print!("{}", doctor::robot_docs());
            return Ok(());
        }
        Some(DoctorCmd::Undo { run_id }) => {
            let root = doctor::DoctorRoot::resolve()?;
            let restored = doctor::undo(&root, run_id)?;
            emit(&serde_json::json!({
                "schema_version": doctor::DOCTOR_SCHEMA_VERSION,
                "command": "doctor.undo",
                "run_id": run_id,
                "actions_restored": restored,
                "verified": "every restored file hash-matched its recorded before_hash",
            }));
            return Ok(());
        }
        None => {}
    }

    let root = doctor::DoctorRoot::resolve()?;
    let findings = doctor::detect(&root);

    // Deterministic run id: findings-count + wall-clock seconds (unique enough
    // for a human-auditable dir name; collision just appends actions).
    let run_id = format!(
        "run-{}",
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_millis())
            .unwrap_or_default()
    );

    let planned: Vec<serde_json::Value> = findings
        .iter()
        .map(|f| {
            serde_json::json!({
                "detector": f.detector,
                "severity": f.severity,
                "path": f.path,
                "message": f.message,
                "fixability": f.fixability,
            })
        })
        .collect();

    if args.robot_triage {
        let recommended = if findings.is_empty() {
            "focr ocr <image> -o out.md".to_string()
        } else if args.fix {
            "focr doctor --fix".to_string()
        } else {
            "focr doctor --fix   # safe repairs only; see `focr doctor capabilities --json`"
                .to_string()
        };
        emit(&serde_json::json!({
            "schema_version": doctor::DOCTOR_SCHEMA_VERSION,
            "command": "doctor.robot-triage",
            "summary": {"findings": findings.len(), "healthy": findings.is_empty()},
            "findings": planned,
            "actions_planned": findings.iter().filter(|f| matches!(f.fixability, doctor::Fixability::Auto{..})).count(),
            "recommended_command": recommended,
            "capabilities_hint": "focr doctor capabilities --json",
        }));
        std::process::exit(if findings.is_empty() {
            doctor::EXIT_HEALTHY
        } else {
            doctor::EXIT_FINDINGS
        });
    }

    if args.dry_run {
        emit(&serde_json::json!({
            "schema_version": doctor::DOCTOR_SCHEMA_VERSION,
            "command": "doctor.dry-run",
            "would_mutate": findings.iter().filter(|f| matches!(f.fixability, doctor::Fixability::Auto{..})).count(),
            "blast_radius": root.cache_root.display().to_string(),
            "findings": planned,
            "note": "NO mutation performed; --fix applies the auto items backup-first",
        }));
        std::process::exit(if findings.is_empty() {
            doctor::EXIT_HEALTHY
        } else {
            doctor::EXIT_FINDINGS
        });
    }

    if args.fix {
        let report = match doctor::fix(&root, &findings, &run_id) {
            Ok(r) => r,
            Err(e) => {
                let msg = format!("{e}");
                if msg.contains("doctor lock held") {
                    eprintln!("focr doctor: {msg}");
                    std::process::exit(doctor::EXIT_CONCURRENCY_LOST);
                }
                return Err(e);
            }
        };
        emit(&serde_json::json!({
            "schema_version": doctor::DOCTOR_SCHEMA_VERSION,
            "command": "doctor.fix",
            "run_id": report.run_id,
            "fixed": report.fixed,
            "refused_unsafe": report.refused,
            "advice_only": report.advice_only,
            "failed_rolled_back": report.failed_rolled_back,
            "undo": format!("focr doctor undo {}", report.run_id),
            "findings": planned,
        }));
        std::process::exit(report.exit_code);
    }

    // Detect-only.
    if args.json {
        emit(&serde_json::json!({
            "schema_version": doctor::DOCTOR_SCHEMA_VERSION,
            "command": "doctor",
            "healthy": findings.is_empty(),
            "findings": planned,
        }));
    } else if findings.is_empty() {
        println!("focr doctor: healthy ({} checks green)", 4);
    } else {
        for f in &findings {
            println!("[{}] {}: {}", f.severity, f.detector, f.message);
            if let doctor::Fixability::RefusedUnsafe {
                recommended_command,
            } = &f.fixability
            {
                println!("    run: {recommended_command}");
            }
        }
    }
    std::process::exit(if findings.is_empty() {
        doctor::EXIT_HEALTHY
    } else {
        doctor::EXIT_FINDINGS
    });
}

fn forced_test_error() -> FocrResult<Option<FocrError>> {
    #[cfg(debug_assertions)]
    {
        let Some(raw) = std::env::var_os(FORCE_TEST_ERROR_ENV) else {
            return Ok(None);
        };
        if raw.as_os_str().is_empty() {
            return Ok(None);
        }
        let value = raw.to_string_lossy();
        if value.contains('@') {
            return Ok(None);
        }
        forced_error_of_kind(&value).map(Some)
    }

    #[cfg(not(debug_assertions))]
    {
        Ok(None)
    }
}

#[cfg(debug_assertions)]
fn forced_error_of_kind(kind: &str) -> FocrResult<FocrError> {
    match kind {
        "input_decode" => Ok(FocrError::InputDecode(format!(
            "forced by {FORCE_TEST_ERROR_ENV}=input_decode"
        ))),
        "timeout" => Ok(FocrError::Timeout(format!(
            "forced by {FORCE_TEST_ERROR_ENV}=timeout"
        ))),
        "cancelled" => Ok(FocrError::Cancelled),
        other => Err(FocrError::Usage(format!(
            "invalid {FORCE_TEST_ERROR_ENV}={other:?}; expected input_decode, timeout, or \
             cancelled"
        ))),
    }
}

/// `FOCR_TEST_FORCE_ERROR=<kind>@<ordinal>`: batch image `ordinal` ends with
/// that error instead of being read, in debug builds only.
fn forced_image_error(ordinal: usize) -> Option<FocrError> {
    #[cfg(debug_assertions)]
    {
        let value = std::env::var(FORCE_TEST_ERROR_ENV).ok()?;
        let (kind, at) = value.split_once('@')?;
        at.parse::<usize>()
            .is_ok_and(|at| at == ordinal)
            .then(|| forced_error_of_kind(kind).ok())
            .flatten()
    }

    #[cfg(not(debug_assertions))]
    {
        let _ = ordinal;
        None
    }
}

fn positive_u32(name: &str, value: i64) -> FocrResult<u32> {
    if value <= 0 {
        return Err(FocrError::Usage(format!("{name} must be > 0, got {value}")));
    }
    u32::try_from(value)
        .map_err(|_| FocrError::Usage(format!("{name} is too large for u32: {value}")))
}

fn non_negative_u32(name: &str, value: i64) -> FocrResult<u32> {
    if value < 0 {
        return Err(FocrError::Usage(format!(
            "{name} must be >= 0, got {value}"
        )));
    }
    u32::try_from(value)
        .map_err(|_| FocrError::Usage(format!("{name} is too large for u32: {value}")))
}

/// `--temperature`: every decode here is greedy (each model's sampler refuses
/// `temperature > 0`), so 0 is the one value a run can honor. Anything else
/// is a usage error now, not a failure after the model has loaded.
fn greedy_temperature(value: f32) -> FocrResult<f32> {
    if value != 0.0 {
        return Err(FocrError::Usage(format!(
            "temperature must be 0: every model here decodes greedily, got {value}"
        )));
    }
    Ok(value)
}

fn robot_health_payload() -> serde_json::Value {
    let model_spec = OcrEngine::model_path();
    let model_present = native_engine::native_model_available(&model_spec);
    let model_search_dirs: Vec<_> = native_engine::model_resolution_search_dirs()
        .into_iter()
        .map(|p| p.display().to_string())
        .collect();
    // Phase 0: minimal health. The expanded report (arch features, thread
    // budget) lands with the rest of plan §7.3.
    serde_json::json!({
        "schema_version": robot::ROBOT_SCHEMA_VERSION,
        "status": "scaffold",
        "ready": false,
        "phase": "pre-Phase-0 skeleton",
        "model_present": model_present,
        "model_spec": model_spec.display().to_string(),
        "model_search_dirs": model_search_dirs,
        "model_license_notice": FOCR_MODEL_LICENSE_NOTICE,
    })
}

/// The `robot triage` mega-command payload (bd-wp8.7 / agent-ergonomics
/// Axiom 0): everything an agent needs to act after ONE round-trip — what the
/// tool does (quick_ref), whether it can run right now (health), what to type
/// NEXT given that state (recommendations, copy-pasteable), the common command
/// templates, and the frozen exit-code dictionary. Composes the existing
/// health payload and schema — no duplicated facts.
fn robot_triage_payload() -> serde_json::Value {
    let health = robot_health_payload();
    let model_present = health["model_present"].as_bool().unwrap_or(false);
    let recommendations: Vec<&str> = if model_present {
        vec![
            "focr ocr <image-or-pdf> -o out.md   # primary: OCR to markdown",
            "focr ocr <image> --json             # structured JSON + bounding boxes",
            "focr models                         # which zoo models/tasks this build can run",
            "focr ocr-batch <img1> <img2> ...    # load weights once, many pages",
        ]
    } else {
        vec![
            "focr pull                           # install the default conservative Unlimited-OCR model",
            "FOCR_MODEL_PATH=/path/to/raw-or-compatible-model focr ocr <image-or-pdf> -o out.md",
            "focr models                         # inspect compatible and blocked model pulls",
        ]
    };
    serde_json::json!({
        "schema_version": robot::ROBOT_SCHEMA_VERSION,
        "command": "robot.triage",
        "quick_ref": {
            "ocr": "parse a document image/PDF into markdown (--json for boxes; -o FILE to write)",
            "ocr-batch": "many images in one process (weights load once)",
            "pull": "download a manifest-compatible model into the cache; defaults to the conservative Unlimited-OCR artifact",
            "models": "list model ids, tasks, and compatible or blocked pull status",
            "convert": "offline safetensors -> .focrq quantization",
            "runs": "query run history (--format json|ndjson; empty history = exit 0)",
            "sync": "export/import the append-only run audit JSONL (one-way contract)",
            "doctor": "self-check/repair",
            "robot": "agent surfaces: run (NDJSON stream), schema, health, backends, selftest, triage",
        },
        "health": health,
        "recommendations": recommendations,
        "commands": {
            "first_ocr": "focr ocr page.png -o page.md",
            "structured": "focr ocr page.png --json",
            "stream_events": "focr robot run page.png",
            "contract": "focr robot schema",
        },
        "exit_codes": robot::robot_schema()["exit_codes"].clone(),
    })
}

fn emit(value: &serde_json::Value) {
    // Robot-facing commands emit exactly one JSON object per line.
    println!(
        "{}",
        serde_json::to_string(value).unwrap_or_else(|_| value.to_string())
    );
}

/// Both stdin AND stderr are TTYs — the prerequisite for an interactive
/// download prompt (stderr is where the prompt is written; stdin is the answer
/// channel; stdout is reserved for the OCR result / JSON).
fn is_interactive() -> bool {
    use std::io::IsTerminal;
    std::io::stdin().is_terminal() && std::io::stderr().is_terminal()
}

/// Append the actionable acquisition hint to a model-not-found message. A
/// `--model` that names a registry id gets that model's own pull when this
/// release's embedded manifest publishes a compatible one, and says so when
/// it does not.
fn with_pull_hint(msg: &str, requested: Option<&Path>) -> String {
    let Some(id) = requested
        .and_then(Path::to_str)
        .filter(|id| crate::model_arch::arch_by_id(id).is_some())
    else {
        return format!(
            "{msg} — run `focr pull` to install the compatible conservative default, point \
             FOCR_MODEL_PATH at raw BF16 weights or an exact-recipe local artifact, or inspect \
             `focr models` for other compatible pulls"
        );
    };
    let manifest = dist::builtin_manifest().ok();
    if !pull_availability(manifest.as_ref(), id)
        .compatible
        .is_empty()
    {
        format!(
            "{msg} — run `focr pull {id}` to install it, or point FOCR_MODEL_PATH at its raw \
             weights or an exact-recipe local artifact"
        )
    } else {
        format!(
            "{msg} — this release's manifest does not publish {id}; point FOCR_MODEL_PATH at \
             its raw weights or an exact-recipe local artifact, or inspect `focr models` for \
             the models `focr pull` installs"
        )
    }
}

/// Prompt on the TTY only when the selected manifest may supply a compatible
/// default. The embedded source is checked before offering its multi-gigabyte
/// download; custom sources are checked by [`dist::pull`].
fn offer_first_run_download() -> FocrResult<Option<dist::PullOutcome>> {
    use std::io::Write as _;
    let source = dist::resolve_manifest_source(None);
    // The bare-`focr pull` default (D25); the embedded manifest is checked
    // for a compatible pull of it first, another manifest at pull time.
    let model = if source == dist::DEFAULT_MANIFEST_SOURCE {
        match first_run_offer(&MODE_DEFAULTS, &dist::builtin_manifest()?) {
            Some(model) => model,
            None => return Ok(None),
        }
    } else {
        mode_default(&MODE_DEFAULTS, RunMode::Pull)
    };
    eprint!("focr: model not found. Download {model} from the configured manifest now? [y/N] ");
    std::io::stderr().flush().ok();
    let mut answer = String::new();
    std::io::stdin()
        .read_line(&mut answer)
        .map_err(|e| FocrError::Other(anyhow::anyhow!("reading prompt response: {e}")))?;
    if !matches!(answer.trim().to_ascii_lowercase().as_str(), "y" | "yes") {
        return Ok(None);
    }
    let outcome = dist::pull(Some(model), dist::DEFAULT_QUANT, &source, |event| {
        eprintln!("focr pull: {event}");
    })?;
    Ok(Some(outcome))
}

/// `focr pull` — download (or confirm-cached) the model weights + tokenizer.
fn run_pull(args: &PullArgs) -> FocrResult<()> {
    let source = dist::resolve_manifest_source(args.manifest.as_deref());
    let outcome = dist::pull(
        Some(
            args.model
                .as_deref()
                .unwrap_or_else(|| mode_default(&MODE_DEFAULTS, RunMode::Pull)),
        ),
        &args.quant,
        &source,
        |event| {
            // `--json` keeps stdout for the one result object; each step is an
            // NDJSON line on stderr (parts and their SHA-256s, the transaction).
            if args.json {
                let mut line = event.to_json();
                line["schema_version"] = robot::ROBOT_SCHEMA_VERSION.into();
                line["command"] = "pull".into();
                eprintln!("{line}");
            } else {
                eprintln!("focr pull: {event}");
            }
        },
    )?;
    if args.json {
        emit(&serde_json::json!({
            "schema_version": robot::ROBOT_SCHEMA_VERSION,
            "command": "pull",
            "status": "ok",
            "quant": outcome.quant,
            "focrq": outcome.focrq_path.display().to_string(),
            "tokenizer": outcome.tokenizer_path.display().to_string(),
            "sidecars": outcome
                .sidecar_paths
                .iter()
                .map(|p| p.display().to_string())
                .collect::<Vec<_>>(),
            "from_cache": outcome.from_cache,
            // A manifest entry without a notice falls back to the pulled
            // model's own built-in notice (the default model's when none was
            // named), never to the Unlimited-OCR one for every model.
            "model_license_notice": if outcome.license_notice.is_empty() {
                args.model
                    .as_deref()
                    .and_then(crate::model_arch::arch_by_id)
                    .unwrap_or_else(crate::model_arch::default_arch)
                    .license_notice()
            } else {
                &outcome.license_notice
            },
        }));
    } else {
        eprintln!(
            "focr pull: ready — model at {} ({})",
            outcome.focrq_path.display(),
            if outcome.from_cache {
                "already cached"
            } else {
                "downloaded"
            }
        );
    }
    Ok(())
}

fn robot_backends_payload() -> serde_json::Value {
    let hardware_selected = simd::detected_tier();
    let effective_route = simd::effective_dense_route();
    let available: Vec<_> = simd::available_tiers()
        .iter()
        .map(|tier| {
            serde_json::json!({
                "tag": tier.tag(),
                "feature": tier.feature_string(),
            })
        })
        .collect();

    serde_json::json!({
        "schema_version": robot::ROBOT_SCHEMA_VERSION,
        "simd_tiers": {
            "selected": effective_route.tag(),
            "selected_feature": effective_route.feature_string(),
            "hardware_selected": hardware_selected.tag(),
            "hardware_selected_feature": hardware_selected.feature_string(),
            "available": available,
            "override_env": "FOCR_FORCE_ARCH",
            "selection_scope": "ordinary_dense_int8",
            "status": "runtime capability and effective-route selection active"
        },
        "logical_cpus": std::thread::available_parallelism().map(|n| n.get()).unwrap_or(0),
        // The ONE process-wide budget (bd-223.2 addendum: FOCR_THREADS else
        // physical cores, of the fastest tier on a two-tier Mac (bd-zex4)
        // — pool-sizing consumers read this, never logical).
        "threads": crate::thread_budget()
    })
}

/// `focr robot selftest` — re-run the dispatched int8 GEMM against the scalar
/// oracle on this exact CPU and emit a machine-checkable verdict. Emits the
/// report JSON (always, so robots see the per-shape detail) and THEN returns a
/// generic error (exit 1) if any case diverged, so the command can gate a CI /
/// post-install check. `FOCR_FORCE_ARCH` selects which available tier runs.
fn run_robot_selftest() -> FocrResult<()> {
    let report = simd::selftest();
    let cases: Vec<_> = report
        .cases
        .iter()
        .map(|c| {
            serde_json::json!({
                "kind": c.kind,
                "label": c.label,
                "m": c.m,
                "k": c.k,
                "n": c.n,
                "ok": c.ok,
                "mismatches": c.mismatches,
                "first_bad": c.first_bad.map(|(i, got, want)| serde_json::json!({
                    "index": i, "dispatched": got, "oracle": want,
                })),
            })
        })
        .collect();
    let available: Vec<_> = report.available.iter().map(|t| t.tag()).collect();
    let executed_routes: Vec<_> = report.executed_routes.iter().map(|r| r.tag()).collect();
    let passed = report.cases.iter().filter(|c| c.ok).count();
    let oracle_independent = !matches!(
        report.effective_route,
        simd::EffectiveI8Route::Autovec | simd::EffectiveI8Route::Scalar
    );
    emit(&serde_json::json!({
        "schema_version": robot::ROBOT_SCHEMA_VERSION,
        "command": "robot.selftest",
        "selected": report.effective_route.tag(),
        "selected_feature": report.effective_route.feature_string(),
        "hardware_selected": report.hardware_selected.tag(),
        "hardware_selected_feature": report.hardware_selected.feature_string(),
        "executed_routes": executed_routes,
        "route_consistent": report.route_consistent,
        "oracle_independent": oracle_independent,
        "available": available,
        "override_env": "FOCR_FORCE_ARCH",
        "logical_cpus": std::thread::available_parallelism().map(|n| n.get()).unwrap_or(0),
        "threads": crate::thread_budget(),
        "cases_total": report.cases.len(),
        "cases_passed": passed,
        "all_ok": report.all_ok,
        "verdict": if report.all_ok { "pass" } else { "fail" },
        // A12 (bd-3jo6.1.12): the machine-readable PER-MODEL verdict — every
        // registered int8 decoder's real kernel shapes proven bit-identical
        // to the scalar oracle on THIS host, incl its own worst-case-K row.
        "models": report.models.iter().map(|(id, ok)| serde_json::json!({
            "id": id, "verdict": if *ok { "pass" } else { "fail" },
        })).collect::<Vec<_>>(),
        "cases": cases,
    }));
    if report.all_ok {
        Ok(())
    } else {
        let failed = report.cases.len() - passed;
        Err(FocrError::Other(anyhow::anyhow!(
            "robot selftest: {failed}/{} parity case(s) diverged; route_consistent={} \
             expected={} observed={:?}, hardware={} — the dense int8 path is not certified on this CPU",
            report.cases.len(),
            report.route_consistent,
            report.effective_route.tag(),
            report
                .executed_routes
                .iter()
                .map(|r| r.tag())
                .collect::<Vec<_>>(),
            report.hardware_selected.feature_string(),
        )))
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ErrorMode {
    Human,
    Robot,
}

impl ErrorMode {
    fn from_cli(cli: &Cli) -> Self {
        match &cli.command {
            Command::Ocr(args) if args.robot => Self::Robot,
            Command::Robot {
                cmd: RobotCmd::Run(_),
            } => Self::Robot,
            _ => Self::Human,
        }
    }
}

fn exit_code_from_error(err: &FocrError, mode: ErrorMode) -> ExitCode {
    match mode {
        // Error paths retire the detached renderer without waiting for
        // terminal I/O. Do not reintroduce that wait while printing the final
        // diagnostic; a stalled renderer makes this best-effort.
        ErrorMode::Human => {
            let _ = progress::try_stderr_message(format_args!("focr: {err}"));
        }
        ErrorMode::Robot => emit(&robot::run_error_event(err)),
    }
    ExitCode::from(exit_code_byte(err))
}

fn exit_code_byte(err: &FocrError) -> u8 {
    u8::try_from(err.exit_code()).unwrap_or(1)
}

#[cfg(test)]
mod tests {
    use super::*;

    const V1: &str = native_engine::model_arch::UNLIMITED_OCR_V1_ID;
    const V2: &str = native_engine::model_arch::UNLIMITED_OCR_V2_ID;
    const MODES: [RunMode; 7] = [
        RunMode::SinglePage,
        RunMode::PdfDocument,
        RunMode::DirectoryDocument,
        RunMode::MultiPage,
        RunMode::Batch,
        RunMode::BatchMultiPage,
        RunMode::Pull,
    ];

    /// A test-only table with v2 as every mode's default (D25, plan R6).
    fn v2_table() -> [(RunMode, &'static str); 7] {
        MODES.map(|mode| (mode, V2))
    }

    /// D25: the shipped table has one entry per mode, every one v1.
    #[test]
    fn the_shipped_mode_table_defaults_every_mode_to_v1() {
        for mode in MODES {
            let entries = MODE_DEFAULTS.iter().filter(|(m, _)| *m == mode).count();
            assert_eq!(entries, 1, "{mode:?}");
            assert_eq!(mode_default(&MODE_DEFAULTS, mode), V1, "{mode:?}");
        }
    }

    /// D25: a `focr ocr` run's mode follows its input and `--multi-page`.
    #[test]
    fn an_ocr_run_mode_follows_its_input() {
        let mode = |argv: &[&str], is_document: bool| {
            let cli = Cli::try_parse_from(argv).expect("ocr parses");
            let Command::Ocr(args) = cli.command else {
                unreachable!("expected ocr command");
            };
            RunMode::of_ocr(&args.to_request().expect("request builds"), is_document)
        };
        let dir = std::env::temp_dir().display().to_string();
        assert_eq!(
            mode(&["focr", "ocr", "scan.png"], false),
            RunMode::SinglePage
        );
        assert_eq!(
            mode(&["focr", "ocr", "doc.pdf"], true),
            RunMode::PdfDocument
        );
        assert_eq!(
            mode(&["focr", "ocr", &dir], true),
            RunMode::DirectoryDocument
        );
        assert_eq!(
            mode(&["focr", "ocr", "doc.pdf", "--multi-page"], true),
            RunMode::MultiPage
        );
    }

    /// D25 precedence: `--model`/`FOCR_MODEL_PATH` > the mode default > v1,
    /// over the shipped table and a v2-default one, with the default
    /// installed or not. Only a non-v1 default is probed.
    #[test]
    fn model_choice_follows_the_precedence_matrix() {
        for table in [MODE_DEFAULTS, v2_table()] {
            for mode in MODES {
                let default_id = mode_default(&table, mode);
                for named in [true, false] {
                    for installed in [true, false] {
                        let mut probed = false;
                        let choice = choose_model(named, default_id, |id| {
                            probed = true;
                            assert_eq!(id, default_id);
                            installed
                        });
                        let want = match (named, default_id == V1, installed) {
                            (true, ..) => ModelChoice::Named,
                            (false, true, _) => ModelChoice::V1Default,
                            (false, false, true) => ModelChoice::ModeDefault(default_id),
                            (false, false, false) => ModelChoice::MissingDefault(default_id),
                        };
                        assert_eq!(choice, want, "{mode:?} named={named} installed={installed}");
                        assert_eq!(probed, !named && default_id != V1, "{mode:?}");
                    }
                }
            }
        }
    }

    /// D25: a missing default's `pull_hint` names the model and mode, and it
    /// prints once: before the decode, never again with the run's warnings.
    #[test]
    fn a_pull_hint_names_the_missing_default_and_prints_once() {
        let hint = pull_hint(RunMode::PdfDocument, V2);
        assert_eq!(hint.kind, "pull_hint");
        assert!(native_engine::RUN_WARNING_KINDS.contains(&hint.kind));
        let json = hint.to_json();
        assert_eq!(json["model_id"], V2);
        assert_eq!(json["mode"], "pdf");
        assert!(
            hint.message
                .contains("unlimited-ocr-2, which is not installed")
                && hint.message.contains("`focr pull unlimited-ocr-2`"),
            "{}",
            hint.message
        );
        assert_eq!(
            hint.recovery,
            native_engine::warning_recovery(native_engine::WarningKind::PullHint)
        );
        assert!(printed_early(&hint));
    }

    /// D25: the first-run offer names the bare-`focr pull` default, and only
    /// when the manifest carries a compatible pull of it.
    #[test]
    fn the_first_run_offer_names_the_table_default() {
        let builtin = dist::builtin_manifest().expect("embedded manifest parses");
        assert_eq!(first_run_offer(&MODE_DEFAULTS, &builtin), Some(V1));
        assert_eq!(
            first_run_offer(&v2_table(), &builtin),
            pull_availability(Some(&builtin), V2)
                .compatible
                .first()
                .map(|_| V2)
        );

        let entry = |recipe: &str| dist::ModelEntry {
            license_notice: builtin.license_notice.clone(),
            version: None,
            quants: [(
                "int8".to_owned(),
                dist::QuantEntry {
                    recipe: recipe.to_owned(),
                    focrq: builtin.quants["int8"].focrq.clone(),
                },
            )]
            .into(),
            tokenizer: builtin.tokenizer.clone(),
            sidecars: Vec::new(),
        };
        let mut local = builtin.clone();
        local.models.insert(
            V2.to_owned(),
            entry(crate::quant::convert::UNLIMITED_OCR_2_INT8_RECIPE_ID),
        );
        assert_eq!(first_run_offer(&v2_table(), &local), Some(V2));
        assert_eq!(first_run_offer(&MODE_DEFAULTS, &local), Some(V1));
        local
            .models
            .insert(V2.to_owned(), entry("some-other-recipe-v1"));
        assert_eq!(first_run_offer(&v2_table(), &local), None);
    }

    #[test]
    fn every_error_variant_maps_to_process_exit_byte_from_error_contract() {
        let cases = [
            (FocrError::Usage("bad flag".into()), 2),
            (FocrError::ModelNotFound("missing".into()), 3),
            (FocrError::InputDecode("bad image".into()), 4),
            (FocrError::Timeout("stage".into()), 5),
            (FocrError::Cancelled, 6),
            (FocrError::FormatMismatch("bad header".into()), 7),
            (FocrError::LowYield("sparse".into()), 8),
            (FocrError::NotImplemented("phase gap".into()), 1),
            (FocrError::Other(anyhow::anyhow!("misc")), 1),
        ];
        for (err, code) in cases {
            eprintln!(
                "{}",
                serde_json::json!({
                    "suite": "cli",
                    "test": "every_error_variant_maps_to_process_exit_byte_from_error_contract",
                    "variant": err.kind(),
                    "exit_code": code,
                    "process_exit_byte": exit_code_byte(&err),
                })
            );
            assert_eq!(exit_code_byte(&err), code);
        }
    }

    #[test]
    fn page_window_flag_takes_pages_auto_or_off_up_to_the_page_limit() {
        use native_engine::{PageWindow, UOCR2_UNWINDOWED_PAGE_LIMIT};
        let parse = |value: &str| {
            Cli::try_parse_from([
                "focr",
                "ocr",
                "b.pdf",
                "--multi-page",
                "--page-window",
                value,
            ])
            .map(|cli| match cli.command {
                Command::Ocr(args) => args.request.page_window,
                _ => panic!("not ocr"),
            })
            .map_err(|error| (error.kind(), error.to_string()))
        };
        assert_eq!(parse("7"), Ok(Some(PageWindow::Pages(7))));
        assert_eq!(parse("auto"), Ok(Some(PageWindow::Auto)));
        assert_eq!(parse("off"), Ok(Some(PageWindow::Off)));
        let limit = UOCR2_UNWINDOWED_PAGE_LIMIT;
        assert_eq!(
            parse(&limit.to_string()),
            Ok(Some(PageWindow::Pages(limit)))
        );

        let (kind, message) = parse(&(limit + 1).to_string()).expect_err("above the limit");
        assert_eq!(kind, clap::error::ErrorKind::ValueValidation);
        assert!(message.contains("at most 102 pages"), "{message}");
        for bad in ["0", "many", "-3", "1.5", ""] {
            assert!(parse(bad).is_err(), "{bad:?}");
        }
    }

    #[test]
    fn resume_flags_parse_and_a_stopped_document_names_its_checkpoint() {
        let resume = |flags: &[&str]| {
            let mut argv = vec!["focr", "ocr", "book.pdf", "--multi-page"];
            argv.extend_from_slice(flags);
            match Cli::try_parse_from(argv).expect("ocr parses").command {
                Command::Ocr(args) => (args.request.resume, args.request.keep_checkpoint),
                _ => panic!("not ocr"),
            }
        };
        assert_eq!(resume(&[]), (None, false));
        assert_eq!(resume(&["--resume"]), (Some(ResumeMode::Matching), false));
        assert_eq!(
            resume(&["--resume=recompute", "--keep-checkpoint"]),
            (Some(ResumeMode::Recompute), true)
        );
        assert!(Cli::try_parse_from(["focr", "ocr", "b.pdf", "--resume=sideways"]).is_err());
        // `--resume` takes no separate value, so a path after it stays one.
        let cli = Cli::try_parse_from(["focr", "ocr", "--resume", "book.pdf"]).expect("parses");
        assert!(
            matches!(cli.command, Command::Ocr(args) if args.request.image.ends_with("book.pdf"))
        );

        let dir = std::env::temp_dir().join(format!("focr-cli-resume-{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("a directory");
        let key = native_engine::checkpoint::ResumeKey::new();
        let files = native_engine::checkpoint::RunFiles::beside(&dir.join("out.md"), key);
        let stopped = || {
            FocrError::Partial(Box::new(crate::error::PartialOutput {
                finish_reason: "cancelled",
                pages_out: 10,
                warnings: Vec::new(),
                model_id: "unlimited-ocr-2",
                source_sha256: None,
                message: "x".into(),
                checkpoint: None,
                resumed_from: None,
            }))
        };
        // A run stopped before its first boundary has nothing to continue.
        let error = with_resume_fields(stopped(), Some(&files), None);
        assert!(matches!(&error, FocrError::Partial(p) if p.checkpoint.is_none()));
        std::fs::write(&files.checkpoint, b"state").expect("a checkpoint");
        let error = with_resume_fields(stopped(), Some(&files), Some(11));
        match &error {
            FocrError::Partial(partial) => {
                assert_eq!(partial.resumed_from, Some(11));
                assert_eq!(
                    partial.checkpoint.as_deref(),
                    Some(files.checkpoint.display().to_string().as_str())
                );
            }
            other => panic!("not partial: {other:?}"),
        }
        let other = with_resume_fields(FocrError::Cancelled, Some(&files), None);
        assert!(matches!(other, FocrError::Cancelled));
    }

    #[test]
    fn long_version_carries_project_and_model_license_notices() {
        let report = long_version_report();
        assert!(report.contains("focr "));
        assert!(report.contains(FOCR_PROJECT_LICENSE_NOTICE));
        assert!(report.contains(&format!("model_license: {FOCR_MODEL_LICENSE_NOTICE}")));
    }

    #[test]
    fn exact_long_version_detection_only_matches_top_level_long_flag() {
        assert!(is_exact_long_version_request(
            ["focr", "--version"].into_iter().map(OsString::from)
        ));
        assert!(!is_exact_long_version_request(
            ["focr", "-V"].into_iter().map(OsString::from)
        ));
        assert!(!is_exact_long_version_request(
            ["focr", "--version", "robot"]
                .into_iter()
                .map(OsString::from)
        ));
    }

    #[test]
    fn robot_health_carries_single_source_model_license_notice() {
        let payload = robot_health_payload();
        assert_eq!(
            payload["model_license_notice"],
            serde_json::json!(FOCR_MODEL_LICENSE_NOTICE)
        );
    }

    #[test]
    fn ocr_robot_flag_selects_robot_error_mode() {
        let cli = Cli {
            command: Command::Ocr(OcrArgs {
                request: OcrRequestArgs {
                    image: PathBuf::from("scan.png"),
                    model: None,
                    base_size: None,
                    image_size: None,
                    crop_mode: Some(CropMode::Gundam),
                    max_length: None,
                    temperature: None,
                    no_repeat_ngram: None,
                    ngram_window: None,
                    max_page_tokens: None,
                    format: false,
                    task: OcrTask::Ocr,
                    question: None,
                    region_box: None,
                    color: None,
                    pages: None,
                    split_spreads: false,
                    multi_page: false,
                    page_window: None,
                    resume: None,
                    keep_checkpoint: false,
                    no_resident: false,
                    threads: None,
                    timing: false,
                    fail_on_low_yield: false,
                },
                json: false,
                output: None,
                extract_figures: false,
                figures_dir: None,
                robot: true,
                check: false,
                raw: false,
            }),
        };
        assert_eq!(ErrorMode::from_cli(&cli), ErrorMode::Robot);
    }

    #[test]
    fn robot_run_selects_robot_error_mode() {
        let cli = Cli {
            command: Command::Robot {
                cmd: RobotCmd::Run(Box::new(RobotRunArgs {
                    request: OcrRequestArgs {
                        image: PathBuf::from("scan.png"),
                        model: None,
                        base_size: None,
                        image_size: None,
                        crop_mode: Some(CropMode::Gundam),
                        max_length: None,
                        temperature: None,
                        no_repeat_ngram: None,
                        ngram_window: None,
                        max_page_tokens: None,
                        format: false,
                        task: OcrTask::Ocr,
                        question: None,
                        region_box: None,
                        color: None,
                        pages: None,
                        split_spreads: false,
                        multi_page: false,
                        page_window: None,
                        resume: None,
                        keep_checkpoint: false,
                        no_resident: false,
                        threads: None,
                        timing: false,
                        fail_on_low_yield: false,
                    },
                })),
            },
        };
        assert_eq!(ErrorMode::from_cli(&cli), ErrorMode::Robot);
    }

    #[test]
    fn ocr_args_validate_rejects_negative_size() {
        let args = OcrArgs {
            request: OcrRequestArgs {
                image: PathBuf::from("scan.png"),
                model: None,
                base_size: Some(-1),
                image_size: None,
                crop_mode: Some(CropMode::Gundam),
                max_length: None,
                temperature: None,
                no_repeat_ngram: None,
                ngram_window: None,
                max_page_tokens: None,
                format: false,
                task: OcrTask::Ocr,
                question: None,
                region_box: None,
                color: None,
                pages: None,
                split_spreads: false,
                multi_page: false,
                page_window: None,
                resume: None,
                keep_checkpoint: false,
                no_resident: false,
                threads: None,
                timing: false,
                fail_on_low_yield: false,
            },
            json: false,
            output: None,
            extract_figures: false,
            figures_dir: None,
            robot: false,
            check: false,
            raw: false,
        };
        let err = args.to_request().expect_err("negative base-size is usage");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
        assert_eq!(err.exit_code(), 2);
    }

    #[test]
    fn output_is_json_follows_extension_case_insensitively() {
        assert!(output_is_json(Some(Path::new("out.json"))));
        assert!(output_is_json(Some(Path::new("OUT.JSON"))));
        assert!(output_is_json(Some(Path::new("/tmp/a/b.Json"))));
        // A `.md` / other / missing extension stays markdown.
        assert!(!output_is_json(Some(Path::new("out.md"))));
        assert!(!output_is_json(Some(Path::new("out.txt"))));
        assert!(!output_is_json(Some(Path::new("out"))));
        assert!(!output_is_json(None));
    }

    #[test]
    fn ocr_output_flag_parses_short_and_long() {
        for flag in ["-o", "--output"] {
            let cli = Cli::try_parse_from(["focr", "ocr", "scan.png", flag, "result.json"])
                .expect("ocr -o/--output parses");
            let Command::Ocr(args) = cli.command else {
                unreachable!("expected ocr command");
            };
            assert_eq!(args.output.as_deref(), Some(Path::new("result.json")));
        }
        // No `-o` => None, i.e. the legacy stdout path.
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png"]).expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        assert!(args.output.is_none());
    }

    #[test]
    fn ocr_format_flag_threads_to_request() {
        // `--format` (GOT `OCR with format:` .mmd mode) parses and reaches OcrRequest;
        // absent, it defaults false (plain OCR — byte-identical to today).
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png", "--format"])
            .expect("ocr --format parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        assert!(args.to_request().expect("request builds").format);
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png"]).expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        assert!(!args.to_request().expect("request builds").format);
    }

    /// Parse `focr ocr <argv…>` and build the request (panics on non-ocr).
    fn ocr_request_from(argv: &[&str]) -> FocrResult<OcrRequest> {
        let full: Vec<&str> = ["focr", "ocr"].iter().chain(argv).copied().collect();
        let cli = Cli::try_parse_from(full).expect("ocr argv parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        args.to_request()
    }

    #[test]
    fn ocr_task_flag_threads_format_to_request() {
        // Each got-ocr2 structured task implies `--format` (the same engine seam
        // `--format` uses); `--task ocr` / no `--task` stay plain (format=false),
        // byte-identical to today.
        for task in [
            "formula",
            "tables",
            "chart",
            "molecular",
            "geometry",
            "music",
        ] {
            let req =
                ocr_request_from(&["scan.png", "--task", task, "--model", "got-ocr2.int8.focrq"])
                    .expect("request builds");
            assert!(req.format, "--task {task} must imply format");
        }
        let req = ocr_request_from(&["scan.png", "--task", "ocr"]).expect("request builds");
        assert!(!req.format, "--task ocr stays plain");
        let req = ocr_request_from(&["scan.png"]).expect("request builds");
        assert!(!req.format, "default task stays plain");
    }

    #[test]
    fn only_chart_and_formula_pad_the_got_image() {
        for (task, pads) in [
            ("chart", true),
            ("formula", true),
            ("tables", false),
            ("molecular", false),
            ("geometry", false),
            ("music", false),
        ] {
            let req =
                ocr_request_from(&["scan.png", "--task", task, "--model", "got-ocr2.int8.focrq"])
                    .expect("request builds");
            assert_eq!(req.square_pad, pads, "--task {task}");
        }
        let req = ocr_request_from(&["scan.png", "--format", "--model", "got-ocr2.int8.focrq"])
            .expect("request builds");
        assert!(!req.square_pad, "`--format` alone is the upstream squash");
    }

    /// bd-1sj1: `--box` takes a box or a point in pixels, brackets and spaces
    /// optional, and `--color` one of GOT's three frame colours.
    #[test]
    fn box_and_color_name_a_got_region() {
        use native_engine::got::{FrameColor, Region};
        let got = ["--model", "got-ocr2.int8.focrq"];
        for (spec, want) in [
            ("10,20,300,400", Region::Box([10.0, 20.0, 300.0, 400.0])),
            (
                "[10, 20.5, 300, 400]",
                Region::Box([10.0, 20.5, 300.0, 400.0]),
            ),
            ("7,8", Region::Point([7.0, 8.0])),
        ] {
            let req = ocr_request_from(&[&["scan.png", "--box", spec][..], &got[..]].concat())
                .expect("request builds");
            assert_eq!(req.region, Some(want), "--box {spec}");
        }
        let argv = [&["scan.png", "--color", "blue", "--format"][..], &got[..]].concat();
        let req = ocr_request_from(&argv).expect("request builds");
        assert_eq!(req.region, Some(Region::Color(FrameColor::Blue)));
        assert!(req.format, "a region composes with --format");
        // A colour frame survives the pad; a box does not.
        let argv = [
            &["scan.png", "--color", "red", "--task", "chart"][..],
            &got[..],
        ]
        .concat();
        let req = ocr_request_from(&argv).expect("request builds");
        assert!(req.square_pad && req.region.is_some());
        assert_eq!(
            ocr_request_from(&["scan.png"])
                .expect("request builds")
                .region,
            None
        );
    }

    #[test]
    fn a_region_is_refused_where_got_would_not_read_it() {
        let got = ["--model", "got-ocr2.int8.focrq"];
        for (argv, says) in [
            (vec!["--box", "1,2,3"], "3 values"),
            (vec!["--box", "1,2,3,4,5"], "5 values"),
            (vec!["--box", "10,20,5,40"], "below and to the right"),
            (vec!["--box", "10,-1,20,40"], "non-negative"),
            (vec!["--box", "a,b"], "non-negative"),
            (vec!["--box", ""], "non-negative"),
            (
                vec!["--box", "1,2,3,4", "--task", "chart"],
                "pads it to a square",
            ),
            (
                vec!["--box", "1,2,3,4", "--task", "formula"],
                "pads it to a square",
            ),
        ] {
            let argv = [&["scan.png"][..], &argv[..], &got[..]].concat();
            let err = ocr_request_from(&argv).expect_err("refused");
            assert!(matches!(err, FocrError::Usage(_)), "{argv:?}: {err}");
            assert!(err.to_string().contains(says), "{argv:?}: {err}");
        }
        for argv in [
            vec!["scan.png", "--box", "1,2,3,4"],
            vec![
                "scan.png",
                "--color",
                "red",
                "--model",
                "unlimited-ocr.int8.focrq",
            ],
            vec![
                "scan.png",
                "--color",
                "red",
                "--task",
                "describe",
                "--model",
                "smolvlm2.int8.focrq",
            ],
            vec![
                "scan.png",
                "--color",
                "red",
                "--task",
                "chart-data",
                "--model",
                "onechart.int8.focrq",
            ],
        ] {
            let err = ocr_request_from(&argv).expect_err("refused");
            assert!(matches!(err, FocrError::Usage(_)), "{argv:?}: {err}");
            assert!(err.to_string().contains("got-ocr2"), "{argv:?}: {err}");
        }
        // Both at once, or a colour GOT was not trained on, is clap's usage error.
        for argv in [
            vec![
                "focr", "ocr", "scan.png", "--box", "1,2,3,4", "--color", "red",
            ],
            vec!["focr", "ocr", "scan.png", "--color", "purple"],
        ] {
            let Err(err) = Cli::try_parse_from(&argv) else {
                panic!("{argv:?}: clap accepted it");
            };
            assert_eq!(err.exit_code(), 2, "{argv:?}");
        }
    }

    #[test]
    fn ocr_task_composes_with_explicit_format() {
        // Explicit `--format` wins / is idempotent: `--task ocr --format` keeps
        // format=true (the task default never masks the flag), and adding
        // `--format` to a format-implying task changes nothing.
        let req =
            ocr_request_from(&["scan.png", "--task", "ocr", "--format"]).expect("request builds");
        assert!(req.format, "--format must not be masked by --task ocr");
        let with_both = ocr_request_from(&[
            "scan.png",
            "--task",
            "tables",
            "--format",
            "--model",
            "got-ocr2.int8.focrq",
        ])
        .expect("request builds");
        let task_only = ocr_request_from(&[
            "scan.png",
            "--task",
            "tables",
            "--model",
            "got-ocr2.int8.focrq",
        ])
        .expect("request builds");
        assert!(
            with_both.format && task_only.format,
            "--format is idempotent with --task"
        );
    }

    #[test]
    fn ocr_task_describe_fails_clean_naming_smolvlm2() {
        // `describe` (C9) needs the smolvlm2 model: the default resolution is
        // knowably unlimited-ocr, so guide (Usage, exit 2) instead of silently
        // running plain OCR — the got-only-task precedent.
        let err = ocr_request_from(&["photo.jpg", "--task", "describe"])
            .expect_err("describe against the default model must guide");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
        assert_eq!(err.exit_code(), 2);
        let msg = err.to_string();
        assert!(
            msg.contains("smolvlm2"),
            "must name the required model: {msg}"
        );
        // A smolvlm2 model spec passes through and carries the question.
        let req = ocr_request_from(&[
            "photo.jpg",
            "--task",
            "describe",
            "--model",
            "smolvlm2.int8.focrq",
            "--question",
            "What color is the car?",
        ])
        .expect("describe with a smolvlm2 model spec");
        assert_eq!(req.question.as_deref(), Some("What color is the car?"));
        assert!(!req.format, "describe must not imply GOT --format");
        // `--question` without `--task describe` is a usage error.
        let err = ocr_request_from(&["photo.jpg", "--question", "what?"])
            .expect_err("--question requires --task describe");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
        // A got/unlimited model spec is knowably wrong for describe.
        let err = ocr_request_from(&[
            "photo.jpg",
            "--task",
            "describe",
            "--model",
            "got-ocr2.int8.focrq",
        ])
        .expect_err("describe against a got model must guide");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
    }

    #[test]
    fn ocr_task_got_only_task_guides_to_got_model() {
        // A `--model` that knowably names unlimited-ocr cannot serve a got-only
        // task: Usage guidance (exit 2) pointing at `focr pull got-ocr2`.
        let err = ocr_request_from(&[
            "scan.png",
            "--task",
            "formula",
            "--model",
            "unlimited-ocr.int8.focrq",
        ])
        .expect_err("unlimited-ocr cannot serve --task formula");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
        assert_eq!(err.exit_code(), 2);
        let msg = err.to_string();
        assert!(
            msg.contains("focr pull got-ocr2"),
            "must carry the pull hint: {msg}"
        );
        assert!(
            msg.contains("--task formula"),
            "must name the offending task: {msg}"
        );

        // No `--model` ⇒ the default resolution (always unlimited-ocr) — same
        // guidance. Read-only env guard (no set_var under deny(unsafe)): only
        // assert when FOCR_MODEL_PATH is not overriding the default; the pure
        // classifier below covers the None case unconditionally.
        if std::env::var_os(crate::MODEL_PATH_ENV).is_none() {
            let err = ocr_request_from(&["scan.png", "--task", "music"])
                .expect_err("default model cannot serve --task music");
            assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
        }

        // A got-named model passes and carries format (case-insensitive name).
        let req = ocr_request_from(&[
            "scan.png",
            "--task",
            "geometry",
            "--model",
            "/models/GOT-OCR2.int8.focrq",
        ])
        .expect("got model serves geometry");
        assert!(req.format);

        // The pure classifier: default/unlimited are knowably-not-got; a got or
        // ambiguous name passes through to the engine's arch-tag dispatch.
        assert!(model_spec_is_knowably_not_got(None));
        assert!(model_spec_is_knowably_not_got(Some(Path::new(
            "/m/unlimited-ocr.int8.focrq"
        ))));
        assert!(!model_spec_is_knowably_not_got(Some(Path::new(
            "got-ocr2.int8.focrq"
        ))));
        assert!(!model_spec_is_knowably_not_got(Some(Path::new(
            "/m/custom.focrq"
        ))));
    }

    #[test]
    fn ocr_task_rejects_unknown_value_and_composes_with_robot_run() {
        // Clap owns the value set: an unknown task is a parse error (usage).
        assert!(Cli::try_parse_from(["focr", "ocr", "scan.png", "--task", "poetry"]).is_err());
        // `focr robot run` flattens the same OcrRequestArgs, so `--task`
        // composes with robot mode identically.
        let cli = Cli::try_parse_from([
            "focr",
            "robot",
            "run",
            "scan.png",
            "--task",
            "chart",
            "--model",
            "got-ocr2.int8.focrq",
        ])
        .expect("robot run --task parses");
        let Command::Robot {
            cmd: RobotCmd::Run(args),
        } = cli.command
        else {
            unreachable!("expected robot run");
        };
        assert!(args.request.to_request().expect("request builds").format);
    }

    #[test]
    fn preprocess_flags_become_overrides_only_when_explicit() {
        // Defaults ⇒ NO overrides: the engine keeps its certified Base-1024.
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png"]).expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let req = args.to_request().expect("request builds");
        assert_eq!(
            preprocess_overrides_from(&req),
            native_engine::PreprocessOverrides::default()
        );

        // Explicit flags ⇒ each maps onto the engine overrides, an explicit
        // `--crop-mode base` included (U2-E1).
        let cli = Cli::try_parse_from([
            "focr",
            "ocr",
            "scan.png",
            "--base-size",
            "512",
            "--image-size",
            "512",
            "--crop-mode",
            "gundam",
        ])
        .expect("ocr with preprocess flags parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let o = preprocess_overrides_from(&args.to_request().expect("request builds"));
        assert_eq!(o.base_size, Some(512));
        assert_eq!(o.image_size, Some(512));
        assert_eq!(o.gundam, Some(true));

        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png", "--crop-mode", "base"])
            .expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let o = preprocess_overrides_from(&args.to_request().expect("request builds"));
        assert_eq!(o.gundam, Some(false));
    }

    #[test]
    fn tuning_flags_become_decode_overrides_only_when_explicit() {
        // Default flags ⇒ NO overrides: engine defaults + env (FOCR_MAX_NEW_TOKENS)
        // stay in force.
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png"]).expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let req = args.to_request().expect("request builds");
        assert_eq!(
            decode_overrides_from(&req),
            native_engine::DecodeOverrides::default()
        );

        // Explicit flags ⇒ each maps to Some(value) on the engine overrides.
        let cli = Cli::try_parse_from([
            "focr",
            "ocr",
            "scan.png",
            "--max-length",
            "700",
            "--temperature",
            "0",
            "--no-repeat-ngram",
            "20",
            "--ngram-window",
            "1024",
            "--max-page-tokens",
            "0",
        ])
        .expect("ocr with tuning flags parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let o = decode_overrides_from(&args.to_request().expect("request builds"));
        assert_eq!(o.max_length, Some(700));
        assert_eq!(o.temperature, Some(0.0));
        assert_eq!(o.no_repeat_ngram, Some(20));
        assert_eq!(o.ngram_window, Some(1024));
        assert_eq!(o.max_page_tokens, Some(0));

        // An explicit value equal to unlimited-ocr's default is still forwarded:
        // another model's defaults differ (U2-E1).
        let cli = Cli::try_parse_from([
            "focr",
            "ocr",
            "scan.png",
            "--max-length",
            "32768",
            "--no-repeat-ngram",
            "35",
            "--ngram-window",
            "128",
            "--temperature",
            "0",
        ])
        .expect("ocr parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        let o = decode_overrides_from(&args.to_request().expect("request builds"));
        assert_eq!(o.max_length, Some(32_768));
        assert_eq!(o.no_repeat_ngram, Some(35));
        assert_eq!(o.ngram_window, Some(128));
        assert_eq!(o.temperature, Some(0.0));
    }

    /// bd-d630: every sampler refuses `temperature > 0`, so the request does
    /// too, before any model loads, instead of exiting 1 after the load.
    #[test]
    fn a_nonzero_temperature_is_refused_before_a_model_loads() {
        for value in ["0.5", "1", "inf", "NaN"] {
            let cli = Cli::try_parse_from(["focr", "ocr", "scan.png", "--temperature", value])
                .expect("the flag parses as a number");
            let Command::Ocr(args) = cli.command else {
                unreachable!("expected ocr command");
            };
            assert!(
                matches!(
                    args.to_request(),
                    Err(FocrError::Usage(message)) if message.contains("decodes greedily")
                ),
                "--temperature {value}"
            );
        }
    }

    #[test]
    fn single_image_json_carries_markdown_and_bounding_boxes() {
        let rec = Recognition::Single(native_engine::RecognizedDocument {
            markdown: "# Title\n\nbody".to_string(),
            raw: "<|ref|>title<|/ref|><|det|>[[1, 2, 3, 4]]<|/det|>\n# Title\n\nbody".to_string(),
            layout: vec![
                native_engine::LayoutSpan {
                    label: "title".to_string(),
                    boxes: vec![[10, 20, 110, 60]],
                    level: None,
                    text: Some("# Title".to_string()),
                },
                native_engine::LayoutSpan {
                    label: "title".to_string(),
                    boxes: vec![[10, 70, 110, 90]],
                    level: Some(2),
                    text: None,
                },
            ],
        });
        let json = rec.to_json(&[], false);
        assert_eq!(json["schema_version"], robot::ROBOT_SCHEMA_VERSION);
        assert_eq!(json["markdown"], "# Title\n\nbody");
        assert_eq!(json["layout"][0]["label"], "title");
        assert_eq!(
            json["layout"][0]["boxes"][0],
            serde_json::json!([10, 20, 110, 60])
        );
        // `level` only on a leveled v2 title (U2-E3b): v1 entries keep their shape.
        assert!(json["layout"][0].get("level").is_none());
        assert_eq!(json["layout"][1]["level"], 2);
        // `text` only on a span with text, and the raw decode only when asked.
        assert_eq!(json["layout"][0]["text"], "# Title");
        assert!(json["layout"][1].get("text").is_none());
        assert!(json.get("raw").is_none());
        assert_eq!(rec.to_json(&[], true)["raw"], rec.raw());
        // A single image has no per-page `pages` array.
        assert!(json.get("pages").is_none());
    }

    /// `--raw` swaps a text output and adds to a JSON one; the markdown stays.
    #[test]
    fn raw_replaces_text_and_joins_json() {
        let rec = Recognition::Document(DocumentRecognition {
            markdown: "md".to_string(),
            raw: "whole".to_string(),
            pages: DocumentPageList::Layouts(vec![DocumentPageLayout {
                page: 1,
                half: None,
                raw: "page one".to_string(),
                layout: vec![],
            }]),
        });
        assert_eq!(rec.text(false), "md");
        assert_eq!(rec.text(true), "whole");
        let plain = rec.to_json(&[], false);
        assert!(plain.get("raw").is_none());
        assert!(plain["pages"][0].get("raw").is_none());
        let json = rec.to_json(&[], true);
        assert_eq!(json["markdown"], "md");
        assert_eq!(json["raw"], "whole");
        assert_eq!(json["pages"][0]["raw"], "page one");
    }

    /// bd-gftg: a run whose pages did not stream hands its text to a robot
    /// consumer as decoded `page` events: page 1 for an image, one per page
    /// (with its half) for a page-by-page document, none for a cross-page parse.
    #[test]
    fn unstreamed_pages_become_decoded_page_events() {
        let single = Recognition::Single(native_engine::RecognizedDocument {
            markdown: "so far".to_string(),
            raw: " so far \n".to_string(),
            layout: vec![],
        });
        let events = single.unstreamed_page_events();
        assert_eq!(events, [robot::page_decoded_event(1, "so far")]);
        assert_eq!(events[0]["status"], "decoded");

        let pages = Recognition::Document(DocumentRecognition {
            markdown: "md".to_string(),
            raw: "whole".to_string(),
            pages: DocumentPageList::Layouts(vec![
                DocumentPageLayout {
                    page: 3,
                    half: None,
                    raw: "page three".to_string(),
                    layout: vec![],
                },
                DocumentPageLayout {
                    page: 4,
                    half: Some("left"),
                    raw: "left half\n".to_string(),
                    layout: vec![],
                },
            ]),
        });
        let mut left = robot::page_decoded_event(4, "left half");
        left["half"] = "left".into();
        assert_eq!(
            pages.unstreamed_page_events(),
            [robot::page_decoded_event(3, "page three"), left]
        );

        let read = Recognition::Document(DocumentRecognition {
            markdown: "md".to_string(),
            raw: "whole".to_string(),
            pages: DocumentPageList::Read(Vec::new()),
        });
        assert!(read.unstreamed_page_events().is_empty());
    }

    /// U2-E3b: the resident daemon's wire carries a span whole, `level` and
    /// `text` included.
    #[test]
    fn a_layout_span_round_trips_its_json() {
        for (level, text) in [(None, None), (Some(1), Some("body".to_string()))] {
            let span = native_engine::LayoutSpan {
                label: "title".to_string(),
                boxes: vec![[1, 2, 3, 4], [5, 6, 7, 8]],
                level,
                text,
            };
            let back = native_engine::LayoutSpan::from_json(&span.to_json());
            assert_eq!(back, Some(span));
        }
        assert_eq!(
            native_engine::LayoutSpan::from_json(&serde_json::json!({"boxes": []})),
            None
        );
    }

    /// bd-av64.11: the --pages spec parser — 1-based pages/ranges to
    /// deduplicated source-order 0-based indices, with loud usage errors.
    /// bd-av64.2: the --json staves array interleaves recognized and skipped
    /// staves in DETECTION order, 1-based, with reasons only on skips.
    #[test]
    fn music_meta_json_interleaves_in_detection_order() {
        let meta = native_engine::MusicPageMeta {
            staves: vec![(0, (0, 10, 800, 100)), (2, (0, 300, 800, 100))],
            skips: vec![native_engine::tromr::StaffSkip {
                index: 1,
                bbox: (0, 150, 800, 90),
                reason: "resized width 1296 exceeds the 1280 position clamp".into(),
            }],
            warnings: Vec::new(),
        };
        let v = music_meta_to_json(&meta);
        let arr = v.as_array().expect("array");
        assert_eq!(arr.len(), 3);
        assert_eq!(arr[0]["staff"], 1);
        assert_eq!(arr[0]["status"], "ok");
        assert!(arr[0].get("reason").is_none());
        assert_eq!(arr[1]["staff"], 2);
        assert_eq!(arr[1]["status"], "skipped");
        assert!(
            arr[1]["reason"].as_str().unwrap_or("").contains("1280"),
            "skip carries the reason"
        );
        assert_eq!(arr[2]["staff"], 3);
        assert_eq!(arr[2]["bbox"], serde_json::json!([0, 300, 800, 100]));
    }

    #[test]
    fn page_spec_parses_and_rejects() {
        // The `--pages` grammar the CLI hands its page source.
        let parse = crate::page_source::select_pages;
        // None => every page.
        assert_eq!(parse(None, 3).unwrap(), vec![0, 1, 2]);
        assert_eq!(parse(Some("3"), 218).unwrap(), vec![2]);
        assert_eq!(parse(Some("3-7"), 10).unwrap(), vec![2, 3, 4, 5, 6]);
        assert_eq!(
            parse(Some("1,5-9,218"), 218).unwrap(),
            vec![0, 4, 5, 6, 7, 8, 217]
        );
        // Overlap/duplicates dedupe; output is source-ordered.
        assert_eq!(parse(Some("5-7,6,1"), 10).unwrap(), vec![0, 4, 5, 6]);
        // Round-trip property: rendering the indices back as 1-based pages
        // and reparsing is a fixed point.
        let idx = parse(Some("2,4-6"), 9).unwrap();
        let rendered = idx
            .iter()
            .map(|i| (i + 1).to_string())
            .collect::<Vec<_>>()
            .join(",");
        assert_eq!(parse(Some(&rendered), 9).unwrap(), idx);
        for bad in ["", " ", ",", "0", "abc", "3-2", "1-", "-4", "300"] {
            let err = parse(Some(bad), 218).unwrap_err();
            assert!(
                matches!(err, FocrError::Usage(_)),
                "{bad:?} must be a usage error, got {err:?}"
            );
            assert!(
                err.to_string().contains("218"),
                "{bad:?}: error names the page count: {err}"
            );
        }
    }

    /// U2-E3: a `--multi-page` run's figures are cropped from each page's
    /// raster fetched again from the source, named by source page and half,
    /// and referenced from that page's markdown. A page without figures is
    /// not fetched or changed.
    #[test]
    fn document_figures_are_cropped_from_refetched_pages_and_named_by_half() {
        let dir = std::env::temp_dir().join(format!("focr_cli_doc_figs_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("temp dir");
        let synth = crate::page_source::tests::synth_page;
        synth(200, 300, &[(40, 160)])
            .save(dir.join("1.png"))
            .expect("write page 1");
        synth(800, 500, &[(50, 350), (450, 750)])
            .save(dir.join("2.png"))
            .expect("write the spread");
        synth(200, 300, &[(40, 160)])
            .save(dir.join("3.png"))
            .expect("write page 3");
        let request = ocr_args_with(|a| {
            a.request.image = dir.clone();
            a.request.split_spreads = true;
        })
        .to_request()
        .expect("request");
        // The pass's pages, rasters dropped: 1, 2 left, 2 right, 3.
        let walked: Vec<PageItem> = open_page_source(&request).expect("open").collect();
        let boxes = [[30, 20, 90, 70], [40, 30, 140, 230], [10, 50, 210, 90]];
        let mut pages: Vec<native_engine::PageResult> = walked
            .iter()
            .map(|item| {
                let k = item.index;
                let token = format!("![](images/page_{k}_0.jpg)");
                let figures = boxes
                    .get(k)
                    .map(|&b| native_engine::postprocess::FigureRef {
                        index: 0,
                        label: "image".to_string(),
                        boxes: vec![b],
                        markdown_ref: token.clone(),
                    })
                    .into_iter()
                    .collect();
                native_engine::PageResult {
                    run_index: k + 1,
                    source_page: item.source_page,
                    half: item.half,
                    window: None,
                    size: (640, 480),
                    text: format!("before\n{token}"),
                    raw: String::new(),
                    layout: Vec::new(),
                    figures,
                    tokens: Some(1),
                    finish: Some(native_engine::PageFinish::Marker),
                    elapsed_ms: Some(1),
                    model_id: native_engine::model_arch::UNLIMITED_OCR_V2_ID,
                }
            })
            .collect();
        assert_eq!(
            pages
                .iter()
                .map(|p| (p.source_page, p.half))
                .collect::<Vec<_>>(),
            [
                (1, None),
                (2, Some(Half::Left)),
                (2, Some(Half::Right)),
                (3, None)
            ]
        );
        let plan = FigurePlan {
            dir: dir.join("figs"),
            ref_prefix: "figs/".to_string(),
        };
        let written = write_page_figures(&request, &mut pages, &plan).expect("figures");
        let names: Vec<&str> = written.iter().map(|w| w.path.as_str()).collect();
        assert_eq!(
            names,
            [
                "figs/page1_figure_1.png",
                "figs/page2l_figure_1.png",
                "figs/page2r_figure_1.png"
            ]
        );
        for ((page, item), want) in pages.iter().zip(&walked).zip(&written) {
            assert_eq!(page.text, format!("before\n![figure 1]({})", want.path));
            assert_eq!((want.page, want.half), (page.source_page, page.half));
            // The crop is the walk's raster at the box, pixel for pixel.
            let [x1, y1, x2, y2] = boxes[item.index];
            assert_eq!(want.bbox, [x1, y1, x2, y2]);
            let raster = item.raster.as_ref().expect("rasterized");
            #[allow(clippy::cast_sign_loss)]
            let expected = raster
                .crop_imm(x1 as u32, y1 as u32, (x2 - x1) as u32, (y2 - y1) as u32)
                .to_luma8();
            let file = dir.join(want.path.as_str());
            let got = image::open(&file).expect("figure decodes").to_luma8();
            assert_eq!(got, expected, "{}", file.display());
        }
        assert_eq!(pages[3].text, "before\n![](images/page_3_0.jpg)");
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// U2-D0: a first-run download re-runs the recognition attempt, and the
    /// retry must read the whole selection again from a fresh page source,
    /// never resume the one the failed attempt consumed.
    #[test]
    fn a_retried_attempt_reopens_the_page_source_and_reads_the_same_pages() {
        let dir = std::env::temp_dir().join(format!("focr_cli_retry_{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("temp dir");
        for (n, width) in [(1u32, 30u32), (2, 40), (3, 50)] {
            image::RgbImage::from_pixel(width, 60, image::Rgb([200, 100, 50]))
                .save(dir.join(format!("p{n}.png")))
                .expect("write page");
        }
        let request = ocr_args_with(|a| {
            a.request.image = dir.clone();
            a.request.pages = Some("3,1".into());
        })
        .to_request()
        .expect("request");
        let walk = |source: PageSource| -> Vec<(usize, Vec<u8>)> {
            source
                .map(|item| {
                    let raster = item.raster.expect("page rasterizes");
                    (item.source_page, raster.as_bytes().to_vec())
                })
                .collect()
        };
        let expected = walk(open_page_source(&request).expect("open"));
        assert_eq!(
            expected.iter().map(|(page, _)| *page).collect::<Vec<_>>(),
            vec![1, 3]
        );

        let opened = std::cell::Cell::new(Some(open_page_source(&request).expect("open")));
        // The first attempt reads one page, then fails (a missing model).
        let mut first = attempt_source(&opened, &request).expect("first attempt");
        assert_eq!(first.next().map(|item| item.source_page), Some(1));
        drop(first);
        // The retry gets a fresh source and reads the same pages.
        let retry = attempt_source(&opened, &request).expect("retry");
        assert_eq!(walk(retry), expected);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn pdf_json_carries_per_page_layout_with_one_based_page_numbers() {
        let rec = Recognition::Document(DocumentRecognition {
            markdown: "p1\n\np2".to_string(),
            raw: "p1\n\np2".to_string(),
            pages: DocumentPageList::Layouts(vec![
                DocumentPageLayout {
                    page: 1,
                    half: None,
                    raw: "p1".to_string(),
                    layout: vec![native_engine::LayoutSpan {
                        label: "text".to_string(),
                        boxes: vec![[0, 0, 5, 5]],
                        level: None,
                        text: None,
                    }],
                },
                DocumentPageLayout {
                    page: 2,
                    half: None,
                    raw: "p2".to_string(),
                    layout: vec![],
                },
            ]),
        });
        let json = rec.to_json(&[], false);
        assert_eq!(json["markdown"], "p1\n\np2");
        assert_eq!(json["pages"][0]["page"], 1);
        assert_eq!(
            json["pages"][0]["layout"][0]["boxes"][0],
            serde_json::json!([0, 0, 5, 5])
        );
        assert_eq!(json["pages"][1]["page"], 2);
        assert_eq!(json["pages"][1]["layout"], serde_json::json!([]));
        // Page-by-page entries keep their shape: no multi-page keys.
        let mut keys: Vec<&str> = json["pages"][0]
            .as_object()
            .expect("an object")
            .keys()
            .map(String::as_str)
            .collect();
        keys.sort_unstable();
        assert_eq!(keys, ["layout", "page"]);
    }

    /// U2-E3: a `--multi-page` document's `pages[]` are its pages as read:
    /// the source page, `half` on a split spread, the run index, the page's
    /// markdown and layout, and the decode facts the model counts. A page
    /// that failed to rasterize has no entry, so source pages skip ahead of
    /// run indices.
    #[test]
    fn multi_page_json_carries_each_page_as_read() {
        let span = native_engine::LayoutSpan {
            label: "title".to_string(),
            boxes: vec![[1, 2, 3, 4]],
            level: Some(1),
            text: None,
        };
        let page = |run_index, source_page, half, finish| native_engine::PageResult {
            run_index,
            source_page,
            half,
            window: None,
            size: (640, 480),
            text: format!("page {source_page}"),
            raw: format!("raw {run_index}"),
            layout: vec![span.clone()],
            figures: Vec::new(),
            tokens: Some(7),
            finish,
            elapsed_ms: Some(1234),
            model_id: native_engine::model_arch::UNLIMITED_OCR_V2_ID,
        };
        let rec = Recognition::Document(DocumentRecognition {
            markdown: "<PAGE>\npage 1\n<PAGE>\npage 3\n<PAGE>\npage 3".to_string(),
            raw: "<PAGE>\nraw 1\n<PAGE>\nraw 2\n<PAGE>\nraw 3".to_string(),
            pages: DocumentPageList::Read(vec![
                page(1, 1, None, Some(native_engine::PageFinish::Marker)),
                page(
                    2,
                    3,
                    Some(Half::Left),
                    Some(native_engine::PageFinish::PageCap),
                ),
                page(
                    3,
                    3,
                    Some(Half::Right),
                    Some(native_engine::PageFinish::Eos),
                ),
            ]),
        });
        let json = rec.to_json(&[], false);
        assert_eq!(
            json["pages"][0],
            serde_json::json!({
                "page": 1, "run_index": 1, "width": 640, "height": 480, "text": "page 1",
                "tokens": 7, "finish": "marker",
                "layout": [{"label": "title", "boxes": [[1, 2, 3, 4]], "level": 1}],
            }),
            "no half, no window, and elapsed_ms only on the robot event"
        );
        assert_eq!(rec.to_json(&[], true)["pages"][1]["raw"], "raw 2");
        let sides: Vec<_> = json["pages"]
            .as_array()
            .expect("pages")
            .iter()
            .map(|p| (p["page"].clone(), p["half"].clone(), p["finish"].clone()))
            .collect();
        assert_eq!(
            sides,
            [
                (1.into(), serde_json::Value::Null, "marker".into()),
                (3.into(), "left".into(), "page_cap".into()),
                (3.into(), "right".into(), "eos".into()),
            ]
        );
        // v1 without one body per page: `pages: []`, type-stable.
        let merged = Recognition::Document(DocumentRecognition {
            markdown: "<PAGE>\nall".to_string(),
            raw: "<PAGE>\nall".to_string(),
            pages: DocumentPageList::Read(Vec::new()),
        });
        assert_eq!(merged.to_json(&[], false)["pages"], serde_json::json!([]));
    }

    #[test]
    fn a_batch_row_says_how_its_page_ended() {
        use native_engine::FinishReason;
        let page = Path::new("a.png");
        let mut rows = Vec::new();
        let mut emit =
            |end| emit_batch_result(true, page, 1.0, Ok("text".into()), None, end, &mut rows);

        let clean = PageEnd {
            finish_reason: Some(FinishReason::Stop),
            ..PageEnd::default()
        };
        assert!(emit(clean).is_none());
        // `focr ocr` exits 0 on a v1 length stop, and so does this row.
        let capped = PageEnd {
            finish_reason: Some(FinishReason::Length),
            ..PageEnd::default()
        };
        assert!(emit(capped).is_none());
        let stopped = PageEnd {
            finish_reason: Some(FinishReason::Budget),
            partial: Some(FocrError::Timeout("stopped early".into())),
            ..PageEnd::default()
        };
        let failure = emit(stopped).expect("a stopped page is a failed page");
        assert_eq!(failure.exit_code(), 5);

        assert_eq!(rows[0]["ok"], true);
        assert_eq!(rows[0]["finish_reason"], "stop");
        assert!(rows[0].get("error").is_none());
        assert_eq!(rows[1]["ok"], true);
        assert_eq!(rows[1]["finish_reason"], "length");
        assert_eq!(rows[2]["ok"], false);
        assert_eq!(rows[2]["finish_reason"], "budget");
        assert_eq!(rows[2]["markdown"], "text");
        assert!(rows[2]["error"].as_str().unwrap().contains("stopped early"));
    }

    #[test]
    fn a_chart_keeps_its_head_whether_or_not_it_warned() {
        let chart = |reliable: Option<bool>| native_engine::ChartPageMeta {
            pred_locs: vec![0.25, 1.0],
            reliable_distance: reliable.map(|_| 0.01),
            reliable,
        };
        let run = |meta: &native_engine::ChartPageMeta| {
            let warnings: Vec<_> = native_engine::chart_warning(meta).into_iter().collect();
            let mut value = serde_json::json!({ "markdown": "x" });
            RunExtras {
                chart: Some(meta),
                warnings: &warnings,
                ..RunExtras::default()
            }
            .merge_into(&mut value);
            value
        };

        let verified = run(&chart(Some(true)));
        assert_eq!(
            verified["chart"]["pred_locs"],
            serde_json::json!([0.25, 1.0])
        );
        assert_eq!(verified["chart"]["reliable"], true);
        assert!(verified.get("warnings").is_none());

        let unverified = run(&chart(None));
        assert_eq!(
            unverified["chart"]["pred_locs"],
            serde_json::json!([0.25, 1.0])
        );
        assert!(unverified["chart"]["reliable"].is_null());
        assert!(unverified["chart"]["reliable_distance"].is_null());
        assert_eq!(unverified["warnings"][0]["kind"], "chart_unverified");

        let mut other = serde_json::json!({ "markdown": "x" });
        RunExtras::default().merge_into(&mut other);
        assert!(other.get("chart").is_none());
    }

    #[test]
    fn write_ocr_output_writes_markdown_and_json_with_boxes() {
        let dir = std::env::temp_dir().join(format!("focr_output_test_{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let rec = Recognition::Single(native_engine::RecognizedDocument {
            markdown: "hello world".to_string(),
            raw: "<|ref|>text<|/ref|><|det|>[[1, 2, 3, 4]]<|/det|>\nhello world".to_string(),
            layout: vec![native_engine::LayoutSpan {
                label: "text".to_string(),
                boxes: vec![[1, 2, 3, 4]],
                level: None,
                text: Some("hello world".to_string()),
            }],
        });

        // Markdown form: source lacks a trailing newline, so one is appended.
        let md_path = dir.join("out.md");
        let text = OutputShape {
            json: false,
            raw: false,
        };
        write_ocr_output(&md_path, &rec, text, &[], RunExtras::default()).expect("write md");
        assert_eq!(std::fs::read_to_string(&md_path).unwrap(), "hello world\n");

        // `--raw`: the same file holds the decode, markers and all.
        let raw_shape = OutputShape {
            json: false,
            raw: true,
        };
        write_ocr_output(&md_path, &rec, raw_shape, &[], RunExtras::default()).expect("write raw");
        assert_eq!(
            std::fs::read_to_string(&md_path).unwrap(),
            "<|ref|>text<|/ref|><|det|>[[1, 2, 3, 4]]<|/det|>\nhello world\n"
        );

        // JSON form: valid JSON, newline-terminated, carrying the bounding boxes.
        let json_path = dir.join("out.json");
        let model = native_engine::ModelIdentity {
            model_id: "unlimited-ocr",
            source_sha256: Some("cd".repeat(32)),
        };
        let json = OutputShape {
            json: true,
            raw: false,
        };
        let extras = RunExtras {
            model: Some(&model),
            finish_reason: Some(native_engine::FinishReason::Length),
            ..RunExtras::default()
        };
        write_ocr_output(&json_path, &rec, json, &[], extras).expect("write json");
        let raw = std::fs::read_to_string(&json_path).unwrap();
        assert!(raw.ends_with('\n'), "json file should end with a newline");
        let parsed: serde_json::Value = serde_json::from_str(&raw).expect("valid json");
        assert_eq!(parsed["markdown"], "hello world");
        assert_eq!(
            parsed["layout"][0]["boxes"][0],
            serde_json::json!([1, 2, 3, 4])
        );
        // U2-E1: the model that ran rides along, and so does how it ended.
        assert_eq!(parsed["model_id"], "unlimited-ocr");
        assert_eq!(parsed["source_sha256"], "cd".repeat(32));
        assert_eq!(parsed["finish_reason"], "length");

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A default `OcrArgs` for the figure-plan tests, mutated by `f`.
    fn ocr_args_with(f: impl FnOnce(&mut OcrArgs)) -> OcrArgs {
        let mut args = OcrArgs {
            request: OcrRequestArgs {
                image: PathBuf::from("scan.png"),
                model: None,
                base_size: None,
                image_size: None,
                crop_mode: None,
                max_length: None,
                temperature: None,
                no_repeat_ngram: None,
                ngram_window: None,
                max_page_tokens: None,
                format: false,
                task: OcrTask::Ocr,
                question: None,
                region_box: None,
                color: None,
                pages: None,
                split_spreads: false,
                multi_page: false,
                page_window: None,
                resume: None,
                keep_checkpoint: false,
                no_resident: false,
                threads: None,
                timing: false,
                fail_on_low_yield: false,
            },
            json: false,
            output: None,
            extract_figures: false,
            figures_dir: None,
            robot: false,
            check: false,
            raw: false,
        };
        f(&mut args);
        args
    }

    #[test]
    fn extract_figures_flag_parses() {
        let cli = Cli::try_parse_from([
            "focr",
            "ocr",
            "scan.png",
            "-o",
            "out.md",
            "--extract-figures",
        ])
        .expect("--extract-figures parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        assert!(args.extract_figures);
        let cli = Cli::try_parse_from(["focr", "ocr", "scan.png", "--figures-dir", "assets"])
            .expect("--figures-dir parses");
        let Command::Ocr(args) = cli.command else {
            unreachable!("expected ocr command");
        };
        assert_eq!(args.figures_dir.as_deref(), Some(Path::new("assets")));
    }

    #[test]
    fn figure_plan_resolves_auto_subfolder_explicit_dir_and_usage_error() {
        // Auto: `<stem>_figures/` next to the `-o` file.
        let plan = FigurePlan::resolve(&ocr_args_with(|a| {
            a.extract_figures = true;
            a.output = Some(PathBuf::from("/a/b/report.md"));
        }))
        .unwrap()
        .expect("enabled");
        assert_eq!(plan.dir, PathBuf::from("/a/b/report_figures"));
        assert_eq!(plan.ref_prefix, "report_figures/");

        // Explicit relative dir: resolved under the output dir; verbatim in refs.
        let plan = FigurePlan::resolve(&ocr_args_with(|a| {
            a.figures_dir = Some(PathBuf::from("assets"));
            a.output = Some(PathBuf::from("/a/b/report.md"));
        }))
        .unwrap()
        .expect("enabled");
        assert_eq!(plan.dir, PathBuf::from("/a/b/assets"));
        assert_eq!(plan.ref_prefix, "assets/");

        // Off when neither flag is set.
        assert!(
            FigurePlan::resolve(&ocr_args_with(|_| {}))
                .unwrap()
                .is_none()
        );

        // `--extract-figures` with no `-o` and no `--figures-dir` is a usage error.
        let err = FigurePlan::resolve(&ocr_args_with(|a| a.extract_figures = true))
            .expect_err("needs a place for the subfolder");
        assert!(matches!(err, FocrError::Usage(_)), "got {err:?}");
    }

    #[test]
    fn choose_figure_format_png_for_flat_jpg_for_photo() {
        // Flat 2-color line-art ⇒ PNG (lossless).
        let mut flat = image::RgbImage::new(64, 64);
        for (i, px) in flat.pixels_mut().enumerate() {
            *px = if i % 9 == 0 {
                image::Rgb([0, 0, 0])
            } else {
                image::Rgb([255, 255, 255])
            };
        }
        assert_eq!(
            choose_figure_format(&image::DynamicImage::ImageRgb8(flat)),
            FigureFormat::Png
        );

        // Many distinct colors (photo-like) ⇒ JPG. A per-pixel `(x*4, y*4, x^y)`
        // ramp gives ~4096 distinct colors (≈1024 after 5-bit quantization), well
        // above the line-art threshold.
        let mut photo = image::RgbImage::new(64, 64);
        for (i, px) in photo.pixels_mut().enumerate() {
            let x = (i % 64) as u8;
            let y = (i / 64) as u8;
            *px = image::Rgb([x.wrapping_mul(4), y.wrapping_mul(4), x ^ (y << 1)]);
        }
        assert_eq!(
            choose_figure_format(&image::DynamicImage::ImageRgb8(photo)),
            FigureFormat::Jpeg
        );
    }

    #[test]
    fn figure_writer_writes_file_and_rewrites_markdown_reference() {
        let dir = std::env::temp_dir().join(format!("focr_figwriter_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let plan = FigurePlan {
            dir: dir.clone(),
            ref_prefix: "figs/".to_string(),
        };
        let mut writer = plan.writer();
        // A flat white image ⇒ PNG; bbox + ref carried through to the record.
        let fig = native_engine::ExtractedFigure {
            index: 0,
            label: "image".to_string(),
            bbox: [5, 6, 25, 16],
            markdown_ref: "![](images/0.jpg)".to_string(),
            image: image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
                20,
                10,
                image::Rgb([255, 255, 255]),
            )),
        };
        let md = writer
            .process_page(
                1,
                None,
                "before ![](images/0.jpg)\nafter",
                vec![fig.clone()],
            )
            .expect("process page");

        // The placeholder is rewritten to `![figure 1](<ref_prefix><name>)`.
        assert!(
            md.contains("![figure 1](figs/page1_figure_1.png)"),
            "md: {md}"
        );
        assert!(!md.contains("images/0.jpg"), "old token gone; md: {md}");
        // The PNG file actually exists.
        assert!(dir.join("page1_figure_1.png").is_file());

        // U2-E3: a spread's halves name their figures by side, so the two
        // halves of page 2 never collide.
        for (half, side) in [(Half::Left, 'l'), (Half::Right, 'r')] {
            let fig = native_engine::ExtractedFigure {
                markdown_ref: "![](images/page_1_0.jpg)".to_string(),
                ..fig.clone()
            };
            let md = writer
                .process_page(2, Some(half), "![](images/page_1_0.jpg)", vec![fig])
                .expect("process a half");
            assert_eq!(md, format!("![figure 1](figs/page2{side}_figure_1.png)"));
            assert!(dir.join(format!("page2{side}_figure_1.png")).is_file());
        }

        // The JSON record carries the relative path, page, half and bbox.
        let written = writer.into_written();
        assert_eq!(written.len(), 3);
        assert_eq!(written[0].path, "figs/page1_figure_1.png");
        assert_eq!(written[0].page, 1);
        assert_eq!(written[0].half, None);
        assert_eq!(written[0].bbox, [5, 6, 25, 16]);
        assert_eq!(
            written[1..]
                .iter()
                .map(|w| (w.page, w.half))
                .collect::<Vec<_>>(),
            [(2, Some(Half::Left)), (2, Some(Half::Right))]
        );

        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn json_appends_figures_array_only_when_present() {
        let rec = Recognition::Single(native_engine::RecognizedDocument {
            markdown: "see ![figure 1](figs/page1_figure_1.png)".to_string(),
            raw: String::new(),
            layout: vec![],
        });
        let figures = vec![
            WrittenFigure {
                label: "image".to_string(),
                page: 1,
                half: None,
                bbox: [1, 2, 3, 4],
                path: "figs/page1_figure_1.png".to_string(),
            },
            WrittenFigure {
                label: "image".to_string(),
                page: 2,
                half: Some(Half::Right),
                bbox: [1, 2, 3, 4],
                path: "figs/page2r_figure_1.png".to_string(),
            },
        ];
        let json = rec.to_json(&figures, false);
        assert_eq!(json["figures"][0]["path"], "figs/page1_figure_1.png");
        assert_eq!(json["figures"][0]["page"], 1);
        assert_eq!(json["figures"][0]["bbox"], serde_json::json!([1, 2, 3, 4]));
        assert!(json["figures"][0].get("half").is_none(), "absent unsplit");
        assert_eq!(json["figures"][1]["half"], "right");
        // No figures ⇒ no `figures` key.
        assert!(rec.to_json(&[], false).get("figures").is_none());
    }

    #[test]
    fn models_json_describes_the_registered_archs() {
        let archs = crate::model_arch::registry();
        assert!(!archs.is_empty());
        let j = model_arch_json(archs[0]);
        assert_eq!(j["id"], "unlimited-ocr");
        assert_eq!(j["status"], "ready");
        assert_eq!(j["implemented"], true);
        assert_eq!(j["tasks"], serde_json::json!(["ocr"]));
        assert_eq!(j["decoder"], "DeepSeekV2MoeRswa");
        assert_eq!(j["vision_encoder"], "SamClip");
        assert!(j["license"].as_str().unwrap_or_default().contains("Baidu"));
    }

    /// Every ready arch has committed distribution provenance and at least one
    /// exact-recipe pull; a planned one is unpublished. An experimental arch
    /// may run from a local conversion before it is published. Recipe
    /// mismatches remain independently fail-closed in the distribution layer.
    #[test]
    fn ready_archs_have_honest_committed_pull_status() {
        use crate::model_arch::Maturity;
        let m = crate::dist::builtin_manifest().expect("embedded manifest parses");
        for a in crate::model_arch::registry() {
            let pull = pull_availability(Some(&m), a.id());
            if a.maturity() == Maturity::Experimental {
                continue;
            }
            if a.maturity() == Maturity::Ready {
                assert!(
                    pull.in_manifest,
                    "{} is runtime-ready but has no manifest entry — publish its \
                     artifacts (bd-av64.7 pattern) or record why not",
                    a.id()
                );
                assert!(
                    !pull.compatible.is_empty(),
                    "{} must retain at least one compatible pull",
                    a.id()
                );
                assert!(pull.blocked.is_empty());
            } else {
                assert!(
                    !pull.in_manifest,
                    "{} is planned-only but published in the manifest",
                    a.id()
                );
            }
        }
    }

    /// U2-E4: a missing `--model <id>` names that id's own pull exactly when
    /// the embedded manifest publishes a compatible one (so v2's hint switches
    /// with its manifest entry); a path or no `--model` keeps the default's.
    #[test]
    fn the_pull_hint_names_the_requested_model_when_it_is_published() {
        let manifest = crate::dist::builtin_manifest().expect("embedded manifest parses");
        for arch in crate::model_arch::registry() {
            let id = arch.id();
            let hint = with_pull_hint("model not found", Some(Path::new(id)));
            let pullable = !pull_availability(Some(&manifest), id).compatible.is_empty();
            assert_eq!(
                hint.contains(&format!("run `focr pull {id}`")),
                pullable,
                "{id}: {hint}"
            );
            assert_eq!(
                hint.contains(&format!("does not publish {id}")),
                !pullable,
                "{id}: {hint}"
            );
        }
        assert!(
            pull_availability(Some(&manifest), "got-ocr2")
                .compatible
                .iter()
                .any(|(quant, _)| quant == "int8"),
            "a published model keeps the positive case exercised"
        );
        for requested in [None, Some(Path::new("/models/custom.focrq"))] {
            assert!(
                with_pull_hint("model not found", requested)
                    .contains("run `focr pull` to install the compatible conservative default"),
                "{requested:?}"
            );
        }
    }

    /// U2-E4: v1's position budget, page merging and prompt-too-long error
    /// name the v2 pull exactly when the embedded manifest publishes a
    /// compatible one; v2's own stops never send a v2 run to `focr pull`.
    #[test]
    fn v1_recoveries_name_the_v2_pull_exactly_when_it_is_published() {
        use native_engine::{WarningKind, warning_recovery};
        let manifest = crate::dist::builtin_manifest().expect("embedded manifest parses");
        let published = !pull_availability(Some(&manifest), V2).compatible.is_empty();
        for kind in [
            WarningKind::V1TruncatedPositions,
            WarningKind::V1PageMerge,
            WarningKind::PromptTooLong,
        ] {
            let recovery = warning_recovery(kind);
            assert_eq!(
                recovery.contains("`focr pull unlimited-ocr-2`, then `--model unlimited-ocr-2`"),
                published,
                "{kind:?}: {recovery}"
            );
        }
        for kind in [
            WarningKind::V2PromptTooLong,
            WarningKind::V2Length,
            WarningKind::V2Budget,
            WarningKind::V2PageCap,
        ] {
            assert!(!warning_recovery(kind).contains("focr pull"), "{kind:?}");
        }
    }

    #[test]
    fn task_name_is_stable_lowercase() {
        use crate::model_arch::Task;
        assert_eq!(task_name(Task::Ocr), "ocr");
        assert_eq!(task_name(Task::Music), "music");
        assert_eq!(task_name(Task::Describe), "describe");
        assert_eq!(task_name(Task::Chart), "chart");
    }

    #[test]
    fn models_command_parses() {
        let cli = Cli::try_parse_from(["focr", "models"]).expect("focr models parses");
        assert!(matches!(cli.command, Command::Models(_)));
        let cli = Cli::try_parse_from(["focr", "models", "--json"]).expect("--json parses");
        let Command::Models(args) = cli.command else {
            unreachable!("expected models");
        };
        assert!(args.json);
    }

    #[test]
    fn convert_arch_enum_parses() {
        let parsed = Cli::try_parse_from([
            "focr",
            "convert",
            "in.safetensors",
            "-o",
            "out.focrq",
            "--arch",
            "x86-vnni",
        ]);
        let parse_error = parsed
            .as_ref()
            .err()
            .map(std::string::ToString::to_string)
            .unwrap_or_default();
        assert!(parsed.is_ok(), "convert --arch parses: {parse_error}");
        let Ok(cli) = parsed else {
            return;
        };
        let is_convert = matches!(cli.command, Command::Convert(_));
        assert!(is_convert, "expected convert command");
        if let Command::Convert(args) = cli.command {
            assert_eq!(args.quant, QuantTarget::Int8);
            assert_eq!(args.arch, ArchTarget::X86Vnni);
        };
    }

    #[test]
    fn robot_backends_reflects_simd_dispatch_snapshot() {
        let payload = robot_backends_payload();
        let tiers = &payload["simd_tiers"];
        let effective = simd::effective_dense_route();
        let hardware = simd::detected_tier();
        assert_eq!(payload["schema_version"], robot::ROBOT_SCHEMA_VERSION);
        assert_eq!(tiers["selected"], effective.tag());
        assert_eq!(tiers["selected_feature"], effective.feature_string());
        assert_eq!(tiers["hardware_selected"], hardware.tag());
        assert_eq!(
            tiers["hardware_selected_feature"],
            hardware.feature_string()
        );
        assert_eq!(tiers["override_env"], "FOCR_FORCE_ARCH");

        assert!(
            tiers["available"].as_array().is_some_and(|available| {
                !available.is_empty()
                    && available.last().and_then(|v| v["tag"].as_str())
                        == Some(simd::IsaTier::Scalar.tag())
            }),
            "available tiers must be a non-empty array ending with the scalar floor"
        );
    }

    /// A tied-embedding (got-ocr2) checkpoint whose `lm_head.weight` and
    /// `embed_tokens` live in different shards, with an I64 arange in shard 2.
    /// `head_matches` false makes the head differ from the embedding.
    fn sharded_got_tensors(
        head_matches: bool,
    ) -> Vec<Vec<native_engine::shards::tests::SyntheticTensor>> {
        use native_engine::shards::tests::arange_bytes;
        let bf16 = |values: &[f32]| -> Vec<u8> {
            values
                .iter()
                .flat_map(|&v| half::bf16::from_f32(v).to_le_bytes())
                .collect()
        };
        let embed: Vec<f32> = (0..8).map(|i| i as f32 * 0.25 - 1.0).collect();
        let mut head = embed.clone();
        if !head_matches {
            head[3] += 1.0;
        }
        let down: Vec<f32> = (0..32).map(|i| ((i * 7 % 13) as f32 - 6.0) / 8.0).collect();
        vec![
            vec![
                (
                    "model.embed_tokens.weight",
                    "BF16",
                    vec![2, 4],
                    bf16(&embed),
                ),
                (
                    "model.layers.0.mlp.down_proj.weight",
                    "BF16",
                    vec![4, 8],
                    bf16(&down),
                ),
            ],
            vec![
                ("lm_head.weight", "BF16", vec![2, 4], bf16(&head)),
                (
                    "model.norm.weight",
                    "BF16",
                    vec![4],
                    bf16(&[1.0, 0.5, 2.0, -1.0]),
                ),
                ("vision.position_ids", "I64", vec![1, 4], arange_bytes(4)),
            ],
        ]
    }

    /// Write `shards` as an indexed checkpoint in a fresh directory named
    /// `label`; returns the directory.
    fn write_sharded_checkpoint(
        label: &str,
        shards: &[Vec<native_engine::shards::tests::SyntheticTensor>],
    ) -> PathBuf {
        use native_engine::shards::tests::{index_json, safetensors_file};
        let dir =
            std::env::temp_dir().join(format!("franken_ocr_cli_{label}_{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("temp dir");
        let mut map = Vec::new();
        let mut total = 0u64;
        for (position, tensors) in shards.iter().enumerate() {
            let name: &'static str = Box::leak(
                format!(
                    "model-{:05}-of-{:05}.safetensors",
                    position + 1,
                    shards.len()
                )
                .into_boxed_str(),
            );
            std::fs::write(dir.join(name), safetensors_file(tensors)).expect("write shard");
            for (tensor, _, _, bytes) in tensors {
                map.push((*tensor, name));
                total += bytes.len() as u64;
            }
        }
        std::fs::write(
            dir.join(native_engine::shards::SHARD_INDEX_NAME),
            index_json(&map, total),
        )
        .expect("write index");
        dir
    }

    fn convert_args(input: &Path, output: &Path, quant: QuantTarget) -> ConvertArgs {
        ConvertArgs {
            input: input.to_path_buf(),
            output: output.to_path_buf(),
            quant,
            arch: ArchTarget::Generic,
            model_id: Some("got-ocr2".into()),
            calib: None,
            json: false,
        }
    }

    /// The `.focrq` header JSON of `blob`.
    fn focrq_header(blob: &[u8]) -> serde_json::Value {
        let header_len = u64::from_le_bytes(blob[43..51].try_into().expect("8 bytes")) as usize;
        serde_json::from_slice(&blob[51..51 + header_len]).expect("header JSON")
    }

    #[test]
    fn sharded_source_converts_shard_by_shard_and_reloads() {
        use native_engine::shards::{self, test_rules, tests::POSITION_IDS_RULE};
        use native_engine::weights::{DType, Weights};
        let started = std::time::Instant::now();
        let test = "sharded_source_converts_shard_by_shard_and_reloads";
        let dir = write_sharded_checkpoint("sharded_convert", &sharded_got_tensors(true));
        let out = dir.join("out.focrq");

        // The I64 tensor is refused until the target arch's census admits it.
        let error = run_convert(&convert_args(&dir, &out, QuantTarget::Int8))
            .expect_err("got-ocr2 has no verify-and-skip rule");
        assert!(
            error.to_string().contains("got-ocr2 accepts I64 only"),
            "{error}"
        );

        let _rules = test_rules::supply(&POSITION_IDS_RULE);
        run_convert(&convert_args(&dir, &out, QuantTarget::Int8)).expect("streaming convert");
        let blob = std::fs::read(&out).expect("read artifact");
        let digests =
            shards::hash_shards(&dir.join(shards::SHARD_INDEX_NAME)).expect("hash the source");
        for digest in &digests {
            println!(
                "{}",
                serde_json::json!({
                    "schema_version": 1, "ts": started.elapsed().as_secs_f64(), "test": test,
                    "case": digest.name, "run_seq": 0, "event": "assert", "result": "pass",
                    "assertion": "shard header checked against the index and hashed",
                    "pass": true,
                    "bytes": digest.size, "header_ok": true, "hashed": true,
                    "sha256": digest.sha256_hex(),
                })
            );
        }
        let convention: String = shards::source_sha256(&digests)
            .iter()
            .map(|byte| format!("{byte:02x}"))
            .collect();
        let header = focrq_header(&blob);
        assert_eq!(header["source_sha256"], convention.as_str());
        let listed = header["provenance"]["source_shards"]
            .as_array()
            .expect("multi-shard provenance");
        assert_eq!(listed.len(), 2);
        for (entry, digest) in listed.iter().zip(&digests) {
            assert_eq!(entry["name"], digest.name.as_str());
            assert_eq!(entry["size"], digest.size);
            assert_eq!(entry["sha256"], digest.sha256_hex().as_str());
        }

        let reloaded =
            Weights::from_bytes(blob.clone()).expect("reload passes the provenance gate");
        assert_eq!(reloaded.model_id(), "got-ocr2");
        assert_eq!(reloaded.source_sha256(), convention);
        assert_eq!(
            reloaded.names().collect::<Vec<_>>(),
            [
                "model.embed_tokens.weight",
                "model.layers.0.mlp.down_proj.weight",
                "model.norm.weight"
            ],
            "tied lm_head omitted; the verified I64 tensor never stored"
        );
        assert_eq!(
            reloaded
                .record("model.layers.0.mlp.down_proj.weight")
                .expect("down")
                .dtype,
            DType::QInt8PerChan
        );
        assert!(native_engine::native_model_available(&out));

        // The same tensors as one plain file convert to the same tensor bytes.
        let plain_dir = dir.join("plain");
        std::fs::create_dir_all(&plain_dir).expect("plain dir");
        let plain = plain_dir.join("model.safetensors");
        let all: Vec<_> = sharded_got_tensors(true).concat();
        std::fs::write(&plain, shards::tests::safetensors_file(&all)).expect("write plain");
        let plain_out = plain_dir.join("plain.focrq");
        run_convert(&convert_args(&plain, &plain_out, QuantTarget::Int8)).expect("plain convert");
        let plain_blob = std::fs::read(&plain_out).expect("read plain artifact");
        assert!(
            focrq_header(&plain_blob).get("provenance").is_none(),
            "one shard: no list"
        );
        let single = Weights::from_bytes(plain_blob).expect("reload plain");
        for name in single.names() {
            let (a, b) = (
                reloaded.tensor(name).expect("sharded"),
                single.tensor(name).expect("plain"),
            );
            assert_eq!(
                (a.dtype, a.data, a.scales),
                (b.dtype, b.data, b.scales),
                "{name}"
            );
        }

        // A provenance whose shard digests disagree with source_sha256 is refused
        // by the loader and by the header probe (exit 7).
        let first = digests[0].sha256_hex();
        let flipped = format!(
            "{}{}",
            if first.starts_with('0') { '1' } else { '0' },
            &first[1..]
        );
        let hits: Vec<usize> = blob
            .windows(64)
            .enumerate()
            .filter(|(_, window)| *window == first.as_bytes())
            .map(|(at, _)| at)
            .collect();
        assert_eq!(
            hits.len(),
            1,
            "the shard digest appears once, in the provenance"
        );
        let at = hits[0];
        let tampered_path = dir.join("tampered.focrq");
        let mut tampered = blob.clone();
        tampered[at..at + 64].copy_from_slice(flipped.as_bytes());
        std::fs::write(&tampered_path, &tampered).expect("write tampered");
        let error = Weights::load(&tampered_path).expect_err("convention mismatch");
        assert_eq!(error.exit_code(), 7);
        assert!(error.to_string().contains("convention digest"), "{error}");
        assert!(!native_engine::native_model_available(&tampered_path));
        println!(
            "{}",
            serde_json::json!({
                "schema_version": 1, "ts": started.elapsed().as_secs_f64(), "test": test,
                "case": "convert", "run_seq": 0, "event": "result", "result": "pass",
                "elapsed_us": started.elapsed().as_micros() as u64,
                "source_sha256": convention, "shards": digests.len(),
            })
        );
    }

    #[test]
    fn sharded_convert_checks_the_tie_across_shards_and_refuses_int4() {
        use native_engine::shards::{test_rules, tests::POSITION_IDS_RULE};
        let _rules = test_rules::supply(&POSITION_IDS_RULE);
        let dir = write_sharded_checkpoint("sharded_untied", &sharded_got_tensors(false));
        let out = dir.join("out.focrq");
        let error = run_convert(&convert_args(&dir, &out, QuantTarget::Int8))
            .expect_err("a tied arch fed an untied head");
        assert!(
            error.to_string().contains("declares TIED embeddings"),
            "{error}"
        );
        assert!(!out.exists(), "nothing is written for a refused source");

        // The arch is judged first: GOT-OCR2 has no int4 recipe at any
        // shard count (U2-A7). v1, the one model with one, is pinned to a
        // single shard by its census, below.
        let error = run_convert(&convert_args(&dir, &out, QuantTarget::Int4))
            .expect_err("got-ocr2 has no int4 recipe");
        assert!(matches!(error, FocrError::NotImplemented(_)), "{error}");
        assert!(
            error.to_string().contains("has no certified int4 recipe"),
            "{error}"
        );

        // v1 has a census, and these headers do not match it: refused on the
        // census (exit 7) before any payload byte is read, at int8 and int4.
        let mut args = convert_args(&dir, &out, QuantTarget::Int8);
        args.model_id = Some("unlimited-ocr".into());
        for quant in [QuantTarget::Int8, QuantTarget::Int4] {
            args.quant = quant;
            let error = run_convert(&args).expect_err("not v1's census");
            assert!(matches!(error, FocrError::FormatMismatch(_)), "{error}");
            assert!(
                error
                    .to_string()
                    .contains("unlimited-ocr source safetensors tensor census failed"),
                "{error}"
            );
            assert!(!out.exists(), "nothing is written for a refused source");
        }

        // With no --model-id, a source no census matches must be named.
        args.model_id = None;
        args.quant = QuantTarget::Int8;
        let error = run_convert(&args).expect_err("no census, no id");
        assert!(matches!(error, FocrError::Usage(_)), "{error}");
        assert!(error.to_string().contains("pass --model-id"), "{error}");
    }
}