printobserver_sdk/

contract.rs

//! Generated by `contract-codegen` from the checked-in contract schemas.
//!
//! This file is the Rust client's request and response types.
//!
//! Do not edit by hand: change the contracts, regenerate with `just
//! generate-clients`, and commit what that writes.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use crate::{Client, ClientError};

/// The version of the server contract these types were generated from: the
/// version of the workspace this crate is compiled from. A published crate
/// reports the release version it was built at, and a crate compiled from a
/// checkout reports that checkout's workspace version.
pub const CONTRACT_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Every operation this client exposes a method for, which is every operation
/// the server declares and no other.
pub const OPERATION_NAMES: [&str; 29] = [
    "prints",
    "status",
    "context",
    "image",
    "history",
    "events",
    "manifest_get",
    "look",
    "manifest_set",
    "spools",
    "spool",
    "printer_history",
    "preflight",
    "pause",
    "resume",
    "cancel",
    "start_print",
    "set_feedrate_factor",
    "set_flowrate_factor",
    "set_tool_target_c",
    "set_bed_target_c",
    "set_fan_percent",
    "acknowledge_failure",
    "close_print",
    "register_spool",
    "load_spool",
    "unload_spool",
    "adjust_spool",
    "retire_spool",
];

/// A field that was sent, null included, as what was sent.
fn present<'de, D, T>(deserializer: D) -> Result<Option<T>, D::Error>
where
    D: serde::Deserializer<'de>,
    T: Deserialize<'de>,
{
    T::deserialize(deserializer).map(Some)
}

/// What an operator's acknowledgement of a failure event asks for next.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum AcknowledgementDisposition {
    /// Carry on printing.
    #[serde(rename = "continue")]
    Continue,
    /// Carry on printing, watched more closely.
    #[serde(rename = "watch")]
    Watch,
    /// The print should stop. Recorded for whoever may cancel it: the
    /// acknowledgement itself asks nothing of the machine.
    #[serde(rename = "stop")]
    Stop,
}

/// What one mutating request left behind it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionAnswer {
    /// The bounded intervention it opened, when it opened one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub intervention: Option<Intervention>,
    /// What the printer said, when the request reached it and it refused.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printer_refusal: Option<String>,
    /// The record of the request and the decision taken on it. A rejected
    /// request's rejection is here, carrying its reason, the value asked for
    /// and the range allowed, so a caller can ask again inside the range.
    pub record: ActionRecord,
}

/// An accepted action reached the printer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionExecutedPayload {
    /// The action's identifier.
    pub action_id: ActionId,
    /// The bounded intervention it opened, when it opened one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub intervention_id: Option<InterventionId>,
}

/// A lowercase hyphenated version 7 UUID identifying one requested action.
pub type ActionId = String;

/// One action of the closed vocabulary, named without its payload.
///
/// This is what a safety envelope grants and what a policy rejection names;
/// the
/// payload lives on `PrintAction` itself.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ActionKind {
    /// Pause the print.
    #[serde(rename = "pause")]
    Pause,
    /// Resume the print.
    #[serde(rename = "resume")]
    Resume,
    /// Cancel the print.
    #[serde(rename = "cancel")]
    Cancel,
    /// Start a print of a named file.
    #[serde(rename = "start_print")]
    StartPrint,
    /// Set the feedrate factor.
    #[serde(rename = "set_feedrate_factor")]
    SetFeedrateFactor,
    /// Set the flowrate factor.
    #[serde(rename = "set_flowrate_factor")]
    SetFlowrateFactor,
    /// Set a tool's target temperature.
    #[serde(rename = "set_tool_target_c")]
    SetToolTargetC,
    /// Set the bed's target temperature.
    #[serde(rename = "set_bed_target_c")]
    SetBedTargetC,
    /// Set the fan percentage.
    #[serde(rename = "set_fan_percent")]
    SetFanPercent,
    /// Acknowledge a failure event.
    #[serde(rename = "acknowledge_failure")]
    AcknowledgeFailure,
    /// Close a print record printobserver left open.
    #[serde(rename = "close_print")]
    ClosePrint,
    /// Register a spool.
    #[serde(rename = "register_spool")]
    RegisterSpool,
    /// Load a spool onto a tool.
    #[serde(rename = "load_spool")]
    LoadSpool,
    /// Unload a spool from its tool.
    #[serde(rename = "unload_spool")]
    UnloadSpool,
    /// Correct a spool's remaining figure.
    #[serde(rename = "adjust_spool")]
    AdjustSpool,
    /// Retire a spool.
    #[serde(rename = "retire_spool")]
    RetireSpool,
}

/// One request, the decision taken on it, and what became of it.
///
/// `executed_at` and `outcome` are both optional and are absent together: a
/// record is written when the decision is taken, which is before — and, for a
/// rejected request, instead of — anything reaching the printer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionRecord {
    /// The decision policy took on it.
    pub decision: PolicyDecision,
    /// When it reached the printer, if it did.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub executed_at: Option<Timestamp>,
    /// This record's identifier, minted by the store.
    pub id: ActionId,
    /// What the printer made of it, if it reached the printer.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub outcome: Option<ExecutionOutcome>,
    /// The print this request was made against.
    pub print_id: PrintId,
    /// The request itself.
    pub request: ActionRequest,
}

/// Policy refused an action.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionRejectedPayload {
    /// The action's identifier.
    pub action_id: ActionId,
    /// The whole decision, carrying which rejection it was.
    pub decision: PolicyDecision,
}

/// One request an actor made, at the instant it made it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionRequest {
    /// What was asked for.
    pub action: PrintAction,
    /// Who asked.
    pub actor: Actor,
    /// When they asked.
    pub requested_at: Timestamp,
}

/// An actor asked for an action.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ActionRequestedPayload {
    /// What was asked for.
    pub action: PrintAction,
    /// The action's identifier.
    pub action_id: ActionId,
    /// Who asked.
    pub actor: Actor,
}

/// Who asked for something.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Actor {
    /// The supervising agent, naming its session.
    #[serde(rename = "agent")]
    Agent {
        /// The supervision session the agent is acting in.
        session_name: String,
    },
    /// A person.
    #[serde(rename = "operator")]
    Operator,
    /// The supervisor itself.
    #[serde(rename = "system")]
    System,
}

/// An actor class, which is what a safety envelope grants actions to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ActorClass {
    /// The supervising agent.
    #[serde(rename = "agent")]
    Agent,
    /// A person.
    #[serde(rename = "operator")]
    Operator,
    /// The supervisor itself.
    #[serde(rename = "system")]
    System,
}

/// One thing an adjustment may change.
pub type Adjustable = String;

/// The agent's written record of one supervision turn.
///
/// This is deliberately not how the agent acts: acting is a
/// `PrintAction` that policy rules on.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AgentAssessment {
    /// How sure the agent is.
    pub confidence: Confidence,
    /// What the agent did.
    pub did: String,
    /// Whether the agent is escalating to a person.
    pub escalating: bool,
    /// Whether the print should carry on.
    pub should_continue: bool,
    /// One line saying what is happening.
    pub summary: String,
    /// Why it did it.
    pub why: String,
}

/// The agent wrote down what it made of a turn.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AgentAssessmentPayload {
    /// What the agent answered with.
    pub assessment: AgentAssessment,
    /// The session the turn ran in.
    pub session_name: String,
}

/// Somebody took a fresh look at the print.
///
/// Written down before the camera is asked for a frame, so that a frame the
/// camera would not give is recorded against a look that is already in the
/// history; the frame itself, when there is one, is this event's image.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CameraLookPayload {
    /// The events for the print that arrived while it waited, and that it
    /// handed to whoever looked, oldest first.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub delivered: Option<Vec<EventId>>,
    /// How long the look waited for something to happen before it was taken,
    /// in whole seconds.
    pub waited_s: i64,
}

/// The durable identity of one debit, so that a replay can never debit twice.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "key")]
pub enum ChargeKey {
    /// One segment of a print this system watched, on one tool.
    #[serde(rename = "print")]
    Print {
        /// The print.
        print_id: PrintId,
        /// Which segment: zero from the print's start, and one more each time
        /// a mid-print swap or a filament-change signal closes the current
        /// one.
        segment: i64,
        /// The tool, in the printer's own numbering.
        tool: i64,
    },
    /// One print this system never saw, on one tool.
    #[serde(rename = "unobserved")]
    Unobserved {
        /// The file that was printed.
        file_name: String,
        /// The file's tally generation, which advances each time the
        /// printer's
        /// tally for the file is reset.
        generation: i64,
        /// Where the file lives, in the printer's own vocabulary.
        origin: String,
        /// The print's ordinal in the file's tally — completed and failed
        /// prints counted up to and including this one — within that
        /// generation.
        print_number: i64,
        /// The tool, in the printer's own numbering.
        tool: i64,
    },
}

/// How the length a charge debits was worked out.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ChargeMethod {
    /// A completed print: the length the file's analysis gives.
    #[serde(rename = "slicer_estimate")]
    SlicerEstimate,
    /// The extrusion the file's own moves add up to, up to a position in it.
    #[serde(rename = "gcode_extrusion")]
    GcodeExtrusion,
    /// The analysed length scaled by how far into the file the print got; the
    /// fallback used only when the file itself could not be read.
    #[serde(rename = "file_fraction")]
    FileFraction,
    /// A completed print this system never saw: the file's analysed length.
    #[serde(rename = "unobserved_estimate")]
    UnobservedEstimate,
}

/// Filament a tool fed after an unconfirmed filament change was held for the
/// next spool loaded onto that tool, or confirmed on it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChargePendedPayload {
    /// What was held.
    pub pending: PendingCharge,
}

/// What a charge took from a spool, and the whole calculation behind it.
///
/// Present or absent as one: a debit names its spool exactly when it carries
/// the grams, the figures they were worked out with, and the spool's figure
/// either side of them.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChargedFilament {
    /// The density the grams were worked out with, in grams per cubic
    /// centimetre.
    pub density_g_cm3: f64,
    /// The diameter the grams were worked out with, in millimetres.
    pub diameter_mm: f64,
    /// What the length weighs, in grams; what is subtracted from the spool.
    pub grams: f64,
    /// The spool's figure after it, in grams.
    pub remaining_after_g: f64,
    /// The spool's figure before the charge, in grams.
    pub remaining_before_g: f64,
    /// The spool charged.
    pub spool_id: SpoolId,
}

/// One mark a spool command cleared, and the spool it was cleared from.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClearedMark {
    /// The reason that no longer stands.
    pub reason: UnverifiedReason,
    /// The spool the mark was cleared from.
    pub spool_id: SpoolId,
}

/// How sure the agent is.
///
/// A closed vocabulary rather than a number, because a number invites a
/// precision the agent does not have.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Confidence {
    /// Not sure.
    #[serde(rename = "low")]
    Low,
    /// Fairly sure.
    #[serde(rename = "medium")]
    Medium,
    /// Sure.
    #[serde(rename = "high")]
    High,
}

/// What a context read answers.
///
/// The latest image is **materialized** here rather than left as the handle
/// `PrintContext` carries: the one thing a supervision turn does with an
/// image is look at it, and a handle is not something anything can open. The
/// path is absolute on this server's own filesystem, exactly as
/// `ImageAnswer`'s is, and is absent when there is no image or when the
/// record is intact and the file is not.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ContextAnswer {
    /// Everything a supervision turn is given about the print.
    pub context: PrintContext,
    /// Where the latest image's bytes are, absolute on this host.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub image_path: Option<String>,
}

/// The envelope intersected with the print's manifest.
///
/// This is what context reports, so that the agent can see its own limits
/// before it asks. Computing one is the supervision core's; this crate
/// declares
/// the shape and nothing that produces it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EffectiveBounds {
    /// The range each adjustable may be set to, inclusive.
    pub allowed: BTreeMap<String, Range>,
}

/// What this server answers when it will not do what it was asked.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ErrorAnswer {
    /// One line saying why, in the words of whatever refused it.
    pub error: String,
}

/// A lowercase hyphenated version 7 UUID identifying one event.
pub type EventId = String;

/// The name one kind of event is written down under: lowercase `snake_case`,
/// declared by the domain that owns the event.
pub type EventKind = String;

/// One event, as the store holds it and the server serves it.
///
/// `raw` holds the bytes exactly as received for an externally sourced event
/// and is absent for an internally raised one — it is what makes the history
/// auditable when a normalization turns out to be wrong. `print_id` is
/// optional, because an externally sourced event may name no print this
/// system
/// knows.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EventRecord {
    /// This event's identifier, minted by the store.
    pub id: EventId,
    /// The image it arrived with, when it arrived with one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub image: Option<ImageRef>,
    /// Which event this is.
    pub kind: EventKind,
    /// What it carries, in the form its kind declares.
    pub payload: serde_json::Value,
    /// The print it belongs to, when it belongs to one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub print_id: Option<PrintId>,
    /// The bytes exactly as received, for an externally sourced event.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub raw: Option<RawBytes>,
    /// When it was received.
    pub received_at: Timestamp,
    /// Where it came from.
    pub source: EventSource,
}

/// Where an event came from, as the bare string the domain that raised it
/// declares for itself.
pub type EventSource = String;

/// What an events read answers: the events stored after its cursor that pass
/// its filters, oldest first, and where the next read picks up.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EventsAnswer {
    /// The last event this read examined, whether or not it passed the
    /// filters, given as `after` to read on from it; null when the log held
    /// nothing to start after. Always sent, as null when it is that.
    pub cursor: Option<EventId>,
    /// The events, oldest first in the order they were stored, each exactly
    /// as
    /// a history read serves it.
    pub events: Vec<EventRecord>,
    /// The watched print's end as stored, whatever the filters said, and null
    /// while it is open. Absent from a read that names no print.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "present"
    )]
    pub print_ended: Option<Option<PrintEnded>>,
}

/// What happened when an accepted action reached the printer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ExecutionOutcome {
    /// The printer took it.
    #[serde(rename = "succeeded")]
    Succeeded,
    /// The printer did not, for this reason.
    #[serde(rename = "failed")]
    Failed {
        /// Why it failed.
        reason: String,
    },
}

/// A filament change was signalled during a print.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FilamentChangeSignalledPayload {
    /// The position the spool was charged up to, and how fresh it is, when
    /// one
    /// was known; absent, there is no position and so no claim about one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<SignalPosition>,
    /// The kind of the alert that carried the signal.
    pub source_kind: EventKind,
    /// The spool that was on it, when one was tracked.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub spool_id: Option<SpoolId>,
    /// The tool the change was signalled for, when it is known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tool: Option<i64>,
}

/// Filament was charged against a spool, or recorded uncharged.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FilamentConsumedPayload {
    /// The file's analysed length for the tool, in millimetres, when it had
    /// one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub analysed_length_mm: Option<f64>,
    /// The durable identity of this debit.
    pub charge_key: ChargeKey,
    /// The spool charged and the whole calculation of what it was charged;
    /// absent when nothing was tracked on the tool, and the filament was
    /// recorded uncharged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub charged: Option<ChargedFilament>,
    /// How much was fed, in millimetres.
    pub length_mm: f64,
    /// How the length was worked out.
    pub method: ChargeMethod,
    /// Anything a reader needs to make sense of the figure.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// How far into the file the charge runs, when that was read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<FilePosition>,
    /// The tool that fed it, as its key names it.
    pub tool: i64,
}

/// A file name a printer's own file API can be asked for: no path separator,
/// no NUL byte, no `.` or `..` segment, no drive prefix, and not empty.
pub type FileName = String;

/// How far into its file a print had got, and when that was read.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FilePosition {
    /// The byte the printer had read the file up to.
    pub bytes: i64,
    /// When the position was read.
    pub observed_at: Timestamp,
    /// The file's size in bytes, when it was known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub size_bytes: Option<i64>,
}

/// The printer's tally for a file went down — the file was deleted and
/// uploaded again — so the file's tally generation advanced, and the new
/// count
/// is that generation's growth from zero.
///
/// The rebaseline itself marks no spool; only an `unverified` disposition
/// does.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FileTallyRebaselinedPayload {
    /// What became of the prints the new generation counts.
    pub disposition: RebaselineDisposition,
    /// The file whose tally went down.
    pub file_name: String,
    /// The failed prints the new tally counts.
    pub new_failures: i64,
    /// The generation it is in now.
    pub new_generation: i64,
    /// The completed prints the new tally counts.
    pub new_successes: i64,
    /// The failed prints the old tally counted.
    pub old_failures: i64,
    /// The generation the tally was in.
    pub old_generation: i64,
    /// The completed prints the old tally counted.
    pub old_successes: i64,
    /// Where it lives, in the printer's own vocabulary.
    pub origin: String,
}

/// One heater, as a source reported it.
///
/// Every field is optional, because a source that reports no heater at all
/// reports none of these; each is a plausibility-ranged reported value in
/// degrees Celsius.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HeaterSnapshot {
    /// The temperature the heater is at.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actual_c: Option<Reported>,
    /// The offset applied to this heater's target.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub offset_c: Option<Reported>,
    /// The temperature the heater is driving towards.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target_c: Option<Reported>,
}

/// What a history read answers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HistoryAnswer {
    /// The print's events, newest first.
    pub events: Vec<EventRecord>,
}

/// What an image read answers.
///
/// The path is absolute on this server's own filesystem, and is the whole of
/// the answer about the bytes: nothing here renders them, encodes them or
/// serves them. It is absent when the record is intact and the file is not,
/// which is a different answer from there being no such image.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ImageAnswer {
    /// Where its bytes are, absolute on this host.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// The record.
    pub record: ImageRecord,
}

/// A lowercase hyphenated version 7 UUID identifying one image.
pub type ImageId = String;

/// One image, stored beside the event it arrived with.
///
/// `relative_path` is relative to the configured state directory, so that the
/// store stays portable. Materializing an image resolves that to an absolute
/// path; nothing in this system renders image bytes into JSON.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ImageRecord {
    /// How many bytes it is.
    pub byte_len: i64,
    /// The content type it was served as.
    pub content_type: String,
    /// The event it arrived with.
    pub event_id: EventId,
    /// When it was fetched.
    pub fetched_at: Timestamp,
    /// This image's identifier, minted by the store.
    pub id: ImageId,
    /// The print it belongs to.
    pub print_id: PrintId,
    /// Where it lives, relative to the configured state directory.
    pub relative_path: String,
    /// The SHA-256 of its bytes, lowercase hexadecimal.
    pub sha256: String,
    /// Where it was fetched from, when it was fetched from somewhere.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_url: Option<String>,
}

/// The handle an image travels in context under.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ImageRef {
    /// The image's identifier.
    pub id: ImageId,
    /// The SHA-256 of its bytes, lowercase hexadecimal.
    pub sha256: String,
}

/// One adjustment made for a bounded time.
///
/// `prior_value` is read from the printer snapshot taken before the change,
/// and
/// is absent when the printer reported none — in which case expiry restores
/// nothing and the outcome says so rather than guessing a default.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Intervention {
    /// The action that asked for it.
    pub action_id: ActionId,
    /// What it changed.
    pub adjustable: Adjustable,
    /// When it was applied.
    pub applied_at: Timestamp,
    /// What it was changed to.
    pub applied_value: f64,
    /// When it stops standing.
    pub expires_at: Timestamp,
    /// This intervention's identifier, minted by the store.
    pub id: InterventionId,
    /// What became of it.
    pub outcome: InterventionOutcome,
    /// The print it was made against.
    pub print_id: PrintId,
    /// What the printer reported before the change, if it reported anything.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prior_value: Option<f64>,
    /// When the prior value was put back, if it was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub restored_at: Option<Timestamp>,
}

/// A bounded intervention expired.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InterventionExpiredPayload {
    /// What it had changed.
    pub adjustable: Adjustable,
    /// The intervention's identifier.
    pub intervention_id: InterventionId,
    /// What became of it.
    pub outcome: InterventionOutcome,
}

/// A lowercase hyphenated version 7 UUID identifying one bounded
/// intervention.
pub type InterventionId = String;

/// What became of a bounded change.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum InterventionOutcome {
    /// It is still in force.
    #[serde(rename = "still_active")]
    StillActive,
    /// The prior value was put back.
    #[serde(rename = "restored")]
    Restored,
    /// There was no prior value to put back.
    #[serde(rename = "restore_unavailable")]
    RestoreUnavailable,
    /// Putting the prior value back failed.
    #[serde(rename = "restore_failed")]
    RestoreFailed {
        /// Why it failed.
        reason: String,
    },
    /// Another intervention replaced it before it expired.
    #[serde(rename = "superseded")]
    Superseded {
        /// The intervention that replaced it.
        by: InterventionId,
    },
}

/// What a sliced job declares about itself and about what may be adjusted.
///
/// An adjustable the manifest does not name takes the envelope's own range; a
/// manifest range wider than the envelope's is narrowed to the envelope's and
/// the narrowing is recorded on the print. A manifest may only narrow.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct JobManifest {
    /// The range each named adjustable may take, inclusive.
    pub allowed: BTreeMap<String, Range>,
    /// The file this manifest is about, as the slicer named it.
    pub file_name: String,
    /// The material the job is sliced for.
    pub material: String,
    /// Whatever else the slicer recorded.
    pub metadata: BTreeMap<String, String>,
    /// The nozzle the job is sliced for, in millimetres.
    pub nozzle_diameter_mm: f64,
    /// The slicer profile the job was sliced with.
    pub slicer_profile: String,
}

/// The job a printer reports it is running.
///
/// Every field but `state` is optional: an absent one means the source did
/// not
/// report it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct JobSnapshot {
    /// How far through the print is, as a fraction from zero to one.
    ///
    /// Normalized to a fraction here regardless of how the source expresses
    /// it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub completion: Option<Reported>,
    /// The error the source reports, when it reports one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// The whole print's estimated duration, in whole seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub estimated_print_time_s: Option<i64>,
    /// The filament the source's analysis of the file says each tool uses;
    /// empty when the source reported none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub filament: Option<Vec<ToolFilament>>,
    /// The name of the file being printed, as the source reported it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// Where the file lives, in the source's own vocabulary.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_origin: Option<String>,
    /// How far into the file the printer has read, in bytes, when the source
    /// reported it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_position_bytes: Option<i64>,
    /// How long the print has left, in whole seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub print_time_left_s: Option<i64>,
    /// How long the print has been running, in whole seconds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub print_time_s: Option<i64>,
    /// The file's size in bytes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub size_bytes: Option<i64>,
    /// The state the source reports the job to be in.
    pub state: PrinterState,
}

/// One spool loaded on one tool, as a print started.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LoadedSpool {
    /// The spool loaded on it.
    pub spool_id: SpoolId,
    /// The tool, in the printer's own numbering.
    pub tool: i64,
}

/// One fresh look at a print.
///
/// An answer rather than a record, so it admits fields beside its own the way
/// every answer of the server does: a client that could not open the frame's
/// path says so in a field of its own beside the rest of the answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Look {
    /// The events for this print that arrived while the look waited, oldest
    /// first; the look returned early when there were any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub arrived: Option<Vec<EventRecord>>,
    /// Whether the print is paused and the pause is the detector's, which is
    /// what an adjustment asked for now would be applied under.
    pub detector_paused: bool,
    /// The look itself, as it was written into the print's history, carrying
    /// the frame as its image when there is one.
    pub event: EventRecord,
    /// The frame the camera gave, absent when no camera is configured or it
    /// gave none — which the history records as a port failure.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub frame: Option<ImageRef>,
    /// The absolute path the frame's bytes are at, on the supervisor's host.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub image_path: Option<String>,
    /// The job the printer reports now, absent when it could not be read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job: Option<JobSnapshot>,
    /// The printer's state now, absent when it could not be read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printer: Option<PrinterSnapshot>,
}

/// An external body arrived that could not be read.
///
/// This kind always carries its `raw` bytes, and it exists so that an alert
/// this system cannot read is written down rather than dropped.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MalformedExternalEventPayload {
    /// One line saying why the body could not be read.
    pub detail: String,
}

/// What a manifest read or write answers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ManifestAnswer {
    /// The manifest, when the print has one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub manifest: Option<JobManifest>,
    /// Every range this manifest asked wider than the envelope allows,
    /// narrowed
    /// to the envelope's — recorded on the print, so nobody has to wonder
    /// later
    /// which bound applied.
    pub narrowings: Vec<ManifestNarrowing>,
}

/// One adjustable whose manifest range was wider than the envelope's.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ManifestNarrowing {
    /// The adjustable that was narrowed.
    pub adjustable: Adjustable,
    /// The range that stands.
    pub applied: Range,
    /// The range the manifest asked for.
    pub requested: Range,
}

/// Obico reported a print failure.
///
/// The two instants are optional because Obico's own field for each is a Unix
/// timestamp number, an empty string, or absent, and the last two both mean
/// the
/// producer reported no instant. An absent field here is that, never an epoch
/// date standing in for it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ObicoFailureAlertPayload {
    /// When the print ended, when Obico reported an instant for it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_at: Option<Timestamp>,
    /// The file being printed, when Obico named one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// Whether Obico called it a warning rather than a failure.
    pub is_warning: bool,
    /// Obico's own identifier for the print, when it named one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub obico_print_id: Option<i64>,
    /// Whether Obico paused the print itself.
    pub print_paused: bool,
    /// When the print started, when Obico reported an instant for it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub started_at: Option<Timestamp>,
}

/// The kind of printer notification Obico sent, normalized.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ObicoNotificationType {
    /// A print started.
    #[serde(rename = "started")]
    Started,
    /// A print finished.
    #[serde(rename = "done")]
    Done,
    /// A print was cancelled.
    #[serde(rename = "cancelled")]
    Cancelled,
    /// A print was paused.
    #[serde(rename = "paused")]
    Paused,
    /// A print was resumed.
    #[serde(rename = "resumed")]
    Resumed,
    /// The printer is waiting for a filament change.
    #[serde(rename = "filament_change")]
    FilamentChange,
    /// A heater cooled down.
    #[serde(rename = "heater_cooled")]
    HeaterCooled,
    /// A heater reached its target.
    #[serde(rename = "heater_target")]
    HeaterTarget,
}

/// Obico sent a printer notification.
///
/// The two instants are optional for the same reason
/// `ObicoFailureAlertPayload`'s are, and are absent along with the rest of
/// the print's fields when the notification is about no print at all.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ObicoPrinterNotificationPayload {
    /// When the print ended, when Obico reported an instant for it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_at: Option<Timestamp>,
    /// The file being printed, when the notification is about one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// Which notification it is.
    pub notification_type: ObicoNotificationType,
    /// Obico's own identifier for the print, when the notification is about
    /// one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub obico_print_id: Option<i64>,
    /// When the print started, when Obico reported an instant for it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub started_at: Option<Timestamp>,
}

/// An operator acknowledged an event.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct OperatorAcknowledgementPayload {
    /// The event being acknowledged.
    pub acknowledged_event_id: EventId,
    /// What the operator asked for next.
    pub disposition: AcknowledgementDisposition,
}

/// Filament a tool fed after a filament change nobody has confirmed, held
/// until
/// somebody says which spool fed it.
///
/// A length rather than grams, because the grams follow the spool that takes
/// it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PendingCharge {
    /// The file's analysed length for the tool, in millimetres, when it had
    /// one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub analysed_length_mm: Option<f64>,
    /// The print segment the filament was fed in, which names the print and
    /// the tool that fed it.
    pub charge_key: PrintSegmentKey,
    /// How much was fed, in millimetres.
    pub length_mm: f64,
    /// How that length was worked out.
    pub method: ChargeMethod,
    /// Anything a reader needs to make sense of the figure.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// When it was held.
    pub pended_at: Timestamp,
    /// How far into the file the segment ran, when that was read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<FilePosition>,
}

/// One pending charge a spool command took.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PendingTaken {
    /// The key it is charged under.
    pub charge_key: ChargeKey,
    /// The print it was fed in.
    pub print_id: PrintId,
}

/// The supervisor looked in on an active print on its own schedule, with no
/// detector having said anything about it.
///
/// What a failure detector never alerts on — a progress that stopped moving,
/// a
/// heater whose target fell to nothing mid-print, a fan cut at a bridge, a
/// wall
/// going thin — is still on the machine and in the camera's frame, so every
/// active print is given one of these each interval and a turn on it. It
/// carries what the printer reported as it was taken; the frame the camera
/// gave
/// at the same moment, untagged by any detector, is this event's image.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PeriodicObservationPayload {
    /// How often these are taken, in whole seconds.
    pub interval_s: i64,
    /// The job the printer reported as the observation was taken, absent when
    /// it could not be read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job: Option<JobSnapshot>,
    /// The printer's state as the observation was taken, absent when it could
    /// not be read — which the history records as a port failure.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printer: Option<PrinterSnapshot>,
}

/// The decision policy took on one request.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum PolicyDecision {
    /// The request may proceed.
    #[serde(rename = "accepted")]
    Accepted,
    /// The request may not, for this reason.
    #[serde(rename = "rejected")]
    Rejected(RejectionReason),
}

/// A port failed while one event was being handled.
///
/// The event is named rather than implied, so that a reader holding an
/// event's
/// identifier reaches every failure recorded while that event was being
/// handled. A failure recorded here is one the handling survived: the event
/// is
/// already in the history by the time any of these sites is reached, and the
/// loop goes on to handle the next event.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PortFailurePayload {
    /// What the port said about it, in the port's own words.
    pub detail: String,
    /// The event whose handling reached the failing call.
    pub event_id: EventId,
    /// Where it failed.
    pub site: PortFailureSite,
}

/// Where a port failed while an event was being handled.
///
/// A closed set of exactly the sites at which a failure has nowhere else to
/// be
/// recorded. The printer's action methods record theirs on the
/// `ActionRecord` the request minted, and a restoring
/// call records its own on the `Intervention` it was
/// expiring; those are not sites here, because a second record of them would
/// be
/// a second version of one fact.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PortFailureSite {
    /// Reading the printer's own state.
    #[serde(rename = "printer_snapshot")]
    PrinterSnapshot,
    /// Reading the job the printer reports it is running.
    #[serde(rename = "printer_job")]
    PrinterJob,
    /// Writing the image the event arrived with.
    #[serde(rename = "image_write")]
    ImageWrite,
    /// Running the supervision turn the event prompted.
    #[serde(rename = "supervision_turn")]
    SupervisionTurn,
    /// Taking a fresh frame from the camera, for a look at the print or for a
    /// periodic observation of it.
    #[serde(rename = "camera_look")]
    CameraLook,
    /// Telling the detector that paused the print its detection was handled.
    #[serde(rename = "detector_acknowledgement")]
    DetectorAcknowledgement,
}

/// How fresh the position a filament change charged up to is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PositionFreshness {
    /// Read from the job as the signal was handled: where the spool stopped.
    #[serde(rename = "read_at_signal")]
    ReadAtSignal,
    /// The last position recorded before the signal, the job reporting none
    /// as it was handled: the spool may have fed past it.
    #[serde(rename = "last_recorded")]
    LastRecorded,
}

/// What a filament check found for one print.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Preflight {
    /// When the check was made.
    pub checked_at: Timestamp,
    /// The file the print is of.
    pub file_name: String,
    /// What it found for each tool.
    pub tools: Vec<PreflightTool>,
    /// The worst of the tools' verdicts, in the order insufficient,
    /// unverified spool, no analysis, warned, overridden, unchecked, passed.
    pub verdict: PreflightVerdict,
}

/// What a filament check answers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreflightAnswer {
    /// What the check found, read now.
    pub preflight: Preflight,
}

/// The filament check before a start was made.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreflightCheckedPayload {
    /// The start it was made for, when it was made for one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub action_id: Option<ActionId>,
    /// What the check found.
    pub preflight: Preflight,
}

/// What a print needs from one spool, in grams: both figures a comparison
/// with what the spool holds uses, or neither.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreflightNeed {
    /// The margin asked for beyond that.
    pub buffer_g: f64,
    /// What the print needs from the spool, by the file's analysis and the
    /// spool's own diameter and density.
    pub required_g: f64,
}

/// What a check that refuses a start found for one tool.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "verdict")]
pub enum PreflightObjection {
    /// The spool holds less than the print needs and its buffer.
    #[serde(rename = "insufficient")]
    Insufficient {
        /// The spool's marks at the check, oldest first, so a spool both
        /// short
        /// and unverified says both.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        marks: Option<Vec<UnverifiedMark>>,
        /// What the print needs from it.
        need: PreflightNeed,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// The spool's figure is in doubt.
    #[serde(rename = "unverified_spool")]
    UnverifiedSpool {
        /// Every reason the spool's figure is in doubt, oldest first; never
        /// empty.
        // llmlint: ignore[invalid_states_unrepresentable] See suppressions.toml.
        marks: Vec<UnverifiedMark>,
        /// What the print needs from it, when the file's analysis says.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        need: Option<PreflightNeed>,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// The file has no analysis, so what the spool must hold is unknown.
    #[serde(rename = "no_analysis")]
    NoAnalysis {
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
}

/// The spool a check judged, named beside its identifier so a reader need
/// not look it up.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreflightSpool {
    /// The spool's identifier.
    pub id: SpoolId,
    /// The spool's name.
    pub name: String,
}

/// What a filament check found for one tool.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreflightTool {
    /// What the check found for it, with the evidence that finding rests on.
    pub result: PreflightToolResult,
    /// The tool, in the printer's own numbering.
    pub tool: i64,
}

/// What a filament check found for one tool, tagged by its verdict, each
/// verdict carrying exactly the evidence it rests on.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "verdict")]
pub enum PreflightToolResult {
    /// The spool holds what the print needs and its buffer, and its figure is
    /// not in doubt.
    #[serde(rename = "passed")]
    Passed {
        /// What the print needs from it.
        need: PreflightNeed,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// No tracked spool is loaded on the tool, so nothing was checked.
    #[serde(rename = "unchecked")]
    Unchecked,
    /// The spool holds less than the print needs and its buffer.
    #[serde(rename = "insufficient")]
    Insufficient {
        /// The spool's marks at the check, oldest first, so a spool both
        /// short
        /// and unverified says both.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        marks: Option<Vec<UnverifiedMark>>,
        /// What the print needs from it.
        need: PreflightNeed,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// The spool's figure is in doubt.
    #[serde(rename = "unverified_spool")]
    UnverifiedSpool {
        /// Every reason the spool's figure is in doubt, oldest first; never
        /// empty.
        // llmlint: ignore[invalid_states_unrepresentable] See suppressions.toml.
        marks: Vec<UnverifiedMark>,
        /// What the print needs from it, when the file's analysis says.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        need: Option<PreflightNeed>,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// `OctoPrint`'s analysis of the file had not appeared, so what the spool
    /// must hold is unknown.
    #[serde(rename = "no_analysis")]
    NoAnalysis {
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// The spool.
        spool: PreflightSpool,
    },
    /// The start went ahead despite this objection, because an operator said
    /// so.
    #[serde(rename = "overridden")]
    Overridden {
        /// What the check objected to.
        objection: PreflightObjection,
    },
    /// The check is set to warn, and let the start go ahead despite this
    /// objection.
    #[serde(rename = "warned")]
    Warned {
        /// What the check objected to.
        objection: PreflightObjection,
    },
}

/// What a filament check found, for one tool or for a whole print.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PreflightVerdict {
    /// The spool holds what the print needs and its buffer.
    #[serde(rename = "passed")]
    Passed,
    /// No tracked spool is loaded on the tool, so nothing was checked.
    #[serde(rename = "unchecked")]
    Unchecked,
    /// The spool holds less than the print needs and its buffer.
    #[serde(rename = "insufficient")]
    Insufficient,
    /// The spool's figure is in doubt.
    #[serde(rename = "unverified_spool")]
    UnverifiedSpool,
    /// `OctoPrint`'s analysis of the file had still not appeared when the
    /// start's wait for it elapsed, or has not appeared yet when the check is
    /// only read.
    #[serde(rename = "no_analysis")]
    NoAnalysis,
    /// The start went ahead despite the check, because the actor said so.
    #[serde(rename = "overridden")]
    Overridden,
    /// The check is set to warn, and let an insufficient, unverified or
    /// unanalysed start go ahead.
    #[serde(rename = "warned")]
    Warned,
}

/// The whole vocabulary an actor may ask for, and there is no other.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "action")]
pub enum PrintAction {
    /// Pause the print.
    #[serde(rename = "pause")]
    Pause {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Resume the print.
    #[serde(rename = "resume")]
    Resume {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Cancel the print.
    #[serde(rename = "cancel")]
    Cancel {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Start a print of a named file, with a manifest.
    #[serde(rename = "start_print")]
    StartPrint {
        /// Who is asking.
        actor: Actor,
        /// The file to print, validated as a name a file API can be asked
        /// for.
        file_name: FileName,
        /// The manifest this print is bounded by.
        manifest: JobManifest,
        /// Start despite an insufficient or unverified spool, or a file
        /// `OctoPrint` has not analysed; the start's own reason is the
        /// override's reason.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        override_filament_check: Option<bool>,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Set the feedrate factor, where one means one hundred percent.
    #[serde(rename = "set_feedrate_factor")]
    SetFeedrateFactor {
        /// Who is asking.
        actor: Actor,
        /// How long the change stands for, in whole seconds.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        duration_s: Option<i64>,
        /// The multiplier asked for.
        factor: f64,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Set the flowrate factor, where one means one hundred percent.
    #[serde(rename = "set_flowrate_factor")]
    SetFlowrateFactor {
        /// Who is asking.
        actor: Actor,
        /// How long the change stands for, in whole seconds.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        duration_s: Option<i64>,
        /// The multiplier asked for.
        factor: f64,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Set one tool's target temperature.
    #[serde(rename = "set_tool_target_c")]
    SetToolTargetC {
        /// Who is asking.
        actor: Actor,
        /// How long the change stands for, in whole seconds.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        duration_s: Option<i64>,
        /// Why the actor is asking for this.
        reason: String,
        /// The target temperature asked for, in degrees Celsius.
        target_c: f64,
        /// The tool, in the printer's own numbering.
        tool: i64,
    },
    /// Set the bed's target temperature.
    #[serde(rename = "set_bed_target_c")]
    SetBedTargetC {
        /// Who is asking.
        actor: Actor,
        /// How long the change stands for, in whole seconds.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        duration_s: Option<i64>,
        /// Why the actor is asking for this.
        reason: String,
        /// The target temperature asked for, in degrees Celsius.
        target_c: f64,
    },
    /// Set the part-cooling fan percentage.
    #[serde(rename = "set_fan_percent")]
    SetFanPercent {
        /// Who is asking.
        actor: Actor,
        /// How long the change stands for, in whole seconds.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        duration_s: Option<i64>,
        /// The percentage asked for.
        percent: f64,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Acknowledge a failure event, with a disposition.
    #[serde(rename = "acknowledge_failure")]
    AcknowledgeFailure {
        /// Who is asking.
        actor: Actor,
        /// What to do next.
        disposition: AcknowledgementDisposition,
        /// The event being acknowledged.
        event_id: EventId,
        /// Why the actor is asking for this.
        reason: String,
    },
    /// Close a print record printobserver left open, with the outcome the
    /// operator judges it ended with. It asks nothing of the machine and
    /// charges no spool: the record's consumption was never seen to end.
    #[serde(rename = "close_print")]
    ClosePrint {
        /// Who is asking.
        actor: Actor,
        /// How the print ended, in the operator's judgement.
        outcome: PrintOutcome,
        /// Why the actor is asking for this.
        reason: String,
    },
}

/// Everything a supervision turn is given about one print.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintContext {
    /// The limits in force, so that the agent can see them before it asks.
    pub bounds: EffectiveBounds,
    /// The interventions still active.
    pub interventions: Vec<Intervention>,
    /// The job, when a snapshot could be taken.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job: Option<JobSnapshot>,
    /// The most recent image, when there is one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub latest_image: Option<ImageRef>,
    /// The manifest, when the print has one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub manifest: Option<JobManifest>,
    /// The print itself.
    pub print: PrintRecord,
    /// The printer, when a snapshot could be taken.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printer: Option<PrinterSnapshot>,
    /// A bounded list of this print's events, newest first.
    pub recent_events: Vec<EventRecord>,
}

/// One print's end, as its `print_ended` event stored it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintEnded {
    /// The `print_ended` event.
    pub event_id: EventId,
    /// How the print ended.
    pub outcome: PrintOutcome,
    /// When that event was received.
    pub received_at: Timestamp,
}

/// A print ended.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintEndedPayload {
    /// How far into its file it last read, when that was read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub last_position: Option<FilePosition>,
    /// How it ended.
    pub outcome: PrintOutcome,
    /// Why it ended, in the words the end was recorded with.
    pub reason: String,
    /// The state the printer was in as it ended.
    pub state: PrinterState,
}

/// A lowercase hyphenated version 7 UUID identifying one print.
pub type PrintId = String;

/// How a print ended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PrintOutcome {
    /// It ran to its end.
    #[serde(rename = "completed")]
    Completed,
    /// Somebody cancelled it.
    #[serde(rename = "cancelled")]
    Cancelled,
    /// It stopped on an error.
    #[serde(rename = "failed")]
    Failed,
    /// It stopped with no cancel, no error the printer reported and no
    /// finish. Charged as a failed print is: what the file's moves extruded
    /// up
    /// to the last file position seen.
    #[serde(rename = "interrupted")]
    Interrupted,
}

/// One print, and the record supervision keys from.
///
/// The provider's own print id is carried beside this record's identifier
/// rather than as it, because a print may be observed before the provider
/// that reports it has one.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintRecord {
    /// Why it ended, if it has.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub end_reason: Option<String>,
    /// When it ended, if it has.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_at: Option<Timestamp>,
    /// The file being printed, as the source reported it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// This print's identifier, minted by the store.
    pub id: PrintId,
    /// The longest running time, in whole seconds, the printer reported for
    /// this print's job at a read that found it printing rather than paused.
    ///
    /// The time a job has spent printing only grows, pause or no pause, so a
    /// job of this print's file reporting less — by more than
    /// `listing::JOB_IDENTITY_TOLERANCE_S` — is a later job. Absent until a
    /// read finds the job printing.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job_print_time_s: Option<i64>,
    /// When the printer's job this print records began, as the printer's own
    /// running time put it at the latest read that found the job running or
    /// paused: the instant of that read, less the running time it reported.
    ///
    /// `OctoPrint` counts a pause into the running time until the job resumes
    /// and then takes the pause back out, so a pause moves this later: a read
    /// putting it further than `listing::JOB_IDENTITY_TOLERANCE_S` from the
    /// one
    /// recorded resets it, rather than it being fixed once. Absent when no
    /// read has
    /// found this print's job reporting a running time — a print opened by an
    /// alert or a start before any read, and every print recorded before this
    /// was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job_started_at: Option<Timestamp>,
    /// Every manifest range this print narrowed to the envelope's.
    pub narrowings: Vec<ManifestNarrowing>,
    /// When the print was opened.
    pub opened_at: Timestamp,
    /// The provider's own identifier for the print, whichever provider
    /// reported it, when one has.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider_print_id: Option<i64>,
    /// The state the print is in.
    pub state: PrinterState,
}

/// One segment of a print this system watched, on one tool: the key of a
/// `ChargeKey::Print` debit, and the only key filament held pending can be
/// under.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintSegmentKey {
    /// The print.
    pub print_id: PrintId,
    /// Which segment, numbered as `ChargeKey::Print` numbers it.
    pub segment: i64,
    /// The tool, in the printer's own numbering.
    pub tool: i64,
}

/// A print started.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintStartedPayload {
    /// The file being printed, when it is known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// The spool loaded on each tool as it started.
    pub loaded: Vec<LoadedSpool>,
    /// The filament check made before it started, when one was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preflight: Option<Preflight>,
    /// The action that started it; absent when the print was observed rather
    /// than started through this system.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub started_by: Option<ActionId>,
}

/// A print that was already open when spool tracking was installed: it is
/// never charged, and this says why it carries no charge.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintUntrackedPayload {
    /// Why the print carries no charge.
    pub reason: String,
}

/// A printer, as a source reported it at one instant.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrinterSnapshot {
    /// The bed heater, when the printer reports one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bed: Option<HeaterSnapshot>,
    /// The chamber heater, when the printer reports one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chamber: Option<HeaterSnapshot>,
    /// The state the printer is in.
    pub connection: PrinterState,
    /// The part-cooling fan, in percent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fan_percent: Option<Reported>,
    /// The feedrate multiplier, where one means one hundred percent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feedrate_factor: Option<Reported>,
    /// The flowrate multiplier, where one means one hundred percent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub flowrate_factor: Option<Reported>,
    /// The instant this observation was taken.
    pub observed_at: Timestamp,
    /// The tool heaters, indexed by tool number.
    pub tools: Vec<HeaterSnapshot>,
}

/// The state a source reports a printer or a print to be in.
///
/// The `unknown` arm exists so that a state nobody anticipated is recorded
/// carrying the source's own word for it rather than lost.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum PrinterState {
    /// Connected and idle.
    #[serde(rename = "operational")]
    Operational,
    /// Printing, but paused.
    #[serde(rename = "paused")]
    Paused,
    /// Printing.
    #[serde(rename = "printing")]
    Printing,
    /// Cancelling a print.
    #[serde(rename = "cancelling")]
    Cancelling,
    /// In an error state.
    #[serde(rename = "error")]
    Error,
    /// Not reachable.
    #[serde(rename = "offline")]
    Offline,
    /// A state this vocabulary does not name, in the source's own word for
    /// it.
    #[serde(rename = "unknown")]
    Unknown(String),
}

/// What the prints read answers: every print, and the one the printer is
/// running.
///
/// An open print's recorded `state` is the state it was opened in, which is
/// `printing` whether or not the machine is paused now; what the machine is
/// doing is the status read's answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PrintsAnswer {
    /// The print the printer's current job belongs to, present exactly when
    /// the
    /// printer reports a job it is printing or has paused. Absent when the
    /// printer could not be read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub active: Option<PrintId>,
    /// Every print this server holds, ended or not, most recently opened
    /// first.
    pub prints: Vec<PrintRecord>,
}

/// An inclusive pair of 64-bit floats.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Range {
    /// The highest value the range admits, inclusive.
    pub max: f64,
    /// The lowest value the range admits, inclusive.
    pub min: f64,
}

/// Bytes exactly as received, base64-encoded.
pub type RawBytes = String;

/// What became of the prints a file's new tally generation counts.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum RebaselineDisposition {
    /// They were accounted as prints this system never saw.
    #[serde(rename = "accounted")]
    Accounted,
    /// It could not be told which of them this system already settled, so the
    /// loaded spool was marked unverified rather than charged on a guess.
    #[serde(rename = "unverified")]
    Unverified,
}

/// Why a request was refused.
///
/// Each rejection is a distinct variant, so a consumer distinguishes them by
/// matching rather than by reading a message.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum RejectionReason {
    /// The value asked for is outside the range allowed for that adjustable.
    #[serde(rename = "out_of_bounds")]
    OutOfBounds {
        /// The adjustable that was asked for.
        adjustable: Adjustable,
        /// The range that was allowed.
        allowed: Range,
        /// The value that was asked for.
        requested: f64,
    },
    /// This actor class may not request this action at all.
    #[serde(rename = "actor_may_not_request")]
    ActorMayNotRequest {
        /// The action they asked for.
        action: ActionKind,
        /// The class of the actor that asked.
        actor_class: ActorClass,
    },
    /// There is no active print to act on.
    #[serde(rename = "no_active_print")]
    NoActivePrint,
    /// The printer is not in a state this action is valid from.
    #[serde(rename = "invalid_from_state")]
    InvalidFromState {
        /// The state the printer is in.
        state: PrinterState,
    },
    /// The agent's minimum interval has not elapsed.
    #[serde(rename = "min_interval_not_elapsed")]
    MinIntervalNotElapsed {
        /// The minimum interval, in whole seconds.
        interval_s: i64,
        /// How long it has been since the last agent action, in whole
        /// seconds.
        since_last_s: i64,
    },
    /// The adjustable is not one this printer has.
    #[serde(rename = "unsupported_adjustable")]
    UnsupportedAdjustable {
        /// The adjustable this printer cannot express.
        adjustable: Adjustable,
    },
    /// A start was refused because the spool on one tool holds less than the
    /// print needs and its buffer.
    #[serde(rename = "insufficient_filament")]
    InsufficientFilament {
        /// The margin asked for beyond that, in grams.
        buffer_g: f64,
        /// What the spool holds, in grams.
        remaining_g: f64,
        /// What the print needs from it, in grams.
        required_g: f64,
        /// The spool loaded on it.
        spool_id: SpoolId,
        /// That spool's name.
        spool_name: String,
        /// The tool whose spool is short.
        tool: i64,
        /// The spool's oldest mark, when the short spool is also unverified.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        unverified: Option<UnverifiedReason>,
    },
    /// A start was refused because the spool on one tool is unverified.
    #[serde(rename = "unverified_spool")]
    UnverifiedSpool {
        /// The spool's oldest mark.
        reason: UnverifiedReason,
        /// The spool loaded on it.
        spool_id: SpoolId,
        /// That spool's name.
        spool_name: String,
        /// The tool whose spool is unverified.
        tool: i64,
    },
    /// A start was refused because `OctoPrint`'s analysis of the file had not
    /// appeared when the start's wait for it elapsed.
    #[serde(rename = "analysis_unavailable")]
    AnalysisUnavailable {
        /// The file that has no analysis.
        file_name: String,
        /// How long the start waited for one, in whole seconds.
        waited_s: i64,
    },
    /// A close was refused because the print record has already ended.
    #[serde(rename = "print_already_ended")]
    PrintAlreadyEnded,
    /// A close was refused because the printer shows a job of the record's
    /// file printing, paused or cancelling.
    #[serde(rename = "print_still_active")]
    PrintStillActive {
        /// The state the printer reported that job in.
        state: PrinterState,
    },
    /// A close was refused because an intervention for the print has neither
    /// expired nor been restored.
    #[serde(rename = "intervention_still_active")]
    InterventionStillActive {
        /// The intervention still standing.
        intervention_id: InterventionId,
    },
    /// A spool command could not be carried out.
    #[serde(rename = "spool_refused")]
    SpoolRefused {
        /// Why, in a form a client acts on without reading `message`.
        cause: SpoolRefusalCause,
        /// Why, in a sentence naming what to do instead, for a person.
        message: String,
    },
}

/// A value as a source reported it, flagged when it is outside the
/// plausibility range this crate declares for its field.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Reported {
    /// One shape of the contracts, which say nothing more about it.
    pub out_of_range: bool,
    /// One shape of the contracts, which say nothing more about it.
    pub value: f64,
}

/// The position a filament change charged up to, and how fresh it is.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SignalPosition {
    /// Whether it was read when the signal was handled, or is the last one
    /// recorded before it.
    pub freshness: PositionFreshness,
    /// The position.
    pub position: FilePosition,
}

/// A spool's remaining figure was corrected.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolAdjustedPayload {
    /// Who corrected it.
    pub actor: Actor,
    /// Every mark the correction cleared.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cleared_marks: Option<Vec<ClearedMark>>,
    /// The scale reading the figure was worked out from, when it was given as
    /// one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub gross_g: Option<f64>,
    /// Why.
    pub reason: String,
    /// Its figure after, in grams.
    pub remaining_after_g: f64,
    /// Its figure before, in grams, after any pending charge it took.
    pub remaining_before_g: f64,
    /// The spool corrected.
    pub spool_id: SpoolId,
    /// The pending charges the correction took first, each also its own
    /// `filament_consumed` event under its key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub took_pending: Option<Vec<PendingTaken>>,
}

/// What one spool's read answers: the spool, and the newest of the printer's
/// own events that name it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolAnswer {
    /// The newest timeline events naming it, newest first.
    pub recent: Vec<EventRecord>,
    /// The spool, retired or not.
    pub spool: SpoolRecord,
}

/// The whole vocabulary of the spool ledger, and there is no other.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "command")]
pub enum SpoolCommand {
    /// Register a spool.
    #[serde(rename = "register_spool")]
    RegisterSpool {
        /// Who is asking.
        actor: Actor,
        /// The filament's colour.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        color: Option<String>,
        /// The material's density, in grams per cubic centimetre; the known
        /// density of the material when absent, and a material with none
        /// known
        /// is refused.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        density_g_cm3: Option<f64>,
        /// The filament's diameter, in millimetres; 1.75 when absent.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        diameter_mm: Option<f64>,
        /// The net filament on the spool when full, in grams.
        initial_g: f64,
        /// The material, such as `PLA`.
        material: String,
        /// The operator's own label for it.
        name: String,
        /// Why the actor is asking for this.
        reason: String,
        /// The filament on it now, in grams; the full figure when absent.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        remaining_g: Option<f64>,
        /// The empty spool's own weight, in grams.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        tare_g: Option<f64>,
    },
    /// Load a spool onto a tool.
    ///
    /// Onto an occupied tool it is a swap, and the spool there is unloaded in
    /// the same write. Naming the spool already on the tool confirms it was
    /// never swapped, which is accepted only while that tool holds a pending
    /// charge or that spool holds a filament-change mark.
    #[serde(rename = "load_spool")]
    LoadSpool {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
        /// The spool to load.
        spool_id: SpoolId,
        /// The tool, in the printer's own numbering.
        tool: i64,
    },
    /// Unload a spool from its tool.
    #[serde(rename = "unload_spool")]
    UnloadSpool {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
        /// The spool to unload.
        spool_id: SpoolId,
    },
    /// Correct a spool's remaining figure, from exactly one of the two; a
    /// command naming both or neither is refused as `spool_refused`.
    #[serde(rename = "adjust_spool")]
    AdjustSpool {
        /// Who is asking.
        actor: Actor,
        /// A scale reading of the spool, in grams, which needs its tare.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        gross_g: Option<f64>,
        /// Why the actor is asking for this.
        reason: String,
        /// The filament left, in grams.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        remaining_g: Option<f64>,
        /// The spool to correct.
        spool_id: SpoolId,
    },
    /// Retire a spool, after which it refuses every command.
    #[serde(rename = "retire_spool")]
    RetireSpool {
        /// Who is asking.
        actor: Actor,
        /// Why the actor is asking for this.
        reason: String,
        /// The spool to retire.
        spool_id: SpoolId,
    },
}

/// What a spool command answers, accepted or refused.
///
/// A refusal is the same shape and deliberately so: the decision carries the
/// grant or the ledger's own reason, and the events are the record the
/// refusal
/// wrote.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolCommandAnswer {
    /// The decision taken on the command.
    pub decision: PolicyDecision,
    /// Every event it wrote, in the order they were written.
    pub events: Vec<EventRecord>,
    /// The spool it was about, as the command left it, when there is one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub spool: Option<SpoolRecord>,
}

/// A spool command was refused.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolCommandRejectedPayload {
    /// The command, as it was asked for.
    pub command: SpoolCommand,
    /// The whole decision, carrying which refusal it was.
    pub decision: PolicyDecision,
}

/// One field of a spool command, as the command names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SpoolField {
    /// The operator's own label for the spool.
    #[serde(rename = "name")]
    Name,
    /// The material, such as `PLA`.
    #[serde(rename = "material")]
    Material,
    /// The filament's diameter, in millimetres.
    #[serde(rename = "diameter_mm")]
    DiameterMm,
    /// The material's density, in grams per cubic centimetre.
    #[serde(rename = "density_g_cm3")]
    DensityGCm3,
    /// The net filament on the spool when full, in grams.
    #[serde(rename = "initial_g")]
    InitialG,
    /// The filament on the spool now, in grams.
    #[serde(rename = "remaining_g")]
    RemainingG,
    /// The empty spool's own weight, in grams.
    #[serde(rename = "tare_g")]
    TareG,
    /// A scale reading of the spool, in grams.
    #[serde(rename = "gross_g")]
    GrossG,
}

/// A lowercase hyphenated version 7 UUID identifying one registered spool.
pub type SpoolId = String;

/// Where a spool is in its life.
///
/// One state rather than a loaded tool beside a retirement instant, because a
/// retired spool is on no tool: retiring a loaded spool takes it off.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "state")]
pub enum SpoolLifecycle {
    /// Registered, and loaded on no tool.
    #[serde(rename = "shelved")]
    Shelved,
    /// Loaded on one tool.
    #[serde(rename = "loaded")]
    Loaded {
        /// The tool, in the printer's own numbering.
        tool: i64,
    },
    /// Retired: it takes no further command, and is on no tool.
    #[serde(rename = "retired")]
    Retired {
        /// When it was retired.
        at: Timestamp,
    },
}

/// A spool was loaded onto a tool, or confirmed as never having left it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolLoadedPayload {
    /// Who loaded it.
    pub actor: Actor,
    /// Every mark the load cleared, on either spool.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cleared_marks: Option<Vec<ClearedMark>>,
    /// Why.
    pub reason: String,
    /// The spool the load swapped off the tool, when it was occupied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub replaced: Option<SpoolId>,
    /// The spool loaded.
    pub spool_id: SpoolId,
    /// The pending charges the load took, each also its own
    /// `filament_consumed` event under its key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub took_pending: Option<Vec<PendingTaken>>,
    /// The tool, in the printer's own numbering.
    pub tool: i64,
}

/// One spool the operator registered, and what is known of it now.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolRecord {
    /// The filament's colour, when the operator gave one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub color: Option<String>,
    /// The material's density, in grams per cubic centimetre; above zero.
    pub density_g_cm3: f64,
    /// The filament's diameter, in millimetres; above zero.
    pub diameter_mm: f64,
    /// This spool's identifier, minted when it was registered.
    pub id: SpoolId,
    /// The net filament on the spool when it was full, in grams; above zero.
    pub initial_g: f64,
    /// Where the spool is in its life: on the shelf, loaded on a tool, or
    /// retired — and never both of the last two.
    pub lifecycle: SpoolLifecycle,
    /// The material, as given and trimmed, such as `PLA`; never empty.
    pub material: String,
    /// The operator's own label for the spool; never empty.
    pub name: String,
    /// When the spool was registered.
    pub registered_at: Timestamp,
    /// The filament left, in grams.
    ///
    /// Always the initial figure less every charge plus every correction. A
    /// charge is never refused or clamped, so this may go below zero.
    pub remaining_g: f64,
    /// The empty spool's own weight, in grams, when the operator gave it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tare_g: Option<f64>,
    /// How far the remaining figure can be trusted.
    pub trust: SpoolTrust,
    /// When anything about the spool last changed.
    pub updated_at: Timestamp,
}

/// Why the spool ledger refused a command, each cause carrying what a client
/// needs to choose the next valid request.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "cause")]
pub enum SpoolRefusalCause {
    /// No spool was ever registered under this identifier.
    #[serde(rename = "unknown_spool")]
    UnknownSpool {
        /// The identifier the command named.
        spool_id: SpoolId,
    },
    /// The spool is retired, and takes no further command.
    #[serde(rename = "retired_spool")]
    RetiredSpool {
        /// The retired spool.
        spool_id: SpoolId,
    },
    /// The spool named is already on the tool, and nothing is pending there
    /// or
    /// marked on it for a load to confirm.
    #[serde(rename = "nothing_to_confirm")]
    NothingToConfirm {
        /// The tool the spool is already on.
        tool: i64,
    },
    /// A figure the command gave is not one the field can hold: not a number,
    /// or out of the field's range.
    #[serde(rename = "invalid_adjustment_figure")]
    InvalidAdjustmentFigure {
        /// The field the figure was given for.
        field: SpoolField,
        /// The figure given; always a number, because a figure JSON cannot
        /// carry is refused as it would be written rather than written as
        /// `null`.
        value: f64,
    },
    /// A scale reading was given for a spool with no tare, so it cannot be
    /// turned into a figure.
    #[serde(rename = "tare_required")]
    TareRequired {
        /// The spool with no tare.
        spool_id: SpoolId,
    },
    /// The material has no known density, so the command needs one.
    #[serde(rename = "density_required")]
    DensityRequired {
        /// The material, as given and trimmed.
        material: String,
        /// The spool, when the command was about one that exists; absent for
        /// a registration.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        spool_id: Option<SpoolId>,
    },
    /// A field the command needs was empty or absent.
    #[serde(rename = "missing_field")]
    MissingField {
        /// The field; for a correction naming neither figure, `remaining_g`,
        /// which `gross_g` may stand in for.
        field: SpoolField,
    },
    /// The command gave fields only one of which it may carry.
    #[serde(rename = "conflicting_fields")]
    ConflictingFields {
        /// Every field given that conflicts, in the command's own order.
        fields: Vec<SpoolField>,
    },
    /// The command named a tool the printer cannot have.
    #[serde(rename = "unknown_tool")]
    UnknownTool {
        /// The tool named.
        tool: i64,
    },
    /// The spool is loaded on no tool, so there is nothing to unload.
    #[serde(rename = "not_loaded")]
    NotLoaded {
        /// The spool.
        spool_id: SpoolId,
    },
    /// The ledger refused the write the command made, because the spools
    /// changed under it; reading them again shows how.
    #[serde(rename = "ledger_refused")]
    LedgerRefused,
}

/// A spool was registered.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolRegisteredPayload {
    /// Who registered it.
    pub actor: Actor,
    /// Why.
    pub reason: String,
    /// The spool, as it was registered.
    pub spool: SpoolRecord,
}

/// A spool was retired.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolRetiredPayload {
    /// Who retired it.
    pub actor: Actor,
    /// Why.
    pub reason: String,
    /// Its figure as it was retired, in grams.
    pub remaining_g: f64,
    /// The spool retired.
    pub spool_id: SpoolId,
}

/// How far a spool's remaining figure can be trusted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "state")]
pub enum SpoolTrust {
    /// Every charge against the spool was taken exactly.
    #[serde(rename = "verified")]
    Verified,
    /// At least one thing happened that could not be charged exactly.
    #[serde(rename = "unverified")]
    Unverified {
        /// Every reason the figure is in doubt, oldest first, at most one per
        /// distinct reason; never empty.
        // llmlint: ignore[invalid_states_unrepresentable] See suppressions.toml.
        marks: Vec<UnverifiedMark>,
    },
}

/// A spool was unloaded from its tool.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolUnloadedPayload {
    /// Who unloaded it.
    pub actor: Actor,
    /// Why.
    pub reason: String,
    /// The spool unloaded.
    pub spool_id: SpoolId,
    /// The tool it left.
    pub tool: i64,
}

/// A spool was marked as one whose figure is in doubt.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolUnverifiedPayload {
    /// Why its figure is in doubt.
    pub reason: UnverifiedReason,
    /// The spool marked.
    pub spool_id: SpoolId,
}

/// What the spools read answers.
///
/// `at_a_glance` is one line per spool, in the order `spools` lists them,
/// composed here so that what is left on each spool is the first thing a
/// reader of either rendering meets rather than a figure inside a whole
/// record. Its name is what puts it first: both renderings walk an answer's
/// fields in name order, ahead of `pending` and `spools`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SpoolsAnswer {
    /// One line per spool in `spools`, in the same order.
    pub at_a_glance: Vec<String>,
    /// Every charge held after a filament change nobody has confirmed, oldest
    /// first: what the next spool loaded on that tool is charged.
    pub pending: Vec<PendingCharge>,
    /// Every spool, retired ones only when asked for, most recently
    /// registered
    /// first.
    pub spools: Vec<SpoolRecord>,
}

/// What one restart put back the way it found it.
///
/// A supervisor that has been restarted adopts whatever the store holds
/// rather
/// than starting empty, and each of these is one of those adoptions. They are
/// recorded rather than merely done, because a print that carried on across a
/// restart and one that was started again look identical afterwards unless
/// the
/// history says which happened.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum StartupOutcome {
    /// A print left open was adopted as the print this supervisor is
    /// watching.
    #[serde(rename = "print_adopted")]
    PrintAdopted,
    /// A session left open was resumed rather than replaced.
    #[serde(rename = "session_resumed")]
    SessionResumed {
        /// The session's own name in the harness.
        session_name: String,
    },
    /// An intervention already past its expiry was expired on start.
    #[serde(rename = "intervention_expired")]
    InterventionExpired {
        /// What it had changed.
        adjustable: Adjustable,
        /// The intervention that had outlived its bound.
        intervention_id: InterventionId,
        /// What became of putting the prior value back.
        outcome: InterventionOutcome,
    },
}

/// A supervisor reconciled one thing the store held when it started.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StartupReconciliationPayload {
    /// What was reconciled.
    pub outcome: StartupOutcome,
    /// The print it is about.
    pub print_id: PrintId,
}

/// What a status read answers.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StatusAnswer {
    /// The bounded interventions still in force.
    pub interventions: Vec<Intervention>,
    /// The job, when a snapshot could be taken.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job: Option<JobSnapshot>,
    /// The print.
    pub print: PrintRecord,
    /// The printer, when a snapshot could be taken.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printer: Option<PrinterSnapshot>,
    /// The supervision session watching it, when one is.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session: Option<SupervisionSession>,
}

/// The supervision session keyed to one print.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SupervisionSession {
    /// Why it was closed, if it was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub close_reason: Option<String>,
    /// When the session was closed, if it was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub closed_at: Option<Timestamp>,
    /// When the session was opened.
    pub created_at: Timestamp,
    /// The identity the harness ran the session under.
    pub harness_identity: String,
    /// When the last turn ran.
    pub last_turn_at: Timestamp,
    /// The print this session watches.
    pub print_id: PrintId,
    /// The session's own name in the harness.
    pub session_name: String,
}

/// A supervision session was closed.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SupervisionSessionClosedPayload {
    /// Why it was closed.
    pub close_reason: String,
    /// The session's own name in the harness.
    pub session_name: String,
}

/// A supervision session was opened.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SupervisionSessionOpenedPayload {
    /// The identity the harness ran it under.
    pub harness_identity: String,
    /// The session's own name in the harness.
    pub session_name: String,
}

/// What a printer history read answers: one page of the printer's own events.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TimelineAnswer {
    /// The events, newest first.
    pub events: Vec<EventRecord>,
    /// The cursor for the following, older page, given as `before`; absent
    /// when there is none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub next: Option<EventId>,
}

/// An instant in UTC, as an RFC 3339 string with a zero offset.
pub type Timestamp = String;

/// The filament one tool feeds, as a length and, when it is known, a volume.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ToolFilament {
    /// The length of filament fed, in millimetres.
    pub length_mm: f64,
    /// The tool, in the printer's own numbering.
    pub tool: i64,
    /// The volume of filament fed, in cubic centimetres, when the source
    /// reported one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub volume_cm3: Option<f64>,
}

/// A print this system never saw was found in the printer's own tally.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UnaccountedPrintPayload {
    /// Whether it was charged against a spool.
    pub charged: bool,
    /// The file that was printed.
    pub file_name: String,
    /// When it was printed, when the printer says.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub printed_at: Option<Timestamp>,
    /// Whether it completed.
    pub success: bool,
}

/// One reason a spool's figure is in doubt, and since when.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UnverifiedMark {
    /// Why the figure is in doubt.
    pub reason: UnverifiedReason,
    /// When the spool was marked for it.
    pub since: Timestamp,
}

/// Why a spool's figure is in doubt.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "reason")]
pub enum UnverifiedReason {
    /// A print ran on the spool's tool and nothing could be charged, because
    /// the file had no analysis — an SD-card file, for one.
    #[serde(rename = "uncharged_print")]
    UnchargedPrint {
        /// The print nothing could be charged for.
        print_id: PrintId,
    },
    /// A print this system never saw ran and did not complete.
    #[serde(rename = "unaccounted_print")]
    UnaccountedPrint {
        /// The file that was printed.
        file_name: String,
        /// When it was printed.
        printed_at: Timestamp,
    },
    /// A filament change was signalled and nobody has said which spool is now
    /// loaded. The spool was charged up to a position read when the signal
    /// was
    /// handled.
    #[serde(rename = "filament_change_unconfirmed")]
    FilamentChangeUnconfirmed {
        /// The print the change was signalled during.
        print_id: PrintId,
    },
    /// A filament change was signalled, nobody has said which spool is now
    /// loaded, and no fresh position could be read at the signal: the spool
    /// was
    /// charged only up to the last recorded position, so its figure may be
    /// overstated.
    #[serde(rename = "filament_change_unconfirmed_position")]
    FilamentChangeUnconfirmedPosition {
        /// The print the change was signalled during.
        print_id: PrintId,
    },
    /// A file's print tally was reset, and it cannot be told which of the
    /// prints since the re-upload were already settled.
    #[serde(rename = "tally_reset")]
    TallyReset {
        /// The file whose tally was reset.
        file_name: String,
        /// Where the file lives, in the printer's own vocabulary.
        origin: String,
    },
}

/// One payload type declared under a kind name, by the domain that owns it.
///
/// The table from kind name to payload type, as the server declares it: every
/// kind below has exactly one implementation here, and a kind this client
/// does not know flows through `EventRecord` untouched.
pub trait EventPayloadKind: serde::de::DeserializeOwned {
    /// The name this payload's events are written down under.
    const KIND: &'static str;
}

impl EventPayloadKind for ActionExecutedPayload {
    const KIND: &'static str = "action_executed";
}

impl EventPayloadKind for ActionRejectedPayload {
    const KIND: &'static str = "action_rejected";
}

impl EventPayloadKind for ActionRequestedPayload {
    const KIND: &'static str = "action_requested";
}

impl EventPayloadKind for AgentAssessmentPayload {
    const KIND: &'static str = "agent_assessment";
}

impl EventPayloadKind for CameraLookPayload {
    const KIND: &'static str = "camera_look";
}

impl EventPayloadKind for ChargePendedPayload {
    const KIND: &'static str = "charge_pended";
}

impl EventPayloadKind for FilamentChangeSignalledPayload {
    const KIND: &'static str = "filament_change_signalled";
}

impl EventPayloadKind for FilamentConsumedPayload {
    const KIND: &'static str = "filament_consumed";
}

impl EventPayloadKind for FileTallyRebaselinedPayload {
    const KIND: &'static str = "file_tally_rebaselined";
}

impl EventPayloadKind for InterventionExpiredPayload {
    const KIND: &'static str = "intervention_expired";
}

impl EventPayloadKind for MalformedExternalEventPayload {
    const KIND: &'static str = "malformed_external_event";
}

impl EventPayloadKind for ObicoFailureAlertPayload {
    const KIND: &'static str = "obico_failure_alert";
}

impl EventPayloadKind for ObicoPrinterNotificationPayload {
    const KIND: &'static str = "obico_printer_notification";
}

impl EventPayloadKind for OperatorAcknowledgementPayload {
    const KIND: &'static str = "operator_acknowledgement";
}

impl EventPayloadKind for PeriodicObservationPayload {
    const KIND: &'static str = "periodic_observation";
}

impl EventPayloadKind for PortFailurePayload {
    const KIND: &'static str = "port_failure";
}

impl EventPayloadKind for PreflightCheckedPayload {
    const KIND: &'static str = "preflight_checked";
}

impl EventPayloadKind for PrintEndedPayload {
    const KIND: &'static str = "print_ended";
}

impl EventPayloadKind for PrintStartedPayload {
    const KIND: &'static str = "print_started";
}

impl EventPayloadKind for PrintUntrackedPayload {
    const KIND: &'static str = "print_untracked";
}

impl EventPayloadKind for SpoolAdjustedPayload {
    const KIND: &'static str = "spool_adjusted";
}

impl EventPayloadKind for SpoolCommandRejectedPayload {
    const KIND: &'static str = "spool_command_rejected";
}

impl EventPayloadKind for SpoolLoadedPayload {
    const KIND: &'static str = "spool_loaded";
}

impl EventPayloadKind for SpoolRegisteredPayload {
    const KIND: &'static str = "spool_registered";
}

impl EventPayloadKind for SpoolRetiredPayload {
    const KIND: &'static str = "spool_retired";
}

impl EventPayloadKind for SpoolUnloadedPayload {
    const KIND: &'static str = "spool_unloaded";
}

impl EventPayloadKind for SpoolUnverifiedPayload {
    const KIND: &'static str = "spool_unverified";
}

impl EventPayloadKind for StartupReconciliationPayload {
    const KIND: &'static str = "startup_reconciliation";
}

impl EventPayloadKind for SupervisionSessionClosedPayload {
    const KIND: &'static str = "supervision_session_closed";
}

impl EventPayloadKind for SupervisionSessionOpenedPayload {
    const KIND: &'static str = "supervision_session_opened";
}

impl EventPayloadKind for UnaccountedPrintPayload {
    const KIND: &'static str = "unaccounted_print";
}

/// Every kind the server declares a payload type for, in name order.
pub const EVENT_KINDS: [&str; 31] = [
    "action_executed",
    "action_rejected",
    "action_requested",
    "agent_assessment",
    "camera_look",
    "charge_pended",
    "filament_change_signalled",
    "filament_consumed",
    "file_tally_rebaselined",
    "intervention_expired",
    "malformed_external_event",
    "obico_failure_alert",
    "obico_printer_notification",
    "operator_acknowledgement",
    "periodic_observation",
    "port_failure",
    "preflight_checked",
    "print_ended",
    "print_started",
    "print_untracked",
    "spool_adjusted",
    "spool_command_rejected",
    "spool_loaded",
    "spool_registered",
    "spool_retired",
    "spool_unloaded",
    "spool_unverified",
    "startup_reconciliation",
    "supervision_session_closed",
    "supervision_session_opened",
    "unaccounted_print",
];

impl EventRecord {
    /// The payload as `P`, when this event is under the kind `P` declares.
    ///
    /// Answers `None` for an event of any other kind — one this client knows
    /// or one it does not — and the parse failure for an event under the
    /// right kind whose payload is not of the type.
    #[must_use]
    pub fn payload_as<P: EventPayloadKind>(&self) -> Option<Result<P, serde_json::Error>> {
        (self.kind == P::KIND).then(|| serde_json::from_value(self.payload.clone()))
    }
}

impl Client {
    /// Call `prints` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    // llmlint: ignore[names_match_behavior] See suppressions.toml.
    pub fn prints(&self) -> Result<PrintsAnswer, ClientError> {
        let target = String::from("/v1/prints");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `status` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn status(&self, print_id: &str) -> Result<StatusAnswer, ClientError> {
        let target = format!("/v1/prints/{print_id}/status");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `context` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn context(&self, print_id: &str) -> Result<ContextAnswer, ClientError> {
        let target = format!("/v1/prints/{print_id}/context");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `image` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn image(&self, image_id: &str) -> Result<ImageAnswer, ClientError> {
        let target = format!("/v1/images/{image_id}");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `history` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn history(
        &self,
        print_id: &str,
        limit: Option<i64>,
    ) -> Result<HistoryAnswer, ClientError> {
        let target = format!("/v1/prints/{print_id}/history");
        let mut asked: Vec<(String, String)> = Vec::new();
        if let Some(value) = limit {
            asked.push(("limit".to_owned(), value.to_string()));
        }
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `events` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn events(
        &self,
        after: Option<String>,
        print_id: Option<String>,
        kinds: Option<Vec<String>>,
        exclude_kinds: Option<Vec<String>>,
        wait_s: Option<i64>,
        limit: Option<i64>,
    ) -> Result<EventsAnswer, ClientError> {
        let target = String::from("/v1/events");
        let mut asked: Vec<(String, String)> = Vec::new();
        if let Some(value) = after {
            asked.push(("after".to_owned(), value));
        }
        if let Some(value) = print_id {
            asked.push(("print_id".to_owned(), value));
        }
        for value in kinds.into_iter().flatten() {
            asked.push(("kinds".to_owned(), value));
        }
        for value in exclude_kinds.into_iter().flatten() {
            asked.push(("exclude_kinds".to_owned(), value));
        }
        if let Some(value) = wait_s {
            asked.push(("wait_s".to_owned(), value.to_string()));
        }
        if let Some(value) = limit {
            asked.push(("limit".to_owned(), value.to_string()));
        }
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `manifest_get` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn manifest_get(&self, print_id: &str) -> Result<ManifestAnswer, ClientError> {
        let target = format!("/v1/prints/{print_id}/manifest");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `look` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn look(&self, print_id: &str, wait_s: Option<i64>) -> Result<Look, ClientError> {
        let target = format!("/v1/prints/{print_id}/look");
        let mut asked: Vec<(String, String)> = Vec::new();
        if let Some(value) = wait_s {
            asked.push(("wait_s".to_owned(), value.to_string()));
        }
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `manifest_set` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn manifest_set(
        &self,
        print_id: &str,
        reason: &str,
        manifest: &JobManifest,
    ) -> Result<ManifestAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/manifest");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        sending.insert("manifest".to_owned(), crate::as_value(&manifest)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("PUT", &target, &asked, sending.as_ref())
    }

    /// Call `spools` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn spools(&self, include_retired: Option<bool>) -> Result<SpoolsAnswer, ClientError> {
        let target = String::from("/v1/spools");
        let mut asked: Vec<(String, String)> = Vec::new();
        if let Some(value) = include_retired {
            asked.push(("include_retired".to_owned(), value.to_string()));
        }
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn spool(&self, spool_id: &str) -> Result<SpoolAnswer, ClientError> {
        let target = format!("/v1/spools/{spool_id}");
        let asked: Vec<(String, String)> = Vec::new();
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `printer_history` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn printer_history(
        &self,
        kinds: Option<Vec<String>>,
        since: Option<String>,
        until: Option<String>,
        spool_id: Option<String>,
        before: Option<String>,
        limit: Option<i64>,
    ) -> Result<TimelineAnswer, ClientError> {
        let target = String::from("/v1/history");
        let mut asked: Vec<(String, String)> = Vec::new();
        for value in kinds.into_iter().flatten() {
            asked.push(("kinds".to_owned(), value));
        }
        if let Some(value) = since {
            asked.push(("since".to_owned(), value));
        }
        if let Some(value) = until {
            asked.push(("until".to_owned(), value));
        }
        if let Some(value) = spool_id {
            asked.push(("spool_id".to_owned(), value));
        }
        if let Some(value) = before {
            asked.push(("before".to_owned(), value));
        }
        if let Some(value) = limit {
            asked.push(("limit".to_owned(), value.to_string()));
        }
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `preflight` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read.
    pub fn preflight(&self, file_name: &str) -> Result<PreflightAnswer, ClientError> {
        let target = String::from("/v1/preflight");
        let asked: Vec<(String, String)> = vec![("file_name".to_owned(), file_name.to_owned())];
        let sending: Option<serde_json::Value> = None;
        self.call("GET", &target, &asked, sending.as_ref())
    }

    /// Call `pause` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn pause(&self, print_id: &str, reason: &str) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/pause");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `resume` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn resume(&self, print_id: &str, reason: &str) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/resume");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `cancel` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn cancel(&self, print_id: &str, reason: &str) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/cancel");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `start_print` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn start_print(
        &self,
        print_id: &str,
        file_name: &FileName,
        manifest: &JobManifest,
        reason: &str,
        override_filament_check: Option<bool>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/start_print");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("file_name".to_owned(), crate::as_value(&file_name)?);
        sending.insert("manifest".to_owned(), crate::as_value(&manifest)?);
        if let Some(value) = override_filament_check {
            sending.insert(
                "override_filament_check".to_owned(),
                crate::as_value(&value)?,
            );
        }
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `set_feedrate_factor` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn set_feedrate_factor(
        &self,
        print_id: &str,
        factor: f64,
        reason: &str,
        duration_s: Option<i64>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/set_feedrate_factor");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = duration_s {
            sending.insert("duration_s".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("factor".to_owned(), crate::as_value(&factor)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `set_flowrate_factor` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn set_flowrate_factor(
        &self,
        print_id: &str,
        factor: f64,
        reason: &str,
        duration_s: Option<i64>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/set_flowrate_factor");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = duration_s {
            sending.insert("duration_s".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("factor".to_owned(), crate::as_value(&factor)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `set_tool_target_c` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn set_tool_target_c(
        &self,
        print_id: &str,
        reason: &str,
        target_c: f64,
        tool: i64,
        duration_s: Option<i64>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/set_tool_target_c");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = duration_s {
            sending.insert("duration_s".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        sending.insert("target_c".to_owned(), crate::as_value(&target_c)?);
        sending.insert("tool".to_owned(), crate::as_value(&tool)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `set_bed_target_c` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn set_bed_target_c(
        &self,
        print_id: &str,
        reason: &str,
        target_c: f64,
        duration_s: Option<i64>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/set_bed_target_c");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = duration_s {
            sending.insert("duration_s".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        sending.insert("target_c".to_owned(), crate::as_value(&target_c)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `set_fan_percent` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn set_fan_percent(
        &self,
        print_id: &str,
        percent: f64,
        reason: &str,
        duration_s: Option<i64>,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/set_fan_percent");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = duration_s {
            sending.insert("duration_s".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("percent".to_owned(), crate::as_value(&percent)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `acknowledge_failure` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn acknowledge_failure(
        &self,
        print_id: &str,
        disposition: &AcknowledgementDisposition,
        event_id: &EventId,
        reason: &str,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/acknowledge_failure");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("disposition".to_owned(), crate::as_value(&disposition)?);
        sending.insert("event_id".to_owned(), crate::as_value(&event_id)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `close_print` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn close_print(
        &self,
        print_id: &str,
        outcome: &PrintOutcome,
        reason: &str,
    ) -> Result<ActionAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/prints/{print_id}/actions/close_print");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("outcome".to_owned(), crate::as_value(&outcome)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `register_spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    // One argument per value the operation declares, as every client takes them; suppressions.toml has the reason.
    #[expect(clippy::too_many_arguments)]
    pub fn register_spool(
        &self,
        initial_g: f64,
        material: &str,
        name: &str,
        reason: &str,
        color: Option<String>,
        density_g_cm3: Option<f64>,
        diameter_mm: Option<f64>,
        remaining_g: Option<f64>,
        tare_g: Option<f64>,
    ) -> Result<SpoolCommandAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = String::from("/v1/spools/actions/register_spool");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = color {
            sending.insert("color".to_owned(), crate::as_value(&value)?);
        }
        if let Some(value) = density_g_cm3 {
            sending.insert("density_g_cm3".to_owned(), crate::as_value(&value)?);
        }
        if let Some(value) = diameter_mm {
            sending.insert("diameter_mm".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("initial_g".to_owned(), crate::as_value(&initial_g)?);
        sending.insert("material".to_owned(), crate::as_value(&material)?);
        sending.insert("name".to_owned(), crate::as_value(&name)?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        if let Some(value) = remaining_g {
            sending.insert("remaining_g".to_owned(), crate::as_value(&value)?);
        }
        if let Some(value) = tare_g {
            sending.insert("tare_g".to_owned(), crate::as_value(&value)?);
        }
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `load_spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn load_spool(
        &self,
        spool_id: &str,
        reason: &str,
        tool: i64,
    ) -> Result<SpoolCommandAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/spools/{spool_id}/actions/load_spool");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        sending.insert("tool".to_owned(), crate::as_value(&tool)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `unload_spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn unload_spool(
        &self,
        spool_id: &str,
        reason: &str,
    ) -> Result<SpoolCommandAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/spools/{spool_id}/actions/unload_spool");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `adjust_spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn adjust_spool(
        &self,
        spool_id: &str,
        reason: &str,
        gross_g: Option<f64>,
        remaining_g: Option<f64>,
    ) -> Result<SpoolCommandAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/spools/{spool_id}/actions/adjust_spool");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        if let Some(value) = gross_g {
            sending.insert("gross_g".to_owned(), crate::as_value(&value)?);
        }
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        if let Some(value) = remaining_g {
            sending.insert("remaining_g".to_owned(), crate::as_value(&value)?);
        }
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }

    /// Call `retire_spool` on the configured supervisor.
    ///
    /// # Errors
    ///
    /// Returns `ClientError` when the supervisor could not be reached, when
    /// it answered something this client cannot read, when this client
    /// refuses the call before making it because the reason is empty, and
    /// when the policy refused the action — which arrives as
    /// `ClientError::Rejected`, carrying the reason, the value asked for and
    /// the range allowed.
    pub fn retire_spool(
        &self,
        spool_id: &str,
        reason: &str,
    ) -> Result<SpoolCommandAnswer, ClientError> {
        crate::reason_given(reason)?;
        let target = format!("/v1/spools/{spool_id}/actions/retire_spool");
        let asked: Vec<(String, String)> = Vec::new();
        let mut sending = serde_json::Map::new();
        sending.insert("actor".to_owned(), crate::as_value(&self.actor())?);
        sending.insert("reason".to_owned(), crate::as_value(&reason)?);
        let sending = Some(serde_json::Value::Object(sending));
        self.call("POST", &target, &asked, sending.as_ref())
    }
}