LemonCore.RunOutcome (lemon_core v0.1.0)

View Source

Outcome labels for finalized runs.

Provides heuristics for inferring :success | :partial | :failure | :aborted | :unknown from a run summary, plus support for explicit overrides.

Outcome semantics

OutcomeMeaning
:successRun completed with ok: true and a non-empty answer.
:partialRun completed with ok: true but produced no substantive answer (e.g. tool-only run).
:failureRun completed with ok: false for a non-abort reason.
:abortedRun was cancelled by the user or watchdog.
:unknownOutcome cannot be determined from available data.

Heuristics

infer/1 checks the summary in order:

  1. Explicit :outcome field on the summary (operator/explicit override).
  2. completed.ok boolean with answer content → :success or :partial.
  3. completed.ok == false with error text → :aborted or :failure.
  4. Top-level :ok fallback for summaries without a :completed sub-map.
  5. Default: :unknown.

Explicit overrides

The caller may embed an explicit :outcome field in the summary map to bypass heuristics entirely. This is the primary escape hatch for engines or external integrations that know the true outcome.

summary = %{..., outcome: :aborted}
RunOutcome.infer(summary)  # => :aborted

Summary

Types

t()

Functions

cast(outcome)

Cast a raw value (atom or string) to an outcome atom.

infer(summary)

Infer the run outcome from a finalized run summary map.

valid?(outcome)

Returns true if outcome is a valid outcome atom.

valid_outcomes()

Returns the list of valid outcome atoms.

Types

t()

@type t() :: :success | :partial | :failure | :aborted | :unknown

Functions

cast(outcome)

@spec cast(term()) :: {:ok, t()} | :error

Cast a raw value (atom or string) to an outcome atom.

Returns {:ok, outcome} if valid, :error otherwise.

infer(summary)

@spec infer(map()) :: t()

Infer the run outcome from a finalized run summary map.

Checks for an explicit :outcome override first, then applies heuristics based on the completed.ok boolean and answer/error content.

Safe against malformed or partial summaries — always returns a valid outcome.

valid?(outcome)

@spec valid?(atom()) :: boolean()

Returns true if outcome is a valid outcome atom.

valid_outcomes()

@spec valid_outcomes() :: [t()]

Returns the list of valid outcome atoms.