ignition_core/

error.rs

//! Typed error taxonomy — THE exit-code contract for `ign`.
//!
//! The mapping error-class → exit code is LOCKED (Phase-1 API freeze). The
//! table exists in exactly two places: [`CoreError::exit_code`] here and the
//! README — kept in sync by the `exit_code_mapping_enumerated` unit test and
//! the golden-file tests in `crates/ignition-cli/tests/`.
//!
//! | exit | class          | slugs
//! |------|----------------|-----------------------------------------------
//! | 1    | internal       | `internal`
//! | 2    | usage          | `confirmation_required`, `invalid_import_file`, `invalid_input`, `gateway_client_error` (09-01) (clap renders its own usage errors — never hook clap)
//! | 3    | config         | `profile_not_found`, `no_active_profile`, `secret_unavailable`, `config_invalid`, `poll_interval_too_small` (08-01), `module_not_registered` (16-01)
//! | 4    | network        | `network_error`, `module_feed_unreachable` (15-01)
//! | 5    | auth           | `auth_rejected`
//! | 6    | target_state   | `gateway_too_old`, `gateway_not_commissioned`, `gateway_restarting`, `not_found`, `project_exists`, `resource_binary`, `trial_not_expired` (04-03), `provider_not_found` (05-04), `routes_not_deployed`, `webdev_unlicensed`, `route_version_mismatch`, `webdev_route_error` (05-03), `tag_collision` (05-05), `alarm_journal_missing` (05-06), `import_denied` (05-07), `session_not_prunable` (06-07), `eam_not_controller` (07-02), `eam_task_type_refused` (07-02), `eam_task_in_flight` (07-06), `script_exec_not_configured` (07-03), `lint_tool_absent` (07-04), `provider_root_unsupported` (07-06), `bundle_not_available` (09-07), `module_release_not_found`, `module_digest_mismatch`, `module_feed_unusable` (15-01), `module_digest_changed` (15-02), `module_uninstall_denied` (19-01)
//! | 7    | rig            | `rig_error` (reserved — first used in Phase 4)
//!
//! Slugs are public contract: never respell them. Exit codes are public
//! contract: never renumber them (the enumerated test guards both).

use serde::Serialize;

/// The `ign tui` TTY-refusal reason (06-07). The InvalidInput hint is
/// content-addressed off this exact string: the frozen taxonomy keeps
/// ONE usage-input variant (no hint field, no new variant), but the
/// TTY refusal's fix is terminal-related, not `--file`/stdin —
/// [`CoreError::hint`] special-cases this one reason while every other
/// raise site keeps the resource-put default. Construct via
/// [`CoreError::tui_tty_refusal`] so the reason/hint pair cannot drift.
pub const TUI_TTY_REFUSAL_REASON: &str = "ign tui requires a terminal (stdout is not a TTY)";

/// The TAGS-12 loss-gate refusal reason prefix (11-07 gap closure). The
/// InvalidInput hint is content-addressed off this literal: the loss
/// gate's reason is DYNAMIC prose (the CLI's `render_loss_prose` header
/// `loss report ({label}): …` plus per-fact lines), so unlike
/// [`TUI_TTY_REFUSAL_REASON`] the sentinel cannot be the whole reason —
/// it is the stable header prefix instead. Same slug (`invalid_input`),
/// same exit 2 (frozen taxonomy; only the hint differs) — the 06-07
/// TTY-refusal pattern at one removal. The contract_tags loss-gate
/// pins are the drift guard: if the prose header ever changes, the
/// hint silently regresses to the generic default and those pins fail.
pub const LOSS_GATE_REFUSAL_REASON_PREFIX: &str = "loss report (";

/// The TESTING bundle's route prefix (QUICK-p0g). The
/// [`CoreError::RoutesNotDeployed`] hint is content-addressed off it
/// — same third instance of the 06-07 pattern: the frozen taxonomy
/// keeps ONE absent-routes variant and one slug
/// (`routes_not_deployed`, exit 6), but the testing bundle installs
/// through a DIFFERENT command (`ign webdev deploy --with-testing` /
/// `ign adopt --project NAME --testing`), so the generic
/// `ign webdev deploy` hint would name a command that does not fix
/// it. Raise sites pass `route: "testing/run"`.
pub const TESTING_ROUTE_PREFIX: &str = "testing/";

/// The api-call catch-all's body cap (09-01): a gateway 4xx body rides
/// [`CoreError::GatewayClientError`] VERBATIM up to this many bytes; a
/// larger body is truncated at [`truncate_api_body`] with the explicit
/// [`GATEWAY_CLIENT_BODY_TRUNCATION_MARKER`]. 4 KiB is the plan-locked
/// cap — an unbounded passthrough would let a pathological gateway
/// page flood the agent's envelope.
pub const GATEWAY_CLIENT_BODY_CAP_BYTES: usize = 4096;

/// The truncation marker [`truncate_api_body`] appends when the api-call
/// body exceeds [`GATEWAY_CLIENT_BODY_CAP_BYTES`]. ASCII-pinned (no
/// multi-byte characters) so golden-file consumers never see an encoding
/// surprise at the cut.
pub const GATEWAY_CLIENT_BODY_TRUNCATION_MARKER: &str = "... [truncated]";

/// The ONE construction site for a capped api-call body: returns `body`
/// verbatim when it fits [`GATEWAY_CLIENT_BODY_CAP_BYTES`], otherwise its
/// first cap bytes (on a UTF-8 char boundary) plus
/// [`GATEWAY_CLIENT_BODY_TRUNCATION_MARKER`]. The variant always carries
/// its final form — construction cannot forget the cap.
pub fn truncate_api_body(body: &str) -> String {
    if body.len() <= GATEWAY_CLIENT_BODY_CAP_BYTES {
        return body.to_string();
    }
    let mut end = GATEWAY_CLIENT_BODY_CAP_BYTES;
    while !body.is_char_boundary(end) {
        end -= 1;
    }
    let mut truncated = body[..end].to_string();
    truncated.push_str(GATEWAY_CLIENT_BODY_TRUNCATION_MARKER);
    truncated
}

/// Every failure `ign` can report. One variant per contract class; `code()`,
/// `exit_code()`, `hint()` are total functions over it.
#[derive(Debug, thiserror::Error)]
pub enum CoreError {
    /// Unexpected runtime failure — the catch-all; report as a bug. Exit 1.
    #[error("internal error: {0}")]
    Internal(String),

    /// Destructive operation invoked without `--yes`. Exit 2 (same class as
    /// usage: it names a flag the caller must add; clap renders its own
    /// usage errors with its exit 2 — never hook clap).
    #[error("{operation} is destructive; rerun with --yes to confirm")]
    ConfirmationRequired { operation: String },

    /// An import byte source the caller must fix (wrong file, too big,
    /// unreadable). Exit 2 — usage class: it names what the CALLER must
    /// change, like [`Self::ConfirmationRequired`] (03-02).
    #[error("invalid import file: {reason}")]
    InvalidImportFile { reason: String },

    /// The gateway ANSWERED the import POST with HTTP 200 but the
    /// body says `{"success": false, "problem": "…"}` — the
    /// denial-rides-200 class the WebDev family handles (05-01)
    /// applied to the project-import family (05-07, UAT Gap 1):
    /// without this check the import caller reports ok while nothing
    /// landed. Exit 6 — target state: the gateway refused the
    /// import (the problem text names why, verbatim).
    #[error("gateway rejected the project import for {project:?}: {problem}")]
    ImportDenied {
        /// The project the import was headed for.
        project: String,
        /// The gateway's own `problem` text (verbatim when present).
        problem: String,
        /// URL of the import request, when known.
        endpoint: Option<String>,
    },

    /// A command input the caller must fix (unreadable `--file`, failed
    /// stdin read). Exit 2 — usage class, the generic sibling of
    /// [`Self::InvalidImportFile`] (03-03: `resource put`'s byte
    /// source).
    #[error("invalid input: {reason}")]
    InvalidInput { reason: String },

    /// Named profile absent from config. Exit 3.
    #[error("profile {name:?} not found (known profiles: {known:?})")]
    ProfileNotFound { name: String, known: Vec<String> },

    /// No `--profile`, no `IGNITION_PROFILE`, no active profile in config.
    /// Exit 3. Constructible from the CLI once config resolution lands
    /// (01-03); the taxonomy is complete on day one.
    #[error("no active profile configured")]
    NoActiveProfile,

    /// No credential resolvable for the profile (env, token_env, keyring all
    /// missed or failed). Exit 3.
    #[error("secret unavailable for profile {profile:?}")]
    SecretUnavailable { profile: String },

    /// The adopt bootstrap's login rung needs `IGNITION_PASSWORD` and it
    /// was absent/empty (ADOPT-05 review round: the generic
    /// [`Self::SecretUnavailable`] hint names the TOKEN paths, which is
    /// exactly wrong for the PASSWORD gate — same exit class, own slug,
    /// never a new exit code; the PollIntervalTooSmall precedent).
    #[error("login password unavailable for profile {profile:?}")]
    PasswordUnavailable { profile: String },

    /// Config file unreadable or wrong shape. Exit 3.
    #[error("invalid configuration: {reason}")]
    ConfigInvalid { reason: String },

    /// A profile's `poll_interval_secs` is below the 1-second floor
    /// (08-01, TUIX-05 clamp): sub-second gateway polling is refused at
    /// load time — the TUI's background refresh cadence may not hammer
    /// the gateway. Exit 3 — the CONFIG class (the Phase-7 additive-slug
    /// precedent, e.g. `eam_not_controller`: same exit class, own slug,
    /// never a new exit code — the 1–7 taxonomy is frozen).
    #[error("profile {profile:?}: poll_interval_secs must be >= 1 (sub-second polling refused)")]
    PollIntervalTooSmall {
        /// The profile carrying the refused value.
        profile: String,
    },

    /// Gateway unreachable / timeout / TLS failure. Exit 4.
    ///
    /// `source: None` marks a POLL deadline expiry (02-04 `poll.rs`):
    /// same class, same slug (`network_error`), no new variant — the
    /// transport-error `source` a real failure carries is simply
    /// absent, and `url` describes what was being waited on instead
    /// (the poll's subject). The deadline's last observation rides
    /// `observation` (09-07): when it is `Some` the gateway ANSWERED
    /// with a concrete state, and the message leads with "no terminal
    /// state" — it NEVER claims unreachability for an observed
    /// answer; `None` keeps the plain unreachability wording.
    #[error(
        "{lead} at {url}{source_note}{observation_note}",
        lead = if observation.is_some() {
            "no terminal state"
        } else {
            "gateway unreachable"
        },
        source_note = source.as_ref().map(|source| format!(": {source}")).unwrap_or_default(),
        observation_note = observation
            .as_deref()
            .map(|obs| format!("; last observation: {obs}"))
            .unwrap_or_default()
    )]
    Network {
        url: String,
        #[source]
        source: Option<reqwest::Error>,
        /// The poll deadline's last concrete observation (e.g. the
        /// gateway's reported state) — `None` for transport failures
        /// and observation-less deadlines. `Some` ⇒ the gateway
        /// answered; the Display never says "unreachable" then.
        observation: Option<String>,
    },

    /// Gateway reachable but rejected credentials (401/403). Exit 5.
    #[error("gateway rejected credentials (HTTP {status})")]
    Auth {
        status: u16,
        /// URL/path of the request that was rejected, when known.
        endpoint: Option<String>,
    },

    /// Gateway reachable but the command is invalid for its current state —
    /// version below minimum, uncommissioned, mid-restart, or a missing
    /// resource. Exit 6.
    #[error("gateway version {found} is below minimum {minimum}")]
    GatewayTooOld {
        found: String,
        minimum: String,
        /// URL/path of the request that answered, when known.
        endpoint: Option<String>,
    },

    /// Gateway reachable but uncommissioned — every `/data` route 302s to
    /// `/welcome` (verified on a fresh 8.3.6 container; 02-RESEARCH
    /// §Error-Body Sniffing). Exit 6.
    #[error("gateway at {} is not commissioned", endpoint.as_deref().unwrap_or("unknown address"))]
    GatewayNotCommissioned {
        /// URL that was redirected to the commissioning wizard.
        endpoint: Option<String>,
    },

    /// Gateway restarting — webserver answers (503) but services are down
    /// (verified restart lifecycle: webserver never drops the connection).
    /// Exit 6.
    #[error("gateway is restarting (webserver up, services down)")]
    GatewayRestarting {
        /// URL that answered 503.
        endpoint: Option<String>,
    },

    /// Named resource absent (404) — terminating a nonexistent session id,
    /// an unknown path, or a pre-8.3 gateway's JSON
    /// `{"message": "No route match for path: …"}`. Exit 6.
    #[error("resource not found on the gateway")]
    NotFound {
        /// URL that answered 404.
        endpoint: Option<String>,
    },

    /// A project of this name already exists and the import's collision
    /// policy is abort — the CLI-side pre-check refused BEFORE any
    /// upload (the server's own answer remains the backstop). Exit 6 —
    /// target state: the command is invalid for the gateway's current
    /// state (03-02, the GatewayTooOld action-built-variant precedent:
    /// constructed by the actions layer, not classify).
    #[error("project {name} already exists on the gateway")]
    ProjectExists {
        /// The colliding project name.
        name: String,
        /// URL of the pre-check request, when known.
        endpoint: Option<String>,
    },

    /// A binary (data.bin-class) resource met the surgical JSON/text
    /// loop — REFUSED rather than corrupted through it. Exit 6 —
    /// target state: the command is invalid for that resource's
    /// nature; the export/import family owns binary resources
    /// (Pitfall 7).
    #[error("resource {path:?} has binary content — not editable via the resource loop")]
    ResourceBinary {
        /// The resource path that was refused.
        path: String,
        /// URL of the request involved, when known.
        endpoint: Option<String>,
    },

    /// The gateway refuses trial resets while the trial is still
    /// active — live-discovered on 8.3.3 during 04-03's spike: the
    /// reset POST answers 403 on a NON-expired trial (verified from
    /// the browser page itself with the exact UI headers), and 200 +
    /// the flip on an expired one. The action layer's expiry pre-check
    /// turns that misleading auth-shaped 403 into the honest
    /// target-state refusal. Exit 6 (the ProjectExists precedent:
    /// action-constructed, not classify).
    #[error(
        "trial is not expired ({remaining_s}s left) — the gateway only honors resets once the trial expires"
    )]
    TrialNotExpired {
        /// Seconds left on the active trial.
        remaining_s: i64,
        /// URL of the rig's trial endpoint, when known.
        endpoint: Option<String>,
    },

    /// The WebDev route family a command depends on is not deployed —
    /// the presence probe answered 405, the live-proven 8.3 absent
    /// marker (missing routes AND missing projects both answer 405,
    /// NOT 404; 05-RESEARCH Pitfall 1). Exit 6 — target state: the
    /// command is invalid until `ign webdev deploy` installs the
    /// routes (the TrialNotExpired precedent: action-constructed, not
    /// classify).
    #[error(
        "webdev routes are not deployed (probe of {route:?} in project {project:?} answered 405)"
    )]
    RoutesNotDeployed {
        /// The deploy project the probe targeted.
        project: String,
        /// The route folder the probe named.
        route: String,
        /// Path of the probe request, when known.
        endpoint: Option<String>,
    },

    /// The WebDev module answered 402 — installed but unlicensed (a
    /// trial-expired gateway; live-verified cross-version on 8.3.6,
    /// 05-RESEARCH §Servlet). Exit 6 — no `/system/webdev` route can
    /// answer until the gateway is licensed.
    #[error(
        "the WebDev module is unlicensed on this gateway (HTTP 402 — trial-expired rigs cannot serve /system/webdev routes)"
    )]
    WebdevUnlicensed {
        /// Path of the probe request, when known.
        endpoint: Option<String>,
    },

    /// A deployed route's handshake version differs from the embedded
    /// bundle's — the CLI refuses rather than auto-upgrading either
    /// side (roadmap-locked: actionable error, no auto-upgrade
    /// magic). Exit 6.
    #[error("route {route:?} version mismatch: deployed {deployed}, this CLI expects {expected}")]
    RouteVersionMismatch {
        /// The route folder that answered.
        route: String,
        /// The route's deployed `routeVersion`.
        deployed: String,
        /// The embedded bundle's version
        /// ([`crate::webdev::ROUTE_BUNDLE_VERSION`]).
        expected: String,
        /// Path of the probe request, when known.
        endpoint: Option<String>,
    },

    /// A tag provider of this name does not exist — the
    /// find→signature→delete chain's find half missed (05-04,
    /// TAGS-01). Exit 6 — target state: the named thing is absent
    /// (the ProjectExists precedent family: action-constructed, not
    /// classify — the honest, family-specific refusal over a bare
    /// 404).
    #[error("tag provider {name:?} not found on the gateway")]
    ProviderNotFound {
        /// The provider name that missed.
        name: String,
        /// URL of the find request, when known.
        endpoint: Option<String>,
    },

    /// A WebDev route answered HTTP 200 with a body denial
    /// (`{ok:false, error{code,message}}`) whose machine code this CLI
    /// does not specifically map — code + message ride verbatim so
    /// agents can branch on the stable route contract (05-01). Exit 6
    /// — target state: the deployed route refused the action.
    #[error("webdev route denied the call ({code}): {message}")]
    WebdevRouteError {
        /// The route's machine error code (stable contract).
        code: String,
        /// The route's human message.
        message: String,
        /// Path of the request, when known.
        endpoint: Option<String>,
    },

    /// A tag import under abort policy found EXISTING tags at the
    /// target provider (05-05, TAGS-09) — the browse pre-check
    /// refuses BEFORE any route write (the LOCKED Phase-3 collision
    /// matrix mapped onto configure's 'a'/'o'). Exit 6 — target
    /// state: the named tags exist; overwrite is the explicit,
    /// guarded opt-in.
    #[error(
        "tag collision importing into provider {provider:?}: {} already exist(s)",
        names.join(", ")
    )]
    TagCollision {
        /// The target provider the import was headed for.
        provider: String,
        /// The colliding top-level tag names the pre-check found.
        names: Vec<String>,
        /// URL of the pre-check browse request, when known.
        endpoint: Option<String>,
    },

    /// The gateway has no alarm-journal profile configured — alarm
    /// history has nowhere to read from. The alarms route's
    /// structured `no_alarm_journal` denial maps here (the
    /// denial_to_error seam, 05-06 TAGS-07): DEFAULT rigs hit this
    /// ALWAYS, because the journal is a config-resource chain —
    /// database connection + `ignition/alarm-journal` profile + the
    /// `general-alarm-settings` singleton pointing at it. Exit 6 —
    /// target state: the command is invalid for the gateway's
    /// current state until that chain is provisioned (the honest,
    /// actionable refusal over a bare route error).
    #[error(
        "no alarm journal profile is configured on this gateway — alarm history has nothing to read"
    )]
    AlarmJournalMissing {
        /// URL of the alarms route request, when known.
        endpoint: Option<String>,
    },

    /// Pruning a LIVE Designer session entry — the gateway's prune
    /// route answers 409 (empty body, wire-verified on 8.3.3,
    /// 06-UAT test 6): prune removes STALE entries only, so the
    /// command is invalid while the Designer is still open. Exit 6 —
    /// target state (additive slug in the frozen taxonomy's
    /// established growth pattern; classify()'s ROUTE-SCOPED 409 arm
    /// constructs this — the first classify-constructed refusal added
    /// since the 02-01 set).
    #[error("designer session {id} is live — the gateway refused the prune")]
    SessionNotPrunable {
        /// The Designer session id that was refused.
        id: String,
        /// URL of the refused DELETE, when known.
        endpoint: Option<String>,
    },

    /// Docker/compose rig failure. Exit 7. Reserved — first used in Phase 4;
    /// trivially constructible so the taxonomy enumerates completely today.
    #[error("rig error: {0}")]
    Rig(String),

    /// The gateway's EAM module is not configured as a controller —
    /// every `/data/eam/api/v1/*` runtime endpoint answers 403 with
    /// "This operation can only be performed when EAM is configured
    /// as a controller" on a stock gateway (live-proven 8.3.3,
    /// 07-RESEARCH): a STATE refusal, not auth — the token is fine,
    /// the module's role is not. Message-classified at the classify
    /// seam, path-scoped to `/data/eam/` so generic 403s elsewhere
    /// cannot shift (the trial_not_expired pattern, classify
    /// edition). Exit 6 — target state.
    #[error(
        "EAM is not configured as a controller on this gateway — every EAM runtime \
         operation refuses until the module's installMode is flipped"
    )]
    EamNotController {
        /// URL of the refused request, when known.
        endpoint: Option<String>,
    },

    /// A provider-ROOT tag path (`[default]` alone, or a bare first
    /// segment that resolves to a provider) met the tagConfig route
    /// — `system.tag.getConfiguration`/`exportTags` need an RPC
    /// context WebDev threads don't carry (live-proven 8.3.3
    /// b2026012009, both gateways; 07-UAT test 12). The route
    /// refuses honestly (pre-call bracket detection + RpcContext
    /// translation for the bare form) instead of surfacing the
    /// IllegalStateException as a generic route error; subtree
    /// paths (`[default]folder`) are the supported form. Exit 6 —
    /// target state: a platform limitation, not a bug.
    #[error(
        "provider-root tag paths are not supported by the deployed route (the gateway needs an \
         RPC context WebDev threads don't carry) — target a subtree like [provider]folder"
    )]
    ProviderRootUnsupported {
        /// URL of the tagConfig route request, when known.
        endpoint: Option<String>,
    },

    /// An `eam task new` whose type is in the REFUSED set —
    /// `eam_restoreBackup`, `eam_installModules`, `eam_remoteUpgrade`
    /// are fleet-destructive (they push backups/modules/upgrades to
    /// every AGENT target), and the CLI refuses them outright over
    /// guard-everything: honest refusal with the v2 scope pointer
    /// (the planner-locked create ladder's top rung). Exit 6 —
    /// target state (additive slug alongside Task 2's).
    #[error(
        "EAM task type {task_type} is fleet-destructive — refused (restore/install/upgrade \
         are EXT-03 (v2) scope; run them from the EAM console)"
    )]
    EamTaskTypeRefused {
        /// The refused `profile.type` token.
        task_type: String,
    },

    /// An `eam task force` whose slot a leftover run occupies — the
    /// force route answers 409 with the gateway's own Jetty page
    /// ("Task 'X (forced)' already exists! It must be completed or
    /// deleted before another task of this type can be force
    /// executed."; live-captured 8.3.3, 07-UAT test 7). Exit 6 —
    /// target state (the `session_not_prunable` precedent,
    /// force-route edition): the gateway's state refused the command,
    /// not a bug; classify()'s path-scoped 409 arm constructs this.
    #[error("EAM task {task} has a run in flight — the gateway refused the force: {detail}")]
    EamTaskInFlight {
        /// The forced task's name (the force URL's last segment).
        task: String,
        /// The gateway's Jetty page message verbatim when sniffed;
        /// the '(forced)' fallback text otherwise.
        detail: String,
        /// URL of the refused force POST, when known.
        endpoint: Option<String>,
    },

    /// The scriptExec route is not configured for this profile — no
    /// webdev secret is persisted, which can only mean `ign webdev
    /// deploy --with-script-exec` has never run (deploy persists the
    /// secret 0600 BEFORE upload, so a deployed route without a
    /// stored secret is not a reachable state). `ign script run`'s
    /// opt-in is STRUCTURAL — the deploy flag — so the verb carries
    /// no `--yes` guard and refuses here instead (07-03, SCRPT-01:
    /// the TrialNotExpired precedent — action-constructed, not
    /// classify). Exit 6 — target state.
    #[error(
        "scriptExec is not configured for profile {profile:?} — the secret-gated route deploys \
         only via the explicit opt-in"
    )]
    ScriptExecNotConfigured {
        /// The profile whose secret store is empty.
        profile: String,
    },

    /// `ign lint` found no `ignition-lint` executable on PATH — the
    /// delegation has nothing to delegate to (07-04, INTR-02). The
    /// hint carries the install command + repo. Exit 6 — target
    /// state (additive slug; the environment lacks the tool, the
    /// command is fine).
    #[error("ignition-lint is not installed (no executable found on PATH)")]
    LintToolAbsent,

    /// `ign e2e init` found no `node` executable on PATH — the scaffold
    /// it would write is unusable without one (QUICK-tg4).
    ///
    /// Exit 6, mirroring [`Self::LintToolAbsent`] line for line: this
    /// is the SAME shape — a local external tool a verb delegates to is
    /// absent, with an install hint. It deliberately does NOT join
    /// exit 7, whose sole slug is `rig_error` for docker/compose rig
    /// failures; putting a missing Node there would force a relabel of
    /// a locked exit class.
    #[error("{tool} is not installed (no executable found on PATH)")]
    NodeToolAbsent {
        /// The tool that was looked for (`node`).
        tool: String,
    },

    /// The gateway answered the api call with a 4xx this CLI does not
    /// curate — the caller's request is the problem, and the body is
    /// theirs to read. Exit 2 (usage class; additive slug — the
    /// poll_interval_too_small precedent: same class, own slug, no new
    /// exit code). Constructed ONLY by the api-call-scoped classify arm
    /// (09-01: the `api_call` parameter) — a curated command's 4xx keeps
    /// its existing classification (the catch-all cannot fire without
    /// the parameter). The body is the gateway's answer VERBATIM,
    /// truncated at [`GATEWAY_CLIENT_BODY_CAP_BYTES`] with the explicit
    /// [`GATEWAY_CLIENT_BODY_TRUNCATION_MARKER`] via [`truncate_api_body`]
    /// at construction.
    #[error("gateway rejected the api call (HTTP {status} from {endpoint}): {body}")]
    GatewayClientError {
        /// HTTP status the gateway answered with.
        status: u16,
        /// Full URL of the rejected request.
        endpoint: String,
        /// The response body VERBATIM, truncated at
        /// [`GATEWAY_CLIENT_BODY_CAP_BYTES`] with an explicit marker.
        body: String,
    },

    /// No diagnostics bundle is available — the status poll ANSWERED
    /// with a captured TERMINAL steady state meaning "no current
    /// bundle" (`Invalid`: live-proven on 8.3.6 rig ign-p9-836,
    /// 2026-09-07 UAT / 09-UAT.md Gap 3 — a `Valid` bundle decays to
    /// `Invalid` within ~2 minutes UNPROMPTED and stays `Invalid`;
    /// only a fresh generate changes it, polling cannot). Exit 6 —
    /// target state (the `ImportDenied` precedent: a gateway-answered
    /// refusal riding its own class, action-constructed by `bundle
    /// wait`'s probe, not classify).
    #[error(
        "no diagnostics bundle available (gateway reports state {state:?}) — run \
         `ign diagnostics bundle generate` first; polling cannot change this state"
    )]
    BundleNotAvailable {
        /// The observed steady state (the captured unavailable
        /// vocabulary, e.g. `Invalid`).
        state: String,
    },

    /// Transport failure reaching a third-party module release feed or
    /// its asset CDN — DNS/connect/timeout/TLS (Phase 15, D-06). Exit 4:
    /// same network class as [`Self::Network`], but a SEPARATE slug and
    /// wording — `Network`'s Display hard-codes "gateway unreachable",
    /// which is actively wrong here (`api.github.com` is not a gateway,
    /// and the user's own gateway may be perfectly reachable). This is
    /// the offline signal `fetch_and_verify` returns when the cache is
    /// empty (SC-4's negative half).
    #[error(
        "module release feed at {url} is unreachable{source_note}",
        source_note = source.as_ref().map(|source| format!(": {source}")).unwrap_or_default()
    )]
    ModuleFeedUnreachable {
        /// The feed or CDN URL that could not be reached.
        url: String,
        #[source]
        source: Option<reqwest::Error>,
    },

    /// No release exists for the pinned tag, or the release carries no
    /// asset of the expected name (Phase 15, SC-1's "unknown version"
    /// refusal). Exit 6 — target state: names BOTH the requested version
    /// and the resolved URL, and (for a missing asset) both the expected
    /// asset name and the names actually present, so the caller never
    /// has to guess which lookup failed or falls back to "latest".
    #[error("module {module:?} version {version:?} not found at {url}: {detail}")]
    ModuleReleaseNotFound {
        /// The [`crate::module::ModuleSpec::id`] being fetched.
        module: String,
        /// The requested version string.
        version: String,
        /// The tag-pinned releases URL that was queried.
        url: String,
        /// What specifically was missing (no release for the tag, or no
        /// matching asset — names the asset actually present).
        detail: String,
    },

    /// Downloaded bytes hash to something other than the release's
    /// published digest — SC-2's hard refusal (Phase 15; this variant is
    /// defined in 15-01, the branch is exercised starting 15-02). Exit 6
    /// — target state: the feed answered and served bytes, but what it
    /// served cannot be trusted. The bytes are discarded (never
    /// persisted to the cache) and BOTH digests are named.
    ///
    /// Payload is BOXED: five inline `String`s put `CoreError` at
    /// exactly clippy's 128-byte `result_large_err` threshold, which
    /// fails `-D warnings` in every crate returning `Result<_,
    /// CoreError>` — `ignition-tui` first. Error paths are cold, so one
    /// allocation on construction is the cheap side of that trade.
    #[error("{0}")]
    ModuleDigestMismatch(Box<ModuleDigestMismatchDetails>),

    /// The module release feed ANSWERED but not usably — rate-limited,
    /// unauthenticated 401/403, 5xx, an unparseable body, an asset with
    /// no published digest, or an insecure downgrade of the asset URL
    /// (Phase 15). Exit 6 — target state: distinct from
    /// [`Self::ModuleFeedUnreachable`] (exit 4 — transport never reached
    /// the feed at all); here the feed DID answer, just not with
    /// something `ign` can safely act on.
    #[error("module release feed at {url} is unusable: {detail}")]
    ModuleFeedUnusable {
        /// The feed or asset URL that answered unusably.
        url: String,
        /// What specifically made the answer unusable.
        detail: String,
    },

    /// A pinned version's upstream digest differs from what's already
    /// cached — D-02's default refusal on `FetchPolicy::Refresh` /
    /// `AcceptUpstreamChange` (Phase 15, 15-02): the feed answered
    /// fine, but what it currently publishes for this version no
    /// longer matches what was verified and cached before. Exit 6 —
    /// target state: names BOTH full digests and the path of the
    /// cached artifact, which is left on disk UNTOUCHED (no path in
    /// `module/` deletes, truncates, or overwrites a cache entry).
    /// `FetchPolicy::AcceptUpstreamChange` is the explicit, documented
    /// override.
    ///
    /// Payload is BOXED for the same reason as
    /// [`Self::ModuleDigestMismatch`] — see that variant.
    #[error("{0}")]
    ModuleDigestChanged(Box<ModuleDigestChangedDetails>),

    /// A declared module id has no matching registry entry (Phase 16,
    /// D-13). A well-formed id that simply isn't registered is a CONFIG
    /// problem, not malformed input (exit 2 belongs to
    /// `validate_module_id`/`validate_version`) and not a Docker
    /// failure (exit 7 is [`Self::Rig`]) — every OTHER module
    /// provisioning refusal (missing artifact, non-file artifact,
    /// relative path, underivable service) stays `CoreError::Rig`.
    /// Exit 3, structurally the [`Self::ProfileNotFound`] shape: names
    /// both the bad id and every id that IS registered.
    #[error("module {id:?} is not registered (known modules: {known:?})")]
    ModuleNotRegistered {
        /// The declared id with no matching [`crate::module::ModuleSpec`].
        id: String,
        /// Every currently registered [`crate::module::ModuleSpec::id`].
        known: Vec<String>,
    },

    /// The gateway ANSWERED `DELETE /data/api/v1/modules/uninstall` with
    /// HTTP 200 but the body says `{"success": false, "failedUninstalls":
    /// {"uninstall": […]}}` — the denial-rides-200 class
    /// ([`Self::ImportDenied`]'s precedent) applied to module uninstall
    /// (Phase 19, D-19-03): live-verified that a stock module, a bogus
    /// id, and a still-mounted module ALL answer 200 with
    /// `success:false`. An unparseable body, a missing `success`, or an
    /// absent `failedUninstalls` all map here too — absence of detail
    /// must never degrade into a reported success. Exit 6 — target
    /// state: names both the registry id and the gateway id that was
    /// sent, plus every failed id the gateway reported (or the sent id
    /// itself when the gateway gave no detail).
    #[error(
        "gateway refused to uninstall module {module_id:?} ({gateway_module_id}): {}",
        failed.join(", ")
    )]
    ModuleUninstallDenied {
        /// The registry slug (`git`) the caller named.
        module_id: String,
        /// The gateway's own id ([`crate::module::ModuleSpec::gateway_module_id`])
        /// sent in the request.
        gateway_module_id: String,
        /// `failedUninstalls.uninstall` verbatim, or `[gateway_module_id]`
        /// when the gateway's body carried no usable detail.
        failed: Vec<String>,
        /// URL of the refused DELETE, when known.
        endpoint: Option<String>,
    },
}

/// Payload of [`CoreError::ModuleDigestMismatch`], boxed to keep
/// `CoreError` under clippy's `result_large_err` threshold.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleDigestMismatchDetails {
    /// The [`crate::module::ModuleSpec::id`] being fetched.
    pub module: String,
    /// The requested version string.
    pub version: String,
    /// The asset URL the mismatched bytes were downloaded from.
    pub url: String,
    /// The release's published sha256 digest.
    pub expected: String,
    /// The sha256 digest of the bytes actually downloaded.
    pub actual: String,
}

/// Payload of [`CoreError::ModuleDigestChanged`], boxed to keep
/// `CoreError` under clippy's `result_large_err` threshold.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleDigestChangedDetails {
    /// The [`crate::module::ModuleSpec::id`] being fetched.
    pub module: String,
    /// The requested version string.
    pub version: String,
    /// The digest of the artifact already cached for this version.
    pub cached_digest: String,
    /// The digest the feed currently publishes for this version.
    pub upstream_digest: String,
    /// Path of the untouched, still-usable cached artifact.
    pub cached_path: String,
}

impl std::fmt::Display for ModuleDigestMismatchDetails {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "module {:?} version {:?} digest mismatch at {}: expected {}, got {}",
            self.module, self.version, self.url, self.expected, self.actual
        )
    }
}

impl std::fmt::Display for ModuleDigestChangedDetails {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "module {:?} version {:?} digest changed upstream: cached {}, \
             upstream now reports {} (cached artifact kept at {})",
            self.module, self.version, self.cached_digest, self.upstream_digest, self.cached_path
        )
    }
}

impl CoreError {
    /// Stable machine slug — public contract, never respell.
    pub fn code(&self) -> &'static str {
        match self {
            Self::Internal(_) => "internal",
            Self::ConfirmationRequired { .. } => "confirmation_required",
            Self::InvalidImportFile { .. } => "invalid_import_file",
            Self::ImportDenied { .. } => "import_denied",
            Self::InvalidInput { .. } => "invalid_input",
            Self::ProfileNotFound { .. } => "profile_not_found",
            Self::NoActiveProfile => "no_active_profile",
            Self::SecretUnavailable { .. } => "secret_unavailable",
            Self::PasswordUnavailable { .. } => "password_unavailable",
            Self::ConfigInvalid { .. } => "config_invalid",
            Self::PollIntervalTooSmall { .. } => "poll_interval_too_small",
            Self::Network { .. } => "network_error",
            Self::Auth { .. } => "auth_rejected",
            Self::GatewayTooOld { .. } => "gateway_too_old",
            Self::GatewayNotCommissioned { .. } => "gateway_not_commissioned",
            Self::GatewayRestarting { .. } => "gateway_restarting",
            Self::NotFound { .. } => "not_found",
            Self::ProjectExists { .. } => "project_exists",
            Self::ResourceBinary { .. } => "resource_binary",
            Self::TrialNotExpired { .. } => "trial_not_expired",
            Self::ProviderNotFound { .. } => "provider_not_found",
            Self::RoutesNotDeployed { .. } => "routes_not_deployed",
            Self::WebdevUnlicensed { .. } => "webdev_unlicensed",
            Self::RouteVersionMismatch { .. } => "route_version_mismatch",
            Self::WebdevRouteError { .. } => "webdev_route_error",
            Self::TagCollision { .. } => "tag_collision",
            Self::AlarmJournalMissing { .. } => "alarm_journal_missing",
            Self::SessionNotPrunable { .. } => "session_not_prunable",
            Self::Rig(_) => "rig_error",
            Self::EamNotController { .. } => "eam_not_controller",
            Self::ProviderRootUnsupported { .. } => "provider_root_unsupported",
            Self::EamTaskTypeRefused { .. } => "eam_task_type_refused",
            Self::EamTaskInFlight { .. } => "eam_task_in_flight",
            Self::ScriptExecNotConfigured { .. } => "script_exec_not_configured",
            Self::LintToolAbsent => "lint_tool_absent",
            Self::NodeToolAbsent { .. } => "node_tool_absent",
            Self::GatewayClientError { .. } => "gateway_client_error",
            Self::BundleNotAvailable { .. } => "bundle_not_available",
            Self::ModuleFeedUnreachable { .. } => "module_feed_unreachable",
            Self::ModuleReleaseNotFound { .. } => "module_release_not_found",
            Self::ModuleDigestMismatch(..) => "module_digest_mismatch",
            Self::ModuleFeedUnusable { .. } => "module_feed_unusable",
            Self::ModuleDigestChanged(..) => "module_digest_changed",
            Self::ModuleNotRegistered { .. } => "module_not_registered",
            Self::ModuleUninstallDenied { .. } => "module_uninstall_denied",
        }
    }

    /// The LOCKED exit-code mapping — the only place exit codes are decided.
    pub fn exit_code(&self) -> u8 {
        match self {
            Self::Internal(_) => 1,
            Self::ConfirmationRequired { .. }
            | Self::InvalidImportFile { .. }
            | Self::InvalidInput { .. }
            | Self::GatewayClientError { .. } => 2,
            Self::ProfileNotFound { .. }
            | Self::NoActiveProfile
            | Self::SecretUnavailable { .. }
            | Self::PasswordUnavailable { .. }
            | Self::ConfigInvalid { .. }
            | Self::PollIntervalTooSmall { .. }
            | Self::ModuleNotRegistered { .. } => 3,
            Self::Network { .. } | Self::ModuleFeedUnreachable { .. } => 4,
            Self::Auth { .. } => 5,
            Self::GatewayTooOld { .. }
            | Self::GatewayNotCommissioned { .. }
            | Self::GatewayRestarting { .. }
            | Self::NotFound { .. }
            | Self::ProjectExists { .. }
            | Self::ResourceBinary { .. }
            | Self::TrialNotExpired { .. }
            | Self::ProviderNotFound { .. }
            | Self::RoutesNotDeployed { .. }
            | Self::WebdevUnlicensed { .. }
            | Self::RouteVersionMismatch { .. }
            | Self::WebdevRouteError { .. }
            | Self::TagCollision { .. }
            | Self::AlarmJournalMissing { .. }
            | Self::SessionNotPrunable { .. }
            | Self::ImportDenied { .. }
            | Self::EamNotController { .. }
            | Self::ProviderRootUnsupported { .. }
            | Self::EamTaskTypeRefused { .. }
            | Self::EamTaskInFlight { .. }
            | Self::ScriptExecNotConfigured { .. }
            | Self::LintToolAbsent
            | Self::NodeToolAbsent { .. }
            | Self::BundleNotAvailable { .. }
            | Self::ModuleReleaseNotFound { .. }
            | Self::ModuleDigestMismatch(..)
            | Self::ModuleFeedUnusable { .. }
            | Self::ModuleDigestChanged(..)
            | Self::ModuleUninstallDenied { .. } => 6,
            Self::Rig(_) => 7,
        }
    }

    /// Actionable next step (CORE-05). Every class carries one.
    pub fn hint(&self) -> Option<String> {
        match self {
            Self::Internal(_) => Some(
                "internal errors are bugs; re-run with -vv and report the \
                 diagnostics output"
                    .to_string(),
            ),
            Self::ConfirmationRequired { .. } => Some(
                "this operation is destructive; re-run with --yes or set \
                   IGNITION_YES=1"
                    .to_string(),
            ),
            Self::InvalidImportFile { .. } => Some(
                "import expects a project-export ZIP (PK\\x03\\x04 magic) of at \
                   most 512 MB — pass a file produced by `ign project export` \
                   via --file (or `-` to pipe one on stdin)"
                    .to_string(),
            ),
            Self::ImportDenied { problem, .. } => Some(format!(
                "the gateway refused the import over a 200 answer — the problem \
                   text above is the gateway's own; `ign project export` of the \
                   current state is the honest baseline for hand-editing ({problem})"
            )),
            Self::InvalidInput { reason } => Some(
                if reason == TUI_TTY_REFUSAL_REASON {
                    // The ONE contextual InvalidInput hint (06-07): the
                    // TTY refusal's fix is terminal-related — the
                    // --file/stdin default is meaningless for a pipe.
                    "run `ign tui` in an interactive terminal (the cockpit \
                     needs a TTY on stdout — not a pipe or redirect)"
                } else if reason.starts_with(LOSS_GATE_REFUSAL_REASON_PREFIX) {
                    // The loss-gate refusal (11-07): the message above already names
                    // every finding and ends with the actionable guidance — the hint
                    // restates it for envelope readers instead of the file-read
                    // default, which is meaningless here (the file WAS readable).
                    "the loss report above names what this import would drop or \
                     coerce — re-run with --yes to import anyway"
                } else {
                    "fix the input source — a readable file path via --file, or `-` \
                     to pipe the content on stdin"
                }
                .to_string(),
            ),
            Self::ProfileNotFound { known, .. } => Some(if known.is_empty() {
                "no profiles configured yet; run `ign profile add` to create \
                     one"
                .to_string()
            } else {
                format!(
                    "known profiles: {}; run `ign profile add` to add another",
                    known.join(", ")
                )
            }),
            Self::NoActiveProfile => Some(
                "pass --profile NAME, set IGNITION_PROFILE, or mark a profile \
                 active with `ign profile use`"
                    .to_string(),
            ),
            Self::SecretUnavailable { profile } => Some(format!(
                "set IGNITION_TOKEN (or token_env in the profile), or store a \
                 keyring entry: service 'ignition-cli', user 'profile:{profile}'"
            )),
            Self::PasswordUnavailable { .. } => Some(
                "ign adopt logs in with the gateway admin password — export \
                 IGNITION_PASSWORD (env-only, never a flag)"
                    .to_string(),
            ),
            Self::ConfigInvalid { .. } => Some(
                "verify the config file is valid TOML with [profiles.NAME] \
                 tables; `ign profile add` writes a known-good one"
                    .to_string(),
            ),
            Self::PollIntervalTooSmall { profile } => Some(format!(
                "set poll_interval_secs to 1 or higher in [profiles.{profile}], \
                 or remove the key to use the default cadence"
            )),
            Self::Network {
                url,
                observation,
                ..
            } => Some(match observation {
                Some(observation) => format!(
                    "the gateway answered but no terminal state arrived before the deadline — \
                     the last observation was: {observation}; address that state, not the \
                     connection ({url})"
                ),
                None => format!("check the gateway is reachable at {url} (host, port, VPN, TLS)"),
            }),
            Self::Auth { status, .. } => Some(match status {
                401 => {
                    // 401 = token not recognized — the #1 setup failure is
                    // a key-only header (verified: key-only → 401, full
                    // `name:key` → 200; Basic is dead on 8.3 /data).
                    "token not recognized — the X-Ignition-API-Token header must be the FULL `name:key` string from the gateway UI (Platform→Security→API Keys); Basic auth does not work on 8.3 /data routes — create an API token"
                }
                403 => {
                    // 403 = recognized but under-permitted (verified
                    // semantics; see 02-RESEARCH Auth §4/§5).
                    "token recognized but under-permitted — Ignition token setup is three parts: (1) token holds an adequate security level, (2) gateway read/write permissions include that level, (3) 'Require secure connections' is unchecked for http gateways; run `ign doctor` for a diagnosis"
                }
                _ => "check the credential; Ignition token setup is three parts: security level, write permissions, token assignment",
            }
            .to_string()),
            Self::GatewayTooOld { minimum, .. } => {
                Some(format!("upgrade the gateway to at least {minimum}"))
            }
            Self::GatewayNotCommissioned { .. } => Some(
                "open http://<host>:<port>/welcome in a browser and complete the \
                 commissioning wizard"
                    .to_string(),
            ),
            Self::GatewayRestarting { .. } => Some(
                "wait for readiness with `ign wait restart` or retry in ~1 minute".to_string(),
            ),
            Self::NotFound { .. } => Some(
                "check the id/path; a 404 JSON 'No route match' body can also mean \
                  a pre-8.3 gateway"
                    .to_string(),
            ),
            Self::ProjectExists { .. } => Some(
                "the default collision policy refuses to overwrite; re-run with \
                  --collision-policy overwrite to replace it — overwrite \
                  REPLACES the ENTIRE project (resources absent from the ZIP \
                  are deleted; merge is Designer-only)"
                    .to_string(),
            ),
            Self::ResourceBinary { .. } => Some(
                "resource content is binary — use `ign project export`/`import` \
                  for data.bin-class resources"
                    .to_string(),
            ),
            Self::TrialNotExpired { .. } => Some(
                "wait for the trial to expire (watch `ign rig trial status`), or \
                  run `ign rig reset --yes` for a completely fresh trial volume"
                    .to_string(),
            ),
            Self::RoutesNotDeployed { route, .. } => Some(
                // CONTENT-ADDRESSED off the route (the
                // TUI_TTY_REFUSAL_REASON / loss-gate prose-prefix
                // pattern, same file): the testing bundle is a
                // SEPARATE deploy with its own flag, so the generic
                // `ign webdev deploy` hint would send the caller to a
                // command that does not install it. No new variant,
                // no new slug — the exit tables are untouched.
                if route.starts_with(TESTING_ROUTE_PREFIX) {
                    "run `ign webdev deploy --with-testing` to install the gateway \
                      testing bundle into the project (or bootstrap it in one shot \
                      with `ign adopt --project NAME --testing`), then retry"
                } else {
                    "run `ign webdev deploy` to install the CLI's WebDev routes into \
                      the gateway, then retry"
                }
                .to_string(),
            ),
            Self::WebdevUnlicensed { .. } => Some(
                "license the gateway — the WebDev module answers 402 while \
                  unlicensed (on a rig, `ign rig trial reset --yes` restarts an \
                  expired trial)"
                    .to_string(),
            ),
            Self::RouteVersionMismatch { deployed, expected, .. } => {
                // Direction decides the fix (roadmap criterion): an older
                // deployed route → redeploy from THIS binary; a NEWER
                // deployed route → this CLI is behind (the route bundle
                // travels with the binary). Same slug either way.
                let newer = semver::Version::parse(deployed)
                    .ok()
                    .zip(semver::Version::parse(expected).ok())
                    .is_some_and(|(deployed, expected)| deployed > expected);
                Some(if newer {
                    "the deployed routes are NEWER than this CLI — update ign \
                      (the route bundle travels with the binary)"
                        .to_string()
                } else {
                    "run `ign webdev deploy` to redeploy the route version \
                      this CLI expects"
                        .to_string()
                })
            }
            Self::ProviderNotFound { .. } => Some(
                "check the provider name; `ign tags provider list` shows the \
                  gateway's tag providers"
                    .to_string(),
            ),
            Self::TagCollision { .. } => Some(
                "re-run with --collision-policy overwrite to replace the \
                  existing tags (destructive: requires --yes)"
                    .to_string(),
            ),
            Self::AlarmJournalMissing { .. } => Some(
                "alarm history needs a journal profile — provision a database \
                  connection + alarm-journal profile on the gateway (and point \
                  the general-alarm-settings singleton at it), then retry; see \
                  the README 'Alarm history' section"
                    .to_string(),
            ),
            Self::SessionNotPrunable { .. } => Some(
                "close the Designer first — prune removes stale entries only".to_string(),
            ),
            Self::WebdevRouteError { code, .. } => Some(if code == "secret_required" || code == "secret_mismatch" {
                "the scriptExec route is secret-gated — deploy it with `ign \
                  webdev deploy --with-script-exec` (the secret is generated \
                  and stored in the profile config at 0600); a mismatch means \
                  the route was deployed with a different secret: redeploy or \
                  pass --rotate-secret"
                    .to_string()
            } else {
                "the deployed route refused the action — the code and message \
                  are the route's stable contract; `ign webdev status` \
                  diagnoses the deployment"
                    .to_string()
            }),
            Self::EamNotController { .. } => Some(
                "flip the gateway's EAM role: config-resource PUT on \
                   com.inductiveautomation.eam/module-settings with \
                   installMode \"Controller\" (array body carrying the current \
                   signature) — a manual gateway-role decision this CLI \
                   deliberately does not automate; see the README 'EAM tasks' \
                   section"
                    .to_string(),
            ),
            Self::ProviderRootUnsupported { .. } => Some(
                "target a subtree path like [provider]folder — provider-ROOT \
                   forms ([default] alone, or a bare provider name) need an \
                   RPC context WebDev threads don't carry (8.3.3); subtree \
                   paths are the supported form"
                    .to_string(),
            ),
            Self::EamTaskTypeRefused { .. } => Some(
                "restore/install/upgrade tasks dispatch fleet-wide (every \
                   agent target); run them from the Ignition EAM console — \
                   EXT-03 (v2) will scope them into the CLI"
                    .to_string(),
            ),
            Self::EamTaskInFlight { .. } => Some(
                "complete or delete the leftover '(forced)' run from the EAM \
                   console — no ign verb deletes runs; the slot frees once the \
                   run is resolved"
                    .to_string(),
            ),
            Self::ScriptExecNotConfigured { .. } => Some(
                "run `ign webdev deploy --with-script-exec` to deploy the route and \
                  generate + persist its secret (the deploy flag IS the opt-in — \
                  `ign script run` has no --yes by design)"
                    .to_string(),
            ),
            Self::LintToolAbsent => Some(
                "install the linter: `uv tool install ignition-lint-toolkit` \
                 (or `pip install ignition-lint-toolkit`) — \
                 github.com/TheThoughtagen/ignition-lint; then re-run with \
                 ignition-lint on PATH"
                    .to_string(),
            ),
            // The SAME string `ign e2e doctor`'s node row hands out —
            // a user who hits this refusal and then runs the doctor
            // must not be given two wordings of one instruction.
            Self::NodeToolAbsent { .. } => {
                Some(crate::actions::e2e::NODE_INSTALL_HINT.to_string())
            }
            Self::GatewayClientError { .. } => Some(
                "the gateway rejected this request — the body above is the \
                 gateway's own answer; fix the path/method/body, or use a \
                 curated `ign` command when one exists"
                    .to_string(),
            ),
            Self::BundleNotAvailable { .. } => Some(
                "generate a fresh bundle with `ign diagnostics bundle generate`, \
                 then wait again — the gateway reports no current bundle and \
                 polling cannot produce one"
                    .to_string(),
            ),
            Self::ModuleFeedUnreachable { .. } => Some(
                "check network reachability to the module release feed — an \
                 already-cached version works fully offline, so this only \
                 blocks a first-time fetch of a new version"
                    .to_string(),
            ),
            Self::ModuleReleaseNotFound {
                module, version, ..
            } => Some(format!(
                "check that {module} version {version} exists as a release upstream \
                 (the tag and asset name must match exactly) — this CLI never falls \
                 back to \"latest\""
            )),
            Self::ModuleDigestMismatch(d) => Some(format!(
                "the downloaded bytes for {} version {} do not match \
                 the feed's published digest — do not trust this artifact; nothing \
                 was cached, so re-running the fetch tries again from scratch",
                d.module,
                d.version
            )),
            Self::ModuleFeedUnusable { .. } => Some(
                "the module release feed answered but was not usable — if the \
                 detail names a rate limit, wait and retry; otherwise the feed's \
                 response itself needs investigation"
                    .to_string(),
            ),
            Self::ModuleDigestChanged(d) => Some(format!(
                "upstream re-released this version with different bytes — the cached \
                 artifact at {} is still there and usable offline; re-run with \
                 FetchPolicy::AcceptUpstreamChange to deliberately accept and verify the \
                 new bytes",
                d.cached_path
            )),
            Self::Rig(_) => Some(
                "check Docker is running and inspect the rig containers \
                 (docker ps)"
                    .to_string(),
            ),
            Self::ModuleNotRegistered { known, .. } => Some(if known.is_empty() {
                "no modules are registered in this build of ign".to_string()
            } else {
                format!(
                    "known module ids: {} — check the id passed to --with-module \
                     or declared under [rigs.NAME.modules.*]",
                    known.join(", ")
                )
            }),
            Self::ModuleUninstallDenied { .. } => Some(
                "the gateway refuses to uninstall a module whose .modl is still \
                 mounted — remove it from [rigs.NAME.modules], run `ign rig up` \
                 so the mount goes, then retry; a successful uninstall is NOT \
                 undone by re-declaring the module — recovery today means \
                 `ign rig reset --yes`, which destroys the rig's data volume"
                    .to_string(),
            ),
        }
    }

    /// URL/path of the request involved, when one was — populated for the
    /// network, auth, and target-state classes (CORE-05).
    pub fn endpoint(&self) -> Option<String> {
        match self {
            Self::Network { url, .. } => Some(url.clone()),
            Self::Auth { endpoint, .. } => endpoint.clone(),
            Self::GatewayTooOld { endpoint, .. }
            | Self::GatewayNotCommissioned { endpoint }
            | Self::GatewayRestarting { endpoint }
            | Self::NotFound { endpoint }
            | Self::ProjectExists { endpoint, .. }
            | Self::ResourceBinary { endpoint, .. }
            | Self::TrialNotExpired { endpoint, .. }
            | Self::ProviderNotFound { endpoint, .. }
            | Self::RoutesNotDeployed { endpoint, .. }
            | Self::WebdevUnlicensed { endpoint }
            | Self::RouteVersionMismatch { endpoint, .. }
            | Self::WebdevRouteError { endpoint, .. }
            | Self::TagCollision { endpoint, .. }
            | Self::AlarmJournalMissing { endpoint }
            | Self::SessionNotPrunable { endpoint, .. }
            | Self::ImportDenied { endpoint, .. }
            | Self::EamNotController { endpoint }
            | Self::ProviderRootUnsupported { endpoint }
            | Self::EamTaskInFlight { endpoint, .. }
            | Self::ModuleUninstallDenied { endpoint, .. } => endpoint.clone(),
            Self::ModuleFeedUnreachable { url, .. }
            | Self::ModuleReleaseNotFound { url, .. }
            | Self::ModuleFeedUnusable { url, .. } => Some(url.clone()),
            // Boxed payload, so it cannot share the or-pattern above.
            Self::ModuleDigestMismatch(d) => Some(d.url.clone()),
            _ => None,
        }
    }

    /// The `ign tui` TTY refusal (06-07): InvalidInput carrying the
    /// ONE reason whose hint is terminal-contextual — see
    /// [`TUI_TTY_REFUSAL_REASON`]. Same slug, same exit 2 (frozen
    /// taxonomy; only the hint differs).
    pub fn tui_tty_refusal() -> Self {
        Self::InvalidInput {
            reason: TUI_TTY_REFUSAL_REASON.to_string(),
        }
    }

    /// Build the LOCKED failure envelope for this error (field order is part
    /// of the golden contract: `ok`, `profile`, `error` then `code`,
    /// `message`, `endpoint`, `hint`).
    pub fn envelope<'a>(&self, profile: Option<&'a str>) -> ErrorEnvelope<'a> {
        ErrorEnvelope {
            ok: false,
            profile,
            error: ErrorBody {
                code: self.code(),
                message: self.to_string(),
                endpoint: self.endpoint(),
                hint: self.hint(),
            },
        }
    }
}

/// LOCKED failure envelope shape: exactly the top-level fields `ok`,
/// `profile`, `error` — changing the set is a breaking change for agents.
#[derive(Debug, Serialize)]
pub struct ErrorEnvelope<'a> {
    /// Always `false` in this envelope.
    pub ok: bool,
    /// Active profile echoed in every output (CORE-01); `None` until config
    /// resolution lands.
    pub profile: Option<&'a str>,
    /// The typed error body.
    pub error: ErrorBody,
}

/// LOCKED error body: `code` (stable slug), `message` (human-readable),
/// `endpoint` (when a request was involved), `hint` (actionable next step).
#[derive(Debug, Serialize)]
pub struct ErrorBody {
    /// Stable slug from [`CoreError::code`] — never respelled.
    pub code: &'static str,
    /// Human-readable description.
    pub message: String,
    /// URL/path when a request was involved.
    pub endpoint: Option<String>,
    /// Actionable next step.
    pub hint: Option<String>,
}

#[cfg(test)]
mod tests {
    use super::{
        CoreError, ErrorBody, ErrorEnvelope, GATEWAY_CLIENT_BODY_CAP_BYTES,
        GATEWAY_CLIENT_BODY_TRUNCATION_MARKER, LOSS_GATE_REFUSAL_REASON_PREFIX,
        ModuleDigestChangedDetails, ModuleDigestMismatchDetails, TESTING_ROUTE_PREFIX,
        truncate_api_body,
    };

    /// Build a real `reqwest::Error` for the Network variant: a request to
    /// an unroutable loopback port fails at connect time (instant refusal —
    /// `reqwest::Error` has no public constructor).
    fn network_error() -> CoreError {
        // reqwest is built with `rustls-no-provider`, so a raw
        // `reqwest::get` panics unless the process-wide provider is
        // installed. In a full lib-test run some other test happens to
        // install it first; running the error tests ALONE (which the
        // exit-table verify command does) hit the panic. The install is
        // idempotent and documented for exactly this use.
        crate::client::install_crypto_provider();
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .expect("test runtime");
        let url = "http://127.0.0.1:1";
        let source = rt
            .block_on(reqwest::get(url))
            .expect_err("request to an unroutable port must fail");
        CoreError::Network {
            url: url.to_string(),
            source: Some(source),
            observation: None,
        }
    }

    /// The [`CoreError::ModuleFeedUnreachable`] twin of [`network_error`]
    /// — a real `reqwest::Error` from an unroutable loopback port, for
    /// the offline-module-feed exit-4 case.
    fn module_feed_unreachable_error() -> CoreError {
        crate::client::install_crypto_provider();
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .expect("test runtime");
        let url = "http://127.0.0.1:1";
        let source = rt
            .block_on(reqwest::get(url))
            .expect_err("request to an unroutable port must fail");
        CoreError::ModuleFeedUnreachable {
            url: url.to_string(),
            source: Some(source),
        }
    }

    /// Pitfall-5 guard: the FULL 1–7 taxonomy enumerated on day one so no
    /// later phase can silently renumber it or respell a slug. The slugs are
    /// asserted against literals — that IS the stability contract.
    #[test]
    fn exit_code_mapping_enumerated() {
        let cases: Vec<(CoreError, u8, &'static str)> = vec![
            (CoreError::Internal("boom".into()), 1, "internal"),
            (
                CoreError::ConfirmationRequired {
                    operation: "project download".into(),
                },
                2,
                "confirmation_required",
            ),
            (
                CoreError::InvalidImportFile {
                    reason: "missing ZIP magic".into(),
                },
                2,
                "invalid_import_file",
            ),
            (
                CoreError::InvalidInput {
                    reason: "cannot read put.json".into(),
                },
                2,
                "invalid_input",
            ),
            (
                CoreError::ProfileNotFound {
                    name: "nope".into(),
                    known: vec!["dev".into()],
                },
                3,
                "profile_not_found",
            ),
            (CoreError::NoActiveProfile, 3, "no_active_profile"),
            (
                CoreError::SecretUnavailable {
                    profile: "dev".into(),
                },
                3,
                "secret_unavailable",
            ),
            (
                CoreError::PasswordUnavailable {
                    profile: "dev".into(),
                },
                3,
                "password_unavailable",
            ),
            (
                CoreError::ConfigInvalid {
                    reason: "bad toml".into(),
                },
                3,
                "config_invalid",
            ),
            (
                CoreError::PollIntervalTooSmall {
                    profile: "dev".into(),
                },
                3,
                "poll_interval_too_small",
            ),
            (network_error(), 4, "network_error"),
            (
                CoreError::Auth {
                    status: 401,
                    endpoint: None,
                },
                5,
                "auth_rejected",
            ),
            (
                CoreError::GatewayTooOld {
                    found: "8.1.0".into(),
                    minimum: "8.3.1".into(),
                    endpoint: None,
                },
                6,
                "gateway_too_old",
            ),
            (
                CoreError::GatewayNotCommissioned {
                    endpoint: Some("http://gw:8088/data/api/v1/gateway-info".into()),
                },
                6,
                "gateway_not_commissioned",
            ),
            (
                CoreError::GatewayRestarting {
                    endpoint: Some("http://gw:8088/data/api/v1/gateway-info".into()),
                },
                6,
                "gateway_restarting",
            ),
            (
                CoreError::NotFound {
                    endpoint: Some("http://gw:8088/data/api/v1/designer/42".into()),
                },
                6,
                "not_found",
            ),
            (
                CoreError::ProjectExists {
                    name: "PlantFloor".into(),
                    endpoint: None,
                },
                6,
                "project_exists",
            ),
            (
                CoreError::ResourceBinary {
                    path: "com.x/perspective/session-permissions".into(),
                    endpoint: None,
                },
                6,
                "resource_binary",
            ),
            (
                CoreError::TrialNotExpired {
                    remaining_s: 6590,
                    endpoint: Some("http://localhost:9088/data/api/v1/trial".into()),
                },
                6,
                "trial_not_expired",
            ),
            (
                CoreError::ProviderNotFound {
                    name: "nope".into(),
                    endpoint: Some("/data/api/v1/resources/find/ignition/tag-provider/nope".into()),
                },
                6,
                "provider_not_found",
            ),
            (
                CoreError::RoutesNotDeployed {
                    project: "ign-cli".into(),
                    route: "tags".into(),
                    endpoint: Some("/system/webdev/ign-cli/cli/tags".into()),
                },
                6,
                "routes_not_deployed",
            ),
            (
                CoreError::WebdevUnlicensed {
                    endpoint: Some("/system/webdev/ign-cli/cli/tags".into()),
                },
                6,
                "webdev_unlicensed",
            ),
            (
                CoreError::RouteVersionMismatch {
                    route: "tags".into(),
                    deployed: "0.9.0".into(),
                    expected: "1.0.0".into(),
                    endpoint: Some("/system/webdev/ign-cli/cli/tags".into()),
                },
                6,
                "route_version_mismatch",
            ),
            (
                CoreError::WebdevRouteError {
                    code: "route_error".into(),
                    message: "boom".into(),
                    endpoint: Some("/system/webdev/ign-cli/cli/tags".into()),
                },
                6,
                "webdev_route_error",
            ),
            (
                CoreError::TagCollision {
                    provider: "p5import".into(),
                    names: vec!["T1".into(), "P5".into()],
                    endpoint: Some("/system/webdev/ign-cli/cli/tags".into()),
                },
                6,
                "tag_collision",
            ),
            (
                CoreError::AlarmJournalMissing {
                    endpoint: Some("/system/webdev/ign-cli/cli/alarms".into()),
                },
                6,
                "alarm_journal_missing",
            ),
            (
                CoreError::ImportDenied {
                    project: "PlantFloor".into(),
                    problem: "resource already exists: ResourceId{resourcePath=com.example, collectionName=views}".into(),
                    endpoint: Some("http://gw:8088/data/api/v1/projects/import/PlantFloor?overwrite=true".into()),
                },
                6,
                "import_denied",
            ),
            (
                CoreError::SessionNotPrunable {
                    id: "d-live-1".into(),
                    endpoint: Some("http://gw:8088/data/api/v1/designer/d-live-1".into()),
                },
                6,
                "session_not_prunable",
            ),
            (
                CoreError::EamNotController {
                    endpoint: Some("http://gw:8088/data/eam/api/v1/eam-tasks/history".into()),
                },
                6,
                "eam_not_controller",
            ),
            (
                CoreError::ProviderRootUnsupported {
                    endpoint: Some("/system/webdev/ign-cli/cli/tagConfig".into()),
                },
                6,
                "provider_root_unsupported",
            ),
            (
                CoreError::EamTaskTypeRefused {
                    task_type: "eam_remoteUpgrade".into(),
                },
                6,
                "eam_task_type_refused",
            ),
            (
                CoreError::EamTaskInFlight {
                    task: "cli-research-backup".into(),
                    detail: "Task 'cli-research-backup (forced)' already exists! It must be completed or deleted before another task of this type can be force executed.".into(),
                    endpoint: Some(
                        "http://gw:8088/data/eam/api/v1/eam-tasks/force/eam/cli-research-backup"
                            .into(),
                    ),
                },
                6,
                "eam_task_in_flight",
            ),
            (
                CoreError::ScriptExecNotConfigured {
                    profile: "dev".into(),
                },
                6,
                "script_exec_not_configured",
            ),
            (CoreError::LintToolAbsent, 6, "lint_tool_absent"),
            (
                CoreError::NodeToolAbsent {
                    tool: "node".into(),
                },
                6,
                "node_tool_absent",
            ),
            (
                CoreError::BundleNotAvailable {
                    state: "Invalid".into(),
                },
                6,
                "bundle_not_available",
            ),
            (
                CoreError::GatewayClientError {
                    status: 400,
                    endpoint: "http://gw:8088/data/api/v1/nonexistent".into(),
                    body: r#"{"error":{"code":"NOT_FOUND"}}"#.into(),
                },
                2,
                "gateway_client_error",
            ),
            (CoreError::Rig("compose up failed".into()), 7, "rig_error"),
            (
                module_feed_unreachable_error(),
                4,
                "module_feed_unreachable",
            ),
            (
                CoreError::ModuleReleaseNotFound {
                    module: "git".into(),
                    version: "99.99.99".into(),
                    url: "https://api.github.com/repos/WhiskeyHouse/ignition-git-module/releases/tags/v99.99.99".into(),
                    detail: "no release exists for tag \"v99.99.99\"".into(),
                },
                6,
                "module_release_not_found",
            ),
            (
                CoreError::ModuleDigestMismatch(Box::new(ModuleDigestMismatchDetails {
                    module: "git".into(),
                    version: "2.3.4".into(),
                    url: "https://release-assets.githubusercontent.com/Git-2.3.4-signed.modl".into(),
                    expected: "b".repeat(64),
                    actual: "c".repeat(64),
                })),
                6,
                "module_digest_mismatch",
            ),
            (
                CoreError::ModuleFeedUnusable {
                    url: "https://api.github.com/repos/WhiskeyHouse/ignition-git-module/releases/tags/v2.3.4".into(),
                    detail: "rate limit exceeded".into(),
                },
                6,
                "module_feed_unusable",
            ),
            (
                CoreError::ModuleDigestChanged(Box::new(ModuleDigestChangedDetails {
                    module: "git".into(),
                    version: "2.3.4".into(),
                    cached_digest: "a".repeat(64),
                    upstream_digest: "b".repeat(64),
                    cached_path: "/cache/modules/git/2.3.4-aaaa.modl".into(),
                })),
                6,
                "module_digest_changed",
            ),
            (
                CoreError::ModuleNotRegistered {
                    id: "bogus".into(),
                    known: vec!["git".into()],
                },
                3,
                "module_not_registered",
            ),
            (
                CoreError::ModuleUninstallDenied {
                    module_id: "git".into(),
                    gateway_module_id: "com.axone_io.ignition.git".into(),
                    failed: vec!["com.axone_io.ignition.git".into()],
                    endpoint: Some(
                        "http://gw:8088/data/api/v1/modules/uninstall".into(),
                    ),
                },
                6,
                "module_uninstall_denied",
            ),
        ];
        for (err, code, slug) in cases {
            assert_eq!(err.exit_code(), code, "wrong exit code for: {err}");
            assert_eq!(err.code(), slug, "unstable slug for: {err}");
        }
    }

    /// The (exit_code, slug) literal table the Three-Place rule syncs.
    /// DUPLICATED from [`exit_code_mapping_enumerated`]'s triple list by
    /// design: that test is the literal source of truth (enum ↔ literals);
    /// this flat table is what the README cross-check runs against, so a
    /// drift inside error.rs surfaces as a disagreement instead of silently
    /// re-shuffling both sides. Keep the two lists in lockstep — the
    /// enumerated test fails if the enum respells/renumbers, and a stale
    /// copy here fails the README check below until updated.
    const EXIT_SLUG_LITERALS: &[(u8, &str)] = &[
        (1, "internal"),
        (2, "confirmation_required"),
        (2, "invalid_import_file"),
        (2, "invalid_input"),
        (2, "gateway_client_error"),
        (3, "profile_not_found"),
        (3, "no_active_profile"),
        (3, "secret_unavailable"),
        (3, "password_unavailable"),
        (3, "config_invalid"),
        (3, "poll_interval_too_small"),
        (3, "module_not_registered"),
        (4, "network_error"),
        (5, "auth_rejected"),
        (6, "gateway_too_old"),
        (6, "gateway_not_commissioned"),
        (6, "gateway_restarting"),
        (6, "not_found"),
        (6, "project_exists"),
        (6, "resource_binary"),
        (6, "trial_not_expired"),
        (6, "provider_not_found"),
        (6, "routes_not_deployed"),
        (6, "webdev_unlicensed"),
        (6, "route_version_mismatch"),
        (6, "webdev_route_error"),
        (6, "tag_collision"),
        (6, "alarm_journal_missing"),
        (6, "import_denied"),
        (6, "session_not_prunable"),
        (6, "eam_not_controller"),
        (6, "eam_task_type_refused"),
        (6, "eam_task_in_flight"),
        (6, "script_exec_not_configured"),
        (6, "lint_tool_absent"),
        (6, "node_tool_absent"),
        (6, "provider_root_unsupported"),
        (6, "bundle_not_available"),
        (4, "module_feed_unreachable"),
        (6, "module_release_not_found"),
        (6, "module_digest_mismatch"),
        (6, "module_feed_unusable"),
        (6, "module_digest_changed"),
        (6, "module_uninstall_denied"),
        (7, "rig_error"),
    ];

    /// Parse the README's exit-code table: rows `| <exit> | class | meaning |
    /// \`slug\`, ... |` where `<exit>` is 1–7 (row 0 is the success row, no
    /// slugs). Parsing is SCOPED to the `## Exit codes` section — the README
    /// contains unrelated tables whose rows coincidentally begin `| 5 |`,
    /// `| 3 |`, etc. Std-only string ops: split on `|`, trim, take the LAST
    /// non-empty cell as the slug column (the meaning column can carry
    /// backticked non-slugs like `--yes`), and keep the backtick-delimited
    /// tokens that start with an ASCII letter and contain no spaces.
    fn parse_readme_exit_table(readme: &str) -> Vec<(u8, Vec<String>)> {
        let section = readme.split("## Exit codes").nth(1).unwrap_or_default();
        let mut rows = Vec::new();
        let table_lines = section
            .lines()
            .skip_while(|line| !line.trim_start().starts_with('|'));
        for line in table_lines {
            if !line.trim_start().starts_with('|') {
                break; // table ended
            }
            let cells: Vec<&str> = line.split('|').map(str::trim).collect();
            let Some(exit) = cells.get(1).and_then(|cell| cell.parse::<u8>().ok()) else {
                continue;
            };
            if !(1..=7).contains(&exit) {
                continue;
            }
            let slug_cell = cells
                .iter()
                .rev()
                .find(|cell| !cell.is_empty())
                .copied()
                .unwrap_or_default();
            let slugs: Vec<String> = slug_cell
                .split('`')
                .enumerate()
                .filter(|(idx, _)| idx % 2 == 1)
                .map(|(_, token)| token.trim().to_string())
                .filter(|token| {
                    token.starts_with(|c: char| c.is_ascii_alphabetic()) && !token.contains(' ')
                })
                .collect();
            rows.push((exit, slugs));
        }
        rows
    }

    /// CORE-11, the Three-Place slug rule made executable: the exit-code
    /// table exists in the enum ([`CoreError::exit_code`]), this file's
    /// literal triples, and the README — and the README side is now
    /// machine-checked. The README is parsed verbatim via `include_str!`
    /// and cross-checked against the literal table in BOTH directions:
    /// (a) every literal slug appears under its exit code (a README row
    /// that lost or misspelled a slug fails), (b) every README slug token
    /// exists in the literal table (a stale/deleted row fails). Exit 6
    /// carries 23 slugs, so the full cross-check is the value — not the
    /// happy-path smoke.
    #[test]
    fn readme_exit_table_agreement() {
        let readme = include_str!("../../../README.md");
        let rows = parse_readme_exit_table(readme);
        assert!(
            rows.len() >= 7,
            "README exit-code table not found — the parser must see all 7 \
             failure-class rows (found {})",
            rows.len()
        );

        // Direction (a): every literal (exit, slug) is present in the
        // README row matching its exit code.
        for (exit, slug) in EXIT_SLUG_LITERALS {
            let row = rows
                .iter()
                .find(|(readme_exit, _)| readme_exit == exit)
                .unwrap_or_else(|| panic!("README table has no row for exit {exit}"));
            assert!(
                row.1.iter().any(|s| s == slug),
                "README exit-{exit} row is missing slug {slug:?} (row: {:?})",
                row.1
            );
        }

        // Direction (b): every README slug token exists in the literal
        // table under the same exit code — catches stale/deleted rows.
        for (exit, slugs) in &rows {
            for slug in slugs {
                assert!(
                    EXIT_SLUG_LITERALS
                        .iter()
                        .any(|(lit_exit, lit_slug)| lit_exit == exit && lit_slug == slug),
                    "README exit-{exit} row carries slug {slug:?} that no \
                     CoreError variant emits — stale table row or slug/exit \
                     drift between README and error.rs"
                );
            }
        }
    }

    /// CORE-05: config, auth, and target-state classes carry actionable
    /// hints (and every other class does too).
    #[test]
    fn hints_are_actionable_for_config_auth_target_state() {
        let profile_not_found = CoreError::ProfileNotFound {
            name: "x".into(),
            known: vec!["dev".into(), "prod".into()],
        };
        let hint = profile_not_found.hint().expect("hint required");
        assert!(
            hint.contains("dev"),
            "hint must list known profiles: {hint}"
        );
        assert!(
            hint.contains("ign profile add"),
            "hint must name the fix: {hint}"
        );

        let auth = CoreError::Auth {
            status: 403,
            endpoint: None,
        };
        let hint = auth.hint().expect("hint required");
        assert!(
            hint.contains("three parts"),
            "auth hint must name the three-part token setup: {hint}"
        );

        // Status-aware auth hints (02-RESEARCH Auth §4): 401 = not
        // recognized (name:key format), 403 = under-permitted.
        let unauthorized = CoreError::Auth {
            status: 401,
            endpoint: None,
        };
        let hint = unauthorized.hint().expect("hint required");
        assert!(
            hint.contains("name:key"),
            "401 hint must name the full name:key token format: {hint}"
        );
        assert!(
            hint.contains("API token"),
            "401 hint must say Basic cannot work: {hint}"
        );
        let hint403 = auth.hint().expect("hint required");
        assert!(
            hint403.contains("secure connections"),
            "403 hint must name the secure-channel part: {hint403}"
        );

        let too_old = CoreError::GatewayTooOld {
            found: "8.1.0".into(),
            minimum: "8.3.1".into(),
            endpoint: None,
        };
        let hint = too_old.hint().expect("hint required");
        assert!(
            hint.contains("8.3.1"),
            "target-state hint must name the minimum: {hint}"
        );

        // The WebDev refusal matrix (05-03): every hint names the fix
        // — `ign webdev deploy` for absent/older routes, `update ign`
        // for newer ones (the roadmap's actionable-error criterion).
        let undeployed = CoreError::RoutesNotDeployed {
            project: "ign-cli".into(),
            route: "tags".into(),
            endpoint: None,
        };
        let hint = undeployed.hint().expect("hint required");
        assert!(
            hint.contains("ign webdev deploy"),
            "absent-routes hint must name the fix: {hint}"
        );

        let older = CoreError::RouteVersionMismatch {
            route: "tags".into(),
            deployed: "0.9.0".into(),
            expected: "1.0.0".into(),
            endpoint: None,
        };
        let hint = older.hint().expect("hint required");
        assert!(
            hint.contains("ign webdev deploy") && !hint.contains("update ign"),
            "older-route hint says redeploy: {hint}"
        );

        let newer = CoreError::RouteVersionMismatch {
            route: "tags".into(),
            deployed: "1.1.0".into(),
            expected: "1.0.0".into(),
            endpoint: None,
        };
        let hint = newer.hint().expect("hint required");
        assert!(
            hint.contains("update ign") && !hint.contains("ign webdev deploy"),
            "newer-route hint says update ign: {hint}"
        );

        let secret_gate = CoreError::WebdevRouteError {
            code: "secret_required".into(),
            message: "missing x-ignition-cli-secret header".into(),
            endpoint: None,
        };
        let hint = secret_gate.hint().expect("hint required");
        assert!(
            hint.contains("--with-script-exec"),
            "secret-gate hint names the deploy flag: {hint}"
        );

        // The alarm-journal refusal (05-06): the hint names the missing
        // provisioning chain AND the README section.
        let journal = CoreError::AlarmJournalMissing { endpoint: None };
        let hint = journal.hint().expect("hint required");
        assert!(
            hint.contains("journal profile") && hint.contains("database connection"),
            "journal hint names the chain: {hint}"
        );
        assert!(
            hint.contains("README"),
            "journal hint points at the README section: {hint}"
        );

        // The live-designer prune refusal (06-07): the hint names the
        // action — close the Designer — and the stale-only semantics.
        let prunable = CoreError::SessionNotPrunable {
            id: "d-live-1".into(),
            endpoint: None,
        };
        let hint = prunable.hint().expect("hint required");
        assert!(
            hint.contains("close the Designer"),
            "prune hint must name the action: {hint}"
        );
        assert!(
            hint.contains("stale entries"),
            "prune hint must name stale-only semantics: {hint}"
        );

        // The TTY refusal's hint is contextual (06-07): the ONE
        // InvalidInput reason whose fix is terminal-related. Every
        // other reason keeps the --file/stdin resource-put hint (pinned
        // here so the special case can never leak or regress).
        let tty = CoreError::tui_tty_refusal();
        assert_eq!(tty.code(), "invalid_input", "slug unchanged");
        assert_eq!(tty.exit_code(), 2, "usage class unchanged");
        let hint = tty.hint().expect("hint required");
        assert!(
            hint.contains("interactive terminal"),
            "TTY hint must name the fix: {hint}"
        );
        assert!(
            !hint.contains("--file"),
            "TTY hint must not carry the resource-put hint: {hint}"
        );
        let put = CoreError::InvalidInput {
            reason: "cannot read put.json".into(),
        };
        let hint = put.hint().expect("hint required");
        assert!(
            hint.contains("--file") && hint.contains("stdin"),
            "resource-put hint unchanged: {hint}"
        );

        // The EAM controller state gate (07-02): the hint names the
        // manual flip recipe + the README section (role decisions
        // stay one config-PUT away from the CLI, never one flag).
        let controller = CoreError::EamNotController { endpoint: None };
        let hint = controller.hint().expect("hint required");
        assert!(
            hint.contains("installMode"),
            "controller hint names the flip: {hint}"
        );
        assert!(
            hint.contains("Controller"),
            "controller hint names the target role: {hint}"
        );
        assert!(
            hint.contains("README"),
            "controller hint points at the README section: {hint}"
        );

        // The refused task-type ladder top (07-02 Task 3): the hint
        // names the EAM console + the v2 scope pointer.
        let refused = CoreError::EamTaskTypeRefused {
            task_type: "eam_restoreBackup".into(),
        };
        assert_eq!(refused.exit_code(), 6, "target state");
        let hint = refused.hint().expect("hint required");
        assert!(
            hint.contains("EAM console"),
            "refused hint names where to run it: {hint}"
        );
        assert!(
            hint.contains("fleet-wide") || hint.contains("EXT-03"),
            "refused hint names the fleet consequence / scope: {hint}"
        );

        // The force-route 409 (07-06 gap 4): the hint names the
        // resolution — complete or delete the leftover '(forced)'
        // run via the EAM console (no ign verb deletes runs).
        let in_flight = CoreError::EamTaskInFlight {
            task: "cli-research-backup".into(),
            detail: "the previous '(forced)' run must be completed or deleted first".into(),
            endpoint: None,
        };
        assert_eq!(in_flight.exit_code(), 6, "target state");
        let hint = in_flight.hint().expect("hint required");
        assert!(
            hint.contains("EAM console"),
            "in-flight hint names where to resolve it: {hint}"
        );
        assert!(
            hint.contains("complete or delete"),
            "in-flight hint names the resolution: {hint}"
        );

        // The scriptExec structural gate (07-03): the hint names the
        // deploy flag VERBATIM — the flag IS the opt-in (no --yes
        // exists on script run).
        let unconfigured = CoreError::ScriptExecNotConfigured {
            profile: "dev".into(),
        };
        assert_eq!(unconfigured.exit_code(), 6, "target state");
        let hint = unconfigured.hint().expect("hint required");
        assert!(
            hint.contains("ign webdev deploy --with-script-exec"),
            "the hint names the deploy flag verbatim: {hint}"
        );

        // Totality: no class silently loses its hint later.
        let no_active = CoreError::NoActiveProfile;
        assert!(no_active.hint().is_some());
    }

    /// The failure envelope's serialized field order and endpoint population
    /// are contract: `ok`, `profile`, `error` / `code`, `message`,
    /// `endpoint`, `hint` (string-level comparison because `serde_json::Value`
    /// maps are key-sorted and would hide ordering).
    #[test]
    fn error_envelope_locked_shape_and_endpoint() {
        let auth = CoreError::Auth {
            status: 401,
            endpoint: Some("https://gw.example.com/data/api/v1/gateway-info".into()),
        };
        let envelope: ErrorEnvelope<'_> = auth.envelope(Some("dev"));
        let json = serde_json::to_string(&envelope).expect("serialize envelope");

        assert_eq!(
            json,
            concat!(
                r#"{"ok":false,"profile":"dev","error":{"code":"auth_rejected","#,
                r#""message":"gateway rejected credentials (HTTP 401)","#,
                r#""endpoint":"https://gw.example.com/data/api/v1/gateway-info","#,
                r#""hint":"token not recognized — the X-Ignition-API-Token header must be the FULL `name:key` string from the gateway UI (Platform→Security→API Keys); Basic auth does not work on 8.3 /data routes — create an API token"}}"#
            )
        );

        // Classes without a request involved carry no endpoint.
        let no_request = CoreError::NoActiveProfile;
        let body: &ErrorBody = &no_request.envelope(None).error;
        assert_eq!(body.endpoint, None);
    }

    /// The api-call body cap (09-01): a body at or under
    /// [`GATEWAY_CLIENT_BODY_CAP_BYTES`] rides verbatim (no marker); a
    /// larger body is truncated to the cap on a UTF-8 char boundary with
    /// the exact ASCII marker appended — and the cap is enforced at
    /// CONSTRUCTION, so the variant always carries its final form.
    #[test]
    fn truncates_at_cap_with_marker() {
        // Under the cap: byte-identical passthrough.
        let short = r#"{"error":{"code":"NOT_FOUND"}}"#;
        assert_eq!(truncate_api_body(short), short);
        assert!(!short.contains(GATEWAY_CLIENT_BODY_TRUNCATION_MARKER));

        // Exactly at the cap: still verbatim (the marker only joins an
        // OVER-cap body — the boundary is <=, not <).
        let exact = "x".repeat(GATEWAY_CLIENT_BODY_CAP_BYTES);
        assert_eq!(truncate_api_body(&exact), exact);

        // One byte over: truncated, marker appended, total size bounded.
        let over = "x".repeat(GATEWAY_CLIENT_BODY_CAP_BYTES + 1);
        let truncated = truncate_api_body(&over);
        assert!(
            truncated.ends_with(GATEWAY_CLIENT_BODY_TRUNCATION_MARKER),
            "truncated body must end with the explicit marker"
        );
        assert!(
            truncated.len()
                <= GATEWAY_CLIENT_BODY_CAP_BYTES + GATEWAY_CLIENT_BODY_TRUNCATION_MARKER.len(),
            "truncated body must stay within cap + marker: {}",
            truncated.len()
        );

        // A multi-byte character straddling the cap boundary does not
        // panic (the cut backs up to a char boundary) and still carries
        // the marker.
        let multibyte = "é".repeat(GATEWAY_CLIENT_BODY_CAP_BYTES); // 2 bytes each
        let truncated = truncate_api_body(&multibyte);
        assert!(truncated.ends_with(GATEWAY_CLIENT_BODY_TRUNCATION_MARKER));
        assert!(
            truncated
                .is_char_boundary(truncated.len() - GATEWAY_CLIENT_BODY_TRUNCATION_MARKER.len())
        );
    }

    /// The loss-gate hint override (11-07 gap closure): a reason with the
    /// [`LOSS_GATE_REFUSAL_REASON_PREFIX`] sentinel carries the --yes
    /// hint, while every OTHER InvalidInput reason (generic file-read)
    /// and the TTY-refusal precedent keep their hints byte-identically.
    /// The loss-gate reason is built from the CONST via format! — a
    /// string literal of the sentinel text here would be a third
    /// production-literal hit and break the prefix-uniqueness gate the
    /// plan's verify pins.
    #[test]
    fn loss_gate_hint_override_and_neighbors_unchanged() {
        // Sentinel-prefixed reason (dynamic prose after the header):
        // the --yes hint, never the file-read default.
        let loss_gate = CoreError::InvalidInput {
            reason: format!(
                "{}xml): the scan reports 2 finding(s) before the import:\nre-run \
                 with --yes to import anyway",
                LOSS_GATE_REFUSAL_REASON_PREFIX
            ),
        };
        assert_eq!(loss_gate.code(), "invalid_input", "slug unchanged");
        assert_eq!(loss_gate.exit_code(), 2, "usage class unchanged");
        let hint = loss_gate.hint().expect("hint required");
        assert!(
            hint.contains("--yes"),
            "loss-gate hint must name the --yes re-run: {hint}"
        );
        assert!(
            hint.contains("loss report above"),
            "loss-gate hint must point back at the report: {hint}"
        );
        assert!(
            !hint.contains("fix the input source"),
            "the file-read default must never leak onto the loss-gate path: {hint}"
        );

        // Generic InvalidInput: the file-read default UNCHANGED (the
        // regression pin for every other raise site).
        let generic = CoreError::InvalidInput {
            reason: "x is not valid JSON: expected value at line 1".into(),
        };
        let hint = generic.hint().expect("hint required");
        assert!(
            hint.contains("--file") && hint.contains("stdin"),
            "resource-put hint unchanged: {hint}"
        );
        assert!(
            !hint.contains("--yes"),
            "the --yes hint must not leak onto generic reasons: {hint}"
        );

        // The TTY-refusal precedent intact (06-07).
        let tty = CoreError::tui_tty_refusal();
        let hint = tty.hint().expect("hint required");
        assert!(
            hint.contains("interactive terminal"),
            "TTY hint unchanged: {hint}"
        );
        assert!(
            !hint.contains("--yes"),
            "the --yes hint must not leak onto the TTY path: {hint}"
        );
    }

    /// The testing-scoped `routes_not_deployed` hint (QUICK-p0g): a
    /// `testing/`-prefixed route names the TESTING install commands,
    /// while every other route keeps the generic `ign webdev deploy`
    /// text BYTE-identically. Both branches are pinned so a future
    /// edit cannot silently merge them — sending a caller to
    /// `ign webdev deploy` for an absent testing bundle is a hint
    /// that does not fix the error.
    #[test]
    fn routes_not_deployed_hint_is_testing_scoped() {
        let testing = CoreError::RoutesNotDeployed {
            project: "Flux".into(),
            route: format!("{TESTING_ROUTE_PREFIX}run"),
            endpoint: None,
        };
        assert_eq!(testing.code(), "routes_not_deployed", "slug unchanged");
        assert_eq!(testing.exit_code(), 6, "target-state class unchanged");
        let hint = testing.hint().expect("hint required");
        assert!(
            hint.contains("ign webdev deploy --with-testing"),
            "testing hint must name the deploy flag: {hint}"
        );
        assert!(
            hint.contains("ign adopt") && hint.contains("--testing"),
            "testing hint must name the adopt path: {hint}"
        );

        // Every non-testing route: the generic hint, unchanged.
        let generic = CoreError::RoutesNotDeployed {
            project: "ign-cli".into(),
            route: "tags".into(),
            endpoint: None,
        };
        let hint = generic.hint().expect("hint required");
        assert_eq!(
            hint,
            "run `ign webdev deploy` to install the CLI's WebDev routes into \
             the gateway, then retry",
            "the generic branch is byte-identical to its pre-QUICK-p0g text"
        );
    }
}