Enforce unique recipe item positions per recipe (Maestro 75bb8cc1) (#198)

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

docs/ARCHITECTURE.md

@@ -95,8 +95,8 @@ Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
 | --- | --- |
 | `household_settings` | One row: timezone, dinner_time (17:30), reminder_time (16:30), review_time (09:00), plan_draft day/time (Fri 09:00), suggestions day/time (Sun 08:00), chat_autosend day/time (Sat 08:00), onboarding_completed_at, updates_seen_at. |
 | `recipes` | A real recipe page: source_url (unique), site_name, title, total/prep/cook minutes (the page's JSON-LD), yield, raw_jsonld, fetched_at; and its grounding: photo_id, method, difficulty, minutes_total (normalized prep to table). |
-| `recipe_ingredients` | recipe_id, position, raw_text, name, qty, unit, note. |
-| `recipe_steps` | recipe_id, position, text. |
+| `recipe_ingredients` | recipe_id, position (unique per recipe: the recipe order), raw_text, name, qty, unit, note. |
+| `recipe_steps` | recipe_id, position (unique per recipe: the recipe order), text. |
 | `photos` | source_url, local_path, width, height, sha256, fetched_at. |
 | `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, recipe_url (a pasted recipe link awaiting grounding), photo_id, grounding_status (`pending` / `grounded` / `failed` / `manual`), grounding_error (why grounding failed), grounding_revision (raised whenever a dinner is renamed, so only the latest `ground_dinner` job may write it and no candidate offered before the rename grounds it), updated_by. |
 | `suggestion_batches` | trigger, status, ai_run_id. |
@@ -121,6 +121,16 @@ Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
 `recipes` holds a fetched recipe page; `dinners` holds the household's meal
 record and its lifecycle, optionally linked to a recipe and a photo.
 
+Migration `0018_recipe_item_position_unique` makes position unique per
+recipe and fails, so the service refuses to start, on a database already
+holding a duplicate. Before deploying it, check the database; both queries
+must return no rows:
+
+```sql
+SELECT recipe_id, position FROM recipe_ingredients GROUP BY 1, 2 HAVING count(*) > 1;
+SELECT recipe_id, position FROM recipe_steps GROUP BY 1, 2 HAVING count(*) > 1;
+```
+
 ## Dinner lifecycle
 
 ```
@@ -215,11 +225,10 @@ automatic** (D-021).
   raw_text}]` and `steps` the step texts, both in recipe position order and
   empty (`[]`) with no recipe, as for a dinner whose grounding is
   `pending` or `failed`; a recipe entered by hand has only `raw_text`.
-  Two items at one position leave recipe order unknown, so such a recipe
-  is 500 rather than shown out of order. `source` is `{site_name, url}`
-  of the page the recipe was fetched from, null for a manual recipe or
-  none, as `dinners.SourceOf` gives it — the one rule for every fetched
-  recipe's source, also used by idea results and recipe candidates. `url`
+  `source` is `{site_name, url}` of the page the recipe was fetched from,
+  null for a manual recipe or none, as `dinners.SourceOf` gives it — the
+  one rule for every fetched recipe's source, also used by idea results
+  and recipe candidates. `url`
   is the page's link only when it is free of secrets (https, no user,
   query or fragment), else null. `site_name` is the name the page gives
   its site (publisher or `og:site_name`), else the link's host without