@spec accept_suggestion(binary(), binary() | nil) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}

Accepts a pending suggestion and creates an immutable prompt version.

Pass prompt_id to scope the transition when accepting from a prompt-specific interface. Concurrent and repeated transitions return an error.

@spec analyze([map()]) :: %{candidates: [map()], frontier: [map()]}

Classifies prompt-version metrics by multi-objective Pareto status.

Candidates missing pass rate, cost per passed test, or latency per passed test are marked :insufficient. Eligible candidates are marked :frontier unless another candidate is no worse on every objective and better on at least one.

@spec create_suggestion(map()) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, Ecto.Changeset.t()}

Persists a prompt suggestion from validated attributes.

Most callers should use generate_suggestion/3, which constructs a suggestion from bounded evaluation evidence.

@spec dismiss_suggestion(binary(), binary() | nil) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}

Dismisses a pending suggestion without creating a prompt version.

Pass prompt_id to scope the transition when dismissing from a prompt-specific interface. Concurrent and repeated transitions return an error.

@spec generate_suggestion(binary(), binary(), binary()) ::
  {:ok, Aludel.Prompts.PromptSuggestion.t()} | {:error, term()}

Generates a prompt revision from recent failed suite results.

The source version and suite must belong to the same prompt. Only one pending suggestion is allowed for a source-version, suite, and provider combination. No suggestion is persisted when evidence is unavailable or the generated template fails validation.

@spec list_suggestions(binary()) :: [Aludel.Prompts.PromptSuggestion.t()]

Lists prompt suggestions newest first with their related records preloaded.