record_print_outcome

The learning database helps agents make better decisions about which
printer to use for a given job and material.  Outcomes are agent-curated
quality data — separate from the auto-populated print history.

**Safety**: Settings are validated against hard safety limits.  Outcomes
with temperatures exceeding safe maximums are rejected to prevent
poisoning the learning database with dangerous data.

**Decoration feedback**: When ``decoration_slug`` is provided, the
corresponding decoration's proven-settings counter is auto-updated
(``success_count`` or ``failure_count``) so the library's tracked
reliability reflects real field outcomes without manual curation.

**Auto-classification** (opt-in): When ``auto_classify=True`` and the
outcome is ``"failed"`` with no explicit ``failure_mode``, the failure
classifier runs (:func:`kiln.failure_recovery.classify_failure`) and
its result is mapped into the canonical DB vocabulary.  The
classification is always echoed back in the ``auto_classification``
key of the response; it is only STORED as ``failure_mode`` when the
classifier's confidence meets or exceeds
``_AUTO_CLASSIFY_MIN_CONFIDENCE`` (0.75).  Lower-confidence guesses
are surfaced to the caller without poisoning the learning database.

Args:
    job_id: The job ID from the print queue.
    outcome: One of ``"success"``, ``"failed"``, ``"partial"``, or
        ``"cancelled"``.
    quality_grade: Optional — ``"excellent"``, ``"good"``, ``"acceptable"``, ``"poor"``.
    failure_mode: Optional — one of ``spaghetti``, ``layer_shift``,
        ``warping``, ``adhesion``, ``stringing``, ``under_extrusion``,
        ``over_extrusion``, ``clog``, ``thermal_runaway``, ``power_loss``,
        ``filament_runout``, ``mechanical``, ``other``.
    settings: Optional dict of print settings used (temp_tool, temp_bed, speed, etc.).
    environment: Optional dict of environment conditions (ambient_temp, humidity).
    notes: Optional — a note on how the print came out, in the words
        of whoever wrote it ("the back-left corner lifted at layer
        40").  Up to 2000 characters; kept with the print on this
        computer and, for a print of a kept design, on the person's
        Kiln account, where the version history shows it with who said
        it.  A person's note is never overwritten
        by an agent's; an agent's is replaced by a later agent's only
        when the ending is at least as surely known.
    note_by: Who wrote ``notes``: ``"person"`` (their own words, which
        you relay as written) or ``"agent"`` (what you saw, as the one
        that watched the print).  When omitted: ``"person"`` for an
        ending the person reported, ``"agent"`` for one you observed
        or saw; a hook's auto-recorded string carries no label.
    clear_note: Delete the note on this print, when the person asks.
        Send the print's ``job_id`` and the ``outcome`` it is recorded
        with (the call is refused if that is not its ending, so the
        wrong print is never changed); nothing else is recorded and the
        ending stays as it was.  The delete reaches the person's Kiln
        account too.
    printer_name: Printer used.  Auto-resolved from job if omitted.
    file_name: File printed.  Auto-resolved from job if omitted.
    file_hash: Optional hash of the file for cross-printer comparison.
    material_type: Material used (e.g. ``"PLA"``, ``"PETG"``).  Omit and
        Kiln backfills it from what the job declared (print history, then
        the queue job) or — for an outcome watched live — from the
        filament the printer currently holds.  Stays unset when no honest
        source knows it; per-material learning skips unset rows rather
        than learning from a guess.
    decoration_slug: Optional decoration slug that was applied to this
        print.  When set, the matching decoration's success/failure
        counters are auto-updated.
    decoration_settings: Optional dict of decoration settings used
        (``depth_mm``, ``mode``, ``image_style``).  Falls back to the
        decoration's current defaults when omitted.
    auto_classify: When True and this outcome is a failure with no
        explicit ``failure_mode``, run the failure classifier; a
        confident guess is stored as ``failure_mode``, a weak one is
        only echoed back in ``auto_classification``.  Default False —
        callers opt in.
    auto_recorded: When True, tags the outcome as auto-fired by
        the terminal-state hook (see
        :mod:`kiln.auto_record_hook`).  Agents can later refine
        the outcome by calling record_print_outcome again with the
        same ``job_id`` — the most recent call wins at the
        ``proven_settings`` level.  Default False.
    determined_by: Who settled this outcome — ``"observed"`` (a
        live process watched the print end), ``"inferred"``
        (reconstructed from printer state after the fact), ``"seen"``
        (a camera frame judged at the ending), or
        ``"user_reported"`` (the human said so).  A weaker source
        never contradicts a decided row.  Defaults to
        ``"observed"`` for auto-recorded outcomes and
        ``"user_reported"`` otherwise — a manual record normally
        relays what the user reported about the part in hand.
        Recording an outcome for a print that started while Kiln
        wasn't watching RESOLVES its pending row in place rather
        than duplicating it.
    print_error: Optional raw firmware error code the print tripped
        (Bambu HMS, e.g. ``50348044``).  Stored as EVIDENCE and kept
        deliberately separate from ``failure_mode``, which is a
        VERDICT: a print the user CANCELLED carries whatever code the
        abort tripped and no failure_mode at all, because a deliberate
        stop is not a machine failure but the firmware's complaint
        still happened and is worth keeping.  A single machine cannot
        characterise a fault from codes like these — what predicts one
        sticking is a question for many printers — so the code is
        captured now against the day there are enough of them to ask.
        ``0`` and unset both store NULL; a backend with no such code
        simply omits it.
    version_id: Optional — the design version that was printed.  A
        print started from a kept design already carries it (the
        start stamps it); pass it here when recording a print Kiln
        did not start, so the ending lands on that version's history.
        Never overwrites a version the start recorded.
    design_id: Optional — the design the version belongs to.
    branch_id: Optional — the branch the version sits on.