Feature 13: Discover - Side Quest Suggestions (#110)

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

internal/ai/harness/context_test.go

@@ -82,9 +82,9 @@ func (s *seeder) pass(name, decidedAt string) {
 	batch := s.id("batch")
 	s.exec(`INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
 		VALUES (?, 'manual', 'done', ?, ?)`, batch, decidedAt, decidedAt)
-	s.exec(`INSERT INTO suggestions (id, dinner_id, batch_id, reason, cited_regular_ids, status,
-		decided_at, created_at, updated_at) VALUES (?, ?, ?, 'why', '[]', 'declined', ?, ?, ?)`,
-		s.id("suggestion"), s.dinner(name, "archived", "", "", 0, false), batch, decidedAt, decidedAt, decidedAt)
+	s.exec(`INSERT INTO suggestions (id, dinner_id, batch_id, name, reason, cited_regular_ids, status,
+		decided_at, created_at, updated_at) VALUES (?, ?, ?, ?, 'why', '[]', 'declined', ?, ?, ?)`,
+		s.id("suggestion"), s.dinner(name, "archived", "", "", 0, false), batch, name, decidedAt, decidedAt, decidedAt)
 }
 
 // plan inserts the week plan starting weekStart with one dinner per date;

internal/ai/skills/prompts/checksums.txt

@@ -3,3 +3,4 @@
 # version, rename its template to match and add a line for the new version.
 echo v1 ab5d7884f5c7a2261c06b0c9353bb9597070c001420bd4cbb6ec6272c093fdce
 normalize_recipe v1 7174e5479fc020f3b2b39953d85411381aea26defb9943145e7864c5b752d7ee
+suggest_side_quests v1 bd54d7bf9aea0980059a346e5f40ff4c866b80ef9bb9f74e7cbd413be0911c8a

internal/ai/skills/prompts/suggest_side_quests.v1.tmpl

@@ -0,0 +1,22 @@
+{{/* suggest_side_quests drafts Side quests: new dinners for the household to try, each based on its Regulars. */}}
+{{define "instructions" -}}
+You suggest Side quests: new dinners for the household to try, based on the dinners it already makes.
+
+Every Side quest must be a dinner the household has not had: never one of its Regulars, its Quest log, its pending Side quests or the dinners it has passed, and never one of those under another name. Base every Side quest on one or more of the household's Regulars, such as a familiar protein in a new cuisine or familiar flavours cooked a new way. Prefer the favorite Regulars, and vary the cuisines across the batch.
+
+Give for each Side quest:
+- name: the dinner's usual name, as a recipe site would title it.
+- cuisine: its cuisine, e.g. "Thai" or "Tex-Mex".
+- method: how it is mainly cooked: "stovetop", "oven", "crockpot" (slow cooker or crock pot), "grill" or "other".
+- est_minutes: your estimate of the whole minutes from starting prep to the table.
+- difficulty: "easy", "medium" or "hard" for a home cook.
+- reason: one sentence of at most 180 characters saying why the household would like it. It must name at least one of the Regulars in cited_regulars.
+- cited_regulars: the Regulars the reason relies on, at least one, each written exactly as its name appears in the Regulars list of the household context, without the details in parentheses. Cite only Regulars from that list.
+- search_query: a web search query that finds a recipe for this dinner.
+
+One valid Side quest, for a household with a Regular named "Chicken Fajitas" (an example only, not about this household):
+{"name": "Chicken Shawarma Bowls", "cuisine": "Middle Eastern", "method": "oven", "est_minutes": 40, "difficulty": "easy", "reason": "Spiced roast chicken and crisp toppings, like your Chicken Fajitas with a Middle Eastern twist.", "cited_regulars": ["Chicken Fajitas"], "search_query": "chicken shawarma bowls recipe"}
+{{- end}}
+{{define "user" -}}
+Suggest {{.Count}} Side quests.
+{{- end}}

internal/ai/skills/suggest_side_quests.go

@@ -0,0 +1,420 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+)
+
+// ReasonLimit is the most characters a Side quest's reason, its "Why
+// this?", may have.
+const ReasonLimit = 180
+
+// SideQuestsRequest is what suggest_side_quests reads.
+type SideQuestsRequest struct {
+	// Context is the household context (see harness.BuildContext). It must
+	// hold at least one Regular, since every Side quest cites one.
+	Context harness.HouseholdContext
+	// Needed is how many Side quests the caller wants to keep. The skill
+	// asks the model for twice as many, since validation and grounding
+	// drop some. It must be positive.
+	Needed int
+	// Pending holds the names of the Side quests not yet tried or passed.
+	Pending []string
+	// Declined holds the name of every passed Side quest, not only the
+	// recent ones Context holds.
+	Declined []string
+}
+
+// SideQuest is one suggested new dinner. Method, EstMinutes and Difficulty
+// are the model's estimates until the dinner is grounded in a recipe.
+type SideQuest struct {
+	Name    string `json:"name"`
+	Cuisine string `json:"cuisine"`
+	// Method is one of stovetop, oven, crockpot, grill and other.
+	Method     string `json:"method"`
+	EstMinutes int    `json:"est_minutes"`
+	// Difficulty is easy, medium or hard.
+	Difficulty string `json:"difficulty"`
+	// Reason is the "Why this?": at most ReasonLimit characters, naming at
+	// least one of CitedRegulars.
+	Reason string `json:"reason"`
+	// CitedRegulars are names of the household's Regulars, as the
+	// household writes them.
+	CitedRegulars []string `json:"cited_regulars"`
+	// SearchQuery is a web search query that finds a recipe for the dinner.
+	SearchQuery string `json:"search_query"`
+}
+
+// SideQuests is suggest_side_quests' output.
+type SideQuests struct {
+	// Suggestions are the Side quests that passed every rule, in the
+	// model's order. There may be more or fewer than Needed.
+	Suggestions []SideQuest `json:"suggestions"`
+	// Dropped are the Side quests the model gave that broke a rule, in the
+	// model's order. It is never part of the model's reply.
+	Dropped []DroppedSideQuest `json:"-"`
+}
+
+// DroppedSideQuest is a Side quest dropped by PostProcess.
+type DroppedSideQuest struct {
+	Name string
+	// Why says which rule it broke.
+	Why string
+}
+
+// SuggestSideQuests runs suggest_side_quests v1 on in and returns the Side
+// quests that cite only real Regulars, give a short reason naming one of
+// them, and repeat no Regular, Quest log dinner, pending or passed Side
+// quest, nor each other. The rest are in Dropped. scope names the batch
+// (see harness.Run).
+func SuggestSideQuests(ctx context.Context, cfg harness.Config, scope string, in SideQuestsRequest) (SideQuests, error) {
+	return harness.Run(ctx, cfg, suggestSideQuests{in: in}, scope, in)
+}
+
+// suggestSideQuests is the skill. It holds its input because validation
+// and post-processing compare the output with it.
+type suggestSideQuests struct {
+	in SideQuestsRequest
+}
+
+var _ harness.Skill[SideQuestsRequest, SideQuests] = suggestSideQuests{}
+
+func (suggestSideQuests) Name() string { return "suggest_side_quests" }
+
+func (suggestSideQuests) Version() int { return 1 }
+
+func (suggestSideQuests) Timeout() time.Duration { return harness.DefaultTimeout }
+
+// sideQuestsPrompt is the template data of suggest_side_quests.v1.tmpl.
+type sideQuestsPrompt struct {
+	// Count is how many Side quests to ask for.
+	Count int
+}
+
+// requested is how many Side quests the model is asked for.
+func (s suggestSideQuests) requested() int { return 2 * s.in.Needed }
+
+func (suggestSideQuests) PromptInput(in SideQuestsRequest) (harness.PromptInput, error) {
+	if in.Needed <= 0 {
+		return harness.PromptInput{}, fmt.Errorf("%d Side quests needed; the number must be positive", in.Needed)
+	}
+	if len(in.Context.Regulars) == 0 {
+		return harness.PromptInput{}, errors.New("household has no Regulars for Side quests to be based on")
+	}
+	sections := append(in.Context.Sections(), harness.ContextSection{Title: "Pending Side quests", Lines: in.Pending})
+	return harness.PromptInput{Data: sideQuestsPrompt{Count: suggestSideQuests{in: in}.requested()}, Context: sections}, nil
+}
+
+func (suggestSideQuests) Schema() llm.JSONSchema {
+	return llm.JSONSchema{Name: "suggest_side_quests", Schema: json.RawMessage(`{
+		"type": "object",
+		"properties": {
+			"suggestions": {
+				"type": "array",
+				"items": {
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"},
+						"cuisine": {"type": "string"},
+						"method": {"type": "string", "enum": ["stovetop", "oven", "crockpot", "grill", "other"]},
+						"est_minutes": {"type": "integer"},
+						"difficulty": {"type": "string", "enum": ["easy", "medium", "hard"]},
+						"reason": {"type": "string"},
+						"cited_regulars": {"type": "array", "items": {"type": "string"}},
+						"search_query": {"type": "string"}
+					},
+					"required": ["name", "cuisine", "method", "est_minutes", "difficulty", "reason", "cited_regulars", "search_query"],
+					"additionalProperties": false
+				}
+			}
+		},
+		"required": ["suggestions"],
+		"additionalProperties": false
+	}`)}
+}
+
+// UnmarshalJSON decodes a Side quest, requiring each of its fields as the
+// schema does: encoding/json would otherwise read a missing or null one as
+// empty.
+func (q *SideQuest) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "name", "cuisine", "method", "est_minutes", "difficulty", "reason", "cited_regulars", "search_query"); err != nil {
+		return fmt.Errorf("suggestion %s", err)
+	}
+	type plain SideQuest
+	return json.Unmarshal(data, (*plain)(q))
+}
+
+// UnmarshalJSON decodes the output, requiring its one field as the schema
+// does.
+func (out *SideQuests) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "suggestions"); err != nil {
+		return fmt.Errorf("output %s", err)
+	}
+	type plain SideQuests
+	return json.Unmarshal(data, (*plain)(out))
+}
+
+// Validate finds what makes the reply unusable as a whole: a wrong number
+// of Side quests or one that is malformed. A well-formed Side quest that
+// breaks a rule is dropped by PostProcess instead.
+func (s suggestSideQuests) Validate(out SideQuests) []string {
+	var problems []string
+	switch n := len(out.Suggestions); {
+	case n == 0 && len(out.Dropped) == 0:
+		problems = append(problems, fmt.Sprintf("suggestions is empty; give %d Side quests", s.requested()))
+	case n > s.requested():
+		problems = append(problems, fmt.Sprintf("suggestions has %d entries; give at most %d Side quests", n, s.requested()))
+	}
+	for i, q := range out.Suggestions {
+		for _, f := range []struct{ field, value string }{
+			{"name", q.Name}, {"cuisine", q.Cuisine}, {"reason", q.Reason}, {"search_query", q.SearchQuery},
+		} {
+			if strings.TrimSpace(f.value) == "" {
+				problems = append(problems, fmt.Sprintf("suggestion %d has an empty %s; give one", i+1, f.field))
+			}
+		}
+		if strings.TrimSpace(q.Name) != "" && harness.Normalize(q.Name) == "" {
+			problems = append(problems, fmt.Sprintf("suggestion %d name %q has only filler words; name the dish", i+1, q.Name))
+		}
+		if !slices.Contains(methods, q.Method) {
+			problems = append(problems, fmt.Sprintf("suggestion %d method %q is not one of %s", i+1, q.Method, strings.Join(methods, ", ")))
+		}
+		if q.EstMinutes <= 0 {
+			problems = append(problems, fmt.Sprintf("suggestion %d est_minutes %d is not positive; give the minutes from prep to table", i+1, q.EstMinutes))
+		}
+		if !slices.Contains(difficulties, q.Difficulty) {
+			problems = append(problems, fmt.Sprintf("suggestion %d difficulty %q is not one of %s", i+1, q.Difficulty, strings.Join(difficulties, ", ")))
+		}
+	}
+	return problems
+}
+
+// PostProcess tidies every Side quest's text, writes its cited Regulars as
+// the household does, and moves each one that breaks a rule to Dropped
+// (see drop).
+func (s suggestSideQuests) PostProcess(out SideQuests) (SideQuests, error) {
+	regulars := regularNames{exact: map[string][]string{}, normalized: map[string][]string{}}
+	var names []string
+	for _, r := range s.in.Context.Regulars {
+		regulars.add(r.Name)
+		names = append(names, r.Name)
+	}
+	regulars.all = names
+	known := harness.NewDeduper(harness.DedupeSources{
+		Regulars: names,
+		QuestLog: s.in.Context.QuestLog,
+		Pending:  s.in.Pending,
+		Declined: s.in.Declined,
+	})
+	result := SideQuests{Suggestions: []SideQuest{}}
+	for _, q := range out.Suggestions {
+		q = SideQuest{
+			Name:          oneLine(q.Name),
+			Cuisine:       oneLine(q.Cuisine),
+			Method:        q.Method,
+			EstMinutes:    q.EstMinutes,
+			Difficulty:    q.Difficulty,
+			Reason:        oneLine(q.Reason),
+			CitedRegulars: q.CitedRegulars,
+			SearchQuery:   oneLine(q.SearchQuery),
+		}
+		cited, why := drop(q, regulars, known, result.Suggestions)
+		if why != "" {
+			result.Dropped = append(result.Dropped, DroppedSideQuest{Name: q.Name, Why: why})
+			continue
+		}
+		q.CitedRegulars = cited
+		result.Suggestions = append(result.Suggestions, q)
+	}
+	return result, nil
+}
+
+// regularNames finds the Regular a cited name means. Names need not be
+// unique, even ignoring case, so each key holds every Regular with it.
+type regularNames struct {
+	// exact is keyed by the name in lower case on one line.
+	exact map[string][]string
+	// normalized is keyed by harness.Normalize of the name.
+	normalized map[string][]string
+	// all holds every Regular's name, in the household's order.
+	all []string
+}
+
+func exactName(name string) string { return strings.ToLower(oneLine(name)) }
+
+func (r regularNames) add(name string) {
+	r.exact[exactName(name)] = append(r.exact[exactName(name)], name)
+	if n := harness.Normalize(name); n != "" {
+		r.normalized[n] = append(r.normalized[n], name)
+	}
+}
+
+// find returns the one Regular cited means, or "" and why there is none.
+// A Regular named exactly cited, ignoring case and spacing, comes first;
+// failing that, cited may name a Regular by its normalized name.
+func (r regularNames) find(cited string) (string, string) {
+	matches := r.exact[exactName(cited)]
+	if len(matches) == 0 {
+		matches = r.normalized[harness.Normalize(cited)]
+	}
+	switch len(matches) {
+	case 0:
+		return "", fmt.Sprintf("cites %q, which is not a Regular", cited)
+	case 1:
+		return matches[0], ""
+	default:
+		return "", fmt.Sprintf("cites %q, which could be any of the Regulars %q", cited, matches)
+	}
+}
+
+// drop returns why q must be dropped, or "" and its cited Regulars as the
+// household writes them when it may be kept. q is dropped when it repeats
+// a known dinner or a Side quest already kept, cites no Regular or one
+// regulars finds no single Regular for, or has a reason over ReasonLimit
+// characters or naming none of its cited Regulars.
+func drop(q SideQuest, regulars regularNames, known *harness.Deduper, kept []SideQuest) ([]string, string) {
+	if known.IsDuplicate(q.Name) {
+		return nil, "repeats a Regular, Quest log dinner, pending or passed Side quest"
+	}
+	for _, k := range kept {
+		if harness.Similar(q.Name, k.Name) {
+			return nil, fmt.Sprintf("repeats the Side quest %q in the same batch", k.Name)
+		}
+	}
+	if len(q.CitedRegulars) == 0 {
+		return nil, "cites no Regular"
+	}
+	var cited []string
+	for _, c := range q.CitedRegulars {
+		name, why := regulars.find(c)
+		if why != "" {
+			return nil, why
+		}
+		cited = append(cited, name)
+	}
+	if n := utf8.RuneCountInString(q.Reason); n > ReasonLimit {
+		return nil, fmt.Sprintf("reason has %d characters, over %d", n, ReasonLimit)
+	}
+	named := regulars.named(q.Reason)
+	if !slices.ContainsFunc(cited, func(name string) bool { return slices.Contains(named, name) }) {
+		return nil, "reason names none of its cited Regulars"
+	}
+	return cited, ""
+}
+
+// named returns the Regulars text names, by one rule. A mention of a
+// Regular is a place where text spells its name, ignoring case and spacing,
+// with no letter, mark or digit just outside it: the start or end of text,
+// white space, punctuation or a symbol must border it, so "Beef
+// Chili-inspired" and "Beef Chili's" mention "Beef Chili" while "Beef
+// Chilis" does not, nor does "Cafe" with a combining accent after it
+// mention "Cafe". Punctuation at either end of the name, with any spacing
+// beside it, is optional, and a mention takes in as much of it as text
+// spells, spaced in any way, with the border still holding after it: "Easy
+// Beef Chili!" is mentioned by "Easy Beef Chili." too, by "Easy Beef Chili
+// !" with its "!", and by "Easy Beef Chili!x" without its "!", and "Beef
+// Chili!!" by "Beef Chili!" with one "!". A
+// combining mark is part of its letter, never punctuation. A mention names
+// its Regular unless a mention of a different Regular covers the same text
+// or more, so "Your Easy Beef Chili." names "Easy Beef Chili" and not "Beef
+// Chili", and text that two Regulars spell alike names neither there.
+func (r regularNames) named(text string) []string {
+	type mention struct {
+		name       string
+		start, end int
+	}
+	text = exactName(text)
+	bordered := func(start, end int) bool {
+		before, _ := utf8.DecodeLastRuneInString(text[:start])
+		after, _ := utf8.DecodeRuneInString(text[end:])
+		return (start == 0 || !isWord(before)) && (end == len(text) || !isWord(after))
+	}
+	var mentions []mention
+	for _, name := range r.all {
+		full := exactName(name)
+		core := strings.TrimFunc(full, isOuter)
+		if core == "" {
+			continue
+		}
+		lead := full[:len(full)-len(strings.TrimLeftFunc(full, isOuter))]
+		trail := full[len(lead)+len(core):]
+		for at := 0; ; {
+			i := strings.Index(text[at:], core)
+			if i < 0 {
+				break
+			}
+			start, end := at+i, at+i+len(core)
+			at = start + 1
+			if !bordered(start, end) {
+				continue
+			}
+			start = spelledBefore(text, start, lead, func(s int) bool { return bordered(s, end) })
+			end = spelledAfter(text, end, trail, func(e int) bool { return bordered(start, e) })
+			mentions = append(mentions, mention{name, start, end})
+		}
+	}
+	var names []string
+	for _, m := range mentions {
+		covered := slices.ContainsFunc(mentions, func(o mention) bool {
+			return o.name != m.name && o.start <= m.start && o.end >= m.end
+		})
+		if !covered && !slices.Contains(names, m.name) {
+			names = append(names, m.name)
+		}
+	}
+	return names
+}
+
+// spelledAfter returns where the longest start of outer that text spells
+// from at ends, ignoring spacing, among those after which bordered holds,
+// or at when there are none.
+func spelledAfter(text string, at int, outer string, bordered func(int) bool) int {
+	end := at
+	for _, c := range strings.Join(strings.Fields(outer), "") {
+		at = len(text) - len(strings.TrimLeftFunc(text[at:], unicode.IsSpace))
+		if !strings.HasPrefix(text[at:], string(c)) {
+			break
+		}
+		at += utf8.RuneLen(c)
+		if bordered(at) {
+			end = at
+		}
+	}
+	return end
+}
+
+// spelledBefore returns where the longest end of outer that text spells up
+// to at starts, ignoring spacing, among those before which bordered holds,
+// or at when there are none.
+func spelledBefore(text string, at int, outer string, bordered func(int) bool) int {
+	start := at
+	punct := []rune(strings.Join(strings.Fields(outer), ""))
+	for i := len(punct) - 1; i >= 0; i-- {
+		at = len(strings.TrimRightFunc(text[:at], unicode.IsSpace))
+		if !strings.HasSuffix(text[:at], string(punct[i])) {
+			break
+		}
+		at -= utf8.RuneLen(punct[i])
+		if bordered(at) {
+			start = at
+		}
+	}
+	return start
+}
+
+// isWord reports whether c is a letter, a mark on one or a digit.
+func isWord(c rune) bool { return unicode.IsLetter(c) || unicode.IsMark(c) || unicode.IsDigit(c) }
+
+// isOuter reports whether c may be left off the end of a name: punctuation
+// or white space.
+func isOuter(c rune) bool { return unicode.IsPunct(c) || unicode.IsSpace(c) }

internal/ai/skills/suggest_side_quests_test.go

@@ -0,0 +1,488 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+	"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/store"
+)
+
+func date(y int, m time.Month, d int) store.LocalDate {
+	return store.LocalDateOf(time.Date(y, m, d, 0, 0, 0, 0, time.UTC))
+}
+
+// household asks for two Side quests, so four are requested.
+var household = SideQuestsRequest{
+	Context: harness.HouseholdContext{
+		Today:    date(2026, 10, 6),
+		Timezone: "America/New_York",
+		Regulars: []harness.RegularDinner{
+			{Name: "Beef Chili", Cuisine: "Tex-Mex", Method: "crockpot", Minutes: 240},
+			{Name: "Chicken Fajitas", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30, Favorite: true},
+			{Name: "Spaghetti Bolognese", Cuisine: "Italian", Method: "stovetop", Minutes: 45},
+		},
+		QuestLog: []string{"Pad Thai"},
+		Passed:   []string{"Chicken Tikka Masala"},
+		Plans: []harness.PlannedDinner{
+			{Date: date(2026, 10, 5), Name: "Chicken Fajitas"},
+			{Date: date(2026, 10, 6), Name: "Beef Chili"},
+		},
+	},
+	Needed:   2,
+	Pending:  []string{"Shrimp Scampi"},
+	Declined: []string{"Chicken Tikka Masala", "Fish Tacos"},
+}
+
+// sideQuest renders one Side quest of a reply.
+func sideQuest(name, reason string, cited ...string) string {
+	c, _ := json.Marshal(append([]string{}, cited...))
+	r, _ := json.Marshal(reason)
+	return fmt.Sprintf(`{"name":%q,"cuisine":"Fusion","method":"stovetop","est_minutes":35,"difficulty":"easy","reason":%s,"cited_regulars":%s,"search_query":%q}`,
+		name, r, c, strings.ToLower(name)+" recipe")
+}
+
+// batch renders a reply holding the Side quests given.
+func batch(quests ...string) string {
+	return `{"suggestions":[` + strings.Join(quests, ",") + `]}`
+}
+
+var (
+	shawarma = sideQuest("Chicken Shawarma Bowls", "Spiced chicken and crisp toppings, like your Chicken Fajitas.", "Chicken Fajitas")
+	ragu     = sideQuest("Beef Ragu Pappardelle", "A slow beef sauce like your Spaghetti Bolognese, on wide noodles.", "Spaghetti Bolognese")
+	verde    = sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "beef chili")
+	bulgogi  = sideQuest("Beef Bulgogi", "Sweet, quick-seared beef for fans of Chicken Fajitas and Beef Chili.", "Chicken Fajitas", "Beef Chili")
+)
+
+// want returns the Side quest that sideQuest renders, with cited as the
+// household writes them.
+func want(name, reason string, cited ...string) SideQuest {
+	return SideQuest{
+		Name: name, Cuisine: "Fusion", Method: "stovetop", EstMinutes: 35, Difficulty: "easy",
+		Reason: reason, CitedRegulars: cited, SearchQuery: strings.ToLower(name) + " recipe",
+	}
+}
+
+var (
+	wantShawarma = want("Chicken Shawarma Bowls", "Spiced chicken and crisp toppings, like your Chicken Fajitas.", "Chicken Fajitas")
+	wantRagu     = want("Beef Ragu Pappardelle", "A slow beef sauce like your Spaghetti Bolognese, on wide noodles.", "Spaghetti Bolognese")
+	wantVerde    = want("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Beef Chili")
+	wantBulgogi  = want("Beef Bulgogi", "Sweet, quick-seared beef for fans of Chicken Fajitas and Beef Chili.", "Chicken Fajitas", "Beef Chili")
+)
+
+// suggest runs SuggestSideQuests on household with f and checks f was
+// called exactly calls times, each at the household temperature.
+func suggest(t *testing.T, f *llm.Fake, in SideQuestsRequest, calls int) (SideQuests, []llm.Request, error) {
+	t.Helper()
+	out, err := SuggestSideQuests(context.Background(), testConfig(t, f), "2026-W41", in)
+	reqs := f.Requests()
+	if len(reqs) != calls {
+		t.Fatalf("Generate called %d times, want %d", len(reqs), calls)
+	}
+	if g, _, _ := f.Remaining(); g != 0 {
+		t.Fatalf("%d scripted Generate results unused", g)
+	}
+	for i, req := range reqs {
+		if req.Temperature == nil || *req.Temperature != 0.7 {
+			t.Fatalf("request %d temperature = %v, want 0.7", i+1, req.Temperature)
+		}
+		if req.Schema == nil || req.Schema.Name != "suggest_side_quests" {
+			t.Fatalf("request %d schema = %v, want suggest_side_quests", i+1, req.Schema)
+		}
+	}
+	return out, reqs, err
+}
+
+func assertSideQuests(t *testing.T, got, want SideQuests) {
+	t.Helper()
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("output = %+v\nwant     %+v", got, want)
+	}
+}
+
+func TestSuggestSideQuestsCleanBatch(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(shawarma, ragu, verde, bulgogi)))
+	out, reqs, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu, wantVerde, wantBulgogi}})
+
+	system, user := reqs[0].System, reqs[0].Messages[0].Content
+	golden(t, "suggest_side_quests_clean.system.golden", system)
+	golden(t, "suggest_side_quests_clean.user.golden", user)
+	for _, part := range []string{
+		"## Household context",
+		"- Chicken Fajitas (Tex-Mex, stovetop, 30 min, favorite)",
+		"### Quest log\n- Pad Thai",
+		"### Passed, oldest first\n- Chicken Tikka Masala",
+		"- 2026-10-06 Tue: Beef Chili",
+		"### Pending Side quests\n- Shrimp Scampi",
+		"## Output contract",
+		`"cited_regulars"`,
+		`"search_query"`,
+	} {
+		if !strings.Contains(system, part) {
+			t.Errorf("system prompt lacks %q", part)
+		}
+	}
+	if strings.Index(system, "## Household context") > strings.Index(system, "## Output contract") {
+		t.Error("the output contract is not after the household context")
+	}
+	if user != "Suggest 4 Side quests." {
+		t.Errorf("user message = %q, want twice the 2 needed", user)
+	}
+}
+
+func TestSuggestSideQuestsPersonaFirst(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(shawarma)))
+	cfg := testConfig(t, &f)
+	cfg.Persona = "You are the household's cheerful kitchen helper."
+	if _, err := SuggestSideQuests(context.Background(), cfg, "2026-W41", household); err != nil {
+		t.Fatal(err)
+	}
+	if system := f.Requests()[0].System; !strings.HasPrefix(system, cfg.Persona+"\n\n## Instructions\n") {
+		t.Fatalf("system prompt does not start with the persona then the instructions:\n%s", system)
+	}
+}
+
+func TestSuggestSideQuestsInventedRegularDropped(t *testing.T) {
+	invented := sideQuest("Meatloaf Wellington", "Your Grandma's Meatloaf, wrapped in pastry.", "Grandma's Meatloaf")
+	partly := sideQuest("Fajita Meatballs", "Chicken Fajitas meets your Grandma's Meatloaf.", "Chicken Fajitas", "Grandma's Meatloaf")
+	none := sideQuest("Mushroom Risotto", "Creamy and comforting.")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(invented, shawarma, partly, none)))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantShawarma},
+		Dropped: []DroppedSideQuest{
+			{Name: "Meatloaf Wellington", Why: `cites "Grandma's Meatloaf", which is not a Regular`},
+			{Name: "Fajita Meatballs", Why: `cites "Grandma's Meatloaf", which is not a Regular`},
+			{Name: "Mushroom Risotto", Why: "cites no Regular"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsSharedNormalizedRegularNotRewritten(t *testing.T) {
+	in := household
+	in.Context.Regulars = append(slices.Clone(household.Context.Regulars),
+		harness.RegularDinner{Name: "Easy Beef Chili", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+	plain := sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "beef chili")
+	easy := sideQuest("Frito Pie", "Your Easy Beef Chili over corn chips.", "EASY  beef chili")
+	either := sideQuest("Tamale Bake", "Your Beef Chili under a cornbread crust.", "Beef Chili!")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(plain, easy, either)))
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{
+			want("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Beef Chili"),
+			want("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili"),
+		},
+		Dropped: []DroppedSideQuest{
+			{Name: "Tamale Bake", Why: `cites "Beef Chili!", which could be any of the Regulars ["Beef Chili" "Easy Beef Chili"]`},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonNamesResolvedRegular(t *testing.T) {
+	in := household
+	in.Context.Regulars = append(slices.Clone(household.Context.Regulars),
+		harness.RegularDinner{Name: "Easy Beef Chili", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+	other := sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Easy Beef Chili")
+	easy := sideQuest("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili")
+	plain := sideQuest("Chili Mac", "The Beef Chili, not the Easy Beef Chili, over macaroni.", "Beef Chili")
+	inside := sideQuest("Tamale Bake", "Your Easy Beef Chili under a cornbread crust.", "Beef Chili")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(other, easy, plain, inside)))
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{
+			want("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili"),
+			want("Chili Mac", "The Beef Chili, not the Easy Beef Chili, over macaroni.", "Beef Chili"),
+		},
+		Dropped: []DroppedSideQuest{
+			{Name: "Chili Verde", Why: "reason names none of its cited Regulars"},
+			{Name: "Tamale Bake", Why: "reason names none of its cited Regulars"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonMentionRule(t *testing.T) {
+	const none = "reason names none of its cited Regulars"
+	for name, tc := range map[string]struct {
+		extra  []string // Regulars added to household's
+		reason string
+		cited  string
+		why    string // "" when the Side quest is kept
+	}{
+		"exact name":                   {nil, "Like your Beef Chili, gone green.", "Beef Chili", ""},
+		"other case and spacing":       {nil, "Like your beef  CHILI, gone green.", "Beef Chili", ""},
+		"sentence punctuation":         {nil, `Green, like "Beef Chili" (yours).`, "Beef Chili", ""},
+		"possessive":                   {nil, "Beef Chili's spices, gone green.", "Beef Chili", ""},
+		"joined by punctuation":        {nil, "A Beef Chili-inspired stew.", "Beef Chili", ""},
+		"no mention":                   {nil, "Grilled skewers with a peanut sauce.", "Beef Chili", none},
+		"letters run on":               {[]string{"Ham"}, "Like your Hamburgers, glazed.", "Ham", none},
+		"stored punctuation written":   {[]string{"Easy Beef Chili!"}, "Your Easy Beef Chili! over corn chips.", "Easy Beef Chili!", ""},
+		"stored punctuation as period": {[]string{"Easy Beef Chili!"}, "Corn chips under your Easy Beef Chili.", "Easy Beef Chili!", ""},
+		"inside stored punctuation":    {[]string{"Easy Beef Chili!"}, "Your Easy Beef Chili! over corn chips.", "Beef Chili", none},
+		"inside before period":         {[]string{"Easy Beef Chili!"}, "Corn chips under your Easy Beef Chili.", "Beef Chili", none},
+		"longer name cited":            {[]string{"Easy Beef Chili"}, "Your Easy Beef Chili over corn chips.", "Easy Beef Chili", ""},
+		"shorter inside longer":        {[]string{"Easy Beef Chili"}, "Your Easy Beef Chili over corn chips.", "Beef Chili", none},
+		"longer not mentioned":         {[]string{"Easy Beef Chili"}, "Your Beef Chili over corn chips.", "Easy Beef Chili", none},
+		"shorter also on its own":      {[]string{"Easy Beef Chili"}, "The Beef Chili, not the Easy Beef Chili.", "Beef Chili", ""},
+		"punctuation-only difference":  {[]string{"Beef Chili!"}, "Your Beef Chili! over corn chips.", "Beef Chili!", ""},
+		"bare name inside punctuated":  {[]string{"Beef Chili!"}, "Your Beef Chili! over corn chips.", "Beef Chili", none},
+		"spelled alike by both":        {[]string{"Beef Chili!"}, "Corn chips under your Beef Chili.", "Beef Chili", none},
+		"punctuation then a letter":    {[]string{"Beef Chili!"}, "Your Beef Chili!X is our inspiration.", "Beef Chili!", none},
+		"letter before punctuation":    {[]string{"¡Beef Chili"}, "Your X¡Beef Chili is our inspiration.", "¡Beef Chili", none},
+		"spacing before punctuation":   {[]string{"Beef Chili!"}, "Your Beef Chili ! over corn chips.", "Beef Chili!", ""},
+		"spacing after punctuation":    {[]string{"¡Beef Chili"}, "Your ¡ Beef Chili is our inspiration.", "¡Beef Chili", ""},
+		"stored spacing left off":      {[]string{"Beef Chili !", "Chili!"}, "Like your Beef Chili!", "Beef Chili !", ""},
+		"inside unspaced punctuation":  {[]string{"Beef Chili !", "Chili!"}, "Like your Beef Chili!", "Chili!", none},
+		"stored punctuation partly":    {[]string{"Beef Chili!!", "Chili!"}, "Like your Beef Chili!", "Beef Chili!!", ""},
+		"inside partial punctuation":   {[]string{"Beef Chili!!", "Chili!"}, "Like your Beef Chili!", "Chili!", none},
+		"partly then a letter":         {[]string{"Beef Chili!!", "Chili!"}, "Your Beef Chili!!X is our inspiration.", "Chili!", none},
+		"leading punctuation partly":   {[]string{"¡¡Beef Chili", "¡Beef"}, "Like your ¡Beef Chili.", "¡¡Beef Chili", ""},
+		"inside partial leading":       {[]string{"¡¡Beef Chili", "¡Beef"}, "Like your ¡Beef Chili.", "¡Beef", none},
+		"stored symbol left off":       {[]string{"Green Chili 🌶"}, "Like your Green Chili, gone green.", "Green Chili 🌶", none},
+		"stored accent left off":       {[]string{"Chicken Cafe\u0301"}, "Like your Chicken Cafe, gone green.", "Chicken Cafe\u0301", none},
+		"accent written after name":    {[]string{"Chicken Cafe"}, "Like your Chicken Cafe\u0301, gone green.", "Chicken Cafe", none},
+	} {
+		t.Run(name, func(t *testing.T) {
+			in := household
+			in.Context.Regulars = slices.Clone(household.Context.Regulars)
+			for _, r := range tc.extra {
+				in.Context.Regulars = append(in.Context.Regulars, harness.RegularDinner{Name: r, Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+			}
+			var f llm.Fake
+			f.QueueGenerate(reply(batch(sideQuest("Frito Pie", tc.reason, tc.cited))))
+			out, _, err := suggest(t, &f, in, 1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			result := SideQuests{Suggestions: []SideQuest{want("Frito Pie", oneLine(tc.reason), tc.cited)}}
+			if tc.why != "" {
+				result = SideQuests{Suggestions: []SideQuest{}, Dropped: []DroppedSideQuest{{Name: "Frito Pie", Why: tc.why}}}
+			}
+			assertSideQuests(t, out, result)
+		})
+	}
+}
+
+func TestSuggestSideQuestsDuplicatesDropped(t *testing.T) {
+	declined := sideQuest("The Best Homemade Chicken Tikka-Masala", "Spiced like your Chicken Fajitas.", "Chicken Fajitas")
+	oldDeclined := sideQuest("Fish Tacos!", "Tortillas like your Chicken Fajitas.", "Chicken Fajitas")
+	regular := sideQuest("Easy Beef Chili", "Just like your Beef Chili.", "Beef Chili")
+	questLog := sideQuest("Pad Thai", "Noodles like your Spaghetti Bolognese.", "Spaghetti Bolognese")
+	pending := sideQuest("Shrimp Scampi", "Pasta like your Spaghetti Bolognese.", "Spaghetti Bolognese")
+	again := sideQuest("Chicken Shawarma Bowls", "Chicken Fajitas, but Middle Eastern.", "Chicken Fajitas")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(declined, oldDeclined, regular, questLog, pending, shawarma, again)))
+	in := household
+	in.Needed = 4
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	known := "repeats a Regular, Quest log dinner, pending or passed Side quest"
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantShawarma},
+		Dropped: []DroppedSideQuest{
+			{Name: "The Best Homemade Chicken Tikka-Masala", Why: known},
+			{Name: "Fish Tacos!", Why: known},
+			{Name: "Easy Beef Chili", Why: known},
+			{Name: "Pad Thai", Why: known},
+			{Name: "Shrimp Scampi", Why: known},
+			{Name: "Chicken Shawarma Bowls", Why: `repeats the Side quest "Chicken Shawarma Bowls" in the same batch`},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonRulesDropped(t *testing.T) {
+	long := sideQuest("Beef Stroganoff", "Your Beef Chili"+strings.Repeat(" and more", 20)+".", "Beef Chili")
+	unnamed := sideQuest("Chicken Satay", "Grilled skewers with a peanut sauce.", "Chicken Fajitas")
+	wrongOne := sideQuest("Beef Tacos", "Like your Beef Chili, in a shell.", "Chicken Fajitas")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(long, unnamed, ragu, wrongOne)))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantRagu},
+		Dropped: []DroppedSideQuest{
+			{Name: "Beef Stroganoff", Why: "reason has 196 characters, over 180"},
+			{Name: "Chicken Satay", Why: "reason names none of its cited Regulars"},
+			{Name: "Beef Tacos", Why: "reason names none of its cited Regulars"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsAllDroppedIsNotRepaired(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(sideQuest("Pad Thai", "Like your Beef Chili.", "Beef Chili"))))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{},
+		Dropped:     []DroppedSideQuest{{Name: "Pad Thai", Why: "repeats a Regular, Quest log dinner, pending or passed Side quest"}},
+	})
+}
+
+func TestSuggestSideQuestsMalformedRepairedOnce(t *testing.T) {
+	for name, tc := range map[string]struct{ first, want string }{
+		"truncated JSON": {
+			`{"suggestions":[` + shawarma + `,{"name":"Beef`,
+			"reply does not decode: unexpected EOF",
+		},
+		"omitted field": {
+			batch(strings.Replace(shawarma, `"cuisine":"Fusion",`, ``, 1)),
+			`suggestion has no "cuisine" field; give every field the schema requires`,
+		},
+		"unknown field": {
+			batch(strings.Replace(shawarma, `"easy",`, `"easy","spice":"mild",`, 1)),
+			`suggestion has unknown field "spice"`,
+		},
+		"bad method": {
+			batch(strings.Replace(shawarma, `"stovetop"`, `"air fryer"`, 1)),
+			`suggestion 1 method "air fryer" is not one of stovetop, oven, crockpot, grill, other`,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var f llm.Fake
+			f.QueueGenerate(reply(tc.first), reply(batch(shawarma, ragu)))
+			out, reqs, err := suggest(t, &f, household, 2)
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu}})
+			repair := reqs[1].Messages
+			if len(repair) != 3 || repair[1].Content != tc.first {
+				t.Fatalf("repair turn does not quote the first reply: %+v", repair)
+			}
+			if !strings.Contains(repair[2].Content, tc.want) {
+				t.Fatalf("repair message = %q, want it to contain %q", repair[2].Content, tc.want)
+			}
+		})
+	}
+}
+
+func TestSuggestSideQuestsFillerNameRepaired(t *testing.T) {
+	filler := sideQuest("The.", "Like your Beef Chili.", "Beef Chili")
+	first := batch(filler, filler)
+	var f llm.Fake
+	f.QueueGenerate(reply(first), reply(batch(shawarma, ragu)))
+	out, reqs, err := suggest(t, &f, household, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu}})
+	repair := reqs[1].Messages
+	if len(repair) != 3 || repair[1].Content != first {
+		t.Fatalf("repair turn does not quote the first reply: %+v", repair)
+	}
+	for _, want := range []string{
+		`suggestion 1 name "The." has only filler words; name the dish`,
+		`suggestion 2 name "The." has only filler words; name the dish`,
+	} {
+		if !strings.Contains(repair[2].Content, want) {
+			t.Fatalf("repair message = %q, want it to contain %q", repair[2].Content, want)
+		}
+	}
+}
+
+func TestSuggestSideQuestsMalformedTwiceFails(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(`{"suggestions":`), reply(`{"suggestions":[]}`))
+	out, _, err := suggest(t, &f, household, 2)
+	var bad *harness.BadOutputError
+	if !errors.As(err, &bad) || !errors.Is(err, llm.ErrBadOutput) {
+		t.Fatalf("err = %v, want a BadOutputError", err)
+	}
+	if !slices.Equal(bad.Repair, []string{"suggestions is empty; give 4 Side quests"}) {
+		t.Fatalf("repair problems = %q", bad.Repair)
+	}
+	if out.Suggestions != nil {
+		t.Fatalf("output = %+v, want none", out)
+	}
+}
+
+func TestSideQuestsValidate(t *testing.T) {
+	s := suggestSideQuests{in: household}
+	if p := s.Validate(SideQuests{Suggestions: []SideQuest{wantShawarma}}); len(p) != 0 {
+		t.Fatalf("valid output has problems: %q", p)
+	}
+	if p := s.Validate(SideQuests{Suggestions: []SideQuest{}, Dropped: []DroppedSideQuest{{Name: "x", Why: "y"}}}); len(p) != 0 {
+		t.Fatalf("output whose Side quests were all dropped has problems: %q", p)
+	}
+	for name, tc := range map[string]struct {
+		out  SideQuests
+		want []string
+	}{
+		"empty": {SideQuests{}, []string{"suggestions is empty; give 4 Side quests"}},
+		"too many": {
+			SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu, wantVerde, wantBulgogi, wantShawarma}},
+			[]string{"suggestions has 5 entries; give at most 4 Side quests"},
+		},
+		"malformed": {
+			SideQuests{Suggestions: []SideQuest{{Name: " ", Method: "air fryer", EstMinutes: 0, Difficulty: "trivial", CitedRegulars: []string{}}}},
+			[]string{
+				"suggestion 1 has an empty name; give one",
+				"suggestion 1 has an empty cuisine; give one",
+				"suggestion 1 has an empty reason; give one",
+				"suggestion 1 has an empty search_query; give one",
+				`suggestion 1 method "air fryer" is not one of stovetop, oven, crockpot, grill, other`,
+				"suggestion 1 est_minutes 0 is not positive; give the minutes from prep to table",
+				`suggestion 1 difficulty "trivial" is not one of easy, medium, hard`,
+			},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if got := s.Validate(tc.out); !slices.Equal(got, tc.want) {
+				t.Fatalf("problems =\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(tc.want, "\n"))
+			}
+		})
+	}
+}
+
+func TestSideQuestsPromptInputRejects(t *testing.T) {
+	noRegulars := household
+	noRegulars.Context.Regulars = nil
+	none := household
+	none.Needed = 0
+	for name, tc := range map[string]struct {
+		in   SideQuestsRequest
+		want string
+	}{
+		"no Regulars": {noRegulars, "household has no Regulars for Side quests to be based on"},
+		"none needed": {none, "0 Side quests needed; the number must be positive"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := suggestSideQuests{in: tc.in}.PromptInput(tc.in)
+			if err == nil || err.Error() != tc.want {
+				t.Fatalf("err = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}

internal/ai/skills/testdata/suggest_side_quests_clean.system.golden

@@ -0,0 +1,110 @@
+## Instructions
+You suggest Side quests: new dinners for the household to try, based on the dinners it already makes.
+
+Every Side quest must be a dinner the household has not had: never one of its Regulars, its Quest log, its pending Side quests or the dinners it has passed, and never one of those under another name. Base every Side quest on one or more of the household's Regulars, such as a familiar protein in a new cuisine or familiar flavours cooked a new way. Prefer the favorite Regulars, and vary the cuisines across the batch.
+
+Give for each Side quest:
+- name: the dinner's usual name, as a recipe site would title it.
+- cuisine: its cuisine, e.g. "Thai" or "Tex-Mex".
+- method: how it is mainly cooked: "stovetop", "oven", "crockpot" (slow cooker or crock pot), "grill" or "other".
+- est_minutes: your estimate of the whole minutes from starting prep to the table.
+- difficulty: "easy", "medium" or "hard" for a home cook.
+- reason: one sentence of at most 180 characters saying why the household would like it. It must name at least one of the Regulars in cited_regulars.
+- cited_regulars: the Regulars the reason relies on, at least one, each written exactly as its name appears in the Regulars list of the household context, without the details in parentheses. Cite only Regulars from that list.
+- search_query: a web search query that finds a recipe for this dinner.
+
+One valid Side quest, for a household with a Regular named "Chicken Fajitas" (an example only, not about this household):
+{"name": "Chicken Shawarma Bowls", "cuisine": "Middle Eastern", "method": "oven", "est_minutes": 40, "difficulty": "easy", "reason": "Spiced roast chicken and crisp toppings, like your Chicken Fajitas with a Middle Eastern twist.", "cited_regulars": ["Chicken Fajitas"], "search_query": "chicken shawarma bowls recipe"}
+
+## Household context
+### Today
+- Tuesday 2026-10-06 (America/New_York)
+
+### Regulars
+- Beef Chili (Tex-Mex, crockpot, 240 min)
+- Chicken Fajitas (Tex-Mex, stovetop, 30 min, favorite)
+- Spaghetti Bolognese (Italian, stovetop, 45 min)
+
+### Quest log
+- Pad Thai
+
+### Passed, oldest first
+- Chicken Tikka Masala
+
+### Recent plans
+- 2026-10-05 Mon: Chicken Fajitas
+- 2026-10-06 Tue: Beef Chili
+
+### Pending Side quests
+- Shrimp Scampi
+
+## Output contract
+This contract overrides any earlier instruction about the form of your reply. Reply with one JSON value matching the JSON Schema "suggest_side_quests" below, and nothing else: no prose and no Markdown code fences.
+
+{
+  "type": "object",
+  "properties": {
+    "suggestions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "cuisine": {
+            "type": "string"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "stovetop",
+              "oven",
+              "crockpot",
+              "grill",
+              "other"
+            ]
+          },
+          "est_minutes": {
+            "type": "integer"
+          },
+          "difficulty": {
+            "type": "string",
+            "enum": [
+              "easy",
+              "medium",
+              "hard"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "cited_regulars": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "search_query": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "cuisine",
+          "method",
+          "est_minutes",
+          "difficulty",
+          "reason",
+          "cited_regulars",
+          "search_query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "suggestions"
+  ],
+  "additionalProperties": false
+}

internal/ai/skills/testdata/suggest_side_quests_clean.user.golden

@@ -0,0 +1 @@
+Suggest 4 Side quests.

internal/db/dinners.sql.go

@@ -503,6 +503,63 @@ func (q *Queries) ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDi
 	return items, nil
 }
 
+const listUnplannedQuestLogDinners = `-- name: ListUnplannedQuestLogDinners :many
+SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision FROM dinners
+WHERE status = 'quest_log'
+  AND NOT EXISTS (
+	SELECT 1 FROM plan_days
+	JOIN week_plans ON week_plans.id = plan_days.plan_id
+	WHERE plan_days.dinner_id = dinners.id
+	  AND week_plans.week_start >= ?1
+  )
+ORDER BY normalized_name, id
+`
+
+// The Quest log: dinners with status quest_log that no plan for the week
+// starting from_week_start or later has on any day.
+func (q *Queries) ListUnplannedQuestLogDinners(ctx context.Context, fromWeekStart string) ([]Dinner, error) {
+	rows, err := q.db.QueryContext(ctx, listUnplannedQuestLogDinners, fromWeekStart)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []Dinner
+	for rows.Next() {
+		var i Dinner
+		if err := rows.Scan(
+			&i.ID,
+			&i.Name,
+			&i.NormalizedName,
+			&i.Status,
+			&i.Origin,
+			&i.Method,
+			&i.MinutesTotal,
+			&i.Difficulty,
+			&i.Cuisine,
+			&i.IsFavorite,
+			&i.RecipeID,
+			&i.PhotoID,
+			&i.GroundingStatus,
+			&i.UpdatedBy,
+			&i.CreatedAt,
+			&i.UpdatedAt,
+			&i.RecipeUrl,
+			&i.GroundingError,
+			&i.GroundingRevision,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const setDinnerFavorite = `-- name: SetDinnerFavorite :one
 UPDATE dinners
 SET is_favorite = ?,

internal/db/household_context.sql.go

@@ -54,16 +54,16 @@ func (q *Queries) ListPlannedDinners(ctx context.Context, arg ListPlannedDinners
 
 const listRecentDeclinedNames = `-- name: ListRecentDeclinedNames :many
 
-SELECT dinners.name
+SELECT name
 FROM suggestions
-JOIN dinners ON dinners.id = suggestions.dinner_id
-WHERE suggestions.status = 'declined'
-ORDER BY suggestions.decided_at DESC, suggestions.id DESC
+WHERE status = 'declined'
+ORDER BY decided_at DESC, id DESC
 LIMIT ?
 `
 
 // Reads for the AI household context block (internal/ai/harness).
-// The names of the most recently declined suggestions, newest first.
+// The names the most recently declined suggestions were suggested under,
+// newest first; renaming their dinners does not change them.
 func (q *Queries) ListRecentDeclinedNames(ctx context.Context, limit int64) ([]string, error) {
 	rows, err := q.db.QueryContext(ctx, listRecentDeclinedNames, limit)
 	if err != nil {

internal/db/models.go

@@ -289,6 +289,7 @@ type Suggestion struct {
 	ID              string
 	DinnerID        string
 	BatchID         string
+	Name            string
 	Reason          string
 	CitedRegularIds string
 	Status          string

internal/db/querier.go

@@ -21,6 +21,8 @@ type Querier interface {
 	// Drops references to the runs created before the cutoff, so the purge
 	// can delete them.
 	ClearWeekPlanAIRunsBefore(ctx context.Context, cutoff string) (int64, error)
+	// How many suggestions ListDeck returns.
+	CountDeck(ctx context.Context) (int64, error)
 	// How many Regulars the household has; archived dinners are not counted.
 	CountRegularDinners(ctx context.Context) (int64, error)
 	CreateAIRun(ctx context.Context, arg CreateAIRunParams) error
@@ -32,6 +34,13 @@ type Querier interface {
 	CreatePhoto(ctx context.Context, arg CreatePhotoParams) (Photo, error)
 	CreateRecipeIngredient(ctx context.Context, arg CreateRecipeIngredientParams) error
 	CreateRecipeStep(ctx context.Context, arg CreateRecipeStepParams) error
+	// name is the name the dish is suggested under, kept whatever its dinner is
+	// later renamed.
+	CreateSuggestion(ctx context.Context, arg CreateSuggestionParams) error
+	CreateSuggestionBatch(ctx context.Context, arg CreateSuggestionBatchParams) (SuggestionBatch, error)
+	// Records the household's decision on a pending suggestion; one already
+	// decided is left as it is (0 rows).
+	DecideSuggestion(ctx context.Context, arg DecideSuggestionParams) (int64, error)
 	DeleteAIRunsBefore(ctx context.Context, cutoff string) (int64, error)
 	DeleteRecipeIngredients(ctx context.Context, recipeID string) error
 	DeleteRecipeSteps(ctx context.Context, recipeID string) error
@@ -42,6 +51,10 @@ type Querier interface {
 	// archived dinner is left as it is; archiving stopped its grounding. Run at
 	// boot, after the job runner fails the jobs a previous process left running.
 	FailOrphanedPendingDinnerGroundings(ctx context.Context, arg FailOrphanedPendingDinnerGroundingsParams) (int64, error)
+	// Fails every batch still pending or running whose job is no longer queued
+	// or running: the process stopped, or recording the batch's end failed,
+	// before its handler recorded a result. Run before reading the active batch.
+	FailOrphanedSuggestionBatches(ctx context.Context, arg FailOrphanedSuggestionBatchesParams) (int64, error)
 	// Records why the background grounding of an unarchived dinner still
 	// pending at the grounding_revision it was grounded for failed; a dinner
 	// grounded some other way, renamed or archived meanwhile is left as it is
@@ -49,8 +62,14 @@ type Querier interface {
 	FailPendingDinnerGrounding(ctx context.Context, arg FailPendingDinnerGroundingParams) (int64, error)
 	// Fails every job left running, at boot before any worker starts.
 	FailRunningJobs(ctx context.Context, arg FailRunningJobsParams) (int64, error)
+	// Records a pending or running batch as done or failed; a batch already
+	// finished is left as it is (0 rows).
+	FinishSuggestionBatch(ctx context.Context, arg FinishSuggestionBatchParams) (int64, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetAISettings(ctx context.Context) (AiSetting, error)
+	// The batch still pending or running, oldest first. Returns sql.ErrNoRows
+	// when there is none.
+	GetActiveSuggestionBatch(ctx context.Context) (SuggestionBatch, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetChatSettings(ctx context.Context) (ChatSetting, error)
 	GetDinner(ctx context.Context, id string) (Dinner, error)
@@ -59,6 +78,9 @@ type Querier interface {
 	// Returns sql.ErrNoRows until the row exists.
 	GetIntegrationsGoogle(ctx context.Context) (IntegrationsGoogle, error)
 	GetJob(ctx context.Context, id string) (Job, error)
+	// The newest batch, whatever its status. Returns sql.ErrNoRows when there
+	// is none.
+	GetLatestSuggestionBatch(ctx context.Context) (SuggestionBatch, error)
 	GetPhoto(ctx context.Context, id string) (Photo, error)
 	// Finds stored image bytes by content hash. The schema does not make sha256
 	// unique, so the earliest-created (lowest id) match is returned.
@@ -67,6 +89,10 @@ type Querier interface {
 	GetRecipeBySourceURL(ctx context.Context, sourceUrl string) (Recipe, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetRecipeSearchSettings(ctx context.Context) (RecipeSearchSetting, error)
+	// A suggestion with its dinner. Returns sql.ErrNoRows for an unknown id.
+	GetSuggestion(ctx context.Context, id string) (GetSuggestionRow, error)
+	// The id of the job that runs batch batch_id.
+	GetSuggestionBatchJobID(ctx context.Context, arg GetSuggestionBatchJobIDParams) (string, error)
 	// Records a dinner's grounding by hand (grounded or manual) and clears any
 	// grounding_error and pasted recipe_url: the recipe chosen replaces the
 	// link. It writes only an unarchived dinner still as it was observed
@@ -83,22 +109,39 @@ type Querier interface {
 	// them only when a member edited them while it was grounding. Like
 	// GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
 	GroundPendingDinner(ctx context.Context, arg GroundPendingDinnerParams) (int64, error)
+	// The pending suggestions whose dinner is still suggested, oldest first,
+	// with their dinners.
+	ListDeck(ctx context.Context) ([]ListDeckRow, error)
+	// The name every declined suggestion was suggested under, oldest decision
+	// first; renaming its dinner does not change it.
+	ListDeclinedSuggestionNames(ctx context.Context) ([]string, error)
 	ListDinnersByStatus(ctx context.Context, status string) ([]Dinner, error)
 	// The planned dinners dated from from_date up to but not including
 	// to_date, oldest first. Days with no dinner are left out.
 	ListPlannedDinners(ctx context.Context, arg ListPlannedDinnersParams) ([]ListPlannedDinnersRow, error)
 	// Reads for the AI household context block (internal/ai/harness).
-	// The names of the most recently declined suggestions, newest first.
+	// The names the most recently declined suggestions were suggested under,
+	// newest first; renaming their dinners does not change them.
 	ListRecentDeclinedNames(ctx context.Context, limit int64) ([]string, error)
 	ListRecipeIngredients(ctx context.Context, recipeID string) ([]RecipeIngredient, error)
 	ListRecipeSteps(ctx context.Context, recipeID string) ([]RecipeStep, error)
 	// Every dinner a new or renamed dinner must not repeat, with the
 	// source_url of the recipe it is grounded in (NULL while it has none).
 	ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDinnersRow, error)
+	// The Quest log: dinners with status quest_log that no plan for the week
+	// starting from_week_start or later has on any day.
+	ListUnplannedQuestLogDinners(ctx context.Context, fromWeekStart string) ([]Dinner, error)
+	// Moves a dinner still suggested to status (quest_log or archived),
+	// recording updated_by; a dinner no longer suggested is left as it is
+	// (0 rows).
+	MoveSuggestedDinner(ctx context.Context, arg MoveSuggestedDinnerParams) (int64, error)
 	// Stores a partial result of a running job.
 	PublishJobResult(ctx context.Context, arg PublishJobResultParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	SetDinnerFavorite(ctx context.Context, arg SetDinnerFavoriteParams) (Dinner, error)
+	// Marks a pending batch running; a batch in any other status is left as
+	// it is (0 rows).
+	StartSuggestionBatch(ctx context.Context, arg StartSuggestionBatchParams) (int64, error)
 	SucceedJob(ctx context.Context, arg SucceedJobParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	ToggleDinnerFavorite(ctx context.Context, arg ToggleDinnerFavoriteParams) (Dinner, error)

internal/db/suggestions.sql.go

@@ -0,0 +1,431 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: suggestions.sql
+
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+const countDeck = `-- name: CountDeck :one
+SELECT COUNT(*)
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested'
+`
+
+// How many suggestions ListDeck returns.
+func (q *Queries) CountDeck(ctx context.Context) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countDeck)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createSuggestion = `-- name: CreateSuggestion :exec
+INSERT INTO suggestions (
+	id, dinner_id, batch_id, name, reason, cited_regular_ids, status, created_at, updated_at
+) VALUES (
+	?, ?, ?, ?, ?, ?, 'pending', ?, ?
+)
+`
+
+type CreateSuggestionParams struct {
+	ID              string
+	DinnerID        string
+	BatchID         string
+	Name            string
+	Reason          string
+	CitedRegularIds string
+	CreatedAt       string
+	UpdatedAt       string
+}
+
+// name is the name the dish is suggested under, kept whatever its dinner is
+// later renamed.
+func (q *Queries) CreateSuggestion(ctx context.Context, arg CreateSuggestionParams) error {
+	_, err := q.db.ExecContext(ctx, createSuggestion,
+		arg.ID,
+		arg.DinnerID,
+		arg.BatchID,
+		arg.Name,
+		arg.Reason,
+		arg.CitedRegularIds,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const createSuggestionBatch = `-- name: CreateSuggestionBatch :one
+INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
+VALUES (?, ?, 'pending', ?, ?)
+RETURNING id, "trigger", status, ai_run_id, created_at, updated_at
+`
+
+type CreateSuggestionBatchParams struct {
+	ID        string
+	Trigger   string
+	CreatedAt string
+	UpdatedAt string
+}
+
+func (q *Queries) CreateSuggestionBatch(ctx context.Context, arg CreateSuggestionBatchParams) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, createSuggestionBatch,
+		arg.ID,
+		arg.Trigger,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const decideSuggestion = `-- name: DecideSuggestion :execrows
+UPDATE suggestions
+SET status = ?1, decided_at = ?2, updated_at = ?2
+WHERE id = ?3 AND status = 'pending'
+`
+
+type DecideSuggestionParams struct {
+	Status string
+	Now    sql.NullString
+	ID     string
+}
+
+// Records the household's decision on a pending suggestion; one already
+// decided is left as it is (0 rows).
+func (q *Queries) DecideSuggestion(ctx context.Context, arg DecideSuggestionParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, decideSuggestion, arg.Status, arg.Now, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const failOrphanedSuggestionBatches = `-- name: FailOrphanedSuggestionBatches :execrows
+UPDATE suggestion_batches
+SET status = 'failed', updated_at = ?1
+WHERE status IN ('pending', 'running')
+	AND NOT EXISTS (
+		SELECT 1 FROM jobs
+		WHERE jobs.kind = ?2
+			AND jobs.status IN ('queued', 'running')
+			AND json_extract(jobs.payload, '$.batch_id') = suggestion_batches.id
+	)
+`
+
+type FailOrphanedSuggestionBatchesParams struct {
+	UpdatedAt string
+	Kind      string
+}
+
+// Fails every batch still pending or running whose job is no longer queued
+// or running: the process stopped, or recording the batch's end failed,
+// before its handler recorded a result. Run before reading the active batch.
+func (q *Queries) FailOrphanedSuggestionBatches(ctx context.Context, arg FailOrphanedSuggestionBatchesParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failOrphanedSuggestionBatches, arg.UpdatedAt, arg.Kind)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const finishSuggestionBatch = `-- name: FinishSuggestionBatch :execrows
+UPDATE suggestion_batches
+SET status = ?, updated_at = ?
+WHERE id = ? AND status IN ('pending', 'running')
+`
+
+type FinishSuggestionBatchParams struct {
+	Status    string
+	UpdatedAt string
+	ID        string
+}
+
+// Records a pending or running batch as done or failed; a batch already
+// finished is left as it is (0 rows).
+func (q *Queries) FinishSuggestionBatch(ctx context.Context, arg FinishSuggestionBatchParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, finishSuggestionBatch, arg.Status, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getActiveSuggestionBatch = `-- name: GetActiveSuggestionBatch :one
+SELECT id, "trigger", status, ai_run_id, created_at, updated_at FROM suggestion_batches
+WHERE status IN ('pending', 'running')
+ORDER BY id
+LIMIT 1
+`
+
+// The batch still pending or running, oldest first. Returns sql.ErrNoRows
+// when there is none.
+func (q *Queries) GetActiveSuggestionBatch(ctx context.Context) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, getActiveSuggestionBatch)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getLatestSuggestionBatch = `-- name: GetLatestSuggestionBatch :one
+SELECT id, "trigger", status, ai_run_id, created_at, updated_at FROM suggestion_batches
+ORDER BY id DESC
+LIMIT 1
+`
+
+// The newest batch, whatever its status. Returns sql.ErrNoRows when there
+// is none.
+func (q *Queries) GetLatestSuggestionBatch(ctx context.Context) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, getLatestSuggestionBatch)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getSuggestion = `-- name: GetSuggestion :one
+SELECT suggestions.id, suggestions.dinner_id, suggestions.batch_id, suggestions.name, suggestions.reason, suggestions.cited_regular_ids, suggestions.status, suggestions.decided_at, suggestions.created_at, suggestions.updated_at, dinners.id, dinners.name, dinners.normalized_name, dinners.status, dinners.origin, dinners.method, dinners.minutes_total, dinners.difficulty, dinners.cuisine, dinners.is_favorite, dinners.recipe_id, dinners.photo_id, dinners.grounding_status, dinners.updated_by, dinners.created_at, dinners.updated_at, dinners.recipe_url, dinners.grounding_error, dinners.grounding_revision
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.id = ?
+`
+
+type GetSuggestionRow struct {
+	Suggestion Suggestion
+	Dinner     Dinner
+}
+
+// A suggestion with its dinner. Returns sql.ErrNoRows for an unknown id.
+func (q *Queries) GetSuggestion(ctx context.Context, id string) (GetSuggestionRow, error) {
+	row := q.db.QueryRowContext(ctx, getSuggestion, id)
+	var i GetSuggestionRow
+	err := row.Scan(
+		&i.Suggestion.ID,
+		&i.Suggestion.DinnerID,
+		&i.Suggestion.BatchID,
+		&i.Suggestion.Name,
+		&i.Suggestion.Reason,
+		&i.Suggestion.CitedRegularIds,
+		&i.Suggestion.Status,
+		&i.Suggestion.DecidedAt,
+		&i.Suggestion.CreatedAt,
+		&i.Suggestion.UpdatedAt,
+		&i.Dinner.ID,
+		&i.Dinner.Name,
+		&i.Dinner.NormalizedName,
+		&i.Dinner.Status,
+		&i.Dinner.Origin,
+		&i.Dinner.Method,
+		&i.Dinner.MinutesTotal,
+		&i.Dinner.Difficulty,
+		&i.Dinner.Cuisine,
+		&i.Dinner.IsFavorite,
+		&i.Dinner.RecipeID,
+		&i.Dinner.PhotoID,
+		&i.Dinner.GroundingStatus,
+		&i.Dinner.UpdatedBy,
+		&i.Dinner.CreatedAt,
+		&i.Dinner.UpdatedAt,
+		&i.Dinner.RecipeUrl,
+		&i.Dinner.GroundingError,
+		&i.Dinner.GroundingRevision,
+	)
+	return i, err
+}
+
+const getSuggestionBatchJobID = `-- name: GetSuggestionBatchJobID :one
+SELECT id FROM jobs
+WHERE kind = ?1
+	AND json_extract(payload, '$.batch_id') = ?2
+ORDER BY id
+LIMIT 1
+`
+
+type GetSuggestionBatchJobIDParams struct {
+	Kind    string
+	BatchID string
+}
+
+// The id of the job that runs batch batch_id.
+func (q *Queries) GetSuggestionBatchJobID(ctx context.Context, arg GetSuggestionBatchJobIDParams) (string, error) {
+	row := q.db.QueryRowContext(ctx, getSuggestionBatchJobID, arg.Kind, arg.BatchID)
+	var id string
+	err := row.Scan(&id)
+	return id, err
+}
+
+const listDeck = `-- name: ListDeck :many
+SELECT suggestions.id, suggestions.dinner_id, suggestions.batch_id, suggestions.name, suggestions.reason, suggestions.cited_regular_ids, suggestions.status, suggestions.decided_at, suggestions.created_at, suggestions.updated_at, dinners.id, dinners.name, dinners.normalized_name, dinners.status, dinners.origin, dinners.method, dinners.minutes_total, dinners.difficulty, dinners.cuisine, dinners.is_favorite, dinners.recipe_id, dinners.photo_id, dinners.grounding_status, dinners.updated_by, dinners.created_at, dinners.updated_at, dinners.recipe_url, dinners.grounding_error, dinners.grounding_revision
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested'
+ORDER BY suggestions.created_at, suggestions.id
+`
+
+type ListDeckRow struct {
+	Suggestion Suggestion
+	Dinner     Dinner
+}
+
+// The pending suggestions whose dinner is still suggested, oldest first,
+// with their dinners.
+func (q *Queries) ListDeck(ctx context.Context) ([]ListDeckRow, error) {
+	rows, err := q.db.QueryContext(ctx, listDeck)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListDeckRow
+	for rows.Next() {
+		var i ListDeckRow
+		if err := rows.Scan(
+			&i.Suggestion.ID,
+			&i.Suggestion.DinnerID,
+			&i.Suggestion.BatchID,
+			&i.Suggestion.Name,
+			&i.Suggestion.Reason,
+			&i.Suggestion.CitedRegularIds,
+			&i.Suggestion.Status,
+			&i.Suggestion.DecidedAt,
+			&i.Suggestion.CreatedAt,
+			&i.Suggestion.UpdatedAt,
+			&i.Dinner.ID,
+			&i.Dinner.Name,
+			&i.Dinner.NormalizedName,
+			&i.Dinner.Status,
+			&i.Dinner.Origin,
+			&i.Dinner.Method,
+			&i.Dinner.MinutesTotal,
+			&i.Dinner.Difficulty,
+			&i.Dinner.Cuisine,
+			&i.Dinner.IsFavorite,
+			&i.Dinner.RecipeID,
+			&i.Dinner.PhotoID,
+			&i.Dinner.GroundingStatus,
+			&i.Dinner.UpdatedBy,
+			&i.Dinner.CreatedAt,
+			&i.Dinner.UpdatedAt,
+			&i.Dinner.RecipeUrl,
+			&i.Dinner.GroundingError,
+			&i.Dinner.GroundingRevision,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listDeclinedSuggestionNames = `-- name: ListDeclinedSuggestionNames :many
+SELECT name
+FROM suggestions
+WHERE status = 'declined'
+ORDER BY decided_at, id
+`
+
+// The name every declined suggestion was suggested under, oldest decision
+// first; renaming its dinner does not change it.
+func (q *Queries) ListDeclinedSuggestionNames(ctx context.Context) ([]string, error) {
+	rows, err := q.db.QueryContext(ctx, listDeclinedSuggestionNames)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			return nil, err
+		}
+		items = append(items, name)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const moveSuggestedDinner = `-- name: MoveSuggestedDinner :execrows
+UPDATE dinners
+SET status = ?1, updated_by = ?2, updated_at = ?3
+WHERE id = ?4 AND status = 'suggested'
+`
+
+type MoveSuggestedDinnerParams struct {
+	Status    string
+	UpdatedBy sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// Moves a dinner still suggested to status (quest_log or archived),
+// recording updated_by; a dinner no longer suggested is left as it is
+// (0 rows).
+func (q *Queries) MoveSuggestedDinner(ctx context.Context, arg MoveSuggestedDinnerParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, moveSuggestedDinner,
+		arg.Status,
+		arg.UpdatedBy,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const startSuggestionBatch = `-- name: StartSuggestionBatch :execrows
+UPDATE suggestion_batches
+SET status = 'running', updated_at = ?
+WHERE id = ? AND status = 'pending'
+`
+
+type StartSuggestionBatchParams struct {
+	UpdatedAt string
+	ID        string
+}
+
+// Marks a pending batch running; a batch in any other status is left as
+// it is (0 rows).
+func (q *Queries) StartSuggestionBatch(ctx context.Context, arg StartSuggestionBatchParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, startSuggestionBatch, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

internal/dinners/dinners.go

@@ -17,10 +17,12 @@ import (
 	"slices"
 	"strings"
 	"sync"
+	"time"
 	"unicode/utf8"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"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/store"
@@ -287,12 +289,20 @@ func (s *Service) createRegular(ctx context.Context, r NewRegular, updatedBy str
 }
 
 // List returns the dinners with status, which must be regular or
-// quest_log, ordered by normalized name.
+// quest_log, ordered by normalized name. The Quest log is the dinners
+// accepted and not yet scheduled, so a quest_log dinner on the plan for the
+// household's current week or a later one is left out of it.
 func (s *Service) List(ctx context.Context, status string) ([]Dinner, error) {
 	if !slices.Contains(listable, status) {
 		return nil, invalid("status", "must be one of "+strings.Join(listable, ", "))
 	}
-	rows, err := db.New(s.st.Reader).ListDinnersByStatus(ctx, status)
+	var rows []db.Dinner
+	var err error
+	if status == StatusQuestLog {
+		rows, err = s.listQuestLog(ctx)
+	} else {
+		rows, err = db.New(s.st.Reader).ListDinnersByStatus(ctx, status)
+	}
 	if err != nil {
 		return nil, fmt.Errorf("dinners: list %s: %w", status, err)
 	}
@@ -303,6 +313,29 @@ func (s *Service) List(ctx context.Context, status string) ([]Dinner, error) {
 	return out, nil
 }
 
+// listQuestLog reads the Quest log in one read transaction, so the
+// household's current week and the plans come from the same snapshot.
+func (s *Service) listQuestLog(ctx context.Context) (rows []db.Dinner, err error) {
+	tx, err := s.st.Reader.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("begin read: %w", err)
+	}
+	defer func() {
+		err = errors.Join(err, tx.Rollback())
+	}()
+	q := db.New(tx)
+	settings, err := q.GetHouseholdSettings(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("read household settings: %w", err)
+	}
+	loc, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return nil, fmt.Errorf("household settings: %w", err)
+	}
+	thisWeek := household.WeekStart(household.Today(time.Now(), loc))
+	return q.ListUnplannedQuestLogDinners(ctx, thisWeek.String())
+}
+
 // Update applies p to dinner id, recording updatedBy. An invalid patch is a
 // *ValidationError and a new name repeating another unarchived dinner a
 // *DuplicateError; either changes nothing. Renaming a dinner raises its

internal/jobs/jobs.go

@@ -54,14 +54,30 @@ const (
 	CodeUnknownKind = "unknown_kind"
 )
 
-// Claim retry backoff. A worker whose claim fails with a database error
-// retries after claimRetryMin, doubling up to claimRetryMax, so a job queued
-// when the error clears is claimed without waiting for a wake token.
+// Retry backoff. A worker whose claim or final job write fails with a
+// database error retries after retryMin, doubling up to retryMax, so a job
+// queued when the error clears is claimed without waiting for a wake token,
+// and a job the worker has finished is never left running.
 const (
-	claimRetryMin = 50 * time.Millisecond
-	claimRetryMax = 5 * time.Second
+	retryMin = 50 * time.Millisecond
+	retryMax = 5 * time.Second
 )
 
+// FinalWriteTimeout bounds each attempt at a job's final write, and at a
+// handler's own last write, so a writer connection that stays busy cannot
+// hold a stopping worker, and with it shutdown, open.
+const FinalWriteTimeout = 5 * time.Second
+
+// FinalWriteContext returns the context for one attempt at a final write
+// of a job: it is not cancelled with ctx, so a job that finishes during
+// shutdown is still recorded, but it ends after FinalWriteTimeout. A
+// handler makes its own last write, the one recording what the job did,
+// with it too, and returns the error when the attempt times out, so its
+// worker can stop; the next Start fails the job as interrupted.
+func FinalWriteContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	return context.WithTimeout(context.WithoutCancel(ctx), FinalWriteTimeout)
+}
+
 // codePattern is the form of every failure code: lower-case snake case.
 var codePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{0,63}$`)
 
@@ -259,6 +275,21 @@ func (k *Kind[P]) Enqueue(ctx context.Context, payload P) (string, error) {
 	return k.r.enqueue(ctx, k.name, data)
 }
 
+// EnqueueTx stores a queued job with payload in tx and returns its id, so
+// the job exists exactly when what else tx writes does. Once tx has
+// committed, call Wake so an idle worker runs it.
+func (k *Kind[P]) EnqueueTx(ctx context.Context, tx *sql.Tx, payload P) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("jobs: enqueue %s: encode payload: %w", k.name, err)
+	}
+	return createJob(ctx, db.New(tx), k.name, data)
+}
+
+// Wake tells an idle worker to look for a job, as Enqueue does itself:
+// call it after committing the transaction a job was enqueued in.
+func (k *Kind[P]) Wake() { k.r.wakeOne() }
+
 // Enqueue stores a queued job of kind with its JSON payload and returns its
 // id, as Kind.Enqueue does for a kind known at compile time. It returns
 // ErrUnknownKind for a kind with no registered handler and
@@ -280,9 +311,20 @@ func (r *Runner) Enqueue(ctx context.Context, kind string, payload json.RawMessa
 // enqueue stores a queued job of kind with its encoded payload and wakes a
 // worker.
 func (r *Runner) enqueue(ctx context.Context, kind string, payload []byte) (string, error) {
+	id, err := createJob(ctx, db.New(r.st.Writer), kind, payload)
+	if err != nil {
+		return "", err
+	}
+	r.wakeOne()
+	return id, nil
+}
+
+// createJob stores a queued job of kind with its encoded payload through q
+// and returns its id.
+func createJob(ctx context.Context, q *db.Queries, kind string, payload []byte) (string, error) {
 	id := store.NewID()
 	now := store.Now().String()
-	if err := db.New(r.st.Writer).CreateJob(ctx, db.CreateJobParams{
+	if err := q.CreateJob(ctx, db.CreateJobParams{
 		ID:        id,
 		Kind:      kind,
 		Payload:   string(payload),
@@ -291,11 +333,15 @@ func (r *Runner) enqueue(ctx context.Context, kind string, payload []byte) (stri
 	}); err != nil {
 		return "", fmt.Errorf("jobs: enqueue %s: %w", kind, err)
 	}
+	return id, nil
+}
+
+// wakeOne gives an idle worker a token to look for a queued job.
+func (r *Runner) wakeOne() {
 	select {
 	case r.wake <- struct{}{}:
 	default: // every worker already has a token and will look again
 	}
-	return id, nil
 }
 
 // Start fails every job a previous process left running with
@@ -357,16 +403,16 @@ func (r *Runner) Get(ctx context.Context, id string) (Job, error) {
 // already queued is not stranded by a transient error.
 func (r *Runner) work(ctx context.Context) {
 	defer r.wg.Done()
-	backoff := claimRetryMin
+	backoff := retryMin
 	for ctx.Err() == nil {
 		job, err := r.claim(ctx, sql.NullString{String: store.Now().String(), Valid: true})
 		switch {
 		case err == nil:
-			backoff = claimRetryMin
+			backoff = retryMin
 			r.run(ctx, job)
 			continue
 		case errors.Is(err, sql.ErrNoRows):
-			backoff = claimRetryMin
+			backoff = retryMin
 			select {
 			case <-r.wake:
 			case <-ctx.Done():
@@ -382,7 +428,7 @@ func (r *Runner) work(ctx context.Context) {
 		case <-ctx.Done():
 			timer.Stop()
 		}
-		backoff = min(2*backoff, claimRetryMax)
+		backoff = min(2*backoff, retryMax)
 	}
 }
 
@@ -390,14 +436,13 @@ func (r *Runner) work(ctx context.Context) {
 // ctx has been cancelled, so a handler that finishes during shutdown is
 // recorded.
 func (r *Runner) run(ctx context.Context, job db.Job) {
-	write := context.WithoutCancel(ctx)
 	logger := r.logger.With("job_id", job.ID, "kind", job.Kind)
 	q := db.New(r.st.Writer)
 
 	h, ok := r.handlers[job.Kind] // read-only once started
 	if !ok {
 		logger.ErrorContext(ctx, "job failed", "code", CodeUnknownKind, "reason", "no handler registered for the kind")
-		r.fail(write, logger, job.ID, CodeUnknownKind)
+		r.fail(ctx, logger, job.ID, CodeUnknownKind)
 		return
 	}
 
@@ -419,7 +464,7 @@ func (r *Runner) run(ctx context.Context, job db.Job) {
 	result, code, reason := h.run(ctx, job.Payload, publish)
 	if code != "" {
 		if ctx.Err() != nil {
-			logger.WarnContext(write, "job interrupted by shutdown; it fails at the next start")
+			logger.WarnContext(context.WithoutCancel(ctx), "job interrupted by shutdown; it fails at the next start")
 			return
 		}
 		level := slog.LevelInfo
@@ -427,35 +472,61 @@ func (r *Runner) run(ctx context.Context, job db.Job) {
 			level = slog.LevelError
 		}
 		logger.Log(ctx, level, "job failed", "code", code, "reason", reason)
-		r.fail(write, logger, job.ID, code)
+		r.fail(ctx, logger, job.ID, code)
 		return
 	}
 
-	n, err := q.SucceedJob(write, db.SucceedJobParams{
-		Result: sql.NullString{String: string(result), Valid: true},
-		Now:    sql.NullString{String: store.Now().String(), Valid: true},
-		ID:     job.ID,
+	r.record(ctx, logger, "record job success", func(write context.Context) (int64, error) {
+		return q.SucceedJob(write, db.SucceedJobParams{
+			Result: sql.NullString{String: string(result), Valid: true},
+			Now:    sql.NullString{String: store.Now().String(), Valid: true},
+			ID:     job.ID,
+		})
 	})
-	if err == nil && n != 1 {
-		err = errors.New("job is not running")
-	}
-	if err != nil {
-		logger.ErrorContext(write, "record job success", "error", err)
-	}
 }
 
 // fail records the job as failed with code. The record errors it logs come
 // from the database, never from a handler.
 func (r *Runner) fail(ctx context.Context, logger *slog.Logger, id, code string) {
-	n, err := db.New(r.st.Writer).FailJob(ctx, db.FailJobParams{
-		Error: sql.NullString{String: code, Valid: true},
-		Now:   sql.NullString{String: store.Now().String(), Valid: true},
-		ID:    id,
+	r.record(ctx, logger, "record job failure", func(write context.Context) (int64, error) {
+		return db.New(r.st.Writer).FailJob(write, db.FailJobParams{
+			Error: sql.NullString{String: code, Valid: true},
+			Now:   sql.NullString{String: store.Now().String(), Valid: true},
+			ID:    id,
+		})
 	})
-	if err == nil && n != 1 {
-		err = errors.New("job is not running")
-	}
-	if err != nil {
-		logger.ErrorContext(ctx, "record job failure", "error", err)
+}
+
+// record makes a job's final write, which must change the one running job.
+// A database error is retried with backoff until the write lands, so a
+// worker never moves on from a job it has finished while leaving it
+// running. Each attempt is made with FinalWriteContext, so even when ctx
+// has been cancelled, and is bounded by FinalWriteTimeout; once ctx is
+// cancelled, a failed or timed-out attempt is not retried and the job
+// stays running, so the next Start fails it as interrupted.
+func (r *Runner) record(ctx context.Context, logger *slog.Logger, what string, write func(context.Context) (int64, error)) {
+	backoff := retryMin
+	for {
+		attempt, cancel := FinalWriteContext(ctx)
+		n, err := write(attempt)
+		cancel()
+		if err == nil {
+			if n != 1 {
+				logger.ErrorContext(ctx, what, "error", "job is not running")
+			}
+			return
+		}
+		if ctx.Err() != nil {
+			logger.ErrorContext(context.WithoutCancel(ctx), what+" failed during shutdown; it fails at the next start", "error", err)
+			return
+		}
+		logger.ErrorContext(ctx, what+" failed; retrying", "error", err, "retry_in", backoff)
+		timer := time.NewTimer(backoff)
+		select {
+		case <-timer.C:
+		case <-ctx.Done():
+			timer.Stop()
+		}
+		backoff = min(2*backoff, retryMax)
 	}
 }

internal/jobs/jobs_test.go

@@ -187,6 +187,46 @@ func TestJobSucceeds(t *testing.T) {
 	}
 }
 
+func TestEnqueueTxStoresJobOnlyWithItsTransaction(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	count := register(t, r, "count", func(_ context.Context, p countPayload, _ func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	start(t, r)
+	ctx := context.Background()
+
+	var rolledBack string
+	refused := errors.New("refused")
+	if err := st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		rolledBack, err = count.EnqueueTx(ctx, tx, countPayload{Steps: 1})
+		if err != nil {
+			return err
+		}
+		return refused
+	}); !errors.Is(err, refused) {
+		t.Fatalf("WithTx = %v, want the refusal", err)
+	}
+	if _, err := r.Get(ctx, rolledBack); !errors.Is(err, ErrNotFound) {
+		t.Errorf("job of a rolled-back transaction: Get = %v, want ErrNotFound", err)
+	}
+
+	var id string
+	if err := st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		id, err = count.EnqueueTx(ctx, tx, countPayload{Steps: 2})
+		return err
+	}); err != nil {
+		t.Fatal(err)
+	}
+	count.Wake()
+	if job := waitFor(t, r, id, finished); job.Status != StatusSucceeded || string(job.Result) != `{"done":2}` {
+		t.Errorf("job = %+v (result %s), want succeeded with {\"done\":2}", job, job.Result)
+	}
+}
+
 func TestJobFailsWithFailureCode(t *testing.T) {
 	t.Parallel()
 	st := migratedStore(t)
@@ -569,6 +609,98 @@ func TestClaimErrorIsRetried(t *testing.T) {
 	}
 }
 
+func TestFinalWriteErrorIsRetried(t *testing.T) {
+	st := migratedStore(t)
+	logs := &logBuffer{}
+	r := newRunnerLogging(t, st, 1, logs)
+	k := register(t, r, "count", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	if _, err := st.Writer.ExecContext(t.Context(), `CREATE TRIGGER refuse_end BEFORE UPDATE OF status ON jobs WHEN NEW.status IN ('succeeded', 'failed') BEGIN SELECT RAISE(ABORT, 'end refused'); END`); err != nil {
+		t.Fatal(err)
+	}
+	start(t, r)
+	id := enqueue(t, k, countPayload{Steps: 3})
+
+	deadline := time.Now().Add(5 * time.Second)
+	for !strings.Contains(logs.String(), "record job success") {
+		if time.Now().After(deadline) {
+			t.Fatal("job success never recorded")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if _, err := st.Writer.ExecContext(t.Context(), `DROP TRIGGER refuse_end`); err != nil {
+		t.Fatal(err)
+	}
+
+	job := waitFor(t, r, id, finished)
+	if job.Status != StatusSucceeded || string(job.Result) != `{"done":3}` {
+		t.Fatalf("job = %+v (result %s), want succeeded with {\"done\":3}", job, job.Result)
+	}
+	if out := logs.String(); !strings.Contains(out, "record job success failed; retrying") {
+		t.Fatalf("final write error not logged as retried: %s", out)
+	}
+}
+
+func TestBlockedFinalWriteDoesNotHoldShutdown(t *testing.T) {
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	started, finish := make(chan struct{}), make(chan struct{})
+	k := register(t, r, "count", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		close(started)
+		<-finish
+		return countResult{Done: p.Steps}, nil
+	})
+	stop := start(t, r)
+	id := enqueue(t, k, countPayload{Steps: 3})
+	<-started
+
+	// Hold the only writer connection, so the job's final write waits for it.
+	conn, err := st.Writer.Conn(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	waits := st.Writer.Stats().WaitCount
+	close(finish)
+	deadline := time.Now().Add(5 * time.Second)
+	for st.Writer.Stats().WaitCount == waits {
+		if time.Now().After(deadline) {
+			t.Fatal("final write never waited for the writer")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	stopped := make(chan struct{})
+	go func() {
+		stop()
+		close(stopped)
+	}()
+	// The final write's attempt ends after 5 seconds; well past that, the
+	// worker is waiting for the writer with no bound.
+	select {
+	case <-stopped:
+	case <-time.After(15 * time.Second):
+		conn.Close()
+		<-stopped
+		t.Fatal("worker waited for a held writer through shutdown")
+	}
+	if err := conn.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	if job := waitFor(t, r, id, func(Job) bool { return true }); job.Status != StatusRunning {
+		t.Fatalf("after shutdown job = %+v, want left running", job)
+	}
+	second := newRunner(t, st, 1)
+	register(t, second, "count", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, nil
+	})
+	start(t, second)
+	if job := waitFor(t, second, id, finished); job.Status != StatusFailed || job.Error == nil || *job.Error != CodeInterrupted {
+		t.Errorf("interrupted job = %+v, want failed with %q", job, CodeInterrupted)
+	}
+}
+
 func TestRunnerEnqueueByKindName(t *testing.T) {
 	t.Parallel()
 	st := migratedStore(t)

internal/server/aisettings_test.go

@@ -28,7 +28,7 @@ const (
 func newAIRouter(t *testing.T) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t),
 		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/dinners_test.go

@@ -11,9 +11,11 @@ import (
 	"sync"
 	"testing"
 	"testing/fstest"
+	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"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"
@@ -66,6 +68,10 @@ func (b *logBuffer) String() string {
 func newDinnersEnv(t *testing.T) *dinnersEnv {
 	t.Helper()
 	st := newTestStore(t)
+	// The Quest log is read against the household's current week.
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
 	e := &dinnersEnv{
 		st:     st,
 		search: &recipestest.Search{Results: map[string][]recipes.Candidate{}},
@@ -86,7 +92,7 @@ func newDinnersEnv(t *testing.T) *dinnersEnv {
 		t.Fatal(err)
 	}
 	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
-		svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		svc, newTestSuggest(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -416,6 +422,61 @@ func TestListDinnersFiltersByStatus(t *testing.T) {
 	}
 }
 
+// The Quest log leaves out a dinner on the plan for the household's current
+// week or a later one: it is scheduled already. A dinner on an earlier
+// week's plan only, or on none, is listed.
+func TestQuestLogLeavesOutPlannedDinners(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	ctx := context.Background()
+	names := []string{"Bibimbap", "Gumbo", "Pho", "Ramen", "Tagine"}
+	ids := map[string]string{}
+	for _, name := range names {
+		id := createDinner(t, router, `{"name":"`+name+`"}`)
+		if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET status = 'quest_log', origin = 'side_quest' WHERE id = ?`, id); err != nil {
+			t.Fatal(err)
+		}
+		ids[name] = id
+	}
+
+	loc, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		t.Fatal(err)
+	}
+	thisWeek := household.WeekStart(household.Today(time.Now(), loc))
+	// day is the date days after the Monday weeks after this week's.
+	day := func(weeks, days int) string {
+		y, m, d := thisWeek.Date()
+		return time.Date(y, m, d+7*weeks+days, 0, 0, 0, 0, time.UTC).Format(time.DateOnly)
+	}
+	// Gumbo is on last week's plan only; Pho on this week's; Ramen on the
+	// week after next; Tagine on last week's and this week's.
+	plan := func(weeks int, dinners ...string) {
+		t.Helper()
+		weekStart := day(weeks, 0)
+		planID := "plan-" + weekStart
+		if _, err := st.Writer.ExecContext(ctx,
+			`INSERT INTO week_plans (id, week_start, status, created_at, updated_at) VALUES (?, ?, 'draft', 't', 't')`,
+			planID, weekStart); err != nil {
+			t.Fatal(err)
+		}
+		for i, name := range dinners {
+			if _, err := st.Writer.ExecContext(ctx,
+				`INSERT INTO plan_days (id, plan_id, date, dinner_id, is_new, created_at, updated_at) VALUES (?, ?, ?, ?, 1, 't', 't')`,
+				planID+"-"+name, planID, day(weeks, i), ids[name]); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	plan(-1, "Gumbo", "Tagine")
+	plan(0, "Pho", "Tagine")
+	plan(2, "Ramen")
+
+	if got := strings.Join(listNames(t, router, "quest_log"), ","); got != "Bibimbap,Gumbo" {
+		t.Errorf("quest_log = %s, want Bibimbap,Gumbo", got)
+	}
+}
+
 func TestPatchDinner(t *testing.T) {
 	t.Parallel()
 	router, st := newDinnersRouter(t)

internal/server/login_test.go

@@ -83,7 +83,7 @@ func newLoginRouter(t *testing.T, issuer string) http.Handler {
 		t.Fatal(err)
 	}
 	r, err := NewRouter(logger, "dev", trusted, flow, sessions, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/media_test.go

@@ -51,7 +51,7 @@ func newMediaRouter(t *testing.T) (r http.Handler, id, orphan string) {
 		t.Fatal(err)
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t),
 		photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/origin_test.go

@@ -45,7 +45,7 @@ func newOriginRouter(t *testing.T, logs io.Writer) http.Handler {
 	}
 	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(logs, nil)))
 	r, err := NewRouter(logger, "dev", trusted, probeAuth{}, stubSessions{}, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/recipesearch_test.go

@@ -22,7 +22,7 @@ const (
 func newRecipeSearchRouter(t *testing.T, search *recipes.SearchSettingsService) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestDinners(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/server.go

@@ -17,6 +17,7 @@ import (
 	"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/suggest"
 )
 
 // reservedPrefixes are owned by the API router and are never answered with the
@@ -38,12 +39,14 @@ type RouteMounter interface {
 // dinnerSvc serves GET and POST /api/v1/dinners, PATCH and DELETE
 // /api/v1/dinners/{id}, POST /api/v1/dinners/{id}/favorite, GET
 // /api/v1/dinners/{id}/recipe-candidates and POST /api/v1/dinners/{id}/ground;
-// runner serves
+// suggestSvc serves POST /api/v1/suggestions/batches, GET
+// /api/v1/suggestions/deck and POST /api/v1/suggestions/{id}/accept and
+// /decline; runner serves
 // POST /api/v1/jobs and GET /api/v1/jobs/{id}; photos serves
 // GET /media/photos/{id}-{size}.jpg; assets is the web build
 // served for every other GET. /health, /auth and the web build are public.
 // Requests to /api/v1 other than GET also need the session's CSRF token in CSRFHeader.
-func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, dinnerSvc *dinners.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
+func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, dinnerSvc *dinners.Service, suggestSvc *suggest.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
 	if settings == nil {
 		return nil, errors.New("server: nil household settings service")
 	}
@@ -56,6 +59,9 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	if dinnerSvc == nil {
 		return nil, errors.New("server: nil dinners service")
 	}
+	if suggestSvc == nil {
+		return nil, errors.New("server: nil suggestions service")
+	}
 	if runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -106,6 +112,10 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	apiV1.Post("/dinners/{id}/favorite", postDinnerFavorite(logger, dinnerSvc))
 	apiV1.Get("/dinners/{id}/recipe-candidates", getDinnerCandidates(logger, dinnerSvc))
 	apiV1.Post("/dinners/{id}/ground", postDinnerGround(logger, dinnerSvc))
+	apiV1.Post("/suggestions/batches", postSuggestionBatch(logger, suggestSvc))
+	apiV1.Get("/suggestions/deck", getSuggestionDeck(logger, suggestSvc))
+	apiV1.Post("/suggestions/{id}/accept", postSuggestionDecision(logger, suggestSvc, true))
+	apiV1.Post("/suggestions/{id}/decline", postSuggestionDecision(logger, suggestSvc, false))
 	apiV1.Post("/jobs", postJob(logger, runner))
 	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	media.Get("/photos/{name}", getPhoto(logger, photos))

internal/server/server_test.go

@@ -5,6 +5,7 @@ import (
 	"crypto/rand"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"io"
 	"log/slog"
 	"maps"
@@ -18,6 +19,7 @@ import (
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
 	"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/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
@@ -25,6 +27,7 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
 
@@ -46,7 +49,7 @@ func newTestRouterWith(t *testing.T, version string, settings *household.Setting
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestDinners(t), runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -160,6 +163,28 @@ func newTestDinners(t *testing.T) *dinners.Service {
 	return svc
 }
 
+// newTestSuggest returns a suggestions service over a migrated temp
+// database, with its own unstarted job runner, a grounder that finds
+// nothing and a suggester that always fails.
+func newTestSuggest(t *testing.T) *suggest.Service {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	fail := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	svc, err := suggest.NewService(st, g, fail, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
 // newTestBox returns a secret box under a random key.
 func newTestBox(t *testing.T) *secretbox.Box {
 	t.Helper()
@@ -191,7 +216,7 @@ func TestNewRouterRequiresAISettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil AI settings service")
 	}
 }
@@ -200,7 +225,7 @@ func TestNewRouterRequiresSearchSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil recipe search settings service")
 	}
 }
@@ -209,7 +234,7 @@ func TestNewRouterRequiresPhotoFiles(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -218,7 +243,7 @@ func TestNewRouterRequiresSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
@@ -227,16 +252,25 @@ func TestNewRouterRequiresDinners(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil dinners service")
 	}
 }
 
+func TestNewRouterRequiresSuggestions(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil suggestions service")
+	}
+}
+
 func TestNewRouterRequiresJobRunner(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil job runner")
 	}
 }

internal/server/settings_test.go

@@ -277,7 +277,7 @@ func TestHouseholdSettingsWithRealSession(t *testing.T) {
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	router, err := NewRouter(logger, "dev", nil, stubAuth{}, sessions, household.NewSettingsService(st),
-		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/suggestions.go

@@ -0,0 +1,78 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+)
+
+// postSuggestionBatch starts a manual suggestion batch and answers 202 with
+// its batch_id and the job_id that GET /jobs/{id} reports on, without
+// waiting for the job. When a batch is already pending or running it
+// answers 202 with that batch instead of starting another.
+func postSuggestionBatch(logger *slog.Logger, svc *suggest.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		b, err := svc.StartBatch(r.Context(), suggest.TriggerManual)
+		if err != nil {
+			writeSuggestionError(w, r, logger, "start suggestion batch", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusAccepted, b)
+	}
+}
+
+// getSuggestionDeck answers GET /suggestions/deck with the pending
+// suggestions, oldest first, and the batch pending or running, or null.
+func getSuggestionDeck(logger *slog.Logger, svc *suggest.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		d, err := svc.Deck(r.Context())
+		if err != nil {
+			writeSuggestionError(w, r, logger, "list suggestion deck", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// postSuggestionDecision records Try it (accept) or Pass (decline) on a
+// suggestion, recording the session's actor as its dinner's updated_by.
+func postSuggestionDecision(logger *slog.Logger, svc *suggest.Service, accept bool) http.HandlerFunc {
+	decide, action := svc.Decline, "decline suggestion"
+	if accept {
+		decide, action = svc.Accept, "accept suggestion"
+	}
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := decide(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeSuggestionError(w, r, logger, action, err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// writeSuggestionError maps a suggest.Service error to its API error: an
+// unknown suggestion is 404, and a decision on one already decided the
+// other way, or whose dinner left the deck, is 409.
+func writeSuggestionError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var decided *suggest.DecidedError
+	switch {
+	case errors.As(err, &decided):
+		writeError(w, r, logger, http.StatusConflict, "suggestion_decided", decided.Error())
+	case errors.Is(err, suggest.ErrDinnerNotSuggested):
+		writeError(w, r, logger, http.StatusConflict, "dinner_not_suggested", err.Error())
+	case errors.Is(err, suggest.ErrNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "suggestion not found")
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/suggestions_test.go

@@ -0,0 +1,228 @@
+package server
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+
+	"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/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"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/internal/suggest"
+)
+
+const suggestionsPath = "/api/v1/suggestions"
+
+// newSuggestionsRouter returns a router whose suggestions service has an
+// unstarted job runner, so batches stay pending, and a deck seeded with
+// pending suggestions of dinners named names, in order, whose ids it
+// returns.
+func newSuggestionsRouter(t *testing.T, names ...string) (http.Handler, *store.Store, []string) {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	fail := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	svc, err := suggest.NewService(st, g, fail, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+		newTestDinners(t), svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	q := db.New(st.Writer)
+	ctx := t.Context()
+	now := store.Now().String()
+	batch, err := q.CreateSuggestionBatch(ctx, db.CreateSuggestionBatchParams{ID: store.NewID(), Trigger: "manual", CreatedAt: now, UpdatedAt: now})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := q.FinishSuggestionBatch(ctx, db.FinishSuggestionBatchParams{Status: "done", UpdatedAt: now, ID: batch.ID}); err != nil {
+		t.Fatal(err)
+	}
+	var ids []string
+	for i, name := range names {
+		d, err := q.CreateDinner(ctx, db.CreateDinnerParams{
+			ID: store.NewID(), Name: name, NormalizedName: harness.Normalize(name), Status: "suggested", Origin: "side_quest",
+			Difficulty: sql.NullString{String: "easy", Valid: true}, GroundingStatus: "grounded", CreatedAt: now, UpdatedAt: now,
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		id := store.NewID()
+		if err := q.CreateSuggestion(ctx, db.CreateSuggestionParams{
+			ID: id, DinnerID: d.ID, BatchID: batch.ID, Name: name, Reason: fmt.Sprintf("Reason %d", i), CitedRegularIds: "[]",
+			CreatedAt: store.Now().String(), UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+		ids = append(ids, id)
+	}
+	return h, st, ids
+}
+
+func TestSuggestionDeck(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho", "Ramen")
+
+	rec, body := callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	list, _ := body["suggestions"].([]any)
+	if len(list) != 2 {
+		t.Fatalf("deck = %v, want 2 suggestions", body)
+	}
+	for i, name := range []string{"Pho", "Ramen"} {
+		s := list[i].(map[string]any)
+		if s["id"] != ids[i] || s["name"] != name || s["difficulty"] != "easy" || s["reason"] != fmt.Sprintf("Reason %d", i) || s["status"] != "pending" {
+			t.Errorf("deck[%d] = %v, want %s", i, s, name)
+		}
+		if _, ok := s["photo_url"]; !ok {
+			t.Errorf("deck[%d] has no photo_url key", i)
+		}
+	}
+}
+
+func TestSuggestionDecisions(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho", "Ramen", "Laksa", "Bibimbap", "Katsu", "Tonkatsu", "Udon")
+
+	for _, tc := range []struct {
+		target       string
+		status       int
+		code         string
+		sugStatus    string
+		dinnerStatus string
+	}{
+		{ids[0] + "/accept", http.StatusOK, "", "accepted", "quest_log"},
+		{ids[0] + "/accept", http.StatusOK, "", "accepted", "quest_log"},
+		{ids[0] + "/decline", http.StatusConflict, "suggestion_decided", "", ""},
+		{ids[1] + "/decline", http.StatusOK, "", "declined", "archived"},
+		{ids[1] + "/decline", http.StatusOK, "", "declined", "archived"},
+		{ids[1] + "/accept", http.StatusConflict, "suggestion_decided", "", ""},
+		{"nope/accept", http.StatusNotFound, "not_found", "", ""},
+		{"nope/decline", http.StatusNotFound, "not_found", "", ""},
+	} {
+		rec, body := callDinners(t, h, http.MethodPost, suggestionsPath+"/"+tc.target, "")
+		if rec.Code != tc.status {
+			t.Fatalf("POST %s = %d, want %d: %s", tc.target, rec.Code, tc.status, rec.Body)
+		}
+		if tc.code != "" {
+			if errorCode(body) != tc.code {
+				t.Errorf("POST %s error = %v, want %s", tc.target, body, tc.code)
+			}
+			continue
+		}
+		s, _ := body["suggestion"].(map[string]any)
+		if s["status"] != tc.sugStatus || s["dinner_status"] != tc.dinnerStatus {
+			t.Errorf("POST %s = %v, want %s with dinner %s", tc.target, body, tc.sugStatus, tc.dinnerStatus)
+		}
+		if body["replenish_job_id"] != nil {
+			t.Errorf("POST %s replenished with 5 left: %v", tc.target, body["replenish_job_id"])
+		}
+	}
+
+	// A third decision leaves 4: a replenish batch starts.
+	rec, body := callDinners(t, h, http.MethodPost, suggestionsPath+"/"+ids[2]+"/decline", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("decline = %d: %s", rec.Code, rec.Body)
+	}
+	replenish, _ := body["replenish_job_id"].(string)
+	if replenish == "" {
+		t.Fatalf("decline leaving 4 = %v, want a replenish_job_id", body)
+	}
+
+	// A fourth decision joins the batch already pending and reports its job.
+	rec, body = callDinners(t, h, http.MethodPost, suggestionsPath+"/"+ids[3]+"/accept", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("accept = %d: %s", rec.Code, rec.Body)
+	}
+	if body["replenish_job_id"] != replenish {
+		t.Errorf("accept leaving 3 = %v, want replenish_job_id %s", body, replenish)
+	}
+}
+
+func TestSuggestionDeckActiveBatch(t *testing.T) {
+	t.Parallel()
+	h, _, _ := newSuggestionsRouter(t, "Pho")
+
+	rec, body := callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	if active, ok := body["active_batch"]; !ok || active != nil {
+		t.Fatalf("deck = %v, want active_batch null", body)
+	}
+	if failed, ok := body["failed_batch"]; !ok || failed != nil {
+		t.Fatalf("deck = %v, want failed_batch null", body)
+	}
+
+	rec, started := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST batches = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body = callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	active, _ := body["active_batch"].(map[string]any)
+	if active == nil || active["batch_id"] != started["batch_id"] || active["job_id"] != started["job_id"] || active["status"] != "pending" {
+		t.Errorf("deck active_batch = %v, want the started batch %v", body["active_batch"], started)
+	}
+}
+
+func TestPostSuggestionBatch(t *testing.T) {
+	t.Parallel()
+	h, st, _ := newSuggestionsRouter(t)
+
+	rec, first := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST batches = %d: %s", rec.Code, rec.Body)
+	}
+	if first["batch_id"] == nil || first["job_id"] == nil || first["trigger"] != "manual" || first["status"] != "pending" {
+		t.Errorf("POST batches = %v, want a pending manual batch with its job", first)
+	}
+	var kind string
+	if err := st.Reader.QueryRow(`SELECT kind FROM jobs WHERE id = ?`, first["job_id"]).Scan(&kind); err != nil || kind != suggest.KindSuggestionBatch {
+		t.Errorf("job kind = %q (%v), want %s", kind, err, suggest.KindSuggestionBatch)
+	}
+
+	rec, again := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted || again["batch_id"] != first["batch_id"] || again["job_id"] != first["job_id"] {
+		t.Errorf("second POST batches = %d %v, want the pending batch %v", rec.Code, again, first)
+	}
+}
+
+func TestSuggestionWritesNeedCSRF(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho")
+	for _, target := range []string{"/batches", "/" + ids[0] + "/accept", "/" + ids[0] + "/decline"} {
+		req := httptest.NewRequest(http.MethodPost, suggestionsPath+target, nil)
+		req.AddCookie(validSessionCookie)
+		rec, body := serve(t, h, req)
+		if rec.Code != http.StatusForbidden || errorCode(body) != "csrf" {
+			t.Errorf("POST %s without CSRF = %d %v, want 403 csrf", target, rec.Code, body)
+		}
+	}
+}

internal/store/migrate_test.go

@@ -3,6 +3,7 @@ package store
 import (
 	"context"
 	"io/fs"
+	"reflect"
 	"slices"
 	"strings"
 	"testing"
@@ -175,8 +176,8 @@ func TestMigrateEmbeddedMigrations(t *testing.T) {
 	if err := Migrate(context.Background(), s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name", got)
 	}
 }
 
@@ -196,8 +197,8 @@ func TestMigrateBootstrapThenEmbeddedInitApplies(t *testing.T) {
 	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name", got)
 	}
 	if !tableExists(t, s, "dinners") {
 		t.Error("table from 0001_init was not created")
@@ -557,3 +558,78 @@ func TestMigrateAIRunsStatus(t *testing.T) {
 		})
 	}
 }
+
+// TestMigrateSuggestionName upgrades a database at 0011 holding a pending
+// and a declined suggestion and checks 0012 keeps both, gives each its
+// dinner's name, and refuses a suggestion with no name.
+func TestMigrateSuggestionName(t *testing.T) {
+	ctx := context.Background()
+	s := openTestStore(t)
+	before := fstest.MapFS{}
+	for _, name := range []string{
+		"0000_bootstrap.sql", "0001_init.sql", "0002_household_settings_updated_by.sql", "0003_jobs_status.sql",
+		"0004_ai_provider_presets.sql", "0005_ai_provider_xai.sql", "0006_ai_runs_status.sql", "0007_recipe_grounding.sql",
+		"0008_dinner_recipe_url.sql", "0009_dinner_grounding_error.sql", "0010_dinner_grounding_revision.sql",
+		"0011_ground_dinner_job_revision.sql",
+	} {
+		body, err := fs.ReadFile(migrations.FS, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		before[name] = &fstest.MapFile{Data: body}
+	}
+	if err := Migrate(ctx, s.Writer, before); err != nil {
+		t.Fatal(err)
+	}
+	for _, stmt := range []string{
+		`INSERT INTO dinners (id, name, normalized_name, status, origin, is_favorite, grounding_status, created_at, updated_at)
+			VALUES ('dinner-1', 'Pho', 'pho', 'suggested', 'side_quest', 0, 'grounded', 'c', 'u'),
+			       ('dinner-2', 'Ramen', 'ramen', 'archived', 'side_quest', 0, 'grounded', 'c', 'u')`,
+		`INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
+			VALUES ('batch-1', 'manual', 'done', 'c', 'u')`,
+		`INSERT INTO suggestions (id, dinner_id, batch_id, reason, cited_regular_ids, status, decided_at, created_at, updated_at)
+			VALUES ('sugg-1', 'dinner-1', 'batch-1', 'why 1', '[]', 'pending', NULL, 'c1', 'u1'),
+			       ('sugg-2', 'dinner-2', 'batch-1', 'why 2', '["dinner-1"]', 'declined', 'd2', 'c2', 'u2')`,
+	} {
+		if _, err := s.Writer.Exec(stmt); err != nil {
+			t.Fatalf("seed: %v", err)
+		}
+	}
+
+	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := s.Reader.Query(`SELECT id, dinner_id, batch_id, name, reason, cited_regular_ids, status, COALESCE(decided_at, ''), created_at, updated_at
+		FROM suggestions ORDER BY id`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got [][]string
+	for rows.Next() {
+		r := make([]string, 10)
+		if err := rows.Scan(&r[0], &r[1], &r[2], &r[3], &r[4], &r[5], &r[6], &r[7], &r[8], &r[9]); err != nil {
+			t.Fatal(err)
+		}
+		got = append(got, r)
+	}
+	if err := rows.Close(); err != nil {
+		t.Fatal(err)
+	}
+	want := [][]string{
+		{"sugg-1", "dinner-1", "batch-1", "Pho", "why 1", "[]", "pending", "", "c1", "u1"},
+		{"sugg-2", "dinner-2", "batch-1", "Ramen", "why 2", `["dinner-1"]`, "declined", "d2", "c2", "u2"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("suggestions after 0012 =\n %v\nwant\n %v", got, want)
+	}
+	if _, err := s.Writer.Exec(`UPDATE suggestions SET name = '' WHERE id = 'sugg-1'`); err == nil || !strings.Contains(err.Error(), "CHECK constraint failed") {
+		t.Errorf("empty suggestion name: error %v, want CHECK constraint failure", err)
+	}
+	if _, err := s.Writer.Exec(`UPDATE suggestions SET dinner_id = 'nope' WHERE id = 'sugg-1'`); err == nil || !strings.Contains(err.Error(), "FOREIGN KEY constraint failed") {
+		t.Errorf("unknown dinner: error %v, want FOREIGN KEY constraint failure", err)
+	}
+	if tableExists(t, s, "suggestions_copy") {
+		t.Error("suggestions_copy left behind")
+	}
+}

internal/store/repository_test.go

@@ -95,7 +95,7 @@ func TestRepositoryInsertReadUpdate(t *testing.T) {
 			parents: []string{"dinners", "suggestion_batches"},
 			row: repoRow{"suggestions", map[string]any{
 				"id": "sugg-1", "dinner_id": "dinner-1", "batch_id": "batch-1",
-				"reason": "You make chili often.", "cited_regular_ids": `["dinner-1"]`,
+				"name": "White Chicken Chili", "reason": "You make chili often.", "cited_regular_ids": `["dinner-1"]`,
 				"status": "pending", "decided_at": nil,
 				"created_at": repoTime, "updated_at": repoTime,
 			}},

internal/store/schema_test.go

@@ -110,6 +110,7 @@ func testRow(table string, i int) map[string]any {
 	case "suggestions":
 		r["dinner_id"] = rowID("dinners", 0)
 		r["batch_id"] = rowID("suggestion_batches", 0)
+		r["name"] = fmt.Sprintf("Side quest %d", i)
 		r["reason"] = "Like your chili."
 		r["cited_regular_ids"] = "[]"
 		r["status"] = "pending"

internal/suggest/batch.go

@@ -0,0 +1,309 @@
+package suggest
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"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/db"
+	"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"
+)
+
+// BatchJob is the KindSuggestionBatch payload: the batch to run.
+type BatchJob struct {
+	BatchID string `json:"batch_id"`
+}
+
+// Batch stages, as the job's result reports them.
+const (
+	StageSuggesting = "suggesting"
+	StageGrounding  = "grounding"
+	StageDone       = "done"
+)
+
+// batchResult is the KindSuggestionBatch result, published as the batch
+// goes: its stage, the suggestions stored so far, and how many Side
+// quests were dropped, by suggest_side_quests' rules, because no recipe
+// grounds them, or because they repeat a dinner added meanwhile.
+type batchResult struct {
+	BatchID       string   `json:"batch_id"`
+	Stage         string   `json:"stage"`
+	SuggestionIDs []string `json:"suggestion_ids"`
+	Dropped       int      `json:"dropped"`
+}
+
+func (r batchResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// runBatch runs batch p.BatchID: it asks suggest_side_quests for BatchSize
+// Side quests given the household context, the deck and every declined
+// name, then grounds them in the model's order, at most the number still
+// wanted at a time, until BatchSize are kept or none are left. A Side quest
+// no recipe grounds is dropped; any other grounding failure fails the
+// batch, as does suggest_side_quests failing, with no Side quest made up
+// instead. Each round's grounded Side quests are stored before the next
+// round starts, so the deck fills as the batch goes. The batch ends done
+// or failed; Side quests stored before a failure stay in the deck. When
+// recording the batch's end fails, so does the job; when it times out at
+// shutdown, the job is left running and the batch with it, for the next
+// start to fail.
+func (s *Service) runBatch(ctx context.Context, p BatchJob, publish func(batchResult) error) (batchResult, error) {
+	n, err := db.New(s.st.Writer).StartSuggestionBatch(ctx, db.StartSuggestionBatchParams{
+		UpdatedAt: store.Now().String(),
+		ID:        p.BatchID,
+	})
+	if err != nil {
+		return batchResult{}, fmt.Errorf("suggest: start batch %s: %w", p.BatchID, err)
+	}
+	if n == 0 {
+		return batchResult{}, fmt.Errorf("suggest: batch %s is not pending", p.BatchID)
+	}
+	res, err := s.fill(ctx, p.BatchID, publish)
+	if err == nil {
+		if err := s.finishBatch(ctx, p.BatchID, BatchDone); err != nil {
+			return batchResult{}, err
+		}
+		return res, nil
+	}
+	finishErr := s.finishBatch(ctx, p.BatchID, BatchFailed)
+	if ctx.Err() != nil {
+		return batchResult{}, errors.Join(ctx.Err(), finishErr)
+	}
+	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.
+		s.logger.InfoContext(ctx, "suggestion batch failed", "batch_id", p.BatchID, "reason", failure.Code)
+	}
+	return batchResult{}, errors.Join(err, finishErr)
+}
+
+// fill does runBatch's work, returning a *jobs.Failure for a failure the
+// household may see.
+func (s *Service) fill(ctx context.Context, batchID string, publish func(batchResult) error) (batchResult, error) {
+	res := batchResult{BatchID: batchID, Stage: StageSuggesting, SuggestionIDs: []string{}}
+	if err := publish(res); err != nil {
+		return batchResult{}, err
+	}
+	in, err := s.request(ctx)
+	if err != nil {
+		return batchResult{}, err
+	}
+	out, err := s.suggest(ctx, batchID, in)
+	if err != nil {
+		if ctx.Err() != nil {
+			return batchResult{}, ctx.Err()
+		}
+		return batchResult{}, &jobs.Failure{Code: ReasonAIFailed}
+	}
+	res.Stage = StageGrounding
+	res.Dropped = len(out.Dropped)
+	if err := publish(res); err != nil {
+		return batchResult{}, err
+	}
+	left := out.Suggestions
+	for len(res.SuggestionIDs) < BatchSize && len(left) > 0 {
+		round := left[:min(BatchSize-len(res.SuggestionIDs), len(left))]
+		left = left[len(round):]
+		grounded, err := s.ground(ctx, round)
+		if err != nil {
+			return batchResult{}, err
+		}
+		res.Dropped += len(round) - len(grounded)
+		ids, err := s.store(ctx, batchID, grounded)
+		if err != nil {
+			return batchResult{}, err
+		}
+		res.Dropped += len(grounded) - len(ids)
+		res.SuggestionIDs = append(res.SuggestionIDs, ids...)
+		if err := publish(res); err != nil {
+			return batchResult{}, err
+		}
+	}
+	res.Stage = StageDone
+	return res, nil
+}
+
+// request reads what suggest_side_quests is given: the household context,
+// the deck's names and every declined name. A household with no Regulars
+// fails with ReasonNoRegulars.
+func (s *Service) request(ctx context.Context) (skills.SideQuestsRequest, error) {
+	hctx, err := harness.BuildContext(ctx, s.st, time.Now(), ContextBudget)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: %w", err)
+	}
+	if len(hctx.Regulars) == 0 {
+		return skills.SideQuestsRequest{}, &jobs.Failure{Code: ReasonNoRegulars}
+	}
+	q := db.New(s.st.Reader)
+	deck, err := q.ListDeck(ctx)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: list deck: %w", err)
+	}
+	pending := []string{}
+	for _, row := range deck {
+		pending = append(pending, row.Dinner.Name)
+	}
+	declined, err := q.ListDeclinedSuggestionNames(ctx)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: list declined names: %w", err)
+	}
+	return skills.SideQuestsRequest{Context: hctx, Needed: BatchSize, Pending: pending, Declined: declined}, nil
+}
+
+// groundedQuest is a Side quest with the recipe that grounds it.
+type groundedQuest struct {
+	quest    skills.SideQuest
+	grounded recipes.Grounded
+}
+
+// ground grounds quests by their search queries and returns those a
+// recipe grounds, in order. A Side quest no recipe grounds is left out;
+// any other failure fails the batch.
+func (s *Service) ground(ctx context.Context, quests []skills.SideQuest) ([]groundedQuest, error) {
+	reqs := make([]recipes.GroundRequest, len(quests))
+	for i, q := range quests {
+		reqs[i] = recipes.GroundRequest{DishName: q.Name, Query: q.SearchQuery}
+	}
+	results := s.grounder.GroundMany(ctx, reqs)
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	var out []groundedQuest
+	for i, r := range results {
+		var ungroundable *recipes.ErrUngroundable
+		switch {
+		case r.Err == nil:
+			out = append(out, groundedQuest{quest: quests[i], grounded: r.Grounded})
+		case errors.As(r.Err, &ungroundable):
+		case errors.Is(r.Err, recipes.ErrSearchNotConfigured):
+			return nil, &jobs.Failure{Code: ReasonSearchNotConfigured}
+		case errors.Is(r.Err, recipes.ErrSearchFailed):
+			return nil, &jobs.Failure{Code: ReasonSearchFailed}
+		case errors.Is(r.Err, recipes.ErrNormalizeFailed):
+			return nil, &jobs.Failure{Code: ReasonAIFailed}
+		default:
+			return nil, fmt.Errorf("suggest: ground %q: %w", quests[i].Name, r.Err)
+		}
+	}
+	return out, nil
+}
+
+// store stores each grounded Side quest of batchID as a dinner with status
+// suggested and origin side_quest, grounded in its recipe, and a pending
+// suggestion citing its Regulars by id, all in one transaction, and
+// returns the suggestion ids. A Side quest is left out when, since
+// suggest_side_quests ran, a dinner it repeats was added, a suggestion it
+// repeats passed, or a Regular it cites renamed or archived. Declined
+// names are read in the same transaction as the store, so a Pass committed
+// before it is never missed.
+func (s *Service) store(ctx context.Context, batchID string, quests []groundedQuest) ([]string, error) {
+	ids := []string{}
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		existing, err := q.ListUnarchivedDinners(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list dinners for dedupe: %w", err)
+		}
+		names, err := q.ListDeclinedSuggestionNames(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list declined names for dedupe: %w", err)
+		}
+		regulars := map[string][]string{}
+		for _, row := range existing {
+			names = append(names, row.Dinner.Name)
+			if row.Dinner.Status == dinners.StatusRegular {
+				regulars[row.Dinner.Name] = append(regulars[row.Dinner.Name], row.Dinner.ID)
+			}
+		}
+		for _, gq := range quests {
+			cited, ok := citedIDs(gq.quest.CitedRegulars, regulars)
+			if !ok || repeats(gq.quest.Name, names) {
+				s.logger.InfoContext(ctx, "suggested dinner dropped: changed while grounding", "batch_id", batchID)
+				continue
+			}
+			citedJSON, err := json.Marshal(cited)
+			if err != nil {
+				return fmt.Errorf("suggest: encode cited Regulars: %w", err)
+			}
+			now := store.Now().String()
+			gr := gq.grounded
+			d, err := q.CreateDinner(ctx, db.CreateDinnerParams{
+				ID:              store.NewID(),
+				Name:            gq.quest.Name,
+				NormalizedName:  harness.Normalize(gq.quest.Name),
+				Status:          dinners.StatusSuggested,
+				Origin:          "side_quest",
+				Method:          sql.NullString{String: gr.Method, Valid: true},
+				MinutesTotal:    nullInt(gr.MinutesTotal),
+				Difficulty:      sql.NullString{String: gr.Difficulty, Valid: true},
+				Cuisine:         sql.NullString{String: gq.quest.Cuisine, Valid: true},
+				RecipeID:        sql.NullString{String: gr.RecipeID, Valid: true},
+				PhotoID:         sql.NullString{String: gr.PhotoID, Valid: true},
+				GroundingStatus: dinners.GroundingGrounded,
+				CreatedAt:       now,
+				UpdatedAt:       now,
+			})
+			if err != nil {
+				return fmt.Errorf("suggest: create dinner: %w", err)
+			}
+			id := store.NewID()
+			if err := q.CreateSuggestion(ctx, db.CreateSuggestionParams{
+				ID:              id,
+				DinnerID:        d.ID,
+				BatchID:         batchID,
+				Name:            d.Name,
+				Reason:          gq.quest.Reason,
+				CitedRegularIds: string(citedJSON),
+				CreatedAt:       now,
+				UpdatedAt:       now,
+			}); err != nil {
+				return fmt.Errorf("suggest: create suggestion: %w", err)
+			}
+			names = append(names, d.Name)
+			ids = append(ids, id)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+// citedIDs returns the ids of the Regulars named cited, false when one
+// names no Regular or more than one.
+func citedIDs(cited []string, regulars map[string][]string) ([]string, bool) {
+	ids := make([]string, len(cited))
+	for i, name := range cited {
+		if len(regulars[name]) != 1 {
+			return nil, false
+		}
+		ids[i] = regulars[name][0]
+	}
+	return ids, true
+}
+
+// repeats reports whether name is harness.Similar to any of names.
+func repeats(name string, names []string) bool {
+	for _, n := range names {
+		if harness.Similar(name, n) {
+			return true
+		}
+	}
+	return false
+}
+
+func nullInt(v *int) sql.NullInt64 {
+	if v == nil {
+		return sql.NullInt64{}
+	}
+	return sql.NullInt64{Int64: int64(*v), Valid: true}
+}

internal/suggest/suggest.go

@@ -0,0 +1,482 @@
+// Package suggest keeps the household's Side quest deck: batches of new
+// dinners the AI suggests, each grounded in a recipe, and the household's
+// Try it / Pass decision on each. A batch runs as a job: suggest_side_quests
+// proposes Side quests, each is grounded with the recipe grounding pipeline
+// (dropping those no recipe grounds), and every one kept is stored as a
+// dinner with status suggested and origin side_quest and a pending
+// suggestion. Only one batch is pending or running at a time.
+package suggest
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"slices"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"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"
+)
+
+// KindSuggestionBatch is the job that runs a suggestion batch.
+const KindSuggestionBatch = "suggestion_batch"
+
+const (
+	// BatchSize is how many Side quests a batch keeps at most.
+	BatchSize = 5
+	// ReplenishBelow is the deck size under which a decision starts a
+	// replenish batch.
+	ReplenishBelow = 5
+	// ContextBudget is the character budget of the household context
+	// suggest_side_quests is given (see harness.BuildContext).
+	ContextBudget = 16000
+)
+
+// Batch triggers (the suggestion_batches.trigger column).
+const (
+	TriggerScheduled = "scheduled"
+	TriggerManual    = "manual"
+	TriggerReplenish = "replenish"
+)
+
+// Batch statuses (the suggestion_batches.status column).
+const (
+	BatchPending = "pending"
+	BatchRunning = "running"
+	BatchDone    = "done"
+	BatchFailed  = "failed"
+)
+
+// Suggestion statuses (the suggestions.status column).
+const (
+	StatusPending  = "pending"
+	StatusAccepted = "accepted"
+	StatusDeclined = "declined"
+)
+
+// Reasons a batch failed, stored as the KindSuggestionBatch job's failure
+// code. Any other failure, such as the database's, is the runner's
+// internal_error.
+const (
+	// ReasonNoRegulars: the household has no Regulars for Side quests to
+	// be based on.
+	ReasonNoRegulars = "no_regulars"
+	// ReasonAIFailed: suggest_side_quests, or normalize_recipe while
+	// grounding, failed; no Side quest 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"
+)
+
+// Reasons are every batch failure reason.
+var Reasons = []string{ReasonNoRegulars, ReasonAIFailed, ReasonSearchNotConfigured, ReasonSearchFailed}
+
+var triggers = []string{TriggerScheduled, TriggerManual, TriggerReplenish}
+
+// ErrNotFound is returned for an unknown suggestion id.
+var ErrNotFound = errors.New("suggestion not found")
+
+// ErrDinnerNotSuggested is a decision on a pending suggestion whose dinner
+// was archived or moved out of the deck some other way.
+var ErrDinnerNotSuggested = errors.New("the suggestion's dinner is no longer suggested")
+
+// DecidedError is a decision on a suggestion already decided the other
+// way.
+type DecidedError struct {
+	// Status is the suggestion's decision: accepted or declined.
+	Status string
+}
+
+func (e *DecidedError) Error() string {
+	return "the suggestion was already " + e.Status
+}
+
+// Suggester runs suggest_side_quests on in; scope names the batch. In
+// production it is skills.SuggestSideQuests with the household's
+// harness.Config.
+type Suggester func(ctx context.Context, scope string, in skills.SideQuestsRequest) (skills.SideQuests, error)
+
+// Service runs suggestion batches and records decisions.
+type Service struct {
+	st       *store.Store
+	grounder *recipes.Grounder
+	suggest  Suggester
+	logger   *slog.Logger
+	batchJob *jobs.Kind[BatchJob]
+}
+
+// NewService returns a service over st that suggests with suggest, grounds
+// with grounder and registers the KindSuggestionBatch job on runner, which
+// must not have started yet.
+func NewService(st *store.Store, grounder *recipes.Grounder, suggest Suggester, runner *jobs.Runner, logger *slog.Logger) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("suggest: nil store")
+	case grounder == nil:
+		return nil, errors.New("suggest: nil grounder")
+	case suggest == nil:
+		return nil, errors.New("suggest: nil suggester")
+	case runner == nil:
+		return nil, errors.New("suggest: nil job runner")
+	case logger == nil:
+		return nil, errors.New("suggest: nil logger")
+	}
+	s := &Service{st: st, grounder: grounder, suggest: suggest, logger: logger}
+	kind, err := jobs.Register(runner, KindSuggestionBatch, s.runBatch, Reasons...)
+	if err != nil {
+		return nil, err
+	}
+	s.batchJob = kind
+	return s, nil
+}
+
+// Batch is a suggestion batch with the id of the job running it.
+type Batch struct {
+	ID      string `json:"batch_id"`
+	JobID   string `json:"job_id"`
+	Trigger string `json:"trigger"`
+	Status  string `json:"status"`
+	// Created says whether this call created the batch rather than found
+	// it already pending or running.
+	Created bool `json:"-"`
+}
+
+// StartBatch creates a batch with trigger and enqueues the
+// KindSuggestionBatch job that runs it, unless a batch is already pending
+// or running, which it returns instead with Created false.
+func (s *Service) StartBatch(ctx context.Context, trigger string) (Batch, error) {
+	if !slices.Contains(triggers, trigger) {
+		return Batch{}, fmt.Errorf("suggest: unknown batch trigger %q", trigger)
+	}
+	var b Batch
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		b, err = s.startBatch(ctx, tx, trigger)
+		return err
+	})
+	if err != nil {
+		return Batch{}, err
+	}
+	if b.Created {
+		s.batchJob.Wake()
+	}
+	return b, nil
+}
+
+// activeBatch returns the batch pending or running in q's transaction, or
+// nil when there is none. A batch still pending or running whose job is no
+// longer queued or running is failed first, so a batch whose job ended
+// without recording its end (the process stopped, or the write failed) is
+// never reported as active and never blocks a later one.
+func (s *Service) activeBatch(ctx context.Context, q *db.Queries) (*Batch, error) {
+	n, err := q.FailOrphanedSuggestionBatches(ctx, db.FailOrphanedSuggestionBatchesParams{
+		UpdatedAt: store.Now().String(),
+		Kind:      KindSuggestionBatch,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: fail orphaned batches: %w", err)
+	}
+	if n > 0 {
+		s.logger.WarnContext(ctx, "failed suggestion batches whose job ended", "count", n)
+	}
+	cur, err := q.GetActiveSuggestionBatch(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read active batch: %w", err)
+	}
+	jobID, err := q.GetSuggestionBatchJobID(ctx, db.GetSuggestionBatchJobIDParams{Kind: KindSuggestionBatch, BatchID: cur.ID})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read job of batch %s: %w", cur.ID, err)
+	}
+	return &Batch{ID: cur.ID, JobID: jobID, Trigger: cur.Trigger, Status: cur.Status}, nil
+}
+
+// failedBatch returns the newest batch in q's transaction when it failed,
+// or nil when it did not or there is none: a later batch, done or under
+// way, supersedes an earlier failure. Run after activeBatch, so a batch
+// whose job ended without recording its end reads as failed.
+func failedBatch(ctx context.Context, q *db.Queries) (*Batch, error) {
+	cur, err := q.GetLatestSuggestionBatch(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read latest batch: %w", err)
+	}
+	if cur.Status != BatchFailed {
+		return nil, nil
+	}
+	jobID, err := q.GetSuggestionBatchJobID(ctx, db.GetSuggestionBatchJobIDParams{Kind: KindSuggestionBatch, BatchID: cur.ID})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read job of batch %s: %w", cur.ID, err)
+	}
+	return &Batch{ID: cur.ID, JobID: jobID, Trigger: cur.Trigger, Status: cur.Status}, nil
+}
+
+// startBatch does StartBatch's work in tx: the batch and the job that runs
+// it are committed together, so a batch is never seen without its job. The
+// caller wakes the job runner once tx has committed and Created is true.
+func (s *Service) startBatch(ctx context.Context, tx *sql.Tx, trigger string) (Batch, error) {
+	q := db.New(tx)
+	cur, err := s.activeBatch(ctx, q)
+	if err != nil {
+		return Batch{}, err
+	}
+	if cur != nil {
+		return *cur, nil
+	}
+	now := store.Now().String()
+	row, err := q.CreateSuggestionBatch(ctx, db.CreateSuggestionBatchParams{
+		ID:        store.NewID(),
+		Trigger:   trigger,
+		CreatedAt: now,
+		UpdatedAt: now,
+	})
+	if err != nil {
+		return Batch{}, fmt.Errorf("suggest: create batch: %w", err)
+	}
+	jobID, err := s.batchJob.EnqueueTx(ctx, tx, BatchJob{BatchID: row.ID})
+	if err != nil {
+		return Batch{}, fmt.Errorf("suggest: enqueue batch %s: %w", row.ID, err)
+	}
+	return Batch{ID: row.ID, JobID: jobID, Trigger: row.Trigger, Status: row.Status, Created: true}, nil
+}
+
+// finishBatch records running batch id as status, with
+// jobs.FinalWriteContext: the write is made even when ctx has been
+// cancelled, but a writer that stays busy cannot hold its worker past
+// jobs.FinalWriteTimeout. Its job's handler returns any error, so the job
+// never ends succeeded with the batch still running; the runner keeps only
+// a code, so the error is logged too.
+func (s *Service) finishBatch(ctx context.Context, id, status string) error {
+	write, cancel := jobs.FinalWriteContext(ctx)
+	defer cancel()
+	n, err := db.New(s.st.Writer).FinishSuggestionBatch(write, db.FinishSuggestionBatchParams{
+		Status:    status,
+		UpdatedAt: store.Now().String(),
+		ID:        id,
+	})
+	if err == nil && n != 1 {
+		err = errors.New("batch is not running")
+	}
+	if err != nil {
+		s.logger.ErrorContext(ctx, "record suggestion batch status", "batch_id", id, "status", status, "error", err)
+		return fmt.Errorf("suggest: record batch %s %s: %w", id, status, err)
+	}
+	return nil
+}
+
+// Suggestion is a Side quest suggestion as the API shows it, with its
+// dinner.
+type Suggestion struct {
+	ID           string  `json:"id"`
+	DinnerID     string  `json:"dinner_id"`
+	Name         string  `json:"name"`
+	PhotoURL     *string `json:"photo_url"`
+	Difficulty   *string `json:"difficulty"`
+	Method       *string `json:"method"`
+	MinutesTotal *int64  `json:"minutes_total"`
+	Cuisine      *string `json:"cuisine"`
+	// Reason is the "Why this?".
+	Reason          string   `json:"reason"`
+	CitedRegularIDs []string `json:"cited_regular_ids"`
+	Status          string   `json:"status"`
+	DinnerStatus    string   `json:"dinner_status"`
+	DecidedAt       *string  `json:"decided_at"`
+	CreatedAt       string   `json:"created_at"`
+}
+
+// Deck is the household's deck: the pending suggestions whose dinner is
+// still suggested, oldest first; the batch pending or running, if any, so
+// a client can follow the job producing more; and the newest batch when it
+// failed, so a client that was not following its job still learns of the
+// failure. At most one of ActiveBatch and FailedBatch is set: a batch is
+// only started when none is pending or running, so the active batch is
+// always the newest.
+type Deck struct {
+	Suggestions []Suggestion `json:"suggestions"`
+	ActiveBatch *Batch       `json:"active_batch"`
+	FailedBatch *Batch       `json:"failed_batch"`
+}
+
+// Deck reads the deck and its active and failed batches in one
+// transaction, so all come from the same snapshot. It is a write
+// transaction because reading the active batch first fails any batch whose
+// job has ended (see activeBatch), which is then the failed batch.
+func (s *Service) Deck(ctx context.Context) (Deck, error) {
+	var deck Deck
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		rows, err := q.ListDeck(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list deck: %w", err)
+		}
+		deck.Suggestions = make([]Suggestion, len(rows))
+		for i, row := range rows {
+			deck.Suggestions[i], err = fromRow(row.Suggestion, row.Dinner)
+			if err != nil {
+				return err
+			}
+		}
+		deck.ActiveBatch, err = s.activeBatch(ctx, q)
+		if err != nil || deck.ActiveBatch != nil {
+			return err
+		}
+		deck.FailedBatch, err = failedBatch(ctx, q)
+		return err
+	})
+	if err != nil {
+		return Deck{}, err
+	}
+	return deck, nil
+}
+
+// Decision is a suggestion once decided, with the id of the replenish
+// batch's job when the decision called for one: the batch it started, or
+// the one already pending or running that it joined.
+type Decision struct {
+	Suggestion     Suggestion `json:"suggestion"`
+	ReplenishJobID *string    `json:"replenish_job_id"`
+}
+
+// Accept records Try it on suggestion id, moving its dinner to the Quest
+// log and recording updatedBy on it.
+func (s *Service) Accept(ctx context.Context, id, updatedBy string) (Decision, error) {
+	return s.decide(ctx, id, StatusAccepted, dinners.StatusQuestLog, updatedBy)
+}
+
+// Decline records Pass on suggestion id, archiving its dinner and
+// recording updatedBy on it. The suggestion keeps the name its dish was
+// suggested under, whatever the dinner is later renamed, and every later
+// batch reads it as declined, so the dish is never suggested again.
+func (s *Service) Decline(ctx context.Context, id, updatedBy string) (Decision, error) {
+	return s.decide(ctx, id, StatusDeclined, dinners.StatusArchived, updatedBy)
+}
+
+// decide records decision on suggestion id and moves its dinner to
+// dinnerStatus. Repeating a decision changes nothing and returns the
+// suggestion as it is; the opposite decision is a *DecidedError. A
+// decision that leaves the deck under ReplenishBelow starts a replenish
+// batch, or joins the one already pending or running, in the decision's own
+// transaction, and returns its job id either way: the decision is never recorded without the replenish it
+// calls for, and a failure to start the batch records neither.
+func (s *Service) decide(ctx context.Context, id, decision, dinnerStatus, updatedBy string) (Decision, error) {
+	if updatedBy == "" {
+		return Decision{}, errors.New("suggest: decide: no member to record as updated_by")
+	}
+	var row db.GetSuggestionRow
+	var replenish *Batch
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetSuggestion(ctx, id)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("suggest: read suggestion %s: %w", id, err)
+		}
+		switch cur.Suggestion.Status {
+		case decision:
+			row = cur
+			return nil
+		case StatusPending:
+		default:
+			return &DecidedError{Status: cur.Suggestion.Status}
+		}
+		if cur.Dinner.Status != dinners.StatusSuggested {
+			return ErrDinnerNotSuggested
+		}
+		now := store.Now().String()
+		if _, err := q.DecideSuggestion(ctx, db.DecideSuggestionParams{
+			Status: decision,
+			Now:    sql.NullString{String: now, Valid: true},
+			ID:     id,
+		}); err != nil {
+			return fmt.Errorf("suggest: decide %s: %w", id, err)
+		}
+		if _, err := q.MoveSuggestedDinner(ctx, db.MoveSuggestedDinnerParams{
+			Status:    dinnerStatus,
+			UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+			UpdatedAt: now,
+			ID:        cur.Dinner.ID,
+		}); err != nil {
+			return fmt.Errorf("suggest: move dinner %s: %w", cur.Dinner.ID, err)
+		}
+		row, err = q.GetSuggestion(ctx, id)
+		if err != nil {
+			return fmt.Errorf("suggest: read suggestion %s: %w", id, err)
+		}
+		left, err := q.CountDeck(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: count deck: %w", err)
+		}
+		if left >= ReplenishBelow {
+			return nil
+		}
+		b, err := s.startBatch(ctx, tx, TriggerReplenish)
+		if err != nil {
+			return err
+		}
+		replenish = &b
+		return nil
+	})
+	if err != nil {
+		return Decision{}, err
+	}
+	if replenish != nil && replenish.Created {
+		s.batchJob.Wake()
+	}
+	sug, err := fromRow(row.Suggestion, row.Dinner)
+	if err != nil {
+		return Decision{}, err
+	}
+	d := Decision{Suggestion: sug}
+	if replenish != nil {
+		d.ReplenishJobID = &replenish.JobID
+	}
+	return d, nil
+}
+
+func fromRow(sg db.Suggestion, d db.Dinner) (Suggestion, error) {
+	out := Suggestion{
+		ID:           sg.ID,
+		DinnerID:     d.ID,
+		Name:         d.Name,
+		Difficulty:   nullString(d.Difficulty),
+		Method:       nullString(d.Method),
+		Cuisine:      nullString(d.Cuisine),
+		Reason:       sg.Reason,
+		Status:       sg.Status,
+		DinnerStatus: d.Status,
+		DecidedAt:    nullString(sg.DecidedAt),
+		CreatedAt:    sg.CreatedAt,
+	}
+	if err := json.Unmarshal([]byte(sg.CitedRegularIds), &out.CitedRegularIDs); err != nil || out.CitedRegularIDs == nil {
+		return Suggestion{}, fmt.Errorf("suggest: suggestion %s cited_regular_ids is not a JSON array: %q", sg.ID, sg.CitedRegularIds)
+	}
+	if d.MinutesTotal.Valid {
+		out.MinutesTotal = &d.MinutesTotal.Int64
+	}
+	if d.PhotoID.Valid {
+		u := dinners.PhotoURL(d.PhotoID.String)
+		out.PhotoURL = &u
+	}
+	return out, nil
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}