@printobserver/sdk 0.2.0 → 0.4.0

package/dist/contract.d.ts

@@ -8,15 +8,17 @@
  */
 import { GeneratedSurface } from "./surface.ts";
 /**
- * The version of the server contract these types were generated from, which
- * is the version the type crate declares in the tree they came from.
+ * The version of the server contract these types were generated from. A
+ * published package reports the release version it was built at; used from a
+ * checkout, this module reports that checkout's workspace version, and
+ * refuses to import when it cannot read one.
  */
-export declare const CONTRACT_VERSION = "0.2.0";
+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 ["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. */
@@ -48,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.
  *
@@ -132,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.
  *
@@ -175,9 +227,12 @@ export interface ErrorAnswer {
 /** A lowercase hyphenated version 7 UUID identifying one event. */
 export type EventId = string;
 /**
- * What every arm of `EventRecord` carries beside its own payload.
- *
- * One event, as the store holds it.
+ * The name one kind of event is written down under: lowercase `snake_case`,
+ * declared by the domain that owns the event.
+ */
+export 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
@@ -186,11 +241,15 @@ export type EventId = string;
  * system
  * knows.
  */
-export interface EventRecordCommon {
+export interface EventRecord {
     /** This event's identifier, minted by the store. */
     id: EventId;
     /** The image it arrived with, when it arrived with one. */
     image?: ImageRef | null;
+    /** Which event this is. */
+    kind: EventKind;
+    /** What it carries, in the form its kind declares. */
+    payload: unknown;
     /** The print it belongs to, when it belongs to one. */
     print_id?: PrintId | null;
     /** The bytes exactly as received, for an externally sourced event. */
@@ -201,68 +260,116 @@ export interface EventRecordCommon {
     source: EventSource;
 }
 /**
- * One event, as the store holds 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.
+ * Where an event came from, as the bare string the domain that raised it
+ * declares for itself.
  */
-export type EventRecord = (EventRecordCommon & {
-    kind: "obico_failure_alert";
-    payload: ObicoFailureAlertPayload;
-}) | (EventRecordCommon & {
-    kind: "obico_printer_notification";
-    payload: ObicoPrinterNotificationPayload;
-}) | (EventRecordCommon & {
-    kind: "malformed_external_event";
-    payload: MalformedExternalEventPayload;
-}) | (EventRecordCommon & {
-    kind: "action_requested";
-    payload: ActionRequestedPayload;
-}) | (EventRecordCommon & {
-    kind: "action_executed";
-    payload: ActionExecutedPayload;
-}) | (EventRecordCommon & {
-    kind: "action_rejected";
-    payload: ActionRejectedPayload;
-}) | (EventRecordCommon & {
-    kind: "intervention_expired";
-    payload: InterventionExpiredPayload;
-}) | (EventRecordCommon & {
-    kind: "supervision_session_opened";
-    payload: SupervisionSessionOpenedPayload;
-}) | (EventRecordCommon & {
-    kind: "supervision_session_closed";
-    payload: SupervisionSessionClosedPayload;
-}) | (EventRecordCommon & {
-    kind: "agent_assessment";
-    payload: AgentAssessmentPayload;
-}) | (EventRecordCommon & {
-    kind: "operator_acknowledgement";
-    payload: OperatorAcknowledgementPayload;
-}) | (EventRecordCommon & {
-    kind: "port_failure";
-    payload: PortFailurePayload;
-}) | (EventRecordCommon & {
-    kind: "startup_reconciliation";
-    payload: StartupReconciliationPayload;
-});
-/** Where an event came from. */
-export type EventSource = "obico" | "operator" | "agent" | "system";
+export type EventSource = string;
 /** What happened when an accepted action reached the printer. */
 export type ExecutionOutcome = "succeeded" | {
     failed: {
         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.
  *
@@ -426,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. */
@@ -439,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.
  *
@@ -523,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;
@@ -558,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";
@@ -577,6 +855,7 @@ export type PrintAction = {
     actor: Actor;
     file_name: FileName;
     manifest: JobManifest;
+    override_filament_check?: boolean;
     reason: string;
 } | {
     action: "set_feedrate_factor";
@@ -635,14 +914,27 @@ 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.
  *
- * Obico's own print id is carried beside this record's identifier rather
- * than
- * as it, because a print may be observed before Obico has one.
+ * 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.
  */
 export interface PrintRecord {
     /** Why it ended, if it has. */
@@ -653,15 +945,65 @@ 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>;
-    /** Obico's own identifier for the print, when Obico has one. */
-    obico_print_id?: number | null;
     /** When the print was opened. */
     opened_at: Timestamp;
+    /**
+     * The provider's own identifier for the print, whichever provider
+     * reported it, when one has.
+     */
+    provider_print_id?: number | null;
     /** 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. */
@@ -690,6 +1032,24 @@ export interface PrinterSnapshot {
 export type PrinterState = "operational" | "paused" | "printing" | "cancelling" | "error" | "offline" | {
     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.
+ */
+export interface 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.
+     */
+    active?: PrintId | null;
+    /** Every print this server holds, ended or not, most recently opened first. */
+    prints: Array<PrintRecord>;
+}
 /** An inclusive pair of 64-bit floats. */
 export interface Range {
     /** The highest value the range admits, inclusive. */
@@ -699,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.
  *
@@ -729,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
@@ -740,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.
  *
@@ -813,8 +1422,114 @@ 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
+ * flows through `EventRecord` untouched, and is in no table.
+ */
+export interface EventPayloads {
+    action_executed: ActionExecutedPayload;
+    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", "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
+ * validation beyond the kind's name: the payload is the document the server
+ * sent, handed on as the type the table says it is.
+ */
+export declare function payloadOf<K extends keyof EventPayloads>(event: EventRecord, kind: K): EventPayloads[K] | undefined;
 /**
  * One method per operation the server declares.
  *
@@ -823,6 +1538,14 @@ export type Timestamp = string;
  * vocabulary are hand-written, and this class is written against them.
  */
 export declare class GeneratedClient extends GeneratedSurface {
+    /**
+     * Call `prints` 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.
+     */
+    prints(): Promise<PrintsAnswer>;
     /**
      * Call `status` on the configured supervisor.
      *
@@ -863,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.
      *
@@ -873,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.
      *
@@ -912,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.
      *
@@ -973,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>;
 }