ftts-cli 0.1.10

#![forbid(unsafe_code)]

//! Shared, stateless command-line dispatch for both FrankenTTS binaries.

pub(crate) mod card;
pub mod diagnostics;
mod error;
pub mod resident;
pub mod robot;
pub mod session_protocol;
pub mod style;
pub mod synth;
pub mod talk;

pub use error::{FttsError, FttsExitCode};
pub use robot::{EventType, validate_event, validate_ndjson};

use std::collections::BTreeMap;
use std::ffi::OsString;
use std::fs;
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::process::ExitCode;
use std::sync::{LazyLock, OnceLock};

#[cfg(test)]
use clap::CommandFactory;
use clap::{Parser, Subcommand, ValueEnum};
use ftts_artifacts::census::{ExpectedTensor, WeightsManifest};
use ftts_artifacts::converter::{
    StreamingConversionPlan, TensorConversion, TensorStoragePolicy, convert_safetensors_streaming,
};
use ftts_artifacts::fttsq::{AccessClass, MappedFttsq};
use ftts_artifacts::safetensors::Dtype;
use ftts_core::{NormalizationMode, NormalizationOptions, SynthesisRequest};
use ftts_kernels::mmap::MappedFile;
use serde_json::{Value, json};

const ROBOT_SCHEMA_VERSION: u8 = 1;
const SCAFFOLD_ADMISSION_TEXT_LIMIT_BYTES: usize = 1_048_576;
const MODEL_BASENAME: &str = "qwen3-tts-12hz-0.6b-base.fttsq";

/// Built-in voices: name, one-line character, and the enrolled 1,024-float x-vector.
///
/// "matt" is the out-of-box default when no enrollment exists. Enrolling a real reference
/// always takes precedence over any of them.
const PRESET_VOICES: &[(&str, &str, &[u8])] = &[
    (
        "aria",
        "clear, warm, feminine",
        include_bytes!("../presets/aria.spk"),
    ),
    (
        "ember",
        "the same character a few semitones deeper",
        include_bytes!("../presets/ember.spk"),
    ),
    (
        "james",
        "natural, conversational, masculine",
        include_bytes!("../presets/james.spk"),
    ),
    (
        "matt",
        "warm, easy, masculine — the out-of-box default",
        include_bytes!("../presets/matt.spk"),
    ),
    (
        "leo",
        "relaxed, resonant, masculine",
        include_bytes!("../presets/leo.spk"),
    ),
    (
        "robert",
        "steady, measured, masculine",
        include_bytes!("../presets/robert.spk"),
    ),
    (
        "judy",
        "bright, articulate, feminine",
        include_bytes!("../presets/judy.spk"),
    ),
    (
        "liam",
        "thoughtful, engaging, masculine",
        include_bytes!("../presets/liam.spk"),
    ),
    (
        "anthony",
        "authoritative, articulate, masculine",
        include_bytes!("../presets/anthony.spk"),
    ),
    (
        "russell",
        "rich, warm, masculine",
        include_bytes!("../presets/russell.spk"),
    ),
    (
        "steve",
        "direct, energetic, masculine",
        include_bytes!("../presets/steve.spk"),
    ),
    (
        "daniel",
        "clear, calm, masculine",
        include_bytes!("../presets/daniel.spk"),
    ),
    (
        "meryl",
        "expressive, poised, feminine",
        include_bytes!("../presets/meryl.spk"),
    ),
    (
        "laurence",
        "deep, measured, masculine",
        include_bytes!("../presets/laurence.spk"),
    ),
    (
        "jack",
        "crisp, confident, masculine",
        include_bytes!("../presets/jack.spk"),
    ),
    (
        "michael",
        "warm, dynamic, masculine",
        include_bytes!("../presets/michael.spk"),
    ),
    (
        "jodie",
        "warm, expressive, feminine",
        include_bytes!("../presets/jodie.spk"),
    ),
    (
        "denzel",
        "commanding, charismatic, masculine",
        include_bytes!("../presets/denzel.spk"),
    ),
];

/// The preset used when `--voice`, `FTTS_DEFAULT_VOICE`, and an enrolled default voice
/// (MODEL_DIR/default.ftvoice or legacy default.spk) are all
/// absent, so a fresh install speaks out of the box.
const DEFAULT_PRESET_VOICE: &str = "matt";

/// Names a preset resolves to a temp-materialized `.spk` path the existing voice loaders read.
///
/// Only fires when the value is NOT an existing file, so a file named like a preset still wins.
/// The file is rewritten unconditionally: 4 KB per run is cheaper than trusting stale content.
fn materialize_preset_voice(name: &str) -> Option<Result<PathBuf, FttsError>> {
    let (_, _, bytes) = PRESET_VOICES
        .iter()
        .find(|(preset, _, _)| *preset == name)?;
    let staging_dir = match synth::private_staging_dir() {
        Ok(dir) => dir,
        Err(error) => {
            return Some(Err(FttsError::Generic(format!(
                "cannot create staging directory for preset voice {name}: {error}"
            ))));
        }
    };
    let path = staging_dir.join(format!("ftts-preset-{name}-{}.spk", std::process::id()));
    Some(
        fs::write(&path, bytes)
            .map(|()| path.clone())
            .map_err(|error| {
                FttsError::Generic(format!(
                    "cannot materialize preset voice {name} at {}: {error}",
                    path.display()
                ))
            }),
    )
}

fn preset_names() -> String {
    PRESET_VOICES
        .iter()
        .map(|(name, _, _)| *name)
        .collect::<Vec<_>>()
        .join(", ")
}

/// Materializes a built-in preset voice as an `.spk` path, so evaluation harnesses can
/// condition synthesis on a real speech x-vector without handling voice bytes themselves.
///
/// # Errors
///
/// Unknown preset name, or the staging directory/file could not be written.
pub fn preset_voice_path(name: &str) -> Result<PathBuf, FttsError> {
    match materialize_preset_voice(name) {
        Some(result) => result,
        None => Err(FttsError::Usage(format!(
            "unknown preset voice {name:?}; available presets: {}",
            preset_names()
        ))),
    }
}
const PINNED_MAIN_WEIGHTS_FILENAME: &str = "model.safetensors";
const PINNED_MAIN_WEIGHTS_SHA256: &str =
    "180b3b10eb1c9f1b4db7806d5475bae3071c0243c299d49926bab1da3b6946f6";
const PINNED_MODEL_REVISION: &str = "5d83992436eae1d760afd27aff78a71d676296fc";
const PINNED_MAIN_TENSOR_COUNT: usize = 478;
//  Crate-local pinned copies (`pinned/`): `cargo package` cannot ship files outside the crate
//  root, and these three are compile-time product surfaces (the artifact census, the model-dir
//  pin assertion, and the Apache attribution the binary prints). A unit test asserts each copy is
//  byte-identical to the truth-pack canonical whenever the truth pack is present.
const PINNED_TENSOR_INVENTORY: &str = include_str!("../pinned/TENSOR_INVENTORY.json");
const PINNED_MODEL_CONFIG: &str = include_str!("../pinned/model_config.json");
const APACHE_LICENSE: &str = include_str!("../pinned/QWEN_APACHE_LICENSE");
//  The `ftts pull` download contract: which release assets make a complete model directory, and
//  the exact digest each must carry. Embedded so a shipped binary can fetch and verify the model
//  with no network-served manifest to trust.
const PINNED_MODEL_MANIFEST: &str = include_str!("../pinned/model_manifest.json");
/// Subdirectory of `$HOME/.cache` that `ftts pull` fills and model resolution falls back to.
const DEFAULT_MODEL_CACHE_SUBDIR: &str = ".cache/franken_tts/model";
// The environment snapshot and the agent-facing contract share ONE list —
// `robot::DOCUMENTED_ENVIRONMENT` — so `doctor`, `robot schema`, and the actual readers can
// never disagree about which levers exist (they did: neither list mentioned the resident
// daemon's variables, and each had entries the other lacked).

/// Runs the shared `ftts` / `franken_tts` command-line interface.
pub fn cli_main() -> ExitCode {
    // The optimized route is the DEFAULT everywhere (library-level: see
    // `ftts_kernels::route`). `FTTS_INT8=0` selects the f32 reference route end to end;
    // DISC-003 records the decision and the evidence.

    let cli = match Cli::try_parse() {
        Ok(cli) => cli,
        Err(error) => {
            let exit_code = match error.kind() {
                clap::error::ErrorKind::DisplayHelp | clap::error::ErrorKind::DisplayVersion => {
                    FttsExitCode::Success
                }
                _ => FttsExitCode::Usage,
            };
            let _ = error.print();
            return exit_code.as_exit_code();
        }
    };

    // `talk` owns the process's stdio from BACKGROUND threads (reader/writer), and the
    // std lock guards are reentrant only on their own thread: holding them here for the
    // whole dispatch would deadlock the session the moment its threads try to lock.
    // Dispatch it before any lock exists.
    if let Command::Talk(args) = &cli.command {
        return match run_talk_command(&cli, args, environment()) {
            Ok(()) => FttsExitCode::Success.as_exit_code(),
            Err(error) => {
                let mut stderr = io::stderr().lock();
                let _ = writeln!(stderr, "error: {error}");
                error.exit_code().as_exit_code()
            }
        };
    }

    use std::io::IsTerminal as _;
    let capabilities = IoCapabilities {
        human_output: io::stdout().is_terminal(),
        can_confirm: io::stdin().is_terminal() && io::stdout().is_terminal(),
    };
    let mut stdin = io::stdin().lock();
    let mut stdout = io::stdout().lock();
    let mut stderr = io::stderr().lock();
    // `say` reports its own failures as a `run_error` NDJSON event on stderr — that IS the
    // machine contract, and under `--stream raw` stderr carries nothing but events. The
    // plain-text duplicate below would be a non-JSON line in that same stream, so for `say`
    // it only appears when a human (a terminal) is reading stderr.
    let already_on_contract = matches!(cli.command, Command::Say(_));
    match dispatch(
        cli,
        environment(),
        &mut stdin,
        &mut stdout,
        &mut stderr,
        capabilities,
    ) {
        Ok(()) => FttsExitCode::Success.as_exit_code(),
        Err(error) => {
            if !already_on_contract || io::stderr().is_terminal() {
                let _ = writeln!(stderr, "error: {error}");
            }
            error.exit_code().as_exit_code()
        }
    }
}

#[derive(Debug, Parser)]
#[command(
    name = "ftts",
    version,
    about = "Pure-Rust Qwen3-TTS command-line interface",
    long_about = "FrankenTTS is stateless by default: synthesis history is never persisted. \
                  Use `ftts robot schema` for the versioned NDJSON contract.",
    arg_required_else_help = true
)]
struct Cli {
    /// Execution profile. The default is balanced unless FTTS_PROFILE overrides it.
    #[arg(long, global = true, value_enum)]
    profile: Option<ExecutionProfile>,

    /// Codec packet size in frames. The default is profile-dependent.
    #[arg(long, global = true, value_enum)]
    packet_frames: Option<PacketFrames>,

    /// Math contract used by this invocation.
    #[arg(long, global = true, value_enum)]
    math_mode: Option<MathMode>,

    /// Voice-pack serialization profile used by enrollment.
    #[arg(long, global = true, value_enum)]
    voice_pack: Option<VoicePackProfile>,

    /// Text-normalization policy.
    #[arg(long, global = true, value_enum)]
    normalize: Option<NormalizeMode>,

    /// Request a structured trace from synthesis without default-persisting sensitive text.
    #[arg(long, global = true, value_name = "DIR")]
    trace: Option<PathBuf>,

    /// Reproducibility seed for a future sampler.
    #[arg(long, global = true)]
    seed: Option<u64>,

    #[command(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    /// Validate or synthesize text with an optional voice pack.
    ///
    /// Signals: the first SIGINT/SIGTERM stops the run cooperatively — audio already
    /// delivered is finalized (a valid WAV of whatever landed; a compressed encoding
    /// is skipped and the partial WAV kept) — and the run ends with `run_error` kind
    /// "cancelled", exit code 6. A second signal exits immediately.
    Say(SayArgs),
    /// Synthesize text and render a share-ready branded video of it.
    #[command(name = "make-video")]
    MakeVideo(MakeVideoArgs),
    /// Build a consent-bearing voice pack from reference audio.
    Enroll(EnrollArgs),
    /// Inspect a portable voice pack.
    Voice(VoiceArgs),
    /// Export or import a voice card: a picture that carries the voice itself,
    /// interchangeable with the iOS app.
    Card(CardArgs),
    /// Convert pinned source weights into a portable .fttsq artifact.
    Convert(ConvertArgs),
    /// Download and verify the pinned model files into the model directory.
    Pull(PullArgs),
    /// Hold a live conversation session: NDJSON ops on stdin, schema-v2 events on
    /// stdout, raw s16le 24 kHz PCM on fd 3 (Unix) or --pcm-out. One warm model for
    /// the whole exchange; the resident daemon is never involved. See
    /// `ftts robot schema --contract session` for the wire contract.
    Talk(TalkArgs),
    /// Emit versioned, line-oriented robot contract data.
    Robot(RobotArgs),
    /// Report local configuration and readiness without inference.
    Doctor(DoctorArgs),
    /// Internal: run the resident engine daemon. Spawned by `ftts say`; not for direct use.
    #[command(hide = true, name = "resident-daemon")]
    ResidentDaemon(ResidentDaemonArgs),
}

#[derive(Debug, clap::Args)]
struct ResidentDaemonArgs {
    /// Model directory this daemon serves.
    #[arg(long, value_name = "PATH")]
    bundle_root: PathBuf,
}

#[derive(Debug, clap::Args)]
struct SayArgs {
    /// Text to synthesize. Use `-` to read UTF-8 text from stdin.
    #[arg(value_name = "TEXT")]
    text: Option<String>,

    /// Output file (same as -o). Format follows the extension: .wav is written natively;
    /// .m4a, .mp3, and .flac are encoded from the native WAV by the first available system
    /// encoder (afconvert, ffmpeg, lame, flac).
    #[arg(value_name = "OUTPUT", conflicts_with_all = ["stream", "output"])]
    output_positional: Option<PathBuf>,

    /// Read UTF-8 text from PATH. Use `-` for stdin.
    #[arg(long, value_name = "PATH", conflicts_with = "text")]
    file: Option<PathBuf>,

    /// Explicit .fttsq model artifact. No network lookup is performed.
    #[arg(long, value_name = "PATH")]
    model: Option<PathBuf>,

    /// Voice source: a .spk vector, a voice-card image (PNG/JPEG), reference
    /// audio, or a built-in voice name
    /// (matt, james, leo, robert, judy, aria, ember, liam, anthony, russell, steve, daniel, meryl, laurence, jack, michael, jodie, denzel).
    /// Default: the enrolled default voice (MODEL_DIR/default.ftvoice, else legacy
    /// default.spk), else the built-in "matt".
    #[arg(long, value_name = "PATH|NAME")]
    voice: Option<PathBuf>,

    /// Write WAV output here. Mutually exclusive with raw stdout streaming.
    #[arg(short = 'o', long, value_name = "PATH", conflicts_with = "stream")]
    output: Option<PathBuf>,

    /// Stream raw PCM on stdout; robot events then use stderr. Packets are written live,
    /// during synthesis. Raw streaming bypasses the resident engine (whose reply is one
    /// whole buffer after synthesis) and pays the in-process model load instead.
    #[arg(long, value_enum)]
    stream: Option<StreamMode>,

    /// Parse inputs and run the conservative admission preflight without synthesis.
    #[arg(long)]
    check: bool,

    /// Emit the NDJSON event stream even when stdout is a terminal.
    ///
    /// Piped, redirected and CI runs already get NDJSON — nothing but a terminal gets the human
    /// view — so this exists for a person who wants to watch the machine contract directly.
    #[arg(long)]
    robot: bool,

    /// Load the model in this process instead of using the resident engine.
    ///
    /// By default `ftts say` keeps the loaded model in a background process so the next
    /// invocation starts without the multi-second load, unloading itself after ten idle
    /// minutes (FTTS_RESIDENT_IDLE_SECS overrides). This flag, or FTTS_NO_RESIDENT=1,
    /// opts a run out; results are identical either way.
    #[arg(long)]
    no_resident: bool,
}

#[derive(Debug, clap::Args)]
struct MakeVideoArgs {
    /// Text to synthesize. Use `-` to read UTF-8 text from stdin.
    #[arg(value_name = "TEXT")]
    text: Option<String>,

    /// Output video. `.mp4` uses the first available system encoder (ffmpeg);
    /// `.y4m` renders natively with a `.wav` sibling and needs no encoder.
    #[arg(value_name = "OUTPUT", conflicts_with = "output")]
    output_positional: Option<PathBuf>,

    /// Read UTF-8 text from PATH. Use `-` for stdin.
    #[arg(long, value_name = "PATH", conflicts_with = "text")]
    file: Option<PathBuf>,

    /// Explicit .fttsq model artifact. No network lookup is performed.
    #[arg(long, value_name = "PATH")]
    model: Option<PathBuf>,

    /// Voice source: a .spk vector, a voice-card image (PNG/JPEG), reference
    /// audio, or a built-in voice name
    /// (matt, james, leo, robert, judy, aria, ember, liam, anthony, russell, steve, daniel, meryl, laurence, jack, michael, jodie, denzel).
    #[arg(long, value_name = "PATH|NAME")]
    voice: Option<PathBuf>,

    /// Write the video here. Same as the positional OUTPUT.
    #[arg(short = 'o', long, value_name = "PATH")]
    output: Option<PathBuf>,

    /// Skip synthesis and render this existing PCM WAV instead.
    #[arg(long, value_name = "PATH", conflicts_with_all = ["text", "file"])]
    audio: Option<PathBuf>,

    /// Voice name shown on the video. Defaults to the voice's name.
    #[arg(long, value_name = "NAME")]
    label: Option<String>,

    /// Load the model in this process instead of using the resident engine.
    #[arg(long)]
    no_resident: bool,
}

/// How enrollment chooses its conditioning path (bead frankentts-p4-enrollment-en6).
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, ValueEnum)]
enum EnrollMode {
    /// Transcript-backed ICL: verified transcript + codec-encoder tokens land in the pack.
    Quality,
    /// x-vector embedding only; upstream documents possible quality reduction and this CLI
    /// says so in the enrollment output.
    Quick,
    /// QUALITY when a transcript is supplied and verifies, else QUICK with a loud warning.
    #[default]
    Auto,
}

/// The mode enrollment actually ran, decided from [`EnrollMode`] plus what the input allows.
#[derive(Clone, Debug, Eq, PartialEq)]
enum ResolvedEnrollMode {
    Quality,
    Quick {
        /// Why QUICK was chosen despite an AUTO/QUALITY request — printed loudly.
        reason: String,
    },
}

/// Pure mode resolution so the fallback policy is unit-testable without audio or models.
///
/// QUALITY demands a transcript; AUTO degrades to QUICK (loudly) without one; an explicit
/// QUICK never silently upgrades.
fn resolve_enroll_mode(requested: EnrollMode, transcript: Option<&str>) -> ResolvedEnrollMode {
    let verified = transcript.is_some_and(|text| !text.trim().is_empty());
    match requested {
        EnrollMode::Quality if verified => ResolvedEnrollMode::Quality,
        EnrollMode::Quality => ResolvedEnrollMode::Quick {
            reason: "--mode quality needs --transcript-text/--transcript-file; enrolled \
                     x-vector only"
                .to_owned(),
        },
        EnrollMode::Auto if verified => ResolvedEnrollMode::Quality,
        EnrollMode::Auto => ResolvedEnrollMode::Quick {
            reason: "no transcript supplied; AUTO fell back to QUICK (x-vector only)".to_owned(),
        },
        EnrollMode::Quick => ResolvedEnrollMode::Quick {
            reason: "--mode quick enrolls the x-vector only".to_owned(),
        },
    }
}

#[derive(Debug, clap::Args)]
struct EnrollArgs {
    /// Reference audio: WAV/FLAC decode natively; m4a/mp3/aac/ogg/opus route through the first
    /// system decoder found (afconvert on macOS, ffmpeg).
    #[arg(value_name = "REFERENCE_AUDIO")]
    reference_audio: PathBuf,

    /// Explicit model directory or .fttsq model artifact. No network lookup is performed.
    #[arg(long, value_name = "PATH")]
    model: Option<PathBuf>,

    /// Write the enrolled portable `.ftvoice` pack here. Refuses to overwrite an existing file.
    #[arg(short = 'o', long, value_name = "PATH", conflicts_with = "default")]
    output: Option<PathBuf>,

    /// Write MODEL_DIR/default.ftvoice — the enrolled default `ftts say` uses when
    /// `--voice` is absent.
    #[arg(long, conflicts_with = "output")]
    default: bool,

    /// Proceed past a REFUSED enrollment: a reference diagnosed as structurally unusable
    /// (no speech, wall-to-wall clipping) otherwise exits 8 (`enrollment-quality
    /// refusal`). Mere quality WARNINGS never refuse on their own.
    #[arg(long)]
    force: bool,

    /// Replace an existing voice at the destination without asking.
    ///
    /// Interactive runs are asked to confirm instead; this is how a script or an agent gives that
    /// consent up front. The displaced voice is copied to `<path>.bak` either way.
    #[arg(long)]
    overwrite: bool,

    /// Remove late reverberation from the reference before enrolling.
    ///
    /// A room is convolutive, so `--denoise` cannot touch it; this is the lever for a reference
    /// that sounds "wet". It matters because the speaker encoder cannot separate voice from room,
    /// so a reverberant reference enrolls the room as part of the speaker and every utterance the
    /// clone speaks is rendered in it. Off by default: it changes the enrolled identity.
    #[arg(long)]
    dereverb: bool,

    /// Clean stationary noise from the reference before enrolling.
    ///
    /// This is the default whenever the neural denoiser's weights are present (`ftts pull`
    /// fetches them; measured on a static-hiss reference, the cleaned enrollment lands
    /// closer to a clean-source enrollment than the raw recording does). Passing the flag
    /// explicitly additionally engages the classic no-weights spectral subtraction when the
    /// weights are absent, where the automatic path would skip cleanup rather than swap in
    /// a different engine unannounced.
    #[arg(long, overrides_with = "no_denoise")]
    denoise: bool,

    /// Enroll the recording exactly as given, with no noise cleanup.
    #[arg(long, overrides_with = "denoise")]
    no_denoise: bool,
    /// Conditioning path: quality (transcript-backed ICL), quick (x-vector only), or auto
    /// (quality when a usable transcript is supplied, else quick with a loud warning).
    /// The modes are NOT interchangeable equals: continuation-style cloning reproduces
    /// prompt-recording defects, so the quick path says what it skipped.
    #[arg(long, value_enum, default_value_t = EnrollMode::Auto)]
    mode: EnrollMode,

    /// Reference transcript text, verbatim (quality path / AUTO input). The ICL prompt
    /// conditions on exactly these words, so they must match the recording word for word.
    #[arg(long, conflicts_with = "transcript_file", value_name = "TEXT")]
    transcript_text: Option<String>,

    /// Read the reference transcript from a UTF-8 file (one alternative to --transcript-text).
    #[arg(long, value_name = "PATH")]
    transcript_file: Option<PathBuf>,

    /// Affirm recording consent non-interactively; interactive runs are asked instead. The
    /// answer — yes or no — is recorded in the pack either way, because a pack that cannot
    /// state its own consent status is worse than one that states `false`.
    #[arg(long)]
    consent_attest: bool,
}

#[derive(Debug, clap::Args)]
struct VoiceArgs {
    #[command(subcommand)]
    command: VoiceCommand,
}

#[derive(Debug, Subcommand)]
enum VoiceCommand {
    /// Inspect a .ftvoice header without synthesizing.
    Inspect { path: PathBuf },
}

#[derive(Debug, clap::Args)]
struct ConvertArgs {
    /// Pinned source-weight directory or file.
    #[arg(value_name = "SOURCE")]
    source: PathBuf,

    /// Destination .fttsq path. Refuses to overwrite an existing artifact.
    #[arg(short = 'o', long, value_name = "PATH")]
    output: PathBuf,

    /// EXPERIMENTAL: store the 622 MB cold text embedding as Q8 (per-row scales) instead of
    /// bf16, roughly halving it. The loader already reads both forms; bf16 remains the default
    /// until the artifact-v2 gates pass (teacher-forced logit parity on the conformance corpus
    /// plus the equivalence-bound listening protocol — frankentts-6ea1). Browser deployments
    /// stay on bf16 artifacts for now: the playground's provided-rows path is bf16-only.
    #[arg(long)]
    embed_q8: bool,

    /// EXPERIMENTAL: store the microdecoder's per-depth residual embedding tables and
    /// scoring heads (~126 MB of bf16 across thirty tensors) as per-row Q8 instead,
    /// roughly halving that block. The loader dequantizes both forms; bf16 stays the
    /// default until the artifact-v2 gates pass (per-depth teacher-forced logit KL/top-k
    /// plus the equivalence-bound listening protocol — frankentts-x7bt, following the
    /// --embed-q8 precedent of frankentts-6ea1/NE-008).
    #[arg(long)]
    micro_q8: bool,
}

#[derive(Debug, clap::Args)]
struct PullArgs {
    /// Destination model directory. Defaults to FTTS_MODEL_DIR, then ~/.cache/franken_tts/model.
    #[arg(long, value_name = "PATH")]
    model: Option<PathBuf>,

    /// Re-download every file even when it is already present and verified.
    #[arg(long)]
    force: bool,
}

#[derive(Debug, clap::Args)]
struct RobotArgs {
    #[command(subcommand)]
    command: RobotCommand,
}

#[derive(Clone, Debug, Subcommand)]
enum RobotCommand {
    /// Print the versioned NDJSON event schema.
    Schema {
        /// Which contract to print: the one-shot run contract (v1, the default and the shape
        /// every existing consumer validates) or the talk-session contract (v2).
        #[arg(default_value = "run")]
        contract: SchemaContract,
    },
    /// Print a versioned machine-readable readiness event.
    Health,
    /// Print available backend routes without probing model weights.
    Backends,
    /// Print the self-test state; no unavailable kernel is reported as passing.
    Selftest,
}

/// Which wire contract `ftts robot schema` prints.
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum SchemaContract {
    /// The one-shot run contract (schema v1), frozen by the conformance fixture.
    Run,
    /// The talk-session contract (schema v2).
    Session,
}

#[derive(Debug, clap::Args)]
struct DoctorArgs {
    /// Emit one JSON object on stdout instead of a human-readable report.
    #[arg(long)]
    json: bool,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum ExecutionProfile {
    Interactive,
    Balanced,
    Throughput,
    Strict,
}

impl ExecutionProfile {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Interactive => "interactive",
            Self::Balanced => "balanced",
            Self::Throughput => "throughput",
            Self::Strict => "strict",
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum PacketFrames {
    #[value(name = "1")]
    One,
    #[value(name = "2")]
    Two,
    #[value(name = "4")]
    Four,
    Auto,
}

impl PacketFrames {
    const fn as_str(self) -> &'static str {
        match self {
            Self::One => "1",
            Self::Two => "2",
            Self::Four => "4",
            Self::Auto => "auto",
        }
    }

    /// Codec frames carried by one PCM packet.
    ///
    /// `auto` resolves to 4 here. The autotuner that will choose it per machine is
    /// `frankentts-k-packet-tuning-28u`; until it exists, `auto` means "the balanced default"
    /// rather than a number this call site invented on the spot.
    const fn frames_per_packet(self) -> u8 {
        match self {
            Self::One => 1,
            Self::Two => 2,
            Self::Four | Self::Auto => 4,
        }
    }

    /// Samples in one packet: frames times the codec's 1,920 samples per 80 ms frame.
    const fn samples_per_packet(self) -> usize {
        self.frames_per_packet() as usize * ftts_core::audio::SAMPLES_PER_FRAME
    }

    const fn default_for(profile: ExecutionProfile) -> Self {
        match profile {
            ExecutionProfile::Interactive => Self::One,
            ExecutionProfile::Balanced => Self::Four,
            ExecutionProfile::Throughput => Self::Auto,
            ExecutionProfile::Strict => Self::Four,
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum MathMode {
    Strict,
    Fast,
}

impl MathMode {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Strict => "strict",
            Self::Fast => "fast",
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum VoicePackProfile {
    Portable,
    Private,
    Minimal,
}

impl VoicePackProfile {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Portable => "portable",
            Self::Private => "private",
            Self::Minimal => "minimal",
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum NormalizeMode {
    Verbatim,
    Conservative,
    LocaleAware,
}

impl NormalizeMode {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Verbatim => "verbatim",
            Self::Conservative => "conservative",
            Self::LocaleAware => "locale-aware",
        }
    }
}

impl From<NormalizeMode> for NormalizationMode {
    fn from(mode: NormalizeMode) -> Self {
        match mode {
            NormalizeMode::Verbatim => Self::Verbatim,
            NormalizeMode::Conservative => Self::Conservative,
            NormalizeMode::LocaleAware => Self::LocaleAware,
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum StreamMode {
    Raw,
}

#[derive(Debug, Default)]
struct Environment {
    values: BTreeMap<&'static str, Option<OsString>>,
    stage_budget_values: BTreeMap<OsString, OsString>,
}

impl Environment {
    fn from_process() -> Self {
        let values = robot::DOCUMENTED_ENVIRONMENT
            .iter()
            .map(|&name| (name, std::env::var_os(name)))
            .collect();
        let stage_budget_values = std::env::vars_os()
            .filter(|(name, _)| {
                name.to_str().is_some_and(|name| {
                    name.starts_with("FTTS_STAGE_BUDGET_") && name.ends_with("_MS")
                })
            })
            .collect();
        Self {
            values,
            stage_budget_values,
        }
    }

    fn value(&self, name: &'static str) -> Option<&str> {
        self.values.get(name)?.as_deref()?.to_str()
    }

    fn documented_values(&self) -> BTreeMap<String, Option<String>> {
        let mut values = self
            .values
            .iter()
            .map(|(name, value)| {
                (
                    (*name).to_owned(),
                    value
                        .as_ref()
                        .map(|value| value.to_string_lossy().into_owned()),
                )
            })
            .collect::<BTreeMap<_, _>>();
        values.insert("FTTS_STAGE_BUDGET_*_MS".to_owned(), None);
        values.extend(self.stage_budget_values.iter().map(|(name, value)| {
            (
                name.to_string_lossy().into_owned(),
                Some(value.to_string_lossy().into_owned()),
            )
        }));
        values
    }
}

fn environment() -> &'static Environment {
    static ENVIRONMENT: OnceLock<Environment> = OnceLock::new();
    ENVIRONMENT.get_or_init(Environment::from_process)
}

#[derive(Debug)]
struct EffectiveSettings {
    profile: ExecutionProfile,
    packet_frames: PacketFrames,
    math_mode: MathMode,
    voice_pack: VoicePackProfile,
    normalize: NormalizeMode,
}

impl EffectiveSettings {
    fn resolve(cli: &Cli, environment: &Environment) -> Result<Self, FttsError> {
        let profile = cli
            .profile
            .or(parse_env_value(
                environment.value("FTTS_PROFILE"),
                "FTTS_PROFILE",
                ExecutionProfile::value_variants(),
            )?)
            .unwrap_or(ExecutionProfile::Balanced);
        let packet_frames = cli
            .packet_frames
            .or(parse_env_value(
                environment.value("FTTS_PACKET_FRAMES"),
                "FTTS_PACKET_FRAMES",
                PacketFrames::value_variants(),
            )?)
            .unwrap_or_else(|| PacketFrames::default_for(profile));
        let math_mode = cli
            .math_mode
            .or(parse_env_value(
                environment.value("FTTS_MATH_MODE"),
                "FTTS_MATH_MODE",
                MathMode::value_variants(),
            )?)
            .unwrap_or(MathMode::Fast);
        let voice_pack = cli.voice_pack.unwrap_or(VoicePackProfile::Portable);
        let normalize = cli.normalize.unwrap_or(NormalizeMode::Verbatim);
        Ok(Self {
            profile,
            packet_frames,
            math_mode,
            voice_pack,
            normalize,
        })
    }

    fn normalization_options(&self) -> NormalizationOptions {
        NormalizationOptions {
            mode: self.normalize.into(),
            ..NormalizationOptions::default()
        }
    }
}

fn parse_env_value<T>(
    value: Option<&str>,
    name: &str,
    variants: &'static [T],
) -> Result<Option<T>, FttsError>
where
    T: ValueEnum + Copy,
{
    match value {
        None => Ok(None),
        Some(value) => T::from_str(value, true).map(Some).map_err(|_| {
            let choices = variants
                .iter()
                .filter_map(|variant| variant.to_possible_value())
                .map(|variant| variant.get_name().to_owned())
                .collect::<Vec<_>>()
                .join(", ");
            FttsError::Usage(format!("invalid {name}={value:?}; use one of: {choices}"))
        }),
    }
}

/// Capabilities of the concrete I/O handles owned by the process entry point.
///
/// Sink-agnostic command functions cannot infer these from `&mut dyn Write`. Keeping them
/// explicit prevents a library call that writes to a buffer from inheriting the parent process's
/// TTY state and accidentally emitting prose, blocking for input, or corrupting NDJSON.
#[derive(Clone, Copy, Debug, Default)]
struct IoCapabilities {
    human_output: bool,
    can_confirm: bool,
}

fn dispatch(
    cli: Cli,
    environment: &Environment,
    stdin: &mut dyn Read,
    stdout: &mut dyn Write,
    stderr: &mut dyn Write,
    capabilities: IoCapabilities,
) -> Result<(), FttsError> {
    match &cli.command {
        Command::Say(args) => run_say(&cli, args, environment, stdin, stdout, stderr, capabilities),
        Command::MakeVideo(args) => {
            run_make_video(&cli, args, environment, stdin, stdout, stderr, capabilities)
        }
        Command::Enroll(args) => run_enroll(args, environment, stdin, stdout, capabilities),
        Command::Voice(VoiceArgs {
            command: VoiceCommand::Inspect { path },
        }) => run_voice_inspect(path, stdout),
        Command::Card(args) => run_card(args, stdout),
        Command::Convert(args) => run_convert(&cli, args, environment, stdout, stderr),
        Command::Pull(args) => run_pull(args, environment, stdout),
        // Talk is dispatched in `cli_main` BEFORE the stdio locks exist (see there); by
        // this point it has already run and returned.
        Command::Talk(_) => unreachable!("talk dispatches before the stdio locks are taken"),
        Command::Robot(args) => run_robot(args.command.clone(), environment, stdout),
        Command::Doctor(args) => run_doctor(args, environment, stdout),
        Command::ResidentDaemon(args) => resident::run_daemon(&args.bundle_root),
    }
}

/// `ftts talk`: the live conversation session (bead frankentts-edz0). Model resolution
/// and voice naming reuse `say`'s exact surfaces; transport rules live in `talk`.
fn run_talk_command(
    cli: &Cli,
    args: &TalkArgs,
    environment: &Environment,
) -> Result<(), FttsError> {
    install_talk_signal_handler();
    let model = resolve_model(args.model.as_deref(), environment)?;
    let bundle = synth::ModelBundle::resolve(Path::new(&model))?;
    let voices = |name: &str| -> Result<Vec<f32>, FttsError> {
        let path = match materialize_preset_voice(name) {
            Some(result) => result?,
            None => PathBuf::from(name),
        };
        synth::speaker_from_voice(
            &bundle,
            &path,
            synth::ReferenceCleanup {
                denoise: None,
                dereverb: None,
            },
        )
    };
    let settings = EffectiveSettings::resolve(cli, environment)?;
    talk::run_talk(
        &bundle,
        args.pcm_out.as_ref(),
        &voices,
        settings.normalization_options(),
        cli.seed.unwrap_or(0),
    )
}

#[derive(Debug, clap::Args)]
struct TalkArgs {
    /// Model directory (defaults to the standard cache location).
    #[arg(long, value_name = "DIR")]
    model: Option<PathBuf>,
    /// Write session PCM here (file or FIFO). Default on Unix: inherited fd 3.
    /// Required on Windows, where fd inheritance does not exist.
    #[arg(long, value_name = "PATH")]
    pcm_out: Option<PathBuf>,
}

/// A source tensor pinned by the truth-pack inventory and its reviewed storage policy.
#[derive(Clone, Debug)]
struct PinnedMainTensor {
    name: String,
    dtype: Dtype,
    shape: Vec<usize>,
    access_class: AccessClass,
    storage: TensorStoragePolicy,
}

fn run_convert(
    cli: &Cli,
    args: &ConvertArgs,
    environment: &Environment,
    stdout: &mut dyn Write,
    stderr: &mut dyn Write,
) -> Result<(), FttsError> {
    let run = robot::RunContext::generate();
    let outcome = run_convert_events(cli, args, environment, &run, &mut |event| {
        write_json_line(stdout, event)
    });

    if let Err(error) = &outcome {
        let mut event = run.event(robot::EventType::RunError);
        event.insert("exit_code".to_owned(), json!(error.exit_code().as_u8()));
        event.insert("kind".to_owned(), json!(error.exit_code().description()));
        event.insert("message".to_owned(), json!(error.to_string()));
        event.insert("remediation".to_owned(), json!(error.remediation()));
        event.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
        write_json_line(stderr, &Value::Object(event))?;
    }

    outcome
}

/// Converts the pinned main checkpoint and emits the normal run lifecycle receipt.
///
/// The source mapping owns no writable state. The destination is first created under a unique
/// sibling name with `create_new`, then atomically renamed only after the streaming writer, an
/// `fsync`, and a digest-validating mapped re-read all succeed. We deliberately leave a failed
/// staging file in place for diagnosis rather than deleting data behind the caller's back.
fn run_convert_events(
    cli: &Cli,
    args: &ConvertArgs,
    environment: &Environment,
    run: &robot::RunContext,
    emit: &mut dyn FnMut(&Value) -> Result<(), FttsError>,
) -> Result<(), FttsError> {
    let settings = EffectiveSettings::resolve(cli, environment)?;
    let mut start = run.event(robot::EventType::RunStart);
    start.insert("command".to_owned(), json!("convert"));
    start.insert("profile".to_owned(), json!(settings.profile.as_str()));
    start.insert(
        "packet_frames".to_owned(),
        json!(settings.packet_frames.as_str()),
    );
    start.insert("math_mode".to_owned(), json!(settings.math_mode.as_str()));
    start.insert("stateless".to_owned(), json!(true));
    start.insert("seed".to_owned(), json!(cli.seed));
    start.insert("model".to_owned(), Value::Null);
    start.insert("voice".to_owned(), Value::Null);
    emit(&Value::Object(start))?;
    let mut seq = 0_u64;

    emit_stage(run, emit, "source_preflight", "begin", &mut seq)?;
    let source = resolve_pinned_main_source(&args.source)?;
    let mapping = MappedFile::open(&source).map_err(|error| {
        FttsError::Input(format!(
            "cannot memory-map pinned source checkpoint {}: {error}",
            source.display()
        ))
    })?;
    let (manifest, plan) = pinned_main_conversion_plan(args.embed_q8, args.micro_q8)?;
    let staging = conversion_staging_path(&args.output)?;
    emit_stage(run, emit, "source_preflight", "end", &mut seq)?;

    emit_stage(run, emit, "convert", "begin", &mut seq)?;
    let destination = std::fs::File::options()
        .write(true)
        .create_new(true)
        .open(&staging)
        .map_err(|error| {
            FttsError::Input(format!(
                "cannot create conversion staging artifact {}: {error}; the output path is never overwritten",
                staging.display()
            ))
        })?;
    let destination = convert_safetensors_streaming(
        mapping.as_slice(),
        &manifest,
        &plan,
        destination,
    )
    .map_err(|error| {
        FttsError::ArtifactFormat(format!(
            "conversion failed before publication: {error}; staging artifact retained at {}",
            staging.display()
        ))
    })?;
    destination.sync_all().map_err(|error| {
        FttsError::ArtifactFormat(format!(
            "cannot sync converted artifact at {}: {error}; staging artifact retained",
            staging.display()
        ))
    })?;
    drop(destination);
    emit_stage(run, emit, "convert", "end", &mut seq)?;

    emit_stage(run, emit, "verify", "begin", &mut seq)?;
    let verified = MappedFttsq::open(&staging).map_err(|error| {
        FttsError::ArtifactFormat(format!(
            "converted staging artifact did not pass digest re-read: {error}; retained at {}",
            staging.display()
        ))
    })?;
    if verified.reader().source_sha256() != PINNED_MAIN_WEIGHTS_SHA256 {
        return Err(FttsError::ArtifactFormat(format!(
            "converted staging artifact recorded an unexpected source digest {}; retained at {}",
            verified.reader().source_sha256(),
            staging.display()
        )));
    }
    drop(verified);
    std::fs::rename(&staging, &args.output).map_err(|error| {
        FttsError::ArtifactFormat(format!(
            "converted artifact verified but could not be published from {} to {}: {error}; staging artifact retained",
            staging.display(),
            args.output.display()
        ))
    })?;
    emit_stage(run, emit, "verify", "end", &mut seq)?;

    let mut complete = run.event(robot::EventType::RunComplete);
    complete.insert("exit_code".to_owned(), json!(FttsExitCode::Success.as_u8()));
    complete.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
    complete.insert("frames".to_owned(), json!(0));
    complete.insert("audio_bytes".to_owned(), json!(0));
    emit(&Value::Object(complete))
}

fn resolve_pinned_main_source(source: &Path) -> Result<PathBuf, FttsError> {
    let source = if source.is_dir() {
        source.join(PINNED_MAIN_WEIGHTS_FILENAME)
    } else {
        source.to_owned()
    };
    if !source.is_file() {
        return Err(FttsError::Input(format!(
            "pinned main checkpoint {} does not exist or is not a file; pass model.safetensors or its containing directory",
            source.display()
        )));
    }
    if source.file_name().and_then(|name| name.to_str()) != Some(PINNED_MAIN_WEIGHTS_FILENAME) {
        return Err(FttsError::Input(format!(
            "this converter accepts the pinned main checkpoint named {PINNED_MAIN_WEIGHTS_FILENAME}, not {}",
            source.display()
        )));
    }
    Ok(source)
}

fn conversion_staging_path(output: &Path) -> Result<PathBuf, FttsError> {
    if output.exists() {
        return Err(FttsError::Input(format!(
            "refusing to overwrite existing output {}; choose a new -o path",
            output.display()
        )));
    }
    let parent = output.parent().unwrap_or_else(|| Path::new("."));
    let file_name = output
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| {
            FttsError::Usage("conversion output must name a file, not a directory".to_owned())
        })?;
    let nonce = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_err(|error| FttsError::Generic(format!("system clock is before UNIX_EPOCH: {error}")))?
        .as_nanos();
    let staging = parent.join(format!(
        ".{file_name}.fttsq-converting-{}-{nonce}",
        std::process::id()
    ));
    Ok(staging)
}

fn pinned_main_conversion_plan(
    embed_q8: bool,
    micro_q8: bool,
) -> Result<(WeightsManifest, StreamingConversionPlan), FttsError> {
    let specs = pinned_main_tensor_specs(embed_q8, micro_q8)?;
    let manifest = WeightsManifest::from_expectations(
        "Qwen/Qwen3-TTS-12Hz-0.6B-Base main checkpoint",
        specs
            .iter()
            .map(|spec| ExpectedTensor::new(&spec.name, spec.shape.clone(), spec.dtype)),
    );
    let model_config = serde_json::from_str(PINNED_MODEL_CONFIG).map_err(|error| {
        FttsError::Generic(format!(
            "checked-in pinned model config is invalid JSON: {error}"
        ))
    })?;
    let q8_count = specs
        .iter()
        .filter(|spec| spec.storage == TensorStoragePolicy::Q8PerOutputChannel)
        .count();
    let mut plan = StreamingConversionPlan::new(
        "qwen3-tts-12hz-0.6b-base",
        PINNED_MAIN_WEIGHTS_SHA256,
    )
    .license_notice(pinned_license_notice())
    .model_config(model_config)
    .quantization_manifest(json!({
        "source": {
            "repository": "Qwen/Qwen3-TTS-12Hz-0.6B-Base",
            "revision": PINNED_MODEL_REVISION,
            "file": PINNED_MAIN_WEIGHTS_FILENAME,
            "sha256": PINNED_MAIN_WEIGHTS_SHA256,
        },
        "q8_recipe": "symmetric per-output-channel int8; zero_point=0; scale=max_abs(row)/127",
        "q8_tensor_count": q8_count,
        "verbatim_tensor_count": specs.len() - q8_count,
        "q8_scope": match (embed_q8, micro_q8) {
            (true, true) => "talker and residual-code-microdecoder attention/MLP projection matrices, plus the cold text embedding (per-64-element-group scales; --embed-q8) and the microdecoder per-depth embedding/head tables (--micro-q8)",
            (true, false) => "talker and residual-code-microdecoder attention/MLP projection matrices, plus the cold text embedding (per-64-element-group scales; --embed-q8)",
            (false, true) => "talker and residual-code-microdecoder attention/MLP projection matrices, plus the microdecoder per-depth embedding/head tables (--micro-q8)",
            (false, false) => "talker and residual-code-microdecoder attention/MLP projection matrices only",
        },
        "verbatim_scope": if embed_q8 || micro_q8 {
            "norms, non-Q8 embeddings and heads, speaker path, and every tensor outside the reviewed Q8 set"
        } else {
            "norms, heads, embeddings, speaker path, and every tensor outside the reviewed Q8 projection set"
        },
        "embedding_q8": embed_q8,
        "micro_tables_q8": micro_q8,
    }));
    for spec in specs {
        let conversion = match spec.storage {
            TensorStoragePolicy::Verbatim => {
                TensorConversion::verbatim(&spec.name, &spec.name, spec.access_class)
            }
            TensorStoragePolicy::Q8PerOutputChannel => {
                TensorConversion::q8_per_output_channel(&spec.name, &spec.name, spec.access_class)
            }
            TensorStoragePolicy::Q8PerGroup64 => {
                TensorConversion::q8_per_group_64(&spec.name, &spec.name, spec.access_class)
            }
        };
        plan = plan.tensor(conversion);
    }
    Ok((manifest, plan))
}

fn pinned_main_tensor_specs(
    embed_q8: bool,
    micro_q8: bool,
) -> Result<Vec<PinnedMainTensor>, FttsError> {
    let inventory: Value = serde_json::from_str(PINNED_TENSOR_INVENTORY).map_err(|error| {
        FttsError::Generic(format!(
            "checked-in tensor inventory is invalid JSON: {error}"
        ))
    })?;
    if inventory.get("source_pin").and_then(Value::as_str)
        != Some(&format!(
            "Qwen/Qwen3-TTS-12Hz-0.6B-Base@{PINNED_MODEL_REVISION}"
        ))
    {
        return Err(FttsError::Generic(
            "checked-in tensor inventory does not name the pinned Qwen3-TTS revision".to_owned(),
        ));
    }
    let records = inventory
        .get("tensors")
        .and_then(Value::as_array)
        .ok_or_else(|| {
            FttsError::Generic("checked-in tensor inventory lacks tensors[]".to_owned())
        })?;
    let mut specs = Vec::new();
    for record in records {
        if record.get("source").and_then(Value::as_str) != Some(PINNED_MAIN_WEIGHTS_FILENAME) {
            continue;
        }
        let name = required_inventory_string(record, "name")?.to_owned();
        let dtype = match required_inventory_string(record, "dtype")? {
            "BF16" => Dtype::Bf16,
            "F32" => Dtype::F32,
            other => {
                return Err(FttsError::Generic(format!(
                    "pinned main inventory has unsupported dtype {other:?} for {name}"
                )));
            }
        };
        let shape = record
            .get("shape")
            .and_then(Value::as_array)
            .ok_or_else(|| {
                FttsError::Generic(format!("pinned inventory tensor {name} lacks shape[]"))
            })?
            .iter()
            .map(|dimension| {
                dimension
                    .as_u64()
                    .and_then(|dimension| usize::try_from(dimension).ok())
                    .ok_or_else(|| {
                        FttsError::Generic(format!(
                            "pinned inventory tensor {name} has a non-usize shape dimension"
                        ))
                    })
            })
            .collect::<Result<Vec<_>, _>>()?;
        // The cold text embedding joins the Q8 set only on explicit request: 47.4% of the
        // artifact (census, frankentts-o461), halved by Q8, but it ships as default only
        // after the artifact-v2 gates (frankentts-6ea1). GROUPED scales, not per-row: the
        // most common tokens' rows measured 23.8 dB SQNR under one row scale (their energy
        // is uneven across the row) and 35.0 dB under 64-element groups, for ~19 MB of
        // scales. The loader reads grouped and per-row forms alike.
        let storage = if is_q8_projection(&name) {
            TensorStoragePolicy::Q8PerOutputChannel
        } else if embed_q8 && name == "talker.model.text_embedding.weight" {
            TensorStoragePolicy::Q8PerGroup64
        } else if micro_q8 && is_micro_table(&name) {
            TensorStoragePolicy::Q8PerOutputChannel
        } else {
            TensorStoragePolicy::Verbatim
        };
        specs.push(PinnedMainTensor {
            access_class: main_access_class(&name)?,
            name,
            dtype,
            shape,
            storage,
        });
    }
    if specs.len() != PINNED_MAIN_TENSOR_COUNT {
        return Err(FttsError::Generic(format!(
            "pinned main inventory contains {} tensors, expected {PINNED_MAIN_TENSOR_COUNT}",
            specs.len()
        )));
    }
    Ok(specs)
}

fn required_inventory_string<'a>(record: &'a Value, field: &str) -> Result<&'a str, FttsError> {
    record.get(field).and_then(Value::as_str).ok_or_else(|| {
        FttsError::Generic(format!(
            "checked-in tensor inventory record lacks string {field:?}"
        ))
    })
}

fn is_q8_projection(name: &str) -> bool {
    (name.starts_with("talker.model.layers.")
        || name.starts_with("talker.code_predictor.model.layers."))
        && [
            ".self_attn.q_proj.weight",
            ".self_attn.k_proj.weight",
            ".self_attn.v_proj.weight",
            ".self_attn.o_proj.weight",
            ".mlp.gate_proj.weight",
            ".mlp.up_proj.weight",
            ".mlp.down_proj.weight",
        ]
        .iter()
        .any(|suffix| name.ends_with(suffix))
}

/// The microdecoder's per-depth residual embedding tables and scoring heads: the ~126 MB
/// bf16 block the census flagged as the second-largest wide surface after the cold text
/// embedding (frankentts-o461). Fifteen `[2048, 1024]` tables each side; `--micro-q8`
/// stores them per-row Q8, which halves them and which [`crate::synth`] consumes
/// natively — heads feed the int8 refine path's coarse pass directly, and the embedding
/// gather dequantizes one row at a time (bead frankentts-x7bt).
fn is_micro_table(name: &str) -> bool {
    (name.starts_with("talker.code_predictor.model.codec_embedding.")
        || name.starts_with("talker.code_predictor.lm_head."))
        && name.ends_with(".weight")
}

fn main_access_class(name: &str) -> Result<AccessClass, FttsError> {
    if name == "talker.model.text_embedding.weight" {
        Ok(AccessClass::ColdTextEmbedding)
    } else if name.starts_with("speaker_encoder.") {
        Ok(AccessClass::EnrollmentSpeakerEncoder)
    } else if name.starts_with("talker.code_predictor.")
        || name == "talker.model.codec_embedding.weight"
    {
        Ok(AccessClass::HotRecurrentMicrodecoder)
    } else if name.starts_with("talker.model.")
        || name.starts_with("talker.codec_head.")
        || name.starts_with("talker.text_projection.")
    {
        Ok(AccessClass::HotRecurrentTalker)
    } else {
        Err(FttsError::Generic(format!(
            "pinned main tensor {name} has no reviewed access-class assignment"
        )))
    }
}

fn pinned_license_notice() -> String {
    format!(
        "This artifact contains model weights derived from\n\
         Qwen3-TTS-12Hz-0.6B-Base (https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base)\n\
         and code derived from QwenLM/Qwen3-TTS (https://github.com/QwenLM/Qwen3-TTS).\n\n\
         Copyright 2026 Alibaba Cloud\n\n\
         Licensed under the Apache License, Version 2.0.\n\
         http://www.apache.org/licenses/LICENSE-2.0\n\n\
         CHANGES: the original bfloat16 weights were converted to franken_tts's\n\
         quantized .fttsq container. Tensors were requantized according to the\n\
         artifact's quantization manifest; protected tensors remain verbatim.\n\
         The model graph is re-implemented in Rust.\n\n\
         Apache License, Version 2.0:\n\n{APACHE_LICENSE}"
    )
}

/// The SIGINT/SIGTERM bridge for one `say` run (bead frankentts-astz).
///
/// `ctrlc` delivers signals on its own thread, so the registered closure is ordinary
/// code, not an async-signal handler: the first strike records [`CancelState::tripped`]
/// and trips the engine token (the frame loop notices within one 80 ms frame); any
/// later strike exits immediately with the cancelled code — the behavioral equivalent
/// of restoring the default disposition, so a wedged process can still be killed. The
/// OS hook is installed once per process and each run swaps in its own state; a failed
/// install degrades to the default disposition rather than failing the run.
struct CancelState {
    /// Signal strikes seen so far: first vs force-exit.
    signals: std::sync::atomic::AtomicU32,
    /// Set by the first signal; polled where the token cannot reach — the resident
    /// daemon round-trip, whose v1 wire protocol has no cancel operation.
    tripped: std::sync::atomic::AtomicBool,
    /// Tripped by the first signal; aborts the in-process engine loop.
    token: ftts_core::CancellationToken,
}

impl CancelState {
    fn new() -> Self {
        Self {
            signals: std::sync::atomic::AtomicU32::new(0),
            tripped: std::sync::atomic::AtomicBool::new(false),
            token: ftts_core::CancellationToken::new(),
        }
    }

    /// Whether any cancellation request has landed, by either route.
    fn was_tripped(&self) -> bool {
        self.tripped.load(std::sync::atomic::Ordering::Relaxed) || self.token.is_cancelled()
    }
}

/// What one delivered signal means for the run.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum StrikeAction {
    /// First signal: cancel cooperatively.
    Trip,
    /// Any later signal: stop now.
    ForceExit,
}

/// The pure two-strike decision, unit-tested here; real delivery timing belongs to
/// the cancellation e2e battery (`frankentts-9t5v`).
fn next_strike_action(signals_seen: u32) -> StrikeAction {
    if signals_seen <= 1 {
        StrikeAction::Trip
    } else {
        StrikeAction::ForceExit
    }
}

/// The ctrlc hook itself, installed on first force. It reads [`ACTIVE_CANCEL`] on
/// every delivery, so later runs replace the served state without touching the OS
/// handler again.
static SIGNAL_HOOK: std::sync::LazyLock<()> = std::sync::LazyLock::new(|| {
    // Best effort by design: if the hook cannot be installed (exotic platform,
    // sandbox), Ctrl-C keeps its default killing disposition instead.
    let _ = ctrlc::set_handler(|| {
        let Ok(guard) = ACTIVE_CANCEL.lock() else {
            return;
        };
        let Some(state) = guard.as_ref() else {
            drop(guard);
            // No `say` run is served: the strike belongs to a live `ftts talk`
            // session. Strike one cancels cooperatively through the router; any
            // later strike force-exits with the cancelled code.
            let seen = TALK_STRIKES.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1;
            if next_strike_action(seen) == StrikeAction::ForceExit {
                std::process::exit(i32::from(FttsExitCode::Cancelled.as_u8()));
            }
            let talk_inbox = TALK_SIGNAL_INBOX
                .lock()
                .ok()
                .and_then(|armed| armed.clone());
            match talk_inbox {
                Some(inbox) => {
                    let _ = inbox.send(crate::talk::RouterIn::Sigint);
                }
                // The bridge is armed but the router is gone; honour the strike.
                None => std::process::exit(i32::from(FttsExitCode::Cancelled.as_u8())),
            }
            return;
        };
        let seen = state
            .signals
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed)
            + 1;
        drop(guard);
        match next_strike_action(seen) {
            StrikeAction::Trip => trip_active_cancel(),
            StrikeAction::ForceExit => {
                std::process::exit(i32::from(FttsExitCode::Cancelled.as_u8()));
            }
        }
    });
});

static ACTIVE_CANCEL: std::sync::Mutex<Option<std::sync::Arc<CancelState>>> =
    std::sync::Mutex::new(None);

/// Armed by a live `ftts talk` session so SIGINT strikes reach its router
/// ([`crate::talk::RouterIn::Sigint`]: cancel the current utterance, settle its
/// receipt, exit 6). Disarmed when the session ends; strikes with no live session
/// force-exit with the cancelled code, matching the two-strike contract.
static TALK_SIGNAL_INBOX: std::sync::Mutex<
    Option<std::sync::mpsc::SyncSender<crate::talk::RouterIn>>,
> = std::sync::Mutex::new(None);

/// SIGINT strikes seen while no `say` run is served (i.e. during `ftts talk`).
static TALK_STRIKES: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);

/// Make `state` the run the signal bridge serves.
fn install_cancel_handler(state: std::sync::Arc<CancelState>) {
    LazyLock::force(&SIGNAL_HOOK);
    *ACTIVE_CANCEL.lock().expect("cancel-state mutex poisoned") = Some(state);
}

/// Arm the process-wide signal hook for a `talk` session.
///
/// Unlike one-shot `say`, talk has no [`CancelState`] to install: its first strike travels through
/// [`TALK_SIGNAL_INBOX`] to the session router. The hook still has to be forced before model load,
/// otherwise the operating system retains its default SIGINT disposition and kills the process
/// before the router can settle `speak_cancelled` and `session_end` receipts.
fn install_talk_signal_handler() {
    TALK_STRIKES.store(0, std::sync::atomic::Ordering::Relaxed);
    LazyLock::force(&SIGNAL_HOOK);
}

/// Record the cancellation and trip whichever engine token is currently serving.
fn trip_active_cancel() {
    let Ok(guard) = ACTIVE_CANCEL.lock() else {
        return;
    };
    if let Some(state) = guard.as_ref() {
        state
            .tripped
            .store(true, std::sync::atomic::Ordering::Relaxed);
        state.token.cancel();
    }
}

/// Finalize what a cancelled run already delivered and word the disposition for the
/// terminal event's message field — the existing `run_error` shape carries it, no new
/// fields anywhere.
///
/// File sinks get their header patched to exactly the samples that landed: a parseable
/// partial artifact beats a torn file. Compressed targets keep that partial WAV at its
/// staging path and skip the system encoder entirely — handing a truncated file to the
/// encoder would produce garbage or nothing, never a valid `.m4a`, and the event says
/// so. Raw streams already ended at a packet boundary; the streamed byte count is the
/// accounting receipt.
fn cancelled_run_disposition(audio: AudioOutput, plan: Option<&OutputPlan>) -> FttsError {
    let streamed_bytes = audio.byte_offset();
    let samples = match audio.finish() {
        Ok(samples) => samples,
        Err(error) => {
            return FttsError::Cancelled(format!(
                "cancelled by signal; the partial WAV could not be finalized: {error}"
            ));
        }
    };
    let message = match plan {
        None => format!("cancelled by signal after streaming {streamed_bytes} raw PCM bytes"),
        Some(plan) if plan.format == OutputFormat::Wav => format!(
            "cancelled after {samples} samples; partial WAV kept at {}",
            plan.final_path.display()
        ),
        Some(plan) => format!(
            "cancelled after {samples} samples; encoding to {} skipped, partial WAV kept at {}",
            plan.final_path.display(),
            plan.wav_path.display()
        ),
    };
    FttsError::Cancelled(message)
}

fn run_say(
    cli: &Cli,
    args: &SayArgs,
    environment: &Environment,
    stdin: &mut dyn Read,
    stdout: &mut dyn Write,
    stderr: &mut dyn Write,
    capabilities: IoCapabilities,
) -> Result<(), FttsError> {
    let run = robot::RunContext::generate();
    // `--stream raw` puts PCM on stdout, so events move to stderr. One contract, chosen once here
    // so no later emission can pick the other stream and interleave NDJSON with audio bytes. The
    // two branches also settle the borrows: in raw mode audio owns `stdout` and events own
    // `stderr`; otherwise events own `stdout` and the raw sink is a discard that never runs.
    let outcome = if args.stream == Some(StreamMode::Raw) {
        run_say_events(
            cli,
            args,
            environment,
            stdin,
            &run,
            SayEventOutput {
                raw_audio: stdout,
                human_progress: false,
            },
            &mut |event| write_json_line(stderr, event),
        )
    } else if args.robot || !capabilities.human_output {
        let mut discard = io::sink();
        run_say_events(
            cli,
            args,
            environment,
            stdin,
            &run,
            SayEventOutput {
                raw_audio: &mut discard,
                human_progress: false,
            },
            &mut |event| write_json_line(stdout, event),
        )
    } else {
        // A terminal gets the human view of the same lifecycle. The NDJSON contract is untouched:
        // it is what every pipe, file, CI job and agent still receives, because none of them is a
        // terminal. `--robot` forces it back on for a human debugging the stream itself.
        let mut discard = io::sink();
        let destination = args
            .output
            .as_deref()
            .or(args.output_positional.as_deref())
            .map(|path| path.display().to_string());
        let mut presenter = style::SayPresenter::writing_to(destination);
        run_say_events(
            cli,
            args,
            environment,
            stdin,
            &run,
            SayEventOutput {
                raw_audio: &mut discard,
                human_progress: true,
            },
            &mut |event| {
                presenter
                    .event(event, stdout)
                    .map_err(|error| FttsError::Generic(format!("cannot write progress: {error}")))
            },
        )
    };

    if let Err(error) = &outcome {
        // The error is reported on the machine contract, not only as a human line: run_error is a
        // stderr event by definition (see the catalogue), so it goes to stderr on both stream
        // shapes.
        let mut event = run.event(robot::EventType::RunError);
        event.insert("exit_code".to_owned(), json!(error.exit_code().as_u8()));
        event.insert("kind".to_owned(), json!(error.exit_code().description()));
        event.insert("message".to_owned(), json!(error.to_string()));
        event.insert("remediation".to_owned(), json!(error.remediation()));
        event.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
        write_json_line(stderr, &Value::Object(event))?;
    }

    outcome
}

/// `ftts make-video`: synthesize (or take a WAV) and render the branded
/// share video. Frames, waveform, and text are pure Rust (`ftts-video`);
/// `.mp4` goes through the same first-available-system-encoder contract as
/// `ftts say`'s `.m4a` path, and `.y4m` + `.wav` is the native no-encoder
/// output.
fn run_make_video(
    cli: &Cli,
    args: &MakeVideoArgs,
    environment: &Environment,
    stdin: &mut dyn Read,
    stdout: &mut dyn Write,
    stderr: &mut dyn Write,
    capabilities: IoCapabilities,
) -> Result<(), FttsError> {
    let output = args
        .output
        .clone()
        .or_else(|| args.output_positional.clone())
        .ok_or_else(|| {
            FttsError::Usage(
                "`ftts make-video` needs an output path (`ftts make-video \"text\" out.mp4`)"
                    .to_owned(),
            )
        })?;
    let extension = output
        .extension()
        .and_then(|extension| extension.to_str())
        .map(str::to_ascii_lowercase);
    let is_mp4 = match extension.as_deref() {
        Some("mp4") => true,
        Some("y4m") => false,
        other => {
            return Err(FttsError::Usage(format!(
                "unsupported video extension `.{}`; use .mp4 (system encoder) or .y4m (native)",
                other.unwrap_or("<none>")
            )));
        }
    };

    // The voice pill needs a human name: an explicit --label wins, a preset
    // keeps its capitalized name, a custom voice shows its file stem. With
    // no voice given, the label follows the same default chain `say` uses
    // (FTTS_DEFAULT_VOICE, then an enrolled default voice, then built-in matt)
    // rather than claiming "Matt" over someone's enrolled voice.
    let capitalize = |raw: &str| {
        let mut chars = raw.chars();
        chars
            .next()
            .map(|first| first.to_uppercase().collect::<String>() + chars.as_str())
            .unwrap_or_else(|| raw.to_owned())
    };
    let stem_of = |path: &Path| {
        path.file_stem()
            .and_then(|stem| stem.to_str())
            .map(str::to_owned)
    };
    let label = args.label.clone().unwrap_or_else(|| {
        if let Some(voice) = &args.voice {
            return stem_of(voice)
                .map(|stem| capitalize(&stem))
                .unwrap_or_else(|| "Voice".to_owned());
        }
        if let Some(audio) = &args.audio {
            // Rendering someone's own recording: name it after the file.
            return stem_of(audio)
                .map(|stem| capitalize(&stem))
                .unwrap_or_else(|| "Voice".to_owned());
        }
        if let Some(default_voice) = environment.value("FTTS_DEFAULT_VOICE")
            && let Some(stem) = stem_of(Path::new(default_voice))
        {
            return capitalize(&stem);
        }
        let enrolled_default = resolve_model(args.model.as_deref(), environment)
            .ok()
            .and_then(|model| synth::ModelBundle::resolve(Path::new(&model)).ok())
            .is_some_and(|bundle| {
                bundle.root.join("default.ftvoice").is_file()
                    || bundle.root.join("default.spk").is_file()
            });
        if enrolled_default {
            "My voice".to_owned()
        } else {
            "Matt".to_owned()
        }
    });

    // Audio: either supplied, or synthesized through the full `say` pipeline
    // (same events, presenter, and resident engine). An mp4 gets a staging
    // WAV that is consumed by the encoder; a y4m synthesizes straight into
    // its `.wav` sibling, which stays as the video's audio track.
    let staging: Option<PathBuf> = if args.audio.is_none() {
        if is_mp4 {
            let mut path = output.as_os_str().to_owned();
            path.push(".ftts-staging.wav");
            Some(PathBuf::from(path))
        } else {
            Some(output.with_extension("wav"))
        }
    } else {
        None
    };
    if let Some(staging_path) = &staging {
        let say_args = SayArgs {
            text: args.text.clone(),
            output_positional: None,
            file: args.file.clone(),
            model: args.model.clone(),
            voice: args.voice.clone(),
            output: Some(staging_path.clone()),
            stream: None,
            check: false,
            robot: false,
            no_resident: args.no_resident,
        };
        run_say(
            cli,
            &say_args,
            environment,
            stdin,
            stdout,
            stderr,
            capabilities,
        )?;
    }
    let audio_path = args
        .audio
        .clone()
        .or_else(|| staging.clone())
        .unwrap_or_default();

    // The video phase reports on the same machine contract as everything else: its own
    // run (the synthesis phase above already closed a `say` run), with `stage` events
    // around rendering and a `run_complete` carrying the video frame count. A terminal
    // gets the human progress line instead; agents were previously left with silence
    // between the say run ending and the process exiting.
    let interactive = capabilities.human_output;
    let settings = EffectiveSettings::resolve(cli, environment)?;
    let run = robot::RunContext::generate();
    let mut seq = 0_u64;
    let emit = |event: &Value, stdout: &mut dyn Write| -> Result<(), FttsError> {
        if interactive {
            return Ok(());
        }
        write_json_line(stdout, event)
    };
    let mut start = run.event(robot::EventType::RunStart);
    start.insert("command".to_owned(), json!("make-video"));
    start.insert("profile".to_owned(), json!(settings.profile.as_str()));
    start.insert(
        "packet_frames".to_owned(),
        json!(settings.packet_frames.as_str()),
    );
    start.insert("math_mode".to_owned(), json!(settings.math_mode.as_str()));
    start.insert("stateless".to_owned(), json!(true));
    start.insert("seed".to_owned(), json!(cli.seed));
    start.insert("model".to_owned(), json!(args.model.as_deref()));
    start.insert("voice".to_owned(), json!(label));
    emit(&Value::Object(start), stdout)?;

    if interactive {
        writeln!(stdout, "rendering video: {}", output.display())
            .map_err(|error| FttsError::Generic(format!("cannot write progress: {error}")))?;
    }
    let request = ftts_video::VideoRequest {
        audio: &audio_path,
        output: &output,
        voice_label: &label,
    };
    emit_stage(
        &run,
        &mut |e| emit(e, stdout),
        "video_render",
        "begin",
        &mut seq,
    )?;
    let mut last_percent = 0usize;
    let mut video_frames = 0_u64;
    let render_result = ftts_video::render(&request, &mut |progress| {
        video_frames = progress.total_frames as u64;
        if !interactive {
            return;
        }
        let percent = progress.frame * 100 / progress.total_frames;
        if percent >= last_percent + 10 || progress.frame == progress.total_frames {
            last_percent = percent;
            let _ = write!(
                stdout,
                "\r  frame {}/{} ({percent}%)",
                progress.frame, progress.total_frames
            );
            let _ = stdout.flush();
        }
    });
    if interactive {
        let _ = writeln!(stdout);
    }
    match &render_result {
        Ok(()) => {
            emit_stage(
                &run,
                &mut |e| emit(e, stdout),
                "video_render",
                "end",
                &mut seq,
            )?;
        }
        Err(message) => {
            // `run_error` is a stderr event by the catalogue, on both stream shapes.
            let mut event = run.event(robot::EventType::RunError);
            let error = FttsError::Generic(message.clone());
            event.insert("exit_code".to_owned(), json!(error.exit_code().as_u8()));
            event.insert("kind".to_owned(), json!(error.exit_code().description()));
            event.insert("message".to_owned(), json!(message));
            event.insert("remediation".to_owned(), json!(error.remediation()));
            event.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
            if !interactive {
                write_json_line(stderr, &Value::Object(event))?;
            }
        }
    }
    render_result.map_err(FttsError::Generic)?;
    let video_bytes = fs::metadata(&output).map_or(0, |meta| meta.len());
    let mut complete = run.event(robot::EventType::RunComplete);
    complete.insert("exit_code".to_owned(), json!(FttsExitCode::Success.as_u8()));
    complete.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
    complete.insert("frames".to_owned(), json!(video_frames));
    // The say run above already reported the PCM bytes; this run's product is the video.
    complete.insert("audio_bytes".to_owned(), json!(0));
    complete.insert("video_bytes".to_owned(), json!(video_bytes));
    emit(&Value::Object(complete), stdout)?;

    // The staging WAV is consumed into the mp4; remove it exactly as the
    // `.m4a` OutputPlan removes its staging file. The `.y4m` path keeps its
    // audio, renamed to the output's `.wav` sibling by the renderer.
    if is_mp4 && let Some(staging_path) = &staging {
        let _ = fs::remove_file(staging_path);
    }
    if interactive {
        writeln!(stdout, "wrote {}", output.display())
            .map_err(|error| FttsError::Generic(format!("cannot write result: {error}")))?;
    }
    Ok(())
}

/// Emit one `stage` event and advance the run's stage counter.
fn emit_stage(
    run: &robot::RunContext,
    emit: &mut dyn FnMut(&Value) -> Result<(), FttsError>,
    name: &str,
    state: &str,
    seq: &mut u64,
) -> Result<(), FttsError> {
    let mut event = run.event(robot::EventType::Stage);
    event.insert("name".to_owned(), json!(name));
    event.insert("seq".to_owned(), json!(*seq));
    event.insert("state".to_owned(), json!(state));
    event.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
    event.insert("budget_ms".to_owned(), Value::Null);
    *seq += 1;
    emit(&Value::Object(event))
}

/// The `say` pipeline proper, emitting its lifecycle through `emit`.
///
/// Split out so the caller owns stream selection and the single `run_error` emission point: a
/// pipeline that emitted its own errors would have to know which stream it was on at every `?`.
struct SayEventOutput<'a> {
    raw_audio: &'a mut dyn Write,
    human_progress: bool,
}

fn run_say_events(
    cli: &Cli,
    args: &SayArgs,
    environment: &Environment,
    stdin: &mut dyn Read,
    run: &robot::RunContext,
    output: SayEventOutput<'_>,
    emit: &mut dyn FnMut(&Value) -> Result<(), FttsError>,
) -> Result<(), FttsError> {
    let settings = EffectiveSettings::resolve(cli, environment)?;

    let mut start = run.event(robot::EventType::RunStart);
    start.insert("command".to_owned(), json!("say"));
    start.insert("profile".to_owned(), json!(settings.profile.as_str()));
    start.insert(
        "packet_frames".to_owned(),
        json!(settings.packet_frames.as_str()),
    );
    start.insert("math_mode".to_owned(), json!(settings.math_mode.as_str()));
    start.insert("stateless".to_owned(), json!(true));
    start.insert("seed".to_owned(), json!(cli.seed));
    start.insert("model".to_owned(), json!(args.model.as_deref()));
    start.insert(
        "voice".to_owned(),
        json!(args.voice.as_ref().map(|path| path.display().to_string())),
    );
    emit(&Value::Object(start))?;

    let mut seq = 0u64;

    emit_stage(run, emit, "resolve", "begin", &mut seq)?;
    let text = read_text(args, stdin)?;
    let model = resolve_model(args.model.as_deref(), environment)?;
    let voice = resolve_requested_voice(args.voice.as_deref(), environment)?;
    emit_stage(run, emit, "resolve", "end", &mut seq)?;

    let request = SynthesisRequest::new(text)
        .with_normalization_options(settings.normalization_options())
        .with_normalization_trace(cli.trace.is_some());

    // Privacy-safe by construction: shape and rule names only, never the text itself. The CLI
    // promises no persisted synthesis history, and an event stream an agent may log is exactly
    // where that promise would leak if this carried the input.
    let mut prepared = run.event(robot::EventType::TextPrepared);
    prepared.insert("normalize".to_owned(), json!(settings.normalize.as_str()));
    prepared.insert(
        "unicode_version".to_owned(),
        json!(ftts_model_qwen::tokenizer::unicode_version()),
    );
    prepared.insert("char_count".to_owned(), json!(request.text.chars().count()));
    prepared.insert(
        "trace_requested".to_owned(),
        json!(request.trace_normalization),
    );
    emit(&Value::Object(prepared))?;

    // `-o PATH` and the positional OUTPUT are the same request; clap rejects supplying both.
    let requested_output: Option<PathBuf> = args
        .output
        .clone()
        .or_else(|| args.output_positional.clone());
    let output_plan = requested_output
        .as_deref()
        .map(OutputPlan::for_path)
        .transpose()?;

    emit_stage(run, emit, "admission", "begin", &mut seq)?;
    let admission = admission_plan(&request.text, &settings)?;
    emit_stage(run, emit, "admission", "end", &mut seq)?;

    if args.check {
        let event = json!({
            "schema_version": ROBOT_SCHEMA_VERSION,
            "event": "check_complete",
            "run_id": run.run_id(),
            "model": model,
            "voice": voice,
            "profile": settings.profile.as_str(),
            "packet_frames": settings.packet_frames.as_str(),
            "math_mode": settings.math_mode.as_str(),
            "voice_pack": settings.voice_pack.as_str(),
            "normalize": settings.normalize.as_str(),
            "normalization_trace_requested": request.trace_normalization,
            "seed": cli.seed,
            "trace": cli.trace.as_ref().map(|path| path.display().to_string()),
            "output": requested_output.as_ref().map(|path| path.display().to_string()),
            "admission": admission,
        });
        emit(&event)?;
        let mut complete = run.event(robot::EventType::RunComplete);
        complete.insert("exit_code".to_owned(), json!(FttsExitCode::Success.as_u8()));
        complete.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
        complete.insert("frames".to_owned(), json!(0));
        complete.insert("audio_bytes".to_owned(), json!(0));
        emit(&Value::Object(complete))?;
        return Ok(());
    }

    // --- audio destination, decided before any model work ----------------------------------
    // A run that synthesizes for thirty seconds and then discovers it has nowhere to put the
    // result has wasted the user's time; the refusal belongs here, before the weights load.
    let raw_stream = args.stream == Some(StreamMode::Raw);
    let mut audio = match (&output_plan, raw_stream) {
        (Some(plan), false) => AudioOutput::wav(&plan.wav_path)?,
        (None, true) => AudioOutput::raw(),
        (None, false) => {
            return Err(FttsError::Usage(
                "`ftts say` has nowhere to put the audio; add an output path (`ftts say \"text\" \
                 out.wav`, or `-o PATH`) or `--stream raw` for PCM on stdout"
                    .to_owned(),
            ));
        }
        // clap declares every output form and `--stream` mutually exclusive.
        (Some(_), true) => unreachable!("clap enforces the conflict"),
    };

    // --- model load ------------------------------------------------------------------------
    emit_stage(run, emit, "load", "begin", &mut seq)?;
    let bundle = synth::ModelBundle::resolve(Path::new(&model))?;
    let voice_path = match voice.as_deref().map(PathBuf::from).or_else(|| {
        // Packs outrank raw vectors when both exist; a pack is what modern enrollment writes.
        ["default.ftvoice", "default.spk"]
            .iter()
            .map(|name| bundle.root.join(name))
            .find(|candidate| candidate.is_file())
    }) {
        Some(path) => path,
        // Out-of-box: no --voice, no FTTS_DEFAULT_VOICE, no enrollment — speak with the built-in
        // default preset rather than refusing. The presets are real enrolled x-vectors taken from
        // speech, so they sit on the speaker encoder's manifold; any user enrollment or explicit
        // voice always outranks them.
        None => materialize_preset_voice(DEFAULT_PRESET_VOICE)
            .expect("the default preset name is a member of PRESET_VOICES")?,
    };
    // A `--voice` that names an audio file (not a .spk vector) computes an ephemeral
    // enrollment, and gets the same automatic denoise `ftts enroll` applies — otherwise the
    // one-off form of the exact same operation would sound worse than the saved form. The
    // report goes unread here: `say` has no enrollment console, and the .spk/preset paths
    // never enter the cleanup code.
    let mut say_denoise_report = None;
    let denoise_ephemeral = bundle.root.join(synth::DENOISE_ARTIFACT_RELPATH).is_file();
    // Ephemeral audio sources keep the automatic denoise here (same rationale as enroll);
    // pack sources already carry their cleaned-audio identity, so no second cleanup runs.
    let voice_conditioning = synth::say_voice_conditioning(
        &bundle,
        &voice_path,
        (denoise_ephemeral).then_some(&mut say_denoise_report),
    )?;
    // With the resident engine (the default), the model stays loaded in a background
    // process and this invocation skips its own hydration; the daemon's load happens
    // inside the synthesis stage on its first request. Any resident-path unavailability
    // falls back to the classic in-process load below, never to a failure.
    //
    // `--stream raw` BYPASSES the resident: the daemon's frozen v1 wire protocol delivers
    // one whole PCM blob after complete synthesis (resident.rs), so a resident-served run
    // can never stream live — and a warm run silently regressing to buffered delivery
    // while the cold run streams would be worse than either behavior alone. Raw streaming
    // therefore pays the in-process load; the warm+streaming surface is the talk session.
    // ICL conditioning cannot ride the resident wire protocol (v1 carries vectors only);
    // serving it through the daemon would silently strip the transcript+tokens quality
    // path, so those runs pay the in-process load instead.
    let use_resident =
        resident::enabled(args.no_resident) && !raw_stream && voice_conditioning.is_xvector();
    let load_inline = || {
        if output.human_progress && !args.robot && !raw_stream {
            synth::LoadedModel::load_with_human_progress(&bundle)
        } else {
            synth::LoadedModel::load(&bundle)
        }
    };
    let loaded = if use_resident {
        None
    } else {
        Some(load_inline()?)
    };
    emit_stage(run, emit, "load", "end", &mut seq)?;

    // --- synthesis -------------------------------------------------------------------------
    // Canonical greedy consumes no RNG state, so an absent `--seed` changes nothing today;
    // 0 is the documented default rather than a value picked per run, which would make a
    // future switch to the production sampler silently irreproducible.
    let seed = cli.seed.unwrap_or(0);

    // The signal bridge goes up before anything slow: a SIGINT during the resident
    // round-trip must land somewhere even though the v1 wire protocol cannot cancel
    // the daemon. Inline synthesis shares this token, so one handler serves both
    // paths (bead frankentts-astz).
    let cancel = std::sync::Arc::new(CancelState::new());
    install_cancel_handler(cancel.clone());

    emit_stage(run, emit, "synthesis", "begin", &mut seq)?;
    let resident_audio = if use_resident {
        let audio = resident::try_synthesize_interruptible(
            &bundle,
            &resident::WireRequest {
                text: &request.text,
                normalize: settings.normalize.as_str(),
                trace: request.trace_normalization,
                speaker: voice_conditioning.embedding(),
                seed,
            },
            // Strike-one must land while the daemon still renders: the poll slice
            // turns the consumed SIGINT into Cancelled within ~100 ms instead of
            // whenever the whole utterance happens to finish (g4zq).
            &|| cancel.was_tripped(),
        )?;
        // The daemon finished anyway — v1 has no cancel op — but honoring the request
        // means discarding the reply, not shipping audio the user asked us to stop
        // making. Same terminal shape as an inline cancel: run_error, exit 6.
        if audio.is_some() && cancel.was_tripped() {
            return Err(FttsError::Cancelled(
                "cancelled while the resident engine was serving the request; its \
                 completed audio was discarded"
                    .to_owned(),
            ));
        }
        audio
    } else {
        None
    };
    // Robot-mode resident observability (bead frankentts-xw2v): which path served the
    // request, as a stage pair so the begin/end discipline holds. The stage NAME
    // carries the state — `resident-hit` (daemon served it), `resident-miss`
    // (consulted but none served; inline fallback) — because the strict-closed stage
    // schema has no spare field and zero schema churn is the standing rule. Not
    // emitted when the resident was disabled outright: `--no-resident` runs are
    // ordinary inline runs, not resident events.
    if use_resident {
        let state = if resident_audio.is_some() {
            "hit"
        } else {
            "miss"
        };
        emit_stage(run, emit, &format!("resident-{state}"), "begin", &mut seq)?;
        emit_stage(run, emit, &format!("resident-{state}"), "end", &mut seq)?;
    }
    // Whether the in-process live path already wrote PCM and emitted `audio_chunk` events
    // during synthesis. The resident path cannot (its v1 wire reply is one whole blob), so
    // it keeps the post-synthesis packetization below.
    let mut live_output_began = false;
    let audio_result = match resident_audio {
        Some(audio) => (audio, false),
        None => {
            let loaded = match loaded {
                Some(loaded) => loaded,
                // The resident path was requested but no daemon could serve it.
                None => load_inline()?,
            };
            let engine = ftts_core::TtsEngine::from_process_environment()
                .map_err(|error| FttsError::Generic(format!("cannot start the engine: {error}")))?;
            // The engine loop aborts on the SHARED token: one SIGINT trips it through
            // the signal bridge, and `cancel.was_tripped()` is what turns whatever
            // refusal the abort produces into the cancelled disposition below.
            let cancellation = &cancel.token;

            // In-process synthesis streams for real: the engine runs on a scoped thread with
            // a channel-backed PcmPacketSink, and THIS thread — which owns `emit`, the audio
            // sink, and the raw stream — consumes packets as they are decoded, writing PCM
            // and emitting `audio_chunk` (and throttled `frame`) events while generation is
            // still running. Backpressure is the bounded channel: a stalled consumer parks
            // the codec worker, which parks the generator — synthesis slows to the consumer's
            // pace instead of buffering unboundedly. Channel disconnect is the shutdown
            // signal in both directions: the producer dropping its senders ends the consume
            // loop, and the consumer dropping the receiver aborts the producer's next send.
            // One consumer thread serves both pipes, so a stalled EVENT reader also pauses
            // synthesis — bounded and cancel-aware, and the fail-closed consumer contract
            // (drain both streams concurrently) already forbids that consumer shape; the
            // independent-queue design belongs to the talk session, not the one-shot CLI.
            enum Live {
                Packet(Vec<f32>, usize),
                Progress(u64, Option<u64>),
            }
            struct ChannelSink(std::sync::mpsc::SyncSender<Live>);
            impl synth::PcmPacketSink for ChannelSink {
                fn deliver(&mut self, samples: &[f32], frames: usize) -> Result<(), FttsError> {
                    self.0
                        .send(Live::Packet(samples.to_vec(), frames))
                        .map_err(|_| {
                            FttsError::Generic(
                                "the live audio consumer stopped accepting packets".to_owned(),
                            )
                        })
                }
            }
            let (live_tx, live_rx) = std::sync::mpsc::sync_channel::<Live>(64);
            let produced = std::thread::scope(|scope| {
                let handle = scope.spawn(|| {
                    // The observer lives inside this closure so that EVERY sender is owned
                    // by the producer side: when synthesis returns, sink and observer drop,
                    // the channel disconnects, and the consume loop below terminates. An
                    // observer outliving the scope would hold a sender forever and deadlock
                    // the loop. Progress sends are try_send — lossy by design (progress
                    // coalesces under pressure); audio uses blocking send and never drops.
                    let progress = std::sync::Mutex::new((live_tx.clone(), None::<u64>));
                    let observer = move |event: ftts_core::SynthesisEvent| {
                        let Ok(mut guard) = progress.lock() else {
                            return;
                        };
                        match event {
                            ftts_core::SynthesisEvent::ResourceAdmission {
                                admitted: true,
                                predicted_max_frames,
                                ..
                            } => guard.1 = Some(predicted_max_frames),
                            ftts_core::SynthesisEvent::FrameProgress { frame } => {
                                let total = guard.1;
                                let _ = guard.0.try_send(Live::Progress(frame, total));
                            }
                            _ => {}
                        }
                    };
                    let mut sink = ChannelSink(live_tx);
                    synth::synthesize(
                        &loaded,
                        &engine,
                        &request,
                        &voice_conditioning,
                        seed,
                        cancellation,
                        &observer,
                        usize::from(settings.packet_frames.frames_per_packet()),
                        None,
                        Some(&mut sink),
                    )
                });

                let mut consumer_error: Option<FttsError> = None;
                let mut last_frame_event: Option<std::time::Instant> = None;
                while let Ok(message) = live_rx.recv() {
                    let step = match message {
                        Live::Packet(pcm, frames) => (|| -> Result<(), FttsError> {
                            if !live_output_began {
                                emit_stage(run, emit, "output", "begin", &mut seq)?;
                                live_output_began = true;
                            }
                            let event = audio.write_packet(
                                &pcm,
                                output.raw_audio,
                                run.run_id(),
                                u8::try_from(frames).unwrap_or(u8::MAX),
                            )?;
                            emit(&event)?;
                            if raw_stream {
                                // Latency depends on flush discipline, not on the writer's
                                // incidental buffering: one packet, one flush.
                                output.raw_audio.flush().map_err(|error| {
                                    FttsError::Generic(format!("cannot flush raw PCM: {error}"))
                                })?;
                            }
                            Ok(())
                        })(),
                        Live::Progress(frame, total) => (|| -> Result<(), FttsError> {
                            // The frozen catalogue pins `frame` as "throttled, never one
                            // per frame": at most one per second. A frame event MAY
                            // precede stage{output,begin} — frames 1..packet exist before
                            // the first packet decodes, and early progress is the point.
                            let due = last_frame_event
                                .is_none_or(|at| at.elapsed() >= std::time::Duration::from_secs(1));
                            if due {
                                last_frame_event = Some(std::time::Instant::now());
                                let mut event = run.event(robot::EventType::Frame);
                                event.insert("index".to_owned(), json!(frame));
                                event.insert(
                                    "total_estimate".to_owned(),
                                    total.map_or(Value::Null, |estimate| json!(estimate)),
                                );
                                event.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
                                emit(&Value::Object(event))?;
                            }
                            Ok(())
                        })(),
                    };
                    if let Err(error) = step {
                        // Remember the true cause, then hang up: the producer's next sink
                        // send fails, aborting synthesis promptly.
                        consumer_error = Some(error);
                        break;
                    }
                }
                drop(live_rx);
                let produced = match handle.join() {
                    Ok(result) => result,
                    Err(_) => Err(FttsError::Generic(
                        "the synthesis thread panicked".to_owned(),
                    )),
                };
                match consumer_error {
                    // The consumer's failure is the root cause; the producer's error is
                    // the induced channel abort and would bury it.
                    Some(error) => Err(error),
                    None => produced,
                }
            });
            let produced = match produced {
                Ok(produced) => produced,
                Err(error) => {
                    // A signal during synthesis outranks whatever refusal the abort
                    // produced: the run reports cancelled (exit 6) with its partial-
                    // artifact disposition, never an incidental channel error.
                    if cancel.was_tripped() {
                        return Err(cancelled_run_disposition(audio, output_plan.as_ref()));
                    }
                    return Err(error);
                }
            };
            (produced, true)
        }
    };
    let (audio_result, live_streamed) = audio_result;
    emit_stage(run, emit, "synthesis", "end", &mut seq)?;

    // --- the output tail ---------------------------------------------------------------------
    // The live path already wrote every packet and opened the `output` stage at the first
    // one; only the buffered (resident) path packetizes here, post hoc.
    if live_streamed {
        if !live_output_began {
            // Zero-packet live runs are refused before this point today, but stage events
            // come in pairs regardless of how the run evolves.
            emit_stage(run, emit, "output", "begin", &mut seq)?;
        }
    } else {
        let packet_samples = settings.packet_frames.samples_per_packet();
        let packet_frame_count = settings.packet_frames.frames_per_packet();
        emit_stage(run, emit, "output", "begin", &mut seq)?;
        for packet in audio_result.pcm.chunks(packet_samples) {
            let event =
                audio.write_packet(packet, output.raw_audio, run.run_id(), packet_frame_count)?;
            emit(&event)?;
        }
    }
    let streamed_bytes = audio.byte_offset();
    let samples = audio.finish()?;
    // `audio_bytes` must agree with `samples`, and `samples` now reports what the file really
    // holds after tail trimming. Deriving the byte count from it keeps `run_complete` internally
    // consistent instead of pairing a trimmed sample count with an untrimmed byte count. The raw
    // stream is never trimmed, so its running total is already the truth and is used as-is.
    let audio_bytes = if raw_stream {
        streamed_bytes
    } else {
        samples * u64::from(ftts_core::audio::BITS_PER_SAMPLE / 8)
    };
    if let Some(plan) = &output_plan {
        plan.finalize()?;
    }
    emit_stage(run, emit, "output", "end", &mut seq)?;

    let mut complete = run.event(robot::EventType::RunComplete);
    complete.insert("exit_code".to_owned(), json!(FttsExitCode::Success.as_u8()));
    complete.insert("elapsed_ms".to_owned(), json!(run.elapsed_ms()));
    complete.insert("frames".to_owned(), json!(audio_result.frames));
    complete.insert("audio_bytes".to_owned(), json!(audio_bytes));
    complete.insert("samples".to_owned(), json!(samples));
    complete.insert(
        "duration_ms".to_owned(),
        json!(samples * 1000 / u64::from(ftts_core::audio::SAMPLE_RATE_HZ)),
    );
    complete.insert(
        "prepared_token_count".to_owned(),
        json!(audio_result.prepared_token_count),
    );
    // The product TTFA is time-to-first-AUDIBLE-sample (leading silence must not flatter
    // the number); output that never crosses the audibility floor falls back to the raw
    // first-delivery mark rather than claiming nothing was delivered. One field, one
    // definition — the raw-vs-audible delta is test-receipt material, not event schema.
    if let Some(ttfa) = audio_result.ttfa_audible.or(audio_result.ttfa) {
        complete.insert(
            "ttfa_ms".to_owned(),
            json!(u64::try_from(ttfa.as_millis()).unwrap_or(u64::MAX)),
        );
    }
    emit(&Value::Object(complete))?;
    Ok(())
}

/// Where synthesised PCM goes, and the `audio_chunk` events that describe it.
///
/// The two destinations are mutually exclusive by contract (AGENTS.md agent ergonomics): either
/// events own stdout and audio goes to `-o PATH`, or `--stream raw` gives stdout to PCM and every
/// event goes to stderr. Raw bytes and NDJSON are never interleaved on one stream, so this type
/// owns the decision once instead of leaving it to each call site.
///
/// `audio_chunk` reports the bytes written, never the bytes themselves.
pub enum AudioSink {
    /// A WAV file. The header is finalised on [`AudioSink::finish`], so a run cut short still
    /// leaves a playable file describing the samples that landed.
    Wav(Box<ftts_core::audio::WavWriter<fs::File>>),
    /// Raw little-endian 16-bit PCM on a caller-supplied stream (`--stream raw`).
    RawPcm,
    /// `--check` and other non-synthesising paths.
    None,
}

/// Accumulating state for the `audio_chunk` event stream.
pub struct AudioOutput {
    sink: AudioSink,
    byte_offset: u64,
    samples_written: u64,
}

/// Audio container selected by the output path's extension.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum OutputFormat {
    /// Written natively by the pure-Rust WAV writer.
    Wav,
    /// AAC in an MPEG-4 container, encoded by `afconvert` (macOS) or `ffmpeg`.
    M4a,
    /// MP3, encoded by `lame` or `ffmpeg`.
    Mp3,
    /// FLAC, encoded by `flac` or `ffmpeg`.
    Flac,
}

/// Where the WAV bytes land and what happens to them after synthesis.
///
/// Synthesis always writes the pure-Rust WAV stream ("self-contained" covers everything up to
/// and including that file). For a compressed extension the WAV goes to a sibling staging file
/// and is then handed to the first available *system* encoder — an optional post-step, never a
/// runtime dependency of synthesis itself. No encoder found is a refusal with the tool list,
/// not a silent format switch.
#[derive(Clone, Debug)]
struct OutputPlan {
    /// The path the user asked for.
    final_path: PathBuf,
    /// Where the WAV sink writes; equals `final_path` for `.wav`.
    wav_path: PathBuf,
    format: OutputFormat,
}

impl OutputPlan {
    fn for_path(path: &Path) -> Result<Self, FttsError> {
        let extension = path
            .extension()
            .and_then(|extension| extension.to_str())
            .map(str::to_ascii_lowercase);
        let format = match extension.as_deref() {
            Some("wav") | None => OutputFormat::Wav,
            Some("m4a" | "aac") => OutputFormat::M4a,
            Some("mp3") => OutputFormat::Mp3,
            Some("flac") => OutputFormat::Flac,
            Some(other) => {
                return Err(FttsError::Usage(format!(
                    "unsupported output extension `.{other}`; use .wav (native), .m4a, .mp3, or \
                     .flac (system encoder)"
                )));
            }
        };
        let wav_path = if format == OutputFormat::Wav {
            path.to_path_buf()
        } else {
            let mut staging = path.as_os_str().to_owned();
            staging.push(".ftts-staging.wav");
            PathBuf::from(staging)
        };
        Ok(Self {
            final_path: path.to_path_buf(),
            wav_path,
            format,
        })
    }

    /// Encodes the staged WAV into the requested container and removes the staging file.
    fn finalize(&self) -> Result<(), FttsError> {
        if self.format == OutputFormat::Wav {
            return Ok(());
        }
        let wav = self.wav_path.as_os_str();
        let target = self.final_path.as_os_str();
        // (encoder, arguments) attempts in preference order; the first tool present decides.
        let attempts: &[(&str, Vec<&std::ffi::OsStr>)] = &match self.format {
            OutputFormat::M4a => [
                (
                    "afconvert",
                    vec![
                        "-f".as_ref(),
                        "m4af".as_ref(),
                        "-d".as_ref(),
                        "aac".as_ref(),
                        wav,
                        target,
                    ],
                ),
                (
                    "ffmpeg",
                    vec![
                        "-y".as_ref(),
                        "-loglevel".as_ref(),
                        "error".as_ref(),
                        "-i".as_ref(),
                        wav,
                        "-c:a".as_ref(),
                        "aac".as_ref(),
                        target,
                    ],
                ),
            ],
            OutputFormat::Mp3 => [
                (
                    "lame",
                    vec!["--quiet".as_ref(), "-V2".as_ref(), wav, target],
                ),
                (
                    "ffmpeg",
                    vec![
                        "-y".as_ref(),
                        "-loglevel".as_ref(),
                        "error".as_ref(),
                        "-i".as_ref(),
                        wav,
                        "-codec:a".as_ref(),
                        "libmp3lame".as_ref(),
                        "-q:a".as_ref(),
                        "2".as_ref(),
                        target,
                    ],
                ),
            ],
            OutputFormat::Flac => [
                (
                    "flac",
                    vec![
                        "--totally-silent".as_ref(),
                        "-f".as_ref(),
                        "-o".as_ref(),
                        target,
                        wav,
                    ],
                ),
                (
                    "ffmpeg",
                    vec![
                        "-y".as_ref(),
                        "-loglevel".as_ref(),
                        "error".as_ref(),
                        "-i".as_ref(),
                        wav,
                        "-c:a".as_ref(),
                        "flac".as_ref(),
                        target,
                    ],
                ),
            ],
            OutputFormat::Wav => unreachable!("handled above"),
        };

        let mut tried = Vec::new();
        for (tool, arguments) in attempts {
            // `tool` is always one of the fixed string literals in `attempts` above — a
            // compile-time allowlist. User-controlled data (the two paths) enters only as argv.
            match std::process::Command::new(tool).args(arguments).status() {
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                    tried.push(*tool);
                }
                Err(error) => {
                    return Err(FttsError::Generic(format!(
                        "audio encoder `{tool}` could not run: {error}; the synthesized WAV is \
                         preserved at {}",
                        self.wav_path.display()
                    )));
                }
                Ok(status) if status.success() => {
                    // The staging WAV is an intermediate this run created; the requested artifact
                    // now exists, so the intermediate is removed.
                    let _ = fs::remove_file(&self.wav_path);
                    return Ok(());
                }
                Ok(status) => {
                    return Err(FttsError::Generic(format!(
                        "audio encoder `{tool}` exited with {status}; the synthesized WAV is \
                         preserved at {}",
                        self.wav_path.display()
                    )));
                }
            }
        }
        Err(FttsError::Generic(format!(
            "no system audio encoder found for {} (tried: {}); install one or use a .wav output. \
             The synthesized WAV is preserved at {}",
            self.final_path.display(),
            tried.join(", "),
            self.wav_path.display()
        )))
    }
}

impl AudioOutput {
    /// Open a WAV file sink.
    ///
    /// # Errors
    ///
    /// If the file cannot be created or the provisional header cannot be written.
    pub fn wav(path: &Path) -> Result<Self, FttsError> {
        let file = fs::File::create(path).map_err(|error| {
            FttsError::Generic(format!(
                "cannot create audio output {}: {error}",
                path.display()
            ))
        })?;
        // File output trims the model's end-of-utterance noise burst (DISC-005). The raw PCM
        // stream deliberately does not: trimming needs the last quarter second held back, and
        // `--stream raw` exists for latency. `FTTS_TRIM_TAIL=0` restores the untrimmed bytes.
        let trim_tail = !matches!(
            std::env::var("FTTS_TRIM_TAIL").ok().as_deref(),
            Some("0") | Some("false")
        );
        let writer = if trim_tail {
            ftts_core::audio::WavWriter::new_trimming_tail(file, ftts_core::audio::SAMPLE_RATE_HZ)
        } else {
            ftts_core::audio::WavWriter::new(file, ftts_core::audio::SAMPLE_RATE_HZ)
        }
        .map_err(|error| {
            FttsError::Generic(format!(
                "cannot write WAV header to {}: {error}",
                path.display()
            ))
        })?;
        Ok(Self {
            sink: AudioSink::Wav(Box::new(writer)),
            byte_offset: 0,
            samples_written: 0,
        })
    }

    /// A raw-PCM sink; the caller supplies the stream on each write.
    #[must_use]
    pub const fn raw() -> Self {
        Self {
            sink: AudioSink::RawPcm,
            byte_offset: 0,
            samples_written: 0,
        }
    }

    /// A sink that discards audio, for paths that synthesise nothing.
    #[must_use]
    pub const fn none() -> Self {
        Self {
            sink: AudioSink::None,
            byte_offset: 0,
            samples_written: 0,
        }
    }

    /// The stable `sink` string reported in `audio_chunk`.
    #[must_use]
    pub const fn sink_name(&self) -> &'static str {
        match self.sink {
            AudioSink::Wav(_) => "file",
            AudioSink::RawPcm => "stdout",
            AudioSink::None => "none",
        }
    }

    /// Bytes of audio emitted so far.
    #[must_use]
    pub const fn byte_offset(&self) -> u64 {
        self.byte_offset
    }

    /// Write one packet and return its `audio_chunk` event.
    ///
    /// `raw` is where PCM goes under `--stream raw`; it is ignored by the other sinks. The event's
    /// `byte_offset` is the offset *before* this packet, so a consumer can seek with it — on the
    /// RAW stream. On a trimmed file sink the chunk events describe samples HANDED to the writer,
    /// up to a quarter second of which the tail trim may withhold, so the final chunk's advertised
    /// range can exceed the file; `run_complete.audio_bytes` is the authoritative file size.
    ///
    /// `duration_ms` is derived from the sample count rather than taken from a caller-supplied
    /// clock: it describes how much *audio* this packet holds, which is a property of the samples,
    /// not of how long the run took to produce them.
    ///
    /// # Errors
    ///
    /// If the sink rejects the write.
    pub fn write_packet(
        &mut self,
        pcm: &[f32],
        raw: &mut dyn Write,
        run_id: &str,
        frame_count: u8,
    ) -> Result<Value, FttsError> {
        let offset_before = self.byte_offset;
        let bytes = (pcm.len() * 2) as u64;

        match &mut self.sink {
            AudioSink::Wav(writer) => writer.write_samples(pcm).map_err(|error| {
                FttsError::Generic(format!("cannot write audio samples: {error}"))
            })?,
            AudioSink::RawPcm => {
                let mut buffer = Vec::with_capacity(pcm.len() * 2);
                for sample in pcm {
                    buffer
                        .extend_from_slice(&ftts_core::audio::sample_to_i16(*sample).to_le_bytes());
                }
                raw.write_all(&buffer).map_err(|error| {
                    FttsError::Generic(format!("cannot write raw PCM: {error}"))
                })?;
            }
            AudioSink::None => {}
        }

        self.byte_offset += bytes;
        self.samples_written += pcm.len() as u64;

        let mut event = robot::EventType::AudioChunk.event();
        event.insert("run_id".to_owned(), json!(run_id));
        event.insert("byte_offset".to_owned(), json!(offset_before));
        event.insert("bytes".to_owned(), json!(bytes));
        event.insert(
            "duration_ms".to_owned(),
            json!((pcm.len() as u64) * 1000 / u64::from(ftts_core::audio::SAMPLE_RATE_HZ.max(1))),
        );
        event.insert("packet_frames".to_owned(), json!(frame_count.to_string()));
        event.insert("sink".to_owned(), json!(self.sink_name()));
        Ok(Value::Object(event))
    }

    /// Finalise the sink, patching the WAV header to the real length.
    ///
    /// # Errors
    ///
    /// If the header cannot be rewritten.
    pub fn finish(self) -> Result<u64, FttsError> {
        let mut samples = self.samples_written;
        if let AudioSink::Wav(writer) = self.sink {
            // Report what the FILE contains, not what was handed to the sink. Tail trimming makes
            // those differ, and `run_complete.samples` claiming audio the file does not hold is a
            // false number in a machine-readable stream: a consumer that trusts it computes the
            // wrong duration. `finish_reporting` exists precisely to close that gap.
            let (_, written) = writer.finish_reporting().map_err(|error| {
                FttsError::Generic(format!("cannot finalize the WAV header: {error}"))
            })?;
            samples = written as u64;
        }
        Ok(samples)
    }
}

fn read_text(args: &SayArgs, stdin: &mut dyn Read) -> Result<String, FttsError> {
    let text = match (&args.text, &args.file) {
        (Some(text), None) if text == "-" => read_utf8(stdin, "stdin")?,
        (Some(text), None) => text.clone(),
        (None, Some(path)) if path == Path::new("-") => read_utf8(stdin, "stdin")?,
        (None, Some(path)) => fs::read_to_string(path).map_err(|error| {
            FttsError::Input(format!(
                "cannot read text file {}: {error}; use `ftts say --file PATH --check --model PATH`",
                path.display()
            ))
        })?,
        (None, None) => {
            return Err(FttsError::Usage(
                "missing text; use `ftts say TEXT`, `ftts say --file PATH`, or `ftts say -`".to_owned(),
            ));
        }
        (Some(_), Some(_)) => unreachable!("clap enforces the conflict"),
    };

    if text.trim().is_empty() {
        return Err(FttsError::Input(
            "text is empty; provide non-whitespace UTF-8 text to `ftts say`".to_owned(),
        ));
    }
    Ok(text)
}

fn read_utf8(reader: &mut dyn Read, source: &str) -> Result<String, FttsError> {
    let mut bytes = Vec::new();
    reader.read_to_end(&mut bytes).map_err(|error| {
        FttsError::Input(format!(
            "cannot read {source}: {error}; retry with readable UTF-8 input"
        ))
    })?;
    String::from_utf8(bytes).map_err(|error| {
        FttsError::Input(format!(
            "{source} is not valid UTF-8: {error}; transcode it before `ftts say`"
        ))
    })
}

fn resolve_model(explicit: Option<&Path>, environment: &Environment) -> Result<String, FttsError> {
    resolve_model_from(
        explicit,
        &model_search_paths(environment),
        default_pull_model_dir(environment).as_deref(),
    )
}

/// The full resolution order — `--model`, then the searched artifact paths (`FTTS_MODEL_DIR`,
/// then the home cache), then the `ftts pull` destination directory, accepted only when it holds
/// a complete bundle. Takes its inputs as data so tests can exercise the order against temp
/// directories without mutating process environment.
fn resolve_model_from(
    explicit: Option<&Path>,
    searched: &[PathBuf],
    pull_dir: Option<&Path>,
) -> Result<String, FttsError> {
    if let Some(path) = explicit {
        // A pinned checkpoint is a *directory* of five files, so `--model DIR` is the natural
        // thing to type and is accepted as such. `.fttsq` is a single file, and both forms reach
        // the same resolver rather than one being a special case documented somewhere else.
        if path.is_dir() {
            return Ok(path.display().to_string());
        }
        return resolve_existing_file(path, "model artifact")
            .map(|path| path.display().to_string());
    }

    if let Some(path) = searched.iter().find(|path| path.is_file()) {
        return Ok(path.display().to_string());
    }
    // A directory named by FTTS_MODEL_DIR may itself BE the model: a pinned checkpoint snapshot
    // (`model.safetensors` + configs) or a directory holding the canonical artifact. `--model DIR`
    // already accepts that shape; the search path accepting it too is what lets a bare
    // `ftts say "text" out.wav` work after one exported variable.
    if let Some(directory) = searched
        .iter()
        .filter_map(|path| path.parent())
        .find(|directory| directory.join("model.safetensors").is_file())
    {
        return Ok(directory.display().to_string());
    }

    // The `ftts pull` destination is a *bundle* directory (checkpoints + tokenizer files), not a
    // single artifact, so it counts only when the whole bundle is present — a half-finished pull
    // resolving here would fail later with a less actionable error than the one below.
    if let Some(directory) = pull_dir
        && directory.is_dir()
        && synth::ModelBundle::resolve(directory).is_ok()
    {
        return Ok(directory.display().to_string());
    }

    let searched = searched
        .iter()
        .map(|path| path.display().to_string())
        .collect::<Vec<_>>()
        .join(", ");
    Err(FttsError::ModelNotFound(format!(
        "no model artifact was found; searched: [{searched}]; run `ftts pull` to fetch the model \
         (~2.0 GB), or pass --model PATH or set FTTS_MODEL_DIR"
    )))
}

fn resolve_optional_file(path: Option<&Path>, label: &str) -> Result<Option<String>, FttsError> {
    path.map(|path| resolve_existing_file(path, label).map(|path| path.display().to_string()))
        .transpose()
}

fn resolve_requested_voice(
    explicit: Option<&Path>,
    environment: &Environment,
) -> Result<Option<String>, FttsError> {
    if let Some(path) = explicit {
        // A bare preset name selects a built-in voice — but only when no such file exists, so
        // `--voice aria` in a directory containing a file named `aria` still means the file.
        if !path.exists()
            && let Some(name) = path.to_str()
            && let Some(materialized) = materialize_preset_voice(name)
        {
            return materialized.map(|path| Some(path.display().to_string()));
        }
        // A failed bare word was probably a preset-name attempt: name the built-ins in the
        // refusal so the user does not have to hunt the docs for the list.
        let looks_like_name =
            path.extension().is_none() && path.components().count() == 1 && !path.exists();
        return resolve_optional_file(Some(path), "voice source").map_err(|error| {
            if looks_like_name {
                FttsError::Input(format!(
                    "{error}; built-in voice names are: {}",
                    preset_names()
                ))
            } else {
                error
            }
        });
    }
    environment
        .value("FTTS_DEFAULT_VOICE")
        .map(Path::new)
        .map(|path| resolve_existing_file(path, "FTTS_DEFAULT_VOICE"))
        .transpose()
        .map(|path| path.map(|path| path.display().to_string()))
}

fn run_enroll(
    args: &EnrollArgs,
    environment: &Environment,
    stdin: &mut dyn Read,
    stdout: &mut dyn Write,
    capabilities: IoCapabilities,
) -> Result<(), FttsError> {
    let started = std::time::Instant::now();
    let model = resolve_model(args.model.as_deref(), environment)?;
    let bundle = synth::ModelBundle::resolve(Path::new(&model))?;
    let output = match (&args.output, args.default) {
        (Some(path), false) => path.clone(),
        (None, true) => bundle.root.join("default.ftvoice"),
        (None, false) => {
            return Err(FttsError::Usage(
                "`ftts enroll` needs -o PATH or --default; enrollment never overwrites a voice source"
                    .to_owned(),
            ));
        }
        (Some(_), true) => unreachable!("clap enforces the conflict"),
    };

    // Transcript source: inline text or a UTF-8 file. Read BEFORE any heavy work so a typo in
    // the path fails fast rather than after a full decode + embed.
    let transcript: Option<String> = match (&args.transcript_text, &args.transcript_file) {
        (Some(text), _) => Some(text.clone()),
        (None, Some(path)) => Some(std::fs::read_to_string(path).map_err(|error| {
            FttsError::Input(format!(
                "cannot read transcript {}: {error}",
                path.display()
            ))
        })?),
        (None, None) => None,
    };
    let resolved = resolve_enroll_mode(args.mode, transcript.as_deref());

    let mut denoise_report = None;
    let mut dereverb_report = None;
    let denoise = if args.no_denoise {
        false
    } else {
        args.denoise || bundle.root.join(synth::DENOISE_ARTIFACT_RELPATH).is_file()
    };

    // Decode once. Diagnostics state what was measured BEFORE the user hears any defect in
    // their clone; the usability gate refuses structurally unusable input (no speech at all)
    // with exit 8 unless --force says otherwise.
    let raw_pcm = synth::decode_reference_audio_any(Path::new(&args.reference_audio))?;
    let dx = diagnostics::diagnose(&raw_pcm, synth::reverb_time_s(&raw_pcm).map(f64::from));
    for warning in dx.warnings() {
        style::warn(stdout, &warning)
            .map_err(|error| FttsError::Generic(format!("cannot write warning: {error}")))?;
    }
    if let Some(reason) = unusable_reference_reason(&dx, raw_pcm.len()) {
        if args.force {
            style::warn(
                stdout,
                &format!("forcing enrollment of unusable reference: {reason}"),
            )
            .map_err(|error| FttsError::Generic(format!("cannot write warning: {error}")))?;
        } else {
            return Err(FttsError::EnrollmentQualityRefusal(format!(
                "{reason}; pass --force to enroll it anyway"
            )));
        }
    }

    let source_bytes = std::fs::read(&args.reference_audio).map_err(|error| {
        FttsError::Input(format!(
            "cannot read reference {}: {error}",
            args.reference_audio.display()
        ))
    })?;
    let (speaker, cleaned_pcm) = synth::enroll_outputs_from_reference_pcm(
        &bundle,
        raw_pcm,
        synth::ReferenceCleanup {
            denoise: denoise.then_some(&mut denoise_report),
            dereverb: args.dereverb.then_some(&mut dereverb_report),
        },
    )?;
    if let Some(report) = dereverb_report {
        style::ok(
            stdout,
            &format!(
                "dereverberated reference {}",
                style::detail(&format!(
                    "RT60-equivalent {:.2} → {:.2} s",
                    report.before_rt60_s, report.after_rt60_s
                )),
            ),
        )
        .map_err(|error| FttsError::Generic(format!("cannot write dereverb report: {error}")))?;
    }
    if let Some(report) = denoise_report {
        let moved = report.before_dbfs - report.after_dbfs;
        style::ok(
            stdout,
            &format!(
                "denoised reference {}",
                style::detail(&format!(
                    "pause floor {:.1} → {:.1} dBFS ({moved:.1} dB quieter)",
                    report.before_dbfs, report.after_dbfs
                )),
            ),
        )
        .map_err(|error| FttsError::Generic(format!("cannot write denoise report: {error}")))?;
    }

    // The fallback notice is LOUD on purpose: continuation-style cloners reproduce
    // prompt-recording defects, and a quiet downgrade is how users end up with a worse
    // clone than they thought they enrolled.
    if let ResolvedEnrollMode::Quick { reason } = &resolved {
        style::warn(
            stdout,
            &format!("QUICK mode — x-vector only, no ICL conditioning ({reason})"),
        )
        .map_err(|error| FttsError::Generic(format!("cannot write warning: {error}")))?;
    }

    // Consent: affirmed via flag or interactively; either way the ANSWER is what the pack
    // records. A silent default would make every pack lie by omission.
    let consent_method = if args.consent_attest {
        ftts_artifacts::voice::ConsentMethod::Flag
    } else {
        ftts_artifacts::voice::ConsentMethod::Interactive
    };
    let consent_attested = args.consent_attest
        || style::confirm(
            stdin,
            stdout,
            "Do you have the right to clone this voice? (recorded in the pack)",
            capabilities.can_confirm,
        )
        .map_err(|error| FttsError::Generic(format!("cannot read a reply: {error}")))?
        .unwrap_or_default();
    if !consent_attested {
        style::warn(stdout, "pack will record consent: NOT ATTESTED")
            .map_err(|error| FttsError::Generic(format!("cannot write warning: {error}")))?;
    }

    // QUALITY adds the ICL identity block: codec tokens cut from the SAME cleaned audio the
    // embedding came from, so one pack conditions one voice, not two.
    let (profile, codec_codes, pack_transcript) = match resolved {
        ResolvedEnrollMode::Quality => {
            let encoder = ftts_model_qwen::speech_encoder::SpeechEncoder::load(
                &bundle.root.join("speech_tokenizer/model.safetensors"),
            )
            .map_err(|error| {
                FttsError::Input(format!(
                    "quality-mode enrollment needs the codec encoder \
                     (speech_tokenizer/model.safetensors): {error}"
                ))
            })?;
            let codes = encoder.encode_24khz_pcm(&cleaned_pcm).map_err(|error| {
                FttsError::Input(format!("cannot encode reference to codec tokens: {error}"))
            })?;
            (
                ftts_artifacts::voice::VoiceProfile::Portable,
                Some(codes),
                transcript,
            )
        }
        ResolvedEnrollMode::Quick { .. } => {
            (ftts_artifacts::voice::VoiceProfile::Private, None, None)
        }
    };

    let speech_regions = crate::diagnostics::voice_activity_regions(&cleaned_pcm)
        .into_iter()
        .map(|(start, end)| (start as u64, end as u64))
        .collect();
    let pack = assemble_enrollment_pack(AssemblePackInput {
        profile,
        consent: ftts_artifacts::voice::ConsentAttestation {
            attested: consent_attested,
            method: consent_method,
        },
        transcript: pack_transcript,
        speech_regions,
        diagnostics: mirror_diagnostics(&dx),
        preprocessing: ftts_artifacts::voice::PreprocessingRecipe {
            target_sample_rate_hz: 24_000,
            resampler: "lanczos6".to_owned(),
            denoise: denoise_report.map(|report| ftts_artifacts::voice::CleanupRecord {
                engine: if bundle.root.join(synth::DENOISE_ARTIFACT_RELPATH).is_file()
                    && !args.no_denoise
                {
                    "fastenhancer-s".to_owned()
                } else {
                    "omlsa".to_owned()
                },
                before: f64::from(report.before_dbfs),
                after: f64::from(report.after_dbfs),
            }),
            dereverb: dereverb_report.map(|report| ftts_artifacts::voice::CleanupRecord {
                engine: "spectral-dereverb".to_owned(),
                before: f64::from(report.before_rt60_s),
                after: f64::from(report.after_rt60_s),
            }),
        },
        provenance: ftts_artifacts::voice::Provenance {
            engine: format!("ftts {}", env!("CARGO_PKG_VERSION")),
            source_audio_sha256: Some(ftts_artifacts::sha256::hex_digest(
                &ftts_artifacts::sha256::digest(&source_bytes),
            )),
            source_frames: None,
        },
        embedding: speaker,
        codec_codes,
    });
    let bytes = ftts_artifacts::voice::serialize_voice_pack(&pack)
        .map_err(|error| FttsError::ArtifactFormat(error.to_string()))?;

    // Occupied destination asks rather than refuses — but only when somebody is there to ask
    // (same contract as the raw-vector writer always had).
    let backup = if output.exists() {
        let consented = if args.overwrite {
            true
        } else {
            style::warn(
                stdout,
                &format!(
                    "{} already holds an enrolled voice",
                    style::emphasis(&output.display().to_string())
                ),
            )
            .map_err(|error| {
                FttsError::Generic(format!("cannot write overwrite notice: {error}"))
            })?;
            match style::confirm(stdin, stdout, "Replace it?", capabilities.can_confirm)
                .map_err(|error| FttsError::Generic(format!("cannot read a reply: {error}")))?
            {
                Some(reply) => reply,
                None => {
                    return Err(FttsError::Input(format!(
                        "{} already exists; pass --overwrite to replace it (the displaced voice is \
                         kept as {}.bak)",
                        output.display(),
                        output.display()
                    )));
                }
            }
        };
        if !consented {
            style::info(stdout, "left the existing voice in place")
                .map_err(|error| FttsError::Generic(format!("cannot write result: {error}")))?;
            return Ok(());
        }
        Some(replace_voice_pack(&output, &bytes)?)
    } else {
        write_voice_pack_new(&output, &bytes)?;
        None
    };

    let elapsed_ms = started.elapsed().as_millis();
    let detail = match &pack.codec_codes {
        Some(codes) => format!(
            "{} · {} · quality · {} codec frames · consent {} · {elapsed_ms} ms",
            pack.profile.as_str(),
            style::detail("ICL"),
            codes.len(),
            if pack.consent.attested {
                "attested"
            } else {
                "NOT ATTESTED"
            },
        ),
        None => format!(
            "{} · quick · x-vector only · consent {} · {elapsed_ms} ms",
            pack.profile.as_str(),
            if pack.consent.attested {
                "attested"
            } else {
                "NOT ATTESTED"
            },
        ),
    };
    style::ok(
        stdout,
        &format!(
            "enrolled {} → {} {}",
            style::emphasis(&args.reference_audio.display().to_string()),
            style::emphasis(&output.display().to_string()),
            style::detail(&detail),
        ),
    )
    .map_err(|error| FttsError::Generic(format!("cannot write enrollment result: {error}")))?;
    if let Some(backup) = backup {
        style::info(
            stdout,
            &format!(
                "previous voice kept at {}",
                style::emphasis(&backup.display().to_string())
            ),
        )
        .map_err(|error| FttsError::Generic(format!("cannot write backup notice: {error}")))?;
    }
    if args.default {
        style::info(
            stdout,
            &format!(
                "{} will use it when --voice is absent",
                style::emphasis("ftts say")
            ),
        )
        .map_err(|error| FttsError::Generic(format!("cannot write result: {error}")))?;
    }
    Ok(())
}

/// Structurally unusable references get exit 8, not a warning: there is no voice in this
/// recording to enroll, and everything downstream of a silent pack is noise. Threshold-based
/// quality refusals stay reserved until owner-validated listening thresholds exist.
fn unusable_reference_reason(
    dx: &crate::diagnostics::AudioDiagnostics,
    pcm_len: usize,
) -> Option<String> {
    if pcm_len == 0 {
        return Some("reference decoded to zero samples".to_owned());
    }
    if dx.voice_activity_ratio <= 0.0 {
        return Some("no speech detected anywhere in the reference".to_owned());
    }
    None
}

fn mirror_diagnostics(
    dx: &crate::diagnostics::AudioDiagnostics,
) -> ftts_artifacts::voice::EnrollmentDiagnostics {
    ftts_artifacts::voice::EnrollmentDiagnostics {
        clipping_fraction: dx.clipping_fraction,
        longest_clip_run: dx.longest_clip_run,
        intersample_overshoot_db: dx.intersample_overshoot_db,
        snr_estimate_db: dx.snr_estimate_db,
        pause_floor_dbfs: dx.pause_floor_dbfs,
        reverb_time_s: dx.reverb_time_s,
        music_bed_likelihood: dx.music_bed_likelihood,
        stationarity_drift: dx.stationarity_drift,
        loudness_rms_dbfs: dx.loudness_rms_dbfs,
        voice_activity_ratio: dx.voice_activity_ratio,
    }
}

/// Everything `run_enroll` hands to pack construction; a named struct keeps the constructor
/// callable from tests without audio fixtures or a model bundle.
struct AssemblePackInput {
    profile: ftts_artifacts::voice::VoiceProfile,
    consent: ftts_artifacts::voice::ConsentAttestation,
    transcript: Option<String>,
    speech_regions: Vec<(u64, u64)>,
    diagnostics: ftts_artifacts::voice::EnrollmentDiagnostics,
    preprocessing: ftts_artifacts::voice::PreprocessingRecipe,
    provenance: ftts_artifacts::voice::Provenance,
    embedding: Vec<f32>,
    codec_codes: Option<Vec<u32>>,
}

fn assemble_enrollment_pack(input: AssemblePackInput) -> ftts_artifacts::voice::VoicePack {
    ftts_artifacts::voice::VoicePack {
        profile: input.profile,
        consent: input.consent,
        language: None,
        transcript: input.transcript,
        speech_regions: input.speech_regions,
        diagnostics: Some(input.diagnostics),
        preprocessing: Some(input.preprocessing),
        provenance: input.provenance,
        embedding: input.embedding,
        codec_codes: input.codec_codes,
        reference_audio: None,
        section_digests: Default::default(),
    }
}

/// Writes a `.ftvoice` pack without replacing an existing file (staged temp + rename, so a
/// crash cannot leave a half-written voice).
fn write_voice_pack_new(path: &Path, bytes: &[u8]) -> Result<(), FttsError> {
    let staged = path.with_extension("ftvoice.partial");
    std::fs::write(&staged, bytes).map_err(|error| {
        FttsError::Input(format!(
            "cannot stage enrolled voice {}: {error}",
            staged.display()
        ))
    })?;
    std::fs::rename(&staged, path).map_err(|error| {
        FttsError::Input(format!(
            "cannot finalize enrolled voice {}: {error}",
            path.display()
        ))
    })
}

/// Replaces an existing `.ftvoice`, keeping the displaced pack alongside it as `<path>.bak`.
fn replace_voice_pack(path: &Path, bytes: &[u8]) -> Result<PathBuf, FttsError> {
    let mut backup_name = path.as_os_str().to_owned();
    backup_name.push(".bak");
    let backup = PathBuf::from(backup_name);
    std::fs::copy(path, &backup).map_err(|error| {
        FttsError::Input(format!(
            "cannot back up displaced voice {}: {error}",
            path.display()
        ))
    })?;
    write_voice_pack_new(path, bytes)?;
    Ok(backup)
}

/// One downloadable model file from the embedded manifest.
#[derive(Clone, Debug)]
struct ModelManifestFile {
    /// The bare release-asset name on the GitHub release.
    asset: String,
    /// Relative path under the model directory the asset lands at.
    dest: String,
    /// Pinned lowercase-hex SHA-256 the downloaded bytes must carry.
    sha256: String,
    /// Pinned exact size, checked before the (much more expensive) digest.
    bytes: u64,
}

/// The embedded `ftts pull` download contract: release coordinates plus per-file pins.
#[derive(Clone, Debug)]
struct ModelManifest {
    model_id: String,
    release_tag: String,
    repo: String,
    files: Vec<ModelManifestFile>,
}

impl ModelManifest {
    /// The compiled-in manifest. Parsing it can only fail if the checked-in copy is malformed,
    /// which the unit tests catch before a binary ships.
    fn embedded() -> Result<Self, FttsError> {
        Self::parse(PINNED_MODEL_MANIFEST)
    }

    /// Parses and validates manifest text; every refusal names the offending field, because a
    /// manifest bug otherwise surfaces as a mystery mid-download.
    fn parse(text: &str) -> Result<Self, FttsError> {
        let value: Value = serde_json::from_str(text).map_err(|error| {
            FttsError::ArtifactFormat(format!("model manifest is not valid JSON: {error}"))
        })?;
        if value["schema_version"].as_u64() != Some(1) {
            return Err(FttsError::ArtifactFormat(format!(
                "model manifest schema_version {} is not the supported 1",
                value["schema_version"]
            )));
        }
        let model_id = manifest_string(&value, "model_id")?;
        let release_tag = manifest_string(&value, "release_tag")?;
        let repo = manifest_string(&value, "repo")?;
        let files = value["files"]
            .as_array()
            .filter(|files| !files.is_empty())
            .ok_or_else(|| {
                FttsError::ArtifactFormat("model manifest needs a non-empty files array".to_owned())
            })?
            .iter()
            .map(parse_manifest_file)
            .collect::<Result<Vec<_>, _>>()?;
        Ok(Self {
            model_id,
            release_tag,
            repo,
            files,
        })
    }

    /// The ordered mirror URLs for one file; the only endpoints `ftts pull` ever contacts.
    ///
    /// Hugging Face first: the GitHub release-asset limiter 503'd real users' pulls under
    /// chunked load (2026-08-12) while the same bytes served fine from the HF model repo, and
    /// every asset there carries the release-asset name byte for byte. GitHub stays as the
    /// fallback so either host failing degrades to a slower pull instead of a dead one; the
    /// digest verification after download is what actually decides acceptance, either way.
    fn download_urls(&self, file: &ModelManifestFile) -> [String; 2] {
        [
            format!(
                "https://huggingface.co/Dicklesworthstone/franken-tts-qwen3-tts-12hz-0.6b-base/resolve/main/{}",
                file.asset
            ),
            format!(
                "https://github.com/{}/releases/download/{}/{}",
                self.repo, self.release_tag, file.asset
            ),
        ]
    }

    fn total_bytes(&self) -> u64 {
        self.files
            .iter()
            .fold(0, |sum, file| sum.saturating_add(file.bytes))
    }
}

fn manifest_string(value: &Value, field: &str) -> Result<String, FttsError> {
    value[field]
        .as_str()
        .filter(|text| !text.is_empty())
        .map(str::to_owned)
        .ok_or_else(|| {
            FttsError::ArtifactFormat(format!(
                "model manifest field {field} must be a non-empty string"
            ))
        })
}

fn parse_manifest_file(value: &Value) -> Result<ModelManifestFile, FttsError> {
    let asset = manifest_string(value, "asset")?;
    if asset.contains('/') || asset.contains('\\') {
        return Err(FttsError::ArtifactFormat(format!(
            "manifest asset {asset:?} must be a bare release-asset name"
        )));
    }
    let dest = manifest_string(value, "dest")?;
    validate_manifest_dest(&dest)?;
    let sha256 = manifest_string(value, "sha256")?;
    if !is_sha256_hex(&sha256) {
        return Err(FttsError::ArtifactFormat(format!(
            "manifest sha256 for {asset} must be 64 lowercase hex characters"
        )));
    }
    let bytes = value["bytes"]
        .as_u64()
        .filter(|bytes| *bytes > 0)
        .ok_or_else(|| {
            FttsError::ArtifactFormat(format!(
                "manifest bytes for {asset} must be a positive integer"
            ))
        })?;
    Ok(ModelManifestFile {
        asset,
        dest,
        sha256,
        bytes,
    })
}

/// A manifest `dest` is joined under the model directory, so it must not be able to escape it:
/// no absolute paths, no `..`, no `.`, no backslash separators.
fn validate_manifest_dest(dest: &str) -> Result<(), FttsError> {
    let path = Path::new(dest);
    let traversal_free = path
        .components()
        .all(|component| matches!(component, std::path::Component::Normal(_)));
    if path.is_absolute() || dest.contains('\\') || !traversal_free {
        return Err(FttsError::ArtifactFormat(format!(
            "manifest dest {dest:?} must be a relative path with no traversal; it is joined under the model directory"
        )));
    }
    Ok(())
}

fn is_sha256_hex(text: &str) -> bool {
    text.len() == 64
        && text
            .bytes()
            .all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'))
}

/// The directory `ftts pull` fills when `--model` is absent, and the last resort model resolution
/// falls back to: the first `FTTS_MODEL_DIR` entry when set, else `$HOME/.cache/franken_tts/model`.
fn default_pull_model_dir(environment: &Environment) -> Option<PathBuf> {
    if let Some(first) = environment
        .value("FTTS_MODEL_DIR")
        .and_then(|dirs| std::env::split_paths(dirs).next())
        .filter(|path| !path.as_os_str().is_empty())
    {
        return Some(first);
    }
    std::env::var_os("HOME").map(|home| PathBuf::from(home).join(DEFAULT_MODEL_CACHE_SUBDIR))
}

/// Skip-versus-download for one manifest file, factored out so it is testable without a network.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum PullDecision {
    /// The destination already carries the pinned size AND the pinned digest.
    Skip,
    /// Absent, wrong-sized, wrong-hashed, or `--force`.
    Download,
}

/// `Skip` requires both pins to hold: size alone accepts a same-length corruption, and hashing
/// alone would digest gigabytes a length check could reject for free (which is why the cheap check
/// runs first). Any mismatch re-downloads rather than erroring — repairing a bad file is exactly
/// what `pull` is for.
fn pull_decision(dest: &Path, file: &ModelManifestFile, force: bool) -> PullDecision {
    if force {
        return PullDecision::Download;
    }
    let Ok(metadata) = fs::metadata(dest) else {
        return PullDecision::Download;
    };
    if !metadata.is_file() || metadata.len() != file.bytes {
        return PullDecision::Download;
    }
    match ftts_artifacts::sha256::hex_digest_file(dest) {
        Ok(digest) if digest == file.sha256 => PullDecision::Skip,
        _ => PullDecision::Download,
    }
}

/// Downloads `url` to `staging` with the system `curl`.
///
/// Shelling out is deliberate: inference never touches the network, so the binary links no HTTP
/// stack. Only `pull` needs one, and `curl` is the same system-tool seam the audio encoders and
/// decoders already use.
fn download_with_curl(url: &str, staging: &Path, pinned_bytes: u64) -> Result<(), FttsError> {
    // Hardening beyond the happy path: HTTPS only through every redirect (a release URL should
    // never bounce through http), a connect timeout and a stall detector instead of hanging a
    // silent `-sS` transfer forever, and the pinned size as a hard transfer cap so a
    // misbehaving endpoint cannot fill the disk before the post-download size check runs.
    let outcome = std::process::Command::new("curl")
        .args([
            "-L",
            "--fail",
            "--retry",
            "3",
            "-sS",
            "--proto",
            "=https",
            "--proto-redir",
            "=https",
            "--connect-timeout",
            "30",
            "--speed-limit",
            "1024",
            "--speed-time",
            "60",
            "--max-filesize",
        ])
        .arg(pinned_bytes.to_string())
        .arg("-o")
        .arg(staging)
        .arg(url)
        .status();
    match outcome {
        Err(error) if error.kind() == io::ErrorKind::NotFound => Err(FttsError::Generic(
            "`ftts pull` downloads with the system `curl`, which was not found on PATH; \
             install curl and retry, or download the release assets by hand"
                .to_owned(),
        )),
        Err(error) => Err(FttsError::Generic(format!("cannot run curl: {error}"))),
        Ok(status) if status.success() => Ok(()),
        Ok(status) => Err(FttsError::Generic(format!(
            "curl failed downloading {url} ({status}); check network access and retry `ftts pull`"
        ))),
    }
}

/// Size first, digest second, both against the embedded pins.
fn verify_pulled_file(path: &Path, file: &ModelManifestFile) -> Result<(), FttsError> {
    let metadata = fs::metadata(path).map_err(|error| {
        FttsError::Generic(format!(
            "cannot stat downloaded {}: {error}",
            path.display()
        ))
    })?;
    if metadata.len() != file.bytes {
        return Err(FttsError::ArtifactFormat(format!(
            "downloaded {} is {} bytes, expected {}; the incomplete download was discarded, retry `ftts pull`",
            file.asset,
            metadata.len(),
            file.bytes
        )));
    }
    let digest = ftts_artifacts::sha256::hex_digest_file(path).map_err(|error| {
        FttsError::Generic(format!(
            "cannot hash downloaded {}: {error}",
            path.display()
        ))
    })?;
    if digest != file.sha256 {
        return Err(FttsError::ArtifactFormat(format!(
            "downloaded {} carries sha256 {digest}, expected {}; the corrupt download was discarded, retry `ftts pull`",
            file.asset, file.sha256
        )));
    }
    Ok(())
}

/// `<dest>.part`, in the destination directory so the final rename never crosses a filesystem.
fn pull_staging_path(dest: &Path) -> PathBuf {
    let mut name = dest.file_name().map(OsString::from).unwrap_or_default();
    name.push(".part");
    dest.with_file_name(name)
}

/// Downloads one asset to `<dest>.part`, verifies it against the pins, and atomically publishes.
///
/// A staging file that fails verification is removed. This is the opposite of `convert`'s
/// retained staging, on purpose: a failed local conversion is diagnosable evidence, while a
/// corrupt download says nothing beyond "the network truncated it", and a multi-gigabyte corpse
/// in the cache directory helps no one.
fn pull_one_file(
    manifest: &ModelManifest,
    file: &ModelManifestFile,
    dest: &Path,
) -> Result<(), FttsError> {
    if let Some(parent) = dest.parent() {
        fs::create_dir_all(parent).map_err(|error| {
            FttsError::Generic(format!(
                "cannot create model directory {}: {error}",
                parent.display()
            ))
        })?;
    }
    let staging = pull_staging_path(dest);
    // The staging name is predictable, and `curl -o` opens it with a plain create-or-truncate
    // that follows symlinks. A pre-planted entry (stale crash debris, or a symlink in a shared
    // model directory) must be cleared first, checked via symlink_metadata so a link is seen as
    // itself rather than its target.
    match fs::symlink_metadata(&staging) {
        Ok(_) => fs::remove_file(&staging).map_err(|error| {
            FttsError::Generic(format!(
                "cannot clear stale staging file {}: {error}",
                staging.display()
            ))
        })?,
        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
        Err(error) => {
            return Err(FttsError::Generic(format!(
                "cannot stat staging path {}: {error}",
                staging.display()
            )));
        }
    }
    // Try each mirror in order; a failure (transport, HTTP, or digest) clears the staging
    // debris and moves on, and only the LAST mirror's error surfaces — by then it is the
    // honest answer to "why did the pull fail everywhere".
    let urls = manifest.download_urls(file);
    let mut last_error = None;
    let mut verified = false;
    for url in &urls {
        match download_with_curl(url, &staging, file.bytes)
            .and_then(|()| verify_pulled_file(&staging, file))
        {
            Ok(()) => {
                verified = true;
                break;
            }
            Err(error) => {
                let _ = fs::remove_file(&staging);
                last_error = Some(error);
            }
        }
    }
    if !verified {
        return Err(last_error.expect("at least one mirror was attempted"));
    }
    // Durability before publish: rename orders the directory entry, not the data. Without the
    // fsync a crash can leave a truncated file at the verified name — and the tokenizer/codec
    // sidecars, unlike the .fttsq, carry no load-time digest to catch that. Same contract as
    // FttsqWriter::write_to_path. The handle must be writable: Windows refuses to flush a
    // read-only handle (ERROR_ACCESS_DENIED), while Unix fsync accepts one.
    fs::OpenOptions::new()
        .write(true)
        .open(&staging)
        .and_then(|file| file.sync_all())
        .map_err(|error| {
            FttsError::Generic(format!(
                "cannot fsync downloaded {}: {error}",
                staging.display()
            ))
        })?;
    fs::rename(&staging, dest).map_err(|error| {
        FttsError::Generic(format!(
            "downloaded {} verified but could not be published to {}: {error}",
            file.asset,
            dest.display()
        ))
    })
}

fn run_pull(
    args: &PullArgs,
    environment: &Environment,
    stdout: &mut dyn Write,
) -> Result<(), FttsError> {
    let manifest = ModelManifest::embedded()?;
    let destination = match &args.model {
        Some(path) => path.clone(),
        None => default_pull_model_dir(environment).ok_or_else(|| {
            FttsError::Usage(
                "cannot choose a model directory: pass --model PATH, or set FTTS_MODEL_DIR or HOME"
                    .to_owned(),
            )
        })?,
    };
    writeln!(
        stdout,
        "pulling {} ({} files, {} bytes) into {}",
        manifest.model_id,
        manifest.files.len(),
        manifest.total_bytes(),
        destination.display()
    )
    .map_err(output_error)?;
    for file in &manifest.files {
        let dest = destination.join(&file.dest);
        match pull_decision(&dest, file, args.force) {
            PullDecision::Skip => writeln!(
                stdout,
                "{} ({} bytes): already present, verified",
                file.dest, file.bytes
            )
            .map_err(output_error)?,
            PullDecision::Download => {
                writeln!(stdout, "{} ({} bytes): downloading", file.dest, file.bytes)
                    .map_err(output_error)?;
                pull_one_file(&manifest, file, &dest)?;
                writeln!(stdout, "{} ({} bytes): verified", file.dest, file.bytes)
                    .map_err(output_error)?;
            }
        }
    }
    writeln!(stdout, "model ready at {}", destination.display()).map_err(output_error)
}

fn resolve_existing_file<'a>(path: &'a Path, label: &str) -> Result<&'a Path, FttsError> {
    if path.is_file() {
        Ok(path)
    } else {
        Err(FttsError::ModelNotFound(format!(
            "{label} {} does not exist or is not a file; use an existing PATH",
            path.display()
        )))
    }
}

/// Preflight admission for `say --check`, computed by the **engine**, not by the CLI.
///
/// This used to be a CLI-local heuristic whose own text said "model-specific KV and memory
/// admission is pending the V_REL engine". That engine now exists, so the preflight calls
/// [`ftts_core::admission`] directly. The point is not code reuse: it is that `--check` and the
/// synthesis that follows it must reach the *same* verdict for the same request. A preflight that
/// says yes and an engine that then says no is worse than no preflight, because the caller
/// budgeted on the first answer.
///
/// Prompt length is not knowable before tokenization, so `--check` reports the admission decision
/// for an *estimated* prompt length and labels it as such. The binding decision remains the
/// engine's, taken after real tokenization.
fn admission_plan(text: &str, settings: &EffectiveSettings) -> Result<Value, FttsError> {
    if text.len() > SCAFFOLD_ADMISSION_TEXT_LIMIT_BYTES {
        return Err(FttsError::BudgetTimeout(format!(
            "text is {} bytes, above the Phase-0 admission bound of {} bytes; split the document before retrying",
            text.len(),
            SCAFFOLD_ADMISSION_TEXT_LIMIT_BYTES
        )));
    }

    let characters = text.chars().count();
    // A deliberately conservative stand-in until the tokenizer is on this path: over-estimating
    // the prompt can only make the preflight refuse something the engine would admit, which is the
    // safe direction. Under-estimating would promise capacity that is not there.
    let estimated_prompt_tokens = u64::try_from(characters).unwrap_or(u64::MAX);
    // The engine's own env-resolved policy (FTTS_MEMORY_BUDGET_MB / FTTS_MAX_FRAMES), not a copy
    // of it — a second parse of the same variables is a second thing to drift.
    let policy = ftts_core::process_engine_config().admission;

    match policy.admit(estimated_prompt_tokens) {
        Ok(plan) => Ok(json!({
            "status": "accepted",
            "scope": "preflight on an ESTIMATED prompt length; the binding decision is the \
                      engine's, taken after tokenization",
            "text_bytes": text.len(),
            "text_characters": characters,
            "estimated_prompt_tokens": estimated_prompt_tokens,
            "predicted_max_frames": plan.predicted_max_frames,
            "predicted_peak_bytes": plan.predicted_peak_bytes,
            "budget_bytes": plan.budget_bytes,
            "binding_constraint": plan.binding_constraint.as_str(),
            "packet_frames": settings.packet_frames.as_str(),
            "profile": settings.profile.as_str(),
        })),
        // AdmissionRejection's Display already carries the shortfall, the binding constraint and
        // what to do about it, so it is passed through rather than re-summarised into something
        // less specific.
        Err(rejection) => Err(FttsError::BudgetTimeout(rejection.to_string())),
    }
}

#[derive(Debug, clap::Args)]
struct CardArgs {
    #[command(subcommand)]
    command: CardCommand,
}

#[derive(Debug, Subcommand)]
enum CardCommand {
    /// Render a voice as a shareable card PNG (mosaic + lossless chunk).
    Export {
        /// Voice source: a .spk vector file or a built-in voice name
        /// (matt, james, leo, robert, judy, aria, ember, liam, anthony, russell, steve, daniel, meryl, laurence, jack, michael, jodie, denzel).
        #[arg(value_name = "PATH|NAME")]
        voice: String,
        /// Name written INTO the card (shown on phones at import).
        /// Default: the preset name or the .spk file stem.
        #[arg(long, value_name = "NAME")]
        name: Option<String>,
        /// Output PNG path. Default: <name>-voice-card.png beside the source.
        #[arg(short, long, value_name = "PATH")]
        output: Option<PathBuf>,
    },
    /// Read a voice card image (PNG or JPEG) back into a .spk vector.
    Import {
        /// The card image: an original PNG, a screenshot, or a re-compressed JPEG.
        #[arg(value_name = "IMAGE")]
        image: PathBuf,
        /// Output .spk path. Default: <embedded name>.spk beside the image.
        #[arg(short, long, value_name = "PATH")]
        output: Option<PathBuf>,
    },
}

fn run_card(args: &CardArgs, stdout: &mut dyn Write) -> Result<(), FttsError> {
    match &args.command {
        CardCommand::Export {
            voice,
            name,
            output,
        } => {
            let (vector, default_name, base_dir) = if let Some((preset_name, _, bytes)) =
                PRESET_VOICES.iter().find(|(n, _, _)| n == voice)
            {
                let vector: Vec<f32> = bytes
                    .as_chunks::<4>()
                    .0
                    .iter()
                    .map(|chunk| f32::from_le_bytes(*chunk))
                    .collect();
                ((vector), (*preset_name).to_owned(), PathBuf::from("."))
            } else {
                let path = PathBuf::from(voice);
                // A bare word that is not a preset and not a file is almost always a
                // typo'd preset name; a raw file-not-found error would hide that.
                if !path.exists()
                    && !voice.contains('.')
                    && !voice.contains('/')
                    && !voice.contains('\\')
                {
                    let names: Vec<&str> = PRESET_VOICES.iter().map(|(name, _, _)| *name).collect();
                    return Err(FttsError::Input(format!(
                        "`{voice}` is not a built-in voice (those are: {}) and no such file exists",
                        names.join(", ")
                    )));
                }
                let vector = card::read_spk(&path)?;
                let stem = path
                    .file_stem()
                    .map_or_else(|| "voice".to_owned(), |s| s.to_string_lossy().into_owned());
                let dir = path
                    .parent()
                    .map_or_else(|| PathBuf::from("."), Path::to_path_buf);
                (vector, stem, dir)
            };
            let card_name = name.clone().unwrap_or(default_name);
            let png = card::render_card_png(&card_name, &vector)?;
            let destination = output.clone().unwrap_or_else(|| {
                base_dir.join(format!(
                    "{}-voice-card.png",
                    card::safe_file_stem(&card_name)
                ))
            });
            std::fs::write(&destination, &png).map_err(|error| {
                FttsError::Generic(format!("cannot write {}: {error}", destination.display()))
            })?;
            writeln!(
                stdout,
                "wrote {} ({} KB) — the mosaic is the voice; phones import it from Photos",
                destination.display(),
                png.len() / 1024
            )
            .map_err(|error| FttsError::Generic(error.to_string()))?;
            Ok(())
        }
        CardCommand::Import { image, output } => {
            let bytes = std::fs::read(image).map_err(|error| {
                FttsError::Input(format!("cannot read {}: {error}", image.display()))
            })?;
            let (voice_name, vector) = card::decode_card(&bytes)?;
            let destination = output
                .clone()
                .unwrap_or_else(|| card::default_import_path(image, &voice_name));
            card::write_spk(&destination, &vector)?;
            writeln!(
                stdout,
                "imported \"{voice_name}\" -> {} — use it with: ftts say --voice {}",
                destination.display(),
                destination.display()
            )
            .map_err(|error| FttsError::Generic(error.to_string()))?;
            Ok(())
        }
    }
}

fn run_voice_inspect(path: &Path, stdout: &mut dyn Write) -> Result<(), FttsError> {
    let path = resolve_existing_file(path, "voice pack")?;
    let bytes = std::fs::read(path)
        .map_err(|error| FttsError::Input(format!("cannot read {}: {error}", path.display())))?;
    if bytes.starts_with(ftts_artifacts::voice::VOICE_MAGIC) {
        let pack = ftts_artifacts::voice::parse_voice_pack(&bytes).map_err(|error| {
            FttsError::Input(format!(
                "{} is not a valid voice pack: {error}",
                path.display()
            ))
        })?;
        style::ok(
            stdout,
            &format!(
                "{} — {} voice pack",
                style::emphasis(&path.display().to_string()),
                pack.profile.as_str(),
            ),
        )
        .map_err(|error| FttsError::Generic(error.to_string()))?;
        let consent = if pack.consent.attested {
            format!("attested ({})", pack.consent.method.as_str())
        } else {
            "NOT ATTESTED".to_owned()
        };
        style::info(
            stdout,
            &format!(
                "consent {consent} · embedding {} f32 · transcript {} · codec tokens {} · audio {}",
                pack.embedding.len(),
                if pack.transcript.is_some() {
                    "yes"
                } else {
                    "no"
                },
                match pack.codec_codes.as_deref() {
                    Some(codes) => format!("{} frames", codes.len()),
                    None => "none".to_owned(),
                },
                if pack.reference_audio.is_some() {
                    "embedded"
                } else {
                    "absent"
                },
            ),
        )
        .map_err(|error| FttsError::Generic(error.to_string()))?;
        if let Some(dx) = &pack.diagnostics {
            for warning in dx_warnings(dx) {
                style::warn(stdout, &warning)
                    .map_err(|error| FttsError::Generic(error.to_string()))?;
            }
        }
        write_json_line(
            stdout,
            &json!({
                "schema_version": ROBOT_SCHEMA_VERSION,
                "event": "voice_inspect",
                "path": path.display().to_string(),
                "status": "ok",
                "profile": pack.profile.as_str(),
                "consent_attested": pack.consent.attested,
                "consent_method": pack.consent.method.as_str(),
                "language": pack.language,
                "transcript_present": pack.transcript.is_some(),
                "codec_codes_present": pack.codec_codes.is_some(),
                "reference_audio_present": pack.reference_audio.is_some(),
                "diagnostics": pack.diagnostics
                    .as_ref()
                    .map(|dx| json!({
                        "clipping_fraction": dx.clipping_fraction,
                        "longest_clip_run": dx.longest_clip_run,
                        "intersample_overshoot_db": dx.intersample_overshoot_db,
                        "snr_estimate_db": dx.snr_estimate_db,
                        "pause_floor_dbfs": dx.pause_floor_dbfs,
                        "reverb_time_s": dx.reverb_time_s,
                        "music_bed_likelihood": dx.music_bed_likelihood,
                        "stationarity_drift": dx.stationarity_drift,
                        "loudness_rms_dbfs": dx.loudness_rms_dbfs,
                        "voice_activity_ratio": dx.voice_activity_ratio,
                    })),
                "recipe_hash": pack.recipe_hash().ok(),
                "embedding_sha256": ftts_artifacts::sha256::hex_digest(
                    &ftts_artifacts::sha256::digest(&{
                        let mut b = Vec::with_capacity(pack.embedding.len() * 4);
                        for v in &pack.embedding { b.extend_from_slice(&v.to_le_bytes()); }
                        b
                    })),
                "provenance_engine": pack.provenance.engine,
            }),
        )
    } else if bytes.len() == synth::SPEAKER_VECTOR_BYTES {
        write_json_line(
            stdout,
            &json!({
                "schema_version": ROBOT_SCHEMA_VERSION,
                "event": "voice_inspect",
                "path": path.display().to_string(),
                "status": "legacy_speaker_vector",
            }),
        )
    } else {
        Err(FttsError::Input(format!(
            "{} is neither a .ftvoice pack nor a raw .spk vector; re-enroll to produce a pack",
            path.display()
        )))
    }
}

/// Re-renders a stored diagnostics record through the live advisory thresholds, so an old pack
/// speaks with the same voice the enrollment console used.
fn dx_warnings(dx: &ftts_artifacts::voice::EnrollmentDiagnostics) -> Vec<String> {
    let audio = crate::diagnostics::AudioDiagnostics {
        clipping_fraction: dx.clipping_fraction,
        longest_clip_run: dx.longest_clip_run,
        intersample_overshoot_db: dx.intersample_overshoot_db,
        snr_estimate_db: dx.snr_estimate_db,
        pause_floor_dbfs: dx.pause_floor_dbfs,
        reverb_time_s: dx.reverb_time_s,
        music_bed_likelihood: dx.music_bed_likelihood,
        stationarity_drift: dx.stationarity_drift,
        loudness_rms_dbfs: dx.loudness_rms_dbfs,
        voice_activity_ratio: dx.voice_activity_ratio,
    };
    audio.warnings()
}

fn run_robot(
    command: RobotCommand,
    environment: &Environment,
    stdout: &mut dyn Write,
) -> Result<(), FttsError> {
    // Every object below is built from `robot::EventType`, so the discriminator and
    // schema_version cannot be forgotten, and the frozen contract test in ftts-conformance
    // fails if any of these stops matching the catalogue.
    let event = match command {
        RobotCommand::Schema { contract } => match contract {
            SchemaContract::Run => robot::schema_document(robot::DOCUMENTED_ENVIRONMENT),
            SchemaContract::Session => {
                session_protocol::session_schema_document(robot::DOCUMENTED_ENVIRONMENT)
            }
        },
        RobotCommand::Health => {
            let searched = model_search_paths(environment);
            let found = searched.iter().find(|path| looks_like_model_artifact(path));
            let mut object = robot::EventType::Health.event();
            object.insert("status".to_owned(), json!("phase0_skeleton"));
            object.insert("model_loaded".to_owned(), json!(false));
            // Presence is a magic-bytes header sniff, never a tensor load: `robot health` must
            // stay cheap enough for an agent to call it on every invocation.
            object.insert("model_present".to_owned(), json!(found.is_some()));
            object.insert(
                "model_path".to_owned(),
                json!(found.map(|path| path.display().to_string())),
            );
            object.insert(
                "model_dir".to_owned(),
                json!(environment.value("FTTS_MODEL_DIR")),
            );
            // Every directory consulted, so a resolution failure is actionable rather than a
            // bare "not found".
            object.insert(
                "searched".to_owned(),
                json!(
                    searched
                        .iter()
                        .map(|path| path.display().to_string())
                        .collect::<Vec<_>>()
                ),
            );
            object.insert("stateless_default".to_owned(), json!(true));
            object.insert(
                "threads".to_owned(),
                json!(
                    environment
                        .value("FTTS_THREADS")
                        .and_then(|value| value.parse::<u64>().ok())
                ),
            );
            object.insert(
                "recommended_command".to_owned(),
                json!("ftts say --check --model PATH TEXT"),
            );
            Value::Object(object)
        }
        RobotCommand::Backends => {
            let mut object = robot::EventType::Backends.event();
            // Capability vs executed-route split: `available` is every tier this build can
            // certify on this CPU; `dispatched` is the one the int8 route would actually run.
            object.insert(
                "available".to_owned(),
                json!(
                    ftts_kernels::int8::Int8Tier::available()
                        .iter()
                        .map(|tier| tier.as_str())
                        .collect::<Vec<_>>()
                ),
            );
            object.insert(
                "dispatched".to_owned(),
                json!(ftts_kernels::int8::Int8Tier::dispatch().as_str()),
            );
            object.insert("isa_features".to_owned(), json!(detected_isa_features()));
            let plan = ftts_kernels::int8::autotuned_plan();
            object.insert(
                "kernel_plan".to_owned(),
                json!({
                    "version": 0,
                    "decode_gemv": plan.decode_gemv.as_str(),
                    "batch_gemm": plan.batch_gemm.as_str(),
                    "persisted": matches!(
                        ftts_kernels::int8::plan_source(),
                        ftts_kernels::int8::PlanSource::PersistedCache
                    ),
                }),
            );
            object.insert("pool_sizing".to_owned(), Value::Null);
            object.insert(
                "force_arch".to_owned(),
                json!(environment.value("FTTS_FORCE_ARCH")),
            );
            Value::Object(object)
        }
        RobotCommand::Selftest => {
            // The permanent integer-kernel law, executed on the end user's silicon: every census
            // binding row through the real dot kernels on every dispatchable tier. The event's
            // top-level fields are pinned by the frozen v1 schema fixture (status/reason/checks);
            // per-row detail lives inside `checks`.
            let report = ftts_kernels::selftest::run_selftest();
            let checks: Vec<Value> = report
                .checks
                .iter()
                .map(|check| {
                    json!({
                        "row": check.row.id,
                        "scope": check.row.scope.as_str(),
                        "census_tensor": check.row.census_tensor,
                        "reduction_k": check.row.reduction_k,
                        "tier": check.tier.as_str(),
                        "contract": check.contract.as_str(),
                        "dispatched": check.tier == report.dispatched,
                        "accumulator_i32": check.accumulator_i32,
                        "reference_i64": check.reference_i64,
                        "passed": check.passed,
                    })
                })
                .collect();
            let mut object = robot::EventType::Selftest.event();
            object.insert(
                "status".to_owned(),
                json!(if report.passed() { "passed" } else { "failed" }),
            );
            object.insert("reason".to_owned(), Value::Null);
            object.insert("checks".to_owned(), json!(checks));
            Value::Object(object)
        }
    };
    write_json_line(stdout, &event)
}

/// Every path the model resolver consults, in order.
///
/// Shared by `robot health` and the resolution error so the two can never disagree about what
/// was searched — a "not found" that lists different directories than `health` reports is worse
/// than no list at all.
fn model_search_paths(environment: &Environment) -> Vec<PathBuf> {
    let mut searched = environment
        .value("FTTS_MODEL_DIR")
        .map(std::env::split_paths)
        .map(|paths| {
            paths
                .map(|path| path.join(MODEL_BASENAME))
                .collect::<Vec<_>>()
        })
        .unwrap_or_default();
    if let Some(home) = std::env::var_os("HOME") {
        let home = PathBuf::from(home);
        searched.push(home.join(".cache/franken_tts/models").join(MODEL_BASENAME));
        // The `ftts pull` destination, listed after the legacy plural directory so existing
        // installs keep winning; it is also the bundle-directory fallback in `resolve_model_from`,
        // which is what lets a bare `ftts pull` then `ftts say` work with no env var at all.
        searched.push(home.join(DEFAULT_MODEL_CACHE_SUBDIR).join(MODEL_BASENAME));
    }
    searched
}

/// A cheap header sniff: is there a plausible `.fttsq` artifact at this path?
///
/// Reads the magic bytes only. Deliberately never opens the tensor data — `robot health` is
/// meant to be callable on every agent invocation, and a multi-gigabyte read would make it a
/// thing agents avoid calling, which defeats the point.
fn looks_like_model_artifact(path: &Path) -> bool {
    use std::io::Read as _;

    let Ok(mut file) = fs::File::open(path) else {
        return false;
    };
    let mut magic = [0u8; 5];
    file.read_exact(&mut magic).is_ok() && &magic == b"FTTSQ"
}

/// ISA features detected at runtime, for `robot backends`.
///
/// Reported as a plain list so an agent can see what the dispatcher had available; the kernel
/// tiers themselves land with the Phase-3 engines.
fn detected_isa_features() -> Vec<&'static str> {
    let mut features = Vec::new();
    #[cfg(target_arch = "aarch64")]
    {
        if std::arch::is_aarch64_feature_detected!("neon") {
            features.push("neon");
        }
        if std::arch::is_aarch64_feature_detected!("dotprod") {
            features.push("dotprod");
        }
        if std::arch::is_aarch64_feature_detected!("i8mm") {
            features.push("i8mm");
        }
    }
    #[cfg(target_arch = "x86_64")]
    {
        if std::arch::is_x86_feature_detected!("avx2") {
            features.push("avx2");
        }
        if std::arch::is_x86_feature_detected!("avxvnni") {
            features.push("avx-vnni");
        }
        if std::arch::is_x86_feature_detected!("avx512vnni") {
            features.push("avx512-vnni");
        }
    }
    features
}

fn run_doctor(
    args: &DoctorArgs,
    environment: &Environment,
    stdout: &mut dyn Write,
) -> Result<(), FttsError> {
    let model_present = model_search_paths(environment)
        .iter()
        .find(|path| looks_like_model_artifact(path))
        .map(|path| path.display().to_string());
    let report = json!({
        "schema_version": ROBOT_SCHEMA_VERSION,
        "status": if model_present.is_some() { "ready" } else { "model_missing" },
        "stateless_default": true,
        "persistent_history": false,
        "model_present": model_present,
        "environment": environment.documented_values(),
        "recommended_command": if model_present.is_some() {
            "ftts say \"hello\" -o hello.wav"
        } else {
            "ftts pull"
        },
    });
    if args.json {
        write_json_line(stdout, &report)
    } else {
        let human = format!(
            "FrankenTTS ftts — local readiness\nstateless default: yes\nmodel: {}\nnext: {}\n",
            model_present.as_deref().map_or_else(
                || "missing — run `ftts pull`".to_owned(),
                |p| format!("present ({p})")
            ),
            report["recommended_command"]
                .as_str()
                .unwrap_or("ftts robot schema"),
        );
        write!(stdout, "{human}").map_err(output_error)
    }
}

fn write_json_line(writer: &mut dyn Write, value: &Value) -> Result<(), FttsError> {
    serde_json::to_writer(&mut *writer, value)
        .map_err(|error| FttsError::Generic(format!("cannot serialize CLI JSON: {error}")))?;
    writer.write_all(b"\n").map_err(output_error)
}

fn output_error(error: io::Error) -> FttsError {
    FttsError::Generic(format!("cannot write CLI output: {error}"))
}

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

    #[test]
    fn preset_voices_are_valid_speaker_vectors() {
        assert!(
            PRESET_VOICES
                .iter()
                .any(|(name, _, _)| *name == DEFAULT_PRESET_VOICE),
            "the default preset must exist in the table"
        );
        for (name, character, bytes) in PRESET_VOICES {
            assert_eq!(
                bytes.len(),
                synth::SPEAKER_VECTOR_BYTES,
                "preset {name} must be exactly one 1,024-float x-vector"
            );
            assert!(
                !character.is_empty(),
                "preset {name} needs a character line"
            );
        }
    }

    #[test]
    fn preset_names_resolve_and_unknown_names_do_not() {
        let environment = Environment {
            values: BTreeMap::new(),
            stage_budget_values: BTreeMap::new(),
        };
        let resolved = resolve_requested_voice(Some(Path::new("aria")), &environment)
            .expect("preset name resolves")
            .expect("preset yields a path");
        let bytes = fs::read(&resolved).expect("materialized preset readable");
        assert_eq!(bytes.len(), synth::SPEAKER_VECTOR_BYTES);

        let error = resolve_requested_voice(Some(Path::new("no-such-voice")), &environment)
            .expect_err("unknown names are refused");
        assert!(
            error.to_string().contains("aria"),
            "the refusal must list the built-in names, got: {error}"
        );
    }

    // Re-baselined for the `talk` subcommand (bead frankentts-edz0), which landed without
    // updating this snapshot. The snapshot exists to make CLI-surface changes deliberate rather
    // than accidental, so it is re-baselined only alongside a real, intended command — never
    // widened to stop failing.
    const CLAP_SURFACE_SNAPSHOT: &str = "commands=say,make-video,enroll,voice,card,convert,pull,talk,robot,doctor,resident-daemon\nrobot=schema,health,backends,selftest\nsay=file,model,voice,output,stream,check,robot,no-resident\npull=model,force\nglobal=profile,packet-frames,math-mode,voice-pack,normalize,trace,seed\n";

    #[test]
    fn clap_surface_matches_snapshot() {
        let command = Cli::command();
        let commands = command
            .get_subcommands()
            .map(|command| command.get_name())
            .collect::<Vec<_>>()
            .join(",");
        let robot = command
            .get_subcommands()
            .find(|command| command.get_name() == "robot")
            .expect("robot subcommand")
            .get_subcommands()
            .map(|command| command.get_name())
            .collect::<Vec<_>>()
            .join(",");
        let say = command
            .get_subcommands()
            .find(|command| command.get_name() == "say")
            .expect("say subcommand")
            .get_arguments()
            .filter_map(|argument| argument.get_long())
            .collect::<Vec<_>>()
            .join(",");
        let pull = command
            .get_subcommands()
            .find(|command| command.get_name() == "pull")
            .expect("pull subcommand")
            .get_arguments()
            .filter_map(|argument| argument.get_long())
            .collect::<Vec<_>>()
            .join(",");
        let global = command
            .get_arguments()
            .filter_map(|argument| argument.get_long())
            .filter(|argument| *argument != "help")
            .collect::<Vec<_>>()
            .join(",");
        let actual = format!(
            "commands={commands}\nrobot={robot}\nsay={say}\npull={pull}\nglobal={global}\n"
        );
        assert_eq!(actual, CLAP_SURFACE_SNAPSHOT);
    }

    #[test]
    fn argument_file_and_stdin_text_are_identical() {
        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../README.md");
        let expected = fs::read_to_string(&root).expect("checked-in README");
        let from_argument = read_text(
            &SayArgs {
                output_positional: None,
                text: Some(expected.clone()),
                file: None,
                model: None,
                voice: None,
                output: None,
                stream: None,
                check: true,
                robot: false,
                no_resident: true,
            },
            &mut Cursor::new(Vec::<u8>::new()),
        )
        .expect("argument text");
        let from_file = read_text(
            &SayArgs {
                output_positional: None,
                text: None,
                file: Some(root),
                model: None,
                voice: None,
                output: None,
                stream: None,
                check: true,
                robot: false,
                no_resident: true,
            },
            &mut Cursor::new(Vec::<u8>::new()),
        )
        .expect("file text");
        let from_stdin = read_text(
            &SayArgs {
                output_positional: None,
                text: Some("-".to_owned()),
                file: None,
                model: None,
                voice: None,
                output: None,
                stream: None,
                check: true,
                robot: false,
                no_resident: true,
            },
            &mut Cursor::new(expected.as_bytes()),
        )
        .expect("stdin text");

        assert_eq!(from_argument, from_file);
        assert_eq!(from_argument, from_stdin);
    }

    #[test]
    fn check_plan_is_deterministic_and_marks_its_scope() {
        let settings = EffectiveSettings {
            profile: ExecutionProfile::Strict,
            packet_frames: PacketFrames::Four,
            math_mode: MathMode::Strict,
            voice_pack: VoicePackProfile::Portable,
            normalize: NormalizeMode::Conservative,
        };
        let first = admission_plan("hello", &settings).expect("admission plan");
        let second = admission_plan("hello", &settings).expect("admission plan");
        assert_eq!(first, second);
        assert_eq!(first["status"], "accepted");
        // The preflight is explicit that it estimates the prompt and that the engine decides.
        assert!(
            first["scope"]
                .as_str()
                .unwrap_or_default()
                .contains("ESTIMATED")
        );
    }

    #[test]
    fn the_cli_preflight_and_the_engine_agree_on_the_same_request() {
        // The property that matters: `--check` saying yes and the engine then saying no is worse
        // than no preflight, because the caller budgeted on the first answer. Both must be the
        // same computation, not two implementations of the same rule.
        let settings = EffectiveSettings {
            profile: ExecutionProfile::Balanced,
            packet_frames: PacketFrames::Four,
            math_mode: MathMode::Strict,
            voice_pack: VoicePackProfile::Portable,
            normalize: NormalizeMode::Verbatim,
        };
        let text = "a moderately sized utterance for admission";
        let plan = admission_plan(text, &settings).expect("preflight admits");

        let policy = ftts_core::process_engine_config().admission;
        let engine = policy
            .admit(text.chars().count() as u64)
            .expect("engine admits the same request");

        assert_eq!(plan["predicted_peak_bytes"], engine.predicted_peak_bytes);
        assert_eq!(plan["predicted_max_frames"], engine.predicted_max_frames);
        assert_eq!(plan["budget_bytes"], engine.budget_bytes);
        assert_eq!(
            plan["binding_constraint"],
            engine.binding_constraint.as_str()
        );
    }

    #[test]
    fn a_wav_sink_writes_a_playable_file_and_conforming_audio_chunk_events() {
        let dir = std::env::temp_dir().join(format!("ftts-wav-sink-{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("temp dir");
        let path = dir.join("out.wav");

        let frame: Vec<f32> = (0..1_920)
            .map(|i| (i as f32 / 1_920.0 * std::f32::consts::TAU).sin() * 0.5)
            .collect();
        let mut sink = AudioOutput::wav(&path).expect("wav sink");
        let mut discard = Vec::new();

        let first = sink
            .write_packet(&frame, &mut discard, "run-1", 1)
            .expect("packet 1");
        let second = sink
            .write_packet(&frame, &mut discard, "run-1", 1)
            .expect("packet 2");

        // Every emitted object must satisfy the frozen robot contract, not merely look plausible.
        assert!(robot::validate_event(&first).is_empty(), "{first:?}");
        assert!(robot::validate_event(&second).is_empty(), "{second:?}");
        assert_eq!(first["sink"], "file");
        assert_eq!(first["byte_offset"], 0);
        assert_eq!(first["bytes"], 1_920 * 2);
        assert_eq!(first["duration_ms"], 80, "1,920 samples at 24 kHz is 80 ms");
        // The offset is cumulative, so a consumer can seek with it.
        assert_eq!(second["byte_offset"], 1_920 * 2);

        let samples = sink.finish().expect("finish");
        assert_eq!(samples, 1_920 * 2);

        // The file on disk must describe exactly what it holds.
        let bytes = std::fs::read(&path).expect("read wav");
        assert_eq!(&bytes[0..4], b"RIFF");
        assert_eq!(&bytes[8..12], b"WAVE");
        let declared = u32::from_le_bytes(bytes[40..44].try_into().expect("data size"));
        assert_eq!(declared as usize, 1_920 * 2 * 2);
        assert_eq!(bytes.len(), 44 + 1_920 * 2 * 2);
        assert!(
            discard.is_empty(),
            "a file sink must not also emit raw PCM to the stream"
        );
    }

    #[test]
    fn a_raw_sink_writes_pcm_to_the_stream_and_never_mixes_it_with_events() {
        // The stream contract: under --stream raw, stdout carries PCM only. An event object landing
        // in the same buffer would corrupt both — the audio and the NDJSON.
        let mut sink = AudioOutput::raw();
        let mut raw = Vec::new();
        let pcm = vec![0.5f32; 4];
        let event = sink
            .write_packet(&pcm, &mut raw, "run-1", 1)
            .expect("packet");

        assert!(robot::validate_event(&event).is_empty(), "{event:?}");
        assert_eq!(event["sink"], "stdout");
        assert_eq!(raw.len(), 8, "four 16-bit samples");
        let first = i16::from_le_bytes([raw[0], raw[1]]);
        assert_eq!(first, ftts_core::audio::sample_to_i16(0.5));
        // The PCM buffer must contain no JSON.
        assert!(
            !raw.windows(2).any(|w| w == b"{\""),
            "raw PCM stream must never contain an event object"
        );
    }

    #[test]
    fn a_none_sink_still_reports_conforming_events() {
        let mut sink = AudioOutput::none();
        let mut discard = Vec::new();
        let event = sink
            .write_packet(&[0.0f32; 960], &mut discard, "run-1", 2)
            .expect("packet");
        assert!(robot::validate_event(&event).is_empty(), "{event:?}");
        assert_eq!(event["sink"], "none");
        assert_eq!(event["packet_frames"], "2");
        assert!(discard.is_empty());
        assert_eq!(sink.finish().expect("finish"), 960);
    }

    #[test]
    fn a_health_violation_renders_as_a_contract_conforming_robot_event() {
        // The engine-to-wire seam: the violation's class, remedy and invalidates_output must
        // survive the crossing, and the result must satisfy the frozen robot contract.
        let silent =
            ftts_core::HealthEvent::Violation(ftts_core::health::HealthViolation::OutputSilent {
                silent_millis: 1_500,
            });
        let event = robot::health_violation_event("run-1", silent, 42);
        assert!(
            robot::validate_event(&event).is_empty(),
            "{:?}",
            robot::validate_event(&event)
        );
        assert_eq!(event["event"], "health_violation");
        assert_eq!(event["violation"], "output_silent");
        assert_eq!(event["invalidates_output"], true);
        assert!(event["detail"].as_str().expect("detail").contains("1500"));
        assert!(event["remedy"].as_str().expect("remedy").len() > 40);

        // A kernel demotion is informational: the run stayed correct, just slower. If this were
        // reported as invalidating, an agent would discard good audio.
        let demoted =
            ftts_core::HealthEvent::Violation(ftts_core::health::HealthViolation::KernelDemoted {
                from: ftts_core::health::KernelTier::Optimized("i8mm"),
                to: ftts_core::health::KernelTier::Scalar,
            });
        let event = robot::health_violation_event("run-1", demoted, 43);
        assert!(robot::validate_event(&event).is_empty());
        assert_eq!(event["invalidates_output"], false);

        // Budget and cancellation are health signals too, and both truncate the audio.
        for event in [
            ftts_core::HealthEvent::BudgetExceeded,
            ftts_core::HealthEvent::Cancelled,
        ] {
            let rendered = robot::health_violation_event("run-1", event, 44);
            assert!(robot::validate_event(&rendered).is_empty());
            assert_eq!(rendered["invalidates_output"], true);
        }
    }

    #[test]
    fn normalization_defaults_to_verbatim_conformance_mode() {
        let cli = Cli {
            profile: None,
            packet_frames: None,
            math_mode: None,
            voice_pack: None,
            normalize: None,
            trace: None,
            seed: None,
            command: Command::Robot(RobotArgs {
                command: RobotCommand::Health,
            }),
        };
        assert_eq!(
            EffectiveSettings::resolve(&cli, &Environment::default())
                .expect("default settings")
                .normalize,
            NormalizeMode::Verbatim
        );
        assert_eq!(
            EffectiveSettings::resolve(&cli, &Environment::default())
                .expect("default settings")
                .normalization_options(),
            NormalizationOptions::default(),
            "CLI defaults must use the same verbatim options as the library"
        );
    }

    #[test]
    fn cli_normalization_modes_map_to_shared_engine_options() {
        for (cli_mode, engine_mode) in [
            (NormalizeMode::Verbatim, NormalizationMode::Verbatim),
            (NormalizeMode::Conservative, NormalizationMode::Conservative),
            (NormalizeMode::LocaleAware, NormalizationMode::LocaleAware),
        ] {
            let settings = EffectiveSettings {
                profile: ExecutionProfile::Balanced,
                packet_frames: PacketFrames::Four,
                math_mode: MathMode::Strict,
                voice_pack: VoicePackProfile::Portable,
                normalize: cli_mode,
            };
            assert_eq!(settings.normalization_options().mode, engine_mode);
        }
    }

    #[test]
    fn embed_q8_flag_flips_exactly_the_text_embedding_and_says_so_in_the_manifest() {
        let default_specs = pinned_main_tensor_specs(false, false).expect("inventory parses");
        let armed_specs = pinned_main_tensor_specs(true, false).expect("inventory parses");
        assert_eq!(default_specs.len(), armed_specs.len());
        for (default, armed) in default_specs.iter().zip(&armed_specs) {
            assert_eq!(default.name, armed.name);
            if default.name == "talker.model.text_embedding.weight" {
                assert_eq!(default.storage, TensorStoragePolicy::Verbatim);
                assert_eq!(armed.storage, TensorStoragePolicy::Q8PerGroup64);
            } else {
                assert_eq!(
                    default.storage, armed.storage,
                    "--embed-q8 must touch no tensor but the text embedding ({})",
                    default.name
                );
            }
        }
    }

    #[test]
    fn micro_q8_flag_flips_exactly_the_microdecoder_tables_and_says_so_in_the_manifest() {
        let default_specs = pinned_main_tensor_specs(false, false).expect("inventory parses");
        let armed_specs = pinned_main_tensor_specs(false, true).expect("inventory parses");
        assert_eq!(default_specs.len(), armed_specs.len());
        let mut flipped = 0;
        for (default, armed) in default_specs.iter().zip(&armed_specs) {
            assert_eq!(default.name, armed.name);
            if is_micro_table(&default.name) {
                assert_eq!(default.storage, TensorStoragePolicy::Verbatim);
                assert_eq!(
                    armed.storage,
                    TensorStoragePolicy::Q8PerOutputChannel,
                    "--micro-q8 must quantize every microdecoder table ({})",
                    armed.name
                );
                flipped += 1;
            } else {
                assert_eq!(
                    default.storage, armed.storage,
                    "--micro-q8 must touch no tensor outside the microdecoder tables ({})",
                    default.name
                );
            }
        }
        assert_eq!(
            flipped, 30,
            "15 residual embedding tables plus 15 scoring heads"
        );
    }

    #[test]
    fn pinned_main_conversion_plan_preserves_the_reviewed_q8_boundary() {
        let specs =
            pinned_main_tensor_specs(false, false).expect("checked-in main inventory parses");
        let (_manifest, _plan) = pinned_main_conversion_plan(false, false)
            .expect("checked-in main conversion plan builds");
        assert_eq!(specs.len(), PINNED_MAIN_TENSOR_COUNT);
        assert_eq!(
            specs
                .iter()
                .filter(|spec| spec.storage == TensorStoragePolicy::Q8PerOutputChannel)
                .count(),
            231,
            "28 talker + 5 microdecoder layers times seven attention/MLP projections"
        );

        let text_embedding = specs
            .iter()
            .find(|spec| spec.name == "talker.model.text_embedding.weight");
        assert!(
            text_embedding.is_some(),
            "pinned inventory must contain the text embedding"
        );
        if let Some(text_embedding) = text_embedding {
            assert_eq!(text_embedding.storage, TensorStoragePolicy::Verbatim);
            assert_eq!(text_embedding.access_class, AccessClass::ColdTextEmbedding);
        }

        let talker_projection = specs
            .iter()
            .find(|spec| spec.name == "talker.model.layers.0.mlp.down_proj.weight");
        assert!(
            talker_projection.is_some(),
            "pinned inventory must contain the talker projection"
        );
        if let Some(talker_projection) = talker_projection {
            assert_eq!(
                talker_projection.storage,
                TensorStoragePolicy::Q8PerOutputChannel
            );
            assert_eq!(
                talker_projection.access_class,
                AccessClass::HotRecurrentTalker
            );
        }

        let micro_projection = specs
            .iter()
            .find(|spec| spec.name == "talker.code_predictor.model.layers.0.mlp.down_proj.weight");
        assert!(
            micro_projection.is_some(),
            "pinned inventory must contain the microdecoder projection"
        );
        if let Some(micro_projection) = micro_projection {
            assert_eq!(
                micro_projection.storage,
                TensorStoragePolicy::Q8PerOutputChannel
            );
            assert_eq!(
                micro_projection.access_class,
                AccessClass::HotRecurrentMicrodecoder
            );
        }

        let primary_embedding = specs
            .iter()
            .find(|spec| spec.name == "talker.model.codec_embedding.weight");
        assert!(
            primary_embedding.is_some(),
            "pinned inventory must contain the primary-code embedding"
        );
        if let Some(primary_embedding) = primary_embedding {
            assert_eq!(
                primary_embedding.access_class,
                AccessClass::HotRecurrentMicrodecoder,
                "the primary-code embedding feeds residual depth one every frame"
            );
        }

        let primary_head = specs
            .iter()
            .find(|spec| spec.name == "talker.codec_head.weight");
        assert!(
            primary_head.is_some(),
            "pinned inventory must contain the primary-code head"
        );
        if let Some(primary_head) = primary_head {
            assert_eq!(primary_head.storage, TensorStoragePolicy::Verbatim);
            assert_eq!(primary_head.access_class, AccessClass::HotRecurrentTalker);
        }

        let text_projection = specs
            .iter()
            .find(|spec| spec.name == "talker.text_projection.linear_fc1.weight");
        assert!(
            text_projection.is_some(),
            "pinned inventory must contain the text-projection MLP"
        );
        if let Some(text_projection) = text_projection {
            assert_eq!(text_projection.storage, TensorStoragePolicy::Verbatim);
            assert_eq!(
                text_projection.access_class,
                AccessClass::HotRecurrentTalker
            );
        }

        let head = specs
            .iter()
            .find(|spec| spec.name == "talker.code_predictor.lm_head.0.weight");
        assert!(
            head.is_some(),
            "pinned inventory must contain the residual-code head"
        );
        if let Some(head) = head {
            assert_eq!(head.storage, TensorStoragePolicy::Verbatim);
            assert_eq!(head.access_class, AccessClass::HotRecurrentMicrodecoder);
        }

        let speaker = specs
            .iter()
            .find(|spec| spec.name == "speaker_encoder.fc.weight");
        assert!(
            speaker.is_some(),
            "pinned inventory must contain the speaker encoder"
        );
        if let Some(speaker) = speaker {
            assert_eq!(speaker.storage, TensorStoragePolicy::Verbatim);
            assert_eq!(speaker.access_class, AccessClass::EnrollmentSpeakerEncoder);
        }
    }

    #[test]
    fn conversion_notice_carries_changes_and_the_full_license() {
        let notice = pinned_license_notice();
        assert!(notice.contains("Copyright 2026 Alibaba Cloud"));
        assert!(notice.contains("CHANGES: the original bfloat16 weights were converted"));
        assert!(notice.contains("Apache License"));
        assert!(notice.contains("TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION"));
    }

    #[test]
    fn convert_refusal_still_emits_a_versioned_robot_lifecycle() {
        let cli = Cli {
            profile: None,
            packet_frames: None,
            math_mode: None,
            voice_pack: None,
            normalize: None,
            trace: None,
            seed: None,
            command: Command::Robot(RobotArgs {
                command: RobotCommand::Health,
            }),
        };
        let args = ConvertArgs {
            // A readable file with the wrong name reaches the explicit pinned-source refusal
            // before any destination is created.
            source: PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml"),
            output: PathBuf::from("never-created.fttsq"),
            embed_q8: false,
            micro_q8: false,
        };
        let mut stdout = Vec::new();
        let mut stderr = Vec::new();
        let error = run_convert(
            &cli,
            &args,
            &Environment::default(),
            &mut stdout,
            &mut stderr,
        )
        .expect_err("the non-pinned source must be refused");
        assert_eq!(error.exit_code(), FttsExitCode::Input);

        let stdout = String::from_utf8(stdout).expect("NDJSON stdout");
        let stderr = String::from_utf8(stderr).expect("NDJSON stderr");
        assert!(robot::validate_ndjson(&stdout).is_empty());
        assert!(robot::validate_ndjson(&stderr).is_empty());
        let stdout_events = stdout
            .lines()
            .map(|line| serde_json::from_str::<Value>(line).expect("JSON event"))
            .collect::<Vec<_>>();
        assert_eq!(stdout_events[0]["event"], "run_start");
        assert_eq!(stdout_events[1]["event"], "stage");
        assert_eq!(
            serde_json::from_str::<Value>(stderr.trim()).expect("run error")["event"],
            "run_error"
        );
    }

    #[test]
    fn say_check_emits_a_versioned_admission_outcome() {
        let model = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml");
        let cli = Cli {
            profile: Some(ExecutionProfile::Balanced),
            packet_frames: Some(PacketFrames::Four),
            math_mode: Some(MathMode::Strict),
            voice_pack: Some(VoicePackProfile::Portable),
            normalize: Some(NormalizeMode::Conservative),
            trace: None,
            seed: Some(7),
            command: Command::Robot(RobotArgs {
                command: RobotCommand::Health,
            }),
        };
        let args = SayArgs {
            text: Some("checked text".to_owned()),
            output_positional: None,
            file: None,
            model: Some(model),
            voice: None,
            output: None,
            stream: None,
            check: true,
            robot: false,
            no_resident: true,
        };
        let mut stdin = Cursor::new(Vec::<u8>::new());
        let mut stdout = Vec::new();
        let mut stderr = Vec::new();

        run_say(
            &cli,
            &args,
            &Environment::default(),
            &mut stdin,
            &mut stdout,
            &mut stderr,
            IoCapabilities::default(),
        )
        .expect("check path");

        assert!(stderr.is_empty());
        let text = String::from_utf8(stdout).expect("utf-8 events");

        // The whole emitted stream must conform, not just the event this test cares about.
        assert!(
            robot::validate_ndjson(&text).is_empty(),
            "emitted stream violates the contract: {:?}",
            robot::validate_ndjson(&text)
        );

        let events: Vec<Value> = text
            .lines()
            .map(|line| serde_json::from_str(line).expect("one JSON object per line"))
            .collect();
        let names: Vec<&str> = events
            .iter()
            .map(|event| event["event"].as_str().expect("event name"))
            .collect();
        assert_eq!(
            names,
            vec![
                "run_start",
                "stage",
                "stage",
                "text_prepared",
                "stage",
                "stage",
                "check_complete",
                "run_complete",
            ],
            "the skeleton lifecycle must flow end-to-end on the empty pipeline"
        );

        // Every event in a run repeats the same run_id, which is what lets an agent stitch a run
        // together across the two streams.
        let run_id = events[0]["run_id"]
            .as_str()
            .expect("run_start carries run_id");
        assert!(!run_id.is_empty());
        assert!(events.iter().all(|event| event["run_id"] == run_id));
        assert!(
            events
                .iter()
                .all(|event| event["schema_version"] == ROBOT_SCHEMA_VERSION)
        );

        // Stage sequence numbers are dense and ordered, so a consumer can detect a dropped event.
        let seqs: Vec<u64> = events
            .iter()
            .filter(|event| event["event"] == "stage")
            .map(|event| event["seq"].as_u64().expect("seq"))
            .collect();
        assert_eq!(seqs, vec![0, 1, 2, 3]);

        let check = &events[6];
        // "accepted", not "scaffold_accepted": the preflight is now the engine's own
        // ftts_core::admission computation rather than a CLI-local heuristic, so `--check` and the
        // synthesis that follows it cannot reach different verdicts for the same request.
        assert_eq!(check["admission"]["status"], "accepted");
        assert!(
            check["admission"]["predicted_peak_bytes"].is_u64(),
            "the engine-backed plan reports a real predicted peak"
        );
        assert_eq!(check["normalization_trace_requested"], false);

        // text_prepared reports shape and provenance only; the input text must never appear.
        let prepared = &events[3];
        assert_eq!(prepared["char_count"], "checked text".chars().count());
        assert!(prepared["unicode_version"].is_string());
        assert!(
            !text.contains("checked text"),
            "the event stream must not carry the user's text"
        );

        assert_eq!(events[7]["exit_code"], 0);
    }

    #[test]
    fn a_newline_inside_a_field_cannot_break_ndjson_framing() {
        // The entire contract rests on one JSON object per line. serde_json escapes control
        // characters, so a message containing a newline stays one line and the newline survives as
        // data -- but nothing pinned that until now, and a hand-rolled serializer or a raw write
        // path would silently break every downstream parser.
        let run = robot::RunContext::with_id("r-test");
        let error = FttsError::Generic("first\nsecond".to_owned());
        let mut event = run.event(robot::EventType::RunError);
        event.insert("exit_code".to_owned(), json!(error.exit_code().as_u8()));
        event.insert("kind".to_owned(), json!(error.exit_code().description()));
        event.insert("message".to_owned(), json!(error.to_string()));
        event.insert("remediation".to_owned(), json!(error.remediation()));
        event.insert("elapsed_ms".to_owned(), json!(0));
        let value = Value::Object(event);

        let mut buffer = Vec::new();
        write_json_line(&mut buffer, &value).expect("serializes");
        let text = String::from_utf8(buffer).expect("utf-8");

        assert_eq!(
            text.lines().count(),
            1,
            "framing broken by an embedded newline"
        );
        assert!(robot::validate_ndjson(&text).is_empty());
        let parsed: Value = serde_json::from_str(text.trim_end()).expect("still one object");
        assert!(
            parsed["message"].as_str().expect("message").contains('\n'),
            "the newline must survive as data, not be stripped"
        );
    }

    #[test]
    fn pinned_copies_match_the_truth_pack_canonicals() {
        //  `pinned/` exists because `cargo package` cannot ship the truth pack. The truth pack
        //  stays canonical; a drifted copy would embed a stale pin assertion or attribution in
        //  the shipped binary, so byte-identity is asserted whenever the repo checkout is present.
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
        for (canonical, embedded, name) in [
            (
                "docs/truth-pack/TENSOR_INVENTORY.json",
                PINNED_TENSOR_INVENTORY,
                "TENSOR_INVENTORY.json",
            ),
            (
                "docs/truth-pack/snapshots/hf/config.json",
                PINNED_MODEL_CONFIG,
                "model_config.json",
            ),
            (
                "docs/truth-pack/snapshots/gh/LICENSE",
                APACHE_LICENSE,
                "QWEN_APACHE_LICENSE",
            ),
        ] {
            match std::fs::read_to_string(root.join(canonical)) {
                Ok(bytes) => assert_eq!(
                    bytes, embedded,
                    "pinned/{name} drifted from {canonical}; re-copy it"
                ),
                Err(_) => eprintln!(
                    "SKIP pinned-copy check for {name}: {canonical} absent (no repo checkout)"
                ),
            }
        }
    }

    #[test]
    fn embedded_model_manifest_is_wellformed_and_agrees_with_the_converter_pin() {
        let manifest = ModelManifest::embedded().expect("embedded manifest parses");
        assert_eq!(manifest.model_id, "qwen3-tts-12hz-0.6b-base");
        assert_eq!(manifest.release_tag, "model-qwen3-tts-v1");
        assert_eq!(manifest.repo, "Dicklesworthstone/franken_tts");
        assert_eq!(manifest.files.len(), 8);

        for file in &manifest.files {
            assert!(
                is_sha256_hex(&file.sha256),
                "{} carries a malformed digest",
                file.asset
            );
            assert!(file.bytes > 0, "{} has no pinned size", file.asset);
            let dest = Path::new(&file.dest);
            assert!(!dest.is_absolute(), "{} dest is absolute", file.asset);
            assert!(
                dest.components()
                    .all(|component| matches!(component, std::path::Component::Normal(_))),
                "{} dest can traverse out of the model directory",
                file.asset
            );
        }

        // Since frankentts-zm5 the pull ships the canonical quantized artifact, not the raw main
        // checkpoint: enrollment and synthesis both hydrate from the .fttsq, so pulling the raw
        // 1.7 GB main would be pure waste. The artifact lands at the exact basename every model
        // search path probes for.
        let main = manifest
            .files
            .iter()
            .find(|file| file.dest == MODEL_BASENAME)
            .expect("manifest carries the canonical artifact");
        assert_eq!(
            manifest.download_urls(main),
            [
                "https://huggingface.co/Dicklesworthstone/franken-tts-qwen3-tts-12hz-0.6b-base/resolve/main/qwen3-tts-12hz-0.6b-base.fttsq",
                "https://github.com/Dicklesworthstone/franken_tts/releases/download/model-qwen3-tts-v1/qwen3-tts-12hz-0.6b-base.fttsq",
            ]
        );
        assert!(
            !manifest
                .files
                .iter()
                .any(|file| file.dest == PINNED_MAIN_WEIGHTS_FILENAME),
            "pull must not fetch the raw main checkpoint alongside the canonical artifact"
        );

        // Together the files are exactly what ModelBundle::resolve requires plus the two config
        // sidecars, so a completed pull always resolves.
        let dests: Vec<&str> = manifest
            .files
            .iter()
            .map(|file| file.dest.as_str())
            .collect();
        for required in [
            MODEL_BASENAME,
            "speech_tokenizer/model.safetensors",
            "vocab.json",
            "merges.txt",
            "tokenizer_config.json",
        ] {
            assert!(dests.contains(&required), "manifest is missing {required}");
        }
    }

    #[test]
    fn malformed_model_manifests_are_refused_with_the_field_named() {
        fn manifest_with(
            schema_version: u64,
            asset: &str,
            dest: &str,
            sha256: &str,
            bytes: u64,
        ) -> String {
            json!({
                "schema_version": schema_version,
                "model_id": "m",
                "release_tag": "t",
                "repo": "owner/repo",
                "files": [{"asset": asset, "dest": dest, "sha256": sha256, "bytes": bytes}],
            })
            .to_string()
        }
        let good_sha = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";

        // The happy shape parses, so every refusal below is attributable to its one bad field.
        ModelManifest::parse(&manifest_with(1, "a.bin", "a.bin", good_sha, 1))
            .expect("well-formed manifest parses");

        for (label, text) in [
            (
                "unsupported schema_version",
                manifest_with(2, "a.bin", "a.bin", good_sha, 1),
            ),
            (
                "short sha256",
                manifest_with(1, "a.bin", "a.bin", "abc123", 1),
            ),
            (
                "uppercase sha256",
                manifest_with(1, "a.bin", "a.bin", &good_sha.to_uppercase(), 1),
            ),
            (
                "zero bytes",
                manifest_with(1, "a.bin", "a.bin", good_sha, 0),
            ),
            (
                "absolute dest",
                manifest_with(1, "a.bin", "/etc/passwd", good_sha, 1),
            ),
            (
                "traversal dest",
                manifest_with(1, "a.bin", "../escape.bin", good_sha, 1),
            ),
            (
                "asset with a path separator",
                manifest_with(1, "dir/a.bin", "a.bin", good_sha, 1),
            ),
            (
                "empty files array",
                json!({
                    "schema_version": 1,
                    "model_id": "m",
                    "release_tag": "t",
                    "repo": "owner/repo",
                    "files": [],
                })
                .to_string(),
            ),
        ] {
            let error = ModelManifest::parse(&text)
                .expect_err(&format!("a manifest with {label} must be refused"));
            assert_eq!(error.exit_code(), FttsExitCode::ArtifactFormat, "{label}");
        }
    }

    #[test]
    fn pull_skips_only_a_file_matching_both_pinned_size_and_digest() {
        let dir = std::env::temp_dir().join(format!("ftts-pull-decision-{}", std::process::id()));
        fs::create_dir_all(&dir).expect("temp dir");
        let payload = b"pinned payload";
        let file = ModelManifestFile {
            asset: "a.bin".to_owned(),
            dest: "a.bin".to_owned(),
            sha256: ftts_artifacts::sha256::hex_digest(payload),
            bytes: payload.len() as u64,
        };
        let dest = dir.join("a.bin");

        let _ = fs::remove_file(&dest);
        assert_eq!(
            pull_decision(&dest, &file, false),
            PullDecision::Download,
            "absent file must download"
        );

        fs::write(&dest, payload).expect("write verified payload");
        assert_eq!(
            pull_decision(&dest, &file, false),
            PullDecision::Skip,
            "matching size and digest must skip"
        );
        assert_eq!(
            pull_decision(&dest, &file, true),
            PullDecision::Download,
            "--force must re-download even a verified file"
        );

        fs::write(&dest, b"pinned_payload").expect("write same-length corruption");
        assert_eq!(
            pull_decision(&dest, &file, false),
            PullDecision::Download,
            "a same-length corruption must be caught by the digest"
        );

        fs::write(&dest, b"short").expect("write truncation");
        assert_eq!(
            pull_decision(&dest, &file, false),
            PullDecision::Download,
            "a truncated file must be caught by the size check"
        );
    }

    #[test]
    fn model_resolution_prefers_explicit_then_searched_then_the_pull_directory() {
        let root = std::env::temp_dir().join(format!("ftts-resolve-order-{}", std::process::id()));

        // A complete bundle directory: ModelBundle::resolve only asks `is_file`, so empty files
        // are a sufficient fake (and would fail loudly if the resolver ever started reading).
        let bundle = root.join("bundle");
        for relative in [
            "model.safetensors",
            "speech_tokenizer/model.safetensors",
            "vocab.json",
            "merges.txt",
            "tokenizer_config.json",
        ] {
            let path = bundle.join(relative);
            fs::create_dir_all(path.parent().expect("bundle parent")).expect("bundle dirs");
            fs::write(&path, b"").expect("bundle file");
        }
        assert!(
            synth::ModelBundle::resolve(&bundle).is_ok(),
            "five empty files must satisfy the resolver's is_file checks"
        );

        let searched_artifact = root.join("searched").join(MODEL_BASENAME);
        fs::create_dir_all(searched_artifact.parent().expect("searched parent"))
            .expect("searched dir");
        fs::write(&searched_artifact, b"").expect("searched artifact");
        let searched = vec![searched_artifact.clone()];
        let absent = vec![root.join("absent").join(MODEL_BASENAME)];

        // 1. `--model` outranks everything.
        assert_eq!(
            resolve_model_from(Some(&bundle), &searched, Some(&bundle)).expect("explicit"),
            bundle.display().to_string()
        );

        // 2. A searched artifact outranks the pull directory.
        assert_eq!(
            resolve_model_from(None, &searched, Some(&bundle)).expect("searched"),
            searched_artifact.display().to_string()
        );

        // 3. The pull directory resolves when nothing searched exists.
        assert_eq!(
            resolve_model_from(None, &absent, Some(&bundle)).expect("pull fallback"),
            bundle.display().to_string()
        );

        // 4. An incomplete pull directory does not resolve, and the error teaches `ftts pull`.
        let incomplete = root.join("incomplete");
        fs::create_dir_all(&incomplete).expect("incomplete dir");
        let error = resolve_model_from(None, &absent, Some(&incomplete))
            .expect_err("an empty pull directory must not resolve");
        assert_eq!(error.exit_code(), FttsExitCode::ModelNotFound);
        assert!(error.to_string().contains("ftts pull"), "{error}");
        assert!(error.to_string().contains("2.0 GB"), "{error}");
        assert!(error.to_string().contains("FTTS_MODEL_DIR"), "{error}");
    }

    #[test]
    fn the_pull_directory_default_prefers_the_env_override() {
        let mut environment = Environment::default();
        environment
            .values
            .insert("FTTS_MODEL_DIR", Some(OsString::from("/tmp/env-model-dir")));
        assert_eq!(
            default_pull_model_dir(&environment),
            Some(PathBuf::from("/tmp/env-model-dir"))
        );

        // Without the override the default lives under $HOME; the exact suffix is the contract
        // `ftts pull` and model resolution share.
        if std::env::var_os("HOME").is_some() {
            let fallback = default_pull_model_dir(&Environment::default())
                .expect("HOME is set, so a default exists");
            assert!(
                fallback.ends_with(DEFAULT_MODEL_CACHE_SUBDIR),
                "{fallback:?}"
            );
        }
    }

    /// Two-strike semantics: the first signal cancels cooperatively, every later one
    /// is a force-exit — the state machine the ctrlc hook runs.
    #[test]
    fn first_signal_trips_and_later_signals_force_exit() {
        assert_eq!(next_strike_action(0), StrikeAction::Trip);
        assert_eq!(next_strike_action(1), StrikeAction::Trip);
        assert_eq!(next_strike_action(2), StrikeAction::ForceExit);
        assert_eq!(next_strike_action(9), StrikeAction::ForceExit);
    }

    /// The handler-trip path without an OS signal: tripping the shared token through
    /// the same routine the hook calls must flip both the flag and the engine token,
    /// which is what `was_tripped` reports to the run's error paths.
    #[test]
    fn trip_active_cancel_marks_the_state_and_token() {
        let cancel = std::sync::Arc::new(CancelState::new());
        assert!(!cancel.was_tripped(), "fresh state starts untripped");

        // Install as the served run, then trip exactly as the signal hook would.
        *ACTIVE_CANCEL.lock().expect("lock") = Some(cancel.clone());
        cancel.token.cancel();
        trip_active_cancel();

        assert!(cancel.tripped.load(std::sync::atomic::Ordering::Relaxed));
        assert!(cancel.was_tripped(), "both routes must report tripped");
        // Restore so other tests never observe this state.
        *ACTIVE_CANCEL.lock().expect("lock") = None;
    }

    /// The disposition wording per sink kind: file sinks name the kept artifact,
    /// compressed targets state the skipped encoding and staging path, raw streams
    /// report streamed bytes. These messages ride the EXISTING run_error.message
    /// field — no new event vocabulary anywhere.
    #[test]
    fn cancelled_dispositions_name_what_happened_to_the_audio() {
        let scratch = std::env::temp_dir().join(format!(
            "ftts-cancel-disposition-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(0, |d| d.as_nanos())
        ));
        std::fs::create_dir_all(&scratch).expect("scratch dir");

        // WAV: partial file finalized at the requested path.
        let wav_plan = OutputPlan::for_path(&scratch.join("out.wav")).expect("wav plan");
        let audio = AudioOutput::wav(&wav_plan.wav_path).expect("wav sink");
        let error = cancelled_run_disposition(audio, Some(&wav_plan));
        assert_eq!(error.exit_code(), FttsExitCode::Cancelled);
        assert!(error.to_string().contains("partial WAV kept at"), "{error}");
        assert!(error.to_string().contains("out.wav"), "{error}");

        // Compressed: encoding skipped, staging WAV named.
        let m4a_plan = OutputPlan::for_path(&scratch.join("out.m4a")).expect("m4a plan");
        assert_eq!(
            m4a_plan.format,
            OutputFormat::M4a,
            "extension selects the compressed arm"
        );
        assert!(
            m4a_plan
                .wav_path
                .to_string_lossy()
                .ends_with(".ftts-staging.wav")
        );
        let audio = AudioOutput::wav(&m4a_plan.wav_path).expect("staging sink");
        let error = cancelled_run_disposition(audio, Some(&m4a_plan));
        assert!(error.to_string().contains("encoding to"), "{error}");
        assert!(error.to_string().contains("skipped"), "{error}");
        assert!(error.to_string().contains(".ftts-staging.wav"), "{error}");

        // Raw: no artifact exists; the byte count is the receipt.
        let audio = AudioOutput::raw();
        let error = cancelled_run_disposition(audio, None);
        assert!(
            error.to_string().contains("streaming 0 raw PCM bytes"),
            "{error}"
        );

        // A zero-packet WAV run still leaves a parseable (header-only) file behind.
        let empty_plan = OutputPlan::for_path(&scratch.join("empty.wav")).expect("plan");
        let audio = AudioOutput::wav(&empty_plan.wav_path).expect("sink");
        let _ = cancelled_run_disposition(audio, Some(&empty_plan));
        let header = std::fs::read(&empty_plan.final_path).expect("finalized wav");
        assert!(header.len() >= 44, "RIFF header present: {}", header.len());
        assert_eq!(&header[..4], b"RIFF", "must be a parseable RIFF file");
    }

    #[test]
    fn voice_inspect_renders_a_real_pack_through_dispatch() {
        let dir = std::env::temp_dir().join(format!(
            "ftts-inspect-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .expect("clock")
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).expect("temp dir");
        let embedding: Vec<f32> = (0..1024).map(|i| i as f32 * 0.001).collect();
        let pack = ftts_artifacts::voice::VoicePack {
            profile: ftts_artifacts::voice::VoiceProfile::Portable,
            consent: ftts_artifacts::voice::ConsentAttestation {
                attested: true,
                method: ftts_artifacts::voice::ConsentMethod::Flag,
            },
            language: Some("en".to_owned()),
            transcript: Some("Please call Stella.".to_owned()),
            speech_regions: vec![(0, 24_000)],
            diagnostics: None,
            preprocessing: None,
            provenance: Default::default(),
            embedding,
            codec_codes: Some(vec![7, 9]),
            reference_audio: None,
            section_digests: Default::default(),
        };
        let bytes = ftts_artifacts::voice::serialize_voice_pack(&pack).expect("serialize pack");
        let path = dir.join("inspect.ftvoice");
        std::fs::write(&path, &bytes).expect("write pack");

        let cli = Cli::parse_from([
            "ftts",
            "voice",
            "inspect",
            path.to_str().expect("utf-8 path"),
        ]);
        let mut stdout: Vec<u8> = Vec::new();
        let mut stderr: Vec<u8> = Vec::new();
        let mut stdin: &[u8] = &[];
        dispatch(
            cli,
            environment(),
            &mut stdin,
            &mut stdout,
            &mut stderr,
            IoCapabilities::default(),
        )
        .expect("inspect succeeds");
        let text = String::from_utf8(stdout).expect("utf-8 output");
        let event_line = text.lines().last().expect("at least one output line");
        let event: serde_json::Value = serde_json::from_str(event_line).expect("json event");
        assert_eq!(event["event"], "voice_inspect");
        assert_eq!(event["status"], "ok");
        assert_eq!(event["profile"], "portable");
        assert_eq!(event["consent_attested"], true);
        assert_eq!(event["consent_method"], "flag");
        assert_eq!(event["transcript_present"], true);
        assert_eq!(event["codec_codes_present"], true);
        assert_eq!(event["reference_audio_present"], false);
        assert!(
            event["recipe_hash"].as_str().is_some_and(|h| h.len() == 64),
            "recipe hash must be a sha256 hex digest"
        );
    }

    #[test]
    fn voice_inspect_reports_legacy_speaker_vectors() {
        let dir = std::env::temp_dir().join(format!("ftts-inspect-spk-{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("temp dir");
        let path = dir.join("legacy.spk");
        let vector: Vec<u8> = (0..synth::SPEAKER_VECTOR_BYTES)
            .map(|i| (i % 251) as u8)
            .collect();
        // A finite f32 vector, not arbitrary noise: encode like the enrollment writer.
        let mut bytes = Vec::with_capacity(synth::SPEAKER_VECTOR_BYTES);
        for i in 0..1024usize {
            bytes.extend_from_slice(&(i as f32 * 0.001).to_le_bytes());
        }
        drop(vector);
        std::fs::write(&path, &bytes).expect("write vector");

        let cli = Cli::parse_from([
            "ftts",
            "voice",
            "inspect",
            path.to_str().expect("utf-8 path"),
        ]);
        let mut stdout: Vec<u8> = Vec::new();
        let mut stderr: Vec<u8> = Vec::new();
        let mut stdin: &[u8] = &[];
        dispatch(
            cli,
            environment(),
            &mut stdin,
            &mut stdout,
            &mut stderr,
            IoCapabilities::default(),
        )
        .expect("inspect of a legacy vector still succeeds");
        let text = String::from_utf8(stdout).expect("utf-8 output");
        let event: serde_json::Value =
            serde_json::from_str(text.lines().last().expect("line")).expect("json");
        assert_eq!(event["status"], "legacy_speaker_vector");
    }

    #[test]
    fn enroll_mode_resolution_follows_the_documented_policy() {
        use EnrollMode::*;
        // QUALITY demands a transcript; without one it refuses to pretend.
        assert_eq!(
            resolve_enroll_mode(Quality, Some("Please call Stella.")),
            ResolvedEnrollMode::Quality
        );
        let missing = resolve_enroll_mode(Quality, None);
        assert!(matches!(missing, ResolvedEnrollMode::Quick { .. }));
        // Blank transcripts are not transcripts.
        assert!(matches!(
            resolve_enroll_mode(Auto, Some("   ")),
            ResolvedEnrollMode::Quick { .. }
        ));
        // AUTO degrades loudly; explicit QUICK never upgrades silently.
        assert!(matches!(
            resolve_enroll_mode(Auto, None),
            ResolvedEnrollMode::Quick { .. }
        ));
        assert!(matches!(
            resolve_enroll_mode(Quick, Some("words")),
            ResolvedEnrollMode::Quick { .. }
        ));
        assert_eq!(
            resolve_enroll_mode(Quality, Some("Please call Stella.")),
            ResolvedEnrollMode::Quality
        );
    }

    #[test]
    fn unusable_references_name_their_reason() {
        let silent = crate::diagnostics::AudioDiagnostics {
            clipping_fraction: 0.0,
            longest_clip_run: 0,
            intersample_overshoot_db: 0.0,
            snr_estimate_db: None,
            pause_floor_dbfs: -120.0,
            reverb_time_s: None,
            music_bed_likelihood: 0.0,
            stationarity_drift: 0.0,
            loudness_rms_dbfs: -120.0,
            voice_activity_ratio: 0.0,
        };
        let reason = unusable_reference_reason(&silent, 48_000).expect("silent is unusable");
        assert!(reason.contains("no speech"), "{reason}");
        assert!(unusable_reference_reason(&silent, 0).is_some());
        let healthy = crate::diagnostics::AudioDiagnostics {
            voice_activity_ratio: 0.8,
            ..silent
        };
        assert!(unusable_reference_reason(&healthy, 48_000).is_none());
    }

    #[test]
    fn quick_pack_roundtrips_and_quality_pack_carries_identity() {
        let embedding: Vec<f32> = (0..1024).map(|i| i as f32 * 0.001).collect();
        let dx = ftts_artifacts::voice::EnrollmentDiagnostics {
            clipping_fraction: 0.0,
            longest_clip_run: 0,
            intersample_overshoot_db: 0.2,
            snr_estimate_db: Some(30.0),
            pause_floor_dbfs: -55.0,
            reverb_time_s: Some(0.3),
            music_bed_likelihood: 0.01,
            stationarity_drift: 0.1,
            loudness_rms_dbfs: -20.0,
            voice_activity_ratio: 0.9,
        };
        let quick = assemble_enrollment_pack(AssemblePackInput {
            profile: ftts_artifacts::voice::VoiceProfile::Private,
            consent: ftts_artifacts::voice::ConsentAttestation {
                attested: true,
                method: ftts_artifacts::voice::ConsentMethod::Flag,
            },
            transcript: None,
            speech_regions: vec![(0, 24_000)],
            diagnostics: dx.clone(),
            preprocessing: ftts_artifacts::voice::PreprocessingRecipe {
                target_sample_rate_hz: 24_000,
                resampler: "lanczos6".to_owned(),
                denoise: None,
                dereverb: None,
            },
            provenance: Default::default(),
            embedding: embedding.clone(),
            codec_codes: None,
        });
        assert_eq!(quick.profile.as_str(), "private");
        let parsed = parse_pack_ok(&quick);
        assert!(parsed.transcript.is_none());

        let quality = assemble_enrollment_pack(AssemblePackInput {
            profile: ftts_artifacts::voice::VoiceProfile::Portable,
            transcript: Some("Please call Stella.".to_owned()),
            codec_codes: Some(vec![3, 1, 4]),
            ..AssemblePackInput {
                profile: quick.profile,
                consent: quick.consent,
                transcript: None,
                speech_regions: quick.speech_regions.clone(),
                diagnostics: dx,
                preprocessing: quick.preprocessing.clone().unwrap(),
                provenance: Default::default(),
                embedding,
                codec_codes: None,
            }
        });
        let parsed_q = parse_pack_ok(&quality);
        assert_eq!(parsed_q.transcript.as_deref(), Some("Please call Stella."));
        assert_eq!(parsed_q.codec_codes.as_deref(), Some(&[3u32, 1, 4][..]));
        assert_eq!(parsed_q.profile.as_str(), "portable");
    }

    fn parse_pack_ok(pack: &ftts_artifacts::voice::VoicePack) -> ftts_artifacts::voice::VoicePack {
        let bytes = ftts_artifacts::voice::serialize_voice_pack(pack)
            .map_err(|e| e.to_string())
            .expect("serialize");
        ftts_artifacts::voice::parse_voice_pack(&bytes)
            .map_err(|e| e.to_string())
            .expect("parse")
    }

    #[test]
    fn pack_writers_stage_and_back_up_without_replacing_the_extension() {
        let dir = std::env::temp_dir().join(format!("enroll-writer-{}", std::process::id()));
        std::fs::create_dir_all(&dir).expect("dir");
        let path = dir.join("w.ftvoice");
        write_voice_pack_new(&path, b"first").expect("first write");
        let backup = replace_voice_pack(&path, b"second").expect("replace");
        assert_eq!(backup, dir.join("w.ftvoice.bak"));
        assert_eq!(std::fs::read(&backup).unwrap(), b"first");
        assert_eq!(std::fs::read(&path).unwrap(), b"second");
        // No partial staging files left behind.
        assert!(!dir.join("w.ftvoice.partial").exists());
    }

    #[test]
    fn doctor_reports_expected_json_and_human_format() {
        let environment = Environment {
            values: BTreeMap::new(),
            stage_budget_values: BTreeMap::new(),
        };

        // JSON mode
        let mut json_out = Vec::new();
        let args_json = DoctorArgs { json: true };
        run_doctor(&args_json, &environment, &mut json_out).expect("run_doctor json");
        let report: Value = serde_json::from_slice(&json_out).expect("valid json");
        assert_eq!(report["schema_version"], ROBOT_SCHEMA_VERSION);
        assert_eq!(report["stateless_default"], true);
        assert_eq!(report["persistent_history"], false);

        // Human mode
        let mut text_out = Vec::new();
        let args_text = DoctorArgs { json: false };
        run_doctor(&args_text, &environment, &mut text_out).expect("run_doctor text");
        let text_str = String::from_utf8(text_out).expect("valid utf8");
        assert!(text_str.contains("FrankenTTS ftts — local readiness"));
        assert!(text_str.contains("stateless default: yes"));
    }
}