@printobserver/sdk 0.3.0 → 0.4.0

package/dist/client.d.ts

@@ -25,10 +25,11 @@ export interface ClientOptions {
     actor: Actor;
     /**
      * What authenticates to it. The supervisor serves no versioned operation to a
-     * caller that does not present the credential it is configured with — its
-     * `api.credential`, or the one it generated into its state directory and
-     * wrote into the client configuration beside it — and a call it refuses for
-     * that throws `Refused` with status 401.
+     * caller that does not present a credential it admits — the operator's, whose
+     * verifier it is configured with and which `printobserver credential issue`
+     * issues, or the one a supervision turn is handed — and a call it refuses for
+     * that throws `Refused` with status 401. A call whose actor is not the
+     * identity that credential is throws it with status 403.
      */
     credential?: string;
 }

package/dist/client.js

@@ -115,7 +115,9 @@ function refusalText(said) {
 /** The policy's own refusal, as the answer to it carries it. */
 function rejection(status, said) {
     const answer = document(status, said);
-    const decision = answer.record.decision;
+    // An action's answer carries its decision in its record; a spool command's
+    // carries it at the top.
+    const decision = "record" in answer ? answer.record.decision : answer.decision;
     if (typeof decision !== "object" || !("rejected" in decision)) {
         return new Unreadable(status, "the supervisor refused this action and answered a record whose decision is not a refusal");
     }

package/dist/contract.d.ts

@@ -18,7 +18,7 @@ export declare const CONTRACT_VERSION: string;
  * Every operation this client exposes a method for, which is every operation
  * the server declares and no other.
  */
-export declare const OPERATION_NAMES: readonly ["prints", "status", "context", "image", "history", "manifest_get", "manifest_set", "pause", "resume", "cancel", "start_print", "set_feedrate_factor", "set_flowrate_factor", "set_tool_target_c", "set_bed_target_c", "set_fan_percent", "acknowledge_failure"];
+export declare const OPERATION_NAMES: readonly ["prints", "status", "context", "image", "history", "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", "register_spool", "load_spool", "unload_spool", "adjust_spool", "retire_spool"];
 /** What an operator's acknowledgement of a failure event asks for next. */
 export type AcknowledgementDisposition = "continue" | "watch" | "stop";
 /** What one mutating request left behind it. */
@@ -50,7 +50,7 @@ export type ActionId = string;
  * the
  * payload lives on `PrintAction` itself.
  */
-export type ActionKind = "pause" | "resume" | "cancel" | "start_print" | "set_feedrate_factor" | "set_flowrate_factor" | "set_tool_target_c" | "set_bed_target_c" | "set_fan_percent" | "acknowledge_failure";
+export type ActionKind = "pause" | "resume" | "cancel" | "start_print" | "set_feedrate_factor" | "set_flowrate_factor" | "set_tool_target_c" | "set_bed_target_c" | "set_fan_percent" | "acknowledge_failure" | "register_spool" | "load_spool" | "unload_spool" | "adjust_spool" | "retire_spool";
 /**
  * One request, the decision taken on it, and what became of it.
  *
@@ -134,6 +134,56 @@ export interface AgentAssessmentPayload {
     /** The session the turn ran in. */
     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.
+ */
+export interface CameraLookPayload {
+    /**
+     * The events for the print that arrived while it waited, and that it
+     * handed to whoever looked, oldest first.
+     */
+    delivered?: Array<EventId>;
+    /**
+     * How long the look waited for something to happen before it was taken,
+     * in whole seconds.
+     */
+    waited_s: number;
+}
+/** The durable identity of one debit, so that a replay can never debit twice. */
+export type ChargeKey = {
+    key: "print";
+    print_id: PrintId;
+    segment: number;
+    tool: number;
+} | {
+    key: "unobserved";
+    file_name: string;
+    generation: number;
+    origin: string;
+    print_number: number;
+    tool: number;
+};
+/** How the length a charge debits was worked out. */
+export type ChargeMethod = "slicer_estimate" | "gcode_extrusion" | "file_fraction" | "unobserved_estimate";
+/**
+ * Filament a tool fed after an unconfirmed filament change was held for the
+ * next spool loaded onto that tool, or confirmed on it.
+ */
+export interface ChargePendedPayload {
+    /** What was held. */
+    pending: PendingCharge;
+}
+/** One mark a spool command cleared, and the spool it was cleared from. */
+export interface ClearedMark {
+    /** The reason that no longer stands. */
+    reason: UnverifiedReason;
+    /** The spool the mark was cleared from. */
+    spool_id: SpoolId;
+}
 /**
  * How sure the agent is.
  *
@@ -220,11 +270,106 @@ export type ExecutionOutcome = "succeeded" | {
         reason: string;
     };
 };
+/** A filament change was signalled during a print. */
+export interface FilamentChangeSignalledPayload {
+    /** The position the spool was charged up to, when one was known. */
+    position?: FilePosition | null;
+    /**
+     * Whether that position was read when the signal was handled, rather than
+     * being the last one recorded; never with no position at all.
+     */
+    position_read_at_signal: boolean;
+    /** The kind of the alert that carried the signal. */
+    source_kind: EventKind;
+    /** The spool that was on it, when one was tracked. */
+    spool_id?: SpoolId | null;
+    /** The tool the change was signalled for, when it is known. */
+    tool?: number | null;
+}
+/** Filament was charged against a spool, or recorded uncharged. */
+export interface FilamentConsumedPayload {
+    /**
+     * The file's analysed length for the tool, in millimetres, when it had
+     * one.
+     */
+    analysed_length_mm?: number | null;
+    /** The durable identity of this debit. */
+    charge_key: ChargeKey;
+    /**
+     * The density the grams were worked out with, in grams per cubic
+     * centimetre.
+     */
+    density_g_cm3?: number | null;
+    /** The diameter the grams were worked out with, in millimetres. */
+    diameter_mm?: number | null;
+    /**
+     * What that length weighs, in grams, when a spool gave its diameter and
+     * density.
+     */
+    grams?: number | null;
+    /** How much was fed, in millimetres. */
+    length_mm: number;
+    /** How the length was worked out. */
+    method: ChargeMethod;
+    /** Anything a reader needs to make sense of the figure. */
+    note?: string | null;
+    /** How far into the file the charge runs, when that was read. */
+    position?: FilePosition | null;
+    /** The spool's figure after it, in grams. */
+    remaining_after_g?: number | null;
+    /** The spool's figure before the charge, in grams. */
+    remaining_before_g?: number | null;
+    /**
+     * The spool charged; absent when nothing was tracked on the tool, and the
+     * filament was recorded uncharged.
+     */
+    spool_id?: SpoolId | null;
+    /** The tool that fed it. */
+    tool: number;
+}
 /**
  * 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.
  */
 export type FileName = string;
+/** How far into its file a print had got, and when that was read. */
+export interface FilePosition {
+    /** The byte the printer had read the file up to. */
+    bytes: number;
+    /** When the position was read. */
+    observed_at: Timestamp;
+    /** The file's size in bytes, when it was known. */
+    size_bytes?: number | null;
+}
+/**
+ * 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.
+ */
+export interface FileTallyRebaselinedPayload {
+    /** What became of the prints the new generation counts. */
+    disposition: RebaselineDisposition;
+    /** The file whose tally went down. */
+    file_name: string;
+    /** The failed prints the new tally counts. */
+    new_failures: number;
+    /** The generation it is in now. */
+    new_generation: number;
+    /** The completed prints the new tally counts. */
+    new_successes: number;
+    /** The failed prints the old tally counted. */
+    old_failures: number;
+    /** The generation the tally was in. */
+    old_generation: number;
+    /** The completed prints the old tally counted. */
+    old_successes: number;
+    /** Where it lives, in the printer's own vocabulary. */
+    origin: string;
+}
 /**
  * One heater, as a source reported it.
  *
@@ -388,10 +533,20 @@ export interface JobSnapshot {
     error?: string | null;
     /** The whole print's estimated duration, in whole seconds. */
     estimated_print_time_s?: number | null;
+    /**
+     * The filament the source's analysis of the file says each tool uses;
+     * empty when the source reported none.
+     */
+    filament?: Array<ToolFilament>;
     /** The name of the file being printed, as the source reported it. */
     file_name?: string | null;
     /** Where the file lives, in the source's own vocabulary. */
     file_origin?: string | null;
+    /**
+     * How far into the file the printer has read, in bytes, when the source
+     * reported it.
+     */
+    file_position_bytes?: number | null;
     /** How long the print has left, in whole seconds. */
     print_time_left_s?: number | null;
     /** How long the print has been running, in whole seconds. */
@@ -401,6 +556,48 @@ export interface JobSnapshot {
     /** The state the source reports the job to be in. */
     state: PrinterState;
 }
+/** One spool loaded on one tool, as a print started. */
+export interface LoadedSpool {
+    /** The spool loaded on it. */
+    spool_id: SpoolId;
+    /** The tool, in the printer's own numbering. */
+    tool: number;
+}
+/**
+ * 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.
+ */
+export interface Look {
+    /**
+     * The events for this print that arrived while the look waited, oldest
+     * first; the look returned early when there were any.
+     */
+    arrived?: Array<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.
+     */
+    detector_paused: boolean;
+    /**
+     * The look itself, as it was written into the print's history, carrying
+     * the frame as its image when there is one.
+     */
+    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.
+     */
+    frame?: ImageRef | null;
+    /** The absolute path the frame's bytes are at, on the supervisor's host. */
+    image_path?: string | null;
+    /** The job the printer reports now, absent when it could not be read. */
+    job?: JobSnapshot | null;
+    /** The printer's state now, absent when it could not be read. */
+    printer?: PrinterSnapshot | null;
+}
 /**
  * An external body arrived that could not be read.
  *
@@ -485,6 +682,72 @@ export interface OperatorAcknowledgementPayload {
     /** What the operator asked for next. */
     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.
+ */
+export interface PendingCharge {
+    /**
+     * The file's analysed length for the tool, in millimetres, when it had
+     * one.
+     */
+    analysed_length_mm?: number | null;
+    /** The key of the print segment the filament was fed in. */
+    charge_key: ChargeKey;
+    /** How much was fed, in millimetres. */
+    length_mm: number;
+    /** How that length was worked out. */
+    method: ChargeMethod;
+    /** Anything a reader needs to make sense of the figure. */
+    note?: string | null;
+    /** When it was held. */
+    pended_at: Timestamp;
+    /** How far into the file the segment ran, when that was read. */
+    position?: FilePosition | null;
+    /** The print it was fed in. */
+    print_id: PrintId;
+    /** The tool that fed it. */
+    tool: number;
+}
+/** One pending charge a spool command took. */
+export interface PendingTaken {
+    /** The key it is charged under. */
+    charge_key: ChargeKey;
+    /** The print it was fed in. */
+    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.
+ */
+export interface PeriodicObservationPayload {
+    /** How often these are taken, in whole seconds. */
+    interval_s: number;
+    /**
+     * The job the printer reported as the observation was taken, absent when
+     * it could not be read.
+     */
+    job?: JobSnapshot | null;
+    /**
+     * The printer's state as the observation was taken, absent when it could
+     * not be read — which the history records as a port failure.
+     */
+    printer?: PrinterSnapshot | null;
+}
 /** The decision policy took on one request. */
 export type PolicyDecision = "accepted" | {
     rejected: RejectionReason;
@@ -520,7 +783,60 @@ export interface PortFailurePayload {
  * be
  * a second version of one fact.
  */
-export type PortFailureSite = "printer_snapshot" | "printer_job" | "image_write" | "supervision_turn";
+export type PortFailureSite = "printer_snapshot" | "printer_job" | "image_write" | "supervision_turn" | "camera_look" | "detector_acknowledgement";
+/** What a filament check found for one print. */
+export interface Preflight {
+    /** When the check was made. */
+    checked_at: Timestamp;
+    /** The file the print is of. */
+    file_name: string;
+    /** What it found for each tool. */
+    tools: Array<PreflightTool>;
+    /**
+     * The worst of the tools' verdicts, in the order insufficient,
+     * unverified spool, no analysis, warned, overridden, unchecked, passed.
+     */
+    verdict: PreflightVerdict;
+}
+/** What a filament check answers. */
+export interface PreflightAnswer {
+    /** What the check found, read now. */
+    preflight: Preflight;
+}
+/** The filament check before a start was made. */
+export interface PreflightCheckedPayload {
+    /** The start it was made for, when it was made for one. */
+    action_id?: ActionId | null;
+    /** What the check found. */
+    preflight: Preflight;
+}
+/** What a filament check found for one tool. */
+export interface PreflightTool {
+    /** The margin asked for beyond that, in grams. */
+    buffer_g?: number | null;
+    /**
+     * The loaded spool's marks at the check, oldest first, whatever the
+     * verdict, so a spool both short and unverified says both.
+     */
+    marks?: Array<UnverifiedMark>;
+    /** What the spool holds, in grams. */
+    remaining_g?: number | null;
+    /** What the print needs from it, in grams, when the file's analysis says. */
+    required_g?: number | null;
+    /** The spool loaded on it, when one is. */
+    spool_id?: SpoolId | null;
+    /**
+     * That spool's name, beside its identifier, so a reader need not look it
+     * up.
+     */
+    spool_name?: string | null;
+    /** The tool, in the printer's own numbering. */
+    tool: number;
+    /** What the check found for this tool. */
+    verdict: PreflightVerdict;
+}
+/** What a filament check found, for one tool or for a whole print. */
+export type PreflightVerdict = "passed" | "unchecked" | "insufficient" | "unverified_spool" | "no_analysis" | "overridden" | "warned";
 /** The whole vocabulary an actor may ask for, and there is no other. */
 export type PrintAction = {
     action: "pause";
@@ -539,6 +855,7 @@ export type PrintAction = {
     actor: Actor;
     file_name: FileName;
     manifest: JobManifest;
+    override_filament_check?: boolean;
     reason: string;
 } | {
     action: "set_feedrate_factor";
@@ -597,8 +914,21 @@ export interface PrintContext {
     /** A bounded list of this print's events, newest first. */
     recent_events: Array<EventRecord>;
 }
+/** A print ended. */
+export interface PrintEndedPayload {
+    /** How far into its file it last read, when that was read. */
+    last_position?: FilePosition | null;
+    /** How it ended. */
+    outcome: PrintOutcome;
+    /** Why it ended, in the words the end was recorded with. */
+    reason: string;
+    /** The state the printer was in as it ended. */
+    state: PrinterState;
+}
 /** A lowercase hyphenated version 7 UUID identifying one print. */
 export type PrintId = string;
+/** How a print ended. */
+export type PrintOutcome = "completed" | "cancelled" | "failed";
 /**
  * One print, and the record supervision keys from.
  *
@@ -615,6 +945,31 @@ export interface PrintRecord {
     file_name?: string | null;
     /** This print's identifier, minted by the store. */
     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.
+     */
+    job_print_time_s?: number | null;
+    /**
+     * 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.
+     */
+    job_started_at?: Timestamp | null;
     /** Every manifest range this print narrowed to the envelope's. */
     narrowings: Array<ManifestNarrowing>;
     /** When the print was opened. */
@@ -627,6 +982,28 @@ export interface PrintRecord {
     /** The state the print is in. */
     state: PrinterState;
 }
+/** A print started. */
+export interface PrintStartedPayload {
+    /** The file being printed, when it is known. */
+    file_name?: string | null;
+    /** The spool loaded on each tool as it started. */
+    loaded: Array<LoadedSpool>;
+    /** The filament check made before it started, when one was. */
+    preflight?: Preflight | null;
+    /**
+     * The action that started it; absent when the print was observed rather
+     * than started through this system.
+     */
+    started_by?: ActionId | null;
+}
+/**
+ * A print that was already open when spool tracking was installed: it is
+ * never charged, and this says why it carries no charge.
+ */
+export interface PrintUntrackedPayload {
+    /** Why the print carries no charge. */
+    reason: string;
+}
 /** A printer, as a source reported it at one instant. */
 export interface PrinterSnapshot {
     /** The bed heater, when the printer reports one. */
@@ -682,6 +1059,8 @@ export interface Range {
 }
 /** Bytes exactly as received, base64-encoded. */
 export type RawBytes = string;
+/** What became of the prints a file's new tally generation counts. */
+export type RebaselineDisposition = "accounted" | "unverified";
 /**
  * Why a request was refused.
  *
@@ -712,6 +1091,32 @@ export type RejectionReason = {
     unsupported_adjustable: {
         adjustable: Adjustable;
     };
+} | {
+    insufficient_filament: {
+        buffer_g: number;
+        remaining_g: number;
+        required_g: number;
+        spool_id: SpoolId;
+        spool_name: string;
+        tool: number;
+        unverified?: UnverifiedReason | null;
+    };
+} | {
+    unverified_spool: {
+        reason: UnverifiedReason;
+        spool_id: SpoolId;
+        spool_name: string;
+        tool: number;
+    };
+} | {
+    analysis_unavailable: {
+        file_name: string;
+        waited_s: number;
+    };
+} | {
+    spool_refused: {
+        detail: string;
+    };
 };
 /**
  * A value as a source reported it, flagged when it is outside the
@@ -723,6 +1128,227 @@ export interface Reported {
     /** One shape of the contracts, which say nothing more about it. */
     value: number;
 }
+/** A spool's remaining figure was corrected. */
+export interface SpoolAdjustedPayload {
+    /** Who corrected it. */
+    actor: Actor;
+    /** Every mark the correction cleared. */
+    cleared_marks?: Array<ClearedMark>;
+    /**
+     * The scale reading the figure was worked out from, when it was given as
+     * one.
+     */
+    gross_g?: number | null;
+    /** Why. */
+    reason: string;
+    /** Its figure after, in grams. */
+    remaining_after_g: number;
+    /** Its figure before, in grams, after any pending charge it took. */
+    remaining_before_g: number;
+    /** The spool corrected. */
+    spool_id: SpoolId;
+    /**
+     * The pending charges the correction took first, each also its own
+     * `filament_consumed` event under its key.
+     */
+    took_pending?: Array<PendingTaken>;
+}
+/**
+ * What one spool's read answers: the spool, and the newest of the printer's
+ * own events that name it.
+ */
+export interface SpoolAnswer {
+    /** The newest timeline events naming it, newest first. */
+    recent: Array<EventRecord>;
+    /** The spool, retired or not. */
+    spool: SpoolRecord;
+}
+/** The whole vocabulary of the spool ledger, and there is no other. */
+export type SpoolCommand = {
+    command: "register_spool";
+    actor: Actor;
+    color?: string | null;
+    density_g_cm3?: number | null;
+    diameter_mm?: number | null;
+    initial_g: number;
+    material: string;
+    name: string;
+    reason: string;
+    remaining_g?: number | null;
+    tare_g?: number | null;
+} | {
+    command: "load_spool";
+    actor: Actor;
+    reason: string;
+    spool_id: SpoolId;
+    tool: number;
+} | {
+    command: "unload_spool";
+    actor: Actor;
+    reason: string;
+    spool_id: SpoolId;
+} | {
+    command: "adjust_spool";
+    actor: Actor;
+    gross_g?: number | null;
+    reason: string;
+    remaining_g?: number | null;
+    spool_id: SpoolId;
+} | {
+    command: "retire_spool";
+    actor: Actor;
+    reason: string;
+    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.
+ */
+export interface SpoolCommandAnswer {
+    /** The decision taken on the command. */
+    decision: PolicyDecision;
+    /** Every event it wrote, in the order they were written. */
+    events: Array<EventRecord>;
+    /** The spool it was about, as the command left it, when there is one. */
+    spool?: SpoolRecord | null;
+}
+/** A spool command was refused. */
+export interface SpoolCommandRejectedPayload {
+    /** The command, as it was asked for. */
+    command: SpoolCommand;
+    /** The whole decision, carrying which refusal it was. */
+    decision: PolicyDecision;
+}
+/** A lowercase hyphenated version 7 UUID identifying one registered spool. */
+export type SpoolId = string;
+/** A spool was loaded onto a tool, or confirmed as never having left it. */
+export interface SpoolLoadedPayload {
+    /** Who loaded it. */
+    actor: Actor;
+    /** Every mark the load cleared, on either spool. */
+    cleared_marks?: Array<ClearedMark>;
+    /** Why. */
+    reason: string;
+    /** The spool the load swapped off the tool, when it was occupied. */
+    replaced?: SpoolId | null;
+    /** The spool loaded. */
+    spool_id: SpoolId;
+    /**
+     * The pending charges the load took, each also its own
+     * `filament_consumed` event under its key.
+     */
+    took_pending?: Array<PendingTaken>;
+    /** The tool, in the printer's own numbering. */
+    tool: number;
+}
+/** One spool the operator registered, and what is known of it now. */
+export interface SpoolRecord {
+    /** The filament's colour, when the operator gave one. */
+    color?: string | null;
+    /** The material's density, in grams per cubic centimetre; above zero. */
+    density_g_cm3: number;
+    /** The filament's diameter, in millimetres; above zero. */
+    diameter_mm: number;
+    /** This spool's identifier, minted when it was registered. */
+    id: SpoolId;
+    /** The net filament on the spool when it was full, in grams; above zero. */
+    initial_g: number;
+    /** The tool the spool is loaded on, when it is loaded. */
+    loaded_on_tool?: number | null;
+    /** The material, as given and trimmed, such as `PLA`; never empty. */
+    material: string;
+    /** The operator's own label for the spool; never empty. */
+    name: string;
+    /** When the spool was registered. */
+    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.
+     */
+    remaining_g: number;
+    /** When the spool was retired, if it has been. */
+    retired_at?: Timestamp | null;
+    /** The empty spool's own weight, in grams, when the operator gave it. */
+    tare_g?: number | null;
+    /** How far the remaining figure can be trusted. */
+    trust: SpoolTrust;
+    /** When anything about the spool last changed. */
+    updated_at: Timestamp;
+}
+/** A spool was registered. */
+export interface SpoolRegisteredPayload {
+    /** Who registered it. */
+    actor: Actor;
+    /** Why. */
+    reason: string;
+    /** The spool, as it was registered. */
+    spool: SpoolRecord;
+}
+/** A spool was retired. */
+export interface SpoolRetiredPayload {
+    /** Who retired it. */
+    actor: Actor;
+    /** Why. */
+    reason: string;
+    /** Its figure as it was retired, in grams. */
+    remaining_g: number;
+    /** The spool retired. */
+    spool_id: SpoolId;
+}
+/** How far a spool's remaining figure can be trusted. */
+export type SpoolTrust = {
+    state: "verified";
+} | {
+    state: "unverified";
+    marks: Array<UnverifiedMark>;
+};
+/** A spool was unloaded from its tool. */
+export interface SpoolUnloadedPayload {
+    /** Who unloaded it. */
+    actor: Actor;
+    /** Why. */
+    reason: string;
+    /** The spool unloaded. */
+    spool_id: SpoolId;
+    /** The tool it left. */
+    tool: number;
+}
+/** A spool was marked as one whose figure is in doubt. */
+export interface SpoolUnverifiedPayload {
+    /** Why its figure is in doubt. */
+    reason: UnverifiedReason;
+    /** The spool marked. */
+    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`.
+ */
+export interface SpoolsAnswer {
+    /** One line per spool in `spools`, in the same order. */
+    at_a_glance: Array<string>;
+    /**
+     * Every charge held after a filament change nobody has confirmed, oldest
+     * first: what the next spool loaded on that tool is charged.
+     */
+    pending: Array<PendingCharge>;
+    /**
+     * Every spool, retired ones only when asked for, most recently registered
+     * first.
+     */
+    spools: Array<SpoolRecord>;
+}
 /**
  * What one restart put back the way it found it.
  *
@@ -796,8 +1422,67 @@ export interface SupervisionSessionOpenedPayload {
     /** The session's own name in the harness. */
     session_name: string;
 }
+/** What a printer history read answers: one page of the printer's own events. */
+export interface TimelineAnswer {
+    /** The events, newest first. */
+    events: Array<EventRecord>;
+    /**
+     * The cursor for the following, older page, given as `before`; absent
+     * when there is none.
+     */
+    next?: EventId | null;
+}
 /** An instant in UTC, as an RFC 3339 string with a zero offset. */
 export type Timestamp = string;
+/** The filament one tool feeds, as a length and, when it is known, a volume. */
+export interface ToolFilament {
+    /** The length of filament fed, in millimetres. */
+    length_mm: number;
+    /** The tool, in the printer's own numbering. */
+    tool: number;
+    /**
+     * The volume of filament fed, in cubic centimetres, when the source
+     * reported one.
+     */
+    volume_cm3?: number | null;
+}
+/** A print this system never saw was found in the printer's own tally. */
+export interface UnaccountedPrintPayload {
+    /** Whether it was charged against a spool. */
+    charged: boolean;
+    /** The file that was printed. */
+    file_name: string;
+    /** When it was printed, when the printer says. */
+    printed_at?: Timestamp | null;
+    /** Whether it completed. */
+    success: boolean;
+}
+/** One reason a spool's figure is in doubt, and since when. */
+export interface UnverifiedMark {
+    /** Why the figure is in doubt. */
+    reason: UnverifiedReason;
+    /** When the spool was marked for it. */
+    since: Timestamp;
+}
+/** Why a spool's figure is in doubt. */
+export type UnverifiedReason = {
+    reason: "uncharged_print";
+    print_id: PrintId;
+} | {
+    reason: "unaccounted_print";
+    file_name: string;
+    printed_at: Timestamp;
+} | {
+    reason: "filament_change_unconfirmed";
+    print_id: PrintId;
+} | {
+    reason: "filament_change_unconfirmed_position";
+    print_id: PrintId;
+} | {
+    reason: "tally_reset";
+    file_name: string;
+    origin: string;
+};
 /**
  * Every kind the server declares a payload type for, keyed by the kind's
  * name, and the type each payload has. A kind this client does not know
@@ -808,18 +1493,36 @@ export interface EventPayloads {
     action_rejected: ActionRejectedPayload;
     action_requested: ActionRequestedPayload;
     agent_assessment: AgentAssessmentPayload;
+    camera_look: CameraLookPayload;
+    charge_pended: ChargePendedPayload;
+    filament_change_signalled: FilamentChangeSignalledPayload;
+    filament_consumed: FilamentConsumedPayload;
+    file_tally_rebaselined: FileTallyRebaselinedPayload;
     intervention_expired: InterventionExpiredPayload;
     malformed_external_event: MalformedExternalEventPayload;
     obico_failure_alert: ObicoFailureAlertPayload;
     obico_printer_notification: ObicoPrinterNotificationPayload;
     operator_acknowledgement: OperatorAcknowledgementPayload;
+    periodic_observation: PeriodicObservationPayload;
     port_failure: PortFailurePayload;
+    preflight_checked: PreflightCheckedPayload;
+    print_ended: PrintEndedPayload;
+    print_started: PrintStartedPayload;
+    print_untracked: PrintUntrackedPayload;
+    spool_adjusted: SpoolAdjustedPayload;
+    spool_command_rejected: SpoolCommandRejectedPayload;
+    spool_loaded: SpoolLoadedPayload;
+    spool_registered: SpoolRegisteredPayload;
+    spool_retired: SpoolRetiredPayload;
+    spool_unloaded: SpoolUnloadedPayload;
+    spool_unverified: SpoolUnverifiedPayload;
     startup_reconciliation: StartupReconciliationPayload;
     supervision_session_closed: SupervisionSessionClosedPayload;
     supervision_session_opened: SupervisionSessionOpenedPayload;
+    unaccounted_print: UnaccountedPrintPayload;
 }
 /** Every kind the server declares a payload type for, in name order. */
-export declare const EVENT_KINDS: readonly ["action_executed", "action_rejected", "action_requested", "agent_assessment", "intervention_expired", "malformed_external_event", "obico_failure_alert", "obico_printer_notification", "operator_acknowledgement", "port_failure", "startup_reconciliation", "supervision_session_closed", "supervision_session_opened"];
+export declare const EVENT_KINDS: readonly ["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"];
 /**
  * The payload of one event as the type its kind declares, or `undefined` for
  * an event of any other kind — one this client knows or one it does not. No
@@ -883,6 +1586,14 @@ export declare class GeneratedClient extends GeneratedSurface {
      * said no.
      */
     manifestGet(printId: string): Promise<ManifestAnswer>;
+    /**
+     * Call `look` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    look(printId: string, waitS?: number): Promise<Look>;
     /**
      * Call `manifest_set` on the configured supervisor.
      *
@@ -893,6 +1604,38 @@ export declare class GeneratedClient extends GeneratedSurface {
      * the reason, the value asked for and the range allowed.
      */
     manifestSet(printId: string, reason: string, manifest: JobManifest): Promise<ManifestAnswer>;
+    /**
+     * Call `spools` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    spools(includeRetired?: boolean): Promise<SpoolsAnswer>;
+    /**
+     * Call `spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    spool(spoolId: string): Promise<SpoolAnswer>;
+    /**
+     * Call `printer_history` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    printerHistory(kinds?: Array<string>, since?: string, until?: string, spoolId?: string, before?: string, limit?: number): Promise<TimelineAnswer>;
+    /**
+     * Call `preflight` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    preflight(fileName: string): Promise<PreflightAnswer>;
     /**
      * Call `pause` on the configured supervisor.
      *
@@ -932,7 +1675,7 @@ export declare class GeneratedClient extends GeneratedSurface {
      * is made, and the policy's own refusal arrives as `Rejected`, carrying
      * the reason, the value asked for and the range allowed.
      */
-    startPrint(printId: string, fileName: FileName, manifest: JobManifest, reason: string): Promise<ActionAnswer>;
+    startPrint(printId: string, fileName: FileName, manifest: JobManifest, reason: string, overrideFilamentCheck?: boolean): Promise<ActionAnswer>;
     /**
      * Call `set_feedrate_factor` on the configured supervisor.
      *
@@ -993,4 +1736,54 @@ export declare class GeneratedClient extends GeneratedSurface {
      * the reason, the value asked for and the range allowed.
      */
     acknowledgeFailure(printId: string, disposition: AcknowledgementDisposition, eventId: EventId, reason: string): Promise<ActionAnswer>;
+    /**
+     * Call `register_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    registerSpool(initialG: number, material: string, name: string, reason: string, color?: string, densityGCm3?: number, diameterMm?: number, remainingG?: number, tareG?: number): Promise<SpoolCommandAnswer>;
+    /**
+     * Call `load_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    loadSpool(spoolId: string, reason: string, tool: number): Promise<SpoolCommandAnswer>;
+    /**
+     * Call `unload_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    unloadSpool(spoolId: string, reason: string): Promise<SpoolCommandAnswer>;
+    /**
+     * Call `adjust_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    adjustSpool(spoolId: string, reason: string, grossG?: number, remainingG?: number): Promise<SpoolCommandAnswer>;
+    /**
+     * Call `retire_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    retireSpool(spoolId: string, reason: string): Promise<SpoolCommandAnswer>;
 }

package/dist/contract.js

@@ -7,7 +7,7 @@
  *  generate-clients`, and commit what that writes.
  */
 import { GeneratedSurface, reasonGiven } from "./surface.js";
-export const CONTRACT_VERSION = "0.3.0";
+export const CONTRACT_VERSION = "0.4.0";
 /**
  * Every operation this client exposes a method for, which is every operation
  * the server declares and no other.
@@ -19,7 +19,12 @@ export const OPERATION_NAMES = [
     "image",
     "history",
     "manifest_get",
+    "look",
     "manifest_set",
+    "spools",
+    "spool",
+    "printer_history",
+    "preflight",
     "pause",
     "resume",
     "cancel",
@@ -30,6 +35,11 @@ export const OPERATION_NAMES = [
     "set_bed_target_c",
     "set_fan_percent",
     "acknowledge_failure",
+    "register_spool",
+    "load_spool",
+    "unload_spool",
+    "adjust_spool",
+    "retire_spool",
 ];
 /** Every kind the server declares a payload type for, in name order. */
 export const EVENT_KINDS = [
@@ -37,15 +47,33 @@ export const EVENT_KINDS = [
     "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",
 ];
 /**
  * The payload of one event as the type its kind declares, or `undefined` for
@@ -155,6 +183,23 @@ export class GeneratedClient extends GeneratedSurface {
         // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
+    /**
+     * Call `look` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    async look(printId, waitS) {
+        const target = `/v1/prints/${printId}/look`;
+        const asked = [];
+        if (waitS !== undefined) {
+            asked.push(["wait_s", String(waitS)]);
+        }
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
     /**
      * Call `manifest_set` on the configured supervisor.
      *
@@ -174,6 +219,88 @@ export class GeneratedClient extends GeneratedSurface {
         // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("PUT", target, asked, sending);
     }
+    /**
+     * Call `spools` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    async spools(includeRetired) {
+        const target = `/v1/spools`;
+        const asked = [];
+        if (includeRetired !== undefined) {
+            asked.push(["include_retired", String(includeRetired)]);
+        }
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
+    /**
+     * Call `spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    async spool(spoolId) {
+        const target = `/v1/spools/${spoolId}`;
+        const asked = [];
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
+    /**
+     * Call `printer_history` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    async printerHistory(kinds, since, until, spoolId, before, limit) {
+        const target = `/v1/history`;
+        const asked = [];
+        if (kinds !== undefined) {
+            for (const value of kinds) {
+                asked.push(["kinds", String(value)]);
+            }
+        }
+        if (since !== undefined) {
+            asked.push(["since", String(since)]);
+        }
+        if (until !== undefined) {
+            asked.push(["until", String(until)]);
+        }
+        if (spoolId !== undefined) {
+            asked.push(["spool_id", String(spoolId)]);
+        }
+        if (before !== undefined) {
+            asked.push(["before", String(before)]);
+        }
+        if (limit !== undefined) {
+            asked.push(["limit", String(limit)]);
+        }
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
+    /**
+     * Call `preflight` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    async preflight(fileName) {
+        const target = `/v1/preflight`;
+        const asked = [];
+        if (fileName !== undefined) {
+            asked.push(["file_name", String(fileName)]);
+        }
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
     /**
      * Call `pause` on the configured supervisor.
      *
@@ -240,7 +367,7 @@ export class GeneratedClient extends GeneratedSurface {
      * is made, and the policy's own refusal arrives as `Rejected`, carrying
      * the reason, the value asked for and the range allowed.
      */
-    async startPrint(printId, fileName, manifest, reason) {
+    async startPrint(printId, fileName, manifest, reason, overrideFilamentCheck) {
         reasonGiven(reason);
         const target = `/v1/prints/${printId}/actions/start_print`;
         const asked = [];
@@ -248,6 +375,9 @@ export class GeneratedClient extends GeneratedSurface {
         sending.actor = this.actor;
         sending.file_name = fileName;
         sending.manifest = manifest;
+        if (overrideFilamentCheck !== undefined) {
+            sending.override_filament_check = overrideFilamentCheck;
+        }
         sending.reason = reason;
         // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
@@ -389,4 +519,124 @@ export class GeneratedClient extends GeneratedSurface {
         // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
+    /**
+     * Call `register_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    async registerSpool(initialG, material, name, reason, color, densityGCm3, diameterMm, remainingG, tareG) {
+        reasonGiven(reason);
+        const target = `/v1/spools/actions/register_spool`;
+        const asked = [];
+        const sending = {};
+        sending.actor = this.actor;
+        if (color !== undefined) {
+            sending.color = color;
+        }
+        if (densityGCm3 !== undefined) {
+            sending.density_g_cm3 = densityGCm3;
+        }
+        if (diameterMm !== undefined) {
+            sending.diameter_mm = diameterMm;
+        }
+        sending.initial_g = initialG;
+        sending.material = material;
+        sending.name = name;
+        sending.reason = reason;
+        if (remainingG !== undefined) {
+            sending.remaining_g = remainingG;
+        }
+        if (tareG !== undefined) {
+            sending.tare_g = tareG;
+        }
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("POST", target, asked, sending);
+    }
+    /**
+     * Call `load_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    async loadSpool(spoolId, reason, tool) {
+        reasonGiven(reason);
+        const target = `/v1/spools/${spoolId}/actions/load_spool`;
+        const asked = [];
+        const sending = {};
+        sending.actor = this.actor;
+        sending.reason = reason;
+        sending.tool = tool;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("POST", target, asked, sending);
+    }
+    /**
+     * Call `unload_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    async unloadSpool(spoolId, reason) {
+        reasonGiven(reason);
+        const target = `/v1/spools/${spoolId}/actions/unload_spool`;
+        const asked = [];
+        const sending = {};
+        sending.actor = this.actor;
+        sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("POST", target, asked, sending);
+    }
+    /**
+     * Call `adjust_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    async adjustSpool(spoolId, reason, grossG, remainingG) {
+        reasonGiven(reason);
+        const target = `/v1/spools/${spoolId}/actions/adjust_spool`;
+        const asked = [];
+        const sending = {};
+        sending.actor = this.actor;
+        if (grossG !== undefined) {
+            sending.gross_g = grossG;
+        }
+        sending.reason = reason;
+        if (remainingG !== undefined) {
+            sending.remaining_g = remainingG;
+        }
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("POST", target, asked, sending);
+    }
+    /**
+     * Call `retire_spool` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no. A call whose reason is empty is refused here, before a request
+     * is made, and the policy's own refusal arrives as `Rejected`, carrying
+     * the reason, the value asked for and the range allowed.
+     */
+    async retireSpool(spoolId, reason) {
+        reasonGiven(reason);
+        const target = `/v1/spools/${spoolId}/actions/retire_spool`;
+        const asked = [];
+        const sending = {};
+        sending.actor = this.actor;
+        sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("POST", target, asked, sending);
+    }
 }

package/dist/surface.d.ts

@@ -10,7 +10,7 @@
  * are that module's, imported as types alone, so that the two files can name
  * each other's shapes without either being unloadable.
  */
-import type { ActionAnswer, Actor, Range, RejectionReason } from "./contract.ts";
+import type { ActionAnswer, Actor, Range, RejectionReason, SpoolCommandAnswer } from "./contract.ts";
 /** Why a call did not answer what it asked for. */
 export declare class ClientError extends Error {
     constructor(said: string);
@@ -72,9 +72,13 @@ export declare class Rejected extends ClientError {
     readonly requested: number | undefined;
     /** The range that is allowed, where the policy ruled on a value. */
     readonly allowed: Range | undefined;
-    /** The whole answer, whose record carries the request and the decision. */
-    readonly answer: ActionAnswer;
-    constructor(reason: RejectionReason, requested: number | undefined, allowed: Range | undefined, answer: ActionAnswer);
+    /**
+     * The whole answer: an action's, whose record carries the request and the
+     * decision, or a spool command's, carrying the decision and the events its
+     * refusal wrote.
+     */
+    readonly answer: ActionAnswer | SpoolCommandAnswer;
+    constructor(reason: RejectionReason, requested: number | undefined, allowed: Range | undefined, answer: ActionAnswer | SpoolCommandAnswer);
 }
 /**
  * Refuse a mutating call that carries no reason, before it is made.

package/dist/surface.js

@@ -99,7 +99,11 @@ export class Rejected extends ClientError {
     requested;
     /** The range that is allowed, where the policy ruled on a value. */
     allowed;
-    /** The whole answer, whose record carries the request and the decision. */
+    /**
+     * The whole answer: an action's, whose record carries the request and the
+     * decision, or a spool command's, carrying the decision and the events its
+     * refusal wrote.
+     */
     answer;
     constructor(reason, requested, allowed, answer) {
         super(`the supervisor's policy refused this action: ${JSON.stringify(reason)}` +

package/package.json

@@ -12,12 +12,12 @@
   "license": "MIT",
   "main": "dist/index.js",
   "name": "@printobserver/sdk",
-  "printobserverContractVersion": "0.3.0",
+  "printobserverContractVersion": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/nickderobertis/printobserver"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.3.0"
+  "version": "0.4.0"
 }