youtube-legend-cli 0.4.0

//! Top-level command dispatch: extract one URL or batch many.

use crate::cli::{Cli, ProviderChoice};
use crate::error::{AppError, AppResult};
use crate::parse::video_id::extract_video_id;
use crate::provider::{Format, ProviderAttempt, ProviderChain, SubtitleInfo};
use crate::text::normalize_nfc;
use serde::Serialize;
use std::process::ExitCode;

pub mod batch;
pub mod config_cmd;
pub mod extract;
pub mod gen;
pub mod schema;

/// Where the target this run acted on came from.
///
/// The envelope carries this verbatim so a caller never has to infer,
/// from the shape of its own invocation, which of several possible
/// inputs the parser actually chose.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum TargetSource {
    /// A positional argument on the command line.
    Argv,
    /// A single line read from stdin.
    Stdin,
    /// One line of the batch stream read from stdin.
    BatchFile,
}

impl TargetSource {
    /// Stable wire spelling emitted in the envelope.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Argv => "argv",
            Self::Stdin => "stdin",
            Self::BatchFile => "batch-file",
        }
    }
}

/// The target this run acted on, and where it came from.
#[derive(Debug, Clone)]
pub struct ResolvedTarget {
    /// The target actually used.
    pub value: String,
    /// Which input supplied it.
    pub source: TargetSource,
}

#[derive(Debug, Serialize)]
struct JsonSuccess {
    /// Provider name that delivered the transcript: `provider-decopy`,
    /// `provider-noiz`, or `cache` for cache hits.
    ///
    /// This named `provider-noteey` until 2026-09-04, a provider removed
    /// with the browser subsystem. The two live names are the
    /// `PROVIDER_NAME` constants of the surviving providers, so read
    /// those before editing this list again.
    provider: &'static str,
    video_id: String,
    /// The target this run acted on, verbatim.
    target_resolved: String,
    /// Which input supplied the target: `argv`, `stdin` or `batch-file`.
    target_source: &'static str,
    /// The language that was REQUESTED, echoed back verbatim. It is an
    /// input, never an observation.
    language: String,
    /// GAP-2026-158: the language of the track the upstream actually
    /// delivered, present only when the upstream named it. ABSENCE
    /// means "we do not know which track came back", and NEVER "the
    /// requested track came back": today only `getsubs` reads a track
    /// identity off the upstream, so every other provider omits the
    /// field rather than repeating `language` under a second name.
    #[serde(skip_serializing_if = "Option::is_none")]
    delivered_language: Option<String>,
    format: String,
    content: String,
    /// GAP-AUD-2026-050: renamed from `bytes` to `byte_size` to match
    /// the contract documented in `docs/AGENTS.pt-BR.md`.
    byte_size: u64,
    duration_ms: u64,
    /// GAP-AUD-2026-050: renamed from `source` to `source_url` to
    /// match the contract documented in `docs/AGENTS.pt-BR.md`.
    source_url: String,
}

#[derive(Debug, Serialize)]
struct JsonError {
    error: bool,
    code: u8,
    /// Human-readable description, localised by `--ui-lang`. Never parse
    /// this field: it changes with the interface language. Branch on
    /// `kind` instead.
    message: String,
    /// Stable machine-readable failure identifier, always English. This
    /// is the field an automated caller branches on, and it is what
    /// finally lets "this video has no captions" be told apart from
    /// "the provider is down" without reading stderr.
    kind: &'static str,
    /// Whether retrying the same invocation later may succeed. `false`
    /// means the failure is definitive and a retry only burns time.
    retryable: bool,
    /// Upstream-declared delay before a retry is worth attempting.
    /// Omitted rather than emitted as `null` when the upstream said
    /// nothing, so a consumer can distinguish "no advice" from "wait 0".
    #[serde(skip_serializing_if = "Option::is_none")]
    retry_after_ms: Option<u64>,
    /// Provider that produced the decisive failure, when the error
    /// names one. [`AppError::CaptchaChallenge`],
    /// [`AppError::ProviderUnavailable`] and [`AppError::RateLimited`]
    /// carry a provider, so this stays absent only for failures that
    /// happened before any provider was reached, rather than naming a
    /// provider we did not observe.
    #[serde(skip_serializing_if = "Option::is_none")]
    provider: Option<&'static str>,
    /// `YouTube` video id the run acted on. Absent when the failure
    /// happened before the id could be extracted.
    #[serde(skip_serializing_if = "Option::is_none")]
    video_id: Option<String>,
    /// The target this run acted on, verbatim. Absent when the failure
    /// happened before a target was resolved at all.
    #[serde(skip_serializing_if = "Option::is_none")]
    target_resolved: Option<String>,
    /// Which input supplied the target: `argv`, `stdin` or `batch-file`.
    #[serde(skip_serializing_if = "Option::is_none")]
    target_source: Option<&'static str>,
    /// The BCP 47 tag the caller asked for. Always known once the
    /// command line parsed, which is what lets a `language_unavailable`
    /// failure be read without re-deriving the request.
    #[serde(skip_serializing_if = "Option::is_none")]
    requested_language: Option<&'static str>,
    /// BCP 47 tags the video actually publishes, as classified by the
    /// watch-page probe in [`crate::parse::player_response`]. Present
    /// only on a language miss, which is the one failure where the
    /// caller can act on it: it names the tags a second run could ask
    /// for, without a second round trip to discover them.
    #[serde(skip_serializing_if = "Option::is_none")]
    available_languages: Option<Vec<String>>,
    /// Verbatim explanation produced by the upstream provider, in the
    /// provider's own words. Present when a provider explained its
    /// refusal; absent rather than empty when none did.
    #[serde(skip_serializing_if = "Option::is_none")]
    diagnostic: Option<String>,
    /// One entry per provider the chain considered, in visit order.
    /// Empty for a failure that happened before any chain walk, and the
    /// field is then omitted rather than emitted as `[]`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    attempts: Vec<ProviderAttempt>,
}

/// GAP-E2E-009: dry-run envelope. Emitted to stdout under `--dry-run`
/// so operators can distinguish cache-miss-dry-run (would fetch)
/// from cache-hit-dry-run (would skip) by parsing the `event` field,
/// instead of branching on the legacy `exit 66` signal that the
/// previous implementation produced.
#[derive(Debug, Serialize)]
struct JsonDryRun {
    event: &'static str,
    video_id: String,
    /// The target this run acted on, verbatim.
    target_resolved: String,
    /// Which input supplied the target: `argv`, `stdin` or `batch-file`.
    target_source: &'static str,
    language: String,
    format: String,
    /// `true` when the cache missed and a real run would have gone to
    /// the network; `false` when the cache already holds the answer.
    would_fetch: bool,
}

/// Dispatch a validated [`Cli`] to the single-URL or batch runner.
///
/// # Errors
///
/// - [`AppError::InvalidUsage`] when the [`Cli::validate`] check fails.
/// - All provider / network / cache / IO errors bubble up.
#[tracing::instrument(level = "debug", err, skip(cli), fields(batch = cli.batch, url = ?cli.url, json = cli.json, verbose = cli.verbose, provider = ?cli.provider))]
pub async fn run(cli: Cli) -> AppResult<ExitCode> {
    // Pin the interface locale before anything can produce output.
    // `cli.ui_lang` already carries the `--ui-lang` flag merged with the
    // `ui_lang` config key (CLI wins), so this single call implements
    // the whole precedence chain; passing `None` leaves the system
    // locale to be resolved lazily. On Windows this is also what
    // switches the console to UTF-8.
    crate::i18n::init(cli.effective_ui_language());

    // Publish the flags that a provider reads through the tuning
    // registry. `cli.offline` and `cli.jobs` already carry the merge of
    // command line over config file, so installing them here is what
    // makes the documented precedence observable from code that never
    // sees the parsed `Cli`.
    let mut effective = toml::Table::new();
    effective.insert("offline".to_string(), toml::Value::Boolean(cli.offline));
    // `--jobs 0` means "derive from the host", which is the absence of
    // a value rather than the value zero; publishing the zero would
    // only trip the range check.
    if cli.jobs > 0 {
        if let Ok(jobs) = i64::try_from(cli.jobs) {
            effective.insert("jobs".to_string(), toml::Value::Integer(jobs));
        }
    }
    // The providers build their own HTTP clients and never see `cli`,
    // so the merged User-Agent travels through the same channel.
    effective.insert(
        "user_agent".to_string(),
        toml::Value::String(cli.effective_user_agent()),
    );
    // Consent for host-touching actions travels the same way. The
    // installer in `provider::stealth` runs far from any `Cli`, and the
    // environment is not an option here, so the answer to "may I install
    // a package" has to arrive as configuration.
    effective.insert("yes".to_string(), toml::Value::Boolean(cli.yes));
    effective.insert("no_input".to_string(), toml::Value::Boolean(cli.no_input));
    crate::config::install_flag_overrides(effective);

    // Surfaces that answer from the binary itself, before any argument
    // that only makes sense for an extraction is validated.
    if cli.print_schema {
        return schema::print_schema().await;
    }
    // Completions and the manual page derive from the command tree, so
    // they answer before any extraction argument is validated: asking
    // for a completion script must never depend on a valid URL.
    match &cli.command {
        Some(crate::cli::Command::Completions { shell }) => {
            return gen::run_completions(*shell).await;
        }
        Some(crate::cli::Command::Man) => {
            return gen::run_man().await;
        }
        _ => {}
    }
    if let Some(crate::cli::Command::Config { action }) = &cli.command {
        return match config_cmd::run(&cli, action).await {
            Ok(code) => Ok(code),
            Err(e) => {
                output_error(&cli, &e, None, None).await.ok();
                eprintln!("{e}");
                Ok(ExitCode::from(e.exit_code()))
            }
        };
    }

    // GAP-AUD-2026-060: intercept validation errors so `output_error`
    // can emit the JSON envelope to stdout when `--json` is active.
    // The previous bare `?` propagated to `main.rs` which only logged
    // to stderr, leaving stdout empty for programmatic consumers.
    if let Err(e) = cli.validate() {
        output_error(&cli, &e, None, None).await.ok();
        // Without `--json` there is no envelope, so the operator would
        // otherwise get a bare non-zero exit and no explanation at all.
        // stdout stays reserved for the payload; the diagnosis goes to
        // stderr.
        if !cli.json {
            eprintln!("{e}");
        }
        return Ok(ExitCode::from(e.exit_code()));
    }

    let chain = build_provider_chain(&cli);

    if cli.batch {
        batch::run(&cli, &chain).await
    } else {
        extract::run(&cli, &chain).await
    }
}

/// Build the [`ProviderChain`] for a given [`Cli`].
///
/// Under `auto` the chain holds every provider in cost-ascending
/// order: decopy, then noiz. Those are the only two that exist.
///
/// This sentence read `noteey, decopy, noiz` and pointed at
/// `providers.getsubs.enabled_in_auto` until 2026-09-04, naming two
/// providers the tree had already removed and a key the registry
/// never prints. The `//` comment inside the function body below
/// recorded the removal correctly on the same day, so the truth sat
/// twelve lines under the falsehood and neither was reconciled with
/// the other. A doc comment ships to docs.rs and an inline comment
/// does not, so the one that travelled was the wrong one.
///
/// Pinning a single provider
/// with `--provider` yields a chain of one, which is what you want
/// when diagnosing which upstream is degraded — a full chain masks
/// one provider's failure behind the next one's success.
#[tracing::instrument(level = "debug", skip(cli), fields(provider = ?cli.provider))]
fn build_provider_chain(cli: &Cli) -> ProviderChain {
    let mut providers: Vec<Box<dyn crate::provider::Provider>> = Vec::new();

    // The selection decides what is pushed. `--provider` used to be
    // read into `let _choice` and discarded, which made the flag inert;
    // it now drives this match.
    //
    // The `Auto` order is cost-ascending, not alphabetical. Decopy leads
    // and noiz closes, because both enforce a small daily quota and answer
    // `429` once it is spent.
    //
    // The chain used to open with two browser-driven providers, getsubs and
    // noteey. Both were removed on 2026-09-04 after being measured broken at
    // the source: getsubs.cc serves its own checkbox challenge in place of
    // the track list, and noteey's API answers `[]` in two bytes for every
    // route, including one invented for the test. Neither is a transient
    // outage a retry could clear.
    let selection = cli.provider.unwrap_or(ProviderChoice::Auto);
    let lang = language_to_str(cli.lang);
    let _ = lang;

    let use_decopy = matches!(
        selection,
        ProviderChoice::Auto | ProviderChoice::ProviderDecopy
    );
    let use_noiz = matches!(
        selection,
        ProviderChoice::Auto | ProviderChoice::ProviderNoiz
    );

    if use_decopy {
        providers.push(Box::new(crate::provider::ProviderDecopy::new()));
    }
    if use_noiz {
        providers.push(Box::new(crate::provider::ProviderNoiz::new()));
    }

    ProviderChain::new(providers)
}

/// Translate a CLI [`crate::cli::FormatArg`] into the provider-layer [`Format`].
///
/// `Vtt` asks for the same `SubRip` body `Srt` does: `WebVTT` is a
/// re-framing of it, not a separate delivery format, so no provider has
/// to learn about it and the two share one cache entry.
pub fn format_to_provider_format(arg: crate::cli::FormatArg) -> Format {
    match arg {
        crate::cli::FormatArg::Txt => Format::Txt,
        crate::cli::FormatArg::Srt | crate::cli::FormatArg::Vtt => Format::Srt,
    }
}

/// Canonical BCP 47 tag consumed by the provider layer, the cache key,
/// and the `--json` envelope.
///
/// The whole tag survives, region and script included: `pt-BR` reaches
/// the provider as `pt-BR`, not as `pt`. Providers that must speak
/// `YouTube`'s legacy ISO codes call
/// [`crate::cli::LanguageArg::youtube_code`] instead.
pub fn language_to_str(arg: crate::cli::LanguageArg) -> &'static str {
    arg.as_str()
}

/// Convert raw subtitle bytes into the user-requested text form.
///
/// The requested form is the CLI's [`crate::cli::FormatArg`] and not the
/// provider-layer [`Format`]: `vtt` and `srt` ask the provider for the
/// same `SubRip` body, so the distinction only exists on this side and
/// taking `Format` here is what made `vtt` unrepresentable.
///
/// # Errors
///
/// - [`AppError::Internal`] when the bytes are not valid UTF-8.
/// - [`AppError::InvalidInput`] / [`AppError::SubtitleTooLarge`] when
///   the SRT body is malformed or exceeds the 50 MiB cap.
/// - [`AppError::InvalidUsage`] when `--format srt` or `--format vtt` is
///   requested but the body is a noteey transcript (no SRT framing
///   available).
pub fn convert_format(
    content: &[u8],
    format: crate::cli::FormatArg,
    format_hint: crate::provider::SubtitleFormat,
) -> AppResult<String> {
    use crate::cli::FormatArg;
    use crate::provider::SubtitleFormat;
    match (format, format_hint) {
        // SRT requested and the body is real SubRip — pass through.
        (FormatArg::Srt, SubtitleFormat::Srt) => srt_body(content),
        // WebVTT requested and the body is real SubRip — re-frame it.
        (FormatArg::Vtt, SubtitleFormat::Srt) => Ok(srt_to_vtt(&srt_body(content)?)),
        // Txt requested and the body is SRT — convert via srt_to_text.
        (FormatArg::Txt, SubtitleFormat::Srt) => crate::parse::srt_to_text(&srt_body(content)?),
        // Txt requested and the body is a plain transcript.
        //
        // No provider produces this shape any more: the one that did was
        // removed on 2026-09-04. These two arms survive for the CACHE,
        // which may hold bodies written under the old provider and whose
        // `.hint` files name this format. Dropping the variant would not
        // free the operator of those files, it would only make them
        // unreadable, and deleting somebody's cache to tidy an enum is
        // not a trade this code gets to make.
        (FormatArg::Txt, SubtitleFormat::NoteeyTranscript) => {
            let raw = String::from_utf8(content.to_vec()).map_err(|e| {
                AppError::Internal(format!("cached transcript body not valid utf-8: {e}"))
            })?;
            crate::parse::noteey_to_text(&raw)
        }
        // Timed output requested but the body is a plain transcript —
        // reject rather than fabricate SubRip timestamps, because the
        // shape carries no end-of-cue information and WebVTT needs the
        // same information SubRip does.
        (FormatArg::Srt | FormatArg::Vtt, SubtitleFormat::NoteeyTranscript) => {
            Err(AppError::InvalidUsage(format!(
                "--format {} is not available for this cached body: it is a plain \
                 transcript with no cue framing; use --format txt (default), or \
                 re-fetch with --no-cache to get a timed body from a live provider",
                format_to_str(format)
            )))
        }
    }
}

/// Decode a `SubRip` body, naming the format in the failure so the
/// operator does not have to guess which of the two bodies was bad.
fn srt_body(content: &[u8]) -> AppResult<String> {
    String::from_utf8(content.to_vec())
        .map_err(|e| AppError::Internal(format!("srt is not valid utf-8: {e}")))
}

/// `true` when the line is a bare `SubRip` cue index.
fn is_cue_index(line: &str) -> bool {
    let trimmed = line.trim();
    !trimmed.is_empty() && trimmed.bytes().all(|b| b.is_ascii_digit())
}

/// `true` when the line carries a cue's timing arrow.
fn is_cue_timing(line: &str) -> bool {
    line.contains("-->")
}

/// Re-frame a `SubRip` body as `WebVTT`.
///
/// The two carry the same timings; `WebVTT` differs by a `WEBVTT`
/// signature line, by a dot instead of a comma before the milliseconds,
/// and by not requiring the numeric cue index. Reusing the body the
/// provider already delivered is what keeps the two outputs from
/// drifting: there is no second parse to disagree with the first.
#[must_use]
pub fn srt_to_vtt(srt: &str) -> String {
    // The signature plus one dot per comma; the body itself is copied
    // once.
    let mut out = String::with_capacity(srt.len() + 8);
    out.push_str("WEBVTT\n\n");
    let mut lines = srt.lines().peekable();
    while let Some(line) = lines.next() {
        // An index is dropped only when a timing line follows it. A bare
        // number that is actually a cue's text has no arrow after it and
        // must survive.
        if is_cue_index(line) && lines.peek().is_some_and(|next| is_cue_timing(next)) {
            continue;
        }
        if is_cue_timing(line) {
            out.push_str(&line.replace(',', "."));
        } else {
            out.push_str(line);
        }
        out.push('\n');
    }
    out
}

/// The `delivered_language` field of the success envelope, and the only
/// currency the envelope accepts for it.
///
/// GAP-2026-172, closing the half that a test could not close. The field
/// used to travel as a bare `Option<String>`, so every one of the four
/// call sites was free to fill it from [`SubtitleInfo::language`] — an
/// echo of the request for most providers — and only an ACCIDENTAL
/// dead-code warning stood in the way. That warning protected nothing:
/// MEASURED on 2026-09-04, `commands::batch` already made the same
/// choice inline at its own site and never went through the extracted
/// helper at all, which is exactly the second production caller the gap
/// predicted would switch the warning off.
///
/// There are two honest answers and this type offers exactly those two,
/// with no constructor that takes a language from anywhere else. Writing
/// the request back into this field is now a compile error rather than a
/// review finding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeliveredLanguage(Option<String>);

impl DeliveredLanguage {
    /// Nothing observed the delivered track.
    ///
    /// This is the cache's answer: the cache stores the body and the
    /// format hint and never stored a track identity, so a hit cannot
    /// know. Absence means unknown, and NEVER "as requested".
    #[must_use]
    pub fn unknown() -> Self {
        Self(None)
    }

    /// Read the observation out of a completed fetch.
    ///
    /// [`SubtitleInfo::delivered_language`] is the only field a provider
    /// may set from a track the upstream itself named, which is why it
    /// is the only field this reads. Taking the whole `info` rather than
    /// a pre-picked string is the point: the choice happens here, inside
    /// the type, instead of at four call sites that could each pick
    /// differently.
    #[must_use]
    pub fn observed(info: &SubtitleInfo) -> Self {
        Self(info.delivered_language.clone())
    }

    /// Borrow the tag for serialisation.
    #[must_use]
    pub fn as_deref(&self) -> Option<&str> {
        self.0.as_deref()
    }
}

/// Write the success envelope to stdout (text or JSON depending on
/// `--json`).
///
/// # Errors
///
/// - [`AppError::Serde`] when serialising the JSON envelope.
/// - [`AppError::Io`] on stdout write failure.
///
/// # Envelope shape
///
/// JSON envelope fields (GAP-AUD-2026-050):
/// - `provider` — which provider delivered: `provider-decopy`,
///   `provider-noiz`, or `cache` for cache hits. The `attempts`
///   ledger may additionally carry `watch-page`, which is the probe
///   that names the real cause and is never a delivering provider.
///   This list named FIVE providers until 2026-09-04 and all five had
///   already been removed from the tree: `provider-noteey`,
///   `provider-headless`, `youtube-direct`, `provider-a` and
///   `provider-b`.
/// - `video_id`, `language`, `format` — request inputs. `language` is
///   what the caller ASKED for and is never an observation.
/// - `delivered_language` — GAP-2026-158: the track the upstream really
///   delivered, passed in by the caller and OMITTED when no provider
///   named it. Its absence means "unknown", never "as requested".
/// - `content` — the cleaned transcript text (utf-8 NFC).
/// - `byte_size` — length of cleaned `content` in bytes (post-parse, post-NFC).
/// - `duration_ms` — wall-clock time for the fetch (or cache lookup).
/// - `source_url` — a synthetic locator for the body, NOT a URL any
///   client can fetch. `decopy` emits `decopy://{video_id}/und/srt`
///   and `noiz` emits `noiz://{video_id}/{tag}/srt`, while a cache hit
///   emits the literal `cache`. Both providers answer a single POST
///   and never hand back a retrievable address, so the field names
///   the origin rather than locating it.
///
///   This read `the upstream URL that returned the raw body
///   (noteey-prefixed for noteey, youtube timedtext for direct, etc)`
///   until 2026-09-04, which was wrong twice over: it named two
///   removed providers, and it called the value a URL when no live
///   provider ever produced a fetchable one.
#[allow(clippy::too_many_arguments)]
pub async fn output_success(
    cli: &Cli,
    provider: &'static str,
    video_id: &str,
    target: &ResolvedTarget,
    content: &str,
    source_url: &str,
    duration_ms: u64,
    delivered_language: &DeliveredLanguage,
) -> AppResult<()> {
    let nfc = normalize_nfc(content);
    if cli.json {
        let payload = success_payload(
            cli,
            provider,
            video_id,
            target,
            nfc,
            source_url,
            duration_ms,
            delivered_language.as_deref(),
        );
        emit_envelope(cli, &payload).await?;
    } else {
        crate::io::write_subtitle_to_stdout(nfc.as_bytes()).await?;
    }
    Ok(())
}

/// Build the success envelope.
///
/// Split out of [`output_success`] so the payload can be inspected
/// without writing to stdout — which is what lets the regression gate
/// below assert that `language` and `delivered_language` come from two
/// different sources instead of from the same one twice.
#[allow(clippy::too_many_arguments)]
fn success_payload(
    cli: &Cli,
    provider: &'static str,
    video_id: &str,
    target: &ResolvedTarget,
    nfc: String,
    source_url: &str,
    duration_ms: u64,
    delivered_language: Option<&str>,
) -> JsonSuccess {
    JsonSuccess {
        provider,
        video_id: video_id.to_string(),
        target_resolved: target.value.clone(),
        target_source: target.source.as_str(),
        // The REQUEST. `cli.lang` is the only legitimate source here.
        language: language_to_str(cli.lang).to_string(),
        // GAP-2026-158: the DELIVERY, and it comes from the caller's
        // observation of the upstream, never from `cli.lang`. Wiring
        // `cli.lang` into this line would restore the defect the field
        // exists to end.
        delivered_language: delivered_language.map(str::to_string),
        format: format_to_str(cli.format).to_string(),
        // GAP-AUD-2026-065: byte_size reflects the final NFC content.
        byte_size: nfc.len() as u64,
        content: nfc,
        duration_ms,
        source_url: source_url.to_string(),
    }
}

/// Serialise `payload`, run the agent-native reduction over it, and
/// write one line to stdout.
///
/// The reduction operates on the [`serde_json::Value`] and not on the
/// rendered text: elements the caller asked to drop never reach a string
/// buffer, which is the whole point of doing the cut in-process instead
/// of piping the envelope through an external JSON processor.
///
/// # Errors
///
/// - [`AppError::Serde`] when the payload cannot be serialised.
/// - [`AppError::InvalidUsage`] when a `--filter` expression is
///   malformed.
/// - [`AppError::Io`] on stdout write failure.
async fn emit_envelope<T: Serialize>(cli: &Cli, payload: &T) -> AppResult<()> {
    let options = cli.surface_options()?;
    let mut json = if options.is_active() {
        let value = serde_json::to_value(payload).map_err(AppError::Serde)?;
        let (reduced, _) = options.apply(value);
        serde_json::to_string(&reduced).map_err(AppError::Serde)?
    } else {
        serde_json::to_string(payload).map_err(AppError::Serde)?
    };
    json.push('\n');
    crate::io::write_subtitle_to_stdout(json.as_bytes()).await
}

/// `true` when the error names a provider the health ledger has
/// measured as broken for a sustained stretch.
///
/// Only the variants that carry a provider name can be answered at
/// all; everything else returns `false` and is left alone, because
/// guessing a provider here would be the silent nullification this
/// envelope has already been fixed for twice.
fn provider_is_persistently_broken(err: &AppError) -> bool {
    let provider = match err {
        AppError::CaptchaChallenge { provider, .. }
        | AppError::ProviderUnavailable { provider }
        | AppError::RateLimited { provider, .. }
        | AppError::ProviderProtocolError { provider, .. } => *provider,
        _ => return false,
    };
    crate::provider::health::is_persistently_broken(provider)
}

/// Best-effort write of the error envelope to stdout when `--json` is
/// set. Errors here are intentionally swallowed: the user already sees
/// the error via the `tracing` / `Termination` path.
///
/// `target` and `video_id` are what the caller already knows about the
/// subject of the failed run. Both are optional because a failure can
/// happen before either exists: a rejected flag has no target, and a
/// URL whose id could not be extracted has a target but no id. Passing
/// what is known is what lets one line of a batch stream be traced back
/// to the input line that produced it.
///
/// The envelope goes to stdout, which is what
/// `docs/schemas/error-envelope.schema.json` publishes as its contract:
/// "Emitted on stdout when --json is set and the run failed". Reserving
/// stdout for the payload costs nothing here, because a failed run has
/// no payload to collide with — measured on 2026-09-04, stdout carried
/// exactly 0 bytes on both failures of a live e2e run while the whole
/// envelope went to stderr, so a consumer reading stdout under `--json`
/// received nothing at all and had no way to learn why.
///
/// # Errors
///
/// Returns [`AppError::Io`], [`AppError::Serde`], or
/// [`AppError::Internal`] when the envelope cannot be serialised or
/// written. The error path itself is best-effort: callers should not
/// treat a return value from this function as fatal because the
/// original error has already been emitted via the regular
/// `Termination` flow.
pub async fn output_error(
    cli: &Cli,
    err: &AppError,
    target: Option<&ResolvedTarget>,
    video_id: Option<&str>,
) -> AppResult<()> {
    output_error_traced(cli, err, target, video_id, &[]).await
}

/// [`output_error`] plus the per-provider ledger the chain produced.
///
/// Only the two call sites that actually walked a chain can supply one;
/// every other failure happens before any provider is reached and
/// passes an empty slice rather than inventing attempts.
///
/// # Errors
///
/// Same as [`output_error`].
pub async fn output_error_traced(
    cli: &Cli,
    err: &AppError,
    target: Option<&ResolvedTarget>,
    video_id: Option<&str>,
    attempts: &[ProviderAttempt],
) -> AppResult<()> {
    if cli.json {
        let payload = error_envelope(cli, err, target, video_id, attempts);
        if let Ok(mut json) = serde_json::to_string(&payload) {
            json.push('\n');
            let _ = crate::io::write_subtitle_to_stdout(json.as_bytes()).await;
        }
    }
    Ok(())
}

/// Build the error envelope without writing it.
///
/// Split out so the schema conformance test can serialise exactly what
/// the binary emits, instead of asserting against a hand-built copy
/// that could drift from it.
fn error_envelope(
    cli: &Cli,
    err: &AppError,
    target: Option<&ResolvedTarget>,
    video_id: Option<&str>,
    attempts: &[ProviderAttempt],
) -> JsonError {
    JsonError {
        error: true,
        code: err.exit_code(),
        message: err.to_string(),
        kind: err.kind(),
        // `AppError::retryable` classifies by TYPE, which is right over
        // the population of future occurrences and wrong for an
        // upstream measured broken for months: it keeps telling the
        // caller to try again, and the most expensive provider in the
        // chain is the one that keeps saying it. The ledger supplies
        // the one thing the type cannot carry, which is TIME, so the
        // override narrows `true` to `false` and never the reverse — a
        // definitive failure never becomes retryable because of
        // bookkeeping.
        // The second narrowing, and it reads the invocation rather than
        // the world. Under `--offline` the refusal is issued by this
        // process to itself before a socket exists, so repeating the
        // same command line fails identically forever; the provider may
        // well be up, but its availability stopped being the variable
        // that decides the outcome. `src/retry.rs` already stopped
        // SLEEPING between attempts for this reason — this line stops
        // the envelope from telling the caller to do what the binary
        // itself no longer does.
        //
        // `cli.offline` and not `provider::is_offline()`: the flag has
        // already been merged over the config key by `config_schema!`,
        // and reading the parameter keeps this function a pure map from
        // its arguments instead of a reader of process-wide state.
        retryable: err.retryable() && !provider_is_persistently_broken(err) && !cli.offline,
        retry_after_ms: err.retry_after_ms(),
        // The error is the only place a provider name survives a
        // failure, so it is read from there rather than guessed.
        provider: match err {
            AppError::CaptchaChallenge { provider, .. }
            | AppError::ProviderUnavailable { provider }
            | AppError::RateLimited { provider, .. }
            | AppError::ProviderProtocolError { provider, .. } => Some(*provider),
            _ => None,
        },
        video_id: video_id.map(str::to_string),
        target_resolved: target.map(|t| t.value.clone()),
        target_source: target.map(|t| t.source.as_str()),
        requested_language: Some(language_to_str(cli.lang)),
        // The error is the only carrier of the track list, exactly as
        // it is the only carrier of the provider name above.
        available_languages: match err {
            AppError::LanguageUnavailable { available } => Some(available.clone()),
            // The ASR variant carries its tag list for the same reason
            // `LanguageUnavailable` carries one: the error is the only
            // thing that survives the failure knowing it. Reading only
            // the first of the two would have left a field declared and
            // never filled in exactly the envelope this project has
            // already fixed that defect in twice.
            AppError::CaptionsAsrOnly { asr_languages } => Some(asr_languages.clone()),
            _ => None,
        },
        // THE RULE: the envelope carries ONE explanation, and it is the
        // LONGEST one any attempt recorded — a provider that wrote more
        // said more. A tie goes to the LATEST attempt, which is the one
        // closest to the failure the caller is being told about.
        diagnostic: attempts
            .iter()
            .filter_map(|a| a.diagnostic.as_deref())
            .max_by_key(|d| d.chars().count())
            .map(str::to_string),
        attempts: attempts.to_vec(),
    }
}

/// GAP-E2E-009: emit the dry-run envelope to stdout. When `--json`
/// is set the payload is a single JSON object per line; without
/// `--json` we emit a human-readable line so a curl-like inspection
/// still surfaces the signal. `would_fetch` reports whether the
/// dry-run encountered a cache miss (true) or hit (false), letting
/// callers branch without parsing the `event` string.
///
/// # Errors
///
/// - [`AppError::Serde`] when serialising the JSON envelope fails.
/// - [`AppError::Io`] when writing the envelope to stdout fails.
pub async fn output_dry_run(
    cli: &Cli,
    video_id: &str,
    target: &ResolvedTarget,
    would_fetch: bool,
) -> AppResult<()> {
    if cli.json {
        let payload = JsonDryRun {
            // The event names the branch taken, so `would_fetch` and
            // `event` never disagree.
            event: if would_fetch {
                "dry_run_cache_miss"
            } else {
                "dry_run_cache_hit"
            },
            video_id: video_id.to_string(),
            target_resolved: target.value.clone(),
            target_source: target.source.as_str(),
            language: language_to_str(cli.lang).to_string(),
            format: format_to_str(cli.format).to_string(),
            would_fetch,
        };
        emit_envelope(cli, &payload).await?;
    } else if would_fetch {
        // An event, not a payload: stdout carries transcripts, so a
        // caller redirecting it must not find a status line mixed in.
        crate::io::write_to_stderr(&format!("dry_run_cache_miss {video_id}\n"))?;
    } else {
        crate::io::write_to_stderr(&format!("dry_run_cache_hit {video_id}\n"))?;
    }
    Ok(())
}

fn format_to_str(arg: crate::cli::FormatArg) -> &'static str {
    match arg {
        crate::cli::FormatArg::Txt => "txt",
        crate::cli::FormatArg::Srt => "srt",
        crate::cli::FormatArg::Vtt => "vtt",
    }
}

/// Resolve the URL to extract: the positional arg if present, else a
/// single line read from stdin.
///
/// # Errors
///
/// - [`AppError::InvalidUsage`] when `--batch` is set (the batch
///   runner reads stdin directly).
/// - All errors from [`crate::io::read_url_from_stdin`].
pub async fn extract_url_from_input(cli: &Cli) -> AppResult<ResolvedTarget> {
    // argv wins unconditionally. A URL offered on stdin can never
    // displace one typed on the command line, and the envelope reports
    // `argv` so the caller can see which one was chosen.
    if let Some(url) = &cli.url {
        return Ok(ResolvedTarget {
            value: url.clone(),
            source: TargetSource::Argv,
        });
    }
    if cli.batch {
        return Err(AppError::InvalidUsage(
            "extract cannot be called with --batch".to_string(),
        ));
    }
    let value = crate::io::read_url_from_stdin(cli.no_input).await?;
    Ok(ResolvedTarget {
        value,
        source: TargetSource::Stdin,
    })
}

/// Run `fut` under the `--timeout` wall clock.
///
/// `Cli::timeout_duration` had no call site at all: the flag parsed, was
/// validated against zero, and then decided nothing. This is its sink.
/// The deadline covers the whole fetch, retries included, which is the
/// only bound an operator can reason about from the command line.
///
/// # Errors
///
/// - [`AppError::Timeout`] when the deadline elapses first.
/// - Whatever `fut` itself returns.
///
/// # Cancel safety
///
/// Cancel-safe: dropping the returned future drops `fut` at its next
/// await point, exactly as awaiting `fut` directly would.
pub async fn with_deadline<T, F>(cli: &Cli, fut: F) -> AppResult<T>
where
    F: std::future::Future<Output = AppResult<T>>,
{
    let budget = cli.timeout_duration();
    match tokio::time::timeout(budget, fut).await {
        Ok(result) => result,
        Err(_) => Err(AppError::Timeout(format!(
            "exceeded --timeout of {}s",
            budget.as_secs()
        ))),
    }
}

/// Extract the video id from `url` and emit a verbose-mode line to
/// stderr if `--verbose` is set.
///
/// # Errors
///
/// - Any error from [`extract_video_id`].
pub fn parse_video_id_from_url(cli: &Cli, url: &str) -> AppResult<String> {
    let id = extract_video_id(url)?;
    // GAP-E2E-017: route the verbose line through `tracing` instead of
    // `io::write_to_stderr` so the `tracing-subscriber` EnvFilter built
    // in `logging.rs` (which honours `--quiet` via `EnvFilter::new("error")`)
    // actually silences it. The previous direct call bypassed the filter
    // and made the `--quiet` flag inert for this path.
    if cli.verbose && !cli.quiet {
        tracing::info!(target: "events", event = "video_id_extracted", video_id = %id);
    }
    Ok(id)
}

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

    fn cli_from<const N: usize>(args: [&str; N]) -> Cli {
        Cli::parse_from(args)
    }

    /// The displaced-token test.
    ///
    /// With stdin offering one URL and argv carrying another, the parser
    /// must resolve the argv one and say so. Silently acting on stdin
    /// would mean the operator's explicit target lost to an ambient one.
    #[tokio::test]
    async fn argv_wins_over_stdin_and_reports_argv() {
        let cli = cli_from(["youtube-legend-cli", "https://youtu.be/FROM_ARGV"]);
        // `extract_url_from_input` short-circuits on the positional, so
        // stdin is never read — which is exactly the property under
        // test: an available stdin cannot displace argv.
        let target = extract_url_from_input(&cli)
            .await
            .expect("argv target resolves");
        assert_eq!(target.value, "https://youtu.be/FROM_ARGV");
        assert_eq!(target.source, TargetSource::Argv);
        assert_eq!(target.source.as_str(), "argv");
    }

    /// A non-positional flag entering or leaving the line must not make
    /// any token change role.
    #[tokio::test]
    async fn flag_position_never_changes_which_token_is_the_target() {
        let expected = "https://youtu.be/dQw4w9WgXcQ";
        for args in [
            vec!["youtube-legend-cli", expected],
            vec!["youtube-legend-cli", "--lang", "pt-BR", expected],
            vec!["youtube-legend-cli", expected, "--lang", "pt-BR"],
            vec!["youtube-legend-cli", "--json", expected, "--timeout", "45"],
        ] {
            let cli = Cli::parse_from(args.clone());
            let target = extract_url_from_input(&cli)
                .await
                .unwrap_or_else(|e| panic!("{args:?} must resolve: {e}"));
            assert_eq!(target.value, expected, "argv shape: {args:?}");
            assert_eq!(target.source, TargetSource::Argv, "argv shape: {args:?}");
        }
    }

    /// `--no-input` with no positional URL leaves no target at all, so
    /// the parser must fail closed rather than reach for stdin.
    #[test]
    fn no_input_without_a_positional_url_is_a_usage_error() {
        let cli = cli_from(["youtube-legend-cli", "--no-input"]);
        let err = cli.validate().unwrap_err();
        assert!(matches!(err, AppError::InvalidUsage(_)));
        assert_eq!(err.exit_code(), 64);
    }

    /// The `SubRip` body the `WebVTT` tests re-frame.
    const SAMPLE_SRT: &str =
        "1\n00:00:01,000 --> 00:00:02,500\nhello\n\n2\n00:00:03,250 --> 00:00:04,000\n42\n";

    /// `WebVTT` is `SubRip` plus a signature, minus the cue index, with a
    /// dot before the milliseconds. All three differences at once.
    #[test]
    fn srt_to_vtt_reframes_the_body_without_touching_the_timings() {
        let vtt = srt_to_vtt(SAMPLE_SRT);
        assert!(vtt.starts_with("WEBVTT\n\n"), "missing signature: {vtt}");
        assert!(
            vtt.contains("00:00:01.000 --> 00:00:02.500"),
            "the comma must become a dot: {vtt}"
        );
        assert!(!vtt.contains(','), "no SubRip comma may survive: {vtt}");
        assert!(vtt.contains("hello"), "the cue text must survive: {vtt}");
        // The index lines are gone, but a bare number that is the cue's
        // own text is not an index and must stay.
        assert!(
            !vtt.contains("\n1\n00:00:01"),
            "the cue index must be dropped: {vtt}"
        );
        assert!(vtt.contains("\n42\n"), "numeric cue text survives: {vtt}");
    }

    /// `--format vtt` was documented and refused with exit 2. It now
    /// routes the same `SubRip` body the provider delivers for `srt`.
    #[test]
    fn convert_format_produces_webvtt_for_the_vtt_flag() {
        let out = convert_format(
            SAMPLE_SRT.as_bytes(),
            crate::cli::FormatArg::Vtt,
            crate::provider::SubtitleFormat::Srt,
        )
        .expect("vtt conversion succeeds");
        assert_eq!(out, srt_to_vtt(SAMPLE_SRT));
        // And the provider is still asked for SubRip, so no upstream
        // has to learn about WebVTT.
        assert_eq!(
            format_to_provider_format(crate::cli::FormatArg::Vtt),
            Format::Srt
        );
    }

    /// A noteey transcript carries no end-of-cue information, so `WebVTT`
    /// is refused exactly as `SubRip` is — and the message names the
    /// format the operator actually typed.
    #[test]
    fn vtt_is_refused_on_a_noteey_transcript() {
        let err = convert_format(
            b"whatever",
            crate::cli::FormatArg::Vtt,
            crate::provider::SubtitleFormat::NoteeyTranscript,
        )
        .expect_err("noteey cannot produce webvtt");
        assert!(matches!(err, AppError::InvalidUsage(_)), "got {err:?}");
        assert!(err.to_string().contains("--format vtt"), "{err}");
    }

    #[test]
    fn target_source_wire_spellings_are_stable() {
        assert_eq!(TargetSource::Argv.as_str(), "argv");
        assert_eq!(TargetSource::Stdin.as_str(), "stdin");
        assert_eq!(TargetSource::BatchFile.as_str(), "batch-file");
    }

    /// The success envelope must declare provenance and must no longer
    /// carry the dead `language_detected` field, which was always
    /// `false` and therefore told a caller nothing.
    #[test]
    fn success_envelope_declares_provenance_and_drops_the_dead_field() {
        let payload = JsonSuccess {
            provider: "cache",
            video_id: "dQw4w9WgXcQ".to_string(),
            target_resolved: "https://youtu.be/dQw4w9WgXcQ".to_string(),
            target_source: TargetSource::Argv.as_str(),
            language: "en".to_string(),
            delivered_language: None,
            format: "txt".to_string(),
            content: "hello".to_string(),
            byte_size: 5,
            duration_ms: 1,
            source_url: "cache".to_string(),
        };
        let value = serde_json::to_value(&payload).expect("serialises");
        assert_eq!(value["target_source"], serde_json::json!("argv"));
        assert_eq!(
            value["target_resolved"],
            serde_json::json!("https://youtu.be/dQw4w9WgXcQ")
        );
        assert!(
            value.get("language_detected").is_none(),
            "the always-false field must be gone: {value}"
        );
    }

    /// GAP-2026-158: the regression gate for the delivered language.
    ///
    /// The defect this replaced reported the language the operator
    /// ASKED for as if it were the language that arrived, so a run with
    /// `--lang xx` announced `"language":"xx"` over a Portuguese body.
    /// The gate builds one envelope whose request and delivery
    /// deliberately disagree and one whose delivery is unknown. If
    /// `success_payload` ever sources `delivered_language` from
    /// `cli.lang` again, the two fields agree in the first case and the
    /// field appears in the second, and both assertions fail.
    ///
    /// GAP-2026-157: five distinct facts are checked, and the floor is
    /// asserted so a future edit cannot quietly shrink the gate.
    #[test]
    fn delivered_language_is_never_sourced_from_the_request() {
        let cli = cli_from([
            "youtube-legend-cli",
            "--json",
            "--lang",
            "en",
            "https://youtu.be/dQw4w9WgXcQ",
        ]);
        let target = ResolvedTarget {
            value: "https://youtu.be/dQw4w9WgXcQ".to_string(),
            source: TargetSource::Argv,
        };
        let mut checked = 0_usize;

        // A provider that KNOWS: request `en`, delivery `pt-BR`.
        let known = success_payload(
            &cli,
            "getsubs",
            "dQw4w9WgXcQ",
            &target,
            "hello".to_string(),
            "getsubs://pt-BR/srt",
            7,
            Some("pt-BR"),
        );
        let value = serde_json::to_value(&known).expect("serialises");
        assert_eq!(value["language"], serde_json::json!("en"));
        checked += 1;
        assert_eq!(value["delivered_language"], serde_json::json!("pt-BR"));
        checked += 1;
        assert_ne!(
            value["language"], value["delivered_language"],
            "delivered_language repeated the request instead of the \
             delivery: {value}"
        );
        checked += 1;

        // A provider that does NOT know: the field must be absent.
        // Absence declares ignorance; emitting `en` here would restore
        // the silent wrong answer.
        let unknown = success_payload(
            &cli,
            "provider-noiz",
            "dQw4w9WgXcQ",
            &target,
            "hello".to_string(),
            "noteey://dQw4w9WgXcQ/en/txt",
            7,
            None,
        );
        let value = serde_json::to_value(&unknown).expect("serialises");
        assert!(
            value.get("delivered_language").is_none(),
            "an unknown delivery must OMIT the field, never guess the \
             request: {value}"
        );
        checked += 1;
        assert_eq!(value["language"], serde_json::json!("en"));
        checked += 1;

        assert!(
            checked >= 5,
            "GAP-2026-157 floor: expected at least 5 verified facts, ran {checked}"
        );
    }

    /// Build a `SubtitleInfo` shaped like the ones the echoing providers
    /// return: `language` mirrors the request, and `delivered_language`
    /// carries an upstream observation only when there was one.
    fn info_with(language: &str, delivered: Option<&str>) -> SubtitleInfo {
        SubtitleInfo {
            video_id: "dQw4w9WgXcQ".to_string(),
            language: language.to_string(),
            delivered_language: delivered.map(str::to_string),
            format: Format::Srt,
            source_url: "https://example.invalid/track".to_string(),
            byte_size: 0,
            format_hint: crate::provider::SubtitleFormat::Srt,
            provider: "noteey",
        }
    }

    /// GAP-2026-172, the closing gate: the whole distance from a
    /// `SubtitleInfo` a provider would return to the JSON a caller
    /// receives.
    ///
    /// The previous gate stopped at a one-line helper, so a call site
    /// that bypassed the helper stayed green — and MEASURED on
    /// 2026-09-04, `commands::batch` was already such a site. This test
    /// starts where the data starts and ends where the contract ends,
    /// so nothing between the two is outside it.
    ///
    /// Its preconditions are asserted before its result, which is the
    /// discipline that stops a future edit from leaving it green by
    /// making it inspect nothing.
    #[test]
    fn a_subtitle_info_reaches_the_envelope_without_the_request_echoing_into_it() {
        let cli = cli_from([
            "youtube-legend-cli",
            "--json",
            "--lang",
            "en",
            "https://youtu.be/dQw4w9WgXcQ",
        ]);
        let target = ResolvedTarget {
            value: "https://youtu.be/dQw4w9WgXcQ".to_string(),
            source: TargetSource::Argv,
        };

        let envelope_for = |info: &SubtitleInfo| {
            let delivered = DeliveredLanguage::observed(info);
            serde_json::to_value(success_payload(
                &cli,
                info.provider,
                &info.video_id,
                &target,
                "hello".to_string(),
                &info.source_url,
                7,
                delivered.as_deref(),
            ))
            .expect("serialises")
        };

        // An echoing provider: `language` repeats the request and the
        // upstream named no track.
        let echoed = info_with("xx", None);
        assert_eq!(echoed.language, "xx", "precondition: request echoed");
        assert!(
            echoed.delivered_language.is_none(),
            "precondition: the upstream named no track"
        );
        let value = envelope_for(&echoed);
        assert!(
            value.get("delivered_language").is_none(),
            "an unobserved track must stay undeclared all the way to the \
             wire; emitting one here echoes the request back at the \
             operator as if it were evidence: {value}"
        );

        // An observing provider: the tag it named travels through
        // unchanged, and does not become the requested one.
        let observed = info_with("xx", Some("pt"));
        assert_eq!(
            observed.language, "xx",
            "precondition: the two fields must disagree, or the assertion \
             below could not tell them apart"
        );
        let value = envelope_for(&observed);
        assert_eq!(
            value["delivered_language"],
            serde_json::json!("pt"),
            "an upstream observation must reach the envelope unchanged: {value}"
        );
        assert_eq!(
            value["language"],
            serde_json::json!("en"),
            "`language` is the REQUEST, and it comes from the CLI rather \
             than from the provider's echo: {value}"
        );
    }

    /// GAP-2026-172: the cache's answer is ignorance, and it must stay
    /// ignorance on the wire.
    #[test]
    fn a_cache_hit_declares_an_unknown_delivered_language() {
        assert_eq!(
            DeliveredLanguage::unknown().as_deref(),
            None,
            "a cache hit stored no track identity, so it must not name one"
        );
    }

    /// `would_fetch: false` used to be unreachable because a cache hit
    /// returned before the dry-run branch. The envelope now names the
    /// branch, and the two can never disagree.
    #[test]
    fn dry_run_envelope_can_report_a_cache_hit() {
        for (would_fetch, event) in [(true, "dry_run_cache_miss"), (false, "dry_run_cache_hit")] {
            let payload = JsonDryRun {
                event,
                video_id: "dQw4w9WgXcQ".to_string(),
                target_resolved: "https://youtu.be/dQw4w9WgXcQ".to_string(),
                target_source: TargetSource::Argv.as_str(),
                language: "en".to_string(),
                format: "txt".to_string(),
                would_fetch,
            };
            let value = serde_json::to_value(&payload).expect("serialises");
            assert_eq!(value["would_fetch"], serde_json::json!(would_fetch));
            assert_eq!(value["event"], serde_json::json!(event));
        }
    }

    /// Every property `docs/schemas/error-envelope.schema.json`
    /// declares, and how the binary treats it.
    ///
    /// The second half of the bidirectional check lives here on
    /// purpose: widening the schema without widening the envelope, or
    /// the reverse, fails the test at the line that has to be edited by
    /// hand, which is the only way the two stay in step.
    const ERROR_ENVELOPE_PROPERTIES: [(&str, bool); 14] = [
        // (property, emitted by a fully-populated envelope)
        ("error", true),
        ("code", true),
        ("message", true),
        ("kind", true),
        ("retryable", true),
        ("retry_after_ms", true),
        ("provider", true),
        ("video_id", true),
        ("target_resolved", true),
        ("target_source", true),
        ("requested_language", true),
        // Filled by `AppError::LanguageUnavailable`, which the
        // watch-page probe raises with the tags it actually read.
        ("available_languages", true),
        // Filled by the attempt ledger `ProviderChain::fetch_subtitle_traced`
        // returns: the provider's own words, and one entry per provider
        // the chain considered.
        ("diagnostic", true),
        ("attempts", true),
    ];

    /// Serialise the envelope with every field the code can populate,
    /// and return the union of the keys that actually reach the wire.
    ///
    /// Serialising is the whole point: `skip_serializing_if` removes a
    /// `None` field at run time, so reading the struct definition
    /// reports fields the caller never receives. Counting the keys of
    /// the real output is what measures the contract.
    fn emitted_error_envelope_keys() -> std::collections::BTreeSet<String> {
        let cli = cli_from([
            "youtube-legend-cli",
            "https://youtu.be/dQw4w9WgXcQ",
            "--json",
        ]);
        let target = ResolvedTarget {
            value: "https://youtu.be/dQw4w9WgXcQ".to_string(),
            source: TargetSource::Argv,
        };
        // `RateLimited` is the only error carrying a `Retry-After`, so
        // the union of these two is what the envelope can emit. Both now
        // name a provider, which is what the `provider` field reads.
        let errors = [
            AppError::RateLimited {
                provider: "provider-noiz",
                retry_after_secs: Some(30),
            },
            AppError::CaptchaChallenge {
                provider: "provider-decopy",
                kind: "cf-turnstile",
            },
            // The only error that carries a track list, and therefore
            // the only one that can emit `available_languages`.
            AppError::LanguageUnavailable {
                available: vec!["en".to_string(), "pt".to_string()],
            },
        ];
        // A real ledger, because `attempts` and `diagnostic` only reach
        // the wire when the chain produced one.
        let attempts = [crate::provider::ProviderAttempt {
            provider: "provider-decopy",
            outcome: crate::provider::AttemptOutcome::Unavailable,
            elapsed_ms: Some(12),
            http_status: None,
            body_len: None,
            diagnostic: Some("track list did not render within poll limit".to_string()),
        }];
        let mut keys = std::collections::BTreeSet::new();
        for err in errors {
            let payload = error_envelope(&cli, &err, Some(&target), Some("dQw4w9WgXcQ"), &attempts);
            let value = serde_json::to_value(&payload).expect("envelope serialises");
            let object = value.as_object().expect("envelope is an object");
            keys.extend(object.keys().cloned());
        }
        keys
    }

    /// The bidirectional guard `AppError::kind`'s documentation
    /// promises. Before it existed the schema declared fourteen
    /// properties while the envelope emitted five, and nothing failed.
    /// Every `kind` the code can emit must exist in the published enum,
    /// and every value of that enum must be reachable from the code.
    ///
    /// This class was open until 2026-09-01, when `ProviderProtocolError`
    /// started reporting `provider_protocol_error` — a value the schema
    /// did not list, so the binary would have emitted a `kind` that
    /// violates the contract it publishes. The property-level test above
    /// could not see it: it compares property NAMES, and `kind` was
    /// present all along.
    ///
    /// The sample below is built from real variants rather than from a
    /// list of strings, because a list of strings would drift from the
    /// code exactly the way the schema did.
    #[test]
    fn every_error_kind_exists_in_the_published_enum() {
        use crate::error::{AppError, NoSubtitleReason};

        let samples = [
            AppError::NoSubtitle(NoSubtitleReason::NotPublished),
            AppError::InvalidUsage("x".into()),
            AppError::StdinEmpty,
            AppError::InvalidInput("x".into()),
            AppError::ProviderUnavailable {
                provider: "provider-noiz",
            },
            AppError::RateLimited {
                provider: "provider-noiz",
                retry_after_secs: None,
            },
            AppError::CaptchaChallenge {
                provider: "provider-decopy",
                kind: "cf-turnstile",
            },
            AppError::ProviderProtocolError {
                provider: "provider-decopy",
                detail: "x".into(),
            },
            AppError::BrowserNotFound("x".into()),
            AppError::Timeout("x".into()),
            AppError::Config("x".into()),
            AppError::Io(std::io::Error::other("x")),
            AppError::Internal("x".into()),
            AppError::LanguageUnavailable {
                available: vec!["pt-BR".into()],
            },
            AppError::CaptionsAsrOnly {
                asr_languages: vec!["pt".into()],
            },
        ];

        // There is no orphan list any more.
        //
        // Until 2026-08-31 this test tolerated one:
        // `captions_asr_unsupported_by_provider` was published and no
        // arm of `kind()` produced it, so the schema promised callers a
        // branch they could never take. It was named here rather than
        // silently skipped, because a published contract with no
        // producer is a lie whichever way you hide it.
        //
        // The probe in `ProviderChain::fetch_subtitle` now emits it
        // under the composite condition that makes it true — every
        // provider failed AND the watch page carries only ASR tracks —
        // so the tolerance is gone and the assertion below is
        // unconditional again.

        let text = crate::commands::schema::SCHEMAS
            .iter()
            .find(|(id, _)| *id == "error-envelope")
            .map(|(_, text)| *text)
            .expect("the catalogue must carry the error envelope");
        let document: serde_json::Value = serde_json::from_str(text).expect("schema parses");
        let published: std::collections::BTreeSet<&str> = document["properties"]["kind"]["enum"]
            .as_array()
            .expect("the schema enumerates kinds")
            .iter()
            .map(|v| v.as_str().expect("each kind is a string"))
            .collect();

        for err in &samples {
            let kind = err.kind();
            assert!(
                published.contains(kind),
                "`{kind}` is emitted by the code and missing from the published enum"
            );
        }

        // The other direction catches a value that survives in the
        // schema after the code stopped producing it, which would
        // promise callers a branch that can never be taken.
        let emitted: std::collections::BTreeSet<&str> =
            samples.iter().map(crate::error::AppError::kind).collect();
        let orphans: Vec<&str> = published.difference(&emitted).copied().collect();
        assert!(
            orphans.is_empty(),
            "the schema publishes kinds no sampled variant produces: {orphans:?}. \
             Either a variant is missing from the sample above, or the enum is \
             stale, or the schema is publishing a promise nothing keeps."
        );
    }

    /// The same bidirectional question, asked of `attempts[].outcome`.
    ///
    /// GAP-2026-146 was exactly this defect on `kind`, and the ledger
    /// that fills `attempts` shipped in the same session that closed it
    /// with NO equivalent gate, so the class reincided in a field one
    /// day old. Values are compared by their SERIALISED form, because
    /// the wire is what the consumer reads and a `rename_all` typo is
    /// invisible to any test that compares variant names.
    #[test]
    fn every_attempt_outcome_is_published_and_every_published_one_is_reachable() {
        use crate::provider::AttemptOutcome as O;

        // Every variant, listed by hand on purpose: a derived iterator
        // would grow silently with the enum and this test would stop
        // being the place somebody has to think.
        let variants = [
            O::Delivered,
            O::NoCaptions,
            O::AsrRefused,
            O::LanguageUnavailable,
            O::Unavailable,
            O::RateLimited,
            O::Captcha,
            O::DomTimeout,
            O::BrowserMissing,
            O::SkippedDegraded,
            O::SkippedDisabled,
        ];

        let text = crate::commands::schema::SCHEMAS
            .iter()
            .find(|(id, _)| *id == "error-envelope")
            .map(|(_, text)| *text)
            .expect("the catalogue must carry the error envelope");
        let document: serde_json::Value = serde_json::from_str(text).expect("schema parses");
        let published: std::collections::BTreeSet<String> = document["properties"]["attempts"]
            ["items"]["properties"]["outcome"]["enum"]
            .as_array()
            .expect("the schema enumerates outcomes")
            .iter()
            .map(|v| v.as_str().expect("each outcome is a string").to_string())
            .collect();

        // A control: an empty published set would let both directions
        // below pass while measuring nothing.
        assert!(
            published.len() >= 11,
            "the schema publishes only {} outcomes, which is too few to be real",
            published.len()
        );

        let emitted: std::collections::BTreeSet<String> = variants
            .iter()
            .map(|outcome| {
                let json = serde_json::to_value(outcome).expect("outcome serialises");
                json.as_str().expect("outcome is a string").to_string()
            })
            .collect();

        let unpublished: Vec<&String> = emitted.difference(&published).collect();
        assert!(
            unpublished.is_empty(),
            "the ledger emits outcomes the schema does not publish: {unpublished:?}"
        );

        let orphans: Vec<&String> = published.difference(&emitted).collect();
        assert!(
            orphans.is_empty(),
            "the schema publishes outcomes no variant produces: {orphans:?}. \
             Either a variant is missing from the list above, or the schema is \
             publishing a branch the caller can never be handed."
        );
    }

    #[test]
    fn error_envelope_matches_the_published_schema() {
        // The very bytes the binary compiles in, not a re-read of the
        // file: a test that opened its own copy could pass against a
        // document the binary never publishes.
        let text = crate::commands::schema::SCHEMAS
            .iter()
            .find(|(id, _)| *id == "error-envelope")
            .map(|(_, text)| *text)
            .expect("the catalogue must carry the error envelope");
        let document: serde_json::Value = serde_json::from_str(text).expect("schema parses");
        let declared: std::collections::BTreeSet<String> = document["properties"]
            .as_object()
            .expect("schema declares properties")
            .keys()
            .cloned()
            .collect();

        // Direction 1: nothing is emitted that the schema does not
        // declare. `additionalProperties: false` makes any extra key a
        // validation failure for every consumer.
        let emitted = emitted_error_envelope_keys();
        for key in &emitted {
            assert!(
                declared.contains(key),
                "the envelope emits `{key}`, which the schema does not declare"
            );
        }

        // Direction 2: every declared property is accounted for, either
        // as emitted or as knowingly unfilled.
        let accounted: std::collections::BTreeSet<String> = ERROR_ENVELOPE_PROPERTIES
            .iter()
            .map(|(name, _)| (*name).to_string())
            .collect();
        assert_eq!(
            declared, accounted,
            "the schema and the accounting list must name the same properties"
        );

        // And the classification must match what serialisation shows,
        // so a field that starts or stops being populated cannot slip
        // through as an unreviewed comment.
        for (name, expected) in ERROR_ENVELOPE_PROPERTIES {
            assert_eq!(
                emitted.contains(name),
                expected,
                "`{name}` is classified as emitted={expected} but serialisation disagrees"
            );
        }
    }

    /// The required trio must survive even the emptiest envelope: a
    /// failure with no target, no id and no upstream advice.
    #[test]
    fn the_minimal_error_envelope_still_carries_the_required_fields() {
        let cli = cli_from(["youtube-legend-cli", "--json", "--no-input"]);
        let payload = error_envelope(&cli, &AppError::StdinEmpty, None, None, &[]);
        let value = serde_json::to_value(&payload).expect("serialises");
        let object = value.as_object().expect("object");
        for required in ["error", "code", "message"] {
            assert!(object.contains_key(required), "missing {required}: {value}");
        }
        // Absent, not null: a consumer must be able to tell "unknown"
        // from "the empty string".
        for absent in ["target_resolved", "target_source", "video_id"] {
            assert!(
                !object.contains_key(absent),
                "{absent} must be omitted, not emitted as null: {value}"
            );
        }
    }

    /// GAP-2026-194: `--offline` is a stable cause, so the envelope must
    /// not advertise a retry.
    ///
    /// The test states its own PRECONDITION before it states its result,
    /// which is the discipline GAP-2026-172 paid for: without the first
    /// assertion, an error that stopped being retryable by TYPE would
    /// leave this green while proving nothing about the flag. The two
    /// halves run against the same error and differ only in the flag, so
    /// the flag is the only thing the comparison can be measuring.
    #[test]
    fn an_offline_run_never_tells_the_caller_to_try_again() {
        let err = AppError::ProviderUnavailable {
            provider: "provider-noiz",
        };
        assert!(
            err.retryable(),
            "precondition: this error must be retryable BY TYPE, or the \
             offline half below would pass without narrowing anything"
        );

        let online = cli_from([
            "youtube-legend-cli",
            "--json",
            "https://youtu.be/dQw4w9WgXcQ",
        ]);
        let value = serde_json::to_value(error_envelope(&online, &err, None, None, &[]))
            .expect("serialises");
        assert_eq!(
            value["retryable"],
            serde_json::json!(true),
            "without the flag the envelope must keep describing the world: {value}"
        );

        let offline = cli_from([
            "youtube-legend-cli",
            "--json",
            "--offline",
            "https://youtu.be/dQw4w9WgXcQ",
        ]);
        let value = serde_json::to_value(error_envelope(&offline, &err, None, None, &[]))
            .expect("serialises");
        assert_eq!(
            value["retryable"],
            serde_json::json!(false),
            "under --offline the refusal is this process's own, so repeating \
             the same command line cannot change it: {value}"
        );
    }

    /// `--timeout` had no call site at all. It now bounds the fetch.
    #[tokio::test(start_paused = true)]
    async fn timeout_flag_bounds_the_operation() {
        let cli = cli_from([
            "youtube-legend-cli",
            "https://youtu.be/dQw4w9WgXcQ",
            "--timeout",
            "1",
        ]);
        let result: AppResult<()> = with_deadline(&cli, async {
            tokio::time::sleep(std::time::Duration::from_secs(30)).await;
            Ok(())
        })
        .await;
        let err = result.unwrap_err();
        assert!(matches!(err, AppError::Timeout(_)), "got {err:?}");
        assert!(err.to_string().contains("--timeout"));
    }

    #[tokio::test]
    async fn a_fast_operation_is_not_cut_by_the_deadline() {
        let cli = cli_from(["youtube-legend-cli", "https://youtu.be/dQw4w9WgXcQ"]);
        let result: AppResult<u8> = with_deadline(&cli, async { Ok(7) }).await;
        assert_eq!(result.ok(), Some(7));
    }

    /// The reduction flags act on the JSON envelope; engaging them
    /// without `--json` must be refused rather than silently ignored.
    #[test]
    fn reduction_flags_require_json() {
        let cli = cli_from([
            "youtube-legend-cli",
            "https://youtu.be/dQw4w9WgXcQ",
            "--limit",
            "1",
        ]);
        let err = cli.validate().unwrap_err();
        assert!(matches!(err, AppError::InvalidUsage(_)));
        assert!(err.to_string().contains("--json"));
    }

    #[test]
    fn a_malformed_filter_is_rejected_at_validation_time() {
        let cli = cli_from([
            "youtube-legend-cli",
            "https://youtu.be/dQw4w9WgXcQ",
            "--json",
            "--filter",
            "no_operator",
        ]);
        assert!(matches!(cli.validate(), Err(AppError::InvalidUsage(_))));
    }

    /// `--provider` used to be read into `let _choice` and thrown away.
    /// It now drives the `match` that decides what the chain contains,
    /// so every documented value must build a usable chain.
    #[test]
    fn provider_selection_is_read_rather_than_discarded() {
        for flag in ["auto", "provider-decopy", "provider-noiz"] {
            let cli = cli_from([
                "youtube-legend-cli",
                "https://youtu.be/dQw4w9WgXcQ",
                "--provider",
                flag,
            ]);
            assert_eq!(
                cli.provider,
                Some(match flag {
                    "provider-decopy" => ProviderChoice::ProviderDecopy,
                    "provider-noiz" => ProviderChoice::ProviderNoiz,
                    _ => ProviderChoice::Auto,
                })
            );
            // Building must not panic for any documented selection.
            let _chain = build_provider_chain(&cli);
        }
    }

    /// O schema publicado e a struct que o preenche são duas fontes
    /// independentes, e foi essa independência que produziu um envelope
    /// de 5 chaves contra 14 declaradas.
    ///
    /// O snapshot vizinho, em `tests/integration/envelope_snapshots.rs`,
    /// fixa UM caminho de erro, e um caminho de erro exercita apenas os
    /// campos que aquele caminho preenche. Foi por isso que ele conviveu
    /// com a divergência sem enxergá-la: `skip_serializing_if` faz a
    /// struct emitir menos chaves do que declara, então a saída de um
    /// caso é a INTERSEÇÃO e nunca a superfície.
    ///
    /// Aqui todos os campos vão preenchidos de propósito, para que a
    /// serialização emita a superfície INTEIRA. O schema declara
    /// `additionalProperties: false`, então chave a mais quebra o
    /// consumidor e chave a menos é promessa não cumprida — os dois
    /// lados precisam ser afirmados, e é isso que torna o teste
    /// bidirecional em vez de uma inclusão só.
    #[test]
    fn the_error_envelope_struct_and_its_published_schema_agree_on_every_key() {
        let envelope = JsonError {
            error: true,
            code: 69,
            message: "provedor indisponível".to_string(),
            kind: "provider_unavailable",
            retryable: true,
            retry_after_ms: Some(60_000),
            provider: Some("provider-decopy"),
            video_id: Some("dQw4w9WgXcQ".to_string()),
            target_resolved: Some("https://youtu.be/dQw4w9WgXcQ".to_string()),
            target_source: Some("argv"),
            requested_language: Some("pt"),
            available_languages: Some(vec!["en".to_string(), "pt".to_string()]),
            diagnostic: Some("checkbox-grid".to_string()),
            attempts: vec![crate::provider::ProviderAttempt {
                provider: "provider-decopy",
                outcome: crate::provider::AttemptOutcome::Unavailable,
                elapsed_ms: Some(1),
                http_status: None,
                body_len: None,
                diagnostic: None,
            }],
        };

        let serde_json::Value::Object(emitido) =
            serde_json::to_value(&envelope).expect("o envelope serializa")
        else {
            panic!("o envelope de erro é um objeto JSON");
        };

        let schema: serde_json::Value = serde_json::from_str(include_str!(
            "../../docs/schemas/error-envelope.schema.json"
        ))
        .expect("o schema publicado é JSON válido");
        let declarado = schema
            .get("properties")
            .and_then(serde_json::Value::as_object)
            .expect("o schema de erro declara `properties`");

        let mut emitidas: Vec<&str> = emitido.keys().map(String::as_str).collect();
        let mut declaradas: Vec<&str> = declarado.keys().map(String::as_str).collect();
        emitidas.sort_unstable();
        declaradas.sort_unstable();

        assert_eq!(
            emitidas, declaradas,
            "a struct e o schema divergiram: com `additionalProperties: false`, chave emitida a mais quebra o consumidor e chave declarada a menos é contrato que ninguém cumpre"
        );
    }
}