Feature 18: Cook From What I Have and Quick Dinners (#155)

Co-authored-by: orchestrator-agent <20+orchestrator-agent@code.cubecraftcreations.com>

internal/ideas/ideas.go

@@ -0,0 +1,662 @@
+// Package ideas finds dinner ideas for Cook from what I have and Quick
+// dinners: from a list of ingredients on hand, ideas_from_ingredients
+// proposes dinners, and for a kind of Quick dinner, quick_ideas does; each
+// is grounded with the recipe grounding pipeline (dropping those no recipe
+// grounds, and Quick dinners whose grounded recipe is not of the kind), and
+// the ideas kept are reported as a job's result, which fills as each idea
+// grounds. A job that keeps no idea, or fails, shows no idea: nothing is
+// made up instead (D-017). Ideas are not stored as dinners: the household
+// acts on one later.
+package ideas
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"slices"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Job kinds.
+const (
+	// KindFromIngredients is the job that finds ideas from ingredients.
+	KindFromIngredients = "ideas_from_ingredients"
+	// KindQuick is the job that finds a page of Quick dinner ideas.
+	KindQuick = "quick_ideas"
+)
+
+// ContextBudget is the character budget of the household context
+// quick_ideas is given (see harness.BuildContext).
+const ContextBudget = 16000
+
+// QuickMinutes is the most minutes from prep to table of a Quick dinner
+// not cooked in a crock pot.
+const QuickMinutes = 30
+
+// Job stages, as the job's result reports them.
+const (
+	StageSuggesting = "suggesting"
+	StageGrounding  = "grounding"
+	StageDone       = "done"
+)
+
+// Reasons the job failed, stored as its failure code. Any other failure,
+// such as the database's, is the runner's internal_error.
+const (
+	// ReasonAIFailed: ideas_from_ingredients or quick_ideas, or
+	// normalize_recipe while grounding, failed; no idea is made up instead
+	// (D-017).
+	ReasonAIFailed = "ai_failed"
+	// ReasonSearchNotConfigured: recipe search is not set up.
+	ReasonSearchNotConfigured = "search_not_configured"
+	// ReasonSearchFailed: the search provider failed.
+	ReasonSearchFailed = "search_failed"
+	// ReasonNoIdeasFound: every idea was dropped, by the skill's rules,
+	// because no recipe grounds it, or because its grounded recipe is not
+	// a Quick dinner (a Quick only request) or not of the kind asked for (a
+	// Quick dinners request).
+	ReasonNoIdeasFound = "no_ideas_found"
+)
+
+// Reasons are every failure reason of both jobs.
+var Reasons = []string{ReasonAIFailed, ReasonSearchNotConfigured, ReasonSearchFailed, ReasonNoIdeasFound}
+
+// InvalidError is a request the household must correct, such as an empty
+// ingredient list or an unknown kind of Quick dinner.
+type InvalidError struct {
+	Message string
+}
+
+func (e *InvalidError) Error() string { return e.Message }
+
+// Generator runs ideas_from_ingredients on in; scope is
+// skills.IdeasScope(in). In production it is skills.IdeasFromIngredients
+// with the household's harness.Config.
+type Generator func(ctx context.Context, scope string, in skills.IdeasRequest) (skills.Ideas, error)
+
+// QuickGenerator runs quick_ideas on in; scope is skills.QuickIdeasScope(in).
+// In production it is skills.QuickIdeas with the household's
+// harness.Config.
+type QuickGenerator func(ctx context.Context, scope string, in skills.QuickIdeasRequest) (skills.QuickIdeaList, error)
+
+// Service starts and runs idea jobs.
+type Service struct {
+	st       *store.Store
+	grounder *recipes.Grounder
+	runner   *jobs.Runner
+	generate Generator
+	quick    QuickGenerator
+	logger   *slog.Logger
+	job      *jobs.Kind[FromIngredientsJob]
+	quickJob *jobs.Kind[QuickJob]
+}
+
+// NewService returns a service that reads the household context from st,
+// finds ideas with generate and Quick dinner ideas with quick, grounds
+// them with grounder and registers the KindFromIngredients and KindQuick
+// jobs on runner, which must not have started yet. The jobs are started
+// only by StartFromIngredients and StartQuick, which check the request
+// first.
+func NewService(st *store.Store, grounder *recipes.Grounder, generate Generator, quick QuickGenerator, runner *jobs.Runner, logger *slog.Logger) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("ideas: nil store")
+	case grounder == nil:
+		return nil, errors.New("ideas: nil grounder")
+	case generate == nil:
+		return nil, errors.New("ideas: nil generator")
+	case quick == nil:
+		return nil, errors.New("ideas: nil quick generator")
+	case runner == nil:
+		return nil, errors.New("ideas: nil job runner")
+	case logger == nil:
+		return nil, errors.New("ideas: nil logger")
+	}
+	s := &Service{st: st, grounder: grounder, runner: runner, generate: generate, quick: quick, logger: logger}
+	var err error
+	if s.job, err = register(runner, KindFromIngredients, s.run, withoutIdeas[Result]); err != nil {
+		return nil, err
+	}
+	if s.quickJob, err = register(runner, KindQuick, s.runQuick, withoutIdeas[QuickResult]); err != nil {
+		return nil, err
+	}
+	return s, nil
+}
+
+// register registers the service-only job name, run by run, whose failed
+// jobs show their result through failed.
+func register[P any, R jobs.Public](runner *jobs.Runner, name string, run jobs.Handler[P, R], failed func(json.RawMessage) (json.RawMessage, error)) (*jobs.Kind[P], error) {
+	kind, err := jobs.Register(runner, name, run, Reasons...)
+	if err != nil {
+		return nil, err
+	}
+	if err := kind.ServiceOnly(); err != nil {
+		return nil, err
+	}
+	if err := kind.FailedResult(failed); err != nil {
+		return nil, err
+	}
+	return kind, nil
+}
+
+// FromIngredientsJob is the KindFromIngredients payload: the ingredients
+// on hand, as skills.CleanIngredients returns them, and whether only
+// Quick dinners are wanted.
+type FromIngredientsJob struct {
+	Ingredients []string `json:"ingredients"`
+	QuickOnly   bool     `json:"quick_only"`
+}
+
+// Started is the job a request started.
+type Started struct {
+	JobID string `json:"jobId"`
+}
+
+// StartFromIngredients enqueues a KindFromIngredients job for ingredients
+// and returns its id. An ingredient list skills.CleanIngredients refuses
+// is an *InvalidError, and starts nothing.
+func (s *Service) StartFromIngredients(ctx context.Context, ingredients []string, quickOnly bool) (Started, error) {
+	ings, err := skills.CleanIngredients(ingredients)
+	if err != nil {
+		return Started{}, &InvalidError{Message: "ingredients: " + err.Error()}
+	}
+	id, err := s.job.Enqueue(ctx, FromIngredientsJob{Ingredients: ings, QuickOnly: quickOnly})
+	if err != nil {
+		return Started{}, fmt.Errorf("ideas: enqueue: %w", err)
+	}
+	return Started{JobID: id}, nil
+}
+
+// Idea is a grounded idea as the job's result shows it. Method,
+// MinutesTotal and Difficulty are the grounded recipe's, never the
+// model's estimates.
+type Idea struct {
+	Name string `json:"name"`
+	// Uses are the household's ingredients the idea uses, as the household
+	// wrote them and in its order.
+	Uses []string `json:"uses"`
+	// Missing are the ingredients the idea needs that the household does
+	// not have.
+	Missing []string `json:"missing"`
+	// Summary is the line shown under the idea, e.g. "Uses 3 of 5 ·
+	// missing: 1 lime" (see skills.IdeaSummary).
+	Summary string `json:"summary"`
+	// Method is stovetop, oven, crockpot, grill or other.
+	Method string `json:"method"`
+	// MinutesTotal is prep to table, null when the recipe does not say.
+	MinutesTotal *int `json:"minutes_total"`
+	// Difficulty is easy, medium or hard.
+	Difficulty string `json:"difficulty"`
+	// Quick says whether the idea is a Quick dinner (see IsQuick).
+	Quick     bool   `json:"quick"`
+	RecipeID  string `json:"recipe_id"`
+	PhotoURL  string `json:"photo_url"`
+	SourceURL string `json:"source_url"`
+	SiteName  string `json:"site_name"`
+}
+
+// Result is the KindFromIngredients result, published as the job goes:
+// its stage, the request, the ideas grounded so far in the model's order
+// (an idea that grounds sooner than one before it is shown first, and the
+// earlier one is put back in its place when it grounds),
+// and how many ideas were dropped, by ideas_from_ingredients' rules,
+// because no recipe grounds them, or, for a Quick only request, because
+// the grounded recipe is not a Quick dinner.
+type Result struct {
+	Stage       string   `json:"stage"`
+	Ingredients []string `json:"ingredients"`
+	QuickOnly   bool     `json:"quick_only"`
+	Ideas       []Idea   `json:"ideas"`
+	Dropped     int      `json:"dropped"`
+}
+
+func (r Result) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// IsQuick reports whether a recipe cooked by method in minutes (nil when
+// unknown) is a Quick dinner: cooked in a crock pot, or 30 minutes or less
+// from prep to table.
+func IsQuick(method string, minutes *int) bool {
+	return method == "crockpot" || (minutes != nil && *minutes <= QuickMinutes)
+}
+
+// run runs a KindFromIngredients job: it asks ideas_from_ingredients for
+// skills.IdeasRequested ideas, then grounds them in the model's order, at
+// most the number still wanted at a time, until skills.IdeasKept are kept
+// or none are left. An idea no recipe grounds is dropped, and so, for a
+// Quick only request, is one whose grounded recipe is not a Quick dinner;
+// when every idea is dropped the job fails with ReasonNoIdeasFound. Any
+// other grounding failure fails the job, as does ideas_from_ingredients
+// failing, with no idea made up instead. The result is published at each
+// stage and again as each idea is kept, so it fills as the ideas ground.
+// Before the job fails, its result is published again with no ideas (see
+// finish).
+func (s *Service) run(ctx context.Context, p FromIngredientsJob, publish func(Result) error) (Result, error) {
+	res, err := s.fill(ctx, p, publish)
+	return finish(ctx, s.logger, "ideas from ingredients", res, err, publish)
+}
+
+// shownResult is a job result that shows ideas.
+type shownResult[R any] interface {
+	jobs.Public
+	// shown is how many ideas the result shows.
+	shown() int
+	// cleared is the result showing no ideas.
+	cleared() R
+}
+
+func (r Result) shown() int { return len(r.Ideas) }
+
+func (r Result) cleared() Result {
+	r.Ideas = []Idea{}
+	return r
+}
+
+// finish ends a job whose work returned res and err. A job that failed
+// has its result published again with no ideas, to tidy the stored
+// result. That write is not what keeps a failed job from showing ideas,
+// since it may fail and a job interrupted by restart never makes it:
+// withoutIdeas, applied whenever a failed job is read, is.
+func finish[R shownResult[R]](ctx context.Context, logger *slog.Logger, what string, res R, err error, publish func(R) error) (R, error) {
+	var zero R
+	if err == nil {
+		return res, nil
+	}
+	if ctx.Err() != nil {
+		return zero, err
+	}
+	var failure *jobs.Failure
+	if errors.As(err, &failure) {
+		// Only the code is logged: the error may quote a model's or
+		// search provider's response.
+		logger.InfoContext(ctx, what+" failed", "reason", failure.Code)
+	}
+	if res.shown() > 0 {
+		if perr := publish(res.cleared()); perr != nil {
+			return zero, fmt.Errorf("ideas: clear failed job's ideas: %w", perr)
+		}
+	}
+	return zero, err
+}
+
+// fill does run's work, returning a *jobs.Failure for a failure the
+// household may see. On failure it returns the result last published with
+// the error, so run can clear its ideas.
+func (s *Service) fill(ctx context.Context, p FromIngredientsJob, publish func(Result) error) (Result, error) {
+	res := Result{Stage: StageSuggesting, Ingredients: p.Ingredients, QuickOnly: p.QuickOnly, Ideas: []Idea{}}
+	if err := publish(res); err != nil {
+		return res, err
+	}
+	in := skills.IdeasRequest{Ingredients: p.Ingredients, QuickOnly: p.QuickOnly}
+	out, err := s.generate(ctx, skills.IdeasScope(in), in)
+	if err != nil {
+		if ctx.Err() != nil {
+			return res, ctx.Err()
+		}
+		return res, &jobs.Failure{Code: ReasonAIFailed}
+	}
+	res.Stage = StageGrounding
+	res.Dropped = len(out.Dropped)
+	if err := publish(res); err != nil {
+		return res, err
+	}
+	reqs := make([]recipes.GroundRequest, len(out.Ideas))
+	for i, idea := range out.Ideas {
+		reqs[i] = recipes.GroundRequest{DishName: idea.Name, Query: idea.SearchQuery}
+	}
+	err = keepGrounded(ctx, s.grounder, reqs, skills.IdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (Idea, bool) {
+		idea := ideaOf(out.Ideas[i], gr)
+		return idea, !p.QuickOnly || idea.Quick
+	}, func() error { return publish(res) })
+	if err != nil {
+		return res, err
+	}
+	if len(res.Ideas) == 0 {
+		return res, &jobs.Failure{Code: ReasonNoIdeasFound}
+	}
+	res.Stage = StageDone
+	return res, nil
+}
+
+// keepGrounded grounds reqs with g in their order, at most the number
+// still wanted at a time, until want ideas are shown or none are left. As
+// each grounds, keep makes its idea from request i's grounding and says
+// whether it is kept: a kept idea is put in *shown in its place in reqs'
+// order (an idea that grounds sooner than one before it is shown first,
+// and the earlier one is put back in its place when it grounds) and
+// publish is called. An idea no recipe grounds, or that keep refuses,
+// counts in *dropped. Any other grounding failure, or publish failing, is
+// returned (see ground).
+func keepGrounded[T any](ctx context.Context, g *recipes.Grounder, reqs []recipes.GroundRequest, want int, shown *[]T, dropped *int, keep func(i int, gr recipes.Grounded) (T, bool), publish func() error) error {
+	// order[k] is the index in reqs of (*shown)[k], so each idea is put in
+	// its place in reqs' order as it grounds.
+	var order []int
+	for next := 0; len(*shown) < want && next < len(reqs); {
+		first := next
+		round := reqs[first:min(first+want-len(*shown), len(reqs))]
+		next += len(round)
+		err := ground(ctx, g, round, func(i int, gr *recipes.Grounded) error {
+			if gr == nil {
+				*dropped++
+				return nil
+			}
+			idea, ok := keep(first+i, *gr)
+			if !ok {
+				*dropped++
+				return nil
+			}
+			at := len(order)
+			for at > 0 && order[at-1] > first+i {
+				at--
+			}
+			order = slices.Insert(order, at, first+i)
+			*shown = slices.Insert(*shown, at, idea)
+			return publish()
+		})
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ground grounds reqs with g and calls kept, one call at a time, as each
+// request grounds, with its index in reqs and its grounding, or nil when
+// no recipe grounds it. Any other grounding failure, or kept failing,
+// stops the groundings still running and is returned, as a *jobs.Failure
+// when the household may see it.
+func ground(ctx context.Context, g *recipes.Grounder, reqs []recipes.GroundRequest, kept func(i int, gr *recipes.Grounded) error) error {
+	groundCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	var failed error
+	g.GroundEach(groundCtx, reqs, func(i int, r recipes.GroundResult) {
+		if failed != nil {
+			return
+		}
+		var ungroundable *recipes.ErrUngroundable
+		switch {
+		case r.Err == nil:
+			failed = kept(i, &r.Grounded)
+		case errors.As(r.Err, &ungroundable):
+			failed = kept(i, nil)
+		case errors.Is(r.Err, recipes.ErrSearchNotConfigured):
+			failed = &jobs.Failure{Code: ReasonSearchNotConfigured}
+		case errors.Is(r.Err, recipes.ErrSearchFailed):
+			failed = &jobs.Failure{Code: ReasonSearchFailed}
+		case errors.Is(r.Err, recipes.ErrNormalizeFailed):
+			failed = &jobs.Failure{Code: ReasonAIFailed}
+		default:
+			failed = fmt.Errorf("ideas: ground %q: %w", reqs[i].DishName, r.Err)
+		}
+		if failed != nil {
+			cancel()
+		}
+	})
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	return failed
+}
+
+// withoutIdeas is a failed job's stored result as the job shows it: with no
+// ideas, however the job failed, so a failed job never shows ideas kept
+// before the failure.
+func withoutIdeas[R shownResult[R]](stored json.RawMessage) (json.RawMessage, error) {
+	var res R
+	if err := json.Unmarshal(stored, &res); err != nil {
+		return nil, fmt.Errorf("ideas: decode failed job's result: %w", err)
+	}
+	return res.cleared().PublicJSON()
+}
+
+// ideaOf is idea as grounded by gr.
+func ideaOf(idea skills.Idea, gr recipes.Grounded) Idea {
+	return Idea{
+		Name:         idea.Name,
+		Uses:         idea.Uses,
+		Missing:      idea.Missing,
+		Summary:      idea.Summary,
+		Method:       gr.Method,
+		MinutesTotal: gr.MinutesTotal,
+		Difficulty:   gr.Difficulty,
+		Quick:        IsQuick(gr.Method, gr.MinutesTotal),
+		RecipeID:     gr.RecipeID,
+		PhotoURL:     dinners.PhotoURL(gr.PhotoID),
+		SourceURL:    gr.SourceURL,
+		SiteName:     gr.SiteName,
+	}
+}
+
+// QuickJob is the KindQuick payload: the kind of Quick dinner wanted,
+// skills.QuickCrockpot or skills.QuickUnder30, and the names already shown
+// to the household, as skills.CleanExclude returns them.
+type QuickJob struct {
+	Kind    string   `json:"kind"`
+	Exclude []string `json:"exclude"`
+}
+
+// StartQuick enqueues a KindQuick job for a page of Quick dinner ideas of
+// kind, none repeating a name in exclude, and returns its id. A kind
+// skills.CheckQuickKind refuses, with no default, or an exclude list
+// skills.CleanExclude refuses, is an *InvalidError, and starts nothing.
+func (s *Service) StartQuick(ctx context.Context, kind string, exclude []string) (Started, error) {
+	if err := skills.CheckQuickKind(kind); err != nil {
+		return Started{}, &InvalidError{Message: "kind: " + err.Error()}
+	}
+	names, err := skills.CleanExclude(exclude)
+	if err != nil {
+		return Started{}, &InvalidError{Message: "exclude: " + err.Error()}
+	}
+	id, err := s.quickJob.Enqueue(ctx, QuickJob{Kind: kind, Exclude: names})
+	if err != nil {
+		return Started{}, fmt.Errorf("ideas: enqueue: %w", err)
+	}
+	return Started{JobID: id}, nil
+}
+
+// QuickIdea is a grounded Quick dinner idea as the job's result shows it.
+// Method, MinutesTotal and Difficulty are the grounded recipe's, never the
+// model's estimates, and always make it of the kind asked for (see
+// OfQuickKind).
+type QuickIdea struct {
+	Name string `json:"name"`
+	// Method is stovetop, oven, crockpot, grill or other: crockpot for
+	// skills.QuickCrockpot.
+	Method string `json:"method"`
+	// MinutesTotal is prep to table, null when the recipe does not say:
+	// never null, and at most QuickMinutes, for skills.QuickUnder30.
+	MinutesTotal *int `json:"minutes_total"`
+	// Difficulty is easy, medium or hard.
+	Difficulty string `json:"difficulty"`
+	RecipeID   string `json:"recipe_id"`
+	PhotoURL   string `json:"photo_url"`
+	SourceURL  string `json:"source_url"`
+	SiteName   string `json:"site_name"`
+}
+
+// QuickResult is the KindQuick result, published as the job goes: its
+// stage, the request, the ideas grounded so far in the model's order (as
+// in Result), and how many ideas were dropped, by quick_ideas' rules
+// (repeating a name already shown or an earlier idea), because no recipe
+// grounds them, or because the grounded recipe is not of the kind.
+type QuickResult struct {
+	Stage   string      `json:"stage"`
+	Kind    string      `json:"kind"`
+	Exclude []string    `json:"exclude"`
+	Ideas   []QuickIdea `json:"ideas"`
+	Dropped int         `json:"dropped"`
+}
+
+func (r QuickResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+func (r QuickResult) shown() int { return len(r.Ideas) }
+
+func (r QuickResult) cleared() QuickResult {
+	r.Ideas = []QuickIdea{}
+	return r
+}
+
+// OfQuickKind reports whether a recipe cooked by method in minutes (nil
+// when unknown) is a Quick dinner of kind: for skills.QuickCrockpot,
+// cooked in a crock pot (normalize_recipe writes a slow cooker as
+// crockpot); for skills.QuickUnder30, known to be 30 minutes or less from
+// prep to table. Any other kind is none.
+func OfQuickKind(kind, method string, minutes *int) bool {
+	switch kind {
+	case skills.QuickCrockpot:
+		return method == "crockpot"
+	case skills.QuickUnder30:
+		return minutes != nil && *minutes <= QuickMinutes
+	}
+	return false
+}
+
+// runQuick runs a KindQuick job: from the household context, it asks
+// quick_ideas for skills.QuickIdeasRequested ideas of the kind, more than
+// a page holds, then grounds them in the model's order, at most the number
+// still wanted at a time, until skills.QuickIdeasKept are kept or none are
+// left. An idea no recipe grounds is dropped, and so is one whose grounded
+// recipe is not of the kind (OfQuickKind): the model's estimate never
+// keeps an idea. When fewer than skills.QuickIdeasKept survive, the page
+// shows only those: fewer is honest, and it is never padded with an idea
+// not of the kind. When every idea is dropped the job fails with
+// ReasonNoIdeasFound. Any other grounding failure fails the job, as does
+// quick_ideas failing, with no idea made up instead. The result is
+// published at each stage and again as each idea is kept, and a failed job
+// shows no ideas, as for KindFromIngredients (see finish).
+func (s *Service) runQuick(ctx context.Context, p QuickJob, publish func(QuickResult) error) (QuickResult, error) {
+	res, err := s.fillQuick(ctx, p, publish)
+	return finish(ctx, s.logger, "quick ideas", res, err, publish)
+}
+
+// fillQuick does runQuick's work as fill does run's.
+func (s *Service) fillQuick(ctx context.Context, p QuickJob, publish func(QuickResult) error) (QuickResult, error) {
+	res := QuickResult{Stage: StageSuggesting, Kind: p.Kind, Exclude: p.Exclude, Ideas: []QuickIdea{}}
+	if err := publish(res); err != nil {
+		return res, err
+	}
+	hctx, err := harness.BuildContext(ctx, s.st, time.Now(), ContextBudget)
+	if err != nil {
+		return res, fmt.Errorf("ideas: %w", err)
+	}
+	in := skills.QuickIdeasRequest{Context: hctx, Kind: p.Kind, Exclude: p.Exclude}
+	out, err := s.quick(ctx, skills.QuickIdeasScope(in), in)
+	if err != nil {
+		if ctx.Err() != nil {
+			return res, ctx.Err()
+		}
+		return res, &jobs.Failure{Code: ReasonAIFailed}
+	}
+	res.Stage = StageGrounding
+	res.Dropped = len(out.Dropped)
+	if err := publish(res); err != nil {
+		return res, err
+	}
+	reqs := make([]recipes.GroundRequest, len(out.Ideas))
+	for i, idea := range out.Ideas {
+		reqs[i] = recipes.GroundRequest{DishName: idea.Name, Query: idea.SearchQuery}
+	}
+	err = keepGrounded(ctx, s.grounder, reqs, skills.QuickIdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (QuickIdea, bool) {
+		return quickIdeaOf(out.Ideas[i], gr), OfQuickKind(p.Kind, gr.Method, gr.MinutesTotal)
+	}, func() error { return publish(res) })
+	if err != nil {
+		return res, err
+	}
+	if len(res.Ideas) == 0 {
+		return res, &jobs.Failure{Code: ReasonNoIdeasFound}
+	}
+	res.Stage = StageDone
+	return res, nil
+}
+
+// quickIdeaOf is idea as grounded by gr.
+func quickIdeaOf(idea skills.QuickIdea, gr recipes.Grounded) QuickIdea {
+	return QuickIdea{
+		Name:         idea.Name,
+		Method:       gr.Method,
+		MinutesTotal: gr.MinutesTotal,
+		Difficulty:   gr.Difficulty,
+		RecipeID:     gr.RecipeID,
+		PhotoURL:     dinners.PhotoURL(gr.PhotoID),
+		SourceURL:    gr.SourceURL,
+		SiteName:     gr.SiteName,
+	}
+}
+
+// Origins of a dinner made from an idea (the dinners.origin column).
+const (
+	// OriginIngredients is an idea from Cook from what I have.
+	OriginIngredients = "ingredients"
+	// OriginQuick is an idea from Quick dinners.
+	OriginQuick = "quick"
+)
+
+// ErrIdeaNotFound is an idea the household cannot act on: an unknown job,
+// a job that does not find ideas, a failed job (which shows no ideas), or
+// an index past the job's ideas.
+var ErrIdeaNotFound = errors.New("idea not found")
+
+// ErrIdeasNotReady is an idea of a job still queued or running. Its ideas
+// may still move: an idea that grounds later is put back in its place
+// before those shown already, so an index names an idea only once the job
+// has succeeded.
+var ErrIdeasNotReady = errors.New("the ideas are still being found; act on one when the job has succeeded")
+
+// Chosen is the idea the household acts on: its name, the recipe it was
+// grounded in, and the origin of a dinner made from it.
+type Chosen struct {
+	Name     string
+	RecipeID string
+	Origin   string
+}
+
+// Idea returns idea i, counted from 0, of the succeeded job jobID, as its
+// stored result shows it: a dinner made from it uses the recipe it was
+// grounded in, never grounding it again. A job still queued or running is
+// ErrIdeasNotReady; any idea not shown by a succeeded KindFromIngredients
+// or KindQuick job is ErrIdeaNotFound.
+func (s *Service) Idea(ctx context.Context, jobID string, i int) (Chosen, error) {
+	job, err := s.runner.Get(ctx, jobID)
+	if errors.Is(err, jobs.ErrNotFound) {
+		return Chosen{}, ErrIdeaNotFound
+	}
+	if err != nil {
+		return Chosen{}, fmt.Errorf("ideas: read job: %w", err)
+	}
+	if job.Kind != KindFromIngredients && job.Kind != KindQuick {
+		return Chosen{}, ErrIdeaNotFound
+	}
+	switch job.Status {
+	case jobs.StatusQueued, jobs.StatusRunning:
+		return Chosen{}, ErrIdeasNotReady
+	case jobs.StatusSucceeded:
+	default:
+		return Chosen{}, ErrIdeaNotFound
+	}
+	if job.Kind == KindQuick {
+		var res QuickResult
+		if err := json.Unmarshal(job.Result, &res); err != nil {
+			return Chosen{}, fmt.Errorf("ideas: decode %s result: %w", job.Kind, err)
+		}
+		if i < 0 || i >= len(res.Ideas) {
+			return Chosen{}, ErrIdeaNotFound
+		}
+		return Chosen{Name: res.Ideas[i].Name, RecipeID: res.Ideas[i].RecipeID, Origin: OriginQuick}, nil
+	}
+	var res Result
+	if err := json.Unmarshal(job.Result, &res); err != nil {
+		return Chosen{}, fmt.Errorf("ideas: decode %s result: %w", job.Kind, err)
+	}
+	if i < 0 || i >= len(res.Ideas) {
+		return Chosen{}, ErrIdeaNotFound
+	}
+	return Chosen{Name: res.Ideas[i].Name, RecipeID: res.Ideas[i].RecipeID, Origin: OriginIngredients}, nil
+}

internal/ideas/ideas_test.go

@@ -0,0 +1,575 @@
+package ideas
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// pantry is the household's ingredient list.
+var pantry = []string{"Chicken thighs", "rice", "black beans", "red onion", "cilantro"}
+
+type env struct {
+	svc    *Service
+	runner *jobs.Runner
+	search *recipestest.Search
+	pages  *recipestest.Pages
+	images *recipestest.Images
+	// model answers ideas_from_ingredients and quick_ideas; normalize
+	// answers normalize_recipe while grounding.
+	model     *llm.Fake
+	normalize *llm.Fake
+	// fail, when set, fails ideas_from_ingredients and quick_ideas without
+	// a model call.
+	fail error
+	st   *store.Store
+}
+
+// newEnv returns an ideas service over a migrated store with the
+// household's settings seeded and an unstarted
+// job runner. It finds ideas through the real harness and
+// ideas_from_ingredients or quick_ideas with the scripted e.model, and
+// grounds with fake
+// search, pages and images and the scripted e.normalize.
+func newEnv(t *testing.T) *env {
+	t.Helper()
+	ctx := t.Context()
+	dataDir := t.TempDir()
+	st, err := store.Open(ctx, dataDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedSettings(ctx, st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	e := &env{
+		search:    &recipestest.Search{Results: map[string][]recipes.Candidate{}},
+		pages:     &recipestest.Pages{Bodies: map[string][]byte{}},
+		images:    &recipestest.Images{JPEGs: map[string][]byte{}},
+		model:     &llm.Fake{},
+		normalize: &llm.Fake{},
+		st:        st,
+	}
+	g := recipestest.NewGrounder(t, st, dataDir, e.search, e.pages, e.images, e.normalize)
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := harness.Config{
+		Settings:    llm.Settings{Provider: "anthropic", Model: "claude-test", Temperature: 0.7},
+		NewProvider: func(llm.Settings, string) (llm.Provider, error) { return e.model, nil },
+		Store:       st,
+		Guard:       guard,
+	}
+	generate := func(ctx context.Context, scope string, in skills.IdeasRequest) (skills.Ideas, error) {
+		if e.fail != nil {
+			return skills.Ideas{}, e.fail
+		}
+		return skills.IdeasFromIngredients(ctx, cfg, scope, in)
+	}
+	quick := func(ctx context.Context, scope string, in skills.QuickIdeasRequest) (skills.QuickIdeaList, error) {
+		if e.fail != nil {
+			return skills.QuickIdeaList{}, e.fail
+		}
+		return skills.QuickIdeas(ctx, cfg, scope, in)
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	e.runner, err = jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.svc, err = NewService(st, g, generate, quick, e.runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return e
+}
+
+// recipe makes the search for name find one page that grounds it, titled
+// title, with a total time of minutes, and scripts the normalize_recipe
+// reply grounding it takes. The page's total time is the grounded
+// minutes, and "Slow Cooker" in title makes the grounded method crockpot,
+// whatever the reply says.
+func (e *env) recipe(t *testing.T, name, title string, minutes int) {
+	t.Helper()
+	slug := strings.ReplaceAll(strings.ToLower(name), " ", "-")
+	page, photo := "https://r.example/"+slug, "https://r.example/"+slug+".jpg"
+	e.search.Results[name] = []recipes.Candidate{{URL: page}}
+	e.pages.Bodies[page] = recipestest.RecipePage(title, "R Kitchen", photo, minutes)
+	e.images.JPEGs[photo] = recipestest.JPEG(t, 400, 320, uint8(len(e.images.JPEGs)+1))
+	e.normalize.QueueGenerate(recipestest.NormalizedReply("stovetop", minutes))
+}
+
+// idea renders one idea of an ideas_from_ingredients reply whose search
+// query is its name.
+func idea(name, method string, minutes int, uses ...string) string {
+	u, _ := json.Marshal(append([]string{}, uses...))
+	return fmt.Sprintf(`{"name":%q,"uses":%s,"missing":["1 lime"],"est_minutes":%d,"method":%q,"difficulty":"easy","search_query":%q}`,
+		name, u, minutes, method, name)
+}
+
+// reply scripts one ideas_from_ingredients reply holding ideas.
+func (e *env) reply(ideas ...string) {
+	js := `{"ideas":[` + strings.Join(ideas, ",") + `]}`
+	e.model.QueueGenerate(llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}})
+}
+
+// recorder collects every result a job publishes.
+type recorder struct {
+	mu        sync.Mutex
+	published []Result
+}
+
+// latest returns the last result published.
+func (r *recorder) latest() (Result, bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if len(r.published) == 0 {
+		return Result{}, false
+	}
+	return r.published[len(r.published)-1], true
+}
+
+func (r *recorder) publish(res Result) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	// The result's slices are copied, as the runner stores each publish
+	// as JSON at once.
+	res.Ideas = append([]Idea(nil), res.Ideas...)
+	r.published = append(r.published, res)
+	return nil
+}
+
+// run runs the job's handler directly on ingredients, recording each
+// publish.
+func (e *env) run(t *testing.T, ingredients []string, quickOnly bool) (Result, []Result, error) {
+	t.Helper()
+	ings, err := skills.CleanIngredients(ingredients)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rec recorder
+	res, err := e.svc.run(t.Context(), FromIngredientsJob{Ingredients: ings, QuickOnly: quickOnly}, rec.publish)
+	return res, rec.published, err
+}
+
+// within reports whether every name in sub appears in list, in list's
+// order.
+func within(sub, list []string) bool {
+	for _, name := range list {
+		if len(sub) > 0 && sub[0] == name {
+			sub = sub[1:]
+		}
+	}
+	return len(sub) == 0
+}
+
+func names(list []Idea) []string {
+	out := []string{}
+	for _, i := range list {
+		out = append(out, i.Name)
+	}
+	return out
+}
+
+func TestResultFillsAsEachIdeaGrounds(t *testing.T) {
+	e := newEnv(t)
+	for _, name := range []string{"Burrito Bowls", "Fried Rice", "Black Bean Soup", "Chicken Tacos", "Rice Pilaf", "Bean Salad"} {
+		e.recipe(t, name, name, 35)
+	}
+	// Eight ideas: two no recipe grounds, so the sixth and seventh are
+	// grounded in a second round, and the eighth never is.
+	e.reply(
+		idea("Burrito Bowls", "stovetop", 35, "rice", "black beans"),
+		idea("Mystery Stew", "stovetop", 35, "rice"),
+		idea("Fried Rice", "stovetop", 20, "rice", "Chicken thighs"),
+		idea("Black Bean Soup", "stovetop", 40, "black beans", "red onion"),
+		idea("Unknown Casserole", "oven", 50, "rice"),
+		idea("Chicken Tacos", "stovetop", 25, "Chicken thighs", "cilantro"),
+		idea("Rice Pilaf", "stovetop", 30, "rice"),
+		idea("Bean Salad", "other", 15, "black beans"),
+	)
+	res, published, err := e.run(t, pantry, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"Burrito Bowls", "Fried Rice", "Black Bean Soup", "Chicken Tacos", "Rice Pilaf"}
+	if got := names(res.Ideas); !reflect.DeepEqual(got, want) {
+		t.Fatalf("ideas = %q, want %q", got, want)
+	}
+	if res.Stage != StageDone || res.Dropped != 2 {
+		t.Fatalf("result stage %s dropped %d, want done with 2 dropped", res.Stage, res.Dropped)
+	}
+	if !reflect.DeepEqual(res.Ingredients, pantry) || res.QuickOnly {
+		t.Fatalf("result request = %q quick %v", res.Ingredients, res.QuickOnly)
+	}
+	if got := e.search.Queries(); len(got) != 7 || strings.Contains(strings.Join(got, ","), "Bean Salad") {
+		t.Errorf("searched %q, want the first seven ideas only", got)
+	}
+
+	// Each publish: the stage, then one more idea at a time, each idea
+	// grounded when it appears.
+	var stages []string
+	var counts []int
+	for _, p := range published {
+		stages = append(stages, p.Stage)
+		counts = append(counts, len(p.Ideas))
+		for _, i := range p.Ideas {
+			if i.RecipeID == "" || i.PhotoURL == "" || i.Method == "" {
+				t.Errorf("published idea %q is not grounded: %+v", i.Name, i)
+			}
+		}
+	}
+	wantStages := []string{StageSuggesting, StageGrounding, StageGrounding, StageGrounding, StageGrounding, StageGrounding, StageGrounding}
+	if !reflect.DeepEqual(stages, wantStages) || !reflect.DeepEqual(counts, []int{0, 0, 1, 2, 3, 4, 5}) {
+		t.Fatalf("published stages %q with %v ideas, want %q with 0, 0, 1, 2, 3, 4, 5", stages, counts, wantStages)
+	}
+	// Ideas ground concurrently, so one may appear before an earlier one,
+	// but each publish keeps every idea already shown, in the model's
+	// order.
+	for i := 3; i < len(published); i++ {
+		prev, cur := names(published[i-1].Ideas), names(published[i].Ideas)
+		if !within(prev, cur) || !within(cur, want) {
+			t.Errorf("publish %d shows %q after %q, want earlier ideas kept in the model's order %q", i+1, cur, prev, want)
+		}
+	}
+
+	first := res.Ideas[0]
+	if first.Summary != "Uses 2 of 5 · missing: 1 lime" || !reflect.DeepEqual(first.Uses, []string{"rice", "black beans"}) {
+		t.Errorf("first idea = %+v", first)
+	}
+}
+
+func TestQuickOnlyChecksTheGroundedRecipe(t *testing.T) {
+	for _, quickOnly := range []bool{true, false} {
+		t.Run(fmt.Sprintf("quick_only=%v", quickOnly), func(t *testing.T) {
+			e := newEnv(t)
+			// The model estimates every idea quick; the grounded recipes
+			// decide.
+			e.recipe(t, "Fried Rice", "Fried Rice", 25)
+			e.recipe(t, "Chicken Chili", "Slow Cooker Chicken Chili", 240)
+			e.recipe(t, "Bean Enchiladas", "Bean Enchiladas", 55)
+			e.recipe(t, "Rice Bowls", "Rice Bowls", 30)
+			e.recipe(t, "Bean Bake", "Bean Bake", 31)
+			e.reply(
+				idea("Fried Rice", "stovetop", 20, "rice"),
+				idea("Chicken Chili", "stovetop", 25, "Chicken thighs", "black beans"),
+				idea("Bean Enchiladas", "oven", 25, "black beans"),
+				idea("Rice Bowls", "stovetop", 15, "rice"),
+				idea("Bean Bake", "oven", 30, "black beans"),
+			)
+			res, _, err := e.run(t, pantry, quickOnly)
+			if err != nil {
+				t.Fatal(err)
+			}
+			quick := map[string]bool{}
+			for _, i := range res.Ideas {
+				quick[i.Name] = i.Quick
+			}
+			want := map[string]bool{"Fried Rice": true, "Chicken Chili": true, "Rice Bowls": true}
+			wantDropped := 2
+			if !quickOnly {
+				want["Bean Enchiladas"], want["Bean Bake"] = false, false
+				wantDropped = 0
+			}
+			if !reflect.DeepEqual(quick, want) || res.Dropped != wantDropped {
+				t.Fatalf("ideas quick = %v dropped %d, want %v dropped %d", quick, res.Dropped, want, wantDropped)
+			}
+			for _, i := range res.Ideas {
+				if i.Name == "Chicken Chili" && (i.Method != "crockpot" || i.MinutesTotal == nil || *i.MinutesTotal != 240) {
+					t.Errorf("Chicken Chili = %s %v, want the grounded crockpot 240", i.Method, i.MinutesTotal)
+				}
+			}
+		})
+	}
+}
+
+func TestQuickOnlyGroundsMoreToReplaceSlowIdeas(t *testing.T) {
+	e := newEnv(t)
+	slow := []string{"Roast One", "Roast Two", "Roast Three", "Roast Four", "Roast Five"}
+	var reply []string
+	for _, name := range slow {
+		e.recipe(t, name, name, 90)
+		reply = append(reply, idea(name, "oven", 20, "Chicken thighs"))
+	}
+	e.recipe(t, "Fried Rice", "Fried Rice", 20)
+	reply = append(reply, idea("Fried Rice", "stovetop", 20, "rice"))
+	e.reply(reply...)
+	res, _, err := e.run(t, pantry, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := names(res.Ideas); !reflect.DeepEqual(got, []string{"Fried Rice"}) || res.Dropped != 5 {
+		t.Fatalf("ideas = %q dropped %d, want Fried Rice with 5 dropped", got, res.Dropped)
+	}
+}
+
+func TestHallucinatedUsesNeverReachTheResult(t *testing.T) {
+	e := newEnv(t)
+	e.recipe(t, "Burrito Bowls", "Burrito Bowls", 35)
+	e.reply(
+		idea("Burrito Bowls", "stovetop", 35, "rice", "sour cream", "black beans", "cheddar"),
+		idea("Parmesan Pasta", "stovetop", 20, "pasta", "parmesan"),
+	)
+	res, _, err := e.run(t, pantry, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Ideas) != 1 || !reflect.DeepEqual(res.Ideas[0].Uses, []string{"rice", "black beans"}) {
+		t.Fatalf("ideas = %+v, want Burrito Bowls using rice and black beans", res.Ideas)
+	}
+	if res.Ideas[0].Summary != "Uses 2 of 5 · missing: 1 lime" || res.Dropped != 1 {
+		t.Fatalf("summary %q dropped %d", res.Ideas[0].Summary, res.Dropped)
+	}
+	if got := e.search.Queries(); !reflect.DeepEqual(got, []string{"Burrito Bowls"}) {
+		t.Errorf("searched %q, want only the idea kept", got)
+	}
+}
+
+func TestFailures(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		setup func(e *env)
+		code  string
+	}{
+		{"ai fails", func(e *env) { e.fail = errors.New("provider down") }, ReasonAIFailed},
+		{"bad output twice", func(e *env) { e.reply(); e.reply() }, ReasonAIFailed},
+		{"search fails", func(e *env) {
+			e.search.Err = errors.New("boom")
+			e.reply(idea("Fried Rice", "stovetop", 20, "rice"))
+		}, ReasonSearchFailed},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			e := newEnv(t)
+			tc.setup(e)
+			_, published, err := e.run(t, pantry, false)
+			var failure *jobs.Failure
+			if !errors.As(err, &failure) || failure.Code != tc.code {
+				t.Fatalf("err = %v, want failure %s", err, tc.code)
+			}
+			for _, p := range published {
+				if len(p.Ideas) != 0 {
+					t.Fatalf("a failed job published ideas: %+v", p.Ideas)
+				}
+			}
+		})
+	}
+}
+
+func TestEachIdeaShowsAsSoonAsItGrounds(t *testing.T) {
+	e := newEnv(t)
+	for _, name := range []string{"Burrito Bowls", "Fried Rice", "Black Bean Soup"} {
+		e.recipe(t, name, name, 35)
+	}
+	// The first idea's search waits, so the two after it ground first.
+	gate := make(chan struct{})
+	e.search.Gates = map[string]chan struct{}{"Burrito Bowls": gate}
+	e.reply(
+		idea("Burrito Bowls", "stovetop", 35, "rice", "black beans"),
+		idea("Fried Rice", "stovetop", 20, "rice"),
+		idea("Black Bean Soup", "stovetop", 40, "black beans"),
+	)
+	ings, err := skills.CleanIngredients(pantry)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rec recorder
+	type outcome struct {
+		res Result
+		err error
+	}
+	done := make(chan outcome, 1)
+	go func() {
+		res, err := e.svc.run(t.Context(), FromIngredientsJob{Ingredients: ings}, rec.publish)
+		done <- outcome{res, err}
+	}()
+
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		if latest, ok := rec.latest(); ok && len(latest.Ideas) == 2 {
+			if got := names(latest.Ideas); !reflect.DeepEqual(got, []string{"Fried Rice", "Black Bean Soup"}) {
+				t.Fatalf("while the first idea grounds, ideas = %q, want the two grounded", got)
+			}
+			if latest.Stage != StageGrounding {
+				t.Fatalf("stage = %s, want grounding", latest.Stage)
+			}
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("the ideas that grounded were not shown while the first idea was still grounding")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	close(gate)
+	out := <-done
+	if out.err != nil {
+		t.Fatal(out.err)
+	}
+	want := []string{"Burrito Bowls", "Fried Rice", "Black Bean Soup"}
+	if got := names(out.res.Ideas); !reflect.DeepEqual(got, want) || out.res.Stage != StageDone {
+		t.Fatalf("result = %s %q, want done with %q in the model's order", out.res.Stage, got, want)
+	}
+}
+
+func TestNoIdeaKeptFailsTheJob(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		quickOnly bool
+		setup     func(t *testing.T, e *env)
+	}{
+		{"no recipe grounds any", false, func(t *testing.T, e *env) {
+			e.reply(idea("Mystery Stew", "stovetop", 30, "rice"), idea("Unknown Casserole", "oven", 50, "rice"))
+		}},
+		{"no grounded recipe is quick", true, func(t *testing.T, e *env) {
+			e.recipe(t, "Roast Chicken", "Roast Chicken", 90)
+			e.reply(idea("Roast Chicken", "oven", 25, "Chicken thighs"))
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			e := newEnv(t)
+			tc.setup(t, e)
+			_, published, err := e.run(t, pantry, tc.quickOnly)
+			var failure *jobs.Failure
+			if !errors.As(err, &failure) || failure.Code != ReasonNoIdeasFound {
+				t.Fatalf("err = %v, want failure %s", err, ReasonNoIdeasFound)
+			}
+			for _, p := range published {
+				if len(p.Ideas) != 0 || p.Stage == StageDone {
+					t.Fatalf("a job that kept no idea published %+v", p)
+				}
+			}
+		})
+	}
+}
+
+func TestLaterRoundFailureClearsPublishedIdeas(t *testing.T) {
+	e := newEnv(t)
+	kept := []string{"Burrito Bowls", "Fried Rice", "Black Bean Soup", "Chicken Tacos"}
+	for _, name := range kept {
+		e.recipe(t, name, name, 35)
+	}
+	// The first round keeps four ideas; the second round's search fails.
+	e.search.Fail = map[string]error{"Rice Pilaf": errors.New("boom")}
+	e.reply(
+		idea("Burrito Bowls", "stovetop", 35, "rice"),
+		idea("Mystery Stew", "stovetop", 35, "rice"),
+		idea("Fried Rice", "stovetop", 20, "rice"),
+		idea("Black Bean Soup", "stovetop", 40, "black beans"),
+		idea("Chicken Tacos", "stovetop", 25, "Chicken thighs"),
+		idea("Rice Pilaf", "stovetop", 30, "rice"),
+	)
+	_, published, err := e.run(t, pantry, false)
+	var failure *jobs.Failure
+	if !errors.As(err, &failure) || failure.Code != ReasonSearchFailed {
+		t.Fatalf("err = %v, want failure %s", err, ReasonSearchFailed)
+	}
+	most := 0
+	for _, p := range published {
+		most = max(most, len(p.Ideas))
+	}
+	if most != len(kept) {
+		t.Fatalf("at most %d ideas published, want the first round's %d before the failure", most, len(kept))
+	}
+	if last := published[len(published)-1]; len(last.Ideas) != 0 {
+		t.Fatalf("last publish before the failure shows %q, want no ideas", names(last.Ideas))
+	}
+}
+
+func TestStartFromIngredientsRunsTheJob(t *testing.T) {
+	e := newEnv(t)
+	e.recipe(t, "Fried Rice", "Fried Rice", 20)
+	e.reply(idea("Fried Rice", "stovetop", 20, "rice"))
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := e.runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		e.runner.Wait()
+	})
+
+	if _, err := e.svc.StartFromIngredients(t.Context(), []string{"rice", "Rice"}, false); err == nil {
+		t.Fatal("a repeated ingredient was accepted")
+	} else if invalid := (*InvalidError)(nil); !errors.As(err, &invalid) {
+		t.Fatalf("err = %v, want an *InvalidError", err)
+	}
+
+	started, err := e.svc.StartFromIngredients(t.Context(), []string{" rice ", "Chicken thighs"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	deadline := time.Now().Add(10 * time.Second)
+	var job jobs.Job
+	for {
+		job, err = e.runner.Get(t.Context(), started.JobID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if job.Status == jobs.StatusSucceeded || job.Status == jobs.StatusFailed {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job still %s", job.Status)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if job.Status != jobs.StatusSucceeded || job.Kind != KindFromIngredients {
+		t.Fatalf("job = %+v", job)
+	}
+	var res Result
+	if err := json.Unmarshal(job.Result, &res); err != nil {
+		t.Fatal(err)
+	}
+	if res.Stage != StageDone || !reflect.DeepEqual(res.Ingredients, []string{"rice", "Chicken thighs"}) || !res.QuickOnly || len(res.Ideas) != 1 {
+		t.Fatalf("result = %+v", res)
+	}
+	if got := res.Ideas[0]; got.Summary != "Uses 1 of 2 · missing: 1 lime" || !got.Quick {
+		t.Errorf("idea = %+v", got)
+	}
+}
+
+func TestIsQuick(t *testing.T) {
+	m := func(n int) *int { return &n }
+	for _, tc := range []struct {
+		method  string
+		minutes *int
+		want    bool
+	}{
+		{"crockpot", m(480), true},
+		{"crockpot", nil, true},
+		{"stovetop", m(30), true},
+		{"oven", m(31), false},
+		{"stovetop", nil, false},
+	} {
+		if got := IsQuick(tc.method, tc.minutes); got != tc.want {
+			t.Errorf("IsQuick(%s, %v) = %v, want %v", tc.method, tc.minutes, got, tc.want)
+		}
+	}
+}

internal/ideas/quick_test.go

@@ -0,0 +1,400 @@
+package ideas
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+)
+
+// quickIdea renders one idea of a quick_ideas reply whose search query is
+// its name.
+func quickIdea(name, method string, minutes int) string {
+	return fmt.Sprintf(`{"name":%q,"est_minutes":%d,"method":%q,"difficulty":"easy","search_query":%q}`,
+		name, minutes, method, name)
+}
+
+// quickRecorder collects every result a quick job publishes.
+type quickRecorder struct {
+	mu        sync.Mutex
+	published []QuickResult
+}
+
+func (r *quickRecorder) latest() (QuickResult, bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if len(r.published) == 0 {
+		return QuickResult{}, false
+	}
+	return r.published[len(r.published)-1], true
+}
+
+func (r *quickRecorder) publish(res QuickResult) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	res.Ideas = append([]QuickIdea(nil), res.Ideas...)
+	r.published = append(r.published, res)
+	return nil
+}
+
+// runQuick runs the quick job's handler directly, recording each publish.
+func (e *env) runQuick(t *testing.T, kind string, exclude ...string) (QuickResult, []QuickResult, error) {
+	t.Helper()
+	names, err := skills.CleanExclude(exclude)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rec quickRecorder
+	res, err := e.svc.runQuick(t.Context(), QuickJob{Kind: kind, Exclude: names}, rec.publish)
+	return res, rec.published, err
+}
+
+func quickNames(list []QuickIdea) []string {
+	out := []string{}
+	for _, i := range list {
+		out = append(out, i.Name)
+	}
+	return out
+}
+
+func TestUnder30DropsIdeasOverThirtyMinutes(t *testing.T) {
+	e := newEnv(t)
+	// The model estimates every idea under 30 minutes; the grounded
+	// recipes decide.
+	e.recipe(t, "Chicken Fried Rice", "Chicken Fried Rice", 25)
+	e.recipe(t, "Beef Stroganoff", "Beef Stroganoff", 45)
+	e.recipe(t, "Shrimp Scampi", "Shrimp Scampi", 30)
+	e.recipe(t, "Chicken Chili", "Slow Cooker Chicken Chili", 240)
+	e.reply(
+		quickIdea("Chicken Fried Rice", "stovetop", 20),
+		quickIdea("Beef Stroganoff", "stovetop", 25),
+		quickIdea("Shrimp Scampi", "stovetop", 20),
+		quickIdea("Chicken Chili", "crockpot", 25),
+	)
+	res, _, err := e.runQuick(t, skills.QuickUnder30)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := quickNames(res.Ideas), []string{"Chicken Fried Rice", "Shrimp Scampi"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("ideas = %q, want %q: the 45-minute and the crock pot ideas dropped", got, want)
+	}
+	if res.Dropped != 2 || res.Stage != StageDone || res.Kind != skills.QuickUnder30 {
+		t.Fatalf("result = %+v, want done with 2 dropped", res)
+	}
+	for _, i := range res.Ideas {
+		if i.MinutesTotal == nil || *i.MinutesTotal > QuickMinutes || i.RecipeID == "" || i.PhotoURL == "" {
+			t.Errorf("idea %+v is not a grounded dinner of 30 minutes or less", i)
+		}
+	}
+}
+
+func TestCrockpotDropsStovetopIdeas(t *testing.T) {
+	e := newEnv(t)
+	// The model calls every idea a crock pot dinner; only the recipes
+	// cooked in a slow cooker are.
+	e.recipe(t, "Pulled Pork", "Slow Cooker Pulled Pork", 480)
+	e.recipe(t, "Beef Stew", "Beef Stew", 150)
+	e.recipe(t, "Chicken Tortilla Soup", "Crock Pot Chicken Tortilla Soup", 375)
+	e.recipe(t, "Chicken Fried Rice", "Chicken Fried Rice", 25)
+	e.reply(
+		quickIdea("Pulled Pork", "crockpot", 480),
+		quickIdea("Beef Stew", "crockpot", 360),
+		quickIdea("Chicken Tortilla Soup", "crockpot", 375),
+		quickIdea("Chicken Fried Rice", "crockpot", 240),
+	)
+	res, _, err := e.runQuick(t, skills.QuickCrockpot)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := quickNames(res.Ideas), []string{"Pulled Pork", "Chicken Tortilla Soup"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("ideas = %q, want %q: the stovetop ideas dropped", got, want)
+	}
+	if res.Dropped != 2 {
+		t.Fatalf("dropped %d, want 2", res.Dropped)
+	}
+	for _, i := range res.Ideas {
+		if i.Method != "crockpot" {
+			t.Errorf("idea %q method %s, want the grounded crockpot", i.Name, i.Method)
+		}
+	}
+	if m := res.Ideas[0].MinutesTotal; m == nil || *m != 480 {
+		t.Errorf("Pulled Pork minutes_total = %v, want the recipe's 480", m)
+	}
+}
+
+func TestExcludedNamesAreNeverReturned(t *testing.T) {
+	e := newEnv(t)
+	// Every idea has a recipe that would ground it as a Quick dinner.
+	for _, name := range []string{"Easy Chicken Fried Rice", "shrimp-tacos", "Garlic Shrimp Pasta"} {
+		e.recipe(t, name, name, 20)
+	}
+	e.reply(
+		quickIdea("Easy Chicken Fried Rice", "stovetop", 20),
+		quickIdea("shrimp-tacos", "stovetop", 15),
+		quickIdea("Garlic Shrimp Pasta", "stovetop", 25),
+	)
+	res, _, err := e.runQuick(t, skills.QuickUnder30, "Chicken Fried Rice", "Shrimp Tacos")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := quickNames(res.Ideas); !reflect.DeepEqual(got, []string{"Garlic Shrimp Pasta"}) || res.Dropped != 2 {
+		t.Fatalf("ideas = %q dropped %d, want only Garlic Shrimp Pasta with 2 dropped", got, res.Dropped)
+	}
+	if got := e.search.Queries(); !reflect.DeepEqual(got, []string{"Garlic Shrimp Pasta"}) {
+		t.Errorf("searched %q, want the excluded names never grounded", got)
+	}
+	if !reflect.DeepEqual(res.Exclude, []string{"Chicken Fried Rice", "Shrimp Tacos"}) {
+		t.Errorf("result exclude = %q", res.Exclude)
+	}
+	// The model was told what was already shown.
+	if system := e.model.Requests()[0].System; !strings.Contains(system, "### Already shown\n- Chicken Fried Rice\n- Shrimp Tacos") {
+		t.Errorf("prompt does not list the names already shown:\n%s", system)
+	}
+}
+
+func TestQuickPageStopsAtSixAndShowsFewerHonestly(t *testing.T) {
+	t.Run("twelve ideas, six shown", func(t *testing.T) {
+		e := newEnv(t)
+		var reply []string
+		for i := range skills.QuickIdeasRequested {
+			name := fmt.Sprintf("Skillet Dish %c", 'A'+i)
+			e.recipe(t, name, name, 20)
+			reply = append(reply, quickIdea(name, "stovetop", 20))
+		}
+		e.reply(reply...)
+		res, _, err := e.runQuick(t, skills.QuickUnder30)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(res.Ideas) != skills.QuickIdeasKept || res.Dropped != 0 {
+			t.Fatalf("ideas = %q dropped %d, want %d", quickNames(res.Ideas), res.Dropped, skills.QuickIdeasKept)
+		}
+		if got := e.search.Queries(); len(got) != skills.QuickIdeasKept {
+			t.Errorf("searched %d ideas, want only the %d a page holds", len(got), skills.QuickIdeasKept)
+		}
+	})
+	t.Run("over-generated ideas replace dropped ones", func(t *testing.T) {
+		e := newEnv(t)
+		var reply []string
+		// The first six ground too slow, so the next six are grounded to
+		// fill the page; only three of those are quick.
+		for i := range skills.QuickIdeasRequested {
+			name := fmt.Sprintf("Skillet Dish %c", 'A'+i)
+			minutes := 20
+			if i < 6 || i%2 == 1 {
+				minutes = 50
+			}
+			e.recipe(t, name, name, minutes)
+			reply = append(reply, quickIdea(name, "stovetop", 20))
+		}
+		e.reply(reply...)
+		res, _, err := e.runQuick(t, skills.QuickUnder30)
+		if err != nil {
+			t.Fatal(err)
+		}
+		// Fewer than six survive: the page shows three, never padded.
+		if got, want := quickNames(res.Ideas), []string{"Skillet Dish G", "Skillet Dish I", "Skillet Dish K"}; !reflect.DeepEqual(got, want) || res.Dropped != 9 || res.Stage != StageDone {
+			t.Fatalf("result %s ideas %q dropped %d, want done with %q and 9 dropped", res.Stage, got, res.Dropped, want)
+		}
+	})
+}
+
+func TestQuickResultFillsAsEachIdeaGrounds(t *testing.T) {
+	e := newEnv(t)
+	for _, name := range []string{"Chicken Fried Rice", "Shrimp Scampi", "Garlic Shrimp Pasta"} {
+		e.recipe(t, name, name, 25)
+	}
+	// The first idea's search waits, so the two after it ground first.
+	gate := make(chan struct{})
+	e.search.Gates = map[string]chan struct{}{"Chicken Fried Rice": gate}
+	e.reply(
+		quickIdea("Chicken Fried Rice", "stovetop", 20),
+		quickIdea("Shrimp Scampi", "stovetop", 20),
+		quickIdea("Garlic Shrimp Pasta", "stovetop", 25),
+	)
+	var rec quickRecorder
+	type outcome struct {
+		res QuickResult
+		err error
+	}
+	done := make(chan outcome, 1)
+	go func() {
+		res, err := e.svc.runQuick(t.Context(), QuickJob{Kind: skills.QuickUnder30, Exclude: []string{}}, rec.publish)
+		done <- outcome{res, err}
+	}()
+
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		if latest, ok := rec.latest(); ok && len(latest.Ideas) == 2 {
+			if got := quickNames(latest.Ideas); !reflect.DeepEqual(got, []string{"Shrimp Scampi", "Garlic Shrimp Pasta"}) {
+				t.Fatalf("while the first idea grounds, ideas = %q, want the two grounded", got)
+			}
+			if latest.Stage != StageGrounding {
+				t.Fatalf("stage = %s, want grounding", latest.Stage)
+			}
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("the ideas that grounded were not shown while the first idea was still grounding")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	close(gate)
+	out := <-done
+	if out.err != nil {
+		t.Fatal(out.err)
+	}
+	want := []string{"Chicken Fried Rice", "Shrimp Scampi", "Garlic Shrimp Pasta"}
+	if got := quickNames(out.res.Ideas); !reflect.DeepEqual(got, want) || out.res.Stage != StageDone {
+		t.Fatalf("result = %s %q, want done with %q in the model's order", out.res.Stage, got, want)
+	}
+
+	var stages []string
+	var counts []int
+	for _, p := range rec.published {
+		stages = append(stages, p.Stage)
+		counts = append(counts, len(p.Ideas))
+	}
+	if !reflect.DeepEqual(stages, []string{StageSuggesting, StageGrounding, StageGrounding, StageGrounding, StageGrounding}) || !reflect.DeepEqual(counts, []int{0, 0, 1, 2, 3}) {
+		t.Fatalf("published stages %q with %v ideas, want suggesting, then grounding with 0, 1, 2, 3", stages, counts)
+	}
+}
+
+func TestQuickFailures(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		setup func(t *testing.T, e *env)
+		code  string
+	}{
+		{"ai fails", func(t *testing.T, e *env) { e.fail = errors.New("provider down") }, ReasonAIFailed},
+		{"no idea is of the kind", func(t *testing.T, e *env) {
+			e.recipe(t, "Beef Stew", "Beef Stew", 150)
+			e.reply(quickIdea("Beef Stew", "crockpot", 360))
+		}, ReasonNoIdeasFound},
+		{"every idea already shown", func(t *testing.T, e *env) {
+			e.reply(quickIdea("Pulled Pork", "crockpot", 480))
+		}, ReasonNoIdeasFound},
+		{"a later round fails after ideas were shown", func(t *testing.T, e *env) {
+			e.recipe(t, "Chicken Chili", "Slow Cooker Chicken Chili", 240)
+			e.recipe(t, "Beef Stew", "Beef Stew", 150)
+			e.search.Fail = map[string]error{"Lentil Soup": errors.New("boom")}
+			reply := []string{quickIdea("Chicken Chili", "crockpot", 240)}
+			for i := range 5 {
+				name := fmt.Sprintf("Mystery Stew %d", i+1)
+				reply = append(reply, quickIdea(name, "crockpot", 300))
+			}
+			e.reply(append(reply, quickIdea("Lentil Soup", "crockpot", 300))...)
+		}, ReasonSearchFailed},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			e := newEnv(t)
+			tc.setup(t, e)
+			_, published, err := e.runQuick(t, skills.QuickCrockpot, "Pulled Pork")
+			var failure *jobs.Failure
+			if !errors.As(err, &failure) || failure.Code != tc.code {
+				t.Fatalf("err = %v, want failure %s", err, tc.code)
+			}
+			if last := published[len(published)-1]; len(last.Ideas) != 0 || last.Stage == StageDone {
+				t.Fatalf("last publish of a failed job = %+v, want no ideas", last)
+			}
+		})
+	}
+}
+
+func TestStartQuickRunsTheJob(t *testing.T) {
+	e := newEnv(t)
+	e.recipe(t, "Pulled Pork", "Slow Cooker Pulled Pork", 480)
+	e.reply(quickIdea("Pulled Pork", "crockpot", 480))
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := e.runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		e.runner.Wait()
+	})
+
+	for _, tc := range []struct {
+		kind    string
+		exclude []string
+		want    string
+	}{
+		{"", nil, `kind: kind "" is not one of crockpot, under30`},
+		{"quick", nil, `kind: kind "quick" is not one of crockpot, under30`},
+		{skills.QuickCrockpot, []string{"Beef Stew", "beef stew"}, `exclude: excluded name 2, "beef stew", repeats "Beef Stew"`},
+	} {
+		_, err := e.svc.StartQuick(t.Context(), tc.kind, tc.exclude)
+		var invalid *InvalidError
+		if !errors.As(err, &invalid) || invalid.Message != tc.want {
+			t.Errorf("StartQuick(%q, %q) = %v, want %q", tc.kind, tc.exclude, err, tc.want)
+		}
+	}
+
+	started, err := e.svc.StartQuick(t.Context(), skills.QuickCrockpot, []string{" Beef  Stew "})
+	if err != nil {
+		t.Fatal(err)
+	}
+	deadline := time.Now().Add(10 * time.Second)
+	var job jobs.Job
+	for {
+		job, err = e.runner.Get(t.Context(), started.JobID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if job.Status == jobs.StatusSucceeded || job.Status == jobs.StatusFailed {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job still %s", job.Status)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if job.Status != jobs.StatusSucceeded || job.Kind != KindQuick {
+		t.Fatalf("job = %+v", job)
+	}
+	var res QuickResult
+	if err := json.Unmarshal(job.Result, &res); err != nil {
+		t.Fatal(err)
+	}
+	if res.Stage != StageDone || res.Kind != skills.QuickCrockpot || !reflect.DeepEqual(res.Exclude, []string{"Beef Stew"}) || len(res.Ideas) != 1 {
+		t.Fatalf("result = %+v", res)
+	}
+	if got := res.Ideas[0]; got.Name != "Pulled Pork" || got.Method != "crockpot" || got.SiteName != "R Kitchen" {
+		t.Errorf("idea = %+v", got)
+	}
+}
+
+func TestOfQuickKind(t *testing.T) {
+	m := func(n int) *int { return &n }
+	for _, tc := range []struct {
+		kind, method string
+		minutes      *int
+		want         bool
+	}{
+		{skills.QuickCrockpot, "crockpot", m(480), true},
+		{skills.QuickCrockpot, "crockpot", nil, true},
+		{skills.QuickCrockpot, "stovetop", m(20), false},
+		{skills.QuickUnder30, "stovetop", m(30), true},
+		{skills.QuickUnder30, "oven", m(31), false},
+		{skills.QuickUnder30, "stovetop", nil, false},
+		{skills.QuickUnder30, "crockpot", m(240), false},
+		{"quick", "crockpot", m(20), false},
+	} {
+		if got := OfQuickKind(tc.kind, tc.method, tc.minutes); got != tc.want {
+			t.Errorf("OfQuickKind(%s, %s, %v) = %v, want %v", tc.kind, tc.method, tc.minutes, got, tc.want)
+		}
+	}
+	if !slices.Equal(skills.QuickKinds, []string{skills.QuickCrockpot, skills.QuickUnder30}) {
+		t.Errorf("kinds = %q", skills.QuickKinds)
+	}
+}