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.analyze_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 — e.g. ``"spaghetti"``, ``"layer_shift"``, ``"warping"``.
    settings: Optional dict of print settings used (temp_tool, temp_bed, speed, etc.).
    environment: Optional dict of environment conditions (ambient_temp, humidity).
    notes: Optional free-text notes about the print.
    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 and
        store its best-guess mode if confidence >= 0.75.  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), or
        ``"user_reported"`` (the human said so).  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.