---
url: /reference/CATALOG_USE_CASES.md
---
# Catalog Use Cases

The Catalog is the first slice of roadmap Phase 6, "Shared commercial core"
(`docs/reference/ROADMAP.md`, Phase 6: Catalog, Pricing, Sales, Settlement,
Payments, Cash, Inventory, Procurement). This catalog starts from what a
member of a business tries to do with the things it sells, and derives the
minimal API from that, never from the tables. It follows the structure of
[`ORGANIZATION_USE_CASES.md`](ORGANIZATION_USE_CASES.md): numbered cases,
routes, statuses, codes and the scenario rows that would prove them. Slice
K1, the SQL foundations (migration `0075`), slice K2, the module and the
items with their default variant (C3, C4, C5, C7, migration `0076`), and
slice K3, the reads and the categories (C1, C2, C8, C9, C10, migration
`0077`), and slice K5, the modifier groups and the groups an item offers
(C12, C13, no migration), and slice K4, the variants, the size by colour
matrix, the barcodes and the barcode lookup (C6, C11, C18, migration
`0079`), and slice K6, the business-unit assortment (C14, C15, C16, no
migration), and slice K8, the in-process `CatalogSellableContract` (C20, no
migration), are built: see "K1 as built", "K2 as built", "K3 as built", "K5
as built", "K4 as built", "Hardening round as built" (migration `0080`),
"K6 as built", "K7 as built" and "K8 as built" in section 9. So are the
option offers of K9 (K9a to K9h, [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md)
§4 and §5), the SQL ownership of K10 (K10a to K10c, the same file §6), what a
new business unit sells (D1, "D1 as built"), the item and variant images
(AC1 to AC5, built by the Assets slices, `ASSETS_USE_CASES.md`), the combo
composition and admission (B1 and B2, "B1 as built", "B2 as built") and the
structure of a menu (M1, "M1 as built"), the menus an outlet shows (M2a, M2b) and the items an outlet does not sell (K16, "K16 as built"). See
[`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md) for the tests that prove
them, and `CATALOG_OPTIONS_V2.md` §10.1 for what is left. Later slices are
documented in the "as built" sections of section 9 and in sections 12 to 17:
translations, food labels, allergens, dietary tags and nutrition, typed
attributes, product brands, additional catalogs and the clone, imports and
exports, history and restore, bulk operations, delta routes, the change sets
with their publication, the outlet bootstrap for devices, and the items an
outlet hides. The routes that exist are the ones in
`docs/generated/openapi.json`: 138 operations carry the `Catalog` tag at
revision 178 (counted from that file). A route or capability named only in a design
paragraph that no "as built" section or OpenAPI operation confirms is design
intent, not shipped behavior.

**Ground truth.** `database/canonical/0080_catalog.sql` (read from `staging`;
line numbers below refer to that file), its neighbours `0090_pricing.sql`,
`0100_commerce.sql`, `0110_sales.sql`, `0140_operations.sql`,
`0150_kitchen.sql`, `0170_inventory.sql`, `0260_tax.sql`;
`database/access/runtime_grants.sql`; migrations `0050`, `0055`, `0071`,
`0072`, `0073`; `docs/reference/ROADMAP.md`, `ARCHITECTURE.md`,
`DOMAIN_MAP.md`, `DECISIONS.md` (D01, D04, D07, D10, D18, D21, D24, D25,
D26, D30), `APP_SHELL_AND_ONBOARDING.md`, `AVAILABILITY_AND_PERFORMANCE.md`,
`BUSINESS_DESIGN.md`, `CURRENCY_AND_LANGUAGE.md`;
`docs/contracts/MODULE_CONTRACTS.md`, `API_AND_SCHEMA_DISCIPLINE.md`,
`FOUNDATION_HTTP_AND_OBSERVABILITY.md`; and the contracts already in `src/`
(`PermissionCheckContract`, `OperationAuthorizationContract`,
`operation-refusal.ts`, `TenantAuditContract`).

**Status words used below.** *Decided* means this document takes the
decision and the owner only needs to object. *Open* means the business owner
must answer; none is open since the owner approved OD1 to OD9 on 2026-10-04
(section 10). *Assumption* means a fact this document could not
verify from the repository.

***

## 1. Purpose and scope

### 1.1 What the Catalog is for

The Catalog answers one question for every other commercial module: **what
can this business sell, under which identity, and how is it described and
configured?** It is the source of truth for the commercial identity of a
sellable thing. It is not its price, its stock, its recipe, its tax class or
whether the kitchen ran out of it tonight (`0080_catalog.sql:8-31` states
that boundary; `ARCHITECTURE.md` §3 states "Catálogo no es Inventario.
Catálogo no es Producción.").

| Business                                                                                                       | What it needs from a catalog on day one                                                                                                                                                                      | What it does NOT need from the catalog                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Small restaurant, café, bar (`BUSINESS_DESIGN.md` line 9: "producto, venta, cobro e impresión desde teléfono") | Dishes and drinks grouped by category; sizes (small/large) as variants; modifiers ("no onion", "extra cheese", "cooking point") with required/optional rules; a fast POS list for the waiter and the cashier | Prices (Pricing), kitchen stations and courses (Kitchen owns `kitchen.course_assignment_rules`, `0150_kitchen.sql:570`), recipes (Production), "86" sold-out (Operations owns `operations.item_variant_unavailabilities`, `0140_operations.sql:4598`) |
| Retail shop                                                                                                    | Products with variants (size, colour), SKU, one or more barcodes per variant, sales unit (unit, kg) and quantity step; fast barcode lookup at the till; search by name/SKU                                   | Stock balances and stock links (Inventory owns `inventory.supply_routes` and `inventory.supply_route_stock_lines`, which replaced `catalog_stock_links` in migration `0137`), packaging conversions, purchase data                                                                                                       |
| Hotel (hospitality)                                                                                            | Sellable services and extras (minibar, laundry, spa, room service dishes through a restaurant business unit)                                                                                                 | Rooms, room types and their availability: Phase 10 gives them their own hospitality aggregates (`ROADMAP.md` Phase 10). A room night is **not** a catalog item                                                                                        |

### 1.2 In scope for the first delivery

*Decided.* The first delivery is the smallest catalog that lets a restaurant
and a retail shop configure what they sell and lets a POS read it fast:

1. The organization's **default catalog** (`catalog.catalogs`, created lazily
   by `catalog.ensure_default_catalog`, `0080_catalog.sql:4245`).
2. **Items** with their mandatory **default variant**, and optional named
   **variants** with SKU and sales-quantity policy.
3. **Categories** (a shallow tree) and the item-to-category classification
   with one primary category.
4. **Barcodes** per variant (retail).
5. **Modifier groups and options** and their attachment to items with
   min/max selections (restaurant; usable by retail too).
6. **Business-unit assortment**: which items a business unit sells
   (`catalog.business_unit_catalogs`, `catalog.business_unit_items`,
   `0080_catalog.sql:4433`, `:4446`).
7. The **reads** behind the screens: the back-office workspace, list and
   search with keyset pagination, item detail, and the **outlet sellable
   read** used by the POS, plus a barcode lookup and a paged search of what
   the outlet sells.
8. One **in-process read contract** that Pricing and Sales consume to
   resolve and admit a sellable variant (`CatalogSellableContract`; Sales
   calls `admit` when it sells, `SALES_USE_CASES.md`).

### 1.3 Out of scope of the first delivery, and what was built since

The first column was out of scope of the first delivery. Where the second
column says "Built", a later slice delivered it and the "as built" section
named there is the authority; the rows that do not say "Built" are still not
catalog work.

| Out of scope                                                     | Reason                                                                                                                                                                                                                          | Where it goes                                                                                                                                             |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prices, price books, modifier price deltas, discounts            | Owned by `pricing` (`0080_catalog.sql:24-25`; `0090_pricing.sql` references `catalog.items`, `item_variants`, `modifier_options`, `menus`)                                                                                      | Pricing: the price list of an organization per currency is built (`PRICING_USE_CASES.md`); discounts, modifier price deltas and combo prices are not built                                                                             |
| Taxes                                                            | `tax.catalog_item_tax_class_assignments` (`0260_tax.sql:646`) is owned by `tax`                                                                                                                                                 | Phase 7                                                                                                                                                   |
| Stock, stock links, units conversion                             | Owned by `inventory` (`0170_inventory.sql:410`)                                                                                                                                                                                 | Inventory slice                                                                                                                                           |
| Recipes / bill of materials                                      | Owned by `production` (`0080_catalog.sql:27`); nothing in the catalog tables requires a recipe                                                                                                                                  | Later, optional (D01: not a requirement of every tenant)                                                                                                  |
| Kitchen course and prep station                                  | Owned by `kitchen` (`0150_kitchen.sql:570`, `:907`)                                                                                                                                                                             | Phase 8 restaurant vertical                                                                                                                               |
| Sold-out / 86 / runtime availability                             | Owned by `operations` (`0140_operations.sql:4598`)                                                                                                                                                                              | Restaurant vertical                                                                                                                                       |
| Images and media (`catalog.item_assets`, `0080_catalog.sql:623`) | No longer out of scope: built once the `assets` module existed                                                                                                                                                                  | `PUT /catalog/items/{id}/images`, `PUT /catalog/item-images` (§5.10)                                                                                      |
| Translations (`*_translations` tables) | Built: per-record translations, the offered languages of the organization and of an outlet, and `locale` on the main reads ("9.z B1 as built") | `PUT`/`DELETE /catalog/{entity}/{id}/translations/{locale}`, `GET /catalog/offered-locales` |
| Allergens, dietary tags, nutrition | Built inside Catalog ("9.aa B2 as built"); the proposed `catalog_food` boundary of `DOMAIN_MAP.md` was not taken | `/catalog/food-labels/{kind}`, `/catalog/items/{itemId}/allergens`, `.../dietary-tags`, `.../nutrition` |
| Generic tags (`tag_groups`, `tags`, `item_tags`, `menu_tags`)    | No use case named them (see §3)                                                                                                                                                                                                 | Dropped by migration `0075`                                                                                                                               |
| Bundles / combos | Built: the composition (B1), the admission (B2) and the combo groups in the till and the search (B2c); no price rule is specific to a combo | Prices come from the price list per variant (`PRICING_USE_CASES.md`) |
| Menu time windows (S1)                                           | Built: the hours in which an outlet shows each of its menus (C31, "S1 as built"); holidays and date ranges stay deferred                                                                                                        | The menus an outlet shows and their order (M2a, C29), the till read by menu (M2b) and now their hours (S1); the assignment gap G1 and risk R13 are closed |
| Multiple catalogs per organization (`access_mode = 'assigned'`) | Built: the registry, rename, transitions and clone of catalogs, the catalog a business unit sells from, and a catalog named on every collection read and create ("CA1 to CA4 as built") | `/catalog/catalogs`, `POST /catalog/catalogs/{catalogId}/clones`, `PUT /catalog/business-units/{businessUnitId}/catalog` |
| Imports and exports | Built: a bulk import document is judged (`POST /catalog/import-validations`), applied (`POST /catalog/imports`) and read back (`GET /catalog/imports/{importId}`); `GET /catalog/exports` exports a catalog ("I1 to I4c", "S6a", "S6b as built") | `/catalog/import-validations`, `/catalog/imports`, `/catalog/exports` |
| Offline replay of catalog writes | Catalog editing is back-office, online; the device reads the outlet bootstrap (`GET /catalog/outlets/{outletId}/bootstrap`, `.../bootstrap/items`, K12a and K12b as built). D06 applies to Sales commands, not to catalog configuration | Not planned |

***

## 2. Ownership and boundaries

### 2.1 Facts the Catalog owns

Only the `catalog` module mutates these facts (one fact, one owner,
`ARCHITECTURE.md` §3):

* the commercial identity of an item and its variants: code, name,
  description, lifecycle status, SKU, sales unit and quantity policy, which
  variant is the default (`0080_catalog.sql:33-45`);
* the scannable identities of a variant (barcodes);
* the classification of items (categories and item-category links);
* the reusable modifier groups and options, and which groups an item offers
  with which min/max rules;
* the catalog namespaces and which business units list which items
  (assortment);
* later: bundle composition, menus and their structure, translations, food
  declarations.

### 2.2 Neighbours

| Neighbour                                              | Direction                               | What crosses the boundary                                                                                                                                                            | Mechanism                                                                                                                                                                                                                 |
| ------------------------------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization                                           | Catalog reads                           | Business unit exists and is active; the effective business unit of an outlet on the site's date (`organization.effective_business_unit`, granted to runtime in `runtime_grants.sql`) | SQL read inside catalog repositories under RLS, the same way `organization` already reads `platform.business_unit_verticals` directly (O11 "As built"). Module-boundary rules constrain TypeScript imports, not SQL (O11) |
| Identity                                               | Catalog consumes                        | Permission decision at an anchor                                                                                                                                                     | `PermissionCheckContract.decide` with `anchor` (`src/modules/identity/contracts/permission-check.contract.ts`)                                                                                                            |
| Platform                                               | Catalog consumes                        | Permission + capability + place operability decision                                                                                                                                 | `OperationAuthorizationContract` (`platform.authorize_operation`, `0071`; `platform.authorize_operation_at`, `0073:162`)                                                                                                  |
| Audit                                                  | Catalog consumes                        | Tenant audit record in the same transaction                                                                                                                                          | `TenantAuditContract`                                                                                                                                                                                                     |
| Pricing (future)                                       | Reads Catalog                           | Sellable variant snapshot; validity of variant / modifier option ids                                                                                                                 | New `CatalogSellableContract` (C20)                                                                                                                                                                                       |
| Sales (future)                                         | Reads Catalog                           | Admission of a variant for a business unit at sale time, atomically                                                                                                                  | `CatalogSellableContract.admit` inside the shared tenant transaction (D18)                                                                                                                                                |
| Inventory, Tax, Kitchen, Commerce, Production (future) | Reference `catalog.item_variants` by FK | Variant identity only                                                                                                                                                                | FKs already in canonical SQL (§2.4)                                                                                                                                                                                       |
| Session context (Identity)                             | Context for the client                  | `workspace.businessUnits` with their verticals, outlets                                                                                                                              | Read only. "La lista `workspace.businessUnits` es contexto, no autoridad" (`APP_SHELL_AND_ONBOARDING.md` line 60): every catalog command re-checks permission                                                             |

### 2.3 Module contracts (R1 to R9)

*Decided.* The module lives at `src/modules/catalog/` with the standard
layers (`ARCHITECTURE.md` §6). Applying `MODULE_CONTRACTS.md` §10:

| Rule       | Consequence for Catalog                                                                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| R1         | Catalog imports only `identity/contracts`, `platform/contracts`, `audit/contracts`. Pricing and Sales will import only `catalog/contracts`                                                                    |
| R2, R6, R7 | Use cases open the transaction with `TenantTransactionRunnerService`; repositories in `infrastructure/` run SQL; controllers never touch `TransactionContext` beyond passing it                               |
| R3         | Domain rules (default-variant invariant, min/max selection validation, code normalisation, category depth) are pure TypeScript, no Nest, no Zod                                                               |
| R4, R5, R8 | Catalog never imports `src/verticals/**`. Vertical-specific behavior (restaurant modifiers UX, retail barcode-first UX) is the client's concern, not a server `if (vertical === ...)` (`ARCHITECTURE.md` §14) |
| R9         | No system transaction: every catalog path runs with tenant context                                                                                                                                            |

Published contract (section 15 of `MODULE_CONTRACTS.md` must list it in the
same change that publishes it): `CatalogSellableContract`
(`src/modules/catalog/contracts/catalog-sellable.contract.ts`), with
`resolve` (read) and `admit` (lock-and-check) methods (C20).

### 2.4 Schema boundary and existing cross-schema SQL

The `catalog` schema is owned by `0080_catalog.sql` (D02). Today:

* **The API could not reach it before K1.** `runtime_grants.sql` granted
  `USAGE` only on `reference, identity, organization, platform` and nothing
  on `catalog`; K1 (migration `0075`) adds the grants listed in "K1 as built"
  (section 9).
* **Catalog reads Organization** in SQL: FKs to `organization.organizations`
  and `organization.business_units`; `guard_assortment_change`,
  `assert_variant_listed` and `resolve_barcode` lock or read
  `organization.business_units` (`0080_catalog.sql:4460`, `:4504`, `:4528`).
* **Thirteen schemas reference catalog tables by FK** (counted with `git grep
  'REFERENCES catalog\.'`): pricing (items, variants, categories, menus,
  modifier groups and options, bundle items, `catalogs`), commerce (cart and
  storefront publication), sales (variants, modifier options, bundle items,
  menu entries, allergens), operations (variants), kitchen (items, variants,
  categories, menu sections), inventory, production, crm, loyalty, tax,
  invoicing, integrations, analytics. `catalog.item_variants` is the hub:
  **variant identity is the most load-bearing fact of this module** and its
  ids must never be reused or hard-deleted.

***

## 3. Table traceability

Classification: **USE NOW** (the first delivery writes or reads it), **USE
LATER** (justified by a named later use case), **DROP OR RESHAPE** (no
defensible use case in its current shape, `API_AND_SCHEMA_DISCIPLINE.md` §3
and §6.4; `ROADMAP.md` §1.3: "Tables with no defensible purpose should be
reviewed instead of automatically exposed").

### 3.1 Existing tables

| Table (line)                                                                                                                                                                                                      | Class                                                                                                                          | Reason                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalogs` (4229)                                                                                                                                                                                                 | USE NOW                                                                                                                        | Every master row carries `catalog_id NOT NULL` (`assign_catalog_id`, 4372); the default catalog is created lazily. Only the default catalog is used in v1                                                   |
| `items` (76)                                                                                                                                                                                                      | USE NOW                                                                                                                        | The commercial item (C3–C7)                                                                                                                                                                                 |
| `item_variants` (140)                                                                                                                                                                                             | USE NOW                                                                                                                        | Default variant is mandatory (`catalog_items_require_default_variant_trg`, deferred, 2979); named variants for sizes/colours; FK hub for every downstream module                                            |
| `item_variant_barcodes` (269)                                                                                                                                                                                     | USE NOW                                                                                                                        | Retail scan (C11, C18); `resolve_barcode` (4528) already exists                                                                                                                                             |
| `categories` (354)                                                                                                                                                                                                | USE NOW                                                                                                                        | Back-office organisation and POS grouping (C9, C10, C17); cycle prevention with an advisory lock (`lock_hierarchy`, 2999)                                                                                   |
| `item_categories` (430)                                                                                                                                                                                           | USE NOW                                                                                                                        | Classification with one primary (C8); a pure link table with a `FOR ALL` policy (3980), so it can be replaced as a set                                                                                      |
| `modifier_groups` (1672), `modifier_options` (1776)                                                                                                                                                               | USE NOW                                                                                                                        | Restaurant customisation (C12)                                                                                                                                                                              |
| `item_modifier_groups` (1937)                                                                                                                                                                                     | USE NOW                                                                                                                        | Which groups an item offers, with `min_selections`/`max_selections` per item (C13)                                                                                                                          |
| `business_unit_catalogs` (4433), `business_unit_items` (4446)                                                                                                                                                     | USE NOW                                                                                                                        | Assortment per business unit (C14–C16) and the POS read (C17); `variant_is_listed` (4487) encodes the listing rule                                                                                          |
| `item_translations`, `item_variant_translations`, `category_translations`, `modifier_group_translations`, `modifier_option_translations` | USED (9.z B1 as built) | Per-record translations and the offered languages are built; the three tables added by migration `0118` complete the set |
| `bundle_groups` (2048), `bundle_group_items` (2170)                                                                                                                                                               | USED (B1, B2, B2c); `bundle_group_translations` later                                                                          | The composition, the admission and the till read are built; the acyclic-graph guard (2258–2357) stays. A combo price needs Pricing                                                                          |
| `menus` (2368), `menu_translations`, `menu_sections` (2506), `menu_section_translations`, `menu_entries` (2660), `menu_entry_translations`, `menu_entry_variants` (2817)                                          | USED (M1, M2a, M2b) for `menus`, `menu_sections`, `menu_entries`, `menu_entry_variants` and `outlet_menus`; translations later | The structure ("M1 as built"), the outlet assignment ("M2a as built") and the till read by menu are built. Sales and Kitchen reference `menu_entries` / `menu_sections`, so rows are retired, never deleted |
| `item_assets` (623)                                                                                                                                                                                               | USED                                                                                                                           | The item and variant images (§5.10, built with the `assets` module)                                                                                                                                         |
| `allergens` (730), `allergen_translations`, `item_allergens` (826), `dietary_tags` (917), `dietary_tag_translations`, `item_dietary_tags` (1013), `item_nutrition_profiles` (1422), `item_nutrition_facts` (1609) | USED (9.aa B2 as built) | Food labels, item declarations and nutrition are built inside Catalog; `DOMAIN_MAP.md` still records the proposed `catalog_food` boundary, which was not taken |
| `tag_groups` (1114), `tag_group_translations`, `tags` (1233), `tag_translations`, `item_tags` (1341), `menu_tags` (2467)                                                                                          | DROPPED                                                                                                                        | A generic tagging system had no named reader: categories already classify, and filters for the POS are categories. Migration `0075_catalog_foundations` dropped the six tables                              |

### 3.2 Seven-question check for the tables used now (abridged)

| Table                                           | Writer                                                                 | Reader                          | Invariant                                                                                                                                                                                                                     | Lifecycle                                                                                                                                                                                   |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalogs`                                      | `ensure_default_catalog` (lazy, on first item/category/modifier write) | every catalog read              | one default per organization (`catalogs_one_default_uq`); `access_mode`/`is_default` immutable (`protect_catalog_identity`, 4269)                                                                                             | active forever in v1                                                                                                                                                                        |
| `items`                                         | C4, C5, C7                                                             | C1–C3, C17, C19, C20            | code unique per (organization, catalog), case-insensitive (redefined at 4426)                                                                                                                                                 | active ⇄ inactive; → archived ⇄ restored (§4.4)                                                                                                                                             |
| `item_variants`                                 | C4, C6                                                                 | C3, C17–C20, all downstream FKs | exactly one default per item (241 + deferred trigger 2979/2986); SKU unique per catalog (4430)                                                                                                                                | active ⇄ inactive; archived final for named variants                                                                                                                                        |
| `item_variant_barcodes`                         | C11                                                                    | C18, C3                         | value unique per catalog (4431); one active primary per variant (332)                                                                                                                                                         | active ⇄ inactive; never deleted (a barcode may already be printed on a receipt)                                                                                                            |
| `categories`                                    | C9                                                                     | C1, C2, C10, C17                | no cycle (advisory lock + trigger, 3019); code unique per catalog                                                                                                                                                             | active ⇄ inactive; archived                                                                                                                                                                 |
| `item_categories`                               | C8                                                                     | C2, C3, C17                     | one primary per item (471)                                                                                                                                                                                                    | replaced as a set                                                                                                                                                                           |
| `modifier_groups`, `modifier_options`           | C12                                                                    | C3, C13, C17, Pricing later     | `catalog_variant` options point to a concrete variant (`modifier_options_kind_target_chk`)                                                                                                                                    | active ⇄ inactive; archived                                                                                                                                                                 |
| `item_modifier_groups`                          | C13                                                                    | C3, C17                         | per-item min/max; unique per item scope (2013), every status included; status `active`, `inactive` or `retired` since revision 94, every read ignoring `retired` ([`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §4.1, K9a) | written in place as an ordered set since K9b: a kept or re-offered link keeps its id, a removed one is retired, never deleted; the runtime holds no `DELETE` on it since revision 101 (K9c) |
| `business_unit_catalogs`, `business_unit_items` | C14, C15                                                               | C16–C20                         | ownership columns immutable; BU row locked on each write (4460)                                                                                                                                                               | active ⇄ inactive; never deleted                                                                                                                                                            |

### 3.3 Gaps: needed facts with no table

| Gap                                            | Need                                                                                                                                                                                                                                                                                                                     | Recommendation                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **G1 — Outlet menu assignment** (closed)       | A restaurant POS shows "the lunch menu" at outlet A. No catalog table linked a menu to an outlet; `commerce.storefront_publications` (`0100_commerce.sql:438`) links outlet + menu only for an online storefront, and `pricing.price_book_assignments` (`0090_pricing.sql:133`) uses outlet + menu only to choose prices | Closed by M2a (C29, migration `0105`, baseline revision 115): `catalog.outlet_menus` holds which menus an outlet shows and in what order (up to 10). The assignment only organizes; the till read by menu follows (M2b)                                                                                                                                                                                                                                   |
| **G2 — Catalog version for conditional reads** | The POS read is the hottest read; a `304` must be answered without re-running the full query (D24)                                                                                                                                                                                                                       | New table `catalog.catalog_versions(organization_id PK, version bigint)` bumped by statement-level triggers, mirroring `organization.structure_versions` (migration `0072`). Justified by C10 and C17                                                                                                                                                                                                                                                     |
| **G3 — Idempotent create**                     | The item code is optional (OD2), so a retried `POST /catalog/items` would create a duplicate                                                                                                                                                                                                                             | Nullable `items.creation_idempotency_key` + unique partial index `(organization_id, creation_idempotency_key)`, per `FOUNDATION_HTTP_AND_OBSERVABILITY.md` §7 (claim lives in the module's own table). Needed: OD2 decided optional, generated codes. Since revision 91 (`0081`) categories, modifier groups and modifier options claim a key the same way, and the four creates store `creation_request_hash` next to it ("Idempotent creates as built") |
| **G4 — Set-based listing predicate**           | `variant_is_listed` (4487) is row-at-a-time; the POS read needs the same rule as one set-based query                                                                                                                                                                                                                     | New `STABLE` SQL function `catalog.listed_items(p_organization_id, p_business_unit_id)` returning item ids, with a contract test that it agrees with `variant_is_listed` row for row                                                                                                                                                                                                                                                                      |
| **G5 — `updated_at` maintenance**              | No trigger maintains `updated_at` on catalog tables (no `updated_at =` assignment in the file); `catalogs`, `business_unit_catalogs`, `business_unit_items` have no `updated_at` at all                                                                                                                                  | The application sets `updated_at` on every update (as Organization does); ETags never depend on it (they use G2 or a content hash). No new columns                                                                                                                                                                                                                                                                                                        |

No other new table is proposed.

***

## 4. Domain model and vocabulary

### 4.1 Aggregates

| Aggregate             | Root                                                                                  | Entities / value objects inside                                                                                                                                                                                                            | Consistency boundary                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Item**              | `Item` (`catalog.items`)                                                              | `Variant` (≥1, exactly one default), `Barcode` (per variant), `Classification` (category links, one primary), `ModifierOffer` (ordered group links with `SelectionRule{min,max}` and the options this item preselects, `defaultOptionIds`) | One item and everything inside it changes in one transaction, after the lock order of §5 (version row first, then the item row)          |
| **Category tree**     | `Category`                                                                            | parent link, `sortOrder`                                                                                                                                                                                                                   | Re-parenting serialised per organization with `catalog.lock_hierarchy(org, 'category')`                                                  |
| **Modifier group**    | `ModifierGroup`                                                                       | `ModifierOption` (`instruction` or `catalog_variant`), `maxQuantity`, `sortOrder` (no default: what starts preselected belongs to each item offer, C13)                                                                                    | One group changes in one transaction, after the lock order of §5 (version row first, then the group row)                                 |
| **Assortment**        | `BusinessUnitAssortment` (`business_unit_catalogs` row per business unit and catalog) | `Listing` (`business_unit_items`)                                                                                                                                                                                                          | Serialised by the organization's catalog version row, locked first (§5); `guard_assortment_change` then also locks the business unit row |
| **Catalog namespace** | `Catalog`                                                                             | —                                                                                                                                                                                                                                          | v1: only the default, created lazily                                                                                                     |

### 4.2 Identifiers and codes

| Field                                                   | Rule                                                                                                                                                                                                                                                                                                                                                                                                  | Source                                                                                                                        |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| ids                                                     | UUIDv7 generated by the application                                                                                                                                                                                                                                                                                                                                                                   | `0080_catalog.sql:51`                                                                                                         |
| `code` (item, variant, category, modifier group/option) | `^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$`, unique case-insensitive per (organization, catalog) for items/categories/groups; per item for variants; per group for options                                                                                                                                                                                                                                    | `catalog_items_code_chk`; indexes at 4426–4429                                                                                |
| `code` (combo group, menu, menu section)                | Same pattern. Unique per combo (every code the combo holds or held) for combo groups; per (organization, catalog) for menus; per menu (retired sections included) for sections                                                                                                                                                                                                                        | B1 and M1 as built                                                                                                            |
| Required or derived `code`                              | **Required** on create for variants, categories and modifier groups. **Optional** for items, modifier options, combo groups, menus and menu sections: when absent the code is derived from the name (accents dropped, lowercase ASCII, hyphens), and `-2`, `-3`… is added against the codes already taken in its scope; a name with nothing left gives `item`, `option`, `group`, `menu` or `section` | request schemas in `presentation/dtos/**` (`*-request.schema*.ts`); `domain/items/item-code.ts`, `domain/shared/part-code.ts` |
| `sku`                                                   | optional, non-blank, ≤120, unique case-insensitive per (organization, catalog)                                                                                                                                                                                                                                                                                                                        | 248, 4430                                                                                                                     |
| `barcode`                                               | non-blank, ≤160, unique per (organization, catalog); optional `symbology` from a closed list                                                                                                                                                                                                                                                                                                          | 269–331, 4431                                                                                                                 |
| names                                                   | `trimmedBoundedText` from `foundation/validation`, reject NUL (`AGENTS.md` §4); item name ≤255, category/group/option ≤180                                                                                                                                                                                                                                                                            | column sizes                                                                                                                  |
| `salesUnitCode`                                         | FK to `reference.units_of_measure` (seeded: `unit`, `g`, `kg`, `ml`, `l`, ...)                                                                                                                                                                                                                                                                                                                        | 140–200                                                                                                                       |
| quantities                                              | `minimumSalesQuantity > 0`, `salesQuantityStep > 0`, `maximum ≥ minimum`; exact decimals as strings through the `decimal.js` wrapper, never `number` (`AGENTS.md` §4)                                                                                                                                                                                                                                 | `item_variants_sales_quantity_policy_chk`                                                                                     |

*Decided:* the default variant of a simple item has `code = 'default'` and
`name = NULL`; a restaurant never sees it in the UX (`0080_catalog.sql:35-36`).
The API returns `variants` always, with `isDefault`, so the client can hide a
single default variant.

### 4.3 Scoping rules

| Fact                                             | Scope                                                                                  | Grounding                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Item, variant, barcode, category, modifier group | **Catalog namespace** (v1: the organization's default catalog), i.e. organization-wide | `catalog_id NOT NULL` on every master row; `ARCHITECTURE.md` §14: business units share the "catálogo base"                                    |
| Whether a business unit sells an item            | **Business unit**                                                                      | `business_unit_catalogs`, `business_unit_items`; `APP_SHELL_AND_ONBOARDING.md` line 34: "El catálogo compartido respeta asignación y surtido" |
| What an outlet's POS shows                       | **Outlet → its effective business unit today**                                         | `organization.effective_business_unit(org, outlet, site date)` (the same resolution `platform.authorize_operation` uses)                      |
| Prices per brand/outlet/menu                     | Not catalog                                                                            | `pricing.price_book_assignments`                                                                                                              |
| Legal entity, brand, site                        | Not a catalog scope in v1                                                              | No catalog table carries them; Pricing and Sales freeze legal entity (D04)                                                                    |

### 4.4 Lifecycle states

Database states are `active`, `inactive`, `archived` for items, variants,
categories, groups and options (`*_status_chk`); `active`, `inactive` for
barcodes and assortment rows. *Decided* meaning and transitions:

| State      | Meaning                                                          | Visible in POS read | Visible in back-office list        |
| ---------- | ---------------------------------------------------------------- | ------------------- | ---------------------------------- |
| `active`   | Sellable where listed                                            | yes                 | yes (default filter)               |
| `inactive` | Temporarily withdrawn everywhere (seasonal dish, paused product) | no                  | yes, with filter `status=inactive` |
| `archived` | Retired; kept because downstream history references the variant  | no                  | only with `status=archived`        |

```text
             deactivate                 archive
  active ─────────────────▶ inactive ─────────────▶ archived
     ▲  ◀───────────────── │   ▲                       │
     │      reactivate     │   └────── restore ────────┘
     └────────── archive (direct) ─────────────────────▶
```

* `archive` is allowed from `active` or `inactive`; `restore` returns
  an archived item to `inactive` (never straight to `active`), so a restored
  item is reviewed before it sells again. (Restorability itself is OD8.)
  Variants follow the same table since API v7 PR 2, and categories,
  modifier groups and modifier options since API v7 PR 3 (each with its own
  `restore`). The names in the diagram are the closed list a client sends to
  `POST .../transitions` (C7, C9, C12). `deactivate` and `archive` never need
  the plan; `reactivate` and `restore` do.
* Nothing is ever hard-deleted by the runtime (no `DELETE` policy exists on
  master tables; the header says "archived/inactivated rather than
  hard-deleted", `0080_catalog.sql:60-62`).
* The default variant cannot be deactivated or archived while its item is
  `active`; to retire a variant that is default, first make another variant
  the default (`assert_item_default_variant`, 2900).
* Menus have their own `draft/active/archived` (2368): created draft, `activate` (draft → active, gated) when at least one entry is available, `unpublish` (active → draft), `archive` (draft or active → archived) and, since API v7 PR 3, `restore` (archived → draft, gated, with its structure); archiving is no longer final (M1). Sections and entries are `active`, `inactive` (SQL only) or `retired`.

***

## 5. Use cases

**Conventions for every case.** Routes are relative to `/api/v1`; every
request carries a session and `X-Organization-Id` (O3; `TenantContextGuard`).
Bodies are strict Zod schemas that reject unknown fields (D24). Responses
use `{ data }` or `{ data, meta }` (`FOUNDATION_HTTP_AND_OBSERVABILITY.md`
§1). `detail` is English and technical; the client translates `code` (D25).
Every command that changes something writes one tenant audit record through
`TenantAuditContract` in the same transaction, only for a real change
(as O11).

**Lock order (one rule for every catalog command).** Every catalog command
first locks the `catalog.catalog_versions` row of its organization with
`SELECT ... FOR UPDATE`, before it locks or writes any item, variant,
category, modifier group or business unit row. The reason: every catalog
write fires the statement-level bump trigger, which updates that same row
and holds its lock until commit, so a command that locked an item first and
bumped later could deadlock with another command that bumped first and then
asked for the same item. Taking the version row first serializes the
catalog commands of one organization in a single order. After it, a command
may lock the rows it edits (`FOR UPDATE`) or reads for validation
(`FOR SHARE`), in id order. Reads and `CatalogSellableContract.resolve`
(C20) do not take it. `CatalogSellableContract.admit` (C20, which writes
nothing in the catalog) shares it (`FOR SHARE`) before anything else, so
admissions and catalog commands never deadlock. The cost falls on the
catalog writer, not on the sale: a shared lock does not queue behind a
waiting `FOR UPDATE`, so new admissions keep entering while a command waits,
and the command proceeds only once no admission of the organization is open;
under continuous overlap of sale transactions it fails after
`DATABASE_STATEMENT_TIMEOUT_MS` (5,000 ms), not after
`DATABASE_LOCK_TIMEOUT_MS`, which PostgreSQL applies to each lock
acquisition separately ("K8 as built", the Sales requirement and the measured
gate).

**Hierarchy locks come after the version row (proven, I2 to I4c).** The
`BEFORE` row triggers of `categories` (`prevent_category_cycle`),
`menu_sections` (`prevent_menu_section_cycle`) and, for every write to
`item_variants`, `bundle_groups` and `bundle_group_items`
(`guard_bundle_graph_write`), take an organization-wide transaction advisory
lock (`lock_hierarchy`, `lock_bundle_graph`) that is held until commit, and
the statement-level bump trigger takes the version row only at the end of
the statement. A writer that held the advisory lock and then asked for the
version row would deadlock (`40P01`) with a writer that held the version row
and then reached a category, menu section or variant. That cannot happen
because no writer reaches those triggers before it has the version row: the
category, menu, bundle, item, variant and import commands all call
`lockVersion` first (`create-category.use-case.ts`, `category-writes.ts`,
`menu-writes.ts`, `set-bundle-groups.use-case.ts`, `lock-item-for-write.ts`,
`apply-catalog-import.use-case.ts`). `catalog-lock-order.e2e-spec.ts` holds
the version row in another transaction and fires each writer: it must wait
on `catalog_versions` and hold no advisory lock while it waits.
`catalog-import.lock-order.integration-spec.ts` interleaves an import that
inserts categories with a category writer (the writer waits on the version
row; both commit) and reproduces the reverse order on purpose: PostgreSQL
gives exactly one of the two sessions `40P01` (raw sessions; the retry of the transaction runner would hide it in production).
Any new writer of those tables must lock the version row first. An import
takes the version row at its start and keeps it, and the advisory locks it
takes at its first category or variant row, until it commits; a concurrent
catalog writer therefore waits for the import on the version row, and
answers the retryable `503` if the import runs longer than
`DATABASE_LOCK_TIMEOUT_MS` (2,000 ms); the advisory lock adds no wait of its
own.

**Update lists (K2 repositories).** UPDATE is granted on whole tables, so
the repository is what keeps identity columns out of a write: an UPDATE
never includes `item_id`, `organization_id`, `catalog_id` or `created_at`
in its `SET` list, not even with an unchanged value. Naming `item_id` on
`item_variants` fires the bundle-graph guard triggers; until revision 110
the runtime could not execute their functions and the statement failed with
`42501`, and since B1 (which grants `EXECUTE` on
`catalog.lock_bundle_graph` and `catalog.assert_bundle_composition_acyclic`)
it would take the bundle-graph lock and re-check the composition graph, so
the rule stays; the others are immutable and their triggers refuse them.

Every command answers the shared rows of this table, which are not repeated
per case:

| Shared path                                                  | Answer                                                                                            |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| No session                                                   | `401 · identity.session_required`                                                                 |
| Organization not selectable                                  | `403 · tenant.context_rejected`                                                                   |
| Permission missing at the anchor                             | `403 · catalog.action_forbidden` (*new*, audited as denied, like `organization.action_forbidden`) |
| Scope assigned to an inactive place                          | `403 · authorization.scope_unavailable`                                                           |
| Capability not in the plan (gated commands only)             | `403 · platform.capability_not_entitled`                                                          |
| Business unit anchor inactive                                | `422 · authorization.place_not_operational`                                                       |
| Outlet anchor not operating                                  | `422 · authorization.outlet_not_operational`                                                      |
| Malformed id, code or body                                   | `400 · foundation.validation_failed` with `meta.errors`                                           |
| Unknown or foreign-tenant catalog object                     | `404 · catalog.not_found` (*new*; RLS makes "another tenant's" and "does not exist" identical)    |
| Unknown or foreign-tenant business unit / outlet in the path | `404 · organization.structure_not_found` (reused, as session context does)                        |
| `If-Match` stale                                             | `412 · foundation.precondition_failed`, nothing written                                           |
| Unexpected constraint not mapped                             | `422 · catalog.item_refused` (*new*, generic backstop like `organization.structure_refused`)      |

The plan gate and the existence check do not run in the same order on every gated route: for an organization without the capability, a route that looks a record up first answers `404` (or `400` for an invalid body) for an id that does not exist, and `403 · platform.capability_not_entitled` once the record is found. The answer depends only on the caller's own organization and input, never on another tenant's data (`catalog-authorization-sweep-capability.e2e-spec.ts`).

**Authorization helpers.** "Org-wide" means `OperationAuthorizationContract`
with no outlet (satisfied only by an organization-wide scope, as every
Organization command today). "At BU" means `platform.authorize_operation_at
(permission, capability, 'business_unit', id)`. "At outlet" means
`PermissionCheckContract.decide` with `outletId`. Ungated commands use
`PermissionCheckContract` (no capability step); gated ones use
`OperationAuthorizationContract`. Permission and capability codes are in §7.

### 5.1 Reads for the back office

#### C1 — Open the catalog workspace

**Actor:** member with `catalog.items.view` (org-wide, or at the chosen
business unit). **Intent:** the first screen of "Products" in two requests
(D10: `GET /session/context` + `GET /<module>/workspace`,
`API_AND_SCHEMA_DISCIPLINE.md` §2.A).
**Route:** `GET /catalog/workspace?businessUnitId=` (optional).
**Response essentials:** `catalog {id, code, name}`, `counts {active,
inactive, archived}` (bounded `count(*)` on an index), `categories` (the
whole tree, capped at 500 nodes with `truncated`), the first page of items
(same shape as C2, `limit` 50, `primaryImage` included since API v7 PR 7), `assortment {mode}` when `businessUnitId` is
given, `allowedActions` derived from the same permission checks (context,
never authority).
**Statuses:** `200`. No ETag (it contains a cursor page, D24). Not
capability-gated (a tenant whose plan lost the catalog must still see and
repair it).
**Scenario rows:** happy path org-wide; BU-scoped member with
`businessUnitId` of its BU → 200; same member without `businessUnitId` →
403; BU-scoped member with another BU → 403; foreign BU → 404; empty
catalog (no default catalog yet) → 200 with zero counts and no write;
category tree over 500 → `truncated: true`.
**Statements (since K10b):** the warning `units_with_different_verticals`
comes from the contracts, not the facts statement: an organization-wide
curator adds `OrganizationContextContract.activeBusinessUnits` (one statement)
and, when two or more units are active, `BusinessUnitVerticalsContract.activeVerticals`
(one more); every other reader adds none (`CATALOG_OPTIONS_V2.md` §6.2).

#### C2 — List and search items

**Actor/permission:** as C1.
**Route:** `GET /catalog/items?q=&status=&categoryId=&includeDescendants=&hasImage=&businessUnitId=&listed=&after=&before=&limit=`.

* `q`: prefix match on name, code or SKU, case- and accent-insensitive
  (`cafe` finds `Café`, `CAFÉ` and `Cafè`; `nandu` finds `Ñandú`), 1–80
  chars (*Decided*: prefix, not substring; §8.3).
* `status`: one or several of `active`, `inactive`, `archived`, separated
  by commas (`status=active,inactive`), each once; `active` when absent
  (API v7 PR 7).
* `categoryId`, and `includeDescendants=true` to add the categories below it
  (two levels at most: a tree is three deep); `hasImage=true|false` keeps
  the items with or without a primary image of their own (API v7 PR 7).
* `businessUnitId` + `listed=true|false`: only items the unit sells / does
  not sell (requires the BU anchor).
* Keyset order `(lower(name) COLLATE "C", id)`; `limit` default 50, max 100;
  signed opaque cursor (`CURSOR_SIGNING_KEY`). *Decided:* catalog lists are
  ordered by name, not `created_at`, because people scan products
  alphabetically; still keyset, never `OFFSET` (`lint:no-offset-paging`).
  **Response:** `data: [{id, code, name, status, defaultVariant {id, sku,
  salesUnitCode}, variantCount, primaryCategory {id, name}, primaryImage
  {assetId, thumbnailUrl} | null}]`, `meta.pageInfo` (`primaryImage` since API
  v7 PR 7, described in one Assets call per page).
  **Statuses/codes:** `200`; `400 · collection.cursor_invalid |
  cursor_tampered | cursor_expired | cursor_incompatible` (a cursor from
  another filter set is incompatible).
  **Scenario rows:** pagination stability under concurrent inserts (no
  duplicate, no skip across pages); prefix on code vs name vs SKU; accent and
  case (`Ñandú` vs `ñandú`); `q` with `%` or `_` is escaped (no wildcard
  injection); tenant isolation with identical codes in two organizations;
  `limit=101` → 400.

#### C3 — Read one item

**Actor/permission:** as C1.
**Route:** `GET /catalog/items/{itemId}`.
**Response:** the full aggregate: item fields, `variants[]` (with
`barcodes[]`), `categories[]` (with `isPrimary`), `modifierGroups[]` (with
`minSelections`, `maxSelections`, `sortOrder`, and the group's options).
Since K9g each item group carries `suspended` and each variant carries
`modifierGroupOverrides[]`: the groups that variant overrides (`optedOut:
false`, its own rule and defaults) or drops (`optedOut: true`), in order,
each with the group's options; retired rows never appear.
**ETag:** *Decided* a content hash of the returned aggregate (D24 allows
"hash del contenido"), `Cache-Control: private, no-cache`; `If-None-Match`
match → `304` with empty body. A per-item hash, not the organization-wide
version, so two people editing different items never collide on `If-Match`
(the cost D24 accepted for the organization structure is avoided here
because catalog editing is far more concurrent).
**Scenario rows:** ETag changes after a variant is added, a barcode is
deactivated, the item is reclassified, a modifier group attached to it is
renamed; old `If-None-Match` no longer gives 304; archived item still
readable (200).

### 5.2 Item commands

#### C4 — Create an item

**Actor:** `catalog.items.manage` org-wide; capability `catalog.items`.
**Route:** `POST /catalog/items`.
**Request:** `{ code?, name, description?, categoryIds?, primaryCategoryId?,
defaultVariant: { sku?, salesUnitCode = 'unit', minimumSalesQuantity = '1',
maximumSalesQuantity?, salesQuantityStep = '1' }, variants?: [{ code, name,
sku?, ... }] }`.
**Main path:** one transaction: lock the catalog version row (lock order,
§5) → `ensure_default_catalog` → insert item →
insert default variant (`is_default = true`, `code = 'default'`) → optional
named variants (≤ 50 per request) → optional category links → audit
`catalog.item.created` → bump `catalog_versions` (trigger). The deferred
constraint trigger (2979) proves the default-variant invariant at commit.
**Response:** `201` with the C3 shape and its `ETag`.
**Idempotency:** with a client-supplied `code`, a retry fails loudly with
`409 · catalog.code_taken` and never duplicates (the K1 posture, as `POST
/brands`, which has no `Idempotency-Key`; superseded in K2, see below). Because OD2 made `code` optional
and generated from the name, `Idempotency-Key` is required when `code` is
omitted (G3). *As built in K2:* the route requires `Idempotency-Key` on every
create, with or without a code, so a client has one rule and a retry always
replays instead of answering `409` (see "K2 as built"). Since revision 91
the replay compares the SHA-256 of the original request, stored next to the
key in `creation_request_hash`, not the item as it is now: a retry with the
same key and body after the item's name, code or description was edited
answers `201` with the item as it is now and `Idempotent-Replayed: true`,
and the same key with another request `409 · idempotency.key_reused`. An
item created before revision 91 has a key without a hash and is still
compared with the item as it is now (see "Idempotent creates as built");
`idempotency.key_reused` / `idempotency.in_progress` as the foundation
contract.
**Errors:** `409 · catalog.code_taken` (`catalog_items_code_ci_uq`), `409 ·
catalog.sku_taken` (`item_variants_sku_ci_uq`), `422 · catalog.unit_unknown`
(*new*, `item_variants_sales_unit_fk`), `422 · catalog.quantity_policy_invalid`
(*new*, `item_variants_sales_quantity_policy_chk`), `404 · catalog.not_found`
for an unknown category id, `422 · catalog.category_archived` for an
archived category; an inactive category is accepted (owner decision
2026-10-05, "Category lifecycle and effective visibility").
**Plan limit:** none in v1 (OD6). If a limit is introduced it is
`catalog.active_items`, checked under a per-organization lock like
`identity.assert_membership_seat_available`.
**Scenario rows:** happy path simple item (one default variant); item with
three sizes; duplicate code differing only in case → 409; SKU duplicated
across two items → 409; two concurrent creates with the same code → one
201, one 409 (unique index); member with the permission only at a BU →
403; plan without `catalog.items` → 403 capability; foreign category id →
404; NUL byte in name → 400; audit record rolls back with a failing insert.

#### C5 — Update an item's profile

**Actor:** as C4 (gated).
**Route:** `PATCH /catalog/items/{itemId}` with optional `If-Match` (C3 ETag).
**Request:** any of `code`, `name`, `description`, and `defaultVariantId`
(with `formerDefaultName` only alongside it) to choose the default variant
(C6).
**Main path:** lock the catalog version row, then `SELECT ... FOR UPDATE`
on the item (lock order, §5) → compare `If-Match`
against the recomputed hash inside the transaction → update →
`catalog.item.updated` with flat `changes[]` (`code`, `before`, `after`).
**Statuses:** `200` with the new ETag; unchanged body → `200`, nothing
written or audited.
**Scenario rows:** rename; code change to a taken code → 409; stale
`If-Match` → 412 with no write; two concurrent PATCHes with the same
`If-Match` → one 200, one 412; archived item → `422 · catalog.item_archived`
(*new*: an archived item is read-only until restored).

#### C6 — Manage variants

**Actor:** as C4 (gated, except deactivation which is ungated).
**Routes:**

* `POST /catalog/items/{itemId}/variants` — add a named variant.
* `PATCH /catalog/items/{itemId}/variants/{variantId}` — `code`, `name`,
  `sku`, sales-quantity policy.
* `PATCH /catalog/items/{itemId}` with `defaultVariantId` (and
  `formerDefaultName` when the current default has no name) — make it the
  default (the old default stays active, `is_default = false`); a variant
  that is not active `422 · catalog.variant_not_active`, a former default
  without a name `422 · catalog.variant_name_required`, a variant of
  another item `404 · catalog.not_found`.
* `POST /catalog/items/{itemId}/variants/{variantId}/transitions` with
  `{ "transition": "deactivate" | "reactivate" | "archive" | "restore" }`,
  the same table and answer shape as C7 (`{ variantId, status }`). A
  restored variant comes back `inactive` with its code, SKU and place among
  the 500 variants of the item (all kept while archived, so nothing else
  needs checking) and its barcodes inactive.
  **Invariants:** exactly one default per item; a named (non-default) variant
  needs a name (`item_variants_named_non_default_chk`); a variant never moves
  to another item (`item_variants_id_item_organization_uq`; catalog namespace
  immutable, `catalog_namespace_immutable`).
  **Concurrency:** the catalog version row first (lock order, §5), then the
  item row `FOR UPDATE`, then the variants, in id order. `If-Match` with the
  item ETag.
  **Audit:** `catalog.item.variant_added`, `catalog.item.variant_updated`,
  `catalog.item.default_variant_changed`, `catalog.item.variant_deactivated`,
  `..._reactivated`, `..._archived`, `..._restored` (resource kind
  `catalog.item`, the variant in the change code, as O11 does with the
  vertical); `catalog.item.variant_restored` is seeded since revision 112
  (migration `0102`, API v7 PR 3); before it a restore was recorded as
  `catalog.item.variant_updated`.
  **Errors:** `422 · catalog.default_variant_required` (*new*: deactivating or
  archiving the default; backstops the deferred trigger), `409 ·
  catalog.code_taken` (`item_variants_item_code_uq`), `409 · catalog.sku_taken`.
  **Scenario rows:** swap default and deactivate the old one in two calls;
  deactivate default → 422; two concurrent default selections on the same
  item → serialised, last wins, exactly one default at commit; variant id of
  another item in the path → 404; changing `salesUnitCode` on a variant already
  sold is allowed (Sales snapshots it; documented consequence).

#### C7 — Deactivate, reactivate, archive, restore an item

**Actor:** `catalog.items.manage` org-wide. `deactivate` and `archive` are
**never capability-gated** (*Decided*: withdrawing something from sale must
work even after a plan downgrade, the "administrator can always repair"
rule); `reactivate` and `restore` are gated by `catalog.items`.
**Route:** `POST /catalog/items/{itemId}/transitions` with optional
`If-Match` (the C3 ETag) and no `Idempotency-Key`: a transition names its
intent, so repeating it is safe.

```json
POST /api/v1/catalog/items/0193…a1/transitions
{ "transition": "deactivate" }

200 OK
ETag: "<strong tag of the whole item, as C3 answers it>"
{ "data": { "itemId": "0193…a1", "status": "inactive" }, "meta": {} }
```

**Transitions:** §4.4; the closed list is `deactivate`, `reactivate`,
`archive`, `restore`, derived from the lifecycle table
(`domain/items/item-lifecycle.ts`). Repeating a transition already in effect
→ `200`, nothing written (as O11). The answer is lean: read the item (C3)
for the rest.
**Effects:** none on assortment rows, barcodes or modifier links; the POS
read stops showing it because the listing rule requires `i.status =
'active'` (`variant_is_listed`, 4487). Existing open sales keep their
snapshot (Sales owns that).
**Audit:** `catalog.item.deactivated`, `.reactivated`, `.archived`,
`.restored`.
**Errors:** `422 · catalog.transition_invalid` (*new*, e.g. `restore` of
an active item, `reactivate` of an archived one); its `detail` teaches
where the item stands, for example `The item is archived; from archived it
allows restore. Read it again and send one of those transitions.` A
transition outside the closed list, or any other field, → `400 ·
foundation.validation_failed`.
**Scenario rows:** each legal transition; each illegal one → 422; archived
item absent from C17 and from `admit` (C20); `reactivate` after a plan
downgrade → 403 capability (`reactivate` and `restore` **are** gated: they
put something back on sale), while `deactivate` and `archive` succeed.

#### C8 — Classify an item

**Actor:** as C4 (gated).
**Route:** `PUT /catalog/items/{itemId}/categories` with `{ categories: [{categoryId, isPrimary}], ... }` (≤ 20 links; at most one primary).
**Main path:** version row, then item `FOR UPDATE` (lock order, §5) →
delete links not in the set → upsert the
rest → one audit record `catalog.item.categories_set` with before/after id
lists. `PUT` because the request carries the complete classification, a
task ("set this item's categories"), not row CRUD.
**Errors:** `422 · catalog.primary_category_conflict` (*new*, two primaries;
backstops `item_categories_one_primary_uq`), `422 ·
catalog.category_archived` for an archived category added to the item (an
inactive one is accepted; a link the item already has may stay after its
category was archived), `404 · catalog.not_found`.
**Scenario rows:** replace set; empty set → item unclassified; idempotent
replay of the same body → 200 without audit.

### 5.3 Categories

#### C9 — Create, rename, move and retire a category

**Actor:** `catalog.items.manage` org-wide (create, edit, move,
`reactivate` and `restore` gated; `deactivate` and `archive` ungated).
**Routes:** `POST /catalog/categories`, `PATCH /catalog/categories/{id}`
(`code`, `name`, `description`, `sortOrder` and, since API v7 PR 3,
`parentCategoryId` (a category id or `null` for the root) to move it in the
same locked transaction; it replaced `POST .../re-parenting`),
`POST /catalog/categories/{id}/transitions` with `{ "transition":
"deactivate" | "reactivate" | "archive" | "restore" }` (API v7 PR 3: it
replaced the three per-verb routes and added `restore`), and since revision
91 `GET /catalog/categories/{id}`.
**Idempotency and preconditions (revision 91):** the create requires
`Idempotency-Key` with the C4 semantics (a retry replays the category as it
is now, even after an edit; the same key with another request answers
`409 · idempotency.key_reused`; a taken code under another key still
answers `409 · catalog.code_taken`). One category is read with its own
strong ETag, a hash of the category as answered, its effective visibility
and depth included; every category write answers that tag and accepts it
in an optional `If-Match` (`412 · foundation.precondition_failed`, never
required). See "Idempotent creates as built".
**Invariants:** no cycle (`categories_prevent_cycle_trg`, 3057, under
`catalog.lock_hierarchy(org,'category')`, 2999 — which also asserts READ
COMMITTED); *Decided* maximum depth 3 (domain rule; a POS cannot render a
deeper tree usefully); the parent must not be archived (an inactive parent
accepts new and moved subcategories, owner decision 2026-10-05); an
organization holds at most 500 categories of any status, archived ones
included because the tree still loads them (`422 ·
catalog.category_limit_reached`, hardening round), so C10 always answers
the whole tree.
**Effects of deactivating a category:** its items stay sellable; the POS
read shows them under "Other" when their primary category is inactive
(*Decided*: hiding products because a folder was hidden surprises owners).
Its subcategories keep their own status and become effectively hidden
(see "Category lifecycle and effective visibility" below).
**Restore (API v7 PR 3):** `archived → inactive` under the same parent,
gated; the code stayed unique and the category kept counting toward the
500, so only its place is judged again: `422 · catalog.category_archived`
while the parent is archived (restore the parent first) and `422 ·
catalog.category_depth_exceeded` if it would nest too deep.
**Audit:** `catalog.category.created`, `.updated`, `.moved`,
`.deactivated`, `.reactivated`, `.archived`, `.restored`; resource kind
`catalog.category`. A `PATCH` that edits and moves writes one `.updated`
and one `.moved` record.
**Errors:** `422 · catalog.category_cycle` (*new*), `422 ·
catalog.category_depth_exceeded` (*new*), `409 · catalog.code_taken`.
**Scenario rows:** move under own descendant → 422; two concurrent moves
creating a cycle together → one fails (advisory lock); depth 4 → 422;
foreign parent id → 404.

#### C10 — Read the category tree

**Actor:** `catalog.items.view` org-wide or at a BU, or
`catalog.sellables.view` at an outlet (the POS needs the tree).
**Route:** `GET /catalog/categories?status=active`.
**ETag:** strong, derived from `catalog_versions.categories_version` since
API v7 PR 7 (migration `0104`); bounded (≤ 500 nodes), not cursor-paged, so
it qualifies under D24. The tag reads `organization:category-tree:<tree version>:<status or all>`, a form no earlier tag can take. The tree version moves only on a category write of
the organization (an insert, a delete, or a change of parent, code, name,
description, sort order or status); item writes, classifications included,
keep the tag. Until PR 7 the tag used the organization-wide version, so any
catalog write invalidated it.
**Scenario rows:** ETag changes on any category write; ETag stays across item
writes and classifications of the same organization; ETag never changes on
another organization's write; old `If-None-Match` after a category rename no
longer gives `304`.

#### Category lifecycle and effective visibility

Owner decisions of 2026-10-05 ("the best for the business"); no SQL object
and no migration. A category has its **own `status`**, set only by its own
lifecycle routes, and an **effective visibility** that is derived, never
stored.

| #   | Rule (*Decided* 2026-10-05)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | A category's status change never changes the status of its descendants                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 2   | A category is effectively active only when it and **all** its ancestors have status `active`; this is computed on every read, never stored                                                                                                                                                                                                                                                                                                                                                         |
| 3   | Reactivating a parent changes no child: each child keeps its own status, so a child that was inactive stays inactive and a child that was active becomes visible again                                                                                                                                                                                                                                                                                                                             |
| 4   | A category lifecycle change never changes any `Item.status` or `Variant.status`                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 5   | An item may belong to several categories, with one primary                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 6   | An **inactive** category may receive new subcategories and be reorganized (children created under it, categories moved under it, its children reactivated). An **archived** category is read-only until it is restored (`restore`, API v7 PR 3): creating a child under it, moving a category under it and editing it answer `422 · catalog.category_archived`. Reactivating a child never looks at the parent's status. The cycle, maximum depth 3, same catalog and same organization rules stay |
| 7   | New classifications (C8, and C4 with `categoryIds`) are refused only for an **archived** category (`422 · catalog.category_archived`); an inactive one is accepted; a link the item already has may stay                                                                                                                                                                                                                                                                                           |
| 8   | The hierarchy is navigation and classification, **not** a source of sellability: K6 and K7 add no category condition to sellability (C17, C19, C20)                                                                                                                                                                                                                                                                                                                                                |
| 9   | Point-of-sale and other read models must hide a branch whose ancestor is not active without touching its descendants (K7 requirement, see C17 and C19). The back-office item list `categoryId` filter and C8 stay as they are: they work on the link, whatever the category's visibility                                                                                                                                                                                                           |
| 10  | The back office distinguishes the own `status` from the effective visibility: every category representation carries `isEffectivelyActive` and `blockedByAncestorId`                                                                                                                                                                                                                                                                                                                                |

**`blockedByAncestorId`** is the id of the **nearest** ancestor whose status
is not `active`; it is `null` when no ancestor hides the category, also
when the category itself is the cause (an inactive category under active
ancestors answers `isEffectivelyActive: false`, `blockedByAncestorId:
null`).

**Example.** *Bebidas* (root) with *Gaseosas* (active) and *Jugos*
(inactive), and *Naturales* (active) under *Jugos*. Deactivating *Bebidas*
answers it with `isEffectivelyActive: false` and `blockedByAncestorId:
null`; the tree then shows *Gaseosas* and *Jugos* with `blockedByAncestorId`
\= *Bebidas*, and *Naturales* with *Jugos* (nearer). Their own status does
not move. Reactivating *Bebidas* makes *Gaseosas* effectively active again,
while *Jugos* stays inactive and *Naturales* stays hidden by it.

**Where it is computed.** In the application layer, from the hierarchy,
with one parent map and a memo, O(n):
`GET /catalog/categories` without `status` and `GET /catalog/workspace`
derive it from the tree they already read in one statement, ordered depth
first, so an ancestor always comes before its descendants and the 500-node
cap never drops the ancestor of a kept node. With a `status` filter the
ancestors may be filtered out, so the read adds one statement, the
organization's hierarchy (`id`, `parent_category_id`, `status`). Every
category write answer (create, edit or move, transition) reads the
written category and then the hierarchy once, in the same transaction. The
item representation's `categories[]` carries no status, so it gains no
field and the item ETag is unchanged by this rule; the tree ETag derives
from the organization-wide catalog version, which every category write
bumps, so a status change of an ancestor changes it.

### 5.4 Barcodes (retail)

#### C11 — Set the barcodes of a variant

**Actor:** `catalog.items.manage` org-wide; a set that adds, brings back,
makes primary or changes a symbology is gated, one that only suspends,
archives or drops the primary never is.
**Route (API v7 PR 4):** `PUT /catalog/items/{itemId}/variants/{variantId}/barcodes`
with `{ barcodes: [{ barcodeId?, barcode, symbology?, isPrimary?, suspended? }] }`,
`If-Match` required (the item tag). It replaced `POST .../barcodes`,
`PATCH .../barcodes/{barcodeId}` and
`POST .../barcodes/{barcodeId}/{deactivation,reactivation}`.
**Validation:** *Decided* check digit validated server-side for `ean13`,
`ean8`, `upca`, `upce` (a mistyped EAN is the most common retail data
error); other symbologies only non-blank and ≤160. At most 20 barcodes,
each value (as a GTIN) and id once, at most one primary.
**Invariants:** unique value among the active barcodes of a catalog (index
`item_variant_barcodes_value_uq`, the final arbiter), one active primary per
variant. A barcode is never deleted and never re-pointed to another variant
(*Decided*: re-pointing would silently change what past scans meant): one
left out of the set is archived (status `archived`, migration `0103`), never
scans, frees its value and no longer counts toward the 20; sending its value
or id again brings it back with the same id. Bringing a value to life fails
when it is active on another variant.
**Audit:** one `catalog.item.barcodes_set` per set change, with the variant
and the live set before and after.
**Errors:** `409 · catalog.barcode_taken`, `422 · catalog.barcode_invalid`,
`422 · catalog.barcode_value_fixed`, `422 · catalog.barcode_not_active`,
`404 · catalog.not_found`, each pointing at its entry (`barcodes[i].barcode`,
`.barcodeId`, `.isPrimary`).
**Scenario rows:** same EAN on two variants → 409; same EAN in two
organizations → both 200; bad check digit → 422; two saves with the same
tag → one 200, one 412.

### 5.5 Modifiers (restaurant first, vertical-neutral)

#### C12 — Define a modifier group and its options

**Actor:** `catalog.items.manage` org-wide; capability `catalog.items`
(*Decided*: no separate capability in v1; OD6).
**Routes:** `POST /catalog/modifier-groups` (`{ code?, name, description?,
options: [{ code?, name, kind: 'instruction'|'catalog_variant',
variantId?, maxQuantity = 1 }] }`, ≤ 50 options; an option has no
default of its own since the hardening round, see C13),
`PUT /catalog/modifier-groups/{groupId}` (API v7 PR 5: the group profile
and its whole ordered option set in one call, `If-Match` required; it
replaced the `PATCH` of the group and the `POST` and `PATCH` of an option,
see "API v7 PR 5 as built"),
`POST /catalog/modifier-groups/{groupId}/transitions` and
`POST /catalog/modifier-groups/{groupId}/options/{optionId}/transitions`
with `{ "transition": "deactivate" | "reactivate" | "archive" | "restore" }`
(API v7 PR 3: they replaced the six per-verb routes and added `restore`,
which brings an archived group or option back as `inactive`; an option only
while its group is not archived).
**Idempotency (revision 91):** the group create requires
`Idempotency-Key` with the C4 semantics. The set needs none: it names the
version it replaces in `If-Match`, so a retry of a set that already landed
answers `412`, and an option sent again by its code takes its id back.
**Invariants:** `instruction` has no variant; `catalog_variant` points to a
variant of the same catalog (`modifier_options_kind_target_chk`, namespace
FK); `maxQuantity` 1–999; an organization holds at most 500 groups of any
status (`422 · catalog.modifier_group_limit_reached`, hardening round), so
the bounded list always answers them all. Deactivating or archiving an
option, deactivating or archiving its group, or deactivating or archiving
the variant a `catalog_variant` option sells removes that option from the
`defaultOptionIds` of every item offer in the same transaction (one
`DELETE`), recorded as the number of offers that lost a default;
reactivating never adds it back. *Decided*: a `catalog_variant` option may point
only to an `active` variant at the time it is set; later deactivation of
that variant hides the option in C17 instead of failing.
**Units, not options (F1, 2026-10-07):** what a group can give an offer is
the sum of the `maxQuantity` of its available options (active, and for a
`catalog_variant` option a target variant and item that are active, the
structural `activeOption` rule of the writes; since K16b the reads also ask the
target to be listed and shown, `availableOption`), the arithmetic of the Sales group check
(`0110_sales.sql`, the sum of `quantity`). Deactivating or archiving an
option, pausing the target of an extra or lowering a `maxQuantity` is never
refused because of the offers that use the group: none of these writes
judges the offers again (C13, K5 design note); an item whose required
minimum the options left can still reach in units stays on sale (one
Cheddar of `maxQuantity` 2 keeps a minimum of two), and one whose minimum
they can no longer reach leaves every reader until an option comes back.
**Audit:** `catalog.modifier_group.created`, `.updated` (one per set, with
`catalog.modifier_group.option_set` before and after since API v7 PR 5),
`.deactivated`, ...; resource kind `catalog.modifier_group`
(`.option_added` and `.option_updated` stay seeded for the records written
before PR 5).
**Scenario rows:** "Cooking point" with three instructions; "Extras" with
`catalog_variant` options; option pointing to another tenant's variant →
404; to an archived variant → 422 `catalog.variant_not_active` (*new*);
to a variant of a combo → 422 `catalog.option_target_not_plain` (K16b);
two sets of one group sent at the same version → the catalog version row
and the group lock serialise them, the second answers `412` (lock order,
§5).

#### C13 — Offer modifier groups on an item

**Actor:** as C4 (gated), except a list that only removes groups (every
group sent is already offered with the same rule, fewer are sent, the empty
list included), which is ungated like a deactivation (owner decision
2026-10-05, "the best for the business": a lapsed plan can always detach).
**Route:** `PUT /catalog/items/{itemId}/modifier-groups` with `{ offers: [{ modifierGroupId, minSelections, maxSelections, defaultOptionIds = [],
suspended = false }], variantOverrides?: [{ variantId, offers: [{ ...,
optedOut = false }] }] }`: `offers` is the ordered item list (≤ 20);
`variantOverrides` (≤ 10 variants per request, API v7 PR 5) replaces the
list of each variant sent. A variant not sent, and every variant when
`variantOverrides` is absent, keeps its overrides; one sent with an empty
list clears them. `If-Match` is required (`428`/`412`).
**Invariants:** `0 ≤ min ≤ max`, `max ≥ 1`, `min ≤` the units the group's
available options can reach, the sum of their `maxQuantity` (domain rule, so
a required group can always be satisfied; since F1, before it the number of
active options, which refused one Cheddar of `maxQuantity` 2 offered with a
minimum of two although Sales and `admit` accept Cheddar × 2); `max` may
exceed those units, as before (the options left may grow, and `admit`
judges each option against its own maximum);
group active. *Decided (owner, hardening round, "the best for the
business")*: the preselected options belong to the offer, not to the
reusable option, so the same group can start "Queso" on the classic burger
and "Tocino, Queso" on the bacon burger; `defaultOptionIds` holds each
option once, at most `maxSelections` of them (an empty list is always
valid), and only options that are active, in an active group, whose
`catalog_variant` target variant and its item are active (`422 ·
catalog.default_options_invalid`; since K8 the command judges it with the
structural `activeOption` fragment of the till, which has no unit; the same answer for an
unknown option, one of another group or of another
organization). A change of defaults is a rule change: gated like any
change that is not a pure removal of groups. *Decided (K14a)*: a default may
start above one unit through the optional `defaultQuantities` (a map by option
id, 1 to 999, only for defaults above one unit; absent means every default
counts one), judged after the defaults (`422 ·
catalog.default_quantities_invalid`: a quantity above the `maxQuantity` of its
option, or units that add up to more than `maxSelections`; a key that is not a
default of the same offer is a `400` at the door); changing only a quantity, up or down, is a rule
change and needs the plan. *Decided (K14b)*: an offer may
lower or withhold an option for itself through the optional `optionLimits` (a
map by option id, 0 to 999, always below the `maxQuantity` of the option, 0 meaning the option is not
offered in this offer; `422 · catalog.option_limits_invalid`), judged before the
rule; the minimum is judged against what the limited options can reach, a
default cannot be an option limited to 0 and a default quantity cannot exceed
the limit; changing only the limits is a rule change and needs the plan. Per-variant offers (`item_variant_id` on the link) were
first decided out of v1 (one offer set per item); **reversed by the owner on
2026-10-07**: per-variant offers ship, a variant-level offer of a group
replacing the item-level one for that variant exactly as the Sales trigger
resolves it, designed in [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md)
(OV9, slices K9f and K9g). Since K9f every reader applies that rule per
variant (C17 to C20); since K9g the variant route below writes them.
**Locks:** the catalog version row first (lock order, §5), then the item
`FOR UPDATE`, then the groups `FOR SHARE` in id order.
**Identity (K9b):** the command never deletes an offer. A group kept in
the list keeps its offer id while its rules or its place change (updated in
place); only a group the item never offered gets a new id; a group left out
is retired (`retired`, its defaults removed) and stays for the rows of
Pricing, Commerce and Sales that reference it; offering it again revives the
same id with the rules sent. A retired offer is a new group for the command:
it must be active and the change is gated. **Suspension (K9g):** a group
sent with `suspended: true` keeps its offer and rule and is written
`inactive` in place; sent again without it, the same id is `active` again.
Suspending a group already offered with the same rule is ungated like a
removal; resuming it, or suspending it with a changed rule, is gated, and a
resume (like any offer becoming `active`, an opt-in included) needs an
active group (`422 · catalog.modifier_group_not_active`) and a valid rule.
**Per-variant lists (K9g; one route since API v7 PR 5):** each entry of
`variantOverrides` (the former `PUT
/catalog/items/{itemId}/variants/{variantId}/modifier-groups`) takes the
same list plus `optedOut` per group and writes the variant scope with the
same identity rules (update in place by `(item_variant_id,
modifier_group_id)`, retire what the list leaves out, revive by the same
key). `optedOut: true` writes an `inactive` variant row whose rule and
defaults are ignored and stored as `0`, `1` and none; a group left out
inherits the item offer again. The variant must belong to the item (else
`404 · catalog.not_found`, like an unknown or foreign one) and not be
archived (`422 · catalog.variant_archived`), both pointing at
`variantOverrides[i].variantId`; an inactive variant may be
configured. Every refusal of a rule points at its offer, for example
`variantOverrides[1].offers[0].minSelections`, and every changed list is
judged and written in the same transaction or none is. `If-Match` is the item's ETag, which covers the variant offers.
An opt-out or a drop is never gated; an override, an opt-in or a reorder
is. The record is the same `catalog.item.modifier_groups_set` on the item,
with `catalog.item.variant` (the variant id) and
`catalog.item.variant.modifier_groups` (the lists) instead of
`catalog.item.modifier_groups`, so no audit action type is added.
**Audit:** `catalog.item.modifier_groups_set` (before/after lists, each
offer as `offerId:groupId:min:max:status`, then its sorted defaults; the
after list ends with the offers this change retired).
**Errors:** `422 · catalog.selection_rule_invalid` (*new*),
`422 · catalog.default_options_invalid` (hardening round).
**Scenario rows:** required group (min 1, max 1); optional multi-select
(min 0, max 3); min greater than the units the available options reach →
422; one option of `maxQuantity` 2 offered with min 2, max 2 → 200 (F1);
group deactivated
after being offered → C17 omits it and, if it was required, omits **the
item** from C17 with a warning counter in `meta` (*Decided*: never sell
something that cannot be configured validly).

### 5.6 Business-unit assortment

#### C14 — Choose how a business unit's assortment works

**Actor:** `catalog.assortment.manage` **at the business unit** (a manager
of one business unit can do this); capability `catalog.items`.
**Route:** `PUT /catalog/business-units/{businessUnitId}/assortment` with
`{ mode: 'all' | 'selected' | 'none' }`.

* `all`: sells every active item of the default catalog except explicit
  exclusions (C15). Same as having no row, which is the SQL default for an
  `organization` access-mode catalog (`variant_is_listed`: `g.id IS NULL AND
  c.access_mode = 'organization'`). Since revision 109 (D1) every business
  unit receives a row when it is registered, and migration `0099` gave every
  earlier unit an explicit active `all` row, so "no row" is left only for
  catalogs other than the default one.
* `selected`: sells only items explicitly listed.
* `none`: the business unit sells nothing from this catalog
  (`business_unit_catalogs.status = 'inactive'`).
  **Main path:** lock the catalog version row (lock order, §5) → upsert the
  `business_unit_catalogs` row (`guard_assortment_change` then locks the
  business unit row, 4460) → audit
  `catalog.assortment.mode_changed` (resource kind `catalog.assortment`).
  **Statuses:** `200`; same mode → `200`, nothing written.
  **Scenario rows:** BU manager of BU-A on BU-A → 200, on BU-B → 403;
  inactive BU → 422 `authorization.place_not_operational`; switching `all`
  → `selected` with no listings empties the POS (documented, and the response
  carries `listedCount: 0` so the UI can warn).

#### C15 — List or delist items at a business unit

**Actor/permission:** as C14 (listing gated; delisting **ungated**).
**Route:** `POST /catalog/business-units/{businessUnitId}/assortment/listing-changes`,
body `{ list?: [...], delist?: [...] }`, up to 200 ids in each list, at
least one id in all, never the same id in both (API v7 PR 7; until then two
routes, `.../listings` and `.../delistings`, with `{ itemIds }`). The plan
gates the change only when `list` names an item.
**Semantics (*Decided*, making the SQL's dual meaning explicit):** in
`selected` mode a listing is an active `business_unit_items` row (an
inclusion); in `all` mode a delisting writes an inactive row (an
exclusion), because `variant_is_listed` already treats `(bi.id IS NULL OR
bi.status = 'active')` that way. The API speaks only of "listed / not
listed"; the repository translates to the row state for the current mode.
**Concurrency:** the catalog version row is locked first (lock order,
§5), which serialises concurrent calls of the organization; then one
set-based upsert, whose trigger also locks the business unit row. Items are
locked `FOR SHARE` in id order after the version row.
**Audit:** one `catalog.assortment.items_listed` record for the items that
started selling and one `.items_delisted` record for the ones that stopped,
each only when its direction changed something, with the id list as the
change (capped at 200 each, so bounded).
**Errors:** `404 · catalog.not_found` (any unknown id: the whole call fails,
nothing written), `422 · catalog.item_archived` when listing an archived
item (as built in K6: an inactive item may be listed and sells once it is
reactivated, so only archival refuses; the code first sketched here,
`catalog.item_not_active`, was never built).
**Scenario rows:** list 200 ids → 200; 201 ids → 400; same id twice → 400;
the same id in `list` and `delist` → 400 pointing at `delist[i]`;
mode `none` → `422 · catalog.assortment_disabled` (*new*, a state refusal:
the catalog keeps `409` for uniqueness clashes); delist works on a
downgraded plan; concurrent list and mode change → serialised by the
catalog version row, which both take first.

#### C16 — Read a business unit's assortment

**Actor:** `catalog.items.view` or `catalog.assortment.manage` at the BU.
**Route:** this is C2 with `businessUnitId` and `listed=true|false`; no
separate route (*Decided*, merged).

### 5.7 Point-of-sale reads (the hot path)

#### C17 — Read what an outlet sells

**Actor:** `catalog.sellables.view` **at the outlet** (cashier, waiter,
sales associate, manager). Not capability-gated (if the catalog is empty
the answer is empty).
**Route:** `GET /catalog/outlets/{outletId}/sellable-items`.
**Main path (one tenant transaction, read-only):**

1. Permission at the outlet (`PermissionCheckContract`, 1 statement).
2. Resolve the effective business unit on the site's date and read
   `catalog_versions.version` and `organization.structure_versions.version`
   (1 statement). Compute a strong ETag
   `"c<catalogVersion>-s<structureVersion>-<businessUnitId>"` (`-none` when
   no business unit operates the outlet today). *Decided*: the server emits
   a strong tag, because the two versions name exactly one body, as a
   strong tag requires (the envelope carries no request id or timestamp).
   The foundation compares as RFC 9110 prescribes: `If-None-Match` uses the
   weak comparison, so `W/"x"` matches `"x"` and answers `304`
   (`satisfiesIfNoneMatch` in
   `src/foundation/http/conditional-requests/conditional-request.ts`, which
   the envelope interceptor and the K7 early `304` share), and
   `If-Match` uses the strong comparison, so a weak tag there answers `412`
   (`src/foundation/http/conditional-requests/conditional-request.ts`).
   If `If-None-Match` matches → `304`, empty body, no further SQL.
3. Otherwise read, set-based, through `catalog.listed_items(org, bu)` (G4):
   active items with active variants (statement A), their primary active
   category ids (in A), offered active modifier groups with active options
   (statement B), the category tree (statement C).
   **K7 requirement (owner decision 2026-10-05, rule 9 of "Category
   lifecycle and effective visibility"):** the tree omits every category
   that is not effectively active, which hides a whole branch below an
   inactive or archived ancestor without changing any descendant; an item
   whose primary category is not effectively active is shown under
   "Other", never dropped. No category condition is added to sellability
   (rule 8).
   **K7 requirement (K5 design note):** when it judges whether an item's
   selection rule can be satisfied (`minSelections` ≤ the sum of the
   `maxQuantity` of the available options since F1; the count of available
   options before),
   the read counts as unavailable every option that is not active, whose
   group is not active, or whose `catalog_variant` target variant is not
   active (inactive or archived) or belongs to an item that is not active
   (since K8: an extra that sells an archived or paused item is not offered;
   since K16b also an extra whose item the unit does not list or the outlet
   hides, or a combo that cannot be composed: the target is judged like the
   component of a combo); an item with a required group whose rule
   is unsatisfiable that way is omitted (C13). The K5 writes do not re-check
   it when an option, a group or a target variant changes later, by design.
   **K7 requirement (hardening round, owner decision):** the point of sale
   preselects exactly the `defaultOptionIds` of the item's offer of each
   group, never a property of the option; since retiring an option, its
   group or its target variant removes it from every offer's defaults in
   the same transaction, every default C17 reads is available.
   **Response (compact by design):**

```text
data: {
  businessUnitId, catalogVersion,
  categories: [{ id, parentId, name, sortOrder }],
  items: [{ id, name, categoryId, variants: [{ id, name, isDefault,
            salesUnitCode, minimumSalesQuantity, salesQuantityStep,
            maximumSalesQuantity }],
            modifierGroups: [{ id, minSelections, maxSelections,
            defaultOptionIds }] }],
  modifierGroups: [{ id, name, options: [{ id, name, kind,
            variantId, maxQuantity }] }],   // de-duplicated
  truncated: boolean
}
```

No descriptions, codes, SKUs or barcodes (payload budget); prices are added
by composition when Pricing ships (the POS reads `sellable-items` and the
price list for the same `catalogVersion`).
**Bounds:** *Decided* at most 2,000 items per response; above that
`truncated: true` and the client falls back to C19 (paged search of what the
outlet sells) and C18 (barcode), both authorized with `catalog.sellables.view`
at the outlet, so a `cashier` or `waiter` never needs `catalog.items.view`
or access to the item master (C2). A retail store with 20,000 SKUs is a
search-and-scan POS, not a scroll POS.
**Outlet with no business unit today:** `organization.effective_business_unit`
returns `NULL` when no active assignment covers the outlet on its site's
date (`0020_organization.sql`, function comment). The permission step runs
first: a member whose scope reaches the outlet only through a business unit
or a legal entity is not covered (no unit resolves) and gets the shared
`403` refusal, while an organization-wide, brand, site or outlet scope still
passes. A caller that passes gets `200` with `businessUnitId: null`, empty
`categories`, `items` and `modifierGroups`, `truncated: false`, and the
ETag ending in `-none`; never `404` or `500`. An inactive outlet keeps the
shared refusal rows (`scope_unavailable` or `outlet_not_operational`).
**Caching:** `ETag` + `Cache-Control: private, no-cache` (tenant data, D24).
**Latency:** `AGENTS.md` §5 targets p50 < 15 ms, p90 < 35 ms, p95 < 50 ms,
p99 < 100 ms. The `304` path is 3 statements on primary-key lookups and
should sit far below p50. The `200` path for a representative restaurant
(300 items, 2 variants, 10 groups × 6 options) must be measured; enters
`perf:http` (§8.4).
**Scenario rows:** happy path restaurant; `selected` assortment; `none`
mode → empty; inactive item absent; inactive variant absent while the item
remains (if it has another active variant); item whose only variant is
inactive absent; required modifier group inactive → item absent (C13);
outlet reassigned to another business unit today → different list and
ETag; outlet assignment effective tomorrow → today's list; 304 after no
change; ETag changes after an unrelated item edit (accepted cost of an
organization-wide version, see §11); cashier scoped to outlet A on outlet B
→ 403; inactive outlet → 403 `authorization.scope_unavailable` or 422
depending on the assignment (as `PermissionCheckContract.decide`); 2,001
items → `truncated`; outlet with no business unit assignment today →
organization-wide caller `200` with empty lists and `businessUnitId: null`,
business-unit-scoped caller `403`; a strong ETag is emitted, and an
`If-None-Match` carrying its weak form `W/"…"` still answers `304` (weak
comparison, RFC 9110), while a weak tag in `If-Match` answers `412`.
**Per variant (K9f, [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §4.2):**
the required groups are judged on the effective offers of each active
variant (an active variant offer replaces the item offer, an inactive one
opts the variant out, a missing or retired one inherits, a suspended item
offer that is required makes the variant not configurable); `variants[]`
keeps only configurable variants, an item is listed while one is, and
`omittedItems` counts an item only when none is. The item-level
`modifierGroups` are unchanged. **K9g** adds the per-variant delta of §5.2
of that design: a listed variant with a live variant row carries
`modifierGroupOverrides: [{ modifierGroupId, optedOut, minSelections,
maxSelections, defaultOptionIds }]`, an opt-out always and an active
override while its group has an available option, in the order of the
rows; a variant without one carries no key at all, so an item without
overrides adds zero bytes. A group only an active variant row offers joins
the top-level `modifierGroups`. The same delta is in C19. Same statements,
same ETag: the catalog version already moves on every offer write.
**Images (A6, AC4 of [`ASSETS_USE_CASES.md`](ASSETS_USE_CASES.md) §7.5):**
every item carries `imageRef` (`<delivery token>/p<profile>`, or `null`)
and `aiGenerated`; a variant carries both only when it has a primary image
of its own, otherwise no key at all and the till shows the item image;
`meta.media.tileUrlTemplate` turns a reference into the tile URL. The read
statement left-joins `catalog.item_assets` through the one-primary indexes
and one `AssetDeliveryContract.describe` call (only when some listed item or
variant has an image) resolves the references, so the `200` costs 9
statements with images and 8 without; the ETag gains `-d<delivery
fingerprint>` (`"c<catalogVersion>-s<structureVersion>-<businessUnitId|none>-d<fingerprint>"`),
computed without SQL, so the `304` stays at 7. C19 adds the same fields per
page. As built in "A6 as built" of `ASSETS_USE_CASES.md`.
**Menus (M2b):** the answer carries a top-level `menus` array, the active
menus the outlet shows (C29) in its order, by ids only: sections and
subsections that are not suspended, and the entries whose item is in the same
sellable set; `variantIds` only on an entry that shows selected variants.
Menus only organize; an outlet without menus answers `menus: []`. Same
statements, same tag. As built in "M2b as built" below; C19 and C18 do not
carry menus.
**Combos (B2c):** a cashier holds `catalog.sellables.view`, never
`catalog.items.view`, so the back-office read of a combo (B1) is closed to
it; C17 therefore carries the composition. An item with at least one active
group carries `bundleGroups`: its active groups in the order the customer
sees them, each with only the choices `admit` accepts now at this outlet,
using the field names of B1 (`bundleGroupId`, `name`, `minSelections`,
`maxSelections`, and per choice `choiceId`, `itemId`, `variantId`,
`quantityPerSelection`, `maxSelectionCount`, `isDefault`). A plain item has
no key at all, byte for byte as before. Never sent: a suspended group, a
suspended choice, a choice whose item or variant is not active, is not listed
at the unit, needs a required modifier group it cannot fill, or is a combo
that cannot be completed there (F1b, F1c), nor an optional group left without
a choice; a combo whose required group cannot be filled is not sold at all
(B2b), so `bundleGroups` can be `[]` only for a combo whose optional groups
have nothing to offer now. A choice names its item by reference: that item
is itself in `items`, with its variants, its modifier groups and, for a
nested combo, its own `bundleGroups`.

```json
{
  "itemId": "01930000-0000-7000-8000-0000000000b0",
  "name": "Combo hamburguesa",
  "categoryId": null,
  "imageRef": null,
  "aiGenerated": false,
  "variants": [
    {
      "variantId": "01930000-0000-7000-8000-0000000000b9",
      "name": null,
      "isDefault": true,
      "salesUnitCode": "unit",
      "minimumSalesQuantity": "1",
      "salesQuantityStep": "1",
      "maximumSalesQuantity": null
    }
  ],
  "modifierGroups": [],
  "bundleGroups": [
    {
      "bundleGroupId": "01930000-0000-7000-8000-0000000000b1",
      "name": "Principal",
      "minSelections": 1,
      "maxSelections": 1,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-0000000000c1",
          "itemId": "01930000-0000-7000-8000-0000000000a1",
          "variantId": "01930000-0000-7000-8000-0000000000a2",
          "quantityPerSelection": "1",
          "maxSelectionCount": null,
          "isDefault": true
        }
      ]
    },
    {
      "bundleGroupId": "01930000-0000-7000-8000-0000000000b3",
      "name": "Acompañamiento",
      "minSelections": 0,
      "maxSelections": 2,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-0000000000c4",
          "itemId": "01930000-0000-7000-8000-0000000000a7",
          "variantId": "01930000-0000-7000-8000-0000000000a8",
          "quantityPerSelection": "1",
          "maxSelectionCount": 1,
          "isDefault": false
        }
      ]
    }
  ]
}
```

A choice is judged where it sits in the combo the till reads: a combo of
`items` judges its choices as the first combo level. Two limits follow and
the till applies them:

* **Depth.** A sale holds at most three combo levels (F1b). The choices of a
  combo met as a component are those it offers when sold on its own, so
  inside the third level the till offers only choices whose item carries no
  `bundleGroups` key (a key with `[]` still counts: that combo has an active
  group); `admit` refuses a deeper selection (`too_deep` request problem, or
  `bundle_too_deep` when the till sends no selection for it).
* **Truncation and search.** The item of a choice is always sellable at the
  outlet, so it is in a complete C17; in a read cut at 2,000 items, or on a
  C19 page, it may be missing and the till finds it by searching.
* **Defaults.** For a group the till does not send, `admit` applies its
  default choices while the choice and its component are active, even one
  C17 hides for its listing or its modifiers, and then refuses the line for
  it; so the till sends every group it shows with the choices the customer
  kept.

The composition is one more column of the same read statement, so the
statement counts and the ETag do not change: every write of a group, a
choice, a component, a listing or a modifier moves the catalog version.
As built in "B2c as built".

#### C18 — Look up a barcode at an outlet

**Actor:** `catalog.sellables.view` at the outlet.
**Route:** `GET /catalog/outlets/{outletId}/barcode-matches?barcode=`.
**Main path:** effective business unit → `catalog.resolve_barcode(org, bu,
barcode)` (4528), which already filters by the listing rule and raises when
ambiguous.
**Response:** `200` with `{ itemId, variantId, name, variantName,
salesUnitCode, quantity policy }`; no match → `200` with `data: null`
(*Decided*: "not found" at a till is a normal outcome, not an error, and a
404 would be logged as noise, D14). Ambiguous across catalogs → `409 ·
catalog.barcode_ambiguous` (*new*; maps `catalog_barcode_ambiguous`,
SQLSTATE 21000). Not ETagged (per-request, tiny).
**Note:** `resolve_barcode` takes `FOR SHARE` locks (4504–4526); for a pure
read this is heavier than needed. *Decided*: C18 uses a read-only twin
query without locks; the locking function stays for `admit` (C20).
**Scenario rows:** scan listed item; scan delisted item → null; scan
suspended or archived barcode → null; same barcode in another organization → null;
latency in `perf:http`; since K9f a variant that is not configurable under
its own effective offers → null, while the other variants of the item still
resolve.

#### C19 — Search what an outlet sells

**Actor:** `catalog.sellables.view` **at the outlet** (cashier, waiter,
sales associate, manager), exactly as C17 and C18. Never `catalog.items.view`:
the till searches what it may sell, not the item master. Not
capability-gated.
**Intent:** the fallback of C17 when the outlet sells more than 2,000 items
(`truncated: true`), and the ordinary "type a few letters" search of a
retail POS.
**Route:** `GET /catalog/outlets/{outletId}/sellable-item-search?q=&barcode=&cursor=&limit=`.

* `q`: prefix match on the item or variant name, case-insensitive, 1–80
  characters, `%` and `_` escaped (same rule as C2, §8.3).
* `barcode`: exact match on an active barcode of an active variant; `q` and
  `barcode` are mutually exclusive and one of them is required (`400`
  otherwise).
* Keyset order `(lower(name) COLLATE "C", id)`, `limit` default 50, max 100,
  signed opaque cursor bound to the outlet, the business unit resolved for
  it and the filter (`collection.cursor_incompatible` when any differs).
  **Main path (one tenant transaction, read-only):** permission at the outlet
  (1) → effective business unit on the site's date (1) → one set-based page
  query through `catalog.listed_items(org, bu)` (G4): only items listed for
  that business unit with at least one active variant, so not-sellable items
  (inactive, archived, delisted, or with no active variant) never appear; an
  item whose required modifier group cannot be satisfied by its available
  options (judged exactly as in C17: an inactive option, an inactive group or
  an inactive or archived target variant, or one whose item is not active,
  counts as unavailable, and since K16b one whose item the unit delists or the
  outlet hides) does not
  appear either.
  **Response:** the item shape of C17 (`id, name, categoryId, variants[],
  modifierGroupIds[]`) plus `meta.pageInfo`; `categoryId` follows the same
  K7 rule as C17 (a category that is not effectively active is not offered as
  navigation, and the item is never dropped for it); no codes, SKUs, descriptions or
  barcodes beyond the one matched. Not ETagged (a cursor page, D24). Since B2c
  a combo carries the same `bundleGroups` as in C17; the item of a choice may
  sit on another page.
  **Outlet with no business unit today:** as C17: the permission step decides
  first; a caller that passes gets `200` with an empty page.
  **Scenario rows:** outlet with 2,001 items, C17 answers `truncated: true`
  and C19 pages through all of them for a `cashier` and for a `waiter` that
  hold only `catalog.sellables.view`; the same `cashier` gets `403` from C2
  (no `catalog.items.view`); name prefix search, case- and accent-variant
  input; barcode exact match and a barcode of a delisted item → empty page;
  cursor stability under a concurrent item insert (no duplicate, no skip);
  a cursor from another outlet or another `q` → `400 ·
  collection.cursor_incompatible`; inactive item, archived item, item whose
  only variant is inactive and item delisted at the unit absent; `q` and
  `barcode` together → `400`; `limit=101` → `400`; cashier scoped to outlet A
  searching outlet B → `403`; tenant isolation with identical names in two
  organizations. Since K9f the page keeps only the configurable variants of
  each item, judged exactly as C17.

### 5.8 Internal contract

#### C20 — Resolve and admit a sellable variant (Pricing, Sales)

**No HTTP route.** `CatalogSellableContract` (D18, read and synchronous
modes):

* `resolve(ctx, { businessUnitId, variantIds[] })` → snapshots
  `{ variantId, itemId, itemName, variantName, salesUnitCode, quantity
  policy, sellable: boolean }` for Pricing configuration screens and Sales
  draft building; one set-based statement.
* `admit(ctx, { businessUnitId, lines: [{ variantId, quantity, selections: [{ optionId, quantity }] }] })` (as built since K9d; K8 took
  `modifierOptionIds[]`) → runs
  `catalog.assert_variant_listed` (4504) inside the caller's tenant
  transaction (as built, K8 reads the rule set-based instead and never calls
  it; see "K8 as built") (it takes `FOR SHARE` on the business unit, variant, item and
  catalog, so a concurrent archival cannot slip between admission and the
  sale insert) and validates modifier options against the item's offer and
  selection rules. Throws `CatalogNotSellableError` (Sales maps it to its own
  public code).
  **Scenario rows:** admitted variant; archived between `resolve` and `admit`
  → refused; concurrent archival blocks until the sale commits (FOR SHARE vs
  FOR UPDATE); option not offered on the item → refused; min/max violated →
  refused; foreign variant → refused without leaking existence. Since K9d
  ([`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §4.4): one option chosen
  twice → admitted with `quantity: 2`; a group's min/max judged on the sum of
  units; an option above its `maxQuantity` → `option_quantity_above_maximum`;
  a line quantity off the variant's sales policy → `quantity_out_of_policy`;
  an option quantity outside 1–999 or not an integer, or a malformed line
  quantity → `invalid_quantity` before any SQL. Since K9e
  ([`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §5.1): `resolve` answers
  the effective offers of each variant inside its snapshot
  (`itemModifierGroupId`, `modifierGroupId`, `source`, min, max, the options
  with the sales unit of each target variant), and `admit` answers each line
  with its `lineIndex` and its effective offers, each holding the line's
  selections with everything a Sales modifier row stores and the removed and
  reduced defaults; the rows built from that answer alone pass the real Sales
  modifier trigger and group check. Since K9f
  ([`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §4.2): the offers are the
  variant's effective offers, `source: variant` with the override's id when an
  active variant offer applies, none for a group the variant opted out of (its
  options answer `option_not_offered`), and a variant whose effective required
  groups cannot be met answers `required_modifier_unsatisfiable` while its
  siblings are admitted. Since migration `0090` (X13 closed) Sales agrees:
  a line of an opted-out variant without selections, admitted here, passes
  the Sales group check, and a selection through the item offer on that
  variant is refused as not offered.

### 5.9 Status of the later cases

Current status of the cases that were deferred when this design was written
(the table was last revised at Catalog = 56 operations, OpenAPI 13.12.0,
baseline revision 125; at revision 178 the Catalog tag has 138 operations). Every case in
this table is built; the routes are the ones in the OpenAPI document.

| Case                                 | Status                                                                                                                                                                                                                                                                                                                                                                                                  | Route or reference                                                                                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| C21 Menus and outlet menu assignment | Built: M1 structure ("M1 as built"), M2a assignment (C29, "M2a as built"), M2b till read by menu                                                                                                                                                                                                                                                                                                        | `GET`, `POST /catalog/menus`, `GET`, `PATCH /catalog/menus/{id}`, `PUT .../structure`, `POST .../{activation,archival}`; `GET`, `PUT /catalog/outlets/{id}/menus`; `menus` in the sellables read |
| C30 Items an outlet does not sell    | Built: K16 ("K16 as built")                                                                                                                                                                                                                                                                                                                                                                             | `GET`, `PUT /catalog/outlets/{id}/hidden-items`                                                                                                                                                  |
| C32 Variant dimensions               | Built: K13 ("K13 as built"): the matrix writes them, the item read shows them, the list offers them as filters                                                                                                                                                                                                                                                                                          | `GET /catalog/variant-dimensions`; `variantValue` in `GET /catalog/items`                                                                                                                        |
| C22 Bundles / combos                 | Built: B1 composition, B2 admission (C28), B2c `bundleGroups` in the till and the search; B3 waits for Pricing and Sales                                                                                                                                                                                                                                                                                | `GET`, `PUT /catalog/items/{id}/bundle-groups`                                                                                                                                                   |
| C26 Images                           | Built                                                                                                                                                                                                                                                                                                                                                                                                   | `PUT /catalog/items/{id}/images`, `PUT /catalog/item-images`                                                                                                                                     |
| S1 Menu time windows                 | Built: C31 ("S1 as built"); holidays and date ranges deferred                                                                                                                                                                                                                                                                                                                                           | `windows` in `PUT /catalog/outlets/{id}/menus`; `menusValidUntil` in the sellables read                                                                                                          |
| C23 Translations                     | Built (9.z): per-record translations, offered languages, `locale` on the main reads                                                                                                                                                                                                                                                                                                                     | `PUT /catalog/{entity}/{id}/translations/{locale}`                                                                                                                                  |
| C24 Food declarations | Built: allergens, dietary tags and nutrition ("9.aa B2 as built") |
| C25 Additional catalogs              | Built in parts: the clone (CL1, CL2), the registry of catalogs, its rename and its transitions (CA2, "CA2 as built"); the assignment of a catalog to a business unit (CA3) and reading and writing by catalog (CA4) are built; the whole flow is under "Multiple catalogs, step by step" | `GET /catalog/catalogs`, `POST /catalog/catalogs`, `GET`/`PATCH /catalog/catalogs/{catalogId}`, `POST /catalog/catalogs/{catalogId}/transitions`, `POST /catalog/catalogs/{catalogId}/clones`    |
| C27 Import                           | Built: I1 judges a document with `dryRun` ("I1 as built"), I2 applies it ("I2 as built"), I3 reads an applied import back ("I3 as built"), I4a imports modifier groups and options ("I4a as built"), I4b imports the item-level offers of those groups ("I4b as built"), I4c imports the overrides of the variants ("I4c as built"), CL1 builds the database side of the catalog clone ("CL1 as built") | `POST /catalog/imports`                                                                                                                                                                          |

### 5.10 Derived API

This table is the route design of the first delivery. Several routes were
reshaped afterwards (the lifecycle verbs are `POST .../transitions` since API v7
PR 2, "API v7 PR 2 as built") and many were added; the OpenAPI document, not this
table, lists the routes that exist.

| Group                 | Routes                                                                                                                                                                                                                                 | Cases                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| Workspace and reads   | `GET /catalog/workspace`, `GET /catalog/items`, `GET /catalog/items/{id}`, `GET /catalog/categories`, `GET /catalog/categories/{id}`                                                                                                   | C1, C2, C3, C9, C10, C16 |
| Items                 | `POST /catalog/items`, `PATCH /catalog/items/{id}`, `POST /catalog/items/{id}/{deactivation,reactivation,archival,restoration}`, `PUT /catalog/items/{id}/categories`, `PUT /catalog/items/{id}/modifier-groups`                       | C4, C5, C7, C8, C13      |
| Variants and barcodes | `POST /catalog/items/{id}/variants`, `PATCH .../variants/{vid}`, `POST .../variants/{vid}/default-selection`, `POST .../variants/{vid}/{deactivation,reactivation,archival}`, `PUT .../variants/{vid}/barcodes` (the set, API v7 PR 4) | C6, C11                  |
| Categories            | `POST /catalog/categories`, `PATCH /catalog/categories/{id}` (moves too since API v7 PR 3), `POST /catalog/categories/{id}/transitions`                                                                                                | C9                       |
| Modifiers             | `POST /catalog/modifier-groups`, `PATCH`, options, lifecycle                                                                                                                                                                           | C12                      |
| Images                | `PUT /catalog/items/{id}/images` with `images` and optional `variants`, `PUT /catalog/item-images` with an optional `ifMatch` per entry (Assets slices A5b and A5c, `ASSETS_USE_CASES.md` §7.5; merged in API v7 PR 4)                 | AC1, AC2, AC3, AC5       |
| Combos                | `GET /catalog/items/{id}/bundle-groups`, `PUT /catalog/items/{id}/bundle-groups` (B1)                                                                                                                                                  | C22                      |
| Menus                 | `GET /catalog/menus`, `POST /catalog/menus`, `GET /catalog/menus/{id}`, `PATCH /catalog/menus/{id}`, `PUT /catalog/menus/{id}/structure`, `POST /catalog/menus/{id}/{activation,archival}` (M1)                                        | C21                      |
| Assortment            | `PUT /catalog/business-units/{id}/assortment`, `POST .../assortment/{listings,delistings}`                                                                                                                                             | C14, C15                 |
| Outlet menus          | `GET /catalog/outlets/{id}/menus`, `PUT /catalog/outlets/{id}/menus` (M2a; the windows of S1)                                                                                                                                          | C29, C31                 |
| Outlet hidden items   | `GET /catalog/outlets/{id}/hidden-items`, `PUT /catalog/outlets/{id}/hidden-items` (K16)                                                                                                                                               | C30                      |
| POS                   | `GET /catalog/outlets/{id}/sellable-items`, `GET /catalog/outlets/{id}/barcode-matches`, `GET /catalog/outlets/{id}/sellable-item-search`                                                                                              | C17, C18, C19            |
| Internal              | `CatalogSellableContract`                                                                                                                                                                                                              | C20                      |

*Decided:* routes carry the `/catalog` prefix (Organization routes do not)
because `items`, `categories` and `variants` are words other modules
(inventory, pricing) will also use; the prefix keeps OpenAPI tags and
throttling per module unambiguous.

***

## 6. Vertical variations

### 6.1 Common vs vertical-specific

| Concept                       | Restaurant                          | Retail                      | Hospitality                      | Where it lives                          |
| ----------------------------- | ----------------------------------- | --------------------------- | -------------------------------- | --------------------------------------- |
| Item + default variant        | Dish, drink                         | Product                     | Service/extra (laundry, minibar) | Catalog, common                         |
| Named variants                | Sizes (small/large), presentations  | Size, colour, pack          | Rarely                           | Catalog, common                         |
| SKU                           | Optional                            | Usually                     | Optional                         | Catalog, common                         |
| Barcodes                      | Bottled drinks only                 | Core                        | Minibar                          | Catalog, common                         |
| Sales unit and step           | `unit`                              | `unit`, `kg` (step 0.050)   | `unit`                           | Catalog, common (`item_variants`)       |
| Categories                    | Starters, mains, drinks             | Departments                 | Service families                 | Catalog, common                         |
| Modifiers                     | Core (cooking point, extras, sides) | Rare (gift wrap, engraving) | Room-service dishes              | Catalog, common                         |
| Bundles/combos                | Combo meals                         | Kits                        | Packages                         | Catalog later + Pricing                 |
| Menus, sections, dayparts     | Core later                          | Not needed                  | Room-service menu                | Catalog later (G1)                      |
| Course, prep station, routing | Yes                                 | —                           | —                                | Kitchen (vertical)                      |
| Allergens, nutrition | Yes | Food retail | Room service | Catalog (built, 9.aa B2 as built) |
| Rooms, room types             | —                                   | —                           | Yes                              | Hospitality (Phase 10), **not** catalog |
| Stock tracking of an item     | Optional                            | Yes                         | Minibar                          | Inventory (`supply_routes`)       |

Two more businesses were weighed on 2026-10-05 (owner decision: design only,
nothing in the database, no vertical code):

| Business           | What the catalog gives it                                                                                                                                                        | What is NOT catalog                                                                                                                                     |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gym                | A membership, a pass or a single class is a sellable item with its default variant (a service)                                                                                   | Renewal, validity, class capacity and access control: modules that do not exist yet                                                                     |
| Clothing (apparel) | Technically retail: products, SKUs, barcodes; the size × colour matrix is a catalog capability delivered with K4 (variants), shared with footwear and any variant-heavy business | Seasons and collections, exchanges and returns, stock per size: other modules. No separate vertical code unless its roles or screens differ from retail |

**Conclusion (*Decided*):** the catalog has no vertical-specific table in the
first delivery. Every concept above in the "Catalog" column is shared. This
matches `ROADMAP.md` Phase 8 ("The restaurant vertical should not duplicate
Catalog") and R8.

### 6.2 How business-unit verticals apply

`platform.business_unit_verticals` (activated by O11) does **not** gate
catalog commands: catalog commands pass no `p_vertical_code` (*Decided*;
a core module never asks "is this a restaurant", `ARCHITECTURE.md` §14).
Verticals act in two places only:

1. **UX:** the client reads the verticals of the selected business unit from
   `GET /session/context` (`workspace.businessUnits[].verticals`) and shows
   modifiers-first screens for restaurant and barcode-first screens for
   retail. The server accepts the same commands from both.
2. **Roles:** the vertical roles of D30 (`waiter`, `kitchen`, `bar`,
   `sales_associate`, `stock_keeper`) receive catalog permissions (§7.2);
   the D30 offer rule already prevents offering `waiter` where restaurant is
   inactive.

Vertical modules (kitchen, restaurant service) will consume
`CatalogSellableContract` and add their own facts by FK to
`catalog.item_variants` / `categories`, never by writing catalog tables (R5).

***

## 7. Authorization design

### 7.1 Permission codes

Format `module.resource.action` (three segments required by
`permissions_code_chk`, `0040_identity.sql`).

| Code                        | Grants                                                                                                             | Anchor checked                                                                                             | Capability gate                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `catalog.items.manage`      | Create and edit items, variants, barcodes, categories, modifier groups, combos and menus; lifecycle of all of them | Organization-wide only (v1; OD3)                                                                           | `catalog.items` for create/edit/reactivate; none for deactivate/archive |
| `catalog.items.view`        | Back-office reads C1–C3, C10, C16, C21 (menus), C22 (combos)                                                       | Organization-wide, or a business unit (with `businessUnitId`)                                              | none                                                                    |
| `catalog.assortment.manage` | C14, C15                                                                                                           | Business unit (`authorize_operation_at('business_unit')`); an organization-wide scope also satisfies it    | `catalog.items` for listing and mode changes; none for delisting        |
| `catalog.sellables.view`    | C10, C17, C18, C19                                                                                                 | Outlet (`PermissionCheckContract` with `outletId`, which also accepts broader scopes covering that outlet) | none                                                                    |

*Decided:* no `catalog.items.create` / `.update` split. Owners and managers
asked for "who can edit the products"; splitting create from edit is a
distinction no current role uses (D30 rejects ranks expressed outside
permissions; a split can be added later without breaking codes).

### 7.2 Seeded role mapping (proposal, per D30)

D30 says each module adds its permissions to the seeded roles in its own
migration and also to `organization_owner` (containment rule of D29).

| Role (`vertical_code`)     | `catalog.items.manage`                                  | `catalog.items.view` | `catalog.assortment.manage` | `catalog.sellables.view` |
| -------------------------- | ------------------------------------------------------- | -------------------- | --------------------------- | ------------------------ |
| `organization_owner` (—)   | ✓                                                       | ✓                    | ✓                           | ✓                        |
| `manager` (—)              | ✓ (effective only with an organization-wide assignment) | ✓                    | ✓                           | ✓                        |
| `cashier` (—)              |                                                         |                      |                             | ✓                        |
| `waiter` (restaurant)      |                                                         |                      |                             | ✓                        |
| `kitchen` (restaurant)     |                                                         |                      |                             |                          |
| `bar` (restaurant)         |                                                         |                      |                             |                          |
| `sales_associate` (retail) |                                                         | ✓                    |                             | ✓                        |
| `stock_keeper` (retail)    |                                                         | ✓                    |                             |                          |

Reasoning: a `manager` assigned to one business unit gets
`catalog.items.manage` in its role but `effective_permission` with no outlet
requires an organization-wide scope, so it can curate its unit's assortment
(C14/C15 at the BU anchor) without editing the shared master data that other
units sell; the same role assigned organization-wide edits everything. This
is exactly the "catalog manager scoped to one business unit" that
`identity.effective_permission_at` was built for (the test fixture already
uses `test.catalog.manage`, `database/tests/shared/anchored-permission-fixture.ts:25`).
Kitchen and bar receive nothing: they read item names on kitchen tickets
through the Kitchen module, not the catalog. `sales_associate` needs search
to answer "do we have it in blue?". `stock_keeper` needs lookup for
receiving (Inventory, later).

### 7.3 Capability gating

*Decided:* one capability, `catalog.items` ("Products and catalog"), seeded
into `platform.capabilities` and attached to a new active plan version of
`pionero` (the pattern of migration `0071`: create version N+1, copy
capabilities and limits, activate, publish offerings).

| Never gated (repair and read)                                       | Gated by `catalog.items`                                                           |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| All reads (C1–C3, C10, C16–C19)                                     | Create/edit items, variants, barcodes, categories, groups (C4–C6, C8, C9, C11–C13) |
| Deactivate / archive anything (C6, C7, C9, C11, C12)                | Reactivate / restore (puts something back on sale)                                 |
| Detach modifier groups from an item (C13, a list that only removes) | Attach a group or change a selection rule (C13)                                    |
| Delist (C15 delistings)                                             | Assortment mode, listings (C14, C15 listings)                                      |
| `CatalogSellableContract`                                           | —                                                                                  |

Order of refusal is the one `platform.authorize_operation` already
guarantees: a caller without the permission never learns about the plan
(`0071` function comment).

***

## 8. Performance and data design

### 8.1 Expected cardinalities (assumption, to validate with real tenants)

| Profile          | Items                                    | Variants   | Barcodes        | Categories | Modifier groups / options | Business units |
| ---------------- | ---------------------------------------- | ---------- | --------------- | ---------- | ------------------------- | -------------- |
| Small restaurant | 50–300                                   | 1.2× items | ~0.1×           | 5–20       | 5–30 / 20–200             | 1              |
| Restaurant group | 300–1,500                                | 1.5×       | ~0.2×           | 20–60      | 30–150 / 200–1,000        | 2–10           |
| Small retail     | 500–5,000                                | 2×         | 1–1.5× variants | 10–100     | 0–5                       | 1              |
| Larger retail    | 5,000–50,000                             | 2–3×       | 1–2×            | 100–500    | 0–10                      | 1–20           |
| Hotel            | 20–300 services + F\&B unit as restaurant | 1×         | rare            | 5–30       | as restaurant             | 2–4            |

All master tables grow with configuration, not with traffic; none grows
without bound per day. `business_unit_items` is the largest multiplier
(items × units in `selected` mode): 50,000 × 20 = 1M rows in the worst case.

### 8.2 Hot queries and indexes

| Query                                   | Existing index                                                                                                                  | Needed (new migration)                                                                                                                                                                                                                                                                   |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C2 list by name, status, keyset         | `catalog_items_organization_status_idx (organization_id, status, name)` (123) — no `catalog_id`, no `id` tiebreak, no `lower()` | `items (organization_id, catalog_id, status, lower(name) COLLATE "C", id)`; replaces the old one only after `EXPLAIN (ANALYZE, BUFFERS)` proves it unused                                                                                                                                |
| C2 prefix on name                       | none usable                                                                                                                     | covered by the index above (`COLLATE "C"` makes `LIKE 'abc%'` indexable)                                                                                                                                                                                                                 |
| C2 prefix on code                       | `catalog_items_code_ci_uq (organization_id, catalog_id, lower(code))` (4426)                                                    | a `text_pattern_ops` twin only if the plan shows the unique index is not used for prefix                                                                                                                                                                                                 |
| C2 prefix / exact on SKU                | `item_variants_sku_ci_uq` (4430)                                                                                                | same remark                                                                                                                                                                                                                                                                              |
| C17 variants of listed items            | `item_variants_item_status_idx (organization_id, item_id, status)` (255)                                                        | none                                                                                                                                                                                                                                                                                     |
| C17 listing in `selected` mode          | `business_unit_items UNIQUE(business_unit_id, item_id)`                                                                         | none                                                                                                                                                                                                                                                                                     |
| C17 offered groups                      | `item_modifier_groups_item_idx` (2027), `modifier_options_group_status_idx` (1875)                                              | none                                                                                                                                                                                                                                                                                     |
| C17 primary category                    | `item_categories_one_primary_uq` (471)                                                                                          | none                                                                                                                                                                                                                                                                                     |
| C18 barcode → variant                   | `item_variant_barcodes_value_uq (organization_id, catalog_id, barcode)` (4431)                                                  | with one catalog this is an exact lookup; when OD4 brings several catalogs, add `(organization_id, barcode)`                                                                                                                                                                             |
| C19 page of listed items by name prefix | none for the listed-and-name order                                                                                              | the C2 index `items (organization_id, catalog_id, status, lower(name) COLLATE "C", id)` drives the order; listing joins `business_unit_items UNIQUE(business_unit_id, item_id)`; `EXPLAIN (ANALYZE, BUFFERS)` on the "larger retail" profile decides whether a dedicated index is needed |
| C19 barcode                             | `item_variant_barcodes_value_uq` (4431)                                                                                         | none                                                                                                                                                                                                                                                                                     |
| `catalog_versions` read                 | PK (G2)                                                                                                                         | —                                                                                                                                                                                                                                                                                        |

Every new query on `items`, `item_variants` and `business_unit_items`
passes `EXPLAIN (ANALYZE, BUFFERS)` on the "larger retail" profile before
merge (D24).

### 8.3 Search strategy

*Decided:* prefix only, on name, code and SKU, case- and accent-insensitive,
under the `C` collation. Both sides go through one immutable SQL function,
`catalog.search_key(text)` (migration `0078`): it lowercases the text and
folds the Latin accents with `translate` (`áàâäãå`, `éèêë`, `íìîï`,
`óòôöõ`, `úùûü`, `ñ`, `ç`, `ýÿ` and their capitals; `ß` becomes `ss`),
so the stored keys and the searched text can never drift; `unaccent` is not
used because it is an extension and is not immutable, which a stored
generated column requires. Reason: `pg_trgm` is not installed (`0000_extensions.sql`
creates only `btree_gist`), adding an extension is an operations change, and
POS/back-office searches are typed from the start of a word. Known cost:
the order follows the folded lowercase key in `C` byte order, so it ignores
locale rules (`Ñandú` sorts as `nandu`, between `nabo` and `nata`); the
list is still stable and keyset-safe. Substring or fuzzy search
(`pg_trgm` GIN) is a later decision driven by measured complaints.

### 8.4 What `perf:http` must measure

| Route                                                    | Class          | Why                               |
| -------------------------------------------------------- | -------------- | --------------------------------- |
| `GET /catalog/outlets/{id}/sellable-items` (200 and 304) | hot            | Every POS start and every refresh |
| `GET /catalog/outlets/{id}/barcode-matches`              | hot            | Every retail scan                 |
| `GET /catalog/outlets/{id}/sellable-item-search?q=`      | hot            | POS search on a large outlet      |
| `GET /catalog/items?q=`                                  | frequent       | Back-office search                |
| `GET /catalog/workspace`                                 | frequent       | Back-office landing               |
| `POST /catalog/items`, `PATCH /catalog/items/{id}`       | administrative | Not in `perf:http` (D24)          |

Fixture: a "representative world" catalog (restaurant 300 items; retail
20,000 variants) added to `tooling/performance/http/representative-world.ts`;
1 client and 16 clients; standard budget from `AGENTS.md` §5. A local run
never proves production capacity (`AGENTS.md` §5 last paragraph).

### 8.5 Statement budget

| Route                                                     | Statements (target)                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C17 `304`                                                 | tenant context (1, migration `0066`) + permission (1) + versions and BU (1) = **3**                                                                                                                                                                                                                                                                |
| C17 `200`                                                 | 3 + items/variants (1) + groups/options (1) + categories (1) = **6**                                                                                                                                                                                                                                                                               |
| C18                                                       | 3 + lookup (1) = **4**                                                                                                                                                                                                                                                                                                                             |
| C19                                                       | 3 + page (1) = **4**                                                                                                                                                                                                                                                                                                                               |
| C4 create                                                 | context, authorization, version row lock, `ensure_default_catalog`, item, variants (one multi-row insert), links, audit, commit = **≈9**                                                                                                                                                                                                           |
| C22 `PUT` (B1)                                            | session (2) + `BEGIN` + context + permission + version row lock + composition lock + capability + components + retire groups + upsert groups + retire choices + upsert choices + re-read + audit + `COMMIT` = **16**, whatever the number of groups; **8** for an unchanged composition                                                            |
| C22 `GET` (B1)                                            | session (2) + `BEGIN` + context + permission + composition + `COMMIT` = **7**                                                                                                                                                                                                                                                                      |
| C3 `GET` item (API v7 PR 6)                               | session (2) + `BEGIN` + context + permission + the item in one statement + `COMMIT` = **7**, plus one `describe` when the item or a variant has an image; 11 before PR 6, when the read was five statements (`test/e2e/statement-budget.e2e-spec.ts` › `creates, reads, answers 304 for, edits and classifies an item in the measured statements`) |
| C3 `304` (API v7 PR 6)                                    | the same **7**: the tag is a hash of the representation, which holds the delivery status and URLs of the images and the names and statuses of shared modifier groups and options, so it is computed from the one-statement read                                                                                                                    |
| C4 create, C5 `PATCH`, `PUT .../categories` (API v7 PR 6) | **14**, **10** and **13** (18, 14 and 21 before): the create and the `PATCH` read the item once, so each saves four statements; the categories `PUT` reads it under the lock and again for the answer, so it saves eight                                                                                                                           |

A use case that needs more than these numbers is a design smell to review,
not a hard gate.

***

## 9. Delivery slices

Each slice is one PR into `staging`, ≤ 400 changed lines where possible,
with its tests, docs and case-matrix rows (`AGENTS.md` §7). Sizes: S 1–2 h,
M 3–5 h, L 6 h+ of agent work.

| #      | Slice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Cases                                                              | Depends on | Size                                                | Risk                                                 | Security-critical                               |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------- | --------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| **K1** | Catalog foundations in SQL: migration with runtime grants on `catalog` (USAGE; SELECT/INSERT/UPDATE on the v1 tables; DELETE only on `item_categories` and `item_modifier_groups`, the latter revoked by K9c in revision 101; EXECUTE on `ensure_default_catalog`, `lock_hierarchy`, `assert_variant_listed`, `resolve_barcode`, `variant_is_listed`), `catalog_versions` (G2) with triggers, `listed_items` (G4), four permissions + role mapping (§7.2), capability `catalog.items` + pionero next version, audit resource kinds and action types. SQL contract tests (`database/tests/contracts/`) including "runtime cannot DELETE an item", "listed\_items ≡ variant\_is\_listed" | —                                                                  | —          | M                                                   | High                                                 | **Yes** (grants, RLS reach, permissions)        |
| **K2** | Module skeleton + create/read/update/lifecycle of items with default variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | C3, C4, C5, C7                                                     | K1         | M                                                   | Medium                                               | Yes (first tenant writes; authorization wiring) |
| **K3** | List/search, workspace, categories                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | C1, C2, C8, C9, C10                                                | K2         | L (split K3a reads / K3b categories if > 400 lines) | Medium                                               | No                                              |
| **K4** | Variants, SKU, barcodes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | C6, C11                                                            | K2         | M                                                   | Medium                                               | No                                              |
| **K5** | Modifier groups and item offers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | C12, C13                                                           | K2         | M                                                   | Medium                                               | No                                              |
| **K6** | Business-unit assortment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | C14, C15, C16                                                      | K1, K3     | M                                                   | High (BU-anchored authorization, dual row semantics) | **Yes** (anchored permission)                   |
| **K7** | POS reads + perf                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | C17, C18, C19, `perf:http` rows, EXPLAIN evidence, index migration | K3–K6      | L                                                   | High (hot path)                                      | No                                              |
| **K8** | `CatalogSellableContract`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | C20                                                                | K6         | S                                                   | Medium                                               | Yes (admission atomic with sales)               |

Default order: K1 → K2 → K3 → K5 → K4 (OD1: restaurant first) → K6 →
K7 → K8. K4 and K5 are independent; the order follows OD1.

### K1 as built (migration `0075_catalog_foundations`, baseline revision 85)

| Piece                   | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime grants          | `USAGE` on `catalog`; `SELECT, INSERT, UPDATE` on `catalogs`, `items`, `item_variants`, `item_variant_barcodes`, `categories`, `item_categories`, `modifier_groups`, `modifier_options`, `item_modifier_groups`, `business_unit_catalogs`, `business_unit_items`; `DELETE` only on `item_categories` (and on `item_modifier_groups` until revision 100: K9c revokes it, an offer is retired and never deleted); `SELECT` and `UPDATE (version)` on `catalog_versions`. Every other catalog table has no grant; `ninaku_worker` gets nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Functions               | `EXECUTE` on `ensure_default_catalog`, `lock_hierarchy`, `variant_is_listed`, `assert_variant_listed`, `resolve_barcode`, `listed_items` and also `assert_item_default_variant`: the deferred default-variant trigger calls it as the writing role, so an item insert fails at commit without it. `lock_bundle_graph`, `assert_bundle_composition_acyclic` and the two version trigger functions stay barred                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| RLS                     | Every granted table already had a tenant policy with the scalar subquery and `WITH CHECK` on writes; no gap was found. `catalog_versions` gets one `FOR ALL` tenant policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `catalog_versions` (G2) | One row per organization, created by the trigger `organizations_catalog_version_insert_trg` when the organization is inserted (provisioning or any other path) and backfilled by the migration, never lazily by `ensure_default_catalog`: the runtime then needs no `INSERT` on the table and the row exists before the first catalog write. Statement-level triggers with transition tables on the eleven tables above bump it once per `INSERT`, `UPDATE` or `DELETE` statement. Each bump takes the row lock until commit, so catalog writes of one organization serialize on it, and every catalog command locks the row `FOR UPDATE` before any other row (lock order, §5). The `BEFORE UPDATE` trigger `catalog_versions_step_trg` (`catalog.guard_catalog_version_step`) lets the version move only forward by exactly one and never to another organization (`catalog_version_step`, `23514`), so the runtime's `UPDATE (version)` grant cannot roll a version back (stale `304`) or push it to the `bigint` maximum (every later write failing with `22003`) |
| `listed_items` (G4)     | `catalog.listed_items(organization, business unit)` returns `(item_id, item_variant_id)`, `STABLE`, `SECURITY INVOKER`, pinned `search_path`, PL/pgSQL so it can refuse another organization with `42501` (an unknown or foreign business unit answers an empty set). Its predicate is the one of `variant_is_listed`; `database/tests/contracts/catalog-listing-differential-contracts.ts` proves both agree on eight units (no row, `all` with an exclusion and an active row, `selected` with listings of active, inactive and archived items, assortment off, inactive unit, `selected` with only an exclusion, a foreign unit, an unknown unit) and an extra catalog in `assigned` mode, with zero differences                                                                                                                                                                                                                                                                                                                                                   |
| Permissions             | The four codes of §7.1, mapped exactly as §7.2; organization-defined roles are untouched                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Capability              | `catalog.items` on a new Pionero version 4 (copy of version 3 plus the capability); version 3 is retired, which retires its offerings, and no subscription moves (see `SUBSCRIPTION_PLANS_USE_CASES.md`, "Catalog capability rollout")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Audit                   | Resource kinds `catalog.item`, `catalog.category`, `catalog.modifier_group`, `catalog.assortment`; the 36 action types named in §5, category `configuration`, retention class `administration.platform` (R16), tenant scope, risk `medium`. Where §5 writes "..." for modifier groups, K1 seeds `reactivated`, `archived` and the option lifecycle (`option_deactivated`, `option_reactivated`, `option_archived`) that its routes name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Generic tags (OD9)      | `tag_groups`, `tag_group_translations`, `tags`, `tag_translations`, `item_tags`, `menu_tags` dropped; nothing outside them referenced them. `dietary_tags` stays                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Update lists            | UPDATE is granted on whole tables; K2 repositories never put `item_id`, `organization_id`, `catalog_id` or `created_at` in an UPDATE `SET` list (§5, "Update lists"): `SET item_id = ...` on `item_variants`, even to the same value, fires the bundle-graph guard triggers and fails closed with `42501`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Not in K1               | G3 (`items.creation_idempotency_key`) belongs to C4, so K2 adds it; G5 adds no column (the application sets `updated_at`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### K2 as built (migration `0076_catalog_item_creation_is_idempotent`, baseline revision 86)

| Piece                        | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Module                       | `src/modules/catalog/` with `domain/` (code generation, lifecycle transitions, profile changes, sales quantities: pure TypeScript), `application/` (four use cases, `CatalogAccess`, ports), `infrastructure/` (item and catalog version repositories) and `presentation/` (controller, DTOs, failures); registered in `AppModule`. It imports only `identity/contracts`, `platform/contracts` and `audit/contracts`; the module boundary check needed no new rule. `contracts/` arrives with `CatalogSellableContract` (K8): an empty layer would be dead code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Routes                       | `POST /catalog/items` (`201`), `GET /catalog/items/{itemId}` (`200`, `304`), `PATCH /catalog/items/{itemId}` (`200`), `POST /catalog/items/{itemId}/{deactivation,reactivation,archival,restoration}` (`200`, one transitions route since API v7 PR 2, C7); every route behind `SessionGuard` and `TenantContextGuard`, errors as Problem Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Authorization                | Gated commands (create, edit, reactivation, restoration) call `OperationAuthorizationContract` with `catalog.items.manage` and `catalog.items` and no anchor, so only an organization-wide scope satisfies them and the order of `platform.authorize_operation` holds: tenant context, permission, scope, capability. Deactivation and archival call `PermissionCheckContract` organization-wide and never ask about the plan. The read calls `PermissionCheckContract` with `catalog.items.view` first, anchored at a business unit when `businessUnitId` is sent; only when that check refuses and the caller holds the permission organization-wide does it look the unit up, and an unknown unit then answers `404 · organization.structure_not_found`. Every other refused caller gets the same `403 · catalog.action_forbidden` for an existing unit, an unknown unit and no unit, so a member cannot probe which unit ids exist. Every refused command leaves one denied tenant audit record whose reason is the decision (`permission_missing`, `scope_unavailable`, `capability_not_entitled`) and whose target is the item id of the path (or the organization for a create), even when the caller lacks the permission and the id names nothing; the volume of those records is bounded only by the rate limiter. No catalog route sets its own limit: like the Organization write routes, they fall under the global `ThrottlerGuard` of `RateLimitModule` (`DEFAULT_RATE_LIMIT`, 120 requests per minute per client IP, behind one trusted proxy hop); only some Identity routes declare a stricter `@Throttle`. Reads record nothing |
| Refusal mapping              | `catalog/presentation/failures`: `permission_missing` and `tenant_context_missing` answer `403 · catalog.action_forbidden`, `scope_unavailable` `403 · authorization.scope_unavailable`, `capability_not_entitled` `403 · platform.capability_not_entitled`; any other refusal answers exactly the plain denial, so a caller without the permission never learns about the plan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Codes                        | Item codes and SKUs are unique per organization and catalog, ignoring case (`catalog_items_code_ci_uq` and `item_variants_sku_ci_uq` on `(organization_id, catalog_id, lower(...))`); with one default catalog per organization today that is the whole organization. `catalog.action_forbidden`, `catalog.not_found`, `catalog.code_taken`, `catalog.sku_taken`, `catalog.item_archived`, `catalog.transition_invalid`, `catalog.unit_unknown`, `catalog.quantity_policy_invalid`, plus the reused `foundation.validation_failed`, `foundation.precondition_failed`, `idempotency.key_reused`, `idempotency.in_progress` and `organization.structure_not_found`. `catalog.item_refused` and `catalog.default_variant_required` are not built: no K2 path reaches them (the create always writes the default variant and K2 never changes a variant's status)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Lock order                   | Every command decides authorization first, then locks `catalog.catalog_versions` `FOR UPDATE`, then the item row `FOR UPDATE OF i` (edit and transitions). The create calls `ensure_default_catalog` after the version lock, so a generated code is chosen while the organization's catalog writes are serialized: parallel creates of one name get `base`, `base-2`, `base-3` with no conflict                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Update lists                 | `UPDATE catalog.items` sets only `code`, `name`, `description`, `status` and `updated_at`; a unit test fails if a `SET` list names `item_id`, `organization_id`, `catalog_id` or `created_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Item code (OD2)              | Optional; when omitted the server takes the name, strips accents, lowercases it, turns every run of other characters into one hyphen, bounds it to 60 characters (so a suffix fits the 80 of the column) and falls back to `item` when nothing is left; on collision it takes the lowest free `-N` from 2, ignoring case. Editable with `PATCH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Idempotency (G3)             | One new column, `catalog.items.creation_idempotency_key uuid`, with the partial unique index `catalog_items_creation_idempotency_uq (organization_id, creation_idempotency_key) WHERE creation_idempotency_key IS NOT NULL`: the claim lives in the module's own table, as `FOUNDATION_HTTP_AND_OBSERVABILITY.md` §7 prescribes, and `API_AND_SCHEMA_DISCIPLINE.md` admits it because a named use case (a retried create) reads and writes it and no other table holds the fact. The use case reuses `resolveIdempotentClaim`: the claim is `INSERT ... ON CONFLICT (organization_id, creation_idempotency_key) DO NOTHING`, the existing item is found by its key, and the intent matches when the name, the description, the explicit code (when sent) and the default variant's SKU, unit and quantities (compared in their shortest decimal form) equal the stored item. A replay answers `201` with the item and `Idempotent-Replayed: true`; another request with the same key `409 · idempotency.key_reused`. Because the claim is the item itself, the replay compared with the item as it is now, so a retry after an edit answered `409 · idempotency.key_reused`. *Closed in revision 91* ("Idempotent creates as built"): the hash of the original request is stored next to the key and a late retry replays the item as it is now                                                                                                                                                                                                                                                                                                    |
| Item representation and ETag | C3 answers the item and its `variants[]` (all of them, default first); barcodes, categories and modifier groups join the representation, and so its hash, in the slices that write them (K3 to K5). The strong ETag is the SHA-256 of the item as answered, so two equal representations share one tag (an edit that is undone gives the old tag back). Write answers (`201`/`200`) carry the ETag of the item they return and `Cache-Control: private, no-store` through `HttpTaggedWriteResponse` (foundation), never answer `304`, and do not declare the header in OpenAPI, where a declared ETag means a conditional read; the read declares it with `ApiConditionalRead`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Lifecycle (OD8)              | §4.4 as decided: a transition already in effect answers `200` and records nothing; reactivating an archived item and restoring an active one answer `422 · catalog.transition_invalid`; restoration returns to `inactive`; an archived item is readable but its profile answers `422 · catalog.item_archived`. Every write accepts an optional `If-Match` with the item's ETag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Performance                  | `GET /catalog/items/{itemId}` is classified frequent and not measured yet (the representative world has no catalog until K7); the commands are administrative                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### K3 as built (migration `0077_catalog_items_are_searchable_by_prefix`, baseline revision 87)

| Piece                            | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Routes                           | `GET /catalog/workspace` (`200`), `GET /catalog/items` (`200`), `GET /catalog/categories` (`200`, `304`), `PUT /catalog/items/{itemId}/categories` (`200`), `POST /catalog/categories` (`201`), `PATCH /catalog/categories/{categoryId}` (`200`), `POST /catalog/categories/{categoryId}/re-parenting` (`200`, folded into `PATCH /catalog/categories/{categoryId}` since API v7 PR 3), `POST /catalog/categories/{categoryId}/{deactivation,reactivation,archival}` (`200`, one transitions route with `restore` since API v7 PR 3)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Read authorization               | The three reads share K2's rule (§5, "K2 as built"): `catalog.items.view` organization-wide or at the business unit named by `businessUnitId`, checked before any lookup; only an organization-wide reader learns that a unit is unknown. Never gated by the plan. The tree is not yet readable with `catalog.sellables.view` at an outlet: that anchor arrives with the point-of-sale reads (K7), which carry the tree anyway                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Search evidence (§8.2, §8.3)     | Under row level security PostgreSQL only uses a filter as an index condition when every function in it is leakproof; `lower()`, `LIKE` and record comparison are not, so on a seeded catalog of 20,000 items an expression index on `lower(name)` still scanned the organization: a page after a cursor read 7,158 buffers and filtered 9,861 rows. Migration `0077` adds three stored generated keys under the `C` collation, `items.name_search_key`, `items.code_search_key` and `item_variants.sku_search_key` (each `lower()` of its column until migration `0078` replaced it with `catalog.search_key()`), and the indexes `catalog_items_name_search_idx (organization_id, catalog_id, status, name_search_key, id)`, `catalog_items_code_search_idx` and the partial `item_variants_sku_search_idx`. Keyset comparison on `(name_search_key, id)` and `starts_with(key, lower(q))` are leakproof, so both become index conditions. The shipped statement, which also joins the page's default variant, variant count and primary category, measured locally on that catalog (16,000 active items, 60 categories): first page 2.1 ms, a page after a cursor 0.8 ms (725 buffers), a backward page 0.7 ms, a rare prefix 0.7 ms, a common prefix 1.9 ms. The widest prefix (`p-`, the code prefix of all 16,000 active items) gathers every match before ordering it: 25.7 ms and 7,768 buffers; a local single-machine run, not a capacity claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| C2 list and search               | Order `(name_search_key, id)`; `q` is a prefix of the name, the code or any SKU after trimming, 1 to 80 characters, compared without case and without accents since migration `0078` (`catalog.search_key`, see "Leftovers closed"), and `%`, `_` and backslash are literal because the search never uses `LIKE`. `status` defaults to `active`; `categoryId` keeps the items linked to that category, primary or not, and an unknown or foreign category lists nothing. `listed` is not built: it reads the assortment of K6. The cursor binds the route, the organization, the status, `q`, `categoryId` and `businessUnitId`, and is decoded only after the view permission is granted: a refused member gets the plain `403` whatever cursor it sends, an authorized one the `collection.cursor_*` failures                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| C1 workspace                     | `catalog` is `null` until the first catalog write creates the default catalog; reading never creates it. `counts` per status, the tree (at most 500 nodes, the creation cap, so no truncation flag), the first page of active items with a cursor `GET /catalog/items` accepts with the same `businessUnitId` (the cursor binds it, so a reader assigned to one unit pages on at that unit), `assortment.mode` of the named unit (`all` without a row, `none` when its row is inactive), and `allowedActions`: `edit` when `catalog.items.manage` organization-wide and the plan allow it, `retire` when the permission does; computing them records no refusal. Classified frequent, not hot, so it has no statement budget row                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| C10 tree                         | One statement: the catalog version and the tree, depth first by `sortOrder`, lowercase name and id, each node with its depth, at most 500 (the creation limit, so always the whole tree; `meta.truncated` was removed in the API v7 foundation, `meta` is `{}`). The strong ETag was `organization:version:categories-<status or all>`; in v1 any catalog write of the organization changed it (the C02 correction), a write of another organization never does. Since API v7 PR 7 it is `organization:category-tree:<tree version>:<status or all>` and only category writes change it. A `status` filter keeps a child of an excluded parent with its `parentCategoryId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| C9 categories                    | The code is required (a retried create answered `409 · catalog.code_taken` instead of duplicating; since revision 91 the create also requires `Idempotency-Key` and a retry replays). Every command locks the version row, then the category `FOR UPDATE`, then reads the organization's hierarchy to judge a parent: unknown or foreign `404 · catalog.not_found`, under itself or a descendant `422 · catalog.category_cycle`, archived `422 · catalog.category_archived` (until 2026-10-05 any parent that was not active answered `422 · catalog.category_not_active`, a code that no longer exists), deeper than three levels counting the moved branch `422 · catalog.category_depth_exceeded`. Only acyclicity is also enforced in SQL (`catalog.prevent_category_cycle` through `categories_prevent_cycle_trg`, and `categories_not_self_parent_chk`); the depth limit of three and the parent that is not archived are enforced in the domain only, under the version row lock. `categories_prevent_cycle_trg`, `categories_not_self_parent_chk`, `categories_code_ci_uq` and the parent foreign keys are mapped as backstops. What a parent's lifecycle does to its subcategories is decided in "Category lifecycle and effective visibility" (§5.3, owner decision 2026-10-05): they keep their own status, are hidden by it through the derived `isEffectivelyActive` and `blockedByAncestorId`, and can be reactivated whatever the parent's status. Archiving is final (no restoration route; K1 seeded no `catalog.category.restored`): an archived category answers `422 · catalog.category_archived` to an edit or a move and `422 · catalog.transition_invalid` to a reactivation. Category writes carried no ETag and accepted no `If-Match` until revision 91, which added the per-category tag and `GET /catalog/categories/{categoryId}` ("Idempotent creates as built"); the tree keeps its organization-wide tag. `UPDATE` lists name only `code`, `name`, `description`, `sort_order`, `parent_category_id`, `status` and `updated_at` |
| C8 classification                | The item is locked after the version row; then the requested categories are read `FOR SHARE` in id order. A category added to the item must not be archived (`422 · catalog.category_archived`; since 2026-10-05 an inactive one is accepted); one it already had may stay after it was archived. The links are replaced by one `DELETE` and one multi-row `INSERT`, so moving the primary never trips `item_categories_one_primary_uq`. One `catalog.item.categories_set` record keeps `catalog.item.categories` (sorted ids) and, when it changes, `catalog.item.primary_category`. The item representation of C3 gains `categories[]` (primary first, then name) and so does its hash: every item tag changed once with K3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Migration 0077, operational note | It adds stored generated columns, which rewrite `catalog.items` and `catalog.item_variants` under an `ACCESS EXCLUSIVE` lock, and builds its three indexes without `CONCURRENTLY`. That is acceptable now because no production catalog exists yet; any later change of this kind on these tables needs an online approach (nullable column backfilled in batches, `CREATE INDEX CONCURRENTLY` outside the migration transaction)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Not built in K3                  | `categoryIds` and `primaryCategoryId` in `POST /catalog/items` and a measured `perf:http` scenario for the three reads; both are closed below ("Leftovers closed")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Leftovers closed (migration `0078_catalog_search_ignores_accents`, baseline revision 88)

| Piece                                                    | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| C4 categories in the create                              | `POST /catalog/items` accepts `categoryIds` (at most 20, each once) and `primaryCategoryId` (one of them; without `categoryIds`, or outside them, `400`). The links are written in the transaction of the item, after the catalog version row, the item and its default variant, with the categories read `FOR SHARE` in id order: an unknown or foreign category answers `404 · catalog.not_found`, an archived one `422 · catalog.category_archived` (since 2026-10-05; an inactive one is accepted), and nothing is created. The `catalog.item.created` record gains `catalog.item.categories` and `catalog.item.primary_category`; no `catalog.item.categories_set` record is written. The replay compares the classification too, so the same key with other categories answers `409 · idempotency.key_reused`. C8 and C4 share one check (`usable-categories.ts`)                                                  |
| Classification failures                                  | The repository maps both foreign keys from a link to a category, `item_categories_category_organization_fk` (the one PostgreSQL checks first) and `item_categories_category_id_catalog_fk`, to `404 · catalog.not_found`, and `item_categories_one_primary_uq` to `422 · catalog.primary_category_conflict`; before, an unknown category reaching the `INSERT` answered `500`. A repeated category id never reaches the use case: both request schemas refuse it with `400`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Accent-insensitive search                                | `catalog.search_key(text)` is `IMMUTABLE`, `STRICT` and `PARALLEL SAFE`, has a SQL-standard body and is executable by `ninaku_runtime`; `0078` sets the three generated columns to it with `ALTER COLUMN … SET EXPRESSION`, which rewrites `catalog.items` and `catalog.item_variants` under an `ACCESS EXCLUSIVE` lock and rebuilds their indexes, keeps the column order, and is acceptable while no production catalog exists (same note as `0077`). The list applies the same function to `q`; the keyset order stays `(name_search_key, id)` and the plan keeps the prefix and the cursor as index conditions under row level security (`database/tests/contracts/catalog-search-key-contracts.ts`). Item codes are ASCII by their check, so the code key only lowercases in practice. No index was added on the code key: the code is only matched as a prefix inside the name-ordered list, never paged by itself |
| Hierarchy depth check                                    | The height of a moved branch is computed level by level and stops after four levels or at a repeated node, so a corrupted cycle or a very deep chain answers `422 · catalog.category_depth_exceeded` instead of overflowing the stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Workspace                                                | The counts are copied field by field into the strict response. An organization that never wrote its catalog reads an empty tree under one stable strong tag (its `catalog_versions` row exists from provisioning) and gets `304` for it. A named unit without a `business_unit_catalogs` row answers `assortment.mode: all`, which is what `variant_is_listed` decides for the default catalog, whose `access_mode` is always `organization` (`catalogs_default_scope_chk`)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Performance                                              | `perf:http` seeds one catalog of 2,000 items (1,800 active), 64 categories in three levels and one or two links per item, and measures `GET /catalog/items` (first page, page six after a cursor, `q=cafe`), `GET /catalog/workspace` and `GET /catalog/categories` (`200` and `304`), with 1 and 16 clients; results in `docs/operations/PERFORMANCE_BASELINE.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Category lifecycle and effective visibility (2026-10-05) | Built as decided in §5.3: the placement judge refuses only an archived parent (`catalog.category_archived`), reactivation no longer judges the parent, C4 and C8 refuse only an archived category, and every category representation (`GET /catalog/categories`, the categories of `GET /catalog/workspace`, every category write answer) carries `isEffectivelyActive` and `blockedByAncestorId`, derived by `domain/categories/category-visibility.ts`. The public code `catalog.category_not_active` was removed: nothing raises it any more. No SQL object, no migration, the baseline stays at revision 88                                                                                                                                                                                                                                                                                                          |
| Replay after an edit                                     | Closed in revision 91 (owner decision): a retry with the same `Idempotency-Key` after the item was edited replays the item as it is now, because the hash of the original request is stored next to the key ("Idempotent creates as built")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### K5 as built (no migration, baseline revision 88)

| Piece               | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema              | No migration. `modifier_groups`, `modifier_options` and `item_modifier_groups` (K1 grants, RLS, catalog namespace triggers, statement-level version bumps) already hold every fact C12 and C13 need, and K1 seeded every audit action type the routes use. Nothing about prices, price deltas, stock or recipes is stored or answered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Routes              | `POST /catalog/modifier-groups` (`201`), `GET /catalog/modifier-groups` (`200`), `GET /catalog/modifier-groups/{modifierGroupId}` (`200`, `304`), `PATCH /catalog/modifier-groups/{modifierGroupId}` (`200`), `POST /catalog/modifier-groups/{modifierGroupId}/{deactivation,reactivation,archival}` (`200`, one transitions route with `restore` since API v7 PR 3), `POST /catalog/modifier-groups/{modifierGroupId}/options` (`201`), `PATCH /catalog/modifier-groups/{modifierGroupId}/options/{optionId}` (`200`), `POST /catalog/modifier-groups/{modifierGroupId}/options/{optionId}/{deactivation,reactivation,archival}` (`200`, one transitions route with `restore` since API v7 PR 3), `PUT /catalog/items/{itemId}/modifier-groups` (`200`); every route behind `SessionGuard` and `TenantContextGuard`, errors as Problem Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Authorization       | As K2 and K3: writes need `catalog.items.manage` organization-wide; create, edit, option add and edit and both reactivations are gated by `catalog.items`; deactivations and archivals never ask about the plan. The offer checks the plain permission first, and only after the item is locked asks about the plan, and only when the list adds a group, changes a rule or the order: a list that only removes groups (and an identical list) is ungated, so a lapsed plan can detach groups. A refused command leaves one denied record whose target is the group of the path (the organization for a create, the item for an offer). The two reads need `catalog.items.view` organization-wide or at `businessUnitId`, checked before any lookup, never gated, recording nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Codes               | New: `422 · catalog.modifier_group_archived`, `422 · catalog.modifier_option_archived`, `422 · catalog.modifier_group_not_active`, `422 · catalog.variant_not_active` (named in C12), `422 · catalog.selection_rule_invalid` (named in C13), `422 · catalog.option_order_incomplete`, `422 · catalog.modifier_group_full` (review fix). Reused: `catalog.action_forbidden`, `catalog.not_found`, `catalog.code_taken`, `catalog.transition_invalid`, `catalog.item_archived`, `foundation.precondition_failed`, `foundation.validation_failed`, `organization.structure_not_found`. The detail of `foundation.precondition_failed` no longer says "the item", since a group answers it too. `modifier_groups_code_ci_uq`, `modifier_options_group_code_uq`, the variant and group foreign keys and `item_modifier_groups_selection_chk` are mapped as backstops, never shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Group (C12)         | The group code is required, unique per catalog ignoring case, so a retried create never duplicates; since revision 91 the create also requires `Idempotency-Key` and a retry replays the group as it is now instead of answering `409` ("Idempotent creates as built"). Up to 50 options per create, in the order sent (`sortOrder` 0, 1, ...); an option code is optional there and derived from its name like an item code, `-2`, `-3` within the group, `option` when nothing is left. `kind` is `instruction` (no target) or `catalog_variant` with `variantId`, which must name an existing variant of the organization (`404` otherwise) that is `active` at that moment (`422 · catalog.variant_not_active`); its later deactivation changes nothing here. `maxQuantity` 1 to 999; `isDefault` was free, several defaults allowed (the selection rules live on each item, so a group cannot know how many defaults fit); superseded by the hardening round, where the defaults belong to each item offer. `PATCH` edits the code, the name and the description and, with `optionOrder`, the whole order: every option of the group, whatever its status, exactly once. Lifecycle as categories: deactivation, reactivation, archival; archiving is final (K1 seeded no `restored` action), an archived group is readable and stays offered where it already was, and it and its options refuse every change with `catalog.modifier_group_archived` |
| Option (C12)        | `POST .../options` appends an active option, and refuses it with `422 · catalog.modifier_group_full` when the group already holds 50 options of any status (archived options count: they are still loaded, hashed and named by `optionOrder`); its code is required (since revision 91 the add also requires `Idempotency-Key`, so a retry replays the group instead of answering `409`, "Idempotent creates as built"), unique within the group ignoring case, checked under the group lock and backstopped by `modifier_options_group_code_uq`. `PATCH` changes code, name, description and `maxQuantity` (`isDefault` until the hardening round); kind and variant never change (archive and add another, so a past sale keeps its meaning). Lifecycle deactivation, reactivation, archival; an archived option refuses edits with `catalog.modifier_option_archived` and reactivation with `catalog.transition_invalid`. Reactivation does not judge the variant again. No option lifecycle changes the group, another option or any item (rule h)                                                                                                                                                                                                                                                                                                                                                                                                    |
| Group ETag          | Strong, the SHA-256 of the group and its options as answered, like the item; `GET` answers `Cache-Control: private, no-cache` and `304` on `If-None-Match`; every group and option write accepts the group tag in `If-Match` (`412` when stale, nothing written) and answers the new tag with `Cache-Control: private, no-store`. The list is bounded (500 groups, the creation limit, so always whole; `meta.truncated` was removed in the API v7 foundation, `meta` is `{}`), not cursor-paged and not tagged                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Offer (C13)         | `PUT /catalog/items/{itemId}/modifier-groups` replaces the ordered list (at most 20, each group once) with `minSelections` 0 to 999 and `maxSelections` 1 to 999 per group; the list order is the `sort_order`. Domain rules: minimum not above the maximum nor above the units the available options of the group can reach, the sum of their `maxQuantity` judged with `activeOption`, the structural half of the till's rule, which has no unit (`422 · catalog.selection_rule_invalid`; F1, before it the count of active options); a group added to the item must be active (`422 · catalog.modifier_group_not_active`); a group the item already offers with the same rule stays even if it was deactivated, archived or lost its options since, and is judged again only when its rule changes. Unknown or foreign group or item `404 · catalog.not_found`; archived item `422 · catalog.item_archived`; an inactive item accepts it. One offer set per item: `item_variant_id` is always null (per-variant offers out of v1, as C13 decided). The links are replaced by one `DELETE` scoped to `item_variant_id IS NULL` (so a variant-scoped row, which no route writes today, is never removed unaudited) and one multi-row `INSERT`; one `catalog.item.modifier_groups_set` record keeps `catalog.item.modifier_groups` before and after as `groupId:min:max` in order; the same list again answers `200` and records nothing                  |
| Item representation | C3 gains `modifierGroups[]` in offer order: the group id, code, name and own status, the item's `minSelections` and `maxSelections`, and every option of the group with its status. The item ETag hashes it, so every item tag changed once with K5, and renaming an offered group or editing, adding, reordering or retiring one of its options changes the tag of every item that offers it (the rename, an option edit and an option deactivation are proven over HTTP)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Lock order          | Every command takes the `catalog.catalog_versions` row `FOR UPDATE` first, then the group row `FOR UPDATE OF g` (group and option commands) or the item row (offer), then shares the referenced variants (`FOR SHARE OF v`) or the offered groups (`FOR SHARE OF g`) in id order. A refused command locks nothing, except an offer refused for the plan, which is decided after the item lock because only the stored list tells whether it merely removes groups. `UPDATE` lists never name `item_id`, `organization_id`, `catalog_id`, `created_at`, `modifier_group_id`, `option_kind` or `item_variant_id` (a unit test checks the statements)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Performance         | `GET /catalog/modifier-groups` and `GET /catalog/modifier-groups/{modifierGroupId}` are classified frequent and not measured (the scenarios seed no modifier groups yet); the commands are administrative. The item read gains two statements (offers, their options)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Still open          | Point-of-sale use of the groups (C17 hides inactive groups and options and an item whose required group is unusable, counting an option whose group is not active or whose `catalog_variant` target is inactive or archived as unavailable; see the K7 requirement in C17 and C19; the K5 writes never re-check it) is K7; `admit` validation of options is K8; a creation key for groups was built in revision 91 ("Idempotent creates as built"), while the group code stays required; the where-used read (which items offer a group) was built in revision 92 ("Contract step and where-used as built")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### K4 as built (migration `0079_catalog_barcodes_are_unique_while_active`, baseline revision 89)

| Piece            | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema           | One migration. `item_variant_barcodes_value_uq` becomes partial (`WHERE status = 'active'`): the K1 index made a value unique among all barcodes, inactive ones included, which contradicted C11 ("to move it, deactivate and add on the other variant; reactivation fails if the value is now active elsewhere"); now a retired barcode frees its value. The audit action `catalog.item.barcode_updated` is seeded for the barcode edit. No column and no table: the size by colour attributes live only in the variant code and name, so the vertical stays neutral. Superseded by revision 119 (K13): the matrix now also writes structured dimensions, see "K13 as built"; the code and the name stay as described here. No new grant (K1 already grants `SELECT, INSERT, UPDATE` on both tables)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Routes           | `POST /catalog/items/{itemId}/variants` (`201`), `PATCH /catalog/items/{itemId}/variants/{variantId}` (`200`), `POST .../variants/{variantId}/default-selection` (`200`, folded into `PATCH /catalog/items/{itemId}` since API v7 PR 2), `POST .../variants/{variantId}/{deactivation,reactivation,archival}` (`200`, one transitions route with `restore` since API v7 PR 2, C6), `POST /catalog/items/{itemId}/variant-matrix` (`201`, or `200` when already in effect), `POST .../variants/{variantId}/barcodes` (`201`), `PATCH .../barcodes/{barcodeId}` (`200`), `POST .../barcodes/{barcodeId}/{deactivation,reactivation}` (`200`), `GET /catalog/outlets/{outletId}/barcode-matches` (`200`, C18) and `GET /catalog/barcode-matches` (`200`, back office); every route behind `SessionGuard` and `TenantContextGuard`, errors as Problem Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Answers and tags | Every write answers the whole item (C3 shape) with its strong ETag and `Cache-Control: private, no-store`, and accepts the item tag in `If-Match` (`412` when stale, nothing written). `variants[]` gains `barcodes[]` (`barcodeId`, `barcode`, `symbology`, `isPrimary`, `status`; active first, primary first), so every item tag changed once with K4, and a variant or barcode change changes the item tag. Both lookups answer `Cache-Control: private, no-cache` and no ETag: a scan is a per-request answer (C18 "not ETagged")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Authorization    | Writes need `catalog.items.manage` organization-wide; add, edit, default selection, matrix and both reactivations are gated by `catalog.items`; deactivations and archival never ask about the plan. A refused command leaves one denied record targeting the item of the path and locks nothing. The till lookup checks `catalog.sellables.view` at the outlet first; only a caller holding it organization-wide learns that an outlet does not exist (`404 · organization.structure_not_found`), everyone else gets the plain `403`. The back-office lookup uses the read rule of K2 (`catalog.items.view` organization-wide or at `businessUnitId`). Lookups never ask about the plan and record nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Variants (C6)    | The code is required and unique within the item ignoring case (`409 · catalog.code_taken`, also the backstop of `item_variants_item_code_uq`), so a retried add never duplicates and needs no `Idempotency-Key`. The create of an item still carries no named variants: they are added afterwards, one by one or as a matrix. At most 500 variants per item, archived ones included (`422 · catalog.item_variants_full`). The default variant can never be deactivated or archived (`422 · catalog.default_variant_required`), whatever the item status, so reactivating an item never fails at commit; only an active variant can become the default (`422 · catalog.variant_not_active`). The default selection releases the former default first and then sets the new one, two statements in one transaction, because `item_variants_one_default_per_item_uq` is not deferrable; since a variant that is not the default must have a name, a nameless former default needs `formerDefaultName` (`422 · catalog.variant_name_required`). Archiving a variant is final (no restoration route, as §3.2 says): reactivation answers `422 · catalog.transition_invalid` and an edit `422 · catalog.variant_archived`. Archiving a variant, and archiving an item (also on a lapsed plan, since archival is never gated), deactivates its active barcodes in the same transaction, recorded once as `catalog.item.barcode_deactivated` with the barcode and its status before and after for each, so their values are free for other variants; restoring the item or reactivating anything never reactivates them, and archiving again writes nothing. No lifecycle of a variant changes the item or another variant. An archived item refuses every variant and barcode command with `422 · catalog.item_archived` |
| Matrix (C6, K4c) | Extended by K13 ("K13 as built"): the same command now persists the dimensions, their values and the links of each variant, links a variant that exists with identical values instead of refusing it, fixes the dimensions of the item with its first matrix and refuses a repeated combination; everything below still holds except where "K13 as built" says otherwise. Up to three dimensions of 1 to 50 values (codes of letters, digits, dots or underscores, unique ignoring case) crossed in the order sent, at most 100 variants per command (`400` beyond). Code `m-azul`, name `M / Azul`, optional SKU `<skuPrefix>-<code>` in upper case, one quantity policy for all. All or nothing: a combination that exists with other values `409 · catalog.code_taken`, a taken SKU `409 · catalog.sku_taken`, 500 variants passed `422 · catalog.item_variants_full`. A matrix whose combinations all exist, none archived, with exactly these values is already in effect, like a repeated transition: `200` with the item and its tag, no `Idempotent-Replayed` header (that header belongs to a stored `Idempotency-Key`), nothing written or recorded. An archived variant holding the code of a combination is a clash (`409 · catalog.code_taken`), never the same matrix. One `catalog.item.variant_added` record lists every new variant. Barcodes per cell are not part of the command                                                                                                                                                                                                                                                                                                                                                                                                               |
| Barcodes (C11)   | Value trimmed, at most 160, never NUL, and stored as a GTIN: an all-digit value of 12 digits (UPC-A) is stored and answered in its 13-digit EAN-13 form with a leading 0, one of 14 digits with a leading 0 without it, so one GTIN is one value whatever its encoding and the active-value index sees it once; the declared symbology stays as sent, and other values (free-form symbologies included) are stored exactly as sent after trimming, with no Unicode or inner-space normalisation; `ean13`, `ean8`, `upca` and `upce` need their digits and a correct GS1 check digit (UPC-E expanded to UPC-A), other symbologies or none take the value as sent (`422 · catalog.barcode_invalid`). The value is checked under the version lock against the active barcodes of the catalog (`409 · catalog.barcode_taken`) and backstopped by the partial unique index. `isPrimary` takes the primary away from the former one in the same command; deactivation clears the primary; only an active barcode can become primary (`422 · catalog.barcode_not_active`). Value and variant never change: the edit (`PATCH`) changes only the symbology and the primary. At most 20 barcodes per variant, inactive included (`422 · catalog.variant_barcodes_full`). Reactivation refuses a value active elsewhere (`409`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Lookup (C18)     | One statement after the permission resolves the business unit operating the outlet today (`organization.effective_business_unit` on the site's date) and the active barcode, lock-free, keeping it only when `catalog.variant_is_listed` admits the variant for that unit; K6 is not built, so every unit sells the default catalog (`all`, the SQL default), and the answer follows any assortment row K6 writes later with no change here. No match, an outlet no unit operates today or another organization's code answer `200` with `data: null`; two sellable matches `409 · catalog.barcode_ambiguous` (only reachable once several catalogs exist). The back-office lookup answers the item and variant of an active barcode whatever their status, ordered by barcode id and bounded to two rows like the till, with the same `409 · catalog.barcode_ambiguous` for two matches (a dead branch with one catalog per organization). Both lookups compare a scanned all-digit value as a GTIN, as on the add. Statement budget of the scan: 7 (session, membership, `BEGIN`, tenant context, permission, lookup, `COMMIT`); it is classified hot and measured by the `catalog-barcode-scan` scenario (2,000 barcodes, one till outlet)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Lock order       | Version row `FOR UPDATE`, then the item `FOR UPDATE OF i`; the variants and barcodes of the item are written only under that item lock, so they are not locked again. `UPDATE` lists never name `item_id`, `organization_id`, `catalog_id`, `created_at`, `item_variant_id` or the barcode value (a unit test checks the statements)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Index evidence   | `EXPLAIN (ANALYZE, BUFFERS)` as `ninaku_runtime` under row level security on 2,500 items, 5,000 variants and 10,000 barcodes (half inactive), local: the back-office lookup and the add's value check use `item_variant_barcodes_value_uq` with `organization_id` and `barcode` as index conditions (`catalog_id` skipped, 2 to 3 index searches), 1.2 ms and 0.03 ms warm; the till lookup the same index plus `variant_is_listed`, 1.0 ms; an exact SKU uses `item_variants_sku_search_idx`, 0.03 ms. No index was added. A local single-machine run, not a capacity claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Still open       | Barcodes in the matrix command; a read of one variant (the item read carries them); per-business-unit listing (K6) and the POS reads C17, C19 (K7); `admit` (K8)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### Hardening round as built (migration `0080_catalog_defaults_belong_to_the_item_offer`, baseline revision 90)

| Piece                     | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Why                       | K5 kept the default on the reusable option (`modifier_options.is_default`) while the selection rule lives on each item offer, so a group with two default options offered with `maxSelections` 1 made the item start in a state its own rule forbids, and two items could not preselect different options of one group. Owner decision ("the best for the business"): the default belongs to the item offer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Schema                    | One migration. `catalog.item_modifier_group_defaults (item_modifier_group_id, modifier_option_id, modifier_group_id, catalog_id, organization_id, created_at)`, primary key on the pair, a composite foreign key to the offer `(id, modifier_group_id, catalog_id, organization_id)` `ON DELETE CASCADE` and one to the option with the same four columns, through the new unique keys `item_modifier_groups_id_group_catalog_org_uq` and `modifier_options_id_group_catalog_org_uq`: SQL itself guarantees that an offer preselects only options of its own group, catalog and organization, which a `uuid[]` column on the offer could not (an array element has no foreign key). Indexes on the option and on the group serve the removals, and the partial index `modifier_options_variant_idx (organization_id, item_variant_id) WHERE item_variant_id IS NOT NULL` serves the cleanup of a retired variant (`EXPLAIN` on 3,000 options under row level security: an index scan with both columns as index conditions, proven by `database/tests/contracts/catalog-offer-default-migration-contracts.ts`). Tenant RLS with the scalar subquery, statement-level catalog version bumps on insert, update and delete, and `ninaku_runtime` gets `SELECT, INSERT, DELETE` only (no `UPDATE`, so no row can move to another organization). The count bound (`≤ maxSelections`) and the availability of a default stay domain rules under the version row lock, like the other K5 rules. The migration carries each existing option default to the offers of the items that already offer its group, only while the option, its group and its target variant are active and only up to the offer's `max_selections` in option order (`ON CONFLICT DO NOTHING`, so it can run again); production holds no catalog data yet, so this carry-over is for local and staging databases only. **Expand step only:** because the migrator runs before the new API (`RAILWAY_OPERATIONS.md`), the migration keeps `modifier_options.is_default` (`NOT NULL DEFAULT false`), which the previous API still reads and writes during the rollout; the new API never reads or writes it (a unit test checks every modifier statement). **The contract step** was built in revision 92: migration `0082` drops the unused column ("Contract step and where-used as built") |
| Routes and representation | `isDefault` is gone from the option create, add and edit requests (sending it answers `400`) and from every option answer. `PUT /catalog/items/{itemId}/modifier-groups` takes `defaultOptionIds` per group (UUIDs, each once, at most 50 because a group holds at most 50 options, absent means empty), and C3 answers it on every offered group in the order of the group's options; the item ETag hashes it, so a change of defaults, including one caused by retiring an option, changes the item tag. The `catalog.item.modifier_groups` audit value appends `:<sorted default ids joined by +>` to a group that has defaults (`groupId:min:max` otherwise, as before)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Rules                     | `422 · catalog.default_options_invalid` (*new*) when a default is repeated, more defaults than `maxSelections` are sent, or a default is not an active option of an active group whose `catalog_variant` target is active; an unknown option, one of another group and one of another organization answer exactly the same, so nothing leaks. The selection rule is judged first. An offer kept identical, defaults included, is not judged again. A change of defaults only is gated by the plan, like any rule change; a pure removal of groups keeps the defaults of the kept groups and stays ungated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Lifecycle                 | Deactivating or archiving an option, deactivating or archiving its group, and deactivating or archiving a variant sold by a `catalog_variant` option each remove the option(s) from every offer's defaults with one `DELETE` in the same transaction; the command's record gains `catalog.modifier_group.offer_defaults_removed` (option and group commands) or `catalog.item.variant.offer_defaults_removed` (variant command) with the number of offers that lost a default, only when some did. Reactivation never adds a default back. Every one of these commands takes the catalog version row first, like the offer, so an option deactivation and an offer preselecting it serialise and no default ever points at an unavailable option                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Business limits           | An organization holds at most 500 categories and 500 modifier groups of any status, archived ones included because the tree and the list still load them: the 501st create answers `422 · catalog.category_limit_reached` or `422 · catalog.modifier_group_limit_reached`, counted after the version row lock, so no race passes it and no migration was needed. Reactivation and restoration create nothing and are unaffected. One constant per collection in `application/catalog-limits.ts` is both the limit and the read cap, so `meta.truncated` could never become true and the API v7 foundation removed it from both reads                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Performance               | `perf:http` measures `GET /catalog/modifier-groups` and `GET /catalog/modifier-groups/{modifierGroupId}` (`200` and `304`) on 150 groups of 7 options; all rows meet the standard budget with 1 and 16 clients (`docs/operations/PERFORMANCE_BASELINE.md` §14.3), local evidence only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Recorded debt | The Assets milestone, built since (`PUT /catalog/items/{id}/images`, `ASSETS_USE_CASES.md`). The idempotency keys of the category, group and option creates and `If-Match` for category writes were built in revision 91 ("Idempotent creates as built")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### K6 as built (no migration, baseline revision 90)

| Piece                         | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                        | No migration. `business_unit_catalogs` (mode `all` or `selected`, status `active` or `inactive`), `business_unit_items`, `guard_assortment_change`, `variant_is_listed`, `listed_items`, their RLS with the scalar subquery and the K1 grants (`SELECT, INSERT, UPDATE`, no `DELETE`) already hold every fact C14 to C16 need, and K1 seeded the three audit actions. A unit with no `business_unit_catalogs` row sells everything (`variant_is_listed`: no row and a catalog in `organization` mode, which the default catalog always is), so a new business unit needs no row (OD5); the baseline stays at revision 90                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Routes                        | `GET /catalog/business-units/{businessUnitId}/assortment` (`200`, `304`), `PUT /catalog/business-units/{businessUnitId}/assortment` (`200`), `POST .../assortment/listings` (`200`), `POST .../assortment/delistings` (`200`); and C16 as decided, `GET /catalog/items?businessUnitId=&listed=true\|false`. Every route behind `SessionGuard` and `TenantContextGuard`, errors as Problem Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Representation and tags       | `{ businessUnitId, mode, listedCount }`; `listedCount` is `count(DISTINCT item_id)` of `catalog.listed_items(org, unit)`, the items the unit sells now, so `selected` with nothing listed answers `0` and the screen can warn. The strong tag is `<organization>:<catalog version>:assortment-<unit>:<mode>:<unit status>`: the organization-wide catalog version, like the category tree, so every assortment write bumps it, no lost update passes `If-Match`, and any catalog write of the organization changes it (accepted, as C10); plus the mode and the status of the unit, because deactivating or reactivating a unit changes what it sells (`listed_items` needs an active unit) without moving the catalog version (K6 review, S1: the old tag answered `304` with a stale `listedCount`). `If-Match` is compared after the version lock and the read of the stored mode and unit status. The read answers `Cache-Control: private, no-cache` and `304` on `If-None-Match` (weak comparison, so `W/"…"` matches); the writes answer the tag with `private, no-store` and take `If-Match` with the strong comparison (`412 · foundation.precondition_failed`, nothing written, checked right after the version lock). A command already in effect answers `200` with the same tag, writes and records nothing, and never sets `Idempotent-Replayed`                                                                  |
| Authorization (anchored, OD3) | The permission is `catalog.assortment.manage` at the unit of the path: `OperationAuthorizationContract` with the `business_unit` anchor (`platform.authorize_operation_at`) for the mode and the listings, `PermissionCheckContract` with the anchor for the delistings; an organization-wide scope also satisfies it. The decision comes before any lock or lookup. A caller it refuses with a plain denial gets the same `403 · catalog.action_forbidden` for its own unit, another unit, an unknown unit and a unit of another organization, with one denied record targeting the unit id of the path; only a caller holding the permission organization-wide learns `404 · organization.structure_not_found` (no record, nothing locked). `catalog.items.manage` alone does not curate, and `catalog.assortment.manage` alone does not edit items. The read accepts `catalog.items.view` or `catalog.assortment.manage` at the unit, with the same rule for unknown units, and records nothing. The unit is taken only from the path: every body is strict, so `organizationId` or `businessUnitId` in a body answers `400`                                                                                                                                                                                                                                                                                                 |
| Plan and place                | The mode change and the listings are gated by `catalog.items` (`403 · platform.capability_not_entitled`, audited, after the permission); delistings and the read never ask about the plan. An inactive unit answers the gated commands `422 · authorization.place_not_operational` (now mapped by the catalog failures; before K6 no catalog route used an anchor, so it never arose); an organization-wide holder may still read and delist there (repair), and a member assigned to the inactive unit gets `403 · authorization.scope_unavailable`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Mode (C14)                    | `all` and `selected` are an active row of that mode, `none` an active row of mode `none` (migration `0116`; before it, an inactive row). An inactive row now means an assignment that rests because the unit sells from another catalog, and it reads as `none` too. The listings and delistings already made are kept and keep their meaning when the mode changes again, so switching `none` back to `selected` restores what the unit listed. One `catalog.assortment.mode_changed` record keeps `catalog.assortment.mode` before and after. The first write of a unit calls `ensure_default_catalog` after the version lock, like the item create                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Listings (C15)                | `{ itemIds }`, 1 to 200, each once (`400` otherwise), all or nothing. The API speaks of listed and not listed; the command writes only what changes: in `selected` a listing inserts a missing inclusion or reactivates an inactive row and a delisting deactivates an inclusion; in `all` a delisting inserts a missing exclusion or deactivates an active row and a listing reactivates an exclusion (an item without a row is already listed). When no unit row exists yet the command first writes the `all` row the listings need as their parent. An unknown item or one of another organization answers `404 · catalog.not_found` for the whole call; listing an archived item answers `422 · catalog.item_archived` (*Decided*: the design named a new `catalog.item_not_active`, but only archived items are refused, an inactive item may be listed and sells once reactivated, and the existing code says exactly that); a unit in mode `none` answers `422 · catalog.assortment_disabled` (*new*; owner decision of the K6 review, "follow the standard": a state refusal is `422`, and the catalog answers `409` only for uniqueness clashes) to both commands. Delisting never changes an item, its status or another unit. One `catalog.assortment.items_listed` or `.items_delisted` record per call keeps `catalog.assortment.items`, the sorted ids that changed; a call that changes nothing records nothing |
| Lock order                    | Authorization at the unit, then `catalog.catalog_versions` `FOR UPDATE` (the If-Match check), then the stored mode, then the requested items `FOR SHARE OF i` in id order; the row writes fire `guard_assortment_change`, which locks the unit row `FOR UPDATE` (proven by a `NOWAIT` probe, and a mutation that drops the guard fails it). Two managers of different units therefore serialise on the version row and never deadlock; a listing and an item archival serialise the same way (`422 · catalog.item_archived` when the archival came first). `UPDATE` lists name only `assortment_mode` and `status` (a unit test checks them), never `id`, `organization_id`, `business_unit_id`, `catalog_id`, `item_id` or `created_at`, which the guard refuses anyway                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| C16 `listed` filter           | `listed=true` keeps the items the unit's assortment admits, `false` the others, whatever their variants; the status filter still applies and `listed` needs `businessUnitId` (`400`). The cursor binds `listed` only when it is sent, so cursors issued before K6 stay valid. The predicate resolves the unit's mode once (`none` for an inactive unit or catalog, `all` without a row) and tests the item against a hashed set of the unit's inactive rows (`all`) or active rows (`selected`), the rule of `variant_is_listed` without the item and variant status. `EXPLAIN (ANALYZE, BUFFERS)` as `ninaku_runtime` under row level security on 20,000 items, local: a first page with 10,000 listed 4.2 ms, with 10 listed 4.1 ms and 4,998 buffers (a correlated `EXISTS` read 184,702 buffers and took 44 ms there, so it was replaced), `listed=false` 1.0 ms; the item order stays on `catalog_items_name_search_idx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Other evidence                | The command's item read uses `catalog_items_name_search_idx` with `id = ANY(...)` as an index condition (200 ids, 2.4 ms); the status update uses the unique `(business_unit_id, item_id)` index (101 rows, 7.0 ms, 3.3 ms of it in the guard trigger, R9); `listedCount` costs 21.5 ms with 10,000 of 20,000 listed and 6.7 ms with 10 (one `listed_items` call); the OD5 check uses `business_units_organization_status_idx` and `business_unit_verticals_organization_status_idx` (0.14 ms). Local single-machine runs, not a capacity claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Workspace                     | `allowedActions` gains `curate` when `businessUnitId` is sent and the caller may set the mode there on the current plan (the same anchored, gated decision, recording nothing). `warnings` (*new*, OD5) answers `units_with_different_verticals` when the active business units of the organization do not all run the same set of active verticals, so the screen can say that a new unit sells the whole shared catalog until its assortment is chosen. The warning describes the whole organization, so it is answered only to a caller holding `catalog.assortment.manage` organization-wide, the person who curates every unit and so must react to a new one; a reader assigned to one unit, or one who only reads the catalog, gets an empty list (K6 review, S2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Till (C18)                    | Unchanged code: the lookup already keeps a match only when `variant_is_listed` admits it, which reads the K6 rows, so a unit in `selected` mode that has not listed the variant answers `data: null` at its outlets while another unit that sells it resolves it, `none` sells nothing, `all` everything, and a delisting at one unit never changes another unit's till (a mutation that drops the listing rule fails both tests). Statement budget unchanged: 7                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Drift guard                   | The `listed` filter writes the listing rule a third time (after `variant_is_listed` and `listed_items`), on purpose, for its plan; `src/modules/catalog/infrastructure/reads/listed-filter.integration-spec.ts` proves it agrees with both on every mode (no row, `all`, `selected`, turned off from either), active and inactive unit, and a listing, an exclusion and no row, so they cannot drift (a mutation that ignores the unit status fails it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Performance                   | The four routes are classified administrative and not measured: they are opened only while curating a unit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Still open                    | K7 reads the assortment through `catalog.listed_items`, which already follows the K6 rows; the K7 requirements recorded in C17 and C19 stand. Per-variant assortment is not built (the listings are per item, as decided). `admit` (K8) does not call `catalog.assert_variant_listed`; the function stays because the order-line trigger of the Sales schema (`database/canonical/0110_sales.sql`) calls it as its database-level admission. A creation key or a request hash for these commands is not needed: every command is a set operation that answers `200` when repeated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### D1 as built (migration `0099`, baseline revision 109)

The owner's D1 decision (audit of `18d8e128`; design in
`CATALOG_OPTIONS_V2.md` §18) replaces OD5 (a) for new units.

| Piece                | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rule                 | When the registration of a business unit commits, the deferred constraint trigger `business_units_default_assortment_trg` (`AFTER INSERT ON organization.business_units`, `DEFERRABLE INITIALLY DEFERRED`, owned by Catalog like `organizations_catalog_version_insert_trg`) runs `catalog.materialize_default_assortment()`: a unit that already has a row on the default catalog (written in the same transaction) is left alone; otherwise it stores one row on the default catalog (creating that catalog when missing), active `all` when no other unit of the organization has an active vertical, or when each active vertical of the unit is active in another unit of the organization, and active `none` otherwise, which includes a unit registered without verticals |
| Stored once          | Nothing recomputes it: activating or deactivating a vertical later never touches the row, and reads still answer from the stored row; only C14 changes it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Concurrency          | The trigger takes the transaction advisory lock keyed `organization.verticals:<organization id>`, the lock every vertical writer takes (Platform's `activate` and the last-vertical guard), before it reads, so a registration committing while another unit of the organization turns a vertical on decides after that activation and counts it (`database/tests/concurrency/catalog-default-assortment-concurrency.ts`; without the lock the registration decides `none` from a stale read). Two registrations in one organization were already serialised by the structure version row their inserts update, so the second one always sees the first (`test/e2e/business-unit-register-verticals.e2e-spec.ts`)                                                                |
| Security             | `SECURITY DEFINER`, `search_path = pg_catalog, pg_temp`, `EXECUTE` revoked from `PUBLIC`: it runs at the commit of provisioning, which has no tenant context, as well as at the commit of a tenant registration. It writes only the row of the unit being inserted, in that unit's organization                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Version and audit    | The insert bumps the catalog version once (the existing statement trigger), so the assortment and till tags move. No catalog audit record: the default is part of the audited `organization.business_unit.registered` (and its `vertical_activated` records); later choices are audited by C14                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Choosing at creation | `POST /business-units` takes the optional `verticalCodes` (O9), activated in the registering transaction, so the trigger sees them. A client that wants another mode sends `PUT /catalog/business-units/{id}/assortment` right after; between the two requests the stored default applies, which never sells another line of business                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Backfill             | Migration `0099` creates the default catalog of every organization that has units and none, and gives every existing unit without a row an explicit active `all` row, so every existing unit keeps selling exactly what it sold (`database/tests/contracts/catalog-default-assortment-migration-contracts.ts`; upgrade from revision 108 with identical till lists)                                                                                                                                                                                                                                                                                                                                                                                                              |
| Proof                | `database/tests/contracts/catalog-default-assortment-contracts.ts`, `test/e2e/business-unit-default-assortment.e2e-spec.ts`, `test/e2e/business-unit-register-verticals.e2e-spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### B1 as built (migration `0100`, baseline revision 110)

C22, the composition of a combo (design in `CATALOG_OPTIONS_V2.md` §19). A
combo is a normal item that owns bundle groups: a restaurant combo, a retail
kit or a service package use the same routes and nothing in them is
restaurant-only. Catalog stores no price for it; Pricing prices the item
itself plus one surcharge per choice (`pricing.bundle_group_item_price_entries`).
Admission came next in B2 ("B2 as built"); Pricing and Sales (B3) follow:
the till reads (C17, C19) and `resolve` are unchanged.

| Piece                                                  | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Routes                                                 | `GET /catalog/items/{itemId}/bundle-groups` (view, any item, archived included, `businessUnitId` as in C3; strong ETag, `304`) and `PUT /catalog/items/{itemId}/bundle-groups` (manage; replaces the ordered groups and their ordered choices in one call). No `Idempotency-Key`: like the other catalog `PUT`s it is a replacement, and sending it again answers `200` with no write, no record and no version change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Vocabulary                                             | `bundleGroups[]` with `bundleGroupId`, `code`, `name`, `minSelections`, `maxSelections`, `suspended`, `isSatisfiable` and `choices[]`; a choice has `choiceId`, `variantId`, `itemId`, `itemName`, `variantName`, `sku`, `itemStatus`, `variantStatus`, `quantityPerSelection` (decimal string, units of the variant one pick gives), `maxSelectionCount` (picks of this choice one sale may take, `null` for no cap), `isDefault`, `suspended` and `isAvailable`. The stored `status` stays internal: `suspended` is `inactive`, and `retired` rows are never answered, exactly as the modifier offer answers `suspended`. `minSelections` and `maxSelections` mean what they mean on modifier offers (C13)                                                                                                                                                                                                                                             |
| Identity                                               | A group keeps its id when the client sends `bundleGroupId` back; a choice is the pair (group, variant) and keeps its id whether or not `choiceId` is sent. Whatever the list leaves out is retired (`status = 'retired'`, widened CHECK), never deleted; sending it again revives the same id. `suspended: true` on a group or a choice writes it `inactive`; `false` or absent writes it `active`, so a suspended row is resumed by sending it without the flag and a retired one comes back as sent. A new group without `code` takes one derived from its name like an item code (lowercase ASCII with hyphens, `-2`, `-3` against every code the combo holds or held, `group` when nothing is left)                                                                                                                                                                                                                                                  |
| Rules before SQL (`400`, `meta.errors` with the field) | `minSelections` 0 to 999 and not above `maxSelections` (1 to 999); 1 to 50 choices per group, each variant once; `isDefault` on none or between the minimum and the maximum; `quantityPerSelection` a decimal above 0 and at most 999 (6 decimals, `"1"` by default); `maxSelectionCount` an integer from 1 to the group's `maxSelections`, or `null` (as `GET` answers it) or absent for no cap, so the body `GET` answers can be sent back as it is, and the caps of a group able to reach its `minSelections`; a suspended choice never `isDefault`; at most 20 groups; no repeated group, code or choice, each repetition pointed at its own element (`bundleGroups[1].bundleGroupId`); strict bodies (a `price` is an unknown field)                                                                                                                                                                                                                |
| Rules that read the database                           | an unknown group, choice or variant `404 · catalog.not_found`; a code another group of the combo holds or held `409 · catalog.code_taken`; a `choiceId` with another variant `422 · catalog.bundle_choice_mismatch`; the combo itself or a combo that contains it `422 · catalog.bundle_cycle`; a new choice whose item or variant is archived, or of another catalog, `422 · catalog.bundle_component_unavailable` (a choice already in the group keeps its place); each with `meta.errors[]` (`location`, `field` such as `bundleGroups[2].choices[0].variantId`, `code`, a message that says how to fix it), only the first kind by precedence (not found, code, mismatch, cycle, unavailable). The ids the client sends back are judged before the composition is compared with the stored one, so an otherwise unchanged request with an unknown or mismatched id is refused, never answered `200`. An archived combo `422 · catalog.item_archived` |
| Cycles                                                 | The use case reads, in the statement that share-locks the requested variants, which of them belong to the combo or to a combo that contains it; the SQL guard stays the backstop and now raises `CONSTRAINT = 'bundle_composition_acyclic'`, mapped to the same `catalog.bundle_cycle`. Both look at the same live graph: retired groups and choices do not count, so a retired choice never forbids a later nesting; the graph triggers of both tables also fire on a status change, so reviving a retired row that would close a loop is refused with the same code                                                                                                                                                                                                                                                                                                                                                                                    |
| Availability                                           | `isAvailable` is true when neither the choice nor its group is suspended and its item and variant are `active`. `isSatisfiable` is the one rule B2 judges too (`domain/bundles/bundle-satisfiability.ts`): an optional group always is; a required one is when it is not suspended and its available choices, each counted up to its `maxSelectionCount` (999 when absent), reach `minSelections`. Sold out (86) is Operations' and is not shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Locks and concurrency                                  | The lock order of every catalog command: the version row `FOR UPDATE`, then the combo item `FOR UPDATE` (with its composition, one statement), then the requested variants `FOR SHARE` in id order. Admissions hold the version row `FOR SHARE`, so a composition edit waits for open admissions of the organization and fails after the 5 s statement timeout under continuous overlap (K8 rule)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Version and audit                                      | Triggers bump the catalog version once per statement kind on insert, update and delete of both tables (X15 for bundles); an upsert that changes nothing bumps nothing. One `catalog.item.bundle_groups_set` record per real change keeps `catalog.item.bundle_groups` before and after: each live group as `groupId:code:min:max:status:name[choiceId:variantId:quantityPerSelection:maxSelectionCount:isDefault:status, ...]`, the same key the change check compares, so a rename alone is recorded with a different before and after                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Plan                                                   | An empty list (the item becomes plain again) never needs the plan; any other change is gated by `catalog.items`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ETag                                                   | A hash of the answer, choice names and statuses included: renaming or deactivating a component changes it, so `If-Match` fails with `412` and the client reads again. The C3 item tag and body are unchanged: the item read does not carry the composition, which would add a statement to every item read and write                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Privileges                                             | `ninaku_runtime` gets `SELECT`, `INSERT`, `UPDATE` (never `DELETE`) on `bundle_groups` and `bundle_group_items` and `EXECUTE` on `catalog.lock_bundle_graph(uuid)` and `catalog.assert_bundle_composition_acyclic(uuid)`, which the graph triggers call as the invoker                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Limits                                                 | 20 groups per combo, 50 choices per group (as modifier offers and options), selections up to 999 (Sales' `selection_count`), names 180 characters and codes as the SQL checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Proof                                                  | `test/e2e/catalog-bundle-groups.e2e-spec.ts`, `database/tests/contracts/catalog-bundle-groups-contracts.ts` (`NINAKU_CATALOG_BUNDLE_GROUPS_OK`), C22 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md); upgrade from revision 109 with seeded bundle rows gives the same schema and privileges as a fresh install                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**Example.** `PUT /api/v1/catalog/items/01930000-0000-7000-8000-0000000000b0/bundle-groups`
keeps the groups Principal and Bebida (ids sent back), adds Té helado to
Bebida and creates Acompañamiento:

```json
{
  "bundleGroups": [
    {
      "bundleGroupId": "01930000-0000-7000-8000-0000000000b1",
      "name": "Principal",
      "minSelections": 1,
      "maxSelections": 1,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-0000000000c1",
          "variantId": "01930000-0000-7000-8000-0000000000a2",
          "isDefault": true
        }
      ]
    },
    {
      "bundleGroupId": "01930000-0000-7000-8000-0000000000b2",
      "name": "Bebida",
      "minSelections": 1,
      "maxSelections": 1,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-0000000000c2",
          "variantId": "01930000-0000-7000-8000-0000000000a4",
          "isDefault": true
        },
        {
          "variantId": "01930000-0000-7000-8000-0000000000a6"
        }
      ]
    },
    {
      "code": "acompanamiento",
      "name": "Acompañamiento",
      "minSelections": 0,
      "maxSelections": 2,
      "choices": [
        {
          "variantId": "01930000-0000-7000-8000-0000000000a8",
          "quantityPerSelection": "1"
        }
      ]
    }
  ]
}
```

`200`, with `ETag` the strong tag of the composition (here Té helado is
inactive, so it is not available, while the group stays satisfiable through
Gaseosa):

```json
{
  "data": {
    "itemId": "01930000-0000-7000-8000-0000000000b0",
    "bundleGroups": [
      {
        "bundleGroupId": "01930000-0000-7000-8000-0000000000b1",
        "code": "principal",
        "name": "Principal",
        "minSelections": 1,
        "maxSelections": 1,
        "suspended": false,
        "isSatisfiable": true,
        "choices": [
          {
            "choiceId": "01930000-0000-7000-8000-0000000000c1",
            "variantId": "01930000-0000-7000-8000-0000000000a2",
            "itemId": "01930000-0000-7000-8000-0000000000a1",
            "itemName": "Hamburguesa clásica",
            "variantName": null,
            "sku": "HB-001",
            "itemStatus": "active",
            "variantStatus": "active",
            "quantityPerSelection": "1",
            "maxSelectionCount": null,
            "isDefault": true,
            "suspended": false,
            "isAvailable": true
          }
        ]
      },
      {
        "bundleGroupId": "01930000-0000-7000-8000-0000000000b2",
        "code": "bebida",
        "name": "Bebida",
        "minSelections": 1,
        "maxSelections": 1,
        "suspended": false,
        "isSatisfiable": true,
        "choices": [
          {
            "choiceId": "01930000-0000-7000-8000-0000000000c2",
            "variantId": "01930000-0000-7000-8000-0000000000a4",
            "itemId": "01930000-0000-7000-8000-0000000000a3",
            "itemName": "Gaseosa",
            "variantName": "500 ml",
            "sku": "GAS-500",
            "itemStatus": "active",
            "variantStatus": "active",
            "quantityPerSelection": "1",
            "maxSelectionCount": null,
            "isDefault": true,
            "suspended": false,
            "isAvailable": true
          },
          {
            "choiceId": "01930000-0000-7000-8000-0000000000c3",
            "variantId": "01930000-0000-7000-8000-0000000000a6",
            "itemId": "01930000-0000-7000-8000-0000000000a5",
            "itemName": "Té helado",
            "variantName": null,
            "sku": null,
            "itemStatus": "inactive",
            "variantStatus": "active",
            "quantityPerSelection": "1",
            "maxSelectionCount": null,
            "isDefault": false,
            "suspended": false,
            "isAvailable": false
          }
        ]
      },
      {
        "bundleGroupId": "01930000-0000-7000-8000-0000000000b3",
        "code": "acompanamiento",
        "name": "Acompañamiento",
        "minSelections": 0,
        "maxSelections": 2,
        "suspended": false,
        "isSatisfiable": true,
        "choices": [
          {
            "choiceId": "01930000-0000-7000-8000-0000000000c4",
            "variantId": "01930000-0000-7000-8000-0000000000a8",
            "itemId": "01930000-0000-7000-8000-0000000000a7",
            "itemName": "Papas fritas",
            "variantName": null,
            "sku": null,
            "itemStatus": "active",
            "variantStatus": "active",
            "quantityPerSelection": "1",
            "maxSelectionCount": null,
            "isDefault": false,
            "suspended": false,
            "isAvailable": true
          }
        ]
      }
    ]
  }
}
```

### B2 as built (no migration, baseline revision 110)

C28, admitting a combo (design in `CATALOG_OPTIONS_V2.md` §20). `admit` of
`CatalogSellableContract` takes, on a line, the components the customer
chose and answers the tree Sales freezes in
`sales.order_line_bundle_selections`; Catalog still answers no price. The
contract change is additive: a line without `bundleSelections`, or of an
item with no active group, is admitted and serialized exactly as before.

| Piece                | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input                | `lines[i].bundleSelections[]`: `{ bundleGroupId, choices[] }`, each choice `{ choiceId, quantity, selections?, bundleSelections? }`. `quantity` is how many times the customer took that choice (integer 1 to 999, Sales' `selection_count`); `selections` are the modifiers of that component, `bundleSelections` the groups of a combo inside the combo. The same choice may come twice in a group (two occurrences with different modifiers)                                                                                                                                                                                                                                                                                                                                                                                                   |
| Answer               | `lines[i].bundleGroups[]` (only when the item has an active group): every active group in catalog order, `{ bundleGroupId, groupNameSnapshot, minSelections, maxSelections, choices, removedDefaults }`; each choice `{ choiceId, quantity, quantityPerSelection, appliedByDefault, snapshot, offers, bundleGroups? }`, in the order sent (a group left out holds its applied defaults in catalog order)                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Defaults             | A group left out gets its available defaults, one each, `appliedByDefault: true`; a group sent gets exactly its choices (an empty list means none), and the available defaults it left out come back in `removedDefaults` (`{ choiceId, itemNameSnapshot, variantNameSnapshot, defaultQuantity }`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Judgement            | the group is a live, active group of that combo; the choice a live, active choice of that group; minimum and maximum on the sum of quantities; a choice's `max_selection_count` on the sum of its entries; a required group whose available choices cannot reach its minimum is unsatisfiable, by the one rule B1 answers as `isSatisfiable` (`domain/bundles/bundle-satisfiability.ts`); a required group suspended with `PUT .../bundle-groups` refuses `bundle_group_unavailable` at the list even when the client leaves it out, as a required suspended modifier offer leaves its item unsellable, while an optional suspended group is simply not offered; each component by the sellable rule of a line (same statement, same fragment) and its modifiers by `judgeSelection` against its own effective offers; a nested combo recursively |
| Refusals             | whole or nothing, `CatalogNotSellableError`. Inside a combo each refusal is a `BundleAdmissionRefusal` (`isBundleAdmissionRefusal`): `line`, `variantId` (of the line), `reason`, `modifierGroupId`, `optionId`, `path`, `bundleGroupId`, `choiceId`, `detail`. Reasons: `bundle_group_not_offered`, `bundle_group_unavailable`, `bundle_group_unsatisfiable`, `bundle_choice_not_offered`, `bundle_choice_unavailable`, `bundle_choice_above_maximum`, `bundle_selection_below_minimum`, `bundle_selection_above_maximum`, `bundle_too_deep`, `bundle_components_above_limit`, and for a component the line reasons (`not_listed`, `item_inactive`, `selection_below_minimum`, ...). A group or a default the client did not send points at the list where it belongs (`lines[0].bundleSelections`)                                              |
| Request problems     | before any lock: a choice quantity off 1 to 999 `invalid_quantity`; a group twice at one level or an option twice in a component `duplicate`; more than 100 components on a line or 20 groups at a level `too_many_components`; nesting deeper than 3 `too_deep`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Statements and locks | the groups of each variant come in the same `SELLABLE_FACTS` statement; the components of every line are read with that statement once per level: 6 statements for a plain line, 7 for a combo, 8 for a combo in a combo, whatever the number of groups. Each line's components are counted while each level is built: a line that passes 100 stops expanding there and is refused `bundle_components_above_limit`, so a level reads at most 100 components per line. One catalog version share lock, so a composition edit waits for open admissions                                                                                                                                                                                                                                                                                             |
| Not built            | `resolve` still answers no composition: the till reads it from `GET .../bundle-groups`; prices are B3. Since B2b a combo that cannot be completed is left out of the till lists, the search, the scan and `resolve` ("B2b as built" in `CATALOG_OPTIONS_V2.md` §20.3), since F1b also a combo that can only be completed through a component combo that cannot, and since F1c one that can only be completed through components the unit cannot sell on their own (below)                                                                                                                                                                                                                                                                                                                                                                         |

**F1b as built (no migration): a combo inside a combo.** Example: the Pack
familiar has a required group that offers a children combo, and the children
combo has a required group that offers a toy. Before F1b, suspending the toy
group left the children combo out of the till, but the Pack was still listed,
found, scanned and answered sellable by `resolve`, and only `admit` refused
it. Now a choice counts toward the minimum of its group only when it is
active, its variant and item are active and, when its component is itself a
combo, that combo can be composed too, one level further down, up to three
combo levels (`BUNDLE_MAX_DEPTH`). Below the third level a component combo
with a group the sale would open (an active group, or a suspended required
one) is not available, because `admit` refuses it with `bundle_too_deep`; B1
guards only cycles at write time, not depth, so such a composition can be
stored. The alternatives stay: if the same required group of the Pack also
offers a plain drink, the Pack stays sold while the children combo is out.
The pure rule is `isComposable` (`domain/sellable/bundle-composability.ts`),
over the groups of each component by variant; the SQL fragment
`bundleComposable` unrolls the same three levels as keyed scalar probes, and
`bundle-composable.integration-spec.ts` runs both on the same nested rows.
`resolve` answers the Pack `bundle_group_unsatisfiable`; `admit` is unchanged
and still explains the refusal with the group of the children combo.
Statement counts, `meta.omittedItems` and the bytes of an item without combo
groups do not change.

**F1c as built (no migration): a component the unit cannot sell.** Example:
a breakfast has a required group that offers a coffee, and the coffee has a
required milk group. Before F1c, suspending the milk group left the coffee
out of the till (its own required modifier could not be satisfied), but the
breakfast was still listed, found, scanned and answered sellable by
`resolve`, and only `admit` refused it, with `required_modifier_unsatisfiable`
on the coffee. The same happened when the coffee was delisted at the unit
(`not_listed`). Now a choice counts toward the minimum of its group only when
its component would be sold on its own at the reader's business unit by the
same rule a plain line uses: an active variant of an active item of the
default catalog, listed at the unit (`listedAt`, with the unit operable), its
required modifier offers satisfiable (`variantConfigurable`, reused, so an
optional group or a variant that opts out of a suspended group does not
block it) and, when it is itself a combo, composable down to the third combo
level as in F1b. Alternatives stay: with a tea in the same required group the
breakfast stays sold while the coffee is out; a listing at another unit does
not count. The till lists, the search, the scan and `resolve` already carry
the unit, so `bundleComposable` takes the scope of the reader instead of an
item alias; every probe stays a keyed `anyRowOf`, three levels unrolled in
the text. The domain twin `isComposable` now reads each component's
sellability facts by variant (the `SELLABLE_FACTS` row `admit` reads) and
judges it with `blockingRefusalOf`, the predicate `admit` applies, so the
combos the till leaves out are those `admit` refuses whatever the selection;
`bundle-component-sellable.integration-spec.ts` runs SQL and domain on the
same rows. `resolve` answers the breakfast `bundle_group_unsatisfiable`;
`admit` is unchanged and refuses the coffee at its path
(`lines[0].bundleSelections[0].choices[0]`). `meta.omittedItems` counts the
coffee while its milk is suspended (a plain item the unit cannot configure),
never the breakfast. Statement counts and the bytes of an item without combo
groups do not change; the plan bounds are in `PERFORMANCE_BASELINE.md` §14.6.

**Sales mapping (`0110_sales.sql:981-1146`).**

| Sales column                                                      | From                                                          |
| ----------------------------------------------------------------- | ------------------------------------------------------------- |
| `bundle_group_id`                                                 | `bundleGroups[].bundleGroupId`                                |
| `bundle_group_item_id`                                            | `choices[].choiceId`                                          |
| `parent_bundle_selection_id`                                      | the row of the enclosing choice, for `choices[].bundleGroups` |
| `selection_number`                                                | the position of the choice in its group, from 1               |
| `group_name_snapshot`                                             | `groupNameSnapshot`                                           |
| `selected_item_name_snapshot`, `selected_variant_name_snapshot`   | `choices[].snapshot.itemName`, `.variantName`                 |
| `selection_count`                                                 | `choices[].quantity`                                          |
| `quantity_per_selection_snapshot`                                 | `choices[].quantityPerSelection`                              |
| `quantity_unit_code_snapshot`                                     | `choices[].snapshot.salesUnitCode`                            |
| modifier rows of the component (`order_line_bundle_selection_id`) | `choices[].offers[].selections`, as a line's                  |
| adjustments                                                       | Pricing (B3)                                                  |

**Example.** A combo whose Principal group the customer fills with a burger
cooked rare, two portions of fries, and no word about the drink:

```json
{
  "businessUnitId": "01930000-0000-7000-8000-000000000b01",
  "lines": [
    {
      "variantId": "01930000-0000-7000-8000-000000000c01",
      "quantity": "1",
      "selections": [],
      "bundleSelections": [
        {
          "bundleGroupId": "01930000-0000-7000-8000-000000000f01",
          "choices": [
            {
              "choiceId": "01930000-0000-7000-8000-000000000a01",
              "quantity": 1,
              "selections": [
                {
                  "optionId": "01930000-0000-7000-8000-000000000d01",
                  "quantity": 1
                }
              ]
            }
          ]
        },
        {
          "bundleGroupId": "01930000-0000-7000-8000-000000000f03",
          "choices": [
            {
              "choiceId": "01930000-0000-7000-8000-000000000a05",
              "quantity": 2
            }
          ]
        }
      ]
    }
  ]
}
```

The admitted line (snapshots and offers shortened to what Sales stores):

```json
{
  "lineIndex": 0,
  "snapshot": {
    "variantId": "01930000-0000-7000-8000-000000000c01",
    "itemName": "Combo hamburguesa",
    "...": "..."
  },
  "quantity": "1",
  "offers": [],
  "bundleGroups": [
    {
      "bundleGroupId": "01930000-0000-7000-8000-000000000f01",
      "groupNameSnapshot": "Principal",
      "minSelections": 1,
      "maxSelections": 1,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-000000000a01",
          "quantity": 1,
          "quantityPerSelection": "1",
          "appliedByDefault": false,
          "snapshot": {
            "itemName": "Hamburguesa",
            "variantName": null,
            "salesUnitCode": "unit",
            "...": "..."
          },
          "offers": [
            {
              "itemModifierGroupId": "01930000-0000-7000-8000-000000000e01",
              "groupNameSnapshot": "Término",
              "selections": [
                {
                  "modifierOptionId": "01930000-0000-7000-8000-000000000d01",
                  "optionNameSnapshot": "Jugoso",
                  "quantity": 1,
                  "...": "..."
                }
              ],
              "...": "..."
            }
          ]
        }
      ],
      "removedDefaults": []
    },
    {
      "bundleGroupId": "01930000-0000-7000-8000-000000000f02",
      "groupNameSnapshot": "Bebida",
      "minSelections": 1,
      "maxSelections": 1,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-000000000a03",
          "quantity": 1,
          "quantityPerSelection": "1",
          "appliedByDefault": true,
          "snapshot": { "itemName": "Gaseosa", "...": "..." },
          "offers": []
        }
      ],
      "removedDefaults": []
    },
    {
      "bundleGroupId": "01930000-0000-7000-8000-000000000f03",
      "groupNameSnapshot": "Acompañamiento",
      "minSelections": 0,
      "maxSelections": 2,
      "choices": [
        {
          "choiceId": "01930000-0000-7000-8000-000000000a05",
          "quantity": 2,
          "quantityPerSelection": "0.5",
          "appliedByDefault": false,
          "snapshot": {
            "itemName": "Papas fritas",
            "salesUnitCode": "kg",
            "...": "..."
          },
          "offers": []
        }
      ],
      "removedDefaults": []
    }
  ]
}
```

Sent without the Principal group, the same line is refused with one
refusal: `{ "line": 0, "reason": "bundle_selection_below_minimum", "path":
"lines[0].bundleSelections", "bundleGroupId":
"01930000-0000-7000-8000-000000000f01", "choiceId": null, "detail": "The
group needs more choices; add choices until the sum of their quantities
reaches its minimum.", ... }`.

Proof: `test/e2e/catalog-sellable-bundles.e2e-spec.ts` (with the Sales
parity helper `test/support/sales-bundle-parity.ts`: the real Sales
triggers store the rows built from the answer alone), the C28 rows of
[`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md).

### B2c as built: the till receives the composition of a combo (no migration, baseline revision 114)

C17 and C19 answer `bundleGroups` on every combo that opens at least one
active group, as described in C17
("Combos (B2c)"); the scan (C18) stays as it was. No route, permission or
statement is added: the composition is one column of the read statement
both share (`infrastructure/till/till-bundle-groups.queries.ts`), made of
correlated `json_agg` subqueries reached by the item key
(`bundle_groups_item_idx`, `bundle_group_items_group_idx`, one `LIMIT 1`
primary-key lookup for the item of each choice). A choice is kept by
`choiceAvailable`, exported from the sellable rule
(`infrastructure/reads/sellable-rule.queries.ts`): it is the very text the
B2b rule (`bundleComposable`) counts each choice with, so the till shows a
choice exactly when the rule that keeps the combo sellable counts it, nested
combos (F1b) and component sellability at the unit (F1c) included.

Proof:

* a plain item answers the same bytes, checked against a literal before the
  SQL changed (`test/e2e/catalog-till-combo-composition.e2e-spec.ts`);
* a cashier, refused the back-office read, sees the groups and choices of a
  combo in the read and the search, and the tag moves when the composition
  changes (same file);
* parity with `admit` on the same rows: every choice the till shows is
  admitted with that choice in its line and every hidden one refused with the
  expected reason, for suspended groups and choices, an
  inactive item and variant, an unlisted component, a component whose
  required modifier group is suspended, an incomplete component combo, a
  variant-specific choice, a component that needs a modifier, and combos
  nested three levels deep
  (`test/e2e/catalog-till-combo-composition-parity.e2e-spec.ts`);
* the shared text (`sellable-rule.queries.spec.ts`,
  `till-bundle-groups.queries.spec.ts`);
* plans under stale statistics, with a page of 50 combos holding combos
  three levels deep in the same page: no sequential scan, no looped scan
  wider than 100 rows, no lookup wider than the imported items, and per
  requested item at most 115 rows and 600 buffers for the 2,000-item list,
  200 rows and 1,050 buffers for a search page, 350 rows and 1,100 buffers
  for the 50-combo page (`till-read.plan.integration-spec.ts`). Those are
  about twice the worst of five runs on a freshly recreated database, with
  stale and with fresh statistics: 114,361 rows and 594,848 buffers for the
  list, 9,634 and 52,078 for the worst search page, 8,811 and 27,594 for the
  50-combo page. On the first measurement the composition about doubled the
  buffers of the 50-combo page and took its items from 34 KB to 102 KB
  (about 1.35 KB per combo of five choices). Each shown choice runs the full
  sellable check of its component, the same work `bundleComposable` already
  does for the required groups of every candidate.

### M1 as built (migration `0101`, baseline revision 111)

C21, the structure of a menu (design in `CATALOG_OPTIONS_V2.md` §21). A menu
says what is shown: ordered sections, one level of subsections, and the items
each section shows. A restaurant card, a retail catalogue page or a list of
service packages use the same routes; nothing is restaurant-only. Which
outlet shows a menu (M2), time windows (S1), translations, the till read by
menu and admission by menu are later slices: C17 to C20 are unchanged.

| Piece                                                  | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Routes                                                 | `GET /catalog/menus` (every menu, archived ones included, by name, with `sectionCount` and `entryCount`; at most 100, never paged), `POST /catalog/menus` (an empty `draft`; `Idempotency-Key` as every catalog create), `GET /catalog/menus/{menuId}` (the whole tree; strong ETag, `304`), `PATCH /catalog/menus/{menuId}` ("Edit a menu", operation `MenusController_update_v1`: name or code), `PUT /catalog/menus/{menuId}/structure` (replaces the ordered tree in one call), `POST .../activation` and `POST .../archival` (one `POST .../transitions` with `activate`, `unpublish`, `archive` and `restore` since API v7 PR 3). Reads need `catalog.items.view` (organization-wide or with `businessUnitId`, as C3); writes need `catalog.items.manage`                                                                                                                                                                                                                                                                                              |
| Vocabulary                                             | `sections[]` with `sectionId`, `code`, `name`, `suspended`, `entries[]` and `subsections[]` (same fields, no `subsections`); an entry has `entryId`, `itemId`, `itemName`, `itemStatus`, `variantMode` (`all` or `selected`), `suspended`, `isAvailable` and `variants[]` (`variantId`, `variantName`, `sku`, `status`); the menu adds `status` (`draft`, `active`, `archived`), `entryCount` and `availableEntryCount`. Order is the position in the array                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Identity                                               | A section keeps its id when the client sends `sectionId`, or the `code` a section of the menu holds (retired ones included), also when it moves between the top and a subsection; two sections of one request that resolve to the same stored section (one by its id, another by that section's code) are refused as a repetition (`400 · foundation.validation_failed` at the alias, such as `sections[1].code`); an entry is the pair (section, item) and keeps its id whether or not `entryId` is sent. What the tree leaves out is retired (`status = 'retired'`, widened CHECKs), never deleted, and sending it again revives the same id. `suspended: true` on a section or an entry writes it `inactive` (`false` or absent, `active`), as on combos and modifier offers. A new section without `code` takes one derived from its name (`-2`, `-3` against every code the menu holds or held, `section` when nothing is left), and a new menu without `code` one derived from its name against the codes of the catalog (`menu` when nothing is left) |
| Rules before SQL (`400`, `meta.errors` with the field) | `selected` needs 1 to 50 `variantIds`, `all` takes none; each item once per section and each variant once per entry; no section, code or entry twice in the tree; at most 50 sections and subsections, 200 entries per section and 1,000 in all; two levels only (a `subsections` inside a subsection is an unknown field); strict bodies (a price is an unknown field). The use case refuses the same repetitions again before any lookup                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Rules that read the database                           | an unknown section, entry, item or variant `404 · catalog.not_found`; a code another section holds or held, sent with a `sectionId`, `409 · catalog.code_taken`; an `entryId` with another item or section `422 · catalog.menu_entry_mismatch`; a selected variant of another item `422 · catalog.menu_variant_mismatch`; a new item archived or of another catalog, or a newly selected archived variant, `422 · catalog.menu_item_unavailable` (an entry already in that section keeps its place); each with `meta.errors[]` naming the field, such as `sections[0].subsections[1].entries[2].itemId`, only the first kind by precedence. The ids sent back are judged before the tree is compared with the stored one. An archived menu `422 · catalog.menu_archived`; an active menu left without entries `422 · catalog.menu_empty`                                                                                                                                                                                                                     |
| Lifecycle                                              | `activation` (draft → active, gated): `422 · catalog.menu_empty` without entries, `422 · catalog.menu_nothing_available` when none is available, `422 · catalog.transition_invalid` once archived (as every lifecycle route; `catalog.menu_archived` stays the answer of `PATCH` and `PUT .../structure`); `archival` (draft or active → archived, never gated). Since API v7 PR 3 these are `activate` and `archive` on `POST .../transitions`, joined by `unpublish` (active → draft, never gated) and `restore` (archived → draft, gated), so archiving is no longer final. Repeating a transition answers `200` and records nothing                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Availability                                           | `isAvailable` is true when neither the entry nor its section (nor the parent of a subsection) is suspended, its item is `active` and at least one offered variant is `active`. With `all` the entry offers every variant of the item that is not archived, the default first; with `selected` the chosen ones in order, whatever their status. Prices are Pricing's, sold out is Operations'                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Locks and concurrency                                  | The lock order of every catalog command: the version row `FOR UPDATE`, then the menu `FOR UPDATE OF` with its tree in one statement; the items and variants are read without row locks, since every catalog command that could change them waits on the same version row                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Version and audit                                      | Triggers bump the catalog version once per statement kind on insert, update and delete of `menus`, `menu_sections`, `menu_entries` and `menu_entry_variants` (X15 for menus); an upsert that changes nothing bumps nothing. Records: `catalog.menu.created` (code and name), `catalog.menu.updated` (what changed), `catalog.menu.structure_set` (`catalog.menu.structure` before and after: `sectionId:code:parent:position:status:name` per section (the same key the change check compares, so a rename alone is recorded with a different before and after), then `entryId:sectionId:itemId:mode:position:status[variants]` per entry), `catalog.menu.activated` and `catalog.menu.archived` (`catalog.menu.status`), target kind `catalog.menu`                                                                                                                                                                                                                                                                                                         |
| Plan                                                   | Create, rename, a structure with sections and activation are gated by `catalog.items`; emptying a draft menu and archiving never are                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ETag                                                   | A hash of the menu answer, item and variant names and statuses included: renaming or deactivating an item changes it, so `If-Match` fails with `412` and the client reads again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Privileges                                             | `ninaku_runtime` gets `SELECT`, `INSERT`, `UPDATE` (never `DELETE`) on `menus`, `menu_sections`, `menu_entries`; `SELECT`, `INSERT`, `UPDATE`, `DELETE` on `menu_entry_variants` (a selection nothing references, rewritten when it changes); `EXECUTE` on `catalog.assert_menu_entry_variant_configuration(uuid)`, which the deferred entry triggers call as the invoker                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Statements                                             | `PUT .../structure` 18 whatever the number of sections and entries, 8 for an unchanged tree; `GET` 7; activation 10                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Proof                                                  | `test/e2e/catalog-menus.e2e-spec.ts`, `database/tests/contracts/catalog-menus-contracts.ts` (`NINAKU_CATALOG_MENUS_OK`), C21 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md); upgrade from revision 110 with seeded menu rows gives the same schema and privileges as a fresh install                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

**Example.** `PUT /api/v1/catalog/menus/01930000-0000-7000-8000-0000000000d0/structure`
keeps Entradas and Principales (ids sent back), adds the subsection Frías
under Entradas, offers two sizes of the lomo and adds Postres:

```json
{
  "sections": [
    {
      "sectionId": "01930000-0000-7000-8000-0000000000d1",
      "name": "Entradas",
      "entries": [
        {
          "entryId": "01930000-0000-7000-8000-0000000000e2",
          "itemId": "01930000-0000-7000-8000-0000000000f3"
        }
      ],
      "subsections": [
        {
          "code": "frias",
          "name": "Frías",
          "entries": [
            {
              "itemId": "01930000-0000-7000-8000-0000000000f1"
            }
          ]
        }
      ]
    },
    {
      "sectionId": "01930000-0000-7000-8000-0000000000d3",
      "name": "Principales",
      "entries": [
        {
          "itemId": "01930000-0000-7000-8000-0000000000f5",
          "variantMode": "selected",
          "variantIds": [
            "01930000-0000-7000-8000-0000000000f6",
            "01930000-0000-7000-8000-0000000000f7"
          ]
        }
      ]
    },
    {
      "name": "Postres",
      "entries": [
        {
          "itemId": "01930000-0000-7000-8000-0000000000f8"
        }
      ]
    }
  ]
}
```

`200`, with `ETag` the strong tag of the menu:

```json
{
  "data": {
    "menuId": "01930000-0000-7000-8000-0000000000d0",
    "code": "almuerzo",
    "name": "Menú del almuerzo",
    "status": "draft",
    "entryCount": 4,
    "availableEntryCount": 4,
    "sections": [
      {
        "sectionId": "01930000-0000-7000-8000-0000000000d1",
        "code": "entradas",
        "name": "Entradas",
        "suspended": false,
        "entries": [
          {
            "entryId": "01930000-0000-7000-8000-0000000000e2",
            "itemId": "01930000-0000-7000-8000-0000000000f3",
            "itemName": "Sopa del día",
            "itemStatus": "active",
            "variantMode": "all",
            "suspended": false,
            "isAvailable": true,
            "variants": [
              {
                "variantId": "01930000-0000-7000-8000-0000000000f4",
                "variantName": null,
                "sku": "SOP-01",
                "status": "active"
              }
            ]
          }
        ],
        "subsections": [
          {
            "sectionId": "01930000-0000-7000-8000-0000000000d2",
            "code": "frias",
            "name": "Frías",
            "suspended": false,
            "entries": [
              {
                "entryId": "01930000-0000-7000-8000-0000000000e1",
                "itemId": "01930000-0000-7000-8000-0000000000f1",
                "itemName": "Ceviche de pescado",
                "itemStatus": "active",
                "variantMode": "all",
                "suspended": false,
                "isAvailable": true,
                "variants": [
                  {
                    "variantId": "01930000-0000-7000-8000-0000000000f2",
                    "variantName": null,
                    "sku": "CEV-01",
                    "status": "active"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "sectionId": "01930000-0000-7000-8000-0000000000d3",
        "code": "principales",
        "name": "Principales",
        "suspended": false,
        "entries": [
          {
            "entryId": "01930000-0000-7000-8000-0000000000e3",
            "itemId": "01930000-0000-7000-8000-0000000000f5",
            "itemName": "Lomo saltado",
            "itemStatus": "active",
            "variantMode": "selected",
            "suspended": false,
            "isAvailable": true,
            "variants": [
              {
                "variantId": "01930000-0000-7000-8000-0000000000f6",
                "variantName": "Regular",
                "sku": "LOM-R",
                "status": "active"
              },
              {
                "variantId": "01930000-0000-7000-8000-0000000000f7",
                "variantName": "Grande",
                "sku": "LOM-G",
                "status": "active"
              }
            ]
          }
        ],
        "subsections": []
      },
      {
        "sectionId": "01930000-0000-7000-8000-0000000000d4",
        "code": "postres",
        "name": "Postres",
        "suspended": false,
        "entries": [
          {
            "entryId": "01930000-0000-7000-8000-0000000000e4",
            "itemId": "01930000-0000-7000-8000-0000000000f8",
            "itemName": "Flan",
            "itemStatus": "active",
            "variantMode": "all",
            "suspended": false,
            "isAvailable": true,
            "variants": [
              {
                "variantId": "01930000-0000-7000-8000-0000000000f9",
                "variantName": null,
                "sku": "FLA-01",
                "status": "active"
              }
            ]
          }
        ],
        "subsections": []
      }
    ]
  }
}
```

### K7 as built (no migration, baseline revision 90)

| Piece               | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Schema              | No migration and no SQL object: the evidence below shows every probe of both reads on an existing index, and the cost that misses the budget is building and sending the JSON of a large body, which no index removes. The baseline stays at revision 90                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Routes              | `GET /catalog/outlets/{outletId}/sellable-items` (C17, `200`, `304`) and `GET /catalog/outlets/{outletId}/sellable-item-search` (C19, `200`); both behind `SessionGuard` and `TenantContextGuard`, every error as Problem Details: `400 · foundation.validation_failed` and `400 · collection.cursor_*`, `403 · tenant.context_rejected`, `403 · catalog.action_forbidden`, `403 · authorization.scope_unavailable`, `404 · organization.structure_not_found`. C10 for the till is the `categories` of C17 (the K3 note: the point-of-sale reads carry the tree); `GET /catalog/categories` stays a back-office read                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Authorization       | `catalog.sellables.view` at the outlet through one gate shared with C18 (`application/till/till-gate.ts`), decided before the outlet is looked up: a refused caller gets the same plain `403` for its own outlet's neighbour, an unknown, a closed and another organization's outlet; only a caller holding the permission organization-wide learns `404 · organization.structure_not_found`. Kitchen, bar, `catalog.items.view` alone and no role are refused; cashier and waiter scoped to their outlet read it. A member anchored at a business unit is refused at an outlet no unit operates today (no unit resolves). Never gated by the plan; reading records nothing. The permission and the statements that resolve the business unit of the outlet (the till read, the search and the barcode scan C18) run in one read-only `REPEATABLE READ` transaction (`TenantTransactionRunnerService.runReadOnlySnapshot`, the same `BEGIN` statement), so a reassignment of the outlet that commits between the permission and the read can never serve a caller anchored only at the old unit the exclusive items of the new one: the permission was judged on the snapshot the read uses. `catalog.sellables.resolve` and `admit` take the unit from their caller and decide no permission, so they have no such window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Sellable rule       | One SQL fragment for the till lists and the scan (`infrastructure/reads/sellable-rule.queries.ts`, review S1): an active item of the default catalog, listed by the unit that operates the outlet on its site's date (the K6 predicate of the item list, now `listedAt`, drift-guarded against `variant_is_listed` and `listed_items`; *Decided*: not a call to `catalog.listed_items`, whose PL/pgSQL body the planner cannot see into and which returns every listed pair of the unit, 21.5 ms on 20,000 items in K6), with at least one active variant, and with no item-level required offer (`minSelections > 0`) whose offer or group is not active or whose available options are fewer than its minimum (since F1: whose available options cannot reach its minimum in units, the sum of their `maxQuantity`). Since B2b also with no live required combo group (`bundleComposable`) that is suspended or whose available choices (active choice, active variant of an active item) cannot reach its minimum in units, the sum of their `maxSelectionCount` (999 when absent): the one rule B1 answers as `isSatisfiable`; since F1b a choice whose component is a combo counts only when that combo can be composed too, down to the third combo level ("F1b as built" under "B2 as built"); since F1c a choice counts only when its component would be sold on its own at the same unit by this rule, listing and required modifiers included ("F1c as built"). An option is available when it is active, its group is active and its `catalog_variant` target variant is active (since K8 also the target variant's item, see "K8 as built"; since K16b the target must also be sellable at the unit and outlet of the reader, the way a combo component is: listed, not hidden, composable when it is a combo and configurable, see "K16b as built"). The category hierarchy is not part of the rule (rule 8). C18 (`MATCH_AT_OUTLET`) applies the same fragment plus the scanned variant being active, instead of `catalog.variant_is_listed` alone: before the review a scan still resolved an item whose required group had lost its options, which the lists left out; a non-sellable item answers `data: null` exactly like an unknown code, in the same single statement (budget still 7). `test/e2e/catalog-till-parity-parity.e2e-spec.ts` proves the scan and the sellables read agree on every case of the rule                                                                                                                                                 |
| C17 read model      | `data: { businessUnitId, categories[], items[], modifierGroups[] }`, `meta: { catalogVersion, truncated, omittedItems }` (review A1: bounded lists answer `truncated` in `meta`, as `FOUNDATION_HTTP_AND_OBSERVABILITY.md` and the sibling reads do). `omittedItems` is the warning counter C13 asks for: how many items the outlet would otherwise sell that are left out because a required group cannot be filled, counted in the same statement over every candidate (not only the first 2,000), never naming them. Names follow the API's identifiers (`itemId`, `variantId`, `categoryId`, `parentCategoryId`, `modifierGroupId`, `optionId`) instead of the sketch's `id`; no codes, SKUs, descriptions, barcodes or prices, as decided. `categories` holds the effectively active categories (descending from active roots through active children only, rule 2), depth first by `sortOrder`, lowercase name and id, and only those that hold something the outlet sells now (*Decided* by the owner, OV25): an item sold by the outlet whose primary category, when effectively active, is the category or one of its descendants, so a category whose items are all hidden at the outlet, delisted from the unit, inactive or archived, or that has no items, is not sent, and the ancestors that lead to a category that is sent are. A secondary classification does not count, because the till places an item only under its primary category. The same statement decides the items and the categories (the set of items sold is the one that feeds both), the tree covers the whole outlet and not the first 2,000 items, and the entity tag moves with every change that empties or fills a category because each of them moves the catalog version or the outlet's menus; there is no parameter to show empty categories, the till shows its own message from what it receives. An item's `categoryId` is its primary category when that category is effectively active, otherwise `null` (the till's "Other"). An offered group without an available option leaves the item (and a required one omits the item); `defaultOptionIds` are the offer's defaults in option order, filtered to available options. `modifierGroups` defines every available group offered by any sellable item of the outlet, not only by the first 2,000 (*Decided*: a truncated till then has the definitions of the groups that C19 items name; bounded by the 500-group limit). At most 2,000 items in name order (`name_search_key`, id), `meta.truncated` when more are sold |
| C17 tag and caching | Strong `c<catalog version>-s<structure version>-<business unit or none>`, `Cache-Control: private, no-cache`. The use case receives an `isCurrent` check built from `If-None-Match` (weak comparison); after the outlet statement it answers `304` with no further SQL. A `200` builds its tag from the versions read in the same statement as the data, so the tag and `meta.catalogVersion` always name the body. An outlet with no unit today answers `200` with empty lists and a tag ending in `-none`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | A refused caller who sends a current tag gets the plain `403`, never `304`, because the tag is compared only after the permission (proven over HTTP); every dependency of the tag has a test: a catalog write, another organization's write (no change), an outlet assigned to a unit and a unit renamed (structure version) |
| C19                 | `q` is optional (*Decided*: without it the pages walk everything the outlet sells, the fallback the scenario row "C19 pages through all of them" needs); with it, a prefix of the name, the code or the SKU of an active variant with the C2 keys (review S2: a retired variant's SKU finds nothing at the till, while the back-office list keeps matching any SKU) (`catalog.search_key`, literal `%`, `_` and backslash). `barcode` is not built (*Decided*: C18 already answers a scan with the exact variant; sending it answers `400`). The repository's `after`/`before` cursors replace the sketched `cursor`; the binding holds the route, the organization, the outlet, the unit operating it today and `q`, and is decoded only after the permission and the outlet. Item shape of C17; `limit` 1 to 100, default 50; no ETag. A hidden item and an unknown name both answer an empty page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Statement budgets   | C17 `200`: 8; C17 `304`: 7; C19: 8 (session, membership, `BEGIN`, tenant context, permission, outlet state, the read, `COMMIT`), proven by `test/e2e/statement-budget.e2e-spec.ts`. The design's "6" for the `200` counted three reads after three statements; the read is one statement so that the data, the tree, the groups and the version share one snapshot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Offline readiness   | Every till read answers the organization-wide catalog version it was read at as `meta.catalogVersion` (an integer, read in the same statement as the data): a client syncing the pages of one walk can tell that the catalog changed between pages, and a future snapshot or "changes since version N" feed can reuse it. Item, variant, group, option and category ids are stable UUIDs, the search pages by keyset cursor, and the answer is already the authorized subset of one outlet. Not built: the snapshot, the delta feed and a device-scoped grant. Per `BUSINESS_DESIGN.md` §4 and D06 only Sales commands replay offline; catalog writes stay online                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Index evidence      | `EXPLAIN (ANALYZE, BUFFERS)` as `ninaku_runtime` under row level security, local. The `perf:http` world (2,000 items, 150 groups of 7 options, one root inactive): the 925-item outlet C17 15.5 ms (27,519 buffers), the 300-item restaurant outlet 9.6 ms (16,710), C19 pages 1.8 to 3.5 ms. A scratch world of 20,000 items × 3 variants × 5 offers on two items of three, half listed: C17 88.8 ms (203,559 buffers, 2,001 of about 9,000 sellable items answered), C19 first page 3.9 ms, after a cursor 3.5 ms, prefixes 5.2 and 9.2 ms. Every probe uses an index: `catalog_items_name_search_idx` and `catalog_items_code_search_idx` for the organization, catalog and status, the unique `(business_unit_id, item_id)` of `business_unit_items`, `item_variants_item_status_idx`, `item_modifier_groups_item_idx`, `modifier_options_group_status_idx`, `item_categories_pk` and the primary keys of `modifier_groups` and `modifier_options`. History: the first formulation evaluated the sellable rule again for every offered group (768 ms and 2.5 million buffers on 20,000 items), fixed by materializing the sold set; a set-based rewrite of the item enrichment was tried in the review and reverted because the planner, estimating one row per CTE, rescanned the grouped offers for every item (320 ms over HTTP); the review then replaced the joins on `modifier_groups`, which the planner hashed again for every item, with primary-key lookups (925 items: 33.7 to 15.5 ms; restaurant: 21.6 to 9.6 ms). A local single-machine run, not a capacity claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Plan stability      | The plans of C17, C19, the scan and `resolve`/`admit` must not depend on fresh statistics. Right after an organization imports a few thousand items, the table statistics still describe the old data (on a large shared table autoanalyze waits for 10 % of all its rows to change), the planner estimates about one row for that organization, and it joined every existence check of the sellable rule (an active variant, a configurable variant, an offer, a group with an available option) as a semi join whose inner side scanned all of the organization's variants or offers once per candidate item; the C19 page joined `catalog.items` back the same way and computed the enrichment of every scanned row before filtering it. In CI the search pages grew from 284 ms to 4.8 s and then answered `503` (statement timeout `57014`). *Decided*: every existence check in `sellable-rule.queries.ts` and the till statements is written as `anyRowOf`, a scalar `coalesce((SELECT true … LIMIT 1), false)` that PostgreSQL never turns into a join, so it runs per row with the item, variant, offer or group key as the leading index condition; the page carries the item columns from the ordered scan instead of joining `catalog.items` again; the primary images are scalar lookups on their partial unique indexes; a variant override names its `item_id` (equal by the composite foreign key) so `item_modifier_groups_live_idx` is used by its prefix; and C17 collects the offered groups per sold item (`offered`) instead of a semi join over the sold set. No migration and no new index: every probe leads with columns of an existing index. Responses, ordering, statement budgets and tags are unchanged. Evidence (`EXPLAIN (ANALYZE, BUFFERS)`, local, 2,001 items imported after `ANALYZE` beside a neighbour of 20,000 variants): before, the C19 page grew with its position from 51 to 84 ms on the first page to 1,048 ms on the sixteenth (665,074 buffers) and C17 took 380 ms (524,647 buffers), against 2 ms and 23.5 ms with fresh statistics; with offers on 6 groups the walk hit the 5 s statement timeout. After, C19 pages take about 1.5 ms (1,280 buffers) and C17 23 ms (25,163 buffers), the same with stale or fresh statistics; with 200 groups, C19 4 ms and C17 68 ms either way (the previous SQL, fresh: 3.8 to 4.3 ms and 93 ms). `till-read.plan.integration-spec.ts` reproduces the import and bounds the rows and buffers of every C19 page and of C17; it fails on the previous SQL                              |
| Performance         | Classified hot and measured (`docs/operations/PERFORMANCE_BASELINE.md` §14.4), one client p50/p90/p95/p99: the `304` 1.82/1.98/2.10/2.57 ms; the search 5.0 to 7.6 ms p95 and below; the `200` of C17 23.99/25.41/25.71/28.28 ms on 925 items (418 KB) and 15.24/16.71/17.10/17.76 ms on the 300-item restaurant (214 KB). Both `200` rows miss only p50 and are recorded in `KNOWN_BREACHES` with their cause (one body by design; building and sending the JSON). The first K7 measurement of the 925-item row was 35.10/36.29/36.69/38.09 ms. *Decided* (review S3): any holder of `catalog.sellables.view` can loop the full `200` and only the global limiter (120 requests per minute per client IP) stops it; the `304` is the cheap path the till uses on every refresh, and no route-specific throttle is added in K7                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Still open          | `CatalogSellableContract` and admission (K8, C20); a `barcode` filter on C19; whether an option whose target item is inactive should count as unavailable (closed by K8: it does not); per-variant assortment and per-variant offers; the snapshot and delta feed for offline tills (the feed is written since K12a; serving it is K12b)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### K8 as built (no migration, baseline revision 90)

| Piece                                                                        | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                                                                       | No migration and no SQL object; the baseline stays at revision 90. *Decided* with `EXPLAIN (ANALYZE, BUFFERS)` as `ninaku_runtime` under row level security, local, on an organization of 2,000 items with 600 of them offering 3 groups of 6 options: the share of the version row 1.3 ms (61 buffers), the share of the unit row 0.15 ms (76), the read of one variant 3.6 ms and of 100 variants 10.7 to 11.1 ms (8,939 buffers), every probe on an index (`item_variants` and `items` primary keys, the unique `(business_unit_id, item_id)` of `business_unit_items`, `item_variants_item_status_idx`, `item_modifier_groups_item_idx`, `modifier_options_group_status_idx`, `item_modifier_group_defaults_pk`); the only sequential scans are over the handful of rows of `business_units`, `catalogs` and `modifier_groups` of a development database. A PL/pgSQL helper would hide that plan from the planner (the K7 reason for not calling `catalog.listed_items`) and add a migration for no gain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Contract                                                                     | `CatalogSellableContract` (`src/modules/catalog/contracts/catalog-sellable.contract.ts`), an abstract class that is also the DI token, bound with `useExisting` to `CatalogSellables` (`application/sellable/catalog-sellables.ts`) and exported by `CatalogModule`, which a consumer imports from `src/modules/catalog/contracts/catalog.module.ts`. `resolve(context, { businessUnitId, variantIds })` answers `{ catalogVersion, verdicts[] }`, one verdict `{ variantId, sellable, refusal, snapshot }` per requested variant in the requested order. `admit(context, { businessUnitId, lines: [{ variantId, modifierOptionIds }] })` answers `{ catalogVersion, lines: [{ snapshot, modifierOptionIds }] }` or throws `CatalogNotSellableError` (`contracts/catalog-sellable.errors.ts`) with every refusal `{ line, variantId, reason, modifierGroupId, optionId }`; the consumer maps it to its own public code. Both run in the caller's tenant transaction (the `TransactionContext` it passes, as `TenantAuditContract`), check no permission (the consuming command authorizes itself, exactly as it does before writing its own tables) and record nothing. No HTTP route, no OpenAPI change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Snapshot                                                                     | `variantId`, `itemId`, `itemCode`, `itemName`, `variantCode`, `variantName`, `isDefault`, `sku`, `salesUnitCode`, `minimumSalesQuantity`, `salesQuantityStep`, `maximumSalesQuantity` (exact decimals as strings) and `modifierGroups[]`: the item-level offers whose offer and group are active and which keep an available option, in offer order, each `{ modifierGroupId, name, minSelections, maxSelections, defaultOptionIds, options[] }` with the available options `{ optionId, name, kind, variantId, maxQuantity }` in option order and the defaults filtered to available options (the C17 rules). A known variant that is not sellable keeps its snapshot (Pricing configures what is not on sale yet); an unknown one answers `snapshot: null`. `catalogVersion` is the organization's version read in the same statement, the number C17 and C19 answer as `meta.catalogVersion`, so a sale can store which catalog it was admitted against (offline replay, D06)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Refusals                                                                     | A closed domain, published from `domain/sellable/sellability.ts`, named in this order (the first failing fact wins): `unknown` (no such variant in the caller's organization: another organization's variant is the same answer, RLS hides it), `business_unit_unavailable` (unknown, another organization's, inactive or malformed unit: one answer), `item_archived`, `item_inactive`, `variant_archived`, `variant_inactive`, `assortment_none` (the unit sells nothing from the catalog), `not_listed` (delisted under `all`, not listed under `selected`), `required_modifier_unsatisfiable`, and since B2b `bundle_group_unsatisfiable` (a combo with a required group that is suspended or whose available choices cannot reach its minimum; `admit` explains it per group at its path instead). The verdict itself is never derived from these facts: `sellable` is the shared rule, and the facts only name the reason (a refusal no fact explains answers `not_listed`). `admit` adds, per line: `option_not_offered` (not an option of an active item-level offer of that item: an unknown option, another item's option, another organization's option), `option_unavailable` (offered, but inactive, in an inactive group or pointing to an inactive variant), `selection_below_minimum` and `selection_above_maximum` (per offered group, counting the chosen available options)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Sellable rule                                                                | The same SQL fragment as the till lists and the scan (review fix: an option whose `catalog_variant` target variant is active but whose item is archived or inactive is unavailable everywhere, the till lists, the scan, the contract and the C13 offer command, which now judges defaults with the same `availableOption`; at the time of this review the target did not have to be listed at the unit (K16b changed that: the target is judged like a combo component); statement budgets unchanged: C17 8 and 7, C19 8, C18 7, `resolve` 1): `sellableItem` of `infrastructure/reads/sellable-rule.queries.ts` plus the variant being active, the exact composition of C18 (`MATCH_AT_OUTLET`). The diagnosis reuses its pieces (`listedAt`, the new `assortmentModeAt` it is built on, `requiredGroupsSatisfiable`), and the snapshot reuses the till's offer pieces (`offerDefaults`, `groupHasAnAvailableOption`, `availableOption`, moved to the same file). A unit test pins the fragment inside the statement, and `test/e2e/catalog-till-parity-parity.e2e-spec.ts` now compares the scan, the sellables read and the contract on every case of the rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Lock order                                                                   | `resolve` takes no lock. `admit` takes, in this order: the organization's `catalog.catalog_versions` row `FOR SHARE`, then the business unit row `FOR SHARE`, then reads (3 statements; `resolve` is 1). Every catalog command takes the version row `FOR UPDATE` first, and every catalog table, `item_modifier_group_defaults` included, carries statement-level bump triggers that update that row, so the shared version row fences every catalog change of the organization, even a write outside any command (shared per-row locks could not fence an insert such as a new delisting row or a new required offer). The unit row `FOR SHARE` blocks any update of that unit's row while the admission is open: its deactivation by the Organization module, which never touches the catalog version, but also a rename or anything the structure version trigger bumps. `admit` never reads defaults. *Decided*: no per-row `FOR SHARE` on items, variants or options (the design's sketch through `catalog.assert_variant_listed`): the version row already excludes every change those locks would, and locking every row of a sale would dirty pages and create multixacts on the sales path for nothing. The application never calls `catalog.assert_variant_listed` (it stays in the database because the order-line trigger of the Sales schema, `database/canonical/0110_sales.sql`, calls it; `CatalogSellableContract` is the in-process path): its rule lacks the default catalog and the required groups of K7, it raises one generic `23514` per variant and it needs one statement per variant                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Consequence                                                                  | PostgreSQL does not queue a `FOR SHARE` behind a waiting `FOR UPDATE`, so a sale never stalls behind a pending catalog edit: new admissions keep taking the shared version row while the command waits. The cost is the reverse: a catalog command of the organization (any item, any unit, deactivating a sold-out dish during a rush included) waits until no admission of the organization is open, and under continuous overlap of sale transactions in a multi-unit organization it fails with `57014` after `DATABASE_STATEMENT_TIMEOUT_MS` (5,000 ms by default, `environment-variables.schema.ts`). *Correction (measured on 2026-10-06)*: earlier text said it failed after `DATABASE_LOCK_TIMEOUT_MS` (2,000 ms) with a lock timeout; PostgreSQL applies `lock_timeout` to each lock acquisition separately, and a command waiting on a version row shared by several sales waits on each sale's transaction in turn, each wait far below 2 s, so the lock timeout never fired in 1,209 measured commands and the statement timeout is the real limit. Two admissions never wait for each other; admissions and commands never deadlock; an admission that arrives while a command already holds the version row waits and then judges what that command committed, never a half state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Requirement for Sales                                                        | Call `admit` last in the sale's transaction, right before the sale's own writes, and commit at once: the time an admission is held is the time every catalog writer of the organization is blocked. Keep the transaction open 50 ms or less after `admit` (the measured gate below), and measure that hold with `npm run perf:admission` before Sales ships                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Gate before Sales ships                                                      | MEASURED on 2026-10-06: keep the version-row share (gate closed, with the Sales requirement above as its condition). `npm run perf:admission` (`tooling/performance/run-admission-benchmark.ts`, opt-in, never in `verify`, `npm test` or CI) boots the compiled application with the production pool (10 connections) and timeouts, seeds one organization with 2,000 items (1,749 sellable at a unit in mode `all`, 873 at a unit in mode `selected`, a third of them offering two modifier groups), and runs N tills in {1, 4, 16, 64} that admit 1 to 5 random lines through the real contract and hold the transaction H in {20, 50, 200} ms, with a think time of 4 × H (realistic, 20 % duty cycle) or 0 (artificial rush), while one writer cycles an item deactivation and reactivation, a delisting and listing and an assortment mode change through the real use cases, 20 s per cell. Results (local, one machine under load, not production capacity; `docs/operations/PERFORMANCE_BASELINE.md` §15): 43,210 admissions, none failed, `admit` p99 at most 62.4 ms in every cell, so sales never waited; zero lock timeouts in 1,209 commands; in the realistic profile up to the 16 tills the pool serves, the writer succeeded 100 % at every hold, with its p99 growing to 776 ms (N 16, H 200) and one command of 4.6 s (N 16, H 50); with H at most 50 ms it succeeded 100 % in every cell, rush included (p99 up to 3.1 s). It degrades only with H = 200 ms: rush 95.8 % at 4 tills and 77.8 % at 16, and realistic 93.8 % at 64 tills, whose offered load (12.8 open transactions) exceeds the pool, so it behaves like rush; each failure is a `57014` statement timeout at 5.0 to 5.4 s. Fallback, kept as the next slice only if Sales must hold the admission longer than 50 ms: a lock-free `admit` that reads once like `resolve`, stores `catalogVersion` with the sale and relies on Sales' own foreign keys to `catalog.item_variants` and `catalog.modifier_options` (`FOR KEY SHARE`), never per-row shares |
| Input                                                                        | At most 100 variants per `resolve` and 100 lines per `admit` (the page maximum of the API), at most 100 options per line; an empty request, a repeated variant in `resolve` or a repeated option in a line throws `CatalogSellableRequestInvalidError` with `empty`, `too_many`, `too_many_options` or `duplicate` before any SQL. The same variant may appear on several lines of one admission (two burgers cooked differently). Ids are compared lowercase; a malformed variant id answers `unknown` and a malformed unit `business_unit_unavailable`, neither reaching SQL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Known defect (2026-10-07; fixed: the quantities by K9d, the offer id by K9e) | `admit` takes `modifierOptionIds` per line, so it cannot carry the quantity of an option and judges each group on the count of distinct options, while the Sales schema stores a quantity per selected option and judges groups on the sum of quantities (`0110_sales.sql:4229-4247`); it also does not answer the offer id (`item_modifier_groups.id`) Sales must store. Fixed by slices K9d and K9e (no migration), the quantity-aware admission with the effective offer identity of [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md) §5.1, after the stable offer identities of K9a–K9c (architect's order), which supersedes the "reported, not judged" note below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Decisions where the design was silent                                        | `admit` takes lines instead of one variant, so a sale admits all its lines in one call and one read. The chosen options are the final selection: `defaultOptionIds` are what the till preselects, and `admit` never adds them (the till sends them when it keeps them). The quantity of an option (`maxQuantity`) is reported, not judged: the option ids of a line are a set, and how many of one option a line carries belongs to Sales (superseded by K9d: the line carries each option's quantity, judged against `maxQuantity`, and the groups on the sum of units)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Proof                                                                        | `src/modules/catalog/domain/sellable/sellability.spec.ts`, `src/modules/catalog/application/sellable/catalog-sellables.spec.ts`, `src/modules/catalog/infrastructure/sellable/sellable.queries.spec.ts`; over PostgreSQL through a consumer module that sees only the contract (`test/fixtures/catalog-sellable/`): `test/e2e/catalog-sellable-contract.e2e-spec.ts` and `test/e2e/catalog-sellable-concurrency.e2e-spec.ts`; the boundary for a future Sales module in `tooling/repository/check-module-boundaries.spec.ts`. See [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Still open                                                                   | The Sales and Pricing consumers (and the public code Sales gives `CatalogNotSellableError`); the hold time of Sales' real transaction, measured with `npm run perf:admission` before Sales ships, and the lock-free `admit` only if that hold exceeds 50 ms; the till's offline snapshot (K12b) and delta feed (written since K12a, "K12a as built"); per-variant offers. `catalog.assert_variant_listed` and `catalog.resolve_barcode` stay with their grants and are not to be retired: no application path calls them, but the order-line trigger of the Sales schema (`database/canonical/0110_sales.sql`, created by the canonical install although no module uses Sales yet) calls `assert_variant_listed`, and the database contracts (`topology-catalog-contracts.ts`, `catalog-foundations-contracts.ts`, `prepare-database-contracts.ts`) exercise both; they remain the database-level admission of that trigger until Sales is built, and `CatalogSellableContract` is the in-process path                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### Idempotent creates as built (migration `0081_catalog_creates_remember_their_request`, baseline revision 91)

| Piece                        | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Why                          | Offline readiness and the owner's "close all pending": a retry after a lost response must return the first result. Before, a retried category, group or option create answered `409 · catalog.code_taken` (the client could not tell its own success from a real clash), and a retried item create answered `409 · idempotency.key_reused` once the item had been edited. The debt recorded in "Hardening round as built" and the open decision of "Leftovers closed" are closed here                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Schema                       | One migration, expand only: `catalog.categories`, `catalog.modifier_groups` and `catalog.modifier_options` gain `creation_idempotency_key uuid` with the partial unique indexes `catalog_categories_creation_idempotency_uq`, `catalog_modifier_groups_creation_idempotency_uq` and `catalog_modifier_options_creation_idempotency_uq` on `(organization_id, creation_idempotency_key) WHERE creation_idempotency_key IS NOT NULL`, exactly like `catalog_items_creation_idempotency_uq`; the four tables gain `creation_request_hash text`, constrained by `<table>_creation_request_hash_chk` (`items_`, `categories_`, `modifier_groups_`, `modifier_options_`) to be `NULL` or a 64-character lowercase hex digest stored next to a key, so a malformed hash or a hash without a key is refused by PostgreSQL itself (the item create always writes both; a key without a hash stays legal for the items created before revision 91). The checks can never fail on existing rows, whose new column is `NULL`. Nothing is dropped or renamed and every new column is nullable, so the previous API keeps working during the rollout (it writes neither column, and rows without a key never collide). The indexes are built inside the migration transaction, which briefly blocks writes on those tables, acceptable while catalogs are small (as `0076`). Grants are unchanged: `ninaku_runtime` holds `SELECT, INSERT, UPDATE` on the whole tables, which covers the new columns (checked with `has_column_privilege`); row level security is unchanged. Proven by `database/tests/contracts/catalog-creation-request-contracts.ts`, and by an upgrade of a populated revision 90 database (2,000 items with keys, 2,000 categories, 500 groups, 3,000 options): the first `db:prepare` applies `0081`, keeps every row and leaves the item keys without a hash, a second `db:prepare` changes neither the schema nor the ledger, and the column order equals a fresh install of the canonical |
| Request hash                 | `requestFingerprint` (`src/foundation/idempotency/request-fingerprint.ts`): the lowercase hex SHA-256 of the canonical JSON of the request, keys sorted by code unit at every depth, arrays in their order, absent fields omitted and `null` kept. It is computed in the application layer over the validated, normalized request, never over the raw body: the item create hashes its draft with the categories sorted by id and the quantities in their shortest form (`itemCreationRequest`), so the same categories in another order or `1.0` for `1` still replay; the category and group creates hash their draft; the option add hashes `{ modifierGroupId, option }`, because the group in the path is part of the request. The hashed request is typed as a plain JSON value (one builder per create that names every field of its draft, so a new draft field cannot be left out of the hash), and the fingerprint throws on a value JSON cannot represent exactly (a `Date`, a `Map`, a `Set`, a non-finite number, `undefined` inside an array) instead of hashing it as something else. The body itself is never stored, and neither the hash nor the key is ever answered or recorded                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Semantics (the four creates) | `resolveIdempotentCreation` (foundation) under `createIdempotently` (`application/catalog-creation.ts`): after the admission and the catalog version row, the key is looked up in the module's own table by organization and key. Found with the same hash: `201`, the resource as it is now (even after an edit) with its current ETag and `Idempotent-Replayed: true`, nothing written or recorded. Found with another hash: `409 · idempotency.key_reused`. Found without a hash, which only items created before revision 91 can be: compared with the row as it is now, as before (`matchesCreationIntent`); the other tables never stored a key before revision 91 and pass no comparator, so there a key without a hash, which only a manual write could leave, answers `409 · idempotency.key_reused`. Not found: the create runs and its `INSERT` claims the key with `ON CONFLICT (organization_id, creation_idempotency_key) WHERE creation_idempotency_key IS NOT NULL DO NOTHING`; a lost claim reads the stored creation and replays or refuses. The lookup comes before the category and group limits, the parent, the variants and the codes, and before the `If-Match` of the option add, so a replay never answers a refusal the first call did not. `Idempotency-Key` is required on the four creates, the rule C4 already had (`400 · foundation.validation_failed` when missing or not a UUID v4 or v7); no client existed, so requiring it broke none. A key is scoped to the organization and to one kind of create: the same key in another organization, or on a create of another kind, is independent. A different key with a taken code still answers `409 · catalog.code_taken`                                                                                                                                                                                                                                                                                         |
| Concurrency                  | Every create takes the catalog version row `FOR UPDATE` before the lookup (lock order, §5), so parallel retries of one key run one after the other: the first creates and the others find its committed row and replay, with one record and no `500`; parallel requests that share a key with different bodies answer one `201` and `409 · idempotency.key_reused` for the others. For items, categories and groups the `ON CONFLICT` claim is a second line of defence (a mutation that skips the lookup still replays them); the option add relies on the lookup, because its in-group code check runs before the insert, which the version row makes safe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| One category and its tag     | `GET /catalog/categories/{categoryId}`: `catalog.items.view` organization-wide or at `businessUnitId`, the gate of every catalog read (a plain `403 · catalog.action_forbidden` before any lookup, the same `404 · catalog.not_found` for an unknown or foreign category). It answers the category with its depth, its own status and its effective visibility, a strong ETag and `Cache-Control: private, no-cache`, and `304` with no body to a matching `If-None-Match` (weak comparison). The tag (`categoryEntityTag`) is the SHA-256 of exactly that representation, in a fixed field order. *Decided:* the derived `isEffectivelyActive`, `blockedByAncestorId` and `depth` belong in the hash. A strong validator must change whenever the representation changes (RFC 9110 §8.8.1); leaving them out would let a `304` confirm a visibility or depth that an ancestor's deactivation or move made stale, which is exactly what the screen shows. The price is that such an ancestor change invalidates its descendants' tags, so a write sent with the old tag answers `412` and the client reads the category again; that is rare, cheap and never loses data. Edits of other categories that do not hide or move it, and unrelated catalog writes, leave the tag unchanged, unlike the organization-wide tree tag, which is unchanged                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Documented answer headers    | The `201` of the four creates documents `Cache-Control: private, no-store` and `Idempotent-Replayed: true` (present only on a replay) in OpenAPI; their `ETag` is described in the operation text, as for every tagged write, because the semantic check reads a documented `ETag` header on a success as a conditional read                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Category writes              | Create, edit, re-parenting, deactivation, reactivation and archival (since API v7 PR 3: create, `PATCH` with the move, and the transitions route, which answers `{ categoryId, status }` with the same tag) answer the category with that tag and `Cache-Control: private, no-store`; the five writes on an existing category accept an optional strong `If-Match`, compared right after the catalog version row, the category row `FOR UPDATE` and one read of the category and of the hierarchy (only when the header is sent): a stale or weak tag answers `412 · foundation.precondition_failed` and nothing is written or recorded; without the header the write is not conditional, never `428`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Proof                        | `src/foundation/idempotency/request-fingerprint.spec.ts`, `src/foundation/idempotency/resolve-idempotent-creation.spec.ts`, `src/modules/catalog/application/categories/create-category.use-case.spec.ts`, `src/modules/catalog/application/modifiers/modifier-creations.use-case.spec.ts`, `src/modules/catalog/application/categories/category-entity-tag.spec.ts`, `src/modules/catalog/application/items/create-item.use-case.spec.ts`; over PostgreSQL `test/e2e/catalog-idempotent-creates.e2e-spec.ts`, `test/e2e/catalog-idempotent-creates-concurrency.e2e-spec.ts`, `test/e2e/catalog-category-preconditions.e2e-spec.ts` and `test/e2e/catalog-items.e2e-spec.ts`. Mutations of the hash comparison, of the stored-hash path, of the claim mapping, of the category `If-Match` and of each field of the category tag fail these tests; a lookup that ignores the organization survives them, because row level security already scopes it (the index scope is proven by the database contract). See [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Not built                    | Variant, matrix and barcode adds keep no key: their code or value is required and unique, so a retry answers `409` without duplicating (K4). Catalog writes other than these creates stay online only (D06)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Contract step and where-used as built (migration `0082_catalog_contract_step_and_offers_by_group`, baseline revision 92)

| Piece            | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Why              | The owner's "close all pending": the expand step of the hardening round left `catalog.modifier_options.is_default` in place for the previous API, and K5 left the where-used read of a group unbuilt, so a manager could not see which items a deactivation or an archival of a group or an option would touch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Contract step    | Migration `0082` runs `ALTER TABLE catalog.modifier_options DROP COLUMN IF EXISTS is_default` inside the claim of the repository's migrations, so it can run again. Safe: no statement of the running code reads or writes the column since revision 90 (a unit test checks every modifier statement), the previous API (before PR 512) is long gone, and production holds no catalog data yet. `rg` over `database/canonical` and `database/access` found one reference to the option column, its definition in `catalog.modifier_options` (`0080_catalog.sql`), and a query of `pg_proc`, `pg_views`, the indexes, constraints and triggers of the table confirmed it: no function, view, index, trigger, constraint or seed named it; outside the schema only the database contract of `0080` and a unit-test title named it, both updated here (in PostgreSQL 18 its `NOT NULL` was a `pg_constraint` row, dropped with the column). Every other `is_default` belongs to variants, catalogs, bundle group items, or the fiscal, production, commerce and cross-domain tables, and stays. The canonical `0080_catalog.sql` is the end state without the column |
| Index            | `item_modifier_groups_group_idx (modifier_group_id, organization_id)`, plain, in the same migration (`CREATE INDEX IF NOT EXISTS`). *Decided* with `EXPLAIN (ANALYZE, BUFFERS)` as `ninaku_runtime` under row level security on two organizations of 2,000 items and 150 groups, one group offered by 1,500 items (15,009 offers in all): without it the offers of a group were a sequential scan of every organization's offers (13,509 rows removed, 1,001 buffers); with it a bitmap index scan (3 index buffers), the first page in 3.7 ms and a later page in 0.9 ms, and the group lookup an index-only scan. It also serves `item_modifier_groups_group_organization_fk`, the foreign key of an offer to its group, which had no index leading with the group                                                                                                                                                                                                                                                                                                                                                                                              |
| Upgrade          | Proven locally on a revision 91 database holding `is_default = true` rows: one `db:prepare` dropped the column and added the index, the rest of the schema (`pg_dump --schema-only`) and the options unchanged, and the result equal to a fresh install at revision 92; a second `db:prepare` changed nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Route            | `GET /catalog/modifier-groups/{modifierGroupId}/offers`: every live offer of the group: the item-level rows `PUT /catalog/items/{itemId}/modifier-groups` writes and, since K9g, the active override of a variant (an opt-out is not a use of the group and is left out), each `{ itemId, variantId, code, name, status, minSelections, maxSelections, sortOrder, defaultOptionIds }` (`variantId` null for the item-level offer), ordered by the item name key and then the offer id with the defaults in the order of the group. *Decided:* `status` filters the items and, absent, answers every item whatever its status, archived ones included, like `GET /catalog/modifier-groups` answers every group: the read is about impact and history. A group of any status answers; one no item offers answers an empty page                                                                                                                                                                                                                                                                                                                                      |
| Paging and cache | Keyset pages ordered by the item's `name_search_key` and then its id (`limit` 1 to 100, default 50, `after` / `before`, `meta.pageInfo`), the signed opaque cursor bound to the route, the organization, the group, `status` and `businessUnitId`. No `ETag` (a page of a list), `Cache-Control: private, no-cache`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Authorization    | The gate of every catalog read: `catalog.items.view` organization-wide or at `businessUnitId`, checked before the cursor is decoded and before any lookup, so a caller without it gets the plain `403 · catalog.action_forbidden` whatever the group, the unit or the cursor; an unknown group and another organization's group answer the identical `404 · catalog.not_found` (row level security hides the latter); only an organization-wide reader learns `404 · organization.structure_not_found`. Never plan-gated; no write, no record                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Statements       | Two: the group lookup by id and one page of the offers; the item read (C3) reuses the same defaults fragment (`offerDefaultIds`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Proof            | `src/modules/catalog/application/modifiers/read-modifier-groups.use-case.spec.ts`, `src/modules/catalog/infrastructure/modifiers/modifier-group-offers.queries.spec.ts`, `src/modules/catalog/infrastructure/modifiers/modifier-group.queries.spec.ts`; over PostgreSQL `test/e2e/catalog-modifier-group-offers.e2e-spec.ts` and `test/e2e/catalog-modifier-group-offers-access.e2e-spec.ts`; the column, the replayed copy of `0080` and the index in `database/tests/contracts/catalog-offer-default-migration-contracts.ts`. Looking the group up before the gate, and a cursor binding without the group, the status or the unit, each fail these tests. See [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Correction       | Earlier text (K6, K8, risk R8) said `catalog.assert_variant_listed` and `catalog.resolve_barcode` were called by no runtime path and could be retired. Not so at database level: the order-line trigger of the Sales schema (`0110_sales.sql`) calls `assert_variant_listed`, and the database contracts and the runtime grants cover both. They stay as the database-level admission of that trigger until Sales is built; `CatalogSellableContract` is the in-process path                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Performance      | `GET /catalog/modifier-groups/{modifierGroupId}/offers` is classified frequent and not measured by `perf:http` (the scenarios seed no item offers yet); the evidence is the `EXPLAIN` above, local only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

### API v7 foundation as built (no migration, baseline revision 111)

The first slice of the Catalog API v7 plan: HTTP rules every later slice
reuses. No route is added, renamed or removed.

| Item                | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Required `If-Match` | A write that replaces a whole collection must name the version it replaces: `PUT /catalog/items/{itemId}/categories`, `PUT /catalog/items/{itemId}/images`, `PUT /catalog/items/{itemId}/variants/{variantId}/images`, `PUT /catalog/items/{itemId}/modifier-groups`, `PUT /catalog/items/{itemId}/variants/{variantId}/modifier-groups`, `PUT /catalog/items/{itemId}/bundle-groups` and `PUT /catalog/menus/{menuId}/structure`. Without `If-Match`, with a blank one or with `*` they answer `428 · precondition.required` (Problem Details whose detail says to read the resource and send its ETag) and nothing is written or recorded; a stale tag still answers `412 · foundation.precondition_failed`, judged by each use case after its locks, exactly as before. One foundation decorator, `@RequiresIfMatch()` (`src/foundation/http/conditional-requests/requires-if-match.decorator.ts`), holds the guard and its OpenAPI (the header `required: true`, the `412` and the `428`); no use case checks the presence. The guard runs after the session and tenant guards and before validation, so a missing session answers `401`, a rejected tenant `403`, and then a missing `If-Match` `428` before any `400`, `403` or `404` of the use case. The bulk `PUT /catalog/item-images`, the creates, the lifecycle routes, `PATCH` and `PUT /catalog/business-units/{businessUnitId}/assortment` keep an optional `If-Match` |
| Replays             | Sending the list a resource already has, with its current tag, still answers `200` with the same tag and records nothing. Two writes sent at once with the same tag now end in one `200` and one `412` instead of two `200`s: the second names a version that no longer exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Closed `meta`       | The shared `Envelope` no longer declares an open `meta` (`additionalProperties: true` with an optional `pageInfo`). Each route closes its own: a route that declares no meta documents `meta` as `{ type: object, additionalProperties: false, maxProperties: 0 }`, a route that declares keys lists exactly those (required, closed), and only a paged collection declares `pageInfo`. Bodies did not change: the interceptor still answers `meta: {}` by default, so no ETag moved. `meta.truncated` left `GET /catalog/categories` and `GET /catalog/modifier-groups`: each list is capped at its creation limit (500), so it could never be true. `test/e2e/envelope-meta-contract.e2e-spec.ts` validates real bodies of eight catalog routes (create, read, a replacement `PUT`, the item list, the tree, the group list, the workspace and the till read) against their documented schema, and shows that one undeclared meta key is refused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Writes per member   | Every catalog route that is not `GET`, `HEAD` or `OPTIONS` counts toward the writes one member may send a minute, all catalog writes together: `MEMBER_WRITE_RATE_LIMIT_PER_MINUTE`, 60 by default, keyed by the membership of the tenant context (the client address when there is none). The next write answers `429 · rate_limit.exceeded` with `Retry-After`; reads never count, and another member of the same organization keeps writing. A refused write counts too, so a member without the permission leaves at most that many denied audit records a minute (security findings S1 and S4). The counter is in memory per process: several API instances would each count apart (see `FOUNDATION_HTTP_AND_OBSERVABILITY.md` §11.B). Proof: `src/foundation/http/rate-limiting/member-write-throttle.guard.spec.ts` and `test/e2e/catalog-member-write-throttle.e2e-spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Body ceilings       | A JSON body is bounded at 100 KB everywhere (`413 · payload.too_large` beyond it), except where the documented maximum does not fit: `PUT /catalog/menus/{menuId}/structure` takes up to 2.25 MiB (its maximum, 50 sections and subsections, 1,000 entries and 50 selected variants each with the longest texts, is 2,143,242 bytes of compact JSON) and `PUT /catalog/items/{itemId}/bundle-groups` up to 256 KiB (20 groups of 50 choices: 214,358 bytes). Each ceiling is the smallest 256 KiB step that holds its maximum; `PUT /catalog/item-images` (57,111 bytes), `POST /catalog/items/{itemId}/variant-matrix` (12,446 bytes) and the assortment listings and delistings (7,813 bytes) fit the default and keep it. The ceilings live in `presentation/controllers/shared/catalog-body-limits.ts`, mounted by `configureHttpApplication` before the default parser. The raised parser reads a body only when the request carries well-formed `Authorization: Bearer` credentials; without them the 100 KB default applies, so an anonymous caller gets `413` past 100 KB and never makes the server read 2 MB before its `401`. Proof: `src/modules/catalog/presentation/controllers/shared/catalog-body-limits.spec.ts`, `src/foundation/http/body-limits/json-body-limits.spec.ts` and `test/e2e/catalog-body-limits.e2e-spec.ts`                                                                                           |
| Menu arrays         | `sections` and each `subsections` array take at most 50 elements at the schema (`MENU_MAX_SECTIONS`), so a longer list is refused at `sections` or `sections[i].subsections` with `too_big` before the tree is walked; the total of 50 sections and subsections is still judged over the whole tree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Response headers    | Every answer carries `X-Content-Type-Options: nosniff` and no `X-Powered-By`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Proof               | `src/foundation/http/conditional-requests/requires-if-match.decorator.spec.ts`, `test/e2e/catalog-required-preconditions.e2e-spec.ts` and `test/e2e/catalog-modifiers-concurrency.e2e-spec.ts`; dropping the guard from the decorator fails both new specs. See [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md), F1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### API v7 PR 2 as built: item and variant transitions (no migration, baseline revision 111)

Eight routes become two (`-6`): one transitions route per resource replaces
the per-verb lifecycle routes, and choosing the default variant folds into
the item edit.

| Before                                                                          | After                                                                                                                  |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `POST /catalog/items/{itemId}/{deactivation,reactivation,archival,restoration}` | `POST /catalog/items/{itemId}/transitions` with `transition` one of `deactivate`, `reactivate`, `archive` or `restore` |
| `POST .../variants/{variantId}/{deactivation,reactivation,archival}`            | `POST .../variants/{variantId}/transitions`, the same list, `restore` new                                              |
| `POST .../variants/{variantId}/default-selection` with `{ formerDefaultName? }` | `PATCH /catalog/items/{itemId}` with `{ defaultVariantId, formerDefaultName? }`                                        |

| Item               | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One table          | The closed list comes from the item lifecycle table (`ITEM_TRANSITION_VERB` and `itemLifecycleTable()` in `domain/items/item-lifecycle.ts`): the request schema, the OpenAPI description (where each transition starts and lands, and whether the plan gates it) and the refusal detail all read it. Variants use the same table                                                                                                                                              |
| `TransitionRoute`  | `src/foundation/openapi/api-transition-route.decorator.ts` documents any transitions route from its table: `POST`, `200`, the optional `If-Match` and its `412`, `403` (the entitlement code only when a transition is gated), `404` and `422`. `CatalogTransitionRoute` binds the catalog codes; categories, modifier groups, options and menus keep `LifecycleRoute` until PR 3 moves them                                                                                  |
| Answer             | Lean: `{ itemId, status }` or `{ variantId, status }`, with the strong ETag of the whole item in the `ETag` header, exactly the tag `GET /catalog/items/{itemId}` answers (the item is still read whole inside the command until the per-item version arrives)                                                                                                                                                                                                                |
| Refusal            | `422 · catalog.transition_invalid` names the current status and the transitions it allows: `The item is archived; from archived it allows restore. Read it again and send one of those transitions.` A value outside the list, the former noun (`deactivation`) or any other field answers `400 · foundation.validation_failed`                                                                                                                                               |
| Gating and audit   | `deactivate` and `archive` never ask about the plan, `reactivate` and `restore` do. One record per real change, named after the transition; a variant restore is recorded as `catalog.item.variant_updated` with the status before and after, because seeding `catalog.item.variant_restored` needs a migration. This reuse is temporary: PR 3 seeds the missing catalog action codes in migration `0102` and switches the variant restore to `catalog.item.variant_restored` |
| Variant restore    | `archived → inactive`, gated, never on the default (which can never be archived) and never on an archived item. Code, SKU and the place among the 500 variants were kept while archived, so nothing else is re-checked; barcodes stay inactive (archival released them) and offer defaults were already removed, so the restore deletes none. Restoring a live default answers `transition_invalid`, no longer `default_variant_required`                                     |
| Default in `PATCH` | `defaultVariantId` switches the default under the same rules and refusals as before (`variant_not_active`, `variant_name_required`, `not_found` for a variant of another item); `formerDefaultName` alone answers `400`. A profile edit and a default switch in one request write both in one locked transaction, one record each                                                                                                                                             |
| Statements         | An item transition issues 10 statements (8 for a repeat), a variant transition 12 (11 for a reactivation or restore, 8 for a repeat): `test/e2e/statement-budget.e2e-spec.ts`; 14, 12, 20 and 19 before the one-statement item read (API v7 PR 6)                                                                                                                                                                                                                             |
| OpenAPI            | 173 operations become 167 (Catalog 64 to 58). Breaking: the eight removed paths (four item verbs, three variant verbs, `default-selection`), plus a changed answer schema; the document moves to `8.0.0`, since staging already holds `7.0.0` from the foundation slice                                                                                                                                                                                                       |
| Proof              | The C6 and C7 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                      |

### API v7 PR 3 as built: category, modifier and menu transitions (migration `0102`, baseline revision 112)

Twelve routes become four (`-8`, Catalog 58 to 50): one transitions route per
resource replaces the per-verb lifecycle routes, and moving a category folds
into its edit.

| Before                                                                                 | After                                                                                                                                                                     |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /catalog/categories/{categoryId}/{deactivation,reactivation,archival}`           | `POST /catalog/categories/{categoryId}/transitions` with `deactivate`, `reactivate`, `archive` or `restore` (new)                                                         |
| `POST /catalog/categories/{categoryId}/re-parenting` with `{ parentCategoryId }`       | `PATCH /catalog/categories/{categoryId}` with an optional `parentCategoryId` (a category id, or `null` for the root) beside `code`, `name`, `description` and `sortOrder` |
| `POST /catalog/modifier-groups/{modifierGroupId}/{deactivation,reactivation,archival}` | `POST /catalog/modifier-groups/{modifierGroupId}/transitions`, the same four, `restore` new                                                                               |
| `POST .../options/{optionId}/{deactivation,reactivation,archival}`                     | `POST .../options/{optionId}/transitions`, the same four, `restore` new; it stays per option because taking one option off sale is an everyday till task                  |
| `POST /catalog/menus/{menuId}/{activation,archival}`                                   | `POST /catalog/menus/{menuId}/transitions` with `activate`, `unpublish` (new), `archive` or `restore` (new)                                                               |

```json
POST /api/v1/catalog/menus/0193…d0/transitions
{ "transition": "unpublish" }

200 OK
ETag: "<strong tag of the menu, as GET /catalog/menus/{menuId} answers it>"
{ "data": { "menuId": "0193…d0", "status": "draft" }, "meta": {} }
```

| Item                       | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tables                     | Categories, modifier groups and options take the item table (`itemLifecycleTable()`); menus have their own (`menuLifecycleTable()` in `domain/menus/menu-lifecycle.ts`): `activate` draft → active (gated), `unpublish` active → draft, `archive` draft or active → archived, `restore` archived → draft (gated). Both tables run on one shared rule set (`domain/shared/lifecycle.ts`: judge, table, allowed verbs)                                      |
| Requests                   | One closed list per table: `LifecycleTransitionRequestSchema` (items, variants, categories, groups, options) and `MenuTransitionRequestSchema`, both built by `transitionRequestSchema(verbs, example)` in `presentation/dtos/shared/transition-request.schema.ts`; any other value or field `400 · foundation.validation_failed`                                                                                                                         |
| Answers                    | Lean: `{ categoryId, status }`, `{ modifierGroupId, status }`, `{ optionId, status }` or `{ menuId, status }`, with the strong ETag of the category, the group (also for an option) or the menu: exactly the tag the read answers. `If-Match` optional, no `Idempotency-Key`; a repeat answers `200` and records nothing                                                                                                                                  |
| Refusal                    | `422 · catalog.transition_invalid` names the status and the transitions it allows, for example `The menu is archived; from archived it allows restore. Read it again and send one of those transitions.`                                                                                                                                                                                                                                                  |
| Gating                     | `deactivate`, `archive` and `unpublish` never ask about the plan; `reactivate`, `restore` and `activate` do                                                                                                                                                                                                                                                                                                                                               |
| Category restore           | `archived → inactive` under the same parent; the code stayed unique and the category kept counting toward the 500, so only the place is judged again: `422 · catalog.category_archived` while the parent is archived (restore the parent first), `422 · catalog.category_depth_exceeded` if too deep                                                                                                                                                      |
| Category move in `PATCH`   | The place is judged (cycle, depth, archived parent, unknown parent `404`) before anything is written; the profile edit and the move are written in one transaction under the catalog version and category locks, each recorded once (`catalog.category.updated`, `catalog.category.moved`). A `PATCH` with only `parentCategoryId` is admitted under `catalog.category.moved`                                                                             |
| Group and option restore   | `archived → inactive`; nothing else to check (codes stayed unique, the 500 groups and the 50 options of a group count archived ones). An option of an archived group answers `422 · catalog.modifier_group_archived` whatever the transition. Whether an item can still be sold is judged by the till reads, as for any status change                                                                                                                     |
| Offer defaults             | Deactivating or archiving a live group, option or variant removes it from every offer default (one `DELETE`, the count recorded); a restore never runs that removal, one shared rule (`retireOfferDefaults` with the status before and after)                                                                                                                                                                                                             |
| Menu restore and unpublish | `restore` brings the archived menu back as draft with its structure; `unpublish` takes an active menu back to draft, where it may be emptied; `activate` keeps refusing `catalog.menu_empty` and `catalog.menu_nothing_available`; an archived menu stays read-only for `PATCH` and `PUT .../structure` (`catalog.menu_archived`)                                                                                                                         |
| Audit                      | Revision 112 (migration `0102`, expand-only) seeds `catalog.category.restored`, `catalog.modifier_group.restored`, `catalog.modifier_group.option_restored`, `catalog.menu.unpublished`, `catalog.menu.restored` and `catalog.item.variant_restored`, which a variant restore now records instead of `catalog.item.variant_updated`. `src/modules/catalog/application/catalog-audit-vocabulary.spec.ts` proves every action the catalog records is seeded |
| Statements                 | Category 12 (13 for a restore under a parent, 10 for a repeat); group and option 14 (13 for a reactivation or restore, 11 for a repeat); menu 10 for each transition (8 for a repeat): `test/e2e/catalog-lifecycle-statement-budget.e2e-spec.ts`                                                                                                                                                                                                          |
| OpenAPI                    | Breaking: the twelve removed paths; the document moves to `9.0.0`. `LifecycleRoute` is gone; the four routes use `CatalogTransitionRoute`                                                                                                                                                                                                                                                                                                                 |
| Proof                      | The C9, C12 and M1 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                             |

### API v7 PR 4 as built: one barcode set, one images route and a conditional bulk (migration `0103`, baseline revision 113)

Seven routes become three (`-4`, Catalog 50 to 46): the barcodes of a
variant are replaced as one set, the item list and the variant lists of an
item are replaced by one images request under one `If-Match`, and each entry
of the bulk images route may name the item version it replaces.

| Before                                                                                                                                                              | After                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /catalog/items/{itemId}/variants/{variantId}/barcodes`, `PATCH .../barcodes/{barcodeId}`, `POST .../barcodes/{barcodeId}/deactivation` and `.../reactivation` | `PUT /catalog/items/{itemId}/variants/{variantId}/barcodes` with `{ barcodes: [{ barcodeId?, barcode, symbology?, isPrimary?, suspended? }] }` |
| `PUT /catalog/items/{itemId}/images` with `{ images }` and `PUT /catalog/items/{itemId}/variants/{variantId}/images` with `{ images }`                              | `PUT /catalog/items/{itemId}/images` with `{ images, variants? }`, `variants` being `[{ variantId, images }]`                                  |
| `PUT /catalog/item-images` with `{ items: [{ itemId, images }] }`                                                                                                   | the same, each entry with an optional `ifMatch`                                                                                                |

```json
PUT /api/v1/catalog/items/0193…a1/variants/0193…a2/barcodes
If-Match: "<strong tag of the item, as GET /catalog/items/{itemId} answers it>"
{
  "barcodes": [
    { "barcodeId": "0193…b1", "barcode": "7750182002363", "symbology": "ean13", "isPrimary": true },
    { "barcode": "CAM-OX-M-AZUL", "symbology": "code128", "suspended": true }
  ]
}

200 OK
ETag: "<new strong tag of the item>"
{
  "data": {
    "variantId": "0193…a2",
    "barcodes": [
      { "barcodeId": "0193…b1", "barcode": "7750182002363", "symbology": "ean13", "isPrimary": true, "suspended": false, "status": "active" },
      { "barcodeId": "0193…b7", "barcode": "CAM-OX-M-AZUL", "symbology": "code128", "isPrimary": false, "suspended": true, "status": "inactive" }
    ]
  },
  "meta": {}
}
```

| Barcodes             | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ids                  | A barcode keeps its id when sent back; one sent without an id takes back the id of a barcode the variant has or had with the same GTIN (a live one before an archived one), so a retried save never duplicates; otherwise a new id. A value never changes under its id (`422 · catalog.barcode_value_fixed`); an id the variant never had answers `404`                                                                                                                                                        |
| Left out             | Archived (status `archived`, migration `0103`): never deleted, never scans, its value is free and it no longer counts toward the 20; the item read and the answer leave it out; sending its value or id brings it back                                                                                                                                                                                                                                                                                         |
| `suspended`          | `true` keeps the barcode in the set as `inactive` (it does not scan and its value is free); a suspended barcode cannot be primary (`422 · catalog.barcode_not_active`)                                                                                                                                                                                                                                                                                                                                         |
| Precondition and tag | `If-Match` required on the item tag (`428`, `412`); no dedicated `GET`: `GET /catalog/items/{itemId}` already returns every variant with its barcodes and the same tag, which is also the tag the bundle groups, categories and images writes use, so one read serves every write of the item. A barcode tag of its own would let two editors of one item save barcodes and images at once without a `412`, but would cost a second read for every editor and a route; not worth it at 20 barcodes per variant |
| Locks                | Catalog version row, item row, then the barcode rows of the variant (read once); values brought to life are checked against other variants, and the unique active value index stays the final arbiter (`409`)                                                                                                                                                                                                                                                                                                  |
| Writes               | Rows that stop being active first, then rows that become active, then the one primary, then the new rows: four statements at most whatever the number of barcodes                                                                                                                                                                                                                                                                                                                                              |
| Gating               | A set that only suspends, archives or drops the primary never asks the plan; adding, bringing back, making primary or changing a symbology does                                                                                                                                                                                                                                                                                                                                                                |
| Audit                | One `catalog.item.barcodes_set` per change with `catalog.item.variant` and `catalog.item.variant.barcodes`, the live set before and after as a JSON list of `[id, value, symbology, primary, status]` sorted by id; the change check compares the same key, so an unchanged set records nothing                                                                                                                                                                                                                |
| Refusals             | Each points at its entry: `barcodes[i].barcode` (`catalog.barcode_invalid`, `catalog.barcode_value_fixed`, `catalog.barcode_taken`), `barcodes[i].barcodeId` (`catalog.not_found`), `barcodes[i].isPrimary` (`catalog.barcode_not_active`); a repeated GTIN or id, two primaries or 21 barcodes answer `400` at the schema. `catalog.variant_barcodes_full` is gone                                                                                                                                            |
| Statements           | 15 to add, suspend and archive at once, the same for 1 and 10 barcodes (`test/e2e/statement-budget.e2e-spec.ts`; 23 before the one-statement item read)                                                                                                                                                                                                                                                                                                                                                        |

Images:

```json
PUT /api/v1/catalog/items/0193…a1/images
If-Match: "<strong tag of the item, as GET /catalog/items/{itemId} answers it>"
{
  "images": [{ "assetId": "0193…f1" }],
  "variants": [
    { "variantId": "0193…a2", "images": [{ "assetId": "0193…f2" }, { "assetId": "0193…f3" }] },
    { "variantId": "0193…a3", "images": [] }
  ]
}

200 OK
ETag: "<new strong tag of the item>"
{ "data": { "itemId": "0193…a1", "images": [ … ], "variants": [ … ] }, "meta": {} }
```

| Item               | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lists              | `images` is required and is the whole item list; `variants` is optional and holds at most 100 lists, each variant once. Every list takes at most 10 images, each once, the first is its primary and an empty list removes them                                                                                                                                                                                                                                                                                             |
| A variant not sent | Keeps its images. Chosen over "not sent means emptied" because most clients only manage the item list: with the replace-everything rule, a client unaware of variant images would wipe them on every save. The tag still protects against a lost update, since `If-Match` names the version of the whole item, variant lists included                                                                                                                                                                                      |
| Precondition       | `If-Match` required (`428 · precondition.required`), judged on the item tag after the catalog version and item locks (`412 · foundation.precondition_failed` when stale); two concurrent saves with the same tag end in one `200` and one `412`                                                                                                                                                                                                                                                                            |
| Refusals           | A variant of another item or unknown `404 · catalog.not_found`; an archived variant `422 · catalog.variant_archived`, an archived item `422 · catalog.item_archived`; an asset that cannot be attached `422 · catalog.image_not_attachable` naming it; a repeated variant `400` at `variants[i].variantId`                                                                                                                                                                                                                 |
| Writes             | One transaction: catalog version row, item row, then the item list (three statements) and every changed variant list together (three batched statements, `unnest` of variant, asset and position), variants in id order. New assets are checked once for all lists. Gated by the plan unless every changed list only removes images                                                                                                                                                                                        |
| Audit              | Unchanged codes: one `catalog.item.images_set` when the item list changed and one `catalog.item.variant_images_set` per changed variant list; sending the lists the item has answers `200` with the same tag and records nothing                                                                                                                                                                                                                                                                                           |
| Bulk `ifMatch`     | Optional per entry, one quoted strong ETag (a wildcard or a weak tag is a `400` at `items[i].ifMatch`). After the items are locked, an unknown item is refused first (`404`), then every stale tag (`412 · foundation.precondition_failed`, `meta.errors` naming `items.<itemId>` with `precondition_failed`, even when its list would not change), then an archived item (`422`); all or nothing as before. An entry without it stays unconditional, as an import needs; the tags cost one extra read of those items only |
| Body               | The largest images request (10 item images and 100 variant lists of 10) is 57,935 bytes and the largest bulk request with the longest `ifMatch` on every entry 71,611 bytes: both stay on the 100 KB default                                                                                                                                                                                                                                                                                                               |
| Statements         | Item list only: 17 (25 before the one-statement item read of API v7 PR 6); variant lists: 15 plus one audit per changed list, whatever the number of variants (`test/e2e/statement-budget.e2e-spec.ts`); the bulk route is unchanged without `ifMatch`                                                                                                                                                                                                                                                                     |
| OpenAPI            | Breaking: the removed variant images path and the four per-barcode operations; the document moves to `10.0.0`                                                                                                                                                                                                                                                                                                                                                                                                              |
| Proof              | The C11 and C26 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### API v7 PR 5 as built: one modifier group set and one offers route (no migration, baseline revision 113)

Five routes become two (`-3`, Catalog 46 to 43): a modifier group and its
whole option set are replaced in one `PUT`, and the item offers and the
overrides of its variants travel in one offers request under one `If-Match`.
No audit action is added: the set records `catalog.modifier_group.updated`
and the offers keep `catalog.item.modifier_groups_set`.

| Before                                                                  | After                                                                              |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `PATCH /catalog/modifier-groups/{modifierGroupId}`                      | `PUT /catalog/modifier-groups/{modifierGroupId}`                                   |
| `POST /catalog/modifier-groups/{modifierGroupId}/options`               | the same `PUT` (an option without `optionId` is new)                               |
| `PATCH /catalog/modifier-groups/{modifierGroupId}/options/{optionId}`   | the same `PUT` (an option sent back with its id)                                   |
| `PUT /catalog/items/{itemId}/modifier-groups` with `{ modifierGroups }` | `PUT /catalog/items/{itemId}/modifier-groups` with `{ offers, variantOverrides? }` |
| `PUT /catalog/items/{itemId}/variants/{variantId}/modifier-groups`      | `variantOverrides` of the same `PUT`                                               |

`POST /catalog/modifier-groups`, both `GET`s of the groups, `GET .../offers`
and both transitions routes stay: taking one option off sale for the day
must not require sending the whole set.

Modifier group set:

```json
PUT /api/v1/catalog/modifier-groups/0193…d1
If-Match: "<strong tag of the group, as GET /catalog/modifier-groups/{modifierGroupId} answers it>"
{
  "code": "termino-de-la-carne",
  "name": "Término de la carne",
  "description": "Cómo prefiere la carne.",
  "options": [
    { "optionId": "0193…d2", "code": "tres-cuartos", "name": "Tres cuartos" },
    { "name": "Tocino", "kind": "catalog_variant", "variantId": "0193…a9", "maxQuantity": 2 },
    { "optionId": "0193…d3", "name": "Bien cocida", "suspended": true }
  ]
}

200 OK
ETag: "<new strong tag of the group>"
{
  "data": {
    "modifierGroupId": "0193…d1", "code": "termino-de-la-carne", "name": "Término de la carne",
    "description": "Cómo prefiere la carne.", "status": "active",
    "options": [
      { "optionId": "0193…d2", "code": "tres-cuartos", "name": "Tres cuartos", "description": null, "kind": "instruction", "variantId": null, "maxQuantity": 1, "sortOrder": 0, "status": "active" },
      { "optionId": "0193…e1", "code": "tocino", "name": "Tocino", "description": null, "kind": "catalog_variant", "variantId": "0193…a9", "maxQuantity": 2, "sortOrder": 1, "status": "active" },
      { "optionId": "0193…d3", "code": "bien-cocida", "name": "Bien cocida", "description": null, "kind": "instruction", "variantId": null, "maxQuantity": 1, "sortOrder": 2, "status": "inactive" },
      { "optionId": "0193…d4", "code": "jugoso", "name": "Jugoso", "description": null, "kind": "instruction", "variantId": null, "maxQuantity": 1, "sortOrder": 3, "status": "archived" }
    ]
  },
  "meta": {}
}
```

A refusal points at the option:

```json
409 Conflict
{ "code": "catalog.code_taken", "status": 409, "meta": { "errors": [
  { "location": "body", "field": "options[1].code", "code": "catalog.code_taken",
    "message": "Another option of this group, or one it had before, holds this code ignoring case; choose another code, or send the id of the option that holds it." }
] } }
```

| Set                  | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Body                 | `code` and `name` required, `description` null or absent leaves none; `options` required, at most 50, the order sent is the till order; an option takes `optionId?`, `code?`, `name`, `description?`, `kind` (default `instruction`), `variantId` (only for `catalog_variant`), `maxQuantity` (default 1) and `suspended` (default false). A repeated `optionId` or code (ignoring case) is a `400` at the repetition                                                            |
| Ids                  | An option keeps its id when sent back; one sent without an id but with the code of an option the group has or had, ignoring case, takes that id back (so a retried save never duplicates); otherwise a new id and, without a code, one derived from its name that no option of the group, archived ones included, holds                                                                                                                                                          |
| Left out             | Archived, never deleted: past sales, offers and Pricing rows that name it stay true; it keeps its code and still counts among the 50 (`422 · catalog.modifier_group_full` when stored plus new options pass 50); sending its id or code again brings it back with the same id, `active` or `inactive` as `suspended` says                                                                                                                                                        |
| `suspended`          | `true` makes the option `inactive`, the meaning of `deactivate` on the transitions route                                                                                                                                                                                                                                                                                                                                                                                         |
| Target               | The kind and the variant of a kept option never change (`422 · catalog.modifier_option_target_fixed` at `options[i].kind` or `.variantId`); the variant of a new option is judged once, share-locked in id order: unknown or of another organization `404 · catalog.not_found`, not active `422 · catalog.variant_not_active`, both at `options[i].variantId`                                                                                                                    |
| Codes                | A code held by another option of the group, archived ones included, is `409 · catalog.code_taken` at `options[i].code`; a group code taken in the catalog `409` from the unique index. Because a request never reuses a stored code of another option, the option writes cannot collide mid-statement                                                                                                                                                                            |
| Precondition and tag | `If-Match` required on the group tag (`428`, `412`); the answer is the whole group as `GET` reads it with its new tag; two sets sent at the same version end in one `200` and one `412`                                                                                                                                                                                                                                                                                          |
| Locks                | Catalog version row, group row `FOR UPDATE`, then the variants of new options `FOR SHARE` in id order                                                                                                                                                                                                                                                                                                                                                                            |
| Writes               | The profile when it changed, one batched `UPDATE` of the changed options (`unnest`, scoped to the group), one batched `INSERT` of the new ones, then one `DELETE` of the offer defaults of the options that stop being sellable (active to inactive or archived, inactive to archived), the count recorded as `catalog.modifier_group.offer_defaults_removed`. Whether a required group can still reach its minimum is judged by the till reads, as for any option status change |
| Gating               | A set that only suspends or archives options, keeping the order of the rest and every other value, never asks the plan; a rename, a new option, an edit, a reorder or bringing an option back does                                                                                                                                                                                                                                                                               |
| Audit                | One `catalog.modifier_group.updated` per change: the changed `code`, `name` and `description` and `catalog.modifier_group.option_set`, the live options in their order as `[id, code, name, description, kind, variant, maxQuantity, status]` before and after; the change check compares that same key, so sending the group as it is answers `200` and records nothing                                                                                                         |
| Archived group       | `422 · catalog.modifier_group_archived` whatever the set                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Body ceiling         | 512 KiB (`2 × 256 KiB`), the smallest step that holds the largest documented body (50 options with 2,000-character descriptions)                                                                                                                                                                                                                                                                                                                                                 |
| Statements           | 18 to rename, add, suspend, edit and archive at once, the same for 1 and 10 options (`test/e2e/statement-budget.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                    |

Offers:

```json
PUT /api/v1/catalog/items/0193…a1/modifier-groups
If-Match: "<strong tag of the item, as GET /catalog/items/{itemId} answers it>"
{
  "offers": [
    { "modifierGroupId": "0193…d1", "minSelections": 1, "maxSelections": 1, "defaultOptionIds": ["0193…d2"] },
    { "modifierGroupId": "0193…c1", "minSelections": 0, "maxSelections": 3, "suspended": true }
  ],
  "variantOverrides": [
    { "variantId": "0193…a2", "offers": [{ "modifierGroupId": "0193…c1", "minSelections": 0, "maxSelections": 6 }] },
    { "variantId": "0193…a3", "offers": [{ "modifierGroupId": "0193…d1", "minSelections": 0, "maxSelections": 1, "optedOut": true }] },
    { "variantId": "0193…a4", "offers": [] }
  ]
}

200 OK
ETag: "<new strong tag of the item>"
{ "data": { "itemId": "0193…a1", "modifierGroups": [ … ], "variants": [ { "variantId": "0193…a2", "modifierGroupOverrides": [ … ] }, … ] }, "meta": {} }
```

| Offers               | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lists                | `offers` is required and is the whole item list (at most 20); `variantOverrides` is optional and holds at most 10 variant lists per request, each variant once, each list at most 20 groups. `suspended` belongs to an item offer and `optedOut` to a variant override (`400` otherwise)                                                                                                                                                                                                          |
| A variant not sent   | Keeps its overrides, and so does every variant when `variantOverrides` is absent: a client that manages only the item list never wipes the overrides; a variant sent with an empty list clears them and follows the item again. Chosen as for the images route                                                                                                                                                                                                                                    |
| Rules                | Unchanged: offer ids kept for ever (K9b), retire instead of delete, `suspended`, `optedOut`, min, max and defaults, the effective-offer rules, the activation judgement of a resumed or opted-in group, the per-variant rules of K9g                                                                                                                                                                                                                                                              |
| Refusals             | Each points at its field: `offers[i].modifierGroupId` (`404 · catalog.not_found`, `422 · catalog.modifier_group_not_active`), `.minSelections` (`422 · catalog.selection_rule_invalid`), `.defaultOptionIds` (`422 · catalog.default_options_invalid`), under `variantOverrides[j].offers[i]` for a variant list; `variantOverrides[j].variantId` for a variant of another item or unknown (`404`) or archived (`422 · catalog.variant_archived`); an archived item `422 · catalog.item_archived` |
| Precondition and tag | `If-Match` required on the item tag, which covers every variant list (`428`, `412`); the answer is the whole item with its new tag                                                                                                                                                                                                                                                                                                                                                                |
| Locks                | Catalog version row, item row `FOR UPDATE`, then the groups of every changed list `FOR SHARE` once, in id order; the variant writes are serialised by the item lock, as every variant write of the catalog                                                                                                                                                                                                                                                                                        |
| Writes               | Only the lists that changed, each judged first and written after: all changed lists or none                                                                                                                                                                                                                                                                                                                                                                                                       |
| Gating               | Per list as before (only removing, suspending or opting out never needs the plan); the plan is asked once when any changed list needs it                                                                                                                                                                                                                                                                                                                                                          |
| Audit                | One `catalog.item.modifier_groups_set` per changed list, as before                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Body ceiling         | The same 512 KiB parser as the group set: the largest documented body (20 offers with 50 defaults each, plus 10 such variant lists) fits it; one parser only, mounted behind the bearer credential like the others                                                                                                                                                                                                                                                                                |
| Statements           | 21 for the item list and one variant list (29 before the one-statement item read of API v7 PR 6), 5 more per further changed variant list (`test/e2e/statement-budget.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                               |
| OpenAPI              | Breaking: the removed `PATCH` of the group, the option add and edit paths, the variant offers path and the `modifierGroups` body property; the document moves to `11.0.0`                                                                                                                                                                                                                                                                                                                         |
| Proof                | The C12 and C13 rows of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                        |

### API v7 PR 6: the item read as built (no migration, baseline revision 113)

| Item read                   | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| One statement               | `READ_ITEM`, `LOCK_ITEM` (`FOR UPDATE OF i`) and `READ_ITEMS` (`ANY($1::uuid[])`) in `infrastructure/items/item-read.queries.ts` answer one row per item that nests, as `json_agg` in keyed scalar subqueries, the variants (with their live barcodes, their overrides and their images), the categories, the item offers with the options and defaults of each group, and the item images. The old read sent five statements (items joined with variants, categories, offers, options, barcodes) and joined them in Node, filtering every row set per item and handing every barcode row to every item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Images                      | The item images are aggregated once per item and the images of a variant once per variant, each through a keyed index of `item_assets` (the planner picks `item_assets_item_asset_uq` and `item_assets_variant_asset_uq`); before, the item images were aggregated again on every variant row                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Representation              | Byte for byte the same: `item-read.golden.integration-spec.ts` compares a rich item key by key with `test/support/rich-item.golden.json`, written from the five-statement read before the change, and read, lock and read-many answer the same entity tag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Plan stability              | Every child is reached through its parent by key, no `EXISTS`, no `OFFSET`; a category, a modifier group and a default option are looked up by primary key in a `LATERAL ... LIMIT 1` per link, so the planner cannot reorder the join and scan the organization's categories or groups for every item (the first version joined them, and with statistics taken while those tables were nearly empty it read the 500 categories of the organization for every link). The spec imports the same catalog into a neighbour before `ANALYZE` and into the measured organization after it: 2,001 items (two variants, two offers on 2,000 groups, a barcode per variant, images and 500 categories), a 40-variant item and an item with the 500 variants allowed, each overriding the same 20 groups. Measured: the 40-variant item 343 rows and 705 buffers, 100 items 2,300 rows and 6,212 buffers, the 500-variant item (locked) 20,581 rows and 24,713 buffers; no sequential scan, no looped scan wider than 50 rows, and no single lookup reads more rows than the item owns. Bounds: 1,000 rows and 2,000 buffers, 4,000 and 10,000, 40,000 and 50,000 (`item-read.plan.integration-spec.ts`) |
| Shared groups               | The facts and the options of every group the item offers are built once per item (`SELECT DISTINCT` of the offered groups, one `jsonb` object keyed by group id) and each offer takes its group from it, instead of rebuilding the options once per offer: the 500-variant item with 20 overrides each went from 50,501 rows, 88,755 buffers and about 110 ms to 20,581 rows, 24,713 buffers and about 57 ms of execution (local, superuser, no RLS)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Writes                      | Unchanged bodies; every item read is now one statement plus one `describe` when there are images. Writes that read the item twice, under the lock and again for the answer, save eight statements: a variant transition, `PUT .../categories`, the images, the barcode set and the offers. Writes that read it once save four: an item transition (it answers `{ itemId, status }` with the tag of the locked item after the step, computed in Node, so its tag costs no statement beyond the lock), the create and the `PATCH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Statements                  | `GET` item 7 (11 before), the same for `304`; create 14 (18); `PATCH` 10 (14); `PUT .../categories` 13 (21); item images 17 (25); barcode set 15 (23); offers 21 (29); item transition 10, 8 for a repeat (14, 12); variant transition 12, 11 for a reactivation or restore, 8 for a repeat (20, 19, 12) (`test/e2e/statement-budget.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Per-item version: not built | Decided against with the numbers above. A `304` already costs the same 7 statements as a `200`; a version column would replace the one read with a one-row probe (about 1 ms of execution and 561 to 705 buffers for 40 variants, 4 buffers for the probe) but not remove a statement. Its costs: the representation holds facts other tables and modules own, so the version would either fan out (an edit of a group offered by 1,500 items updates 1,500 item rows under the catalog version lock) or the tag would have to combine the item version with the groups it offers; and the delivery status and URLs of the images belong to Assets, whose changes (an image finishing processing, an archive) never touch a catalog row, so a version-only tag would answer a stale `304`. It would also need migration `0104`, canonical files, contract tests and an upgrade proof. The content hash stays the tag                                                                                                                                                                                                                                                                             |
| OpenAPI                     | Unchanged by the read. The same PR removes `categoriesTruncated` from `GET /catalog/workspace` (a catalog holds at most 500 categories, the workspace answers up to 500, so it could never be true), bounds `quantityPerSelection` of a bundle choice to 21 characters and corrects three descriptions; the document moves to `12.0.0`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Proof                       | The rows "The item read is one statement", "The item representation is byte for byte the one before the one-statement read" and "The item read stays keyed under stale statistics" of [`CATALOG_CASE_MATRIX.md`](CATALOG_CASE_MATRIX.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### API v7 PR 7 as built: one listing-changes route, a richer item list and a category tree version (migration `0104`, baseline revision 114)

Two routes become one (`-1`, Catalog 43 to 42). The item list gains what an
admin grid needs without one detail call per row, and the category tree gets
its own version, so item writes stop invalidating it.

| Before                                                                                   | After                                                                                      |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `POST /catalog/business-units/{businessUnitId}/assortment/listings` with `{ itemIds }`   | `POST /catalog/business-units/{businessUnitId}/assortment/listing-changes` with `{ list }` |
| `POST /catalog/business-units/{businessUnitId}/assortment/delistings` with `{ itemIds }` | the same route with `{ delist }`, or both lists in one change                              |
| `GET /catalog/items?status=active` (one status)                                          | `status=active,inactive` (one or several, comma separated)                                 |
| `GET /catalog/items?categoryId=` (that category only)                                    | `categoryId=&includeDescendants=true` adds the two levels below it                         |
| no image filter                                                                          | `hasImage=true` or `hasImage=false`                                                        |
| a row without image                                                                      | every row carries `primaryImage`: `{ assetId, thumbnailUrl }` or `null`                    |
| `GET /catalog/categories` tagged with the organization-wide version                      | tagged with `catalog_versions.categories_version`                                          |

Listing changes:

```json
POST /api/v1/catalog/business-units/0193…09/assortment/listing-changes
If-Match: "<optional: the tag of GET .../assortment>"
{
  "list": ["0193…a1", "0193…a4"],
  "delist": ["0193…a3"]
}
```

| Listing changes      | As built                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Body                 | `list` and `delist`, both optional, up to 200 ids each, each once, at least one id in all; an id in both answers `400` with `meta.errors[].field` such as `delist[0]`; an unknown field such as `itemIds` answers `400`                                                                                                                                                                            |
| Rules kept           | Mode `all`: a listing lifts an exclusion, a delisting writes one; mode `selected`: a listing writes an inclusion, a delisting withdraws it; mode `none`: `422 catalog.assortment_disabled`. An archived item is refused only in `list` (`422 catalog.item_archived`); an unknown item or one of another organization answers `404 catalog.not_found` for the whole change; nothing is written then |
| Plan and permission  | `catalog.assortment.manage` anchored at the unit, as before. The plan (capability `catalog.items`) gates the change only when `list` names an item; a change that only delists never needs it, so withdrawing from sale always works                                                                                                                                                               |
| Audit                | One `catalog.assortment.items_listed` record naming the items that started selling and one `catalog.assortment.items_delisted` record naming the ones that stopped, each only when its direction changed something; a change that changes nothing records nothing. A refusal is recorded under `items_listed` when `list` names an item and under `items_delisted` otherwise                       |
| Statements and locks | One permission step, the catalog version row locked first, one read of the stored mode, one share of every named item in id order, then per changed direction one insert and one update at most; the answer is the assortment as `GET .../assortment` reads it                                                                                                                                     |
| If-Match             | Optional, as the owner decided: the assortment is a mode and a membership set, not a whole-collection replace                                                                                                                                                                                                                                                                                      |

| Item list                     | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Several statuses              | Each status is its own ordered branch (`ORDER BY name_search_key, id LIMIT 51` on `catalog_items_name_search_idx`) merged with `UNION ALL` and limited again, so every branch stops at the page; a single status keeps the one scan it always had. A text prefix is judged per branch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Category tree                 | `includeDescendants=true` keeps the items classified in the category or in the categories one or two levels below it (`categories_parent_idx`, no recursion: a tree is at most three deep), whatever their status. Both category filters now read the classified item ids once per statement (`id = ANY (ARRAY(...))`, an InitPlan) instead of once per scanned item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Image filter                  | `hasImage` is one keyed probe per scanned item on `item_assets_one_item_primary_uq` (the item primary image; an image of a variant does not count)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `primaryImage`                | Read in the same statement through the same unique index; the page then asks Assets once for the thumbnail of every distinct primary image (`AssetDeliveryContract.describe`, rendition `thumbnail`). `thumbnailUrl` is `null` while the image is processing, when it failed or when the media host is not configured. The key is always present: `null` for an item without a primary image, as `primaryCategory` already does, so a row without image differs from before only by `"primaryImage": null`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Workspace                     | Its first page is read by the same statement and enriched by the same call, so it keeps matching the first page of the list key by key (`catalog-item-list-filters.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Cursor                        | Bound to the route, the organization and every filter: the statuses (in lifecycle order, so `inactive,active` and `active,inactive` share cursors), `q`, `categoryId`, `includeDescendants` when true, `hasImage` when sent, `businessUnitId` and `listed`. A cursor sent with another filter set answers `400 collection.cursor_incompatible`; the workspace `endCursor` is still accepted by `GET /catalog/items` with no other filter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Plan stability                | Right after importing 2,001 items (two variants each, a third inactive, a primary image on every other item, every fourth item in a three-level tree, the rest in 100 categories) before the statistics know it, a first page of 50 reads: three statuses 332 rows and about 1,060 buffers; the category tree 1,142 rows and about 1,130 buffers; one exact category 833 rows and about 1,050 buffers; `hasImage=true` 458 rows and about 1,300 buffers, `false` 410 and about 1,240; two statuses with the tree and `hasImage=true` 2,080 rows and about 1,630 buffers; no sequential scan and no wide looped scan; the spec bounds each at 2,500 rows and 2,500 buffers (`item-list.plan.integration-spec.ts`). Before the change an exact category read 88,664 rows (the classified items were scanned again for every item); the tree filter written the same way read 88,880                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Plan stability, CI correction | The CI of the promotion found the primary category of each row read by a looped `Seq Scan on categories` (102,051 loops) when the categories table was nearly empty at the last `ANALYZE`, and a text prefix whose SKU branch ran once per scanned item (4,002 rows x 718 loops locally). The row summary now reads the primary category id of each row through `item_categories_one_primary_uq` (`LIMIT 1`, never flattened) and every category name of the page once (`category_names`, a `jsonb_object_agg` over `id = ANY (ARRAY(...))`), the prefix and the second tree level are evaluated once per statement (`id = ANY (ARRAY(...))`), and the plan spec asserts that no scan of `categories` repeats per row. A second correction after the full integration run (where `together` read 4,667 rows): the items of a category and the items matching a text prefix are now one candidate set read once per statement (`candidates`, the two intersected when both are sent) instead of once per status branch, each status branch keeps its ordered scan and tests membership with a filter that is never an index condition (`coalesce(id = ANY (...), false)`), and the SKU branch of the prefix states `sku_search_key IS NOT NULL` so its partial index applies. The ordered scan stays (owner decision): a bad plan of an admin list costs a few thousand rows, not a catastrophe. The plan spec therefore checks invariants that hold in the good and in the bad plan: no sequential scan of `items`, `item_variants`, `item_assets` or `item_categories`, no looped wide scan, no scan of `categories` repeated per row, three statuses at most three single-status pages, and ceilings of 4 rows and 4 buffers per imported item for the filters and 8 for a text prefix. Good plan: `together` about 2,480 rows and 2,230 buffers, a one-letter prefix 12,710 rows; bad plan forced with near-empty statistics: `together` 4,260 rows and 3,350 buffers, an image filter 5,330 buffers; the worst forced with `enable_nestloop = off`, 6,210 rows. Its fixture now holds 497 categories besides the tree, near the 500 a catalog may hold; with it every filter reads at most about 2,820 rows and 1,550 buffers (bound 3,000 rows and 2,500 buffers) and a prefix about two pages' worth per status |
| Prefix across statuses        | A prefix that matches few names (`bulk 19`) still reads every item of a status under stale statistics (3,666 rows for one status, a cost the prefix filter already had); two statuses read 5,334, never more than two single-status pages, which the spec asserts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Statements                    | 7 for a page whatever the filters (several statuses, the tree, the image filter, as before for one status or `categoryId`), 8 with `listed` (the unit status, as before), and one more when the page holds primary images (the Assets call): 8, and the workspace 12 without images and 13 with them (`catalog-reads-statement-budget.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

Item list request and row:

```json
GET /api/v1/catalog/items?status=active,inactive&categoryId=0193…c1&includeDescendants=true&hasImage=true&limit=50
{
  "data": [
    {
      "itemId": "0193…a1",
      "code": "hamburguesa-clasica",
      "name": "Hamburguesa clásica",
      "status": "active",
      "defaultVariant": { "variantId": "0193…a2", "sku": "HB-001", "salesUnitCode": "unit" },
      "variantCount": 1,
      "primaryCategory": { "categoryId": "0193…c1", "name": "Platos de fondo" },
      "primaryImage": {
        "assetId": "0193…e1",
        "thumbnailUrl": "https://media.ninaku.io/a/k3j7m2q9x4v8b6n5c1d0f7g2h4/p1/thumbnail.webp"
      }
    }
  ],
  "meta": { "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "…", "endCursor": "…" } }
}
```

| Category tree version   | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Column                  | `catalog.catalog_versions.categories_version bigint NOT NULL DEFAULT 1`, `catalog_versions_categories_version_chk` (> 0)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Backfill and tag format | Every existing row takes its current `version`. The tag also changes form, from `organization:version:categories-<status or all>` to `organization:category-tree:<tree version>:<status or all>` (`category-tree-entity-tag.ts`), so a tag issued from the organization-wide version, before the upgrade or by an old instance during a rolling deploy, can never equal a new one even when the numbers coincide: such a client gets one `200` and the new tag                                                                                                             |
| Triggers                | The three statement-level triggers of `catalog.categories` now run `catalog.bump_category_tree_version()`: one `UPDATE` of the version row that moves `version` as before and `categories_version` when the statement inserts or deletes categories or changes the parent, code, name, description, sort order or status of one (the update trigger compares `OLD TABLE` and `NEW TABLE`); an update that leaves those columns as they were moves only `version`. No other table moves it, so item, variant, classification, image and assortment writes keep the tree tag |
| Guard                   | `catalog.guard_catalog_version_step()` still demands `version + 1` and lets `categories_version` stay or move by one; the runtime receives `UPDATE (categories_version)`, which the trigger needs, and cannot forge it (contract `catalog-category-tree-version-contracts.ts`)                                                                                                                                                                                                                                                                                             |
| Effective visibility    | Derived from ancestors, which are categories, so every change that can alter `isEffectivelyActive` or `blockedByAncestorId` moves the tree version. The tree body holds categories only (no item counts), so item writes cannot change it                                                                                                                                                                                                                                                                                                                                  |
| Not changed             | The till tag, the assortment tag and every other tag keep the organization-wide `version`, which category writes still move                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Upgrade proof           | A revision-113 database built from `origin/staging`, with a catalog and two categories seeded in a superuser `DO` block under a tenant context, upgraded by `db:prepare`: its `pg_dump --schema-only` (privileges included) equals a fresh revision-114 install apart from the `\restrict` keys, the seeded rows survive and `categories_version` equals `version` (6)                                                                                                                                                                                                     |

OpenAPI moves to `13.0.0`. Breaking (`npm run openapi:compat` against
`origin/staging`): the two former assortment routes are removed (and PR 6's
`categoriesTruncated`). Additive: `listing-changes`, the `includeDescendants`
and `hasImage` parameters, and `primaryImage` on every row of the list and of
the workspace page; `status` widens from one value to a comma-separated
text, which the check counts as compatible.

### M2a as built: which menus an outlet shows, and in what order (migration `0105`, baseline revision 115)

Two operations are added (Catalog 42 to 44). Gap G1 is closed.

#### C29 — Choose which menus an outlet shows, and in what order

**Owner decisions.** The menus assigned to an outlet only organize what its
till shows, in that order; they never limit what it sells. The assortment of
the business unit that operates the outlet and the sellable rule stay the only
rule of what sells, and `CatalogSellableContract.admit` does not look at menus.
**Actor:** the read needs `catalog.items.view` or `catalog.assortment.manage`
**at the outlet** (`PermissionCheckContract` with `outletId`, which a broader
scope covering the outlet also satisfies); the write needs
`catalog.assortment.manage` at the outlet. `catalog.items.manage` alone is not
enough, as for the assortment.
**Plan:** copied from the sibling assortment writes, which are gated for the
same permission: any list but the empty one is gated by `catalog.items`
(`platform.authorize_operation` with the outlet, so an outlet that is not
operating answers `422 · authorization.outlet_not_operational`, mapped by the
catalog since this slice); the empty list is never gated, so taking every menu
off an outlet always works, like a delisting.
**Routes:** `GET /catalog/outlets/{outletId}/menus` and
`PUT /catalog/outlets/{outletId}/menus` with `{ "menuIds": [...] }`.

```json
PUT /api/v1/catalog/outlets/0193…e1/menus
If-Match: "<the ETag of GET /catalog/outlets/0193…e1/menus>"
{
  "menuIds": ["01930000-0000-7000-8000-0000000000d0", "01930000-0000-7000-8000-0000000000d9"]
}
```

```json
200 OK
ETag: "<a new strong tag>"
{
  "data": {
    "outletId": "01930000-0000-7000-8000-0000000000e1",
    "menus": [
      { "menuId": "01930000-0000-7000-8000-0000000000d0", "code": "almuerzo", "name": "Menú del almuerzo", "status": "active" },
      { "menuId": "01930000-0000-7000-8000-0000000000d9", "code": "bebidas", "name": "Bebidas", "status": "active" }
    ]
  }
}
```

| C29              | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Answer           | `{ outletId, menus: [{ menuId, code, name, status }] }` in the order the till shows them; an outlet nobody assigned menus to answers `menus: []`. The write answers the same body as the read, with the new tag                                                                                                                                                                                                                                                                                                                                              |
| Body             | `menuIds`, required, 0 to 10 menu ids (`OUTLET_MENU_LIMIT`, one per position the table allows), each once; an eleventh answers `400` at `menuIds`, a repetition `400` at `menuIds[i]`, any other field `400`                                                                                                                                                                                                                                                                                                                                                 |
| Judgement        | Only a menu that starts being shown is judged: unknown or of another organization `404 · catalog.not_found`, archived `422 · catalog.menu_archived`, each with `meta.errors[].field` such as `menuIds[1]` and a message that says how to fix it; an unknown menu is answered before an archived one. A draft menu may be assigned. A menu the outlet already shows keeps its place even if it was archived since, and stays listed with its status                                                                                                           |
| No-op            | The same ids in the same order answer `200` with nothing written, no record and the catalog version unchanged; a new order of the same menus is a change                                                                                                                                                                                                                                                                                                                                                                                                     |
| ETag             | A strong hash of the answer (`contentEntityTag`), so renaming, archiving or restoring a shown menu changes it; `If-None-Match` answers `304` with no body; `Cache-Control: private, no-cache`. The write uses `@RequiresIfMatch()`: missing, blank or `*` answers `428 · precondition.required`, a stale tag `412 · foundation.precondition_failed`, judged after the version lock and the read                                                                                                                                                              |
| Unknown outlet   | Every caller refused at the outlet gets the same plain `403`; only a caller holding the permission organization-wide learns `404 · organization.structure_not_found`, through the published `organization.outlet_operating_context`, also when the gated decision answered `outlet_not_operational` for an outlet that does not exist                                                                                                                                                                                                                        |
| Locks and writes | The catalog version row `FOR UPDATE` first (menu transitions take it first too, so archiving or unpublishing a menu cannot race the assignment), then the stored list, then the new menus only, then one `DELETE` of the outlet's rows (when it had any) and one `INSERT ... unnest(...) WITH ORDINALITY` (when the list is not empty). The rows are links, deleted and inserted again; menus, sections and entries are never deleted. Each statement moves the catalog version once, so the tag of `GET /catalog/outlets/{outletId}/sellable-items` changes |
| Audit            | One `catalog.outlet.menus_set` record (resource kind `organization.outlet`, the outlet id) per real change, with `catalog.outlet.menus` before and after as the comma-separated ids (`null` for none); refusals of the permission, the plan or the outlet are recorded as denied, like the sibling routes                                                                                                                                                                                                                                                    |
| Statements       | `GET` 7 and `304` 7 (one permission, one read that also answers whether the outlet exists); `PUT` 15 whatever the number of menus, 14 without a stored list to delete or without a new menu to judge, 13 to empty it, 10 for the same list (`catalog-outlet-menus-statement-budget.e2e-spec.ts`); the 2 added statements are the lock of the outlet tree and the second permission decision of *Writes and reassignments of the outlet*                                                                                                                      |

**Writes and reassignments of the outlet.** `PUT /catalog/outlets/{outletId}/menus` and `PUT /catalog/outlets/{outletId}/hidden-items` decide `catalog.assortment.manage` at the outlet, and the business unit that operates the outlet is part of that decision, so a reassignment of the outlet that commits between the decision and the write must not let a caller anchored only at the old unit change the assortment of the new one. One gate, `admitOutletCommand` (`application/outlets/outlet-assortment-gate.ts`), serves both routes and any later outlet write: it decides the permission (a refused caller is audited and returns without taking any lock, so a caller without the permission can never block a reassignment), takes the shared outlet-tree advisory lock of the organization (`pg_advisory_xact_lock_shared` on the key `organization.outlet-tree:<organization id>` that Organization takes exclusively in every reassignment, reparent and update of an outlet), and decides again, in a new statement, so under READ COMMITTED the second decision sees every reassignment that committed before the lock was granted, while a later one waits for the write to commit. The lock order is the outlet tree (shared), then the catalog version; Organization takes its structure version, then the tree (exclusive), then the outlet row, and never the catalog version, and no other Catalog command takes an outlet lock, so the orders cannot form a cycle. A caller refused by the second decision gets the same `403 catalog.action_forbidden` and the denial audit record of the transaction; a caller that waits behind a reassignment longer than `DATABASE_LOCK_TIMEOUT_MS` gets `503 service.unavailable` and nothing is written. The two `GET`s read in one read-only snapshot like the till reads. Responses for authorized callers do not change |
| Table | `catalog.outlet_menus(organization_id, outlet_id, menu_id, position smallint, created_at)`, primary key `(organization_id, outlet_id, position)`, unique `(organization_id, outlet_id, menu_id)`, `position` 0 to 9, composite foreign keys to the outlet and to the menu of the same organization, index `(organization_id, menu_id)`; statement-level version triggers, the organization reassignment guard, RLS select, insert and delete; the runtime holds `SELECT`, `INSERT`, `DELETE`. Contract: `database/tests/contracts/catalog-outlet-menus-contracts.ts` |
| Upgrade proof | A revision-114 database built from `origin/staging`, with an organization, an outlet and two menus seeded in a superuser `DO` block under a tenant context, upgraded by `db:prepare`: its `pg_dump --schema-only` (privileges included) equals a fresh revision-115 install apart from the `\restrict` keys, the seeded rows survive and the runtime writes an assignment that moves the version |
| Front end | Read the list, reorder or edit it on screen, send the whole list with the tag read; refresh the tag after any write (the write answers it). An archived menu in the list is shown as archived; it can be kept or taken out, never added again until it is restored |

OpenAPI moves to `13.1.0`: `npm run openapi:compat` against `origin/staging`
finds no breaking change and one additive one, the path
`/api/v1/catalog/outlets/{outletId}/menus`.

### M2b as built: the till groups what an outlet sells by its menus (no migration, baseline revision 115)

No operation is added (Catalog stays at 44). C17 gains one top-level key.

**Owner decisions.** Menus only organize the till screen; they never limit
what sells. An item outside every menu still sells through the search (C19)
and the scan (C18); an outlet without menus answers `menus: []` and the till
keeps grouping by category. The key is only on the snapshot the till loads at
start, `GET /catalog/outlets/{outletId}/sellable-items`, never on the search
or the scan.

```json
GET /api/v1/catalog/outlets/01930000-0000-7000-8000-0000000000e1/sellable-items
200 OK
{
  "data": {
    "businessUnitId": "01930000-0000-7000-8000-0000000000b1",
    "categories": [ ... ],
    "items": [ ... ],
    "modifierGroups": [ ... ],
    "menus": [
      {
        "menuId": "01930000-0000-7000-8000-0000000000d0",
        "name": "Menú del almuerzo",
        "sections": [
          {
            "sectionId": "01930000-0000-7000-8000-0000000000d1",
            "name": "Entradas",
            "entries": [{ "itemId": "01930000-0000-7000-8000-0000000000f3" }],
            "subsections": [
              {
                "sectionId": "01930000-0000-7000-8000-0000000000d2",
                "name": "Frías",
                "entries": [{ "itemId": "01930000-0000-7000-8000-0000000000f1" }]
              }
            ]
          },
          {
            "sectionId": "01930000-0000-7000-8000-0000000000d3",
            "name": "Principales",
            "entries": [
              {
                "itemId": "01930000-0000-7000-8000-0000000000f5",
                "variantIds": ["01930000-0000-7000-8000-0000000000f6", "01930000-0000-7000-8000-0000000000f7"]
              }
            ],
            "subsections": []
          }
        ]
      }
    ]
  },
  "meta": { "catalogVersion": 42, "truncated": false, "omittedItems": 0, "media": { "tileUrlTemplate": "https://media.ninaku.io/a/{imageRef}/tile.webp" } }
}
```

| C17 menus                | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Which menus              | The menus assigned to the outlet (C29) whose status is `active` and whose window is open now (C31; a menu without a window is always open), in the assignment order (`outlet_menus.position`); a draft or archived menu is not shown, even while assigned                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Shape                    | `menus: [{ menuId, name, sections: [{ sectionId, name, entries, subsections: [{ sectionId, name, entries }] }] }]`, the M1 names; an entry is `{ itemId }`, or `{ itemId, variantIds }` when its `variantMode` is `selected`. Nothing about the item is repeated: the till reads it from `items` by `itemId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Order                    | Sections, subsections and entries in their M1 order; `variantIds` in the order of the selection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| What is left out         | A suspended or retired section, with its subsections; a suspended or retired entry; an entry whose item is not in the sellable set of the same answer (inactive, archived, delisted at the unit, without an active configurable variant, or a combo that cannot be composed); a selected variant that is inactive, archived or not configurable, and a selected entry left with none; then a section left with no entries and no non-empty subsection, and a menu left with no section                                                                                                                                                                                                                                                                                                 |
| Same rule as the domain  | The SQL answers what `isAvailableEntry` and `isActivePart` (`domain/menus`, `domain/shared`) decide with the item status read as "sold by this answer" and the variant statuses as "among the sold variants"; an integration spec runs both on the same fixtures                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Truncated list           | Entries are kept against the whole sellable set, not the 2,000 answered items: with `meta.truncated: true` an `itemId` may be outside `items`, and the till resolves it through C19                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ETag and `304`           | Unchanged: `outlet_menus` and the four menu tables move the catalog version, so assigning, reordering, activating a menu, renaming or suspending a section changes the till tag and an earlier `If-None-Match` answers `200`. The `304` path reads no menu                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Statements               | Unchanged: 8 for the `200` (9 with images) and 7 for the `304`, guards, `BEGIN` and `COMMIT` included; the menus are composed inside the existing read statement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| SQL                      | One correlated aggregation from the outlet's assignment: the menu by key (`LATERAL ... LIMIT 1`), its active top sections and their subsections through `menu_sections_menu_parent_idx`, the entries of each section through `menu_entries_section_idx`, the selected variants through their primary key. Whether an entry's item sells is one lookup in a `jsonb` set built once from the statement's own `sold` set (an init plan, read only when an entry is judged), so the menus cost no second evaluation of the sellable rule and no join the planner could reorder                                                                                                                                                                                                             |
| Plan on stale statistics | With 2,001 items, 10 menus of 1,000 entries (3 active, 3,000 shown) imported after the statistics were frozen: no sequential scan of a menu tree table, no looped scan wider than 100 rows, the widest menu lookup 18 rows, about 6 rows and 16 to 20 buffers per shown entry, also with `enable_nestloop = off` (the spec allows 14 and 40, about twice the measured). Known limit: when the statistics were taken while the menu tables were nearly empty (a new database), PostgreSQL may read the top sections of a menu through the primary key with a filter, every section of the table per menu (520 rows per loop measured, with the same cost per entry); the spec seeds a neighbour organization with menus so its statistics are not near-empty, as a running database has |
| Payload                  | A restaurant of 300 items with two menus showing 240 entries, half of them with two selected variants: the menus add 25.1 KB to 276.2 KB of categories, items and groups (+9.1 %)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Latency                  | Same fixture, median of 15 runs on a loaded development machine: execution 18.6 → 21.6 ms and planning 3.4 → 4.2 ms. An outlet without menus pays only the planning of the menus part and one read of its (empty) assignment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Front end                | Group the screen by `menus`, then `sections` and `subsections`; render each entry from `items` by `itemId`, limited to `variantIds` when present; when `menus` is empty group by `categories` as before. Items outside every menu still sell through the search and the scan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

OpenAPI moves to `13.2.0`: `npm run openapi:compat` against `origin/staging`
finds no breaking change; the additive ones are the M2a path and the
`menus` property of the `200` of `GET /catalog/outlets/{outletId}/sellable-items`.

***

### K16 as built: the items an outlet does not sell (migration `0106`, baseline revision 116)

Two operations are added (Catalog 44 to 46). Several outlets may share one
business unit, and nothing said "this item is not sold at this outlet".

#### C30 — Choose which items of its unit assortment an outlet does not sell

**Owner decisions.** The catalog is abstract and administered per business
unit or per outlet, without per-channel flags (OV24). The effective sellable
set of an outlet is the assortment of the business unit that operates it
today **minus** the items it hides. An outlet can only hide: it never sells
what its unit does not list. Hiding is by item, so all its variants are
hidden. Menus stay presentation and never limit what sells.
**Actor:** the read needs `catalog.items.view` or `catalog.assortment.manage`
at the outlet; the write needs `catalog.assortment.manage` at the outlet
(`decideAtOutlet`, the same gate as C29, now one shared function).
**Plan:** like C29, any set but the empty one is gated by `catalog.items`, and
an outlet that is not operating answers `422 · authorization.outlet_not_operational`;
the empty set is never gated.
**Routes:** `GET /catalog/outlets/{outletId}/hidden-items` and
`PUT /catalog/outlets/{outletId}/hidden-items` with `{ "itemIds": [...] }`.

```json
PUT /api/v1/catalog/outlets/0193…e1/hidden-items
If-Match: "<the ETag of GET /catalog/outlets/0193…e1/hidden-items>"
{
  "itemIds": ["01930000-0000-7000-8000-0000000000a1", "01930000-0000-7000-8000-0000000000a3"]
}
```

```json
200 OK
ETag: "<a new strong tag>"
{
  "data": {
    "outletId": "01930000-0000-7000-8000-0000000000e1",
    "items": [
      { "itemId": "01930000-0000-7000-8000-0000000000a3", "code": "ensalada-cesar", "name": "Ensalada César", "status": "active" },
      { "itemId": "01930000-0000-7000-8000-0000000000a1", "code": "hamburguesa-clasica", "name": "Hamburguesa clásica", "status": "active" }
    ]
  },
  "meta": {}
}
```

| C30                    | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Answer                 | `{ outletId, items: [{ itemId, code, name, status }] }` by name; an outlet that hides nothing answers `items: []`. The write answers the same body as the read, with the new tag. The item reference is the one every other catalog route uses                                                                                                                                                                                                                                                                                                                                              |
| Body                   | `itemIds`, required, 0 to 500 item ids (`OUTLET_HIDDEN_ITEM_LIMIT`: a restaurant outlet hides tens and a store a few hundred; the bound keeps the set one read under one tag), each once; a 501st answers `400` at `itemIds`, a repetition `400` at `itemIds[i]`, any other field `400`                                                                                                                                                                                                                                                                                                     |
| Write shape            | The whole set is replaced under the tag of the set that was read (`428` without `If-Match`, `412` when it changed), like C29 and the structure of a menu. The assortment of a unit uses the delta `listing-changes` because its set is unbounded; this set is bounded, so no second write route exists                                                                                                                                                                                                                                                                                      |
| Judgement              | Only an item that starts being hidden is judged: unknown or of another organization `404 · catalog.not_found` with `meta.errors[].field` such as `itemIds[1]` and a message that says how to fix it. An item of any status can be hidden; one archived later stays in the answer with its status until it is taken out                                                                                                                                                                                                                                                                      |
| No-op                  | The same set in any order answers `200` with nothing written, no record and the catalog version unchanged                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Effect                 | The item leaves the till list (C17), the search (C19), the scan (C18) and `CatalogSellableContract.resolve` and `admit` (given an `outletId`, refused `not_listed`) of that outlet only; a combo whose component it hides is incomplete there exactly like one with an unlisted component; a menu entry of the item leaves that outlet's menus. A sibling outlet of the same unit is unaffected; the rows stay when the outlet moves to another unit                                                                                                                                        |
| Outlet in the contract | `CatalogSellableContract.resolve` and `admit` take an optional `outletId`. Given one, they judge in the same statement that the outlet exists in the organization and is operated by the given business unit on the date of its site; otherwise the verdict or the admission is refused with `outlet_not_operated_by_unit` (right after `business_unit_unavailable`), so a wrong outlet can never skip the hidden items. Without an `outletId` they judge the unit alone, which is a documented mode of the contract. `catalog.variant_is_listed_at_outlet` answers false in the same cases |
| A set, not a list      | An item sent twice is refused by the schema at the position of the repeat (`400`, `itemIds[i]`); the use case, which other callers reach, compares, writes and records the distinct items in the order first sent, so `[A, A]` over a stored `[A]` is a no-op                                                                                                                                                                                                                                                                                                                               |
| One fragment           | `hiddenAtOutlet` in `sellable-rule.queries.ts`, a keyed anti-lookup per candidate item on the primary key `(organization_id, outlet_id, item_id)`, composed once by `listedInScope`; the plan specs of the till keep their original ceilings with 5 % of the items hidden                                                                                                                                                                                                                                                                                                                   |
| ETag and `304`         | The strong tag of the set (`contentEntityTag`); the till tag moves with every write because `outlet_hidden_items` bumps the catalog version, so the tag the till sent before no longer answers `304`                                                                                                                                                                                                                                                                                                                                                                                        |
| Locks and writes       | The catalog version row `FOR UPDATE` first (archiving an item takes it first too), then the stored set, then the new items only, then one `DELETE` of the outlet's rows and one `INSERT`                                                                                                                                                                                                                                                                                                                                                                                                    |
| Audit                  | One `catalog.outlet.hidden_items_set` record (resource kind `organization.outlet`, the outlet id) per real change, with `catalog.outlet.hidden_items` before and after as the comma-separated sorted ids (`null` for none); refusals are audited                                                                                                                                                                                                                                                                                                                                            |
| Table                  | `catalog.outlet_hidden_items(organization_id, outlet_id, item_id, created_at)`, primary key `(organization_id, outlet_id, item_id)`, composite foreign keys to the outlet and the item; runtime `SELECT`, `INSERT`, `DELETE` only                                                                                                                                                                                                                                                                                                                                                           |
| SQL                    | `catalog.variant_is_listed_at_outlet(org, unit, outlet, variant)` is `variant_is_listed` plus "the unit operates the outlet today" and the hiding check, and fails closed; the Sales order-line trigger keeps the unit-keyed functions until Sales decides to use it                                                                                                                                                                                                                                                                                                                        |
| OpenAPI                | Moves to `13.3.0` (additive): `openapi:compat` against `origin/staging` finds no breaking change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Front end              | Read the set, add or remove items on screen, send the whole set with the tag read; refresh the tag after any write                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

#### C31 — Choose the hours in which an outlet shows each of its menus

**Owner decisions.** A business shows different menus at different times at an
outlet ("Breakfast" until 11:00, "Lunch" on certain days). Menus only organize
the till screen and never limit what is sold: `admit` ignores menus. The
catalog stays abstract, with no per-channel flag (OV18, OV24). A window decides
which of the menus assigned to an outlet (C29) its till shows *now*. The window
belongs to the assignment of the menu to the outlet, not to the menu: the same
"Breakfast" may open 06:00 to 11:00 at outlet A and 07:00 to 12:00 at outlet B.
A menu with no window is always shown. Holidays and date ranges are out of
scope (deferred).
**Actor, plan and closed outlet:** exactly C29 (same gate, same plan rule, same
`authorization.outlet_not_operational`).
**Routes:** no new route. The windows ride on `GET` and `PUT
/catalog/outlets/{outletId}/menus` (C29): one write route for one use case, one
`If-Match`, one tag and one audit record. The request keeps `menuIds` (the set
and the order) and gains an optional `windows` list; every menu of the answer
gains `windows`. A separate `/menu-windows` route was rejected: two writes for
one use case, with two `If-Match` and two records. Replacing `menuIds` with
`menus: [{ menuId, windows }]` was rejected: it breaks the contract of M2a.

```json
PUT /api/v1/catalog/outlets/0193…e1/menus
If-Match: "<the ETag of GET /catalog/outlets/0193…e1/menus>"
{
  "menuIds": ["01930000-0000-7000-8000-0000000000d0", "01930000-0000-7000-8000-0000000000d9"],
  "windows": [
    { "menuId": "01930000-0000-7000-8000-0000000000d0", "days": [1, 2, 3, 4, 5], "from": "12:00", "until": "16:00" },
    { "menuId": "01930000-0000-7000-8000-0000000000d9", "from": "22:00", "until": "02:00" }
  ]
}
```

```json
200 OK
ETag: "<a new strong tag>"
{
  "data": {
    "outletId": "01930000-0000-7000-8000-0000000000e1",
    "menus": [
      { "menuId": "01930000-0000-7000-8000-0000000000d0", "code": "almuerzo", "name": "Menú del almuerzo", "status": "active",
        "windows": [{ "days": [1, 2, 3, 4, 5], "from": "12:00", "until": "16:00" }] },
      { "menuId": "01930000-0000-7000-8000-0000000000d9", "code": "bebidas", "name": "Bebidas", "status": "active",
        "windows": [{ "days": [1, 2, 3, 4, 5, 6, 7], "from": "22:00", "until": "02:00" }] }
    ]
  },
  "meta": {}
}
```

| C31             | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Window          | `days` (1 Monday to 7 Sunday, each once, every day when omitted), `from` (inclusive) and `until` (exclusive) as `HH:MM`, in the local time of the site of the outlet. `until` earlier than `from` crosses midnight and the window belongs to the weekday it starts on (Friday 22:00 to 02:00 ends on Saturday at 02:00). `from` equal to `until` is refused                                                                                                                                                                                                                                                                                                                                                                             |
| Body            | `windows` is optional; each entry names its `menuId`, which must be in `menuIds`. At most 14 windows per menu (`MENU_WINDOW_LIMIT`: two service periods on each of seven weekdays), 140 in all. A body without `windows`, the form that predates them, shows every menu always and so replaces the windows the outlet had: the write is a whole-set `PUT`, so send the windows read from the `GET` again to keep them                                                                                                                                                                                                                                                                                                                   |
| Validation      | `400` with a pointer that teaches: an hour that is not `HH:MM` (`windows[0].from`), `from` equal to `until` (`windows[0].until`), no day, a day outside 1 to 7 or a repeated day (`windows[0].days[1]`), a window of a menu that is not in `menuIds` (`windows[1].menuId`), more than 14 windows for a menu (`windows[14]`), any other field                                                                                                                                                                                                                                                                                                                                                                                            |
| Overlap         | Windows of one menu may touch (one ends when the next starts) but not share a minute of the week, midnight and Sunday to Monday included: `422 · catalog.menu_windows_overlap` with `meta.errors` naming each window that overlaps an earlier one (`windows[2]`). Refused rather than merged: two windows that share a minute are almost always a typing mistake. Judged also when no menu is new                                                                                                                                                                                                                                                                                                                                       |
| Answer          | Each menu carries `windows: [{ days, from, until }]` in canonical order (by `from`, then `until`, then `days`), days ascending; `[]` when the menu is always shown. The tag of the read is the strong hash of the answer, so a window change moves it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| No-op           | The same windows, in any order and with the days in any order, answer `200` with nothing written, no record and the catalog version unchanged                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Writes          | As C29 plus, when the outlet has or gets windows, one `DELETE` of the weekdays and one of the windows before the assignment is deleted, and one `INSERT` of the windows and one of the weekdays after it is inserted (no foreign key cascades). Each statement moves the catalog version once                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Audit           | The same `catalog.outlet.menus_set` record per real change, with `catalog.outlet.menus` (only when the ids or their order moved) and `catalog.outlet.menu_windows` (only when the windows moved) before and after; the windows read `<menuId> <days> <from>-<until>` joined by `; ` (`null` for none). No new action code                                                                                                                                                                                                                                                                                                                                                                                                               |
| Tables          | `catalog.outlet_menu_windows(organization_id, outlet_id, menu_id, window_number, time_from, time_until, spans_midnight, created_at)`, primary key on the first four, composite foreign key to `outlet_menus(organization_id, outlet_id, menu_id)`, number 0 to 13, and the time check of Pricing (`from <> until`, `spans_midnight` exactly when `from > until`) without any foreign key to Pricing; `catalog.outlet_menu_window_weekdays(…, window_number, iso_weekday 1 to 7)` with a composite foreign key to the window. Statement-level version triggers, the organization reassignment guard, RLS and `SELECT`, `INSERT`, `DELETE` for the runtime. Contract: `database/tests/contracts/catalog-outlet-menu-windows-contracts.ts` |
| Rejected shapes | Columns on `outlet_menus` (a menu needs several windows and each window a repeating set of weekdays), a column on `menus` (the menu is organization-wide), and weekdays as an array column (no foreign key, no check per element, nothing to probe)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Front end       | Read the menus with their windows, edit them on screen, send `menuIds` and `windows` with the tag read; a menu without a window is always shown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**The till read.** `GET /catalog/outlets/{outletId}/sellable-items` (C17) keeps
only the menus whose window is open at the instant of the read, in the outlet
order, and a menu without a window always; `menus: []` when none is open and
nothing else is blocked. The server evaluates, in SQL, in the local time of the
site of the outlet (`organization.outlet_operating_context` returns
`site_timezone`), at an instant that a `Clock` (`src/foundation/time`) gives the
use case once per request and the use case passes to both statements of the
read; tests inject it. The comparison is on the wall clock, so a daylight
saving change moves a window with the clock, and the autumn hour that happens
twice is open twice. `menusValidUntil` (ISO-8601 UTC, in `data` next to
`menus`, absent when no window will ever change the set) is the next instant at
which a menu opens or closes: the till refreshes then. It is the earliest
boundary that only one side owns (the start of a window of a menu that is no
window's end, or the other way round), so touching windows name no change. The
wall clock advances at the pace of the instant until the zone changes its UTC
offset, so the boundary is the instant plus the wall-clock distance to it, with
no conversion of an ambiguous or skipped local time. The first change of UTC
offset of the zone after the instant (found on a 15-minute grid, PostgreSQL's
`AT TIME ZONE` on the site zone) caps it: the clock jumps there, and the set can
change there (the autumn clock going back to 01:00 closes a window that opened
at 01:30 in the first pass, and reopens it in the second), so `menusValidUntil`
is the least of both and names that instant even when the set does not change
then, which only brings a harmless early refresh; it is never later than the
true change, in the first or the second pass of the repeated hour and when a
window starts in the hour a spring change skips. The tag and the menus are
exact at every instant.

| C17 menus and time | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ETag               | `c<catalog>-s<structure>-<unit or none>-d<delivery>-m<mask>[-u<instant>]`. `m` is the set of open menus as a bit mask over their positions, in hexadecimal (exact, not a hash: a menu keeps its position until a write, and a write moves the catalog version); `u` is `menusValidUntil`. It moves with the clock and without any write, answers `304` for the same set, and never for a stale one. Two days with the same open menus still get different tags because the body differs |
| One statement      | The statement that already resolves the outlet state also returns the mask and the next change, so a `304` costs no new statement (`catalog-till-menus-statement-budget.e2e-spec.ts` is unchanged). The search keeps its lean statement and carries no menus                                                                                                                                                                                                                            |
| Plan               | Every window probe is a keyed lookup on the primary keys; the plan specs keep their ceilings and read no window table whole, with 150 neighbour outlets so the frozen statistics see a real table                                                                                                                                                                                                                                                                                       |
| OpenAPI            | Moves to `13.4.0` (additive): `windows` in the request and in each menu of the answer, `menusValidUntil` in the sellables answer, `catalog.menu_windows_overlap` in the `422`                                                                                                                                                                                                                                                                                                           |

### K16b as built: option targets are judged by the listing and the hiding (no migration)

**Owner decision.** A local never sells what its business unit does not list
or what its outlet hides. K16 left the modifier options whose target is an
item outside that rule ("kept on purpose"); this slice changes it, and
corrects the claim of PR #597, which said that a combo or an option whose
component is hidden at an outlet was unavailable there: for options it was not.

**The rule.** An option is available when it is active and, when it targets a
variant, that variant is an active variant of an active item that the unit
lists, the outlet does not hide and that opens no combo group (`targetSellable`:
the listing and hiding fragments of the sellable rule, written once). An
option sells a plain item: a combo, composable or not, is not available as an
option target. The judgement is made inside the statement that reads the data,
so there is no window between the check and the answer. A group is offered when
one of its options is available; a required group counts only the units of its
available options; the defaults, quantities and option limits of an offer leave
with the option; the item whose required group lost all its options is left out
of the lists, the search and the scan (`required_modifier_unsatisfiable` at
`resolve`) and is refused at `admit`; selecting an option that left is refused
`option_unavailable`. Without an `outletId`, `resolve` and `admit` judge the
unit alone, so only the delisting applies.

**Where it lives.** `availableOption(alias, scope)` in
`sellable-rule.queries.ts` has three modes. With `inline` it judges the target
where the option is read: the scan and the filter of the search, which look at
the few options of the items they examine, so the work follows the page and not
the organization. With `targets` it asks a `jsonb` set of sellable targets that
the statement builds once with `optionTargetSet` (`option_targets`: the list,
for every active target of the organization; `resolve`, for the options of the
items it serves and of the components of their combos; `page_targets`: the
enriched page of the search, for the options of the items on the page), as a
keyed lookup. Without either it is the structural `activeOption`. The options of
the offering item and of the components of its combo (level 1) are judged by the
scope; those of deeper components, and those of a target, structurally. The
writes (`SHARE_LOCK_GROUPS`, the defaults of an offer) keep the structural rule:
they have no unit.

**The write path (C12).** Creating a group or setting its options refuses a new
option whose `variantId` belongs to a combo, an item with a live bundle group
(the fragment `opensAGroup` the read uses): `422 · catalog.option_target_not_plain`,
at `options[i].variantId` in the set and without a field in the create, after
`404 · catalog.not_found` and `422 · catalog.variant_not_active`. The check runs
inside the transaction of the write: the variants and their items are
share-locked, and the plain flag comes back in that same statement, so the
write costs no extra statement. The composition command locks the item row for
update, so it waits for the write that holds the share lock; a composition that
commits between the snapshot of that statement and its lock is the same as one
that composes right after the write, which the reads already neutralize. A kept option never changes its variant, so it is not
judged again. OpenAPI moves to `13.8.0` (additive: the new code on the two
routes).

**Existing rows.** Options written before this rule that point to a combo stop
being offered at the next read; nothing rewrites them. The repository holds no
seed, fixture or test with a combo as an option target (an offering item that is
a combo is a different thing). No database constraint backs the rule, because it
would need a migration; a plain item composed into a combo after it became a
target stops being offered in the same way.

**The item read (C3)** is unchanged byte for byte: it shows the stored status
of each option and of its target, never availability, which depends on a unit
and an outlet.

**Known limit.** The Sales order-line trigger is unit-keyed
(`catalog.assert_variant_listed`) and does not enforce the hiding of an outlet
nor the listing of an option target. Moving it to
`catalog.variant_is_listed_at_outlet` is a Sales decision (R19).

**Cost.** Measured in `PERFORMANCE_BASELINE.md`, section 20.

### K14a as built: a quantity for each preselected option (migration `0108`, baseline revision 118)

No operation is added (Catalog stays at 46). C13 gains `defaultQuantities` and
`admit` (C20) answers `reducedDefaults` for real; the design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K14a as built" (OV16).

| C13 default quantities | As built                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                 | `catalog.item_modifier_group_defaults.quantity` (`integer NOT NULL DEFAULT 1`, check 1 to 999); `catalog.item_modifier_group_option_overrides` is created for K14b and nothing reads it yet                                                                                                                                                                                                         |
| Request                | Each offered group, on the item and on a variant override, may send `defaultQuantities`: `{ "<optionId>": 2 }`, integers 1 to 999, keys among `defaultOptionIds`; absent or empty counts every default as one unit                                                                                                                                                                                  |
| Rules                  | `422 · catalog.default_quantities_invalid` pointing at `offers[i].defaultQuantities` (or `variantOverrides[j].offers[i].defaultQuantities`) when a quantity is above the `maxQuantity` of its option or the quantities of all the defaults add up to more than `maxSelections`; the defaults are judged first; a key that is not in `defaultOptionIds` is a `400` at `defaultQuantities.<optionId>` |
| Change detection       | A quantity-only edit is a change: the offer, its audit summary (`o1*3`) and the item tag move; a replay writes nothing; the plan is asked, lowering included                                                                                                                                                                                                                                        |
| Reads                  | `defaultQuantities` appears on the item read (offers and variant overrides), on the offers of a group (C12), on the till list, search and scan and in the `resolve` snapshot only when some default starts above one unit, so every payload without quantities is byte-identical                                                                                                                    |
| `admit`                | A default counts its quantity: `reducedDefaults` names one chosen with less, `removedDefaults` one left out (its quantity as `defaultQuantity`); an unavailable default is never named and a preselection is never added                                                                                                                                                                            |
| Option writes          | They still do not judge offers again; the till reads `least(default quantity, option maxQuantity)`, so a lowered option maximum never makes a till preselect more than the option allows                                                                                                                                                                                                            |
| OpenAPI                | Moves to `13.5.0` (additive): `defaultQuantities` in the request and in the answers that carry `defaultOptionIds`, `catalog.default_quantities_invalid` in the `422`                                                                                                                                                                                                                                |

### K14b as built: lower or withhold an option for one offer (no migration, baseline revision 118)

No operation is added (Catalog stays at 46). C13 gains `optionLimits`; the
table `catalog.item_modifier_group_option_overrides` that migration `0108`
created is now read and written. The design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K14b as built" (OV16).

| C13 option limits     | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Request               | Each offered group, on the item and on a variant override, may send `optionLimits`: `{ "<optionId>": 1 }`, integers 0 to 999, option ids lowercase; absent or empty limits nothing. A limit is the most units of that option this offer allows; 0 withholds the option from this offer. The option itself, and every other offer of it, is untouched                                                                                                                                                                                                                                                                                                                    |
| Rules                 | `422 · catalog.option_limits_invalid` pointing at `offers[i].optionLimits.<optionId>` (or `variantOverrides[j].offers[i].optionLimits.<optionId>`) when a limit is equal to or above the `maxQuantity` of its option (it would raise or do nothing) or names an option that is not an available option of the group; the message names the option and its real maximum. The limits are judged first                                                                                                                                                                                                                                                                     |
| Interplay             | The minimum is judged against the units the limited options can still reach (the sum of the lower of each option maximum and its limit, an option limited to 0 adds nothing): `422 · catalog.selection_rule_invalid` as before. A default cannot be an option limited to 0 (`catalog.default_options_invalid`) and a default quantity cannot exceed the limit (`catalog.default_quantities_invalid`)                                                                                                                                                                                                                                                                    |
| Stored limits         | A limit already stored for the same option in the same offer is never judged again, so reading an offer and sending it back works after the option was lowered or retired (the limit is then moot: the effective maximum is the lower of the two)                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Change detection      | A limit-only edit is a change: the offer, its audit summary (`;limits=o1=1+o2=0` after the status and the defaults) and the item tag move; a replay writes nothing; the plan is asked, lifting limits included                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Write                 | The limits are replaced as a set in the same transaction as the offer: the limits of the scope are deleted and the sent ones inserted, after the defaults; a group that leaves the list loses its limits. The lock order is unchanged                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Reads                 | `optionLimits` appears on the item read (offers and variant overrides), on the offers of a group (C12), on the till list and the search (the scan only judges sellability) only when the offer limits an option, so every payload without limits is byte-identical. The till carries only the limits of available options that really lower the option: the client takes the lower of the option `maxQuantity` and the limit of the offer, and an option limited to 0 is not offered there                                                                                                                                                                              |
| `resolve` and `admit` | Each effective offer lists only the options it still allows: an option limited to 0 is absent, the others carry the effective maximum, so choosing the excluded one is `option_not_offered` and choosing more than the effective maximum `option_quantity_above_maximum`; an offer left with no option is not offered. An option belongs to one group and a variant has one effective offer per group, so the per-option map of the selection judgement is already per offer. A required offer whose limited options cannot reach its minimum makes the variant unsellable (`required_modifier_unsatisfiable`) in the till, the search, the scan, `resolve` and `admit` |
| Option writes         | They still do not judge offers again: lowering an option below an existing limit makes the limit moot. Sales and Commerce triggers check only the option's own maximum, which a limit never exceeds                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| OpenAPI               | Moves to `13.6.0` (additive): `optionLimits` in the request and in the answers that carry the offer, `catalog.option_limits_invalid` in the `422`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### K13 as built: structured variant dimensions (migration `0109`, baseline revision 119)

One operation is added, `GET /catalog/variant-dimensions` (C32; Catalog goes from
46 to 47); the matrix, the item read and the item list gain fields and a filter. The design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), section 8 and "K13 as built"
(H6); the tables are justified in `DECISIONS.md` D34.

| C6 matrix with dimensions | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                    | Four tables in `catalog`: `variant_dimensions`, `variant_dimension_values`, `item_variant_dimensions` and `item_variant_dimension_values` (columns, keys and grants in `database/README.md`, revision 119). Runtime `SELECT` and `INSERT` only: nothing is renamed, archived or removed yet, so no `UPDATE` or `DELETE` is granted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Dimension identity        | A dimension belongs to the catalog, not to an item; its code is the name reduced to lowercase letters and digits joined by hyphens (`Talla`, `TALLA` and `tallá` are `talla`; `dimension` when nothing is left) and is unique per catalog ignoring case. A value is found by its code ignoring case inside the dimension. A dimension or value that exists keeps its stored name; the request name is used only when it is created                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Fixed dimensions          | The first matrix of an item attaches its dimensions in the order sent (positions 0 to 2; at most three by the position check). A later matrix must name the same dimensions in the same order, and may add values; any other set, order or count answers `422 · catalog.variant_dimensions_locked`, whose detail names the dimensions of the item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Linking                   | A cell whose code exists, not archived, with exactly the name, SKU and quantity policy of the cell and no links is linked (its id, barcodes and images are untouched); one already linked to the same values is in effect; one with another profile, archived or linked to other values is `409 · catalog.code_taken`. A matrix that creates variants answers `201`; one that only links answers `200` with the new tag; one with nothing to do answers `200` and writes and records nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Combination               | Two active variants of an item cannot hold the same set of values: the database refuses it (a deferred constraint trigger on the links, which the matrix settles with `SET CONSTRAINTS ... IMMEDIATE` before it answers, and an immediate trigger on a variant that becomes active, which fails inside the `UPDATE` of its status and adds no statement), so the failure is `409 · catalog.variant_combination_taken` for the matrix and for the `reactivate` transition. Variants without links are never compared                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Statements and locks      | Fixed per command whatever the number of cells: the dimensions of the item, the known dimensions and values (one statement), at most one insert each of dimensions, values and item dimensions, the variants and the links. Lock order unchanged (catalog version row, item row `FOR UPDATE`); the combination check takes the item row `FOR NO KEY UPDATE`, the same row, so it adds no new ordering                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Audit                     | `catalog.item.variant_added`, with the changes it had plus `catalog.item.variant_dimensions` (the codes the first matrix fixed, in order), `catalog.item.variants_created` and `catalog.item.variants_linked`. No new action type was needed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Item read                 | Each variant that has links answers `dimensionValues: [{ dimension: { code, name }, value: { code, name } }]` in the order of the dimensions of the item, built once per statement for the items asked (`variant_links`, `labels` and `item_dimension_entries` CTEs of the same single statement); a variant without links does not carry the field, so the payload and the tag of every item that never had a matrix are byte-identical (the rich item golden file did not change). The till and sellable payloads are unchanged: the variant code and name remain what they sell by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| List (C32)                | `GET /catalog/variant-dimensions` (optional `businessUnitId`, as the item read) answers every active dimension of the default catalog ordered by the position of the matrix that created it and then by name: `{ code, name, activeItemCount, values: [{ code, name }] }`, the values active and in the order they were first sent, the count only of active items that a matrix gave the dimension. `catalog.items.view`, never the plan, nothing recorded; `Cache-Control: private, no-cache` and a strong content tag with `304`. One statement: the count visits each active item of the organization once and probes its dimensions by the key of the item (at most three), so it costs a few buffers per item and the plan spec bounds it; the answer is not capped because a catalog reuses a small vocabulary (a matrix creates at most three dimensions and fifty values per command). No new permission, grant or audit action                                                                                                                                                                                                                       |
| Filter (C2)               | `GET /catalog/items?variantValue=<dimension code>:<value code>`, repeatable up to three times for different dimensions: the items that have an **active variant carrying every value** (one variant must hold all of them; a size of one variant and a color of another do not match), codes compared without case, an unknown code listing nothing. It is one more candidate beside `q` and `categoryId` in the same `id IN (...)` shape: the value is found by the code of its dimension (the catalog case-insensitive unique index) and of its value, the links are read by `item_variant_dimension_values_value_idx`, the variant status by its key and each further value by the primary key of the links (`variant, dimension`), so the plan spec keeps it keyed and inside a ceiling of its own, 5 rows and buffers per imported item against the 4 of the other filters (measured 3.3 to 3.8 over three runs). The filter joins the cursor fingerprint (sorted pairs, only when present, so every other cursor is unchanged). A malformed value, more than three or one dimension twice answers `400` with a message that shows `variantValue=talla:m` |
| OpenAPI                   | Moves to `13.7.0` (additive): `GET /catalog/variant-dimensions`, `dimensionValues` in the answers that carry an item, `catalog.variant_dimensions_locked` in the `422` and `catalog.variant_combination_taken` in the `409` of the matrix, and a `409` on the variant transitions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### K14c as built: text options, prefixes and print hints (migration `0110`, baseline revision 120)

No operation is added: the options of a group are written by the existing
`PUT /catalog/modifier-groups/{modifierGroupId}` (C12) and, for a new group, by
`POST /catalog/modifier-groups`. The design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K14c as built" (OV13, OV14);
the decision is `DECISIONS.md` D36.

| C12 option presentation | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                  | Four columns of `catalog.modifier_options` and five new `CHECK`s (columns and constraints in `database/README.md`, revision 120). No table, no grant, no trigger                                                                                                                                                                                                                                                                                                                                                                               |
| Request                 | Each option of the set accepts `kind` (`instruction`, `catalog_variant`, `text`), `textMaxLength` (1 to 500), `prefix` (`add`, `extra`, `light`, `no`, `on_the_side`, `substitute`), `printsOnReceipt` and `printsOnKitchenTicket` (booleans). A field left out is its default: no length, no prefix, both hints `true`                                                                                                                                                                                                                        |
| Judgement               | The domain judges every option of the sent set before any write and answers `422 · catalog.modifier_option_presentation_invalid` listing each option by name and the rule it breaks, at the field (`options[2].textMaxLength`): a text option needs a length and exactly one unit and takes no prefix or `add`; a length belongs to text options only; `light`, `no`, `on_the_side` and `substitute` need `maxQuantity` 1; `no`, `on_the_side` and `substitute` apply to instruction options only. The same judgement runs on the group create |
| Offers                  | Per K5 an option write does not judge the offers that hold the option; the prefix rules are judged when the option is written                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Answers                 | The group read, the group write and the item read answer `textMaxLength`, `prefix`, `printsOnReceipt: false` and `printsOnKitchenTicket: false` only when they differ from the default, so every payload and tag of existing data is byte-identical (the rich item golden file did not change)                                                                                                                                                                                                                                                 |
| Audit                   | The option set audit change carries the new fields only when an option holds a non-default value, so records and comparisons of existing groups are unchanged                                                                                                                                                                                                                                                                                                                                                                                  |
| OpenAPI                 | Moves to `13.9.0` (additive, after the `13.8.0` of the option target listing): the option fields above and the `422` code                                                                                                                                                                                                                                                                                                                                                                                                                      |

### K14d as built: the reads and the judging of text selections (no migration, baseline revision 120)

No operation is added. The design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K14d as built".

| C17, C20 text selections | As built                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Till read                | `modifierGroups[].options[]` answers `textMaxLength`, `prefix`, `printsOnReceipt: false` and `printsOnKitchenTicket: false` only when they differ from the default; a text option answers `kind: "text"`. The payload, the entity tag and the golden file of a catalog without text options are byte-identical                                                                                 |
| `resolve` and `admit`    | The option of an effective offer carries the same fields under the same rule. A selection of a text option carries `text`; `admit` normalizes it to NFC and answers it in the admitted selection                                                                                                                                                                                               |
| Judging                  | `text_required`, `text_not_allowed`, `text_invalid` (blank, NUL, any control character) and `text_too_long` (beyond `textMaxLength`, 500 at most), naming the option; a quantity above the option maximum (1 for a text option) is refused first. More than 10 selections with text in a line, those of a combo's components included, is the request problem `too_many_texts` before any lock |
| Statements               | Unchanged: the four columns join the existing `SELECT`s                                                                                                                                                                                                                                                                                                                                        |
| Sales                    | Must add a `text` branch to its kind check and a column for the value before it consumes text options (X10, X3)                                                                                                                                                                                                                                                                                |

### K15a as built: master data hardening (migration `0111`, baseline revision 121)

No operation is added. The design is in
[`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K15a as built"; the
decision for the flags table is `DECISIONS.md` D37.

| Piece                   | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                  | Three description checks, one quantity step check, two columns of `item_variants` with their check, and `catalog.item_regulatory_flags` (columns and grants in `database/README.md`, revision 121)                                                                                                                                                                                                                                                                                                            |
| C4, C5 regulatory flags | `regulatoryFlags` (a list of `age_restricted_alcohol`, `age_restricted_tobacco`, `prescription_only`, `pharmacy_only`, `hazardous_goods`, each once) on the create and on `PATCH /catalog/items/{itemId}`, where it replaces the set and an empty list clears it; `400` for an unknown, repeated or `null` value. The item read answers `regulatoryFlags` only on an item that has any, so every other payload, tag and golden file is byte-identical. Catalog enforces nothing: a flagged item is still sold |
| C4, C6 net content      | `netContentQuantity` (greater than zero) with `netContentUnitCode` on `defaultVariant` of the create, on the add of a variant and on its edit (`null` in both clears them). `400` when only one is sent; `422 · catalog.unit_unknown` when the unit is not a reference unit of measure. Answered only on a variant that has one                                                                                                                                                                               |
| C6 quantity policy      | A minimum or a maximum that is not a multiple of the step is `422 · catalog.quantity_policy_invalid`                                                                                                                                                                                                                                                                                                                                                                                                          |
| Descriptions            | The 2000 character bound already applied by the API now holds in the database too; it adds no refusal                                                                                                                                                                                                                                                                                                                                                                                                         |
| Audit                   | The item edit holds the profile and the flag changes in one record; the variant edit names the two net content fields                                                                                                                                                                                                                                                                                                                                                                                         |
| OpenAPI                 | Still `13.9.0` (additive): `regulatoryFlags` on the item create, edit and answers, `netContentQuantity` and `netContentUnitCode` on the variant requests and answers, and `catalog.net_content_invalid`                                                                                                                                                                                                                                                                                                       |

### K12b as built: device bootstrap (no migration, baseline revision 124)

Two operations. Design in [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K12b as built"; decision `DECISIONS.md` D41.

| Piece                | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Open                 | `GET /catalog/outlets/{outletId}/bootstrap` answers `data: { cut, catalogVersion, businessUnitId, categories[], modifierGroups[] }` and `meta: { catalogVersion, media }`, read in one snapshot: every active category with its active ancestors and every active modifier group with its available options, whether or not an item offers it today (the device prunes), which keeps the opening a few milliseconds instead of evaluating the sold set. `cut` is an opaque value (`c<catalog version>-s<structure version>-<unit or none>`) the device sends unchanged on every page |
| Pages                | `GET /catalog/outlets/{outletId}/bootstrap/items?cut=&limit=&after=`: the items the outlet sells, in the item shape of the sellables read with, on each variant, `sku` and `barcodes[]` (`barcodeId`, `barcode`, `symbology`, `isPrimary`; active barcodes only), ordered by name and id, keyset (`limit` 1 to 100, default 50), no ceiling on the number of items. `meta: { pageInfo, catalogVersion, cut, media }`                                                                                                                                                                 |
| Cut moved            | `409 · catalog.bootstrap_cut_moved` when the catalog version, the structure version or the unit that operates the outlet is no longer the one of `cut`; nothing is read. The device opens again                                                                                                                                                                                                                                                                                                                                                                                      |
| Bad input            | `400` for a missing or malformed `cut`, a limit out of range, `before` or any unknown parameter, and a cursor issued for another cut, outlet, route or organization                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Access               | `catalog.sellables.view` at the outlet, decided on every call before the outlet is looked up (the till gate): a member without it, or whose scope moved, gets the same plain `403` for an existing, an unknown, a closed and a foreign outlet; only a caller holding it organization-wide learns `404 · organization.structure_not_found`                                                                                                                                                                                                                                            |
| Scan index           | The device builds `barcode -> variant` from the pages; the answer equals the online scan at the outlet (`GET .../barcode-matches`) for every barcode, and an archived or inactive barcode, a variant that is not active and an item the outlet does not sell are never in it                                                                                                                                                                                                                                                                                                         |
| Applying the feed    | Events of the organization with `catalogVersion` greater than the cut, in publication order; a `retired` or `removed` change deletes what its id names (an item with its variants and barcodes, a variant with its barcodes, a barcode); an `upserted` change rereads that aggregate. Serving the events and rereading by id belong to Sync                                                                                                                                                                                                                                          |
| Not in the bootstrap | Product brands and variant dimensions (no till screen shows them and their changes write no event), and menus with their time windows (read online from the sellables read)                                                                                                                                                                                                                                                                                                                                                                                                          |
| Statements           | Open: 7 (session, membership, `BEGIN`, tenant context, permission, the read, `COMMIT`); a page: 8 (the same plus the cut check); a refused cut: 7                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| OpenAPI              | Moves to `13.10.0` (additive: two paths and the `409` code)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### K12a as built: catalog change feed (migration `0114`, baseline revision 124)

No operation is added and the OpenAPI document does not change. Design in [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K12a as built"; decision `DECISIONS.md` D40.

| Piece              | As built                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| What it is         | Every catalog write that moves the catalog version also leaves, in the same transaction, typed events in `events.outbox_records`: `catalog.item.changed`, `.variant.changed`, `.barcode.changed`, `.offer.changed`, `.modifier.changed`, `.bundle.changed`, `.menu.changed`, `.category.changed` and `.listing.changed`. It is written by SQL triggers, so no command, route or use case changes |
| Payload            | `{ schemaVersion: 1, catalogVersion, change, <id>, status?, retiredAt? }`; `change` is `upserted`, `retired` or `removed`; a retirement or a removal carries `retiredAt` (the tombstone). Contract: `src/modules/catalog/contracts/catalog-change-event.ts`                                                                                                                                      |
| Which commands     | All of them: the item, variant, barcode, category, modifier, offer, bundle, menu, assortment, hidden item, outlet menu and window commands, and the business unit registration (its default assortment is written when it commits). Retiring an offer, archiving an item or a barcode, and every other `archived` or `retired` transition write a tombstone                                      |
| Rollback and retry | A command that fails after its write leaves no event, no outbox row and no version move; a replayed create (`Idempotent-Replayed: true`) writes nothing                                                                                                                                                                                                                                          |
| Cost               | No statement is added to any command (the triggers run inside the existing statements), so the statement budgets are unchanged; the latency of a write grows by the event inserts (`docs/operations/PERFORMANCE_BASELINE.md`, section 22)                                                                                                                                                        |
| Not served yet     | Nothing reads the feed: the bootstrap and the delta read for a device are K12b and the Sync module                                                                                                                                                                                                                                                                                               |

### K15d as built: variant identifiers (migration `0113`, baseline revision 123)

No operation is added. Design in [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K15d as built"; decision `DECISIONS.md` D39.

| Piece   | As built                                                                                                                                                                                                                                                                                                                                                                     |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema  | `catalog.item_variant_identifiers` (columns and grants in `database/README.md`, revision 123)                                                                                                                                                                                                                                                                                |
| Write   | `identifiers` (a list of `{ scheme, value }`, scheme `mpn`, `isbn` or `manufacturer_code` each once, value 1 to 100 characters) on `defaultVariant` of `POST /catalog/items`, on `POST /catalog/items/{itemId}/variants` and on `PATCH .../variants/{variantId}`, where it replaces the set (`[]` clears it); `400` for an unknown or repeated scheme, a bad value or `null` |
| Read    | `identifiers` on a variant only while it has any                                                                                                                                                                                                                                                                                                                             |
| Audit   | The variant edit records `catalog.item.variant.identifiers` with the set before and after as `scheme:value` pairs                                                                                                                                                                                                                                                            |
| OpenAPI | Still `13.9.0`, additive                                                                                                                                                                                                                                                                                                                                                     |

### K15c as built: product brands (migration `0112`, baseline revision 122)

Design in [`CATALOG_OPTIONS_V2.md`](CATALOG_OPTIONS_V2.md), "K15c as built"; decision `DECISIONS.md` D38.

| Piece          | As built                                                                                                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema         | `catalog.product_brands` and `items.product_brand_id` (columns and grants in `database/README.md`, revision 122)                                                                                                     |
| Brand routes   | Five operations under `/catalog/product-brands`: create (idempotent), list (`status`), read, rename (`If-Match`) and `transitions` (archive, restore); `catalog.items.manage` organization-wide                      |
| Item side      | `productBrandId` on the create and edit of an item (`null` clears); `404 · catalog.not_found` for an unknown or foreign brand; `422 · catalog.product_brand_archived`; the read answers `productBrand` only when set |
| List           | `productBrandId` filters `GET /catalog/items`, archived brands included, and is bound into the cursor                                                                                                                |
| Archived brand | An item that already has it keeps it; only giving it is refused                                                                                                                                                      |
| Audit          | `catalog.product_brand` created, renamed, archived, restored; the item edit records `catalog.item.product_brand` with the ids                                                                                        |
| OpenAPI        | Still `13.9.0`, additive                                                                                                                                                                                             |

### I1 as built: a bulk import document is judged, not applied (no migration, baseline revision 124)

Design in `catalog-c25-c27-plan.md` section B; the owner decisions of 2026-10-26 (JSON only, upsert by code, synchronous, 500 items a request, no new permission).

| Piece        | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Route        | `POST /catalog/imports`, `catalog.items.manage` organization-wide and capability `catalog.items`, counted by the member write limit, `Cache-Control: private, no-store`; classified as a back-office route, not hot                                                                                                                                                                                                                                                                                                                                                                                                              |
| Document     | `catalogId` (default catalog when omitted), `mode` (`create` or `upsert`), `dryRun`, `categories` (at most 200), `items` (at most 500) with `variants` (at most 1,500 in all) and `barcodes` (at most 3,000 in all); fields reuse the item, variant, category and barcode schemas; a limit is a `400`, the body ceiling is 1 MiB (four 256 KiB steps, `413`)                                                                                                                                                                                                                                                                     |
| Dry run      | `200` with `status: validated`, `counts` (created, updated, unchanged for categories, items, variants and barcodes); nothing is written, not even the default catalog; no version lock and no audit record, because nothing changes                                                                                                                                                                                                                                                                                                                                                                                              |
| Not applying | `dryRun: false` answered `422 · catalog.import_apply_unavailable` in I1; I2 removed that code and applies the document ("I2 as built")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Errors       | All of them are collected: the document alone first (repeated codes, SKUs and barcodes, two primary barcodes, a barcode off its symbology, a quantity policy that cannot hold), then the catalog (taken or archived codes, SKUs and barcodes of other variants, unknown parents, categories and sales units, cycles, depth, the category limit). `422 · catalog.import_rejected`; `meta.errors` has up to 100 entries with `field` as the path (`items[12].variants[0].sku`); the `ref` of the row is echoed in the `ref` of each of its entries; `meta.total` and `meta.truncated` state the count and whether the list was cut |
| Statements   | Seven set-based reads (catalog, categories, items, variants with their barcodes, SKU holders, barcode holders, units), the same number for 1 row and for 500, plus the tenant context statement                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Idempotency  | `Idempotency-Key` is not read: a dry run changes nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| OpenAPI      | `13.11.0`, additive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### I2 as built: a bulk import document is applied (migration 0115, baseline revision 125)

| Piece           | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Route           | `POST /catalog/imports` with `dryRun: false` answers `201 { data: { importId, status: "applied", counts }, meta: {} }`; `dryRun: true` is unchanged (`200`, no key). `Cache-Control: private, no-store`; classified as a back-office route, not hot, because a manager runs it a few times a day while a catalog is loaded, never during a sale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Idempotency     | `Idempotency-Key` (UUID v4 or v7) is required only when `dryRun` is false; without it the answer is the house `400 · foundation.validation_failed` with `location: header`, `field: idempotency-key`. The request hash is the SHA-256 of the canonical body. The same key and body answer `201` with the stored report and `Idempotent-Replayed: true` and write nothing, also after the catalog moved on; the same key with another body answers `409 · idempotency.key_reused`; a rejected import records nothing, so its key stays free                                                                                                                                                                                                                                                                                                                  |
| Transaction     | One tenant transaction: permission and capability (a refusal leaves one denied audit record), the `catalog_versions` row `FOR UPDATE` first, as every catalog command, then the key lookup, then the state is read again after the lock and judged with the I1 rules (`422 · catalog.import_rejected`, nothing written, recorded or audited), then the plan is written, the import recorded and one audit record left. Two imports that create the same code serialize on the lock: one applies and the other is rejected with `catalog.code_taken`; two requests with the same key give one applied import and one replay; a request that cannot take the lock within the lock timeout (2 s) because another command holds it answers a retryable `503 · service.unavailable` and writes nothing, so `idempotency.in_progress` cannot happen on this route |
| Table           | `catalog.imports (id, organization_id, catalog_id, creation_idempotency_key, request_hash, summary jsonb, created_at)`, unique on the organization and key, tenant policy on the scalar subquery, `SELECT` and `INSERT` for the runtime. It has no `created_by`: the audit record holds the actor, and no other Catalog table references `identity`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Audit           | `catalog.import.applied` on the resource `catalog.import`, one record per import with one change per kind of row (`catalog.import.categories`, `.items`, `.variants`, `.barcodes`: "created n, updated n, unchanged n"), never one per row                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Counts          | Created, updated and unchanged come from comparing the document with the state read after the lock, and the plan writes only what differs: the same document twice leaves the second run all `unchanged`, with no catalog version bump, no change-feed event and no outbox row (it still records an import and its audit record)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Feed and keys   | The writes are the statements the version and change-feed triggers already watch, so an imported item leaves the same rows, version steps, events and search keys as one created through `POST /catalog/items` (`catalog-imports-parity.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Statements      | 33 statements per request counting authentication, the same for 1 item as for 500 (the import itself: tenant context, lock, key lookup, seven reads, fifteen writes, record, audit)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Default catalog | When `catalogId` is omitted the default catalog is created if the organization has none, inside the transaction, so a rejected import leaves no catalog behind                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Removed         | `catalog.import_apply_unavailable` (code, error, tests and OpenAPI)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Proof           | `catalog-imports-apply.e2e-spec.ts`, `catalog-imports-integrity.e2e-spec.ts` (atomic rollback, convergence, concurrency, replay, modes, archived), `catalog-imports-parity.e2e-spec.ts` (parity and 500-item cost), `catalog-import.writes.integration-spec.ts` (a failing statement rolls back what earlier ones wrote), `catalog-import.plan.integration-spec.ts` (plans after 3,000 items) and `PERFORMANCE_BASELINE.md` section 24                                                                                                                                                                                                                                                                                                                                                                                                                      |
| OpenAPI         | `13.12.0`, additive: `201` with `CatalogAppliedImport`, optional `Idempotency-Key`, `409`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

### I4a as built: modifier groups and options in the import (no migration, baseline revision 126)

| Piece        | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document     | `POST /catalog/imports` gains the optional `modifierGroups[{ code, name, description?, ref?, options?[{ code, name, description?, kind?, target?{ itemCode, variantCode }, maxQuantity?, textMaxLength?, prefix?, printsOnReceipt?, printsOnKitchenTicket?, suspended? }] }]`. Groups are matched by code ignoring case, options by code within their group. At most 200 groups, 50 options a group and 3,000 options a request (`400`). The option `code` is required, so a re-run converges                                                                                                                                                                                                                                                                                                                                               |
| Options      | A group that sends `options` describes its whole set, in the order sent (`sortOrder` is the position): an option is written whole and a field left out takes the default of `PUT /catalog/modifier-groups/{modifierGroupId}` (instruction, one unit, no prefix, both print hints on, active; `suspended: true` is inactive). A matched option keeps its id and the spelling of its stored code. An option the group has that is not sent is archived after those sent (never deleted) and one sent again comes back. A group that omits `options` keeps its options; a group the document does not name is untouched. The options a sent list archives are not counted, the same rule as the barcodes a sent list archives in I2: the counts describe the rows the document sends, in the dry run, the apply, the replay and the read alike |
| Group fields | `name` is required and updated; `description` left out keeps the stored one and `null` clears it. Import never changes a status: an archived group answers `catalog.modifier_group_archived` and an inactive one `catalog.modifier_group_not_active`, in create mode an existing code is `catalog.code_taken`, and a refused group does not judge its options again                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Kinds        | `instruction`, `catalog_variant` and `text` with every rule of the manage routes, judged at the field (`catalog.modifier_option_presentation_invalid`), the six prefix words in any case; any other prefix label (1 to 20 characters) carries no rule. A `catalog_variant` option needs `target`, any other kind takes none (`400`); a new target has to exist, be active and belong to a plain item (`catalog.not_found`, `catalog.variant_not_active`, `catalog.option_target_not_plain`), in the catalog or in the document; the kind and the target of an existing option never change (`catalog.modifier_option_target_fixed`)                                                                                                                                                                                                         |
| Cap          | A new group counts toward the 500 groups of the organization, archived ones included, counted org-wide like the create route (`COUNT_GROUPS`); a catalog-wide count is for C25. One error at `modifierGroups`: `catalog.modifier_group_limit_reached`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Race         | The catalog version row is locked `FOR UPDATE` first, as for every catalog command, and an apply reads the target variants `FOR SHARE` in the same statement; composition serializes on the same lock, so the plain-target rule is not made weaker by the import (no database constraint backs it, as for the manage routes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Counts       | `counts.modifierGroups` and `counts.modifierOptions` (created, updated, unchanged) appear in the dry run, the apply, the replay, the read and the audit record only when the document sent `modifierGroups`; the stored summary reader accepts a summary without them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Statements   | A document without groups keeps its seven reads and fifteen writes. With groups, three more reads (groups with their options, the target variants, the organization-wide group count) and four more writes (insert and update groups, insert and update options) run whatever the number of rows: 40 statements per request for 2 groups and for the 200 groups and 3,000 options of the limit (100 options selling a variant), about 2.1 s and 600 change-feed events at the limit, measured                                                                                                                                                                                                                                                                                                                                               |
| Plan         | `catalog-import.modifiers.plan.integration-spec.ts` freezes the statistics of a neighbour of 3,000 groups, 30,000 options and 200 combos, imports the limit and keeps both reads keyed within 20 rows and 10 buffers a group and 4 rows and 12 buffers a target                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| OpenAPI      | `13.12.0` (unreleased), additive: optional `modifierGroups` in the request, optional counts in the answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### I4b as built: item offers in the import (no migration, baseline revision 126)

| Piece      | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document   | An item gains the optional `offers[{ groupCode, minSelections, maxSelections, defaultOptionCodes?, defaultQuantities?, optionLimits?, suspended? }]`, keyed by group code and option code (case-insensitive, never ids), at most 20 an item, a group once per item (`foundation.validation_failed` at `items[i].offers[j].groupCode`). The offers of a variant are sent on the variant (I4c)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Semantics  | An item that sends `offers` replaces its whole item-level list in the order sent (`sort_order` is the position): an offer it has that is not sent is retired, one sent again comes back, `[]` retires all; an item that omits `offers` keeps them. The group has to be active and be of the catalog or of the document (a stored offer of an inactive group may stay, a suspended one may wait)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Rules      | Judged in code space with `judgeOfferList`, the same function as `PUT /catalog/items/{itemId}/modifier-groups`, over the options the group will have on sale after the document: minimum reachable, defaults on sale, once and within `maxSelections`, quantities within the `maxQuantity` of the option and the maximum, limits below the `maxQuantity`. Its refusals keep their codes and move to `items[i].offers[j].<field>` (`catalog.not_found`, `catalog.modifier_group_not_active`, `catalog.selection_rule_invalid`, `catalog.default_options_invalid`, `catalog.default_quantities_invalid`, `catalog.option_limits_invalid`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Cleanup    | An option the import takes out of `active` (I4a path) loses its defaults in every offer (`REMOVE_DEFAULTS_OF_OPTIONS`, the statement of the manage route). I4a did not do this; fixed first, with a mutation proof                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Counts     | `counts.itemOffers` (created, updated, unchanged) in the dry run, the apply, the replay, the read and the audit record only when an item sent `offers`; it counts the offers the document sends, by position: an offer that moved or changed is updated, a retired one that comes back is created, one retired because the list left it out is written but not counted; the stored summary reader accepts a summary without it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Statements | A document without offers is unchanged. With offers, one more read (the offers of the items named, with their defaults and limits, by key) and five more writes (clear defaults and limits of the items whose list changed, retire the offers left out, upsert on `(item_id, modifier_group_id) WHERE item_variant_id IS NULL`, insert defaults, insert limits; I4c adds a sixth, the upsert of the variant scope), whatever the number of rows; only items whose list differs are written. At the cap (100 items of 20 offers: 2,000 offers, 2,000 default rows, 2,000 limit rows, 6,200 change-feed events): 42 statements in the request, as for one offer (43 since I4c adds the variant upsert), 2.2 to 2.3 s on a fresh database and 6.9 s for the newest tenant of a test database with 130 tenants (load average 6 to 7); the difference is the sequential scans of the small identity tables inside `has_active_tenant_context()`, not the size of the outbox. Each of the three inserts costs about 0.4 ms a row (`events.append_tenant_event` once per row through `catalog.record_change_feed`), and a statement over 5 s answers `503`: 4,000 offers took 10 s on a loaded machine and one run hit the statement timeout, so a request holds at most 2,000 offers, 2,000 default rows and 2,000 limit rows (`IMPORT_LIMIT.OFFERS`, `OFFER_DEFAULTS`, `OFFER_LIMITS`), `400` at `items` with one error for each cap exceeded |
| Body       | The caps (2,000 offers, 2,000 default rows, 2,000 limit rows) are reached long before the 1 MiB body ceiling (about 190 bytes an offer with a default and a limit, so about 380 KB at the cap); the ceiling is unchanged                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Plan       | `catalog-import.modifiers.plan.integration-spec.ts` keeps the offers read keyed within 6 rows and 16 buffers an offer after a bulk load with old statistics (measured 1,300 rows, 3,644 buffers for 300 offers)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| OpenAPI    | `13.12.0` (unreleased), additive: optional `offers` on an item, optional `itemOffers` in the counts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### I4c as built: variant offers in the import (no migration, baseline revision 126)

| Piece      | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document   | A variant gains the optional `offers[{ groupCode, minSelections, maxSelections, defaultOptionCodes?, defaultQuantities?, optionLimits?, optedOut? }]`, keyed by group code and option code, at most 20 a variant, a group once per variant (`foundation.validation_failed` at `items[i].variants[j].offers[k].groupCode`); two variants may override the same group. `optedOut` replaces `suspended`                                                                                          |
| Semantics  | As `variantOverrides` of `PUT /catalog/items/{itemId}/modifier-groups`: a variant that sends `offers` replaces its own list in the order sent (an override left out is retired, one sent again comes back), `[]` clears it so the variant follows the offers of its item again, a variant that omits `offers` keeps its overrides. The offers of the item and of its other variants are never touched. An override does not depend on the item having the offer, as in the offer route        |
| Opt out    | An override with `optedOut: true` drops the group from the variant even when the item offers it. Its rule, defaults and limits are ignored and stored as the offer route stores them (`inactive`, 0 to 1, no defaults, no limits, `withheldOf`), and are not judged                                                                                                                                                                                                                           |
| Rules      | The same `judgeOfferList` over the options the group will have on sale after the document, against the overrides the variant already has (not the offers of the item); the group has to be active unless the override is already stored or opted out. Refusals keep the codes of I4b and point at `items[i].variants[j].offers[k].<field>`. An archived variant is refused by its own code (`catalog.variant_archived` at `items[i].variants[j].code`) and its overrides are not judged again |
| Cleanup    | An option an import takes out of `active` loses its defaults in every offer, variant overrides included (the same statement as I4b, proven for the variant scope)                                                                                                                                                                                                                                                                                                                             |
| Counts     | `counts.variantOffers` (created, updated, unchanged) next to `itemOffers`, only when a variant sent `offers`, with the convention of I4b; the stored summary reader accepts a summary without it, and the audit record gains `catalog.import.variantOffers`                                                                                                                                                                                                                                   |
| Statements | The read of I4b also returns the overrides of the variants named, by `(item, variant)` key, in the same statement. The writes of I4b take lists of an item or of a variant (clear, retire, defaults, limits), plus a second upsert on `(item_variant_id, modifier_group_id) WHERE item_variant_id IS NOT NULL`: 43 statements in the request at the cap and for two offers, whatever the placement                                                                                            |
| Cap        | Offers of items and of variants share the caps of I4b: at most 2,000 offers, 2,000 default rows and 2,000 limit rows in all of them together (`400` at `items`, one error for each cap exceeded). No constant was raised. At the cap the change feed holds 6,200 events when all sit on items, 6,300 on variants (the extra 100 are the second variant of each item) and 6,250 split, and the wall time was 2.3 to 3.1 s on a fresh database (load average 24 to 32)                          |
| OpenAPI    | `13.12.0` (unreleased), additive: optional `offers` on a variant, optional `variantOffers` in the counts, the description of the caps                                                                                                                                                                                                                                                                                                                                                         |

### CL1 as built: the catalog clone function and the feed rule (migrations 0116 and 0119, baseline revision 128)

| Piece                 | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Function              | `catalog.clone_catalog(source, code, name, creation_key, request_hash) returns jsonb`, INVOKER, so it runs under row level security with the runtime role; `EXECUTE` only for `ninaku_runtime`. Requires READ COMMITTED (`0A000 catalog_clone_isolation`). It returns `{ catalogId, replayed, counts, skippedAssets }`, `counts` by table name. The code is required here: the slug of the name is the application's job (CL2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Order                 | Tenant check, cheap argument checks, then `catalog_versions FOR UPDATE` first (the house lock order, proved by `catalog-lock-order.e2e-spec.ts` and `catalog-clone.concurrency.integration-spec.ts`), replay lookup, source `FOR SHARE`, the cap, the new `catalogs` row, one `INSERT ... SELECT` per table in dependency order, a check that the rows written equal the rows counted before. The hierarchy advisory locks come after, from the category and bundle triggers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Tables                | 24: the 23 tables with `catalog_id` (all but `business_unit_catalogs`, `business_unit_items` and `imports`) and `item_assets` through its item. `database/tests`-free guard: `catalog-clone.drift.integration-spec.ts` walks `information_schema` and the foreign keys from items, categories, menus, modifier groups and variants and fails when a table is neither cloned nor excluded with a reason, or a column of a cloned table is not copied, remapped, regenerated or excluded (`test/support/catalog-clone-coverage.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| New ids               | `uuidv7()` kept in arrays of the function and joined with `unnest(old, new)`; no temp table. `ninaku_runtime` has no `TEMPORARY` privilege and none was granted. Measured against the temp table of the spike on the same data and database, the two are the same within noise (below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Trees                 | Categories and menu sections go in one statement each with their parents already mapped. The cycle triggers accept it: they read the rows the statement has inserted so far, and a copy of an acyclic tree cannot cycle. The two-pass variant measured the same time and wrote 2 more statements, 2 more version moves and 97 more events                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Images                | Copied by reference (same asset) only when the asset is `ready`, not archived and an image; the assets are locked `FOR SHARE`; the ones skipped are returned as `skippedAssets`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Not copied            | Creation keys and hashes (left null), the generated search keys, timestamps (new), assignments, listings, outlet menus, prices, translations and the allergen, dietary and nutrition tables (no write path yet), other modules' references                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| New catalog           | Always `active`, `access_mode = assigned`, not the default, no assignments; `cloned_from_catalog_id`, `creation_idempotency_key`, `creation_request_hash` and `clone_summary` (the counts, for the replay) on its row; unique key per organization                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Errors                | Named by `CONSTRAINT`: `P0002 catalog_clone_source_not_found` (also another organization's catalog), `54000 catalog_clone_too_large` (more than 1,200 items, archived ones included, `DETAIL items=N limit=1200`), `23514 catalog_clone_code_reserved` (`default` in any case), `22023 catalog_clone_code_invalid`, `catalog_clone_name_invalid`, `catalog_clone_key_invalid`, `23505 catalogs_code_uq` (code taken, ignoring case, no suffix added), `23505 catalog_clone_key_reused` (same key, other hash), `0A000 catalog_clone_isolation`, `55000 catalog_clone_version_missing` and `XX000 catalog_clone_count_mismatch` (neither is expected)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Replay                | The same key and hash returns the stored counts with `replayed: true` and writes nothing; two concurrent clones with one key make one catalog                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Audit seed            | Resource `catalog.catalog` and action `catalog.catalog.cloned` (written by the application in CL2, counts only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Feed rule (0118)      | `catalog.record_change_feed` writes events only for rows whose catalog has an active assignment to a business unit (`business_unit_catalogs.status = 'active'`), from the data and without a setting the caller can change. A statement in an organization with no active assignment returns before building any SQL; `item_assets` follows its item; `catalogs`, `business_unit_catalogs`, `business_unit_items` and `outlet_*` rows always write events (a clone announces its birth with one `catalog.listing.changed`, and the assignment announces the catalog). The catalog version moves as before. Changes to an unassigned catalog are dropped, not deferred (owner decision: the consumer re-reads the whole catalog when it learns of the assignment, by the `cut` and the version, D41). The images of an item the statement can no longer find (a cascade) are announced: the filter fails open, never closed; no code path deletes items (the runtime has no `DELETE` on `catalog.items`), so the case only arises from an administrator's cascade. The tests that prove the rule: `catalog-clone.feed.integration-spec.ts` (an unassigned catalog emits nothing, an assigned one emits, nothing again once the assignment is inactive, one statement over both catalogs, the catalog row and its assignment always emit, the images follow their item, an item that cannot be found still announces) and the feed-scope drift test in `catalog-clone.drift.integration-spec.ts` (every table wired to the trigger has a `catalog_id` or is named by the function). A consumer that learns of an assignment has to read the whole catalog, because the draft's rows were never announced |
| Measured              | Clone of a catalog that nobody sells from, feed rule on, ninaku\_runtime under RLS, five runs each after one warm-up: 300 items 0.45 to 0.52 s, 1,200 items (the cap) 1.44 to 1.64 s, at load average 3.6 to 4.3; 1 event and 25 version moves each time; WAL about 3.2 MB and 11.7 to 12.5 MB. Earlier runs at load 6 to 8 gave 1.9 to 2.5 s at 1,500 items. The spike's numbers with the feed on, same data: 1.4 s and 6.2 s (300 and 1,180 items)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Cap                   | 1,200 items (owner decision; 1,500 was the first proposal). The function holds the version row from its first statement to the commit, under 2 s at the cap, so another catalog writer or an admission waiting longer than `DATABASE_LOCK_TIMEOUT_MS` (2,000 ms) gets the retryable `503`; the route has to issue `SET LOCAL statement_timeout` as its own statement before the call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Parity                | A database upgraded from revision 126 and a fresh revision 128 give an identical `pg_dump -s` (158,448 lines), the same audit seeds and the same grant; the manifest hashes are recomputed for every canonical file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Not run by the author | `database/tests/contracts` run on `ninaku_ci`, which this work never touches; the same checks live in the integration specs above and `db:test` is the integrator's                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### CL2 as built: the route that clones a catalog (migration 0116, baseline revision 130)

| Piece                 | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Route                 | `POST /catalog/catalogs/{catalogId}/clones`, body `{code?, name}`, header `Idempotency-Key` required (UUID), `201` with `{catalogId, code, name, status: active, clonedFrom: {catalogId}, counts, assignedBusinessUnits: 0, isDraft: true}`. A thin controller, one use case (`CloneCatalogUseCase`), one port (`CatalogCloneRepositoryPort`) and one adapter that calls `catalog.clone_catalog` as the caller, under RLS, READ COMMITTED, in one transaction                                                                                                                                                                                                                      |
| Body                  | `name` trimmed, 1 to 200 characters, no NUL; `code` optional, lowercase `[a-z0-9-]` up to 80 characters; left out it is derived from the name in the domain function `catalogCodeOf` (accents dropped, other characters become single dashes); a name that gives no code and no code sent is `400` at the field `name`. A taken code (ignoring case) is `409 catalog.code_taken` and no suffix is ever added; `default` is `422 catalog.clone_code_reserved`                                                                                                                                                                                                                       |
| Idempotency           | The function owns it (creation key and request hash on the new catalog). The hash is the fingerprint of `{catalogId, code or null, name}`. The same key and hash answer the same `201` with `Idempotent-Replayed: true` and write nothing, audit included; another body is `409 idempotency.key_reused`; two concurrent requests with one key make one catalog                                                                                                                                                                                                                                                                                                                     |
| Statement timeout     | `set_config('statement_timeout', '10000', true)` as its own statement before the call, because a `SET LOCAL` inside the function does not re-arm the timer; it lasts for that transaction only and no global timeout changes. 10 s is four times the worst measured time of the cap (2.5 s at load 6 to 8); the route measured 1,475 ms at the cap with load average 20                                                                                                                                                                                                                                                                                                            |
| Refusals              | `404 catalog.not_found` (also another organization's catalog), `422 catalog.clone_too_large` (the detail names the items and the 1,200 limit, which lives in one constant, `CATALOG_CLONE_ITEM_LIMIT`), `422 catalog.clone_code_reserved`, `422 catalog.clone_code_invalid`, `422 catalog.clone_name_invalid`, `409 catalog.code_taken`, `409 idempotency.key_reused`, `503 service.unavailable` with `Retry-After` when the lock timeout runs out (nothing written; send the same key again). `catalog_clone_version_missing`, `catalog_clone_count_mismatch`, `catalog_clone_isolation` and `catalog_clone_key_invalid` mean a defect or a broken setup and stay a generic `500` |
| Permission            | New permission `catalog.catalogs.manage` (migration `0116`), granted to `organization_owner` and `manager` and checked organization-wide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Capability            | New capability `catalog.multiple_catalogs` (migration `0116`, scope global). It is an add-on, not part of any plan version: Catalog only checks it, and Platform operations activate it for an organization with an `allow` (`grant`) row of `platform.organization_capability_overrides`. An organization without it is refused with `403 platform.capability_not_entitled`. No plan version was published and none was touched                                                                                                                                                                                                                                                   |
| Audit                 | `catalog.catalog.cloned`, target kind `catalog.catalog` = the new catalog, one record with the counts of the rows copied (`catalog.clone.<table>`), written by the use case in the same transaction and never on a replay. A refusal (permission or add-on) leaves one denied record whose target is the source catalog                                                                                                                                                                                                                                                                                                                                                            |
| Cap                   | 1,200 items of the source, archived ones included; one over is refused before anything is written                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Not measured          | The route is administrative and is not in `perf:http`; its classification and the measurement are in `PERFORMANCE_BASELINE.md` section 25                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Owner decision        | Accepted by the owner: the cap stays in the `detail` of `catalog.clone_too_large` and `meta` is not extended. `meta` carries only `errors`, `total` and `truncated`, and a generic `limit` field would change the Foundation problem schema                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Not run by the author | `database/tests/contracts` (they need `ninaku_ci`), the full suites and `npm run verify`; the integrator runs them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### CA1 as built: the database rules of additional catalogs (migration 0116, baseline revisions 131 and 132)

| Piece                 | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One active catalog    | Partial unique index `business_unit_catalogs_one_active_uq (organization_id, business_unit_id) WHERE status = 'active'`. A unit may keep any number of resting rows, one per catalog, and moving between catalogs is: the current row rests, the target row is reactivated or inserted. A row never changes catalog (the existing guard) and the rows of the old catalog keep their stored mode and their `business_unit_items`, so a switch back finds them          |
| Active catalog needed | `business_unit_catalogs_active_catalog_trg` refuses an active assignment, on insert or on update of the status, to a catalog that is not active (`23514 business_unit_catalog_requires_active_catalog`), taking the catalog row `FOR SHARE`                                                                                                                                                                                                                           |
| Status guard          | `catalogs_status_guard_trg` refuses leaving active when the catalog is the default (`23514 catalog_default_status_locked`) or has an active assignment (`23514 catalog_in_use`). It runs after the row lock of the update, so it serializes with a concurrent assignment; the application still takes the version row first                                                                                                                                           |
| Identity              | `catalogs_clone_provenance_chk` is now `(cloned_from_catalog_id IS NULL) = (clone_summary IS NULL)`, so a created catalog may hold a creation key and hash without a source. `catalogs_code_pattern_chk` equals the pattern of the clone function (letters, digits, dot, underscore and dash, 1 to 80, starting with a letter or digit); lowercase is an API rule and the unique index already ignores case                                                           |
| Audit seeds           | `catalog.catalog.created`, `.renamed`, `.deactivated`, `.reactivated`, `.archived`, `.restored` and `catalog.assignment.changed`                                                                                                                                                                                                                                                                                                                                      |
| Mode none             | `assortment_mode` accepts `none`. The unit always has one active row; `none` is its mode, so the unit stays assigned to its catalog while selling nothing. `variant_is_listed` and `listed_items` list nothing for `none`. The SQL of `assortmentModeAt` and `listedAt` already returned the stored mode and treated anything but `all` and `selected` as not listed, so it did not change                                                                            |
| Data migration        | The resting row of the default catalog of a unit that has no active row becomes an active `none` row, in one statement, with the version trigger of the table disabled around it (the migration changes no sale, so no till reopens). On a scratch database of 500 organizations and 2,000 units (1,000 resting default rows) it moved exactly those 1,000 rows in 3.8 s with the whole upgrade, left the 500 resting rows of other catalogs alone and wrote no event |
| New units             | `materialize_default_assortment` stores `active all` as before when the unit sells everything and `active none` where it used to store an inactive row                                                                                                                                                                                                                                                                                                                |
| Change feed           | `record_change_feed` treats a catalog as assigned only while an assignment is active and not `none`, so the catalogs nobody sells from still write no event (the rule of CL1 and 0118)                                                                                                                                                                                                                                                                                |
| Domain                | `storedModeOf(mode)` stores every mode, `none` included, as an active row; `assortmentModeOf` still reads an inactive row as `none`                                                                                                                                                                                                                                                                                                                                   |
| Not run by the author | `database/tests/contracts` (they need `ninaku_ci`) and the full suites; their equivalents are the integration specs under `infrastructure/catalogs` and the case-matrix rows of C25                                                                                                                                                                                                                                                                                   |

### CA2 as built: the registry of catalogs (migration 0116, baseline revision 133)

| Piece                 | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Routes                | `GET /catalog/catalogs`, `POST /catalog/catalogs`, `GET /catalog/catalogs/{catalogId}`, `PATCH /catalog/catalogs/{catalogId}` and `POST /catalog/catalogs/{catalogId}/transitions`, in the feature folder `catalogs` of every layer (`CatalogRegistryController`, one use case per command, `CatalogRegistryRepositoryPort` and its adapter)                                                                                                                                                                                                                                                                                                                                                                       |
| Who may               | Reads need `catalog.items.view` organization-wide and never the add-on. Every write needs `catalog.catalogs.manage` organization-wide. Only create (and the clone) needs the add-on `catalog.multiple_catalogs`: rename and transitions work after the add-on lapses, and so does reading, so the default catalog and every catalog that exists keep working. A refused write leaves one denied audit record                                                                                                                                                                                                                                                                                                       |
| List                  | Keyset by the generated column `catalogs.name_search_key` (the name without case or accents, collation `C`) and the id, 50 by default and 100 at most, every status unless `status` names one; the cursor is bound to the route, the organization and the status. Each entry is `{catalogId, code, name, isDefault, status, isDraft, businessUnitCount}`; `isDraft` is derived (no business unit sells from it). Not tagged. The page is read through `catalogs_name_keyset_idx (organization_id, name_search_key, id)`: the keyset condition is an index condition because it names a stored column, not `lower(name)`, which sits behind the row level security qual                                             |
| Read                  | The same fields plus `businessUnitIds` (sorted), a strong ETag over exactly that content and `304` on `If-None-Match`; a catalog of another organization is `404 catalog.not_found`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Create                | `{code?, name}` with the rules of the clone (name 1 to 200 trimmed, lowercase code derived from the name when left out, `409 catalog.code_taken` and no suffix, reserved `default` is `422 catalog.code_reserved`), `Idempotency-Key` required, `201` with the lean entry and the ETag the read gives, replay with `Idempotent-Replayed`, `409 idempotency.key_reused` for another body, audit `catalog.catalog.created` with the code and the name as after values and none on a replay. The creation key is shared with the clone: a key a clone used is refused as reused. The version row is locked first, so two requests with one key make one catalog and the other answers the replay                      |
| Rename                | `PATCH {name}`, optional `If-Match` (`412`), nothing written and nothing audited when the name is the stored one, `422 catalog.catalog_archived` for an archived catalog, audit `catalog.catalog.renamed` with the name before and after                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Transitions           | `POST {transition: deactivate\|reactivate\|archive\|restore}`, no Idempotency-Key (state based, repeating one already in effect answers `200` and writes nothing), optional `If-Match`. The lifecycle is the one of the items with no step gated by the plan; restore lands on inactive. The default catalog never leaves active (`422 catalog.default_catalog_locked`) and a catalog a business unit sells from cannot be deactivated or archived (`422 catalog.catalog_in_use`); the database triggers of CA1 are the backstop, and the adapter maps their constraint names to the same errors. Audit `catalog.catalog.deactivated`, `.reactivated`, `.archived` or `.restored` with the status before and after |
| Statements            | List 7, read 7, create 11, rename 11 and status 12, with 2 catalogs or with 43 (`catalog-registry-statement-budget.e2e-spec.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Plan and time         | `catalog-registry.plan.integration-spec.ts` pages 1,500 catalogs on statistics frozen before they existed: the first, a middle and a backward page read 51 rows of `catalogs` through the index, and the units are counted by one aggregate of the active assignments of the organization, never more rows than the organization has units. At the route, with 201 catalogs, the list and the read answer in about 1 ms at p50 and 2 ms at p99 with one client, and 5 and 11 ms with 16 (`PERFORMANCE_BASELINE.md` section 26)                                                                                                                                                                                     |
| Not run by the author | `database/tests/contracts` (they need `ninaku_ci`) and the full suites                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### CA3 as built: the catalog a business unit sells from (migration 0116, baseline revision 135)

| Piece | As built |
| ----- | -------- |
| Routes | `GET /catalog/business-units/{businessUnitId}/catalog`, `PUT` the same path and `GET .../catalog/history`, in the feature folder `assignments` of every layer |
| Who may | Reads need `catalog.items.view` organization-wide. The `PUT` needs `catalog.catalogs.manage` organization-wide and never the add-on (the add-on only gates creating and cloning catalogs); a refusal leaves one denied audit record |
| Read | `{businessUnitId, catalogId, code, name, isDefault, status, assortmentMode, itemCount, listedCount, assignedAt}` with a strong ETag over exactly that content and `304` on `If-None-Match`; a unit that sells from nothing, or a unit of another organization, is `404` |
| Switch | `PUT {catalogId, assortmentMode?}` with `If-Match` required (`428`, `412`): after the version row the old assignment goes inactive and the new one is the one active assignment of the unit (the partial unique index of CA1 holds), in one transaction. The mode stored for that catalog is kept when `assortmentMode` is absent (`all` the first time). The same catalog and mode answers `200` and writes nothing. An inactive or archived catalog is `422 catalog.catalog_not_active`. No `Idempotency-Key`: repeating the call is already in effect. `Validate-Only` works. One `catalog.assignment.changed` record keeps the catalog and the mode before and after |
| History | `catalog.business_unit_catalog_periods` (migration 0116): one row per period a catalog was the one active assignment of a unit, `startedAt` and `endedAt` (null while open), one open period per unit by a partial unique index, kept by a trigger on the status of `business_unit_catalogs` and filled from the assignments that existed. The list is keyset (newest first, 50 by default and 100 at most), the cursor bound to the route, the organization and the unit |
| Reads that follow the unit | The assortment (mode, listings, curation), the listed filter and the sellable rule of the till now use the catalog the unit sells from instead of the default one (`unitCatalogOf`, a scalar subquery with the default catalog as fallback for a unit with no assignment). Items of another catalog cannot be listed at the unit (`404`) and each catalog keeps its own mode and listings for the unit |
| Collection routes | They take `catalogId` since CA4, see "CA4 as built" |
| Statements | Read 8, switch 14, already in effect 10, history 8 |

```http
PUT /api/v1/catalog/business-units/01a1e26a-e3e0-7000-8000-0000000000b1/catalog
If-Match: "7d2a90c3f4"
{ "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c1", "assortmentMode": "selected" }
```

```json
{ "data": { "businessUnitId": "01a1e26a-e3e0-7000-8000-0000000000b1", "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c1",
            "code": "summer-2027", "name": "Summer 2027", "isDefault": false, "status": "active", "assortmentMode": "selected",
            "itemCount": 1180, "listedCount": 0, "assignedAt": "2026-11-16T12:30:41.120552Z" }, "meta": {} }
```

```json
{ "data": [
    { "periodId": "01a1e26a-e3e2-7000-8000-0000000000d2", "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c1", "code": "summer-2027", "name": "Summer 2027",
      "startedAt": "2026-11-16T12:30:41.120552Z", "endedAt": null },
    { "periodId": "01a1e26a-e3e2-7000-8000-0000000000d1", "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c0", "code": "default", "name": "Default catalog",
      "startedAt": "2026-10-01T09:00:00.000000Z", "endedAt": "2026-11-16T12:30:41.120552Z" } ],
  "meta": { "pageInfo": { "hasNextPage": false, "endCursor": null } } }
```

### CA4 as built: every collection read and every create names its catalog (no migration beyond 0116, baseline revision 136)

| Piece | As built |
| ----- | -------- |
| Reads | `catalogId` (query, optional) on `GET /catalog/items`, `GET /catalog/workspace`, `GET /catalog/variant-dimensions` and `GET /catalog/barcode-matches`, next to the lists of categories, brands, modifier groups and menus that already took it. Absent means the default catalog, as before (one rule for every read, the barcode search included: it looks in the default catalog only, and `409 catalog.barcode_ambiguous` is left for a value two active barcodes hold inside the one catalog searched, which the unique index prevents); an id the organization does not have is `404 catalog.not_found`, a malformed one `400`. The cursor of the item list is bound to the catalog, so a cursor of one catalog sent to another is `400`; the `endCursor` of the workspace continues in `GET /catalog/items?catalogId=` of the same catalog |
| Creates | `catalogId` (body, optional, same meaning) on `POST /catalog/items`, `/categories`, `/modifier-groups`, `/product-brands` and `/menus`. It enters the Idempotency-Key fingerprint, so one key reused for another catalog is `409`. Codes and names are unique within a catalog, so the same item code, menu code or brand name may live in two catalogs |
| Caps | The limits of categories (500), modifier groups (500), menus (100) and brands (1,000) are counted within the catalog (`catalog.*_limit_reached`), never within the organization; `GET /catalog/metadata` says so in `limits.catalog.countedPer: "catalog"`. There is no cap on items and no count limit on catalogs |
| Writes by id | Routes that name an existing record (edit, move, classify, offer, menu structure) work in the catalog of that record: a category parent, a category of an item, a group offered on an item, a variant behind an option, an item on a menu and a barcode value are all checked inside that catalog, and something of another catalog is `404` (or `422 catalog.menu_item_unavailable` on a menu) |
| Catalog states | A write that names a catalog needs it to be `active` or `inactive` (a draft being prepared): an `archived` catalog is `422 catalog.catalog_archived` with `meta.errors[0].field = "catalogId"`, for every create and for the import (dry run and apply). Reads of an archived catalog stay open. Migration `0122` defines the final `catalog.assign_catalog_id`, relaxed: it used to refuse any child row of a catalog that was not active |
| Found on the way | The check "this barcode is active on another variant" was organization wide, so a code used by an item of one catalog could not be added to a variant of another; it is now inside the catalog of the variant, like the unique index |
| Plans | `LIST_VARIANT_DIMENSIONS` keeps one scalar subquery for the catalog (`(SELECT COALESCE($2::uuid, default))`): the two-InitPlan form read 10,522 buffers against the 10,000 of the plan budget, the scalar form is inside it |
| Not run by the author | `database/tests/contracts` (they need `ninaku_ci`) and the full suites |

### Multiple catalogs, step by step

The add-on `catalog.multiple_catalogs` (Platform) lets an organization create and clone catalogs; everything else keeps working without it. The default catalog always exists and is where every call without `catalogId` goes.

1. Create a draft catalog (needs the add-on and `catalog.catalogs.manage`).

```http
POST /api/v1/catalog/catalogs
Idempotency-Key: 01a1e26a-e3e3-7000-8000-0000000000a1
{ "name": "Summer 2027" }
```

```json
{ "data": { "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c1", "code": "summer-2027", "name": "Summer 2027",
            "isDefault": false, "status": "active", "isDraft": true, "businessUnitCount": 0 }, "meta": {} }
```

2. Or clone one (the default, here) with everything in it, up to 1,200 items.

```http
POST /api/v1/catalog/catalogs/01a1e26a-e3e1-7000-8000-0000000000c0/clones
Idempotency-Key: 01a1e26a-e3e3-7000-8000-0000000000a2
{ "name": "Winter 2027" }
```

```json
{ "data": { "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c2", "code": "winter-2027", "name": "Winter 2027", "status": "active",
            "clonedFrom": { "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c0" },
            "counts": { "items": 1180, "itemVariants": 1240, "menuEntries": 96 }, "assignedBusinessUnits": 0, "isDraft": true }, "meta": {} }
```

3. Prepare it: every write names the catalog.

```http
POST /api/v1/catalog/items
Idempotency-Key: 01a1e26a-e3e3-7000-8000-0000000000a3
{ "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c2", "name": "Pumpkin soup", "defaultVariant": { "sku": "SOUP-PUMPKIN" } }
```

```http
GET /api/v1/catalog/items?catalogId=01a1e26a-e3e1-7000-8000-0000000000c2&q=pumpkin
GET /api/v1/catalog/workspace?catalogId=01a1e26a-e3e1-7000-8000-0000000000c2
```

An archived catalog refuses these writes:

```json
{ "status": 422, "code": "catalog.catalog_archived", "title": "Catalog archived",
  "meta": { "errors": [ { "location": "body", "field": "catalogId", "code": "catalog.catalog_archived",
    "message": "An archived catalog cannot receive writes; restore it with POST /catalog/catalogs/{catalogId}/transitions, or name another catalog." } ], "total": 1, "truncated": false } }
```

4. Assign it to a business unit, switching the unit from the one it sells from (needs `If-Match` of the current assignment).

```http
PUT /api/v1/catalog/business-units/01a1e26a-e3e0-7000-8000-0000000000b1/catalog
If-Match: "7d2a90c3f4"
{ "catalogId": "01a1e26a-e3e1-7000-8000-0000000000c2", "assortmentMode": "all" }
```

The answer is the one of `GET .../catalog`, with the new strong tag; the catalog the unit left becomes free to be deactivated, and `GET .../catalog/history` lists both periods. A switch back keeps the mode stored for that catalog, and the old outlet menus stay dormant.

### Lessons of the multiple catalog work (CA1 to CA5)

* A rule that says "of the organization" in a query is a defect once there are two catalogs: every count, uniqueness pre-check and lookup has to be asked what its catalog is. The barcode check and the limits were organization wide until CA4 found them.
* Keep the catalog out of the identity of the thing: routes by id work in the catalog of the record, and only collections and creates need `catalogId`.
* Test the isolation with a second catalog that contains the same data (a clone), not with an empty one: an empty catalog hides an organization-wide query.
* One scalar subquery for "the catalog of this call" keeps the plan of the till and of the reads; a `COALESCE` of two subqueries changed two plans.

### S6a as built: the import is two routes (OpenAPI 14.0.0)

| Piece | As built |
| ----- | -------- |
| Validate | `POST /catalog/import-validations` judges the document and writes nothing; `200` with the counts, never an `Idempotency-Key`, `422 catalog.import_rejected` with the errors of the document. It is the dry run of the old route |
| Apply | `POST /catalog/imports` applies the document, all or nothing: `Idempotency-Key` required, `201` with `{importId, status: "applied", counts}`, `Idempotent-Replayed` on a replay, `409 idempotency.key_reused` for another body, `503` while another command holds the catalog |
| Breaking change | The body has no `dryRun` any more and an unknown field is `400`, so the old flag is refused on both routes. The route decides what happens, not a flag a client can forget. The document, its limits and its rules are the same on both routes (one schema, one rule set) |
| Catalog | `catalogId` in the document names the target; an archived one is `422 catalog.catalog_archived` on both routes |
| Not run by the author | `database/tests/contracts` and the full suites |

```http
POST /api/v1/catalog/import-validations
{ "mode": "upsert", "items": [ { "code": "soup-pumpkin", "name": "Pumpkin soup", "variants": [ { "code": "default", "salesUnitCode": "unit" } ] } ] }
```

```json
{ "data": { "status": "validated", "counts": { "items": { "created": 1, "updated": 0, "unchanged": 0 } } }, "meta": {} }
```

```http
POST /api/v1/catalog/imports
Idempotency-Key: 01a1e26a-e3e3-7000-8000-0000000000a4
{ "mode": "upsert", "items": [ { "code": "soup-pumpkin", "name": "Pumpkin soup", "variants": [ { "code": "default", "salesUnitCode": "unit" } ] } ] }
```

```json
{ "data": { "importId": "01a1e26a-e3e4-7000-8000-0000000000e1", "status": "applied", "counts": { "items": { "created": 1, "updated": 0, "unchanged": 0 } } }, "meta": {} }
```

### S6b as built: the export of a catalog (no migration)

| Piece | As built |
| ----- | -------- |
| Route | `GET /catalog/exports?format=csv\|xlsx&entity=items\|categories&status=active\|inactive\|any&categoryId=&catalogId=`; needs `catalog.items.view` organization-wide and never the plan; records nothing, no ETag; `Cache-Control: private, no-store`; `Content-Disposition: attachment; filename="items-<catalog code>.csv"` (`catalog-<code>.xlsx` for the workbook). An unknown catalog is `404 catalog.not_found`, an archived one can be exported |
| Columns | The fields of the import document named by their path in it: `item.code, item.name, item.categoryCodes, variant.code, variant.name, variant.sku, variant.salesUnitCode, variant.minimumSalesQuantity, variant.maximumSalesQuantity, variant.salesQuantityStep, variant.barcodes` (one row for each variant, the item repeated) and `category.code, category.name, category.parentCode`. Lists use `\|`; `variant.barcodes` is `value:symbology:primary` entries (`primary` 1 or 0, the characters `%`, `:` and `\|` of a value written `%25`, `%3A`, `%7C`). Modifier groups and offers are not exported, and a catalog has no per-locale columns because there are no translations yet |
| CSV | RFC 4180 UTF-8, one table for each request, streamed in pages of 500 items, each page one short read-only transaction with one statement, so memory is bounded by a page and no connection is held while a slow client reads. A cell that starts with `=`, `+`, `-` or `@` (or a tab or carriage return) gets a leading apostrophe so a spreadsheet never runs it; a tool that rebuilds the import document strips it |
| XLSX | One workbook with the sheets `categories` and `items`, every value an inline string, written without a dependency (a minimal OOXML package in `application/exports/xlsx-writer.ts` with `node:zlib`); built in memory, which the row cap bounds |
| Filters and cap | `status` (archived records are never exported: an import never restores them), `categoryId` (items only) and `catalogId`; more than 50,000 variant rows is `422 catalog.export_too_large` before a byte is sent, and `GET /catalog/metadata` exposes the cap and the page size in `limits.exports` |
| Consistency | The pages are read one after the other, keyed by the lowercase item code (`lower(code) > last`, an index condition of `catalog_items_code_ci_uq`), so an export during a change is not one instant of the catalog: export again to be sure. A failure after the first byte ends the stream early |
| Round trip | The CSV of 1,100 items with two variants each (2,200 rows, names with commas, quotes and line breaks, barcodes holding `:`, `\|` and `%`) rebuilt as an import document and sent to `POST /catalog/import-validations` is judged entirely unchanged: items, categories, variants and barcodes created 0, updated 0 |
| Measured | 2,200 rows: 254,271 bytes of CSV in 40 to 46 ms through the route, 111,700 bytes of XLSX; 24 statements (admission and count, then four short transactions for the pages); a page of 500 items reads 1,500 rows and 6,633 buffers in 7 ms on the plan, constant for the middle and the last page (`catalog-export.plan.integration-spec.ts`) |
| Not run by the author | `database/tests/contracts` and the full suites |

```http
GET /api/v1/catalog/exports?format=csv&entity=items&status=active
```

```text
item.code,item.name,item.categoryCodes,variant.code,variant.name,variant.sku,variant.salesUnitCode,variant.minimumSalesQuantity,variant.maximumSalesQuantity,variant.salesQuantityStep,variant.barcodes
soup-pumpkin,Pumpkin soup,dishes|soups,default,,SOUP-1,unit,1,,1,7750182002363:ean13:1
```

### S8 as built: the history of a record and its restore (migration 0123, baseline revision 137)

| Piece | As built |
| ----- | -------- |
| Why a table of its own | The audit trail keeps before and after values only for some fields, records an import or a clone as counts and not row by row, lives in the Audit schema under its retention, and has no read contract for Catalog. A restore needs the exact stored fields of a version, so Catalog keeps `catalog.entity_revisions` itself |
| Table | `entity_revisions(id, organization_id, catalog_id, entity_kind, entity_id, version, operation, snapshot jsonb, changed_fields text[], actor_identity_id, membership_id, changed_at)`, a unique index `(entity_kind, entity_id, version)`, the tenant row policy, grants `SELECT, INSERT, DELETE` for the runtime, no version trigger of its own and not copied by a clone. `operation` is `created`, `updated`, or `baseline` for the state a row had before its first revision |
| Written by | Statement triggers with transition tables, two for each of `items`, `categories`, `product_brands` and `modifier_groups` (`AFTER INSERT` and `AFTER UPDATE`, not `UPDATE OF`): one statement writes one revision for each row it inserted or changed, set-based, so an import, a clone, a bulk SQL change and an API edit are all covered. An update that leaves the core fields as they were writes nothing; the first change of a row with no revision writes its previous state as the baseline first. The actor is `app.actor_identity_id` of the session when there is one |
| Retention | The last 50 revisions of a record are kept (`REVISIONS_KEPT`, exposed as `limits.revisions.kept`). The statement that writes the newest deletes the older ones of the rows it touched through the unique index, so there is no job and no wide lock: only the rows of the same entities |
| Core fields | `code`, `name`, `description` and `status` of every kind; `fulfillment` and `product_brand_id` of an item; `parent_category_id` and `sort_order` of a category. Restorable: every one of them except `status`. Not versioned, never touched by a restore: variants, barcodes, images, the categories of an item, options and offers of a group, bundles, menus, translations |
| Routes | `GET /catalog/{entity}/{entityId}/history` (keyset, newest first, `version`, `operation`, `changedAt`, `actorIdentityId`, `changedFields`), `GET .../history/{version}` (the same plus `snapshot`) and `POST .../restore {version}`; `entity` is `items`, `categories`, `product-brands` or `modifier-groups`. Reads need `catalog.items.view` organization-wide; the restore needs `catalog.items.manage` and the plan |
| Restore | `If-Match` with the strong tag of the record (`428`, `412`), `Validate-Only` supported, answer `{id, outcome: change\|already_in_effect, changed, etag}` with the tag also in the header. It is an ordinary edit: the version row first, the record locked, the same repository writes as the edit routes, one audit record of the record's own update action (`catalog.product_brand.renamed` for a brand) naming the fields that came back, and one new revision for each column group written (an item restore that changes profile and brand writes two). A version equal to what the record holds is `already_in_effect` and writes, audits and bumps nothing |
| Refusals | `404 catalog.not_found` (record of another organization, unknown version), `410 catalog.revision_pruned` (older than the last 50), `422 catalog.restore_target_archived`, `409 catalog.restore_conflict` with `meta.errors` naming the colliding field (`code`, or `name` for a brand) when another record uses it now, `422 catalog.product_brand_archived` and `404` for a brand or parent that is gone |
| Trigger overhead | Measured on a scratch database with the eight triggers disabled and enabled, two runs each: an import of 500 items 408 and 487 ms off against 398 and 500 ms on, 33 statements both ways; a rename of 200 items by import 66 and 233 ms off against 87 and 209 ms on; a clone of 1,200 items 1,381 and 1,768 ms off against 1,378 and 1,386 ms on, 20 statements both ways. The difference is inside the run to run noise, below the 25% line, so creation revisions are written and the lazy baseline stays only for rows that predate the migration |
| Not run by the author | The full suites |

```http
GET /api/v1/catalog/items/01a1e26a-e3e5-7000-8000-0000000000f1/history?limit=2
```

```json
{ "data": [
    { "version": 3, "operation": "updated", "changedAt": "2026-11-16T14:20:03.512004Z", "actorIdentityId": "01a1e26a-e3e6-7000-8000-0000000000a1", "changedFields": ["name"] },
    { "version": 2, "operation": "updated", "changedAt": "2026-11-16T13:02:51.101220Z", "actorIdentityId": "01a1e26a-e3e6-7000-8000-0000000000a1", "changedFields": ["description", "fulfillment"] } ],
  "meta": { "pageInfo": { "hasNextPage": true, "endCursor": "eyJ2IjoxfQ" } } }
```

```http
POST /api/v1/catalog/items/01a1e26a-e3e5-7000-8000-0000000000f1/restore
If-Match: "7d2a90c3f4"
{ "version": 1 }
```

```json
{ "data": { "id": "01a1e26a-e3e5-7000-8000-0000000000f1", "outcome": "change", "changed": ["name", "description"], "etag": "\"3f9c0b7e21\"" }, "meta": {} }
```

### I4-0 as built: a neutral option prefix and option codes compared without case (migration 0117, baseline revision 126)

| Piece       | As built                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prefix      | `modifier_options.prefix` is any trimmed label of 1 to 20 characters (`modifier_options_prefix_chk`). The six words `add`, `extra`, `light`, `no`, `on_the_side` and `substitute` keep their rules whatever their case (`modifier_options_prefix_quantity_chk`, `modifier_options_prefix_kind_chk` and `modifier_options_text_shape_chk` compare `lower(prefix)`, so `No` or `LIGHT` obey the rule of `no` and `light`; the label is stored as written, and any other label carries no rule) and a text option still takes none or `add`. A shop of phones, apparel or salon services names its own labels (`Express`, `Add-on`) with no kitchen vocabulary; the prefix stays optional and a hint for printing and screens, never a sale rule |
| Option code | `modifier_options_group_code_ci_uq` is unique on `(modifier_group_id, lower(code))`; the case-sensitive `modifier_options_group_code_uq` stays. The migration refuses to run, naming `modifier_options_code_ci_duplicates` (proven by `modifier-option.constraints.integration-spec.ts`, which runs the guard of the migration against two such codes), while a group holds two codes that differ only in case; the routes never wrote such a pair because they compare without case                                                                                                                                                                                                                                                          |
| Routes      | The request and the answer of `POST /catalog/modifier-groups`, `PUT /catalog/modifier-groups/{modifierGroupId}` and the reads carry `prefix` as a string of 1 to 20 characters (trimmed on the request) instead of the six-word enum. A unique violation of the new index answers `409 · catalog.code_taken`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| OpenAPI     | `13.12.0`, unreleased on this branch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### I3 as built: an applied import is read back (no migration, baseline revision 125)

| Piece          | As built                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Route          | `GET /catalog/imports/{importId}` answers `200 { data: { importId, status: "applied", counts }, meta: {} }`, exactly the report the apply answered, read from the summary stored with the import. `Cache-Control: private, no-cache`, no ETag: a stored report never changes and the route is rarely read. A dry run stores nothing, so it has no id            |
| Access         | The same as the apply: `catalog.items.manage` organization-wide and the capability `catalog.items`, decided before the read (no new permission). As every read of the catalog, a refusal leaves no audit record                                                                                                                                                 |
| Not found      | An id that does not exist and one of another organization answer the same `404 · catalog.not_found` (the house code for every catalog resource, no `catalog.import_not_found`); the read filters on the organization of the tenant and the row policy is a second guard, so nothing tells a foreign id from an unknown one. A malformed id is `400` on the path |
| Statements     | One primary key lookup (`catalog.imports`, `id`) after the permission check; no plan spec, because no table that grows by organization is scanned                                                                                                                                                                                                               |
| Unreadable     | A stored summary that does not have the recorded shape raises `StoredImportSummaryUnreadableError`, answered as `500 · foundation.internal_error` with the named error in the log, never a half report                                                                                                                                                          |
| Classification | `GET /catalog/imports/{importId}` is a back-office route, not hot: opened by the manager who loaded the sheet                                                                                                                                                                                                                                                   |
| OpenAPI        | Still `13.12.0` (unreleased on this branch), additive                                                                                                                                                                                                                                                                                                           |

### 9.w The code pattern of a catalog: the database is a deliberate superset

`catalogs_code_pattern_chk` and `catalog.clone_catalog` accept `^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$`, the pattern every other catalog code in the schema already uses (items, variants, categories, menus), while the API creates a catalog only with `^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$` (lowercase letters, digits and dashes, derived from the name when no code is sent). The difference is deliberate: the database keeps one code alphabet for every catalog entity and never rejects a row a future route or an import may legitimately write, while the API keeps catalog codes lowercase so they read well in a URL. A code legal in SQL and not in the API can therefore only come from SQL, never from HTTP; `catalog-clone.constants.integration-spec.ts` pins the lengths both sides share (the 1,200 items of a source, the 200 characters of a name and the 80 of a code).

### 9.x S1 as built: contract hygiene of the catalog admin

OpenAPI `14.0.0` (two breaking changes: the answer of `POST /catalog/items/{itemId}/variants` and the shape of `GET /catalog/menus`). Every change below has its observed RED and its mutation proof in the commits `05ae007c` .. `291f3b53`.

| Change                                                                                                                | Request                                                                                                                                                                                 | Answer                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lists scoped to one catalog (bug found by the showcase: after a clone the four lists mixed the rows of every catalog) | `GET /catalog/{categories,product-brands,modifier-groups,menus}?catalogId=<id>`; absent means the default catalog; an id the organization does not have answers `404 catalog.not_found` | Only the rows of that catalog. The category tree tag names the catalog (`<org>:category-tree:<version>:<status>:<catalogId or default>`). The default read costs the same statements as before (one scalar subquery inside the list statement); a named catalog adds one existence statement                                                                                                                          |
| Menus list as a bare array                                                                                            | `GET /catalog/menus`                                                                                                                                                                    | `data` is `[{menuId, code, name, status, sectionCount, entryCount}]`, no longer `{menus: [...]}`                                                                                                                                                                                                                                                                                                                      |
| Clone counts in camelCase                                                                                             | `POST /catalog/catalogs/{id}/clones`                                                                                                                                                    | `counts` keys are `items`, `itemVariants`, `menuEntries`, ... instead of `item_variants`                                                                                                                                                                                                                                                                                                                              |
| Lean answer of a new variant                                                                                          | `POST /catalog/items/{itemId}/variants` (+ optional `?include=item`)                                                                                                                    | one stable shape `{variant: {variantId, code, name, sku, salesUnitCode, minimumSalesQuantity, maximumSalesQuantity, salesQuantityStep, isDefault, status}, item?: <whole item>}` with the new tag of the item in `ETag`; `item` is present only with `include=item`                                                                                                                                                   |
| Named default variant at creation                                                                                     | `POST /catalog/items` with `defaultVariant: {code?, name?, sku?, ...}`                                                                                                                  | Same item answer; the default variant carries that code and name. A default that stops being the default needs a name, so a dish with sizes names its first size here and skips the rename call                                                                                                                                                                                                                       |
| A matrix can replace the unnamed default                                                                              | `POST /catalog/items/{itemId}/variant-matrix` with `replaceDefault: true` and optional `formerDefaultName`                                                                              | The first created cell becomes the default; only when the default is the unnamed variant a new item is born with, which stays as a named (`formerDefaultName` or the item name), inactive variant. A default that already has a name (a named default at creation, or a cell of an earlier matrix) is never touched: the cells are still created and the default stays. A matrix that creates nothing changes nothing |
| Card fields on the item row                                                                                           | `GET /catalog/items` and the first page of `GET /catalog/workspace`                                                                                                                     | Each row adds `description` (nullable), `categoryIds` (primary first), `groupCount` (active groups the item offers, suspended offers and variant overrides excluded) and `extrasCount` (active `catalog_variant` options of those groups); the same single statement                                                                                                                                                  |

Examples:

```
POST /api/v1/catalog/items/{itemId}/variants
{ "code": "grande", "name": "Grande", "sku": "CC-G" }
201  ETag: "<item tag>"
{ "data": { "variant": { "variantId": "...", "code": "grande", "name": "Grande", "sku": "CC-G",
            "salesUnitCode": "unit", "minimumSalesQuantity": "1", "maximumSalesQuantity": null,
            "salesQuantityStep": "1", "isDefault": false, "status": "active" } } }

POST /api/v1/catalog/items
{ "name": "Ceviche de camaron", "defaultVariant": { "code": "pequeno", "name": "Pequeno", "sku": "CC-P" } }

POST /api/v1/catalog/items/{itemId}/variant-matrix
{ "dimensions": [ { "name": "RAM", "values": [ {"code":"8gb","name":"8 GB"}, {"code":"16gb","name":"16 GB"} ] } ],
  "skuPrefix": "IDEAPAD", "replaceDefault": true, "formerDefaultName": "Base" }

GET /api/v1/catalog/items?limit=1
{ "data": [ { "itemId": "...", "code": "ceviche-camaron", "name": "Ceviche de camaron", "description": null,
              "status": "active", "defaultVariant": { "variantId": "...", "sku": "CC-G", "salesUnitCode": "unit" },
              "variantCount": 2, "categoryIds": ["..."], "groupCount": 2, "extrasCount": 4,
              "primaryCategory": { "categoryId": "...", "name": "Ceviches" }, "primaryImage": null } ] }
```

Measured on the showcase company (same driver before and after, `ninaku_play`, one client): 267 calls became 246 (the rename call and the default clean-up calls are gone); response bytes of one `POST /variants` fell from about 900 to 304 and the whole run (without the scale probe) from 379,227 to 347,580 bytes; the item list row grew by about 25 percent (3,990 to 5,004 bytes for ten rows) for the five card fields; the lists after a clone answer 15 categories, 3 brands, 6 groups and 2 menus where they answered 30, 6, 12 and 4. Reads p50 3.5 to 3.3 ms and p95 15 to 13.4 ms, writes p50 9.6 to 7.6 ms (a load average above 10 on this machine, so read the ratios, not the absolute numbers).

Decisions and what S1 left out:

* `include=item` adds the whole item next to the variant (the answer is one shape, never a union); the lean answer is the default. OpenAPI stays at the major bump `14.0.0` because the answer of `POST /variants` and the shape of `GET /catalog/menus` changed on the wire (pre-release, no consumers).
* `replaceDefault` swaps only the unnamed default a new item is born with; it never touches a named default or a cell of an earlier matrix (a later matrix that adds a size keeps the default and the earlier cells).
* Non-happy matrix of S1: `test/e2e/catalog-s1-non-happy.e2e-spec.ts` (validation, authorization, tenant leak, state, concurrency, caps, rollback, empty collections, cursor and limit bounds). Not covered and listed as gaps: oversized body (413) and rate limit (429) on these routes, revoked capability on the new routes, a forced failure after the replacement inside one transaction, lists of 5,000+ rows, lock timeout 503 and lock order against imports and clones for the matrix replacement.
* Not built, awaiting the owner: the `fulfillment: sellable | extra_only` flag (it needs a migration and the sellable rule of the till, which every parity spec guards), the till payload fields (description, bundle choice names, per-choice availability: the golden file `till-snapshot.golden.json` and the sellable budgets would move, so it stops here), and a required `If-Match` on single-entity PATCH routes (D24 keeps `If-Match` optional there; the whole-collection PUT routes already answer `428`).
* Delta actions proposed here and built later ("9.ac Slice D as built"): `PUT /items/{id}/categories` becomes `POST /items/{id}/categories {categoryId, isPrimary?}` plus `DELETE /items/{id}/categories/{categoryId}`; `PUT /items/{id}/modifier-groups` becomes `POST /items/{id}/modifier-groups {modifierGroupId, minSelections, maxSelections, ...}`, `PATCH /items/{id}/modifier-groups/{groupId}` and `DELETE`, plus `POST .../modifier-groups/moves {modifierGroupId, before?}`; `PUT /menus/{id}/structure` keeps being the document replace and gains `POST /menus/{id}/entries {sectionId, itemId, variantMode?, before?}`, `POST /menus/{id}/entries/{entryId}/moves {sectionId, before?}` and `DELETE /menus/{id}/entries/{entryId}`; `PUT /items/{id}/bundle-groups` gains `POST /items/{id}/bundle-groups/{groupId}/choices {variantId, quantityPerSelection?, isDefault?}` and `DELETE .../choices/{choiceId}`. Each answers the id, the new tag and what changed, never the whole document.
* The variant matrix still answers the whole item (3.7 KB); making it lean (`include=item`) is the next candidate for the same rule.

### 9.y S1b as built: fulfillment of an item and the till card fields

Migration `0117` (revision 134, additive: it revises no earlier migration) adds `catalog.items.fulfillment` (`sellable` by default, or `extra_only`; `catalog_items_fulfillment_chk`) and migration `0125` defines `catalog.clone_catalog` so a clone copies it. Parity proof: a database upgraded from revision 133 with `db:prepare` and a database installed fresh from the new canonical files give identical `pg_dump --schema-only` output (privileges included), apart from the random `\restrict` token.

| Change                  | Request                                                                                                                                                                        | Answer                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fulfillment` on create | `POST /catalog/items` with `fulfillment: "extra_only"` (optional, `sellable` when absent); a replay with another value under the same key answers `409 idempotency.key_reused` | The item answer and every item read carry `fulfillment`                                                                                                                                                                                                                                                                                                                                             |
| `fulfillment` on edit   | `PATCH /catalog/items/{itemId}` with `fulfillment`                                                                                                                             | The item with its new tag; a repeat writes and records nothing; one `catalog.item.fulfillment` change (before, after) in the audit record                                                                                                                                                                                                                                                           |
| Admin reads             | `GET /catalog/items`, the first page of the workspace, the item read                                                                                                           | `fulfillment` on every row                                                                                                                                                                                                                                                                                                                                                                          |
| Till rule               | the lists, the search, the scan and the sellable contract                                                                                                                      | An `extra_only` item is never sold on its own: it is out of `GET /catalog/outlets/{id}/sellable-items`, the search, the barcode scan and the admission of Sales. It stays a valid target of a `catalog_variant` option and a component of a combo (the rule that decides an option target and a combo component never looked at the flag; only the standalone gate does, through `scope.component`) |
| Till item description   | `GET .../sellable-items`, `.../sellable-item-search`, `.../bootstrap/items`                                                                                                    | `description` on an item that has one; no key on one that has none                                                                                                                                                                                                                                                                                                                                  |
| Till combo choice names | the same reads, on a combo                                                                                                                                                     | each choice adds `itemName` and `variantName` (null for an unnamed variant), so the till can label a component that is not among its items (an `extra_only` one)                                                                                                                                                                                                                                    |

Decision on per-choice availability: a choice that the till cannot sell is already omitted from the answer (never suspended, inactive, unlisted or unfillable ones are sent), so an `isAvailable` flag would always be true there. The admin read of the bundle groups keeps its `isAvailable`. Runtime stock and quota availability stay out of Catalog.

Examples:

```
POST /api/v1/catalog/items
{ "name": "Chifle", "fulfillment": "extra_only", "defaultVariant": { "sku": "EX-CHIFLE" } }
201  { "data": { "itemId": "...", "fulfillment": "extra_only", ... } }

PATCH /api/v1/catalog/items/{itemId}
{ "fulfillment": "sellable" }
200  ETag: "<new tag>"  { "data": { "fulfillment": "sellable", ... } }

GET /api/v1/catalog/outlets/{outletId}/sellable-items   (a combo item)
{ "itemId": "...", "name": "Combo Planchero", "description": "Bebida, dos platos y postre",
  "bundleGroups": [ { "bundleGroupId": "...", "name": "Bebida", "minSelections": 1, "maxSelections": 1,
    "choices": [ { "choiceId": "...", "itemId": "...", "itemName": "Colada morada", "variantName": "Vaso",
                   "variantId": "...", "quantityPerSelection": "1", "maxSelectionCount": null, "isDefault": true } ] } ] }
```

Non-happy matrix of S1b, all in `test/e2e/catalog-s1b-gaps.e2e-spec.ts`, `catalog-item-fulfillment.e2e-spec.ts` and `catalog-till-card-fields.e2e-spec.ts`: body over 100 KB (413 `payload.too_large`), rate limit (429 with `Retry-After`, nothing written), plan without the catalog (403 `platform.capability_not_entitled` on the three S1 writes), a forced failure after the default replacement (500, item tag, variants and audit trail unchanged), a held catalog lock (503 `service.unavailable`, `Retry-After: 1`, then the same matrix applies), the replacing matrix racing an import, a clone, a category write and an item create three times over (all 201, no deadlock), the status-filtered category tree equal to the default catalog alone after a clone, and 5,000 items (the list answers in the same 7 statements as with five, and pages by cursor). Gaps left: lock timeout of the other S1 routes, and the 5,000-row case for the four lists scoped by catalog.

### 9.z B1 as built: translations (migration 0118, baseline revision 140)

C23 is built. A business writes the text of its records once, in the default language of the organization (`organization.default_locale`), and adds other languages as translations that reads fall back from.

**Tables.** The 11 existing translation tables are usable; migration `0118` adds `product_brand_translations`, `variant_dimension_translations` and `variant_dimension_value_translations` with the same shape (owner id, `organization_id`, `locale_code` against `reference.locales`, text, composite foreign key to the owner, tenant policy with the scalar subquery) and `catalog.offered_locales` (`organization_id`, `locale_code`, `outlet_id` nullable, `status` `active` or `inactive`; one row per organization and language, one per outlet and language). Every translation table and `offered_locales` carries the three catalog version triggers; the translation tables of records a device reads also feed the change feed of the owner record (`catalog.item.changed`, `variant`, `category`, `modifier`, `bundle`, `menu`), and `category_translations` moves the category tree version too, so the tree ETag follows a translated name. The runtime role may select, insert, update and delete the translation tables and `offered_locales`, and select `allergens` and `dietary_tags` (their own API is C24). A catalog clone copies the 12 translation tables of a catalog (the allergen and dietary tag lists are organization data and are not cloned).

**Write routes.** One pair of routes serves the 14 kinds of record (`items`, `variants`, `categories`, `allergens`, `dietary-tags`, `modifier-groups`, `modifier-options`, `bundle-groups`, `menus`, `menu-sections`, `menu-entries`, `product-brands`, `variant-dimensions`, `variant-dimension-values`):

| Route                                               | Request                                                        | Answer                                                                                                                          |
| --------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `PUT /catalog/{kind}/{id}/translations/{locale}`    | `{"name":"Grilled chicken","description":"Served with rice."}` | `200 {"data":{"locale":"en","name":"Grilled chicken","description":"Served with rice."}}` and the ETag of that translation      |
| `DELETE /catalog/{kind}/{id}/translations/{locale}` | none                                                           | `204`, also when nothing was there                                                                                              |
| `GET /catalog/{kind}/{id}/translations`             | none                                                           | `200 {"data":[{"locale":"en","name":"Grilled chicken","description":"Served with rice."}]}` ordered by locale, ETag of the list |

Decisions. `PUT` replaces the translation of one language of one record and nothing else, so it is idempotent: an absent or `null` field means no translation of that field (the read falls back to the original), a body with neither field is refused with 400, and a record without a description (variants, product brands, variant dimensions and their values) refuses `description` with a field error. The default language of the organization is the text of the record itself: it answers `422 catalog.translation_default_locale`. An unknown locale answers `400 catalog.locale_unknown`. An archived or retired record cannot receive a translation (`422 catalog.translation_owner_archived`) but a translation can still be removed. Permission is `catalog.items.manage`, the permission every catalog entity uses (`PUT` gated by the plan, `DELETE` not). `If-Match` is optional, like the edit of a category: it names the ETag of the translation (a hash of locale, name and description); a stale tag, or any tag for a translation that does not exist, answers 412 and writes nothing, and `*` matches an existing translation. Only a real change is written and audited (`catalog.<kind>.translation_set`, `catalog.<kind>.translation_removed`, one attribute per changed field and language); the catalog version row is locked first, like every other write.

**Offered languages.** `GET /catalog/offered-locales` answers `{"defaultLocale":"es","organization":[{"locale":"en","status":"active"}],"outlets":[{"outletId":"...","locale":"fr","status":"active"}]}` with an ETag. `PUT /catalog/offered-locales/{locale}` and `PUT /catalog/outlets/{outletId}/offered-locales/{locale}` take `{"status":"active"|"inactive"}`; `DELETE /catalog/outlets/{outletId}/offered-locales/{locale}` removes the adjustment of an outlet. The default language is always offered and cannot be set (`422 catalog.default_locale_always_offered`); each scope holds at most 40 languages.

**Reads.** A `locale` query parameter (a BCP 47 code written as `reference.locales` holds it) is accepted by the category tree and one category, the item list and one item, the modifier group list and one group, the product brand list and one brand, and by the till reads: `sellable-items`, `sellable-item-search`, `bootstrap` and `bootstrap/items`. The fallback chain, per field: the translation of the requested language, otherwise the text of the record. Order, cursors and search stay on the original text, so a language never changes which records come back or in which order; `q` searches the original text. A till read takes only a language the outlet offers (organization row, adjusted by the outlet row; the default is always offered), otherwise `400 catalog.locale_not_offered`. Statement cost: without `locale` nothing changes; with it, one statement for the translations of every record of the answer together (it also checks the locale, reads the offered rows and, through the published function `organization.organization_default_locale` of migration `0118`, the default language), on admin and till reads alike. Each language has its own ETag (the category tree and sellable tags carry the language; item, category, group and brand tags are hashes of the answered content), and the tag of a localized read is not the tag to send in `If-Match` on a write: write with the tag of the read without `locale`.

**Also localized.** The menu list and one menu (menu, sections, subsections, item and variant names of the entries), the combo read (`GET /catalog/items/{itemId}/bundle-groups`: group, component item and variant names) and the variant dimension list (dimension and value labels) accept `locale` with the same per-field fallback; their ETags are hashes of the answered content, so a translation edit moves them (proved for category, item, modifier group, menu, brand, dimension list and till reads). A conditional `DELETE` of a translation that does not exist answers 412, like `PUT`; without `If-Match` it stays idempotent. Migration `0118` makes the catalog version bump fail with `NINAKU_CATALOG_VERSION_MISSING` when no version row exists.

**Outlet menus and matrix labels.** `GET /catalog/outlets/{outletId}/menus` also takes `locale` (the menu names, one more statement, its own ETag per language). The item read answers the dimension and value labels of every matrix variant in the language inside the same single lookup as the other names (the read keeps the ids of dimensions and values internally and never sends them in `dimensionValues`). `GET /catalog/variant-dimensions` now answers `dimensionId` and, per value, `valueId`, the ids that `PUT /catalog/variant-dimensions/{dimensionId}/translations/{locale}` and `PUT /catalog/variant-dimension-values/{valueId}/translations/{locale}` take (before this a client could not name them).

**Translations in the import document.** Categories, items, variants, modifier groups and options accept an optional `translations` object keyed by locale code: `{"translations":{"en":{"name":"Grilled chicken","description":"With rice."},"fr":{"name":"Poulet"}}}`; a variant takes `name` only. At most 12 languages per record and 6000 translations per request; a malformed key, an empty body, an unknown field or a variant `description` answer 400 before any database work. The apply replaces each sent language of each sent record and leaves every other language alone (to remove one use `DELETE /catalog/{kind}/{id}/translations/{locale}`); a document without `translations` runs the same statements as before. A document that carries translations costs exactly two statements more, whatever their number (one read of the default language and of the known locales, one write: a single statement with one `INSERT ... ON CONFLICT` per translation table, resolving each owner by code in the target catalog; asserted with 3 and with 120 items). A language that is the default of the organization (`422 catalog.translation_default_locale`, field `items[0].translations.es`) or is not in `reference.locales` (`422 catalog.locale_unknown`) is a row error with its `ref`, in `dryRun` too, and nothing is written. The catalog version and the change feed move through the same triggers as the translation routes. A future export carries the same shape: one `translations` object per record with the languages that exist, so an export is a valid import; the export does not exist yet.

**Non-happy matrix of the translation and offered language routes** (`catalog-translations-non-happy`, `catalog-translations-throttle`):

| Case | Expected | Observed |
| --- | --- | --- |
| Body of 100 KB + 1 and of 1 MiB on `PUT .../translations/{locale}` and `PUT /catalog/offered-locales/{locale}` | `413 payload.too_large` | as expected; a 100 KB body is read and refused as validation (400) |
| Fifth write of a member within the minute (limit 4 in the test) on a translation and on an offered language | `429 rate_limit.exceeded` with `Retry-After`, nothing written, reads still answer | as expected |
| Write, removal and offered language while another transaction holds the catalog version | `503 service.unavailable`, `retryable`, `Retry-After: 1`, nothing written, version unchanged; the same call succeeds when the catalog is free | as expected |
| Translations, offered language, two imports with translations, a category create, a delete and a clone of one organization in parallel | no `40P01`, no 500 | as expected |
| The statements of a translation write and of an offered language write | the `catalog_versions` row is locked before the translation or the offered language is touched | proved by statement order; removing the lock fails the test |
| `recordSuccess` fails after the write | `500`, no translation row, version and audit trail as before | as expected, for the translation and for the offered language |
| Translation lists | not paged (at most one row per language of the record), so there is no cursor to tamper | n/a |

**Measured** (150 items with translations, 25 runs each, median and 95th percentile of the whole HTTP round trip in milliseconds, statements including the tenant ones; Postgres 18 and the API on one laptop, load average 3.1 3.7 4.0, so only the ratio means anything):

| Read | `locale` | Bytes | Statements | p50 | p95 |
| --- | --- | ---: | ---: | ---: | ---: |
| Item list (50) | none / en | 18558 / 19099 | 7 / 8 | 3.7 / 3.8 | 4.2 / 4.3 |
| Item read | none / en | 505 / 517 | 7 / 8 | 3.7 / 3.4 | 4.3 / 3.9 |
| Category tree | none / en | 473 / 478 | 7 / 8 | 2.0 / 2.0 | 2.5 / 2.4 |
| Menu read | none / en | 621 / 618 | 7 / 8 | 2.2 / 2.3 | 3.0 / 2.9 |
| Menu list | none / en | 160 / 157 | 7 / 8 | 1.6 / 2.0 | 2.0 / 2.4 |
| Outlet menus | none / en | 201 / 198 | 7 / 8 | 1.8 / 1.8 | 2.1 / 2.0 |
| Variant dimensions | none / en | 223 / 223 | 7 / 8 | 1.6 / 2.3 | 1.9 / 43.9 (one outlier) |
| Sellable items | none / en | 51110 / 56140 | 8 / 9 | 17.0 / 17.8 | 18.6 / 19.0 |
| Bootstrap, page 1 | none / en | 660 / 665 | 7 / 8 | 2.4 / 2.9 | 3.1 / 18.5 (one outlier) |

Mutation proofs: breaking the outlet menu localization, the dimension refs of the item read, the default-language rule of the import, the lock order of the translation write, and migration `0118` (the check `IF v_updated < v_expected` replaced by `IF false`) each fail the test that names it.

### C1 as built: typed business-defined attributes

Decision D50. Definitions and options are organization data; a value follows its item or variant (see D50 and migration `0120`).

**Routes** (all under `catalog.items.manage` for writes and `catalog.items.view` for reads):

| Route | What it does |
| --- | --- |
| `POST /catalog/attribute-definitions` | Define an attribute (`Idempotency-Key` required). |
| `GET /catalog/attribute-definitions[/{definitionId}]` | List (bounded at 200) or read one, with its options and an ETag. |
| `PATCH /catalog/attribute-definitions/{definitionId}` | Name, unit, `filterable`, order. Code, kind and `multiSelect` never change. |
| `POST /catalog/attribute-definitions/{definitionId}/transitions` | deactivate, reactivate, archive, restore. |
| `POST .../{definitionId}/options`, `PATCH .../options/{optionCode}`, `POST .../options/{optionCode}/transitions` | Delta actions on one option of a list. |
| `PUT` / `DELETE /catalog/items/{itemId}/attributes/{code}` | Set or clear the value on an item. |
| `PUT` / `DELETE /catalog/items/{itemId}/variants/{variantId}/attributes/{code}` | The same on a variant. |
| `GET /catalog/items/{itemId}?include=attributes` | The item with `attributes` on the item and on each variant. The strong ETag covers them. |
| `GET /catalog/items?include=attributes&attr.<code>=...` | The list with the compact attributes of each item, and the filters. |

Request and response examples:

```json
POST /catalog/attribute-definitions
{ "code": "weight", "name": "Weight", "valueKind": "number", "unitCode": "kg", "filterable": true }
201 { "data": { "definitionId": "01930000-0000-7000-8000-0000000000d1", "code": "weight", "name": "Weight", "valueKind": "number", "unitCode": "kg", "filterable": true, "multiSelect": false, "sortOrder": 0, "status": "active", "options": [] } }

POST /catalog/attribute-definitions/{definitionId}/options
{ "code": "i7", "name": "Core i7" }
200 { "data": { "definitionId": "...", "code": "processor", "valueKind": "list", "options": [{ "code": "i7", "name": "Core i7", "sortOrder": 0, "status": "active" }], "...": "..." } }

PUT /catalog/items/{itemId}/attributes/weight
{ "value": 1.85 }
200 { "data": { "code": "weight", "value": 1.85 } }

PUT /catalog/items/{itemId}/attributes/ports        (a multi-select list)
{ "value": ["usb", "hdmi"] }
200 { "data": { "code": "ports", "value": ["hdmi", "usb"] } }

GET /catalog/items/{itemId}?include=attributes
200 { "data": { "itemId": "...", "attributes": { "weight": 1.85, "processor": "i7", "warranty": true }, "variants": [{ "variantId": "...", "attributes": {} }], "...": "..." } }

GET /catalog/items?attr.weight.max=2&attr.processor=i7,i9&include=attributes&limit=50
```

**Filters.** `attr.<code>=<value>` compares a text without case, a number exactly, `true` or `false`, or one or several option codes separated by commas (any of them); `attr.<code>.min` and `.max` bound a number, both inclusive; up to five different attributes combine with AND and with every other filter. A code that is unknown, inactive or not `filterable` lists nothing, like an unknown `variantValue`. A value of a variant counts for its item. The cursor is bound to the filter, so a cursor of another filter is a 400.

**Statements.** The list stays one statement with or without the filters or `include=attributes`: each filter is one more candidate set intersected with the others, and `include` adds one correlated column. The item read with `include=attributes` adds one statement (`valuesOfItem`) in the same transaction. A set is the item lock, the definition read, a count, a delete and an insert, and one audit record only when the value changed.

**Measured** (10 repeats each, development machine, load average 4 to 9, 50 items with six attributes each, not a capacity claim):

| Request | Bytes | p50 | p90 |
| --- | --- | --- | --- |
| `GET /catalog/items/{id}` | 513 | 3.4 ms | 6.1 ms |
| `GET /catalog/items/{id}?include=attributes` | 635 | 5.7 ms | 19.0 ms |
| `GET /catalog/items?limit=50` | 18,780 | 4.7 ms | 10.1 ms |
| `GET /catalog/items?limit=50&include=attributes` | 24,045 | 6.6 ms | 9.1 ms |
| `GET /catalog/items?limit=50&attr.weight.max=3` | 7,920 | 3.9 ms | 6.3 ms |
| `GET /catalog/items?limit=50&attr.processor=i7&attr.warranty=true` | 9,730 | 4.2 ms | 5.9 ms |
| `PUT /catalog/items/{id}/attributes/weight` | 46 | 11.6 ms | 16.3 ms |

With stale statistics (`item-list-attributes.plan.integration-spec.ts`: 10,000 neighbour items, 2,001 imported, statistics frozen before the import) every filter reads its first page through the partial indexes without a sequential scan; a filter reads at most 4 rows and buffers per item of the tenant, and `include=attributes` adds at most 30 buffers per listed item.

**Skipped in C1:** facets (S3). The import of attributes is C1b below.

### C1b as built: attributes in the import

An item and a variant of an import document may send `attributes` (`{ code: value }`, the typed value of `PUT /catalog/items/{itemId}/attributes/{code}`).

```json
{ "mode": "upsert", "dryRun": false, "items": [{
    "code": "LAPTOP", "name": "Laptop",
    "attributes": { "weight": 1.85, "processor": "i7", "ports": ["usb", "hdmi"] },
    "variants": [{ "code": "default", "salesUnitCode": "unit", "attributes": { "material": "Magnesium" } }] }] }
```

Only the codes sent change; the ones left out are never touched, so a sheet that carries a few columns cannot erase the rest. A value equal to the stored one counts as `unchanged` and writes nothing. The counts gain `attributeValues` (`created`, `updated`, `unchanged`, one per code on each item or variant) only when the document sent attributes. Refusals are row errors, all together, with the field `items[i].attributes.<code>` or `items[i].variants[j].attributes.<code>` and the `ref` of the row: `catalog.not_found` (unknown attribute), `catalog.attribute_definition_not_active`, `catalog.attribute_value_invalid`, `catalog.attribute_option_not_active` and `catalog.attribute_value_limit_reached` (an item would hold more than 100 stored values). A request holds at most 5,000 attribute values and an object at most 100 codes (400). The import stays all or nothing.

**Statements.** The import adds a constant number of statements however many values it sends: one read of the definitions named by the document with their options, one read of the stored values of the items it names, and, only when a value changes, one delete of the replaced slots and one insert, both from arrays. The ids of the new items and variants are resolved by code inside the insert, after the items and variants were written.

### 9.aa B2 as built: allergens, dietary tags and nutrition (migration 0119, baseline revision 147)

C24 is built. The catalog declares what a dish contains in three layers: the lists a business defines, what each item and variant declares from them, and the nutrition facts of the item. Every write needs the catalog manage permission with the plan, `If-Match` where it changes an item, audits in the same transaction and moves the catalog version once. Decisions: D42 (combo labels) and D43 (nutrition versions) in `DECISIONS.md`.

**Lists and defaults.** `GET` and `POST /catalog/food-labels/{kind}` (`kind` is `allergens` or `dietary-tags`), `GET` and `PATCH /catalog/food-labels/{kind}/{labelId}`, and `POST /catalog/food-labels/{kind}/defaults`, which loads the 14 EU allergens into the list and skips the codes already present. A list holds at most 500 labels; codes are unique without regard to case, archived ones included.

```json
POST /catalog/food-labels/allergens   {"code":"milk","name":"Milk","sortOrder":1}
201 {"data":{"id":"...","code":"milk","name":"Milk","status":"active"}}
POST /catalog/food-labels/allergens/defaults   {}
200 {"data":{"created":["gluten","crustaceans"],"skipped":["milk"]}}
```

**Assignment deltas.** One thing changes per call, on the item or on one of its variants (`variantId`), at most 20 labels of a kind per target. The answer is lean: the item, `outcome` (`change` or `already_in_effect`), what changed, the count and the new tag.

| Route | Request | Answer |
| --- | --- | --- |
| `POST /catalog/items/{itemId}/allergens` | `{"allergenId":"...","presence":"contains"}` | `200 {"data":{"itemId":"...","outcome":"change","changed":{"action":"added","allergenId":"...","variantId":null,"presence":"contains"},"allergenCount":1,"etag":"..."}}` |
| `PATCH /catalog/items/{itemId}/allergens/{allergenId}` | `{"presence":"may_contain"}` | the same shape with `action` `presence_changed` |
| `DELETE /catalog/items/{itemId}/allergens/{allergenId}?variantId=...` | none | the same shape with `action` `removed` |
| `POST /catalog/items/{itemId}/dietary-tags` | `{"dietaryTagId":"..."}` | `200 {"data":{"itemId":"...","outcome":"change","changed":{"action":"added","dietaryTagId":"...","variantId":null},"dietaryTagCount":1,"etag":"..."}}` |
| `DELETE /catalog/items/{itemId}/dietary-tags/{dietaryTagId}` | none | the same shape with `action` `removed` |

**Chips.** The labels travel by code and name, in the requested `locale`, and a record without labels carries no key at all. The item read answers `allergens: [{"allergenId":"...","code":"milk","name":"Milk","presence":"contains"}]` and `dietaryTags`; the item list adds only the codes behind `include=labels`; the till (`sellable-items`, menus and the bootstrap) answers `allergens: [{"code":"gluten","name":"Gluten","presence":"contains"}]` and `dietaryTags: [{"code":"vegan","name":"Vegan"}]` on each item and variant, `contains` winning over `may_contain`.

**Combos.** A combo declares nothing: its allergens are the union of those of its possible components (`contains` over `may_contain`) and it carries a dietary tag only when every possible component does, through nested combos. The union is read from the projection `catalog.bundle_food_label_projection` kept by triggers (D42), so the till reads it inside its page statement.

**Import.** An import item and its variants accept `allergens: [{"code":"milk","presence":"contains"}]` and `dietaryTags: ["vegan"]` keyed by label code; when the key is sent the list replaces what the record holds, and an unknown, archived or repeated code is a row error with its field path (the import adds two statements, whatever the number of labels). **The import does not carry nutrition**: its profiles are versioned and dated, and an import document has no place to say the version or the basis (D43).

**Nutrition.** `PUT` and `DELETE /catalog/items/{itemId}/nutrition` need `If-Match`; `GET /catalog/items/{itemId}/nutrition` answers the published profiles and `GET .../nutrition/versions` the history by keyset.

```json
PUT /catalog/items/{itemId}/nutrition   If-Match: "<tag>"
{"basisType":"per_100g","facts":[{"nutrientCode":"calories","amount":250},{"nutrientCode":"protein","amount":12.5,"qualifier":"exact"}]}
200 {"data":{"itemId":"...","outcome":"change","changed":{"action":"published","basisType":"per_100g","variantId":null,"version":1},"etag":"..."}}

DELETE /catalog/items/{itemId}/nutrition?basisType=per_100g   If-Match: "<tag>"
200 {"data":{"itemId":"...","outcome":"change","changed":{"action":"retired","basisType":"per_100g","variantId":null,"version":1},"etag":"..."}}

GET /catalog/items/{itemId}/nutrition
200 {"data":{"profiles":[{"basisType":"per_100g","version":2,"serving":{"quantity":100,"unitCode":"g"},"facts":[{"nutrientCode":"calories","amount":260,"qualifier":"less_than"}]}]}}

GET /catalog/items/{itemId}/nutrition/versions?limit=50
200 {"data":[{"basisType":"per_100g","variantId":null,"version":2,"status":"published","factCount":1,"publishedAt":"2026-11-16T15:30:00.000Z"}],"meta":{"pageInfo":{"endCursor":null}}}
```

Rules: a profile has 1 to 40 facts, each nutrient once and known to `reference.nutrients` (`catalog.nutrient_unknown`, 422); the `qualifier` is `exact`, `less_than`, `less_than_or_equal`, `greater_than` or `trace`; a version is the highest of its target and basis plus one; a target and basis hold at most 100 versions (`catalog.nutrition_versions_full`, 422); the same facts again change nothing; a variant profile and an item profile are separate targets; an archived item or variant refuses the write. The item read carries only `nutrition: [{"basisType":"per_100g","version":2,"factCount":1}]`.

**Non-happy matrix.** Rows `CN1` of `CATALOG_CASE_MATRIX.md` (`catalog-item-nutrition`, `-pressure`, `-throttle`, `-budgets`) and `C24` for the lists; the deltas add `catalog-item-food-label-deltas`, `-gaps` and `-throttle`.

**Measured** (statements are the database statements of one call including the session and the permission check; bytes are the JSON body; latency was not re-measured for this slice):

| Call | Statements | Bytes |
| --- | ---: | ---: |
| `PUT .../nutrition` (two facts) | 16 | 246 |
| `DELETE .../nutrition` | 12 | not measured |
| `GET .../nutrition` | 8 | not measured |
| `GET .../nutrition/versions` | 8 | not measured |
| `GET /catalog/items/{id}` with a profile | 7 | 507 (summary included) |
| `POST .../allergens` (delta) | at most 14 (budget) | under 400 (budget) |

The till with chips answers about 2 to 6 ms slower than without them under load (one extra projection read inside the page statement, no extra statement); a quiet-machine re-measurement is deferred to the integration step. The plan spec of the item read (`item-read.plan.integration-spec.ts`) covers the nutrition lookup on a fresh database; its ceilings did not move.

### 9.ab S2 as built: the metadata for forms and the dry run of a write

**`GET /api/v1/catalog/metadata`** answers what an admin form needs to render and validate without hardcoding it. It needs `catalog.items.view`, answers a strong ETag (a content hash of exactly the sections answered) and `Cache-Control: private, max-age=300, must-revalidate`, and a matching `If-None-Match` answers 304 without a body. `?include=` takes any of `limits,enumerations,rules,errors,caller`; absent, the answer holds `limits,enumerations,rules,caller` and the error catalogue (the largest section) only comes with `include=errors`, each include set under its own ETag; anything else, an empty value or an unknown query parameter answers 400 `foundation.validation_failed`.

| Section | What it holds | Where it comes from |
|---|---|---|
| `limits` | text lengths, collection sizes, matrix, menu, import and clone caps, quantity ranges | the very constants the validators import; the unit spec `catalog-metadata-limits.spec.ts` scans every `export const NAME = <number>` of the module and fails when one is neither exposed nor named as not a form limit, and `catalog-metadata-boundaries.spec.ts` proves the schemas accept the limit and refuse one more |
| `enumerations` | item, menu, brand statuses; fulfillment; option kinds and the six prefix words; menu entry variant modes; assortment modes; import modes; barcode symbologies; identifier schemes; regulatory flags | the domain `as const` objects |
| `rules` | lifecycle per status (`editable`, `transitions`) for item, catalog, menu and brand; the default catalog never deactivates; case-insensitive code uniqueness; the prefix sets; required fields, defaults, updatable and only-at-creation fields of each create and update schema; the validate-only contract | the lifecycle tables, the prefix sets of `option-presentation.ts` and the request schemas themselves (`z.toJSONSchema`) |
| `errors` | the problem shape, the field-path convention of a validation failure, the foundation codes and every `CATALOG_FAILURE` with code, status, retryable, title and meaning | the failure registries |
| `caller` | the catalog permissions the caller holds and whether the plan entitles `catalog.items` and `catalog.multiple_catalogs` | the permission check and the operation authorization |

`data.buildHash` fingerprints the static sections; the same static sections are byte-identical for every organization.

```json
{
  "data": {
    "buildHash": "6b3f0c1d9a47e2aa",
    "limits": { "text": { "itemName": 255, "itemCode": 80, "itemCodeGenerated": 60, "sku": 120 }, "collections": { "variantsPerItem": 500, "optionsPerModifierGroup": 50 }, "imports": { "items": 500 }, "catalog": { "cloneItems": 1200 } },
    "enumerations": { "itemStatus": ["active", "inactive", "archived"], "modifierOptionPrefixWords": ["add", "extra", "light", "no", "on_the_side", "substitute"] },
    "rules": {
      "lifecycle": { "item": { "archived": { "editable": false, "transitions": ["restore"] } } },
      "defaultCatalog": { "canBeDeactivated": false, "canBeArchived": false },
      "optionPrefix": { "singleUnitOnly": ["light", "no", "on_the_side", "substitute"], "instructionOptionsOnly": ["no", "on_the_side", "substitute"] },
      "fields": { "item": { "createRequired": ["name"], "createDefaults": {}, "updatable": ["code", "name"], "onlyAtCreation": ["categoryIds", "defaultVariant", "primaryCategoryId"] } }
    },
    "errors": { "catalog": [{ "code": "catalog.item_archived", "status": 422, "retryable": false, "title": "Item archived", "meaning": "The item is archived and read-only until it is restored." }] },
    "caller": { "permissions": { "catalog.items.manage": true, "catalog.catalogs.manage": true }, "capabilities": { "catalog.items": true, "catalog.multiple_catalogs": false } }
  },
  "meta": {}
}
```

Measured on a fresh database, warm, on the real stack:

| Request | Bytes | gzip | Statements | Latency |
|---|---|---|---|---|
| default (limits, enumerations, rules, caller) | 5,206 | 1,652 | 13 | 6.8 ms |
| `include=limits,enumerations,rules` | 4,959 | 1,583 | 6 | 2.3 ms |
| all five sections | 22,949 | 5,856 | 13 | 8.8 ms |
| `include=limits,enumerations,rules,errors` | 22,702 | 5,790 | 6 | 4.3 ms |
| `include=limits` | 1,459 | 654 | 6 | 2.6 ms |
| `include=enumerations` | 928 | 450 | 6 | 2.2 ms |
| `include=rules` | 2,644 | 797 | 6 | 2.1 ms |
| `include=errors` | 17,824 | 4,444 | 6 | 2.6 ms |
| `include=caller` | 298 | 168 | 13 | 7.2 ms |
| 304 on the full answer | 0 | 0 | 13 | |

The 6 statements are the floor of any catalog read, not a cost of the metadata: the tenant context and the `catalog.items.view` check. The static sections add none above that floor (accepted by the owner; the answer is not served without the permission gate). `caller` adds 7 (five permission checks and two entitlement checks).

**Validate-Only** on `POST` and `PATCH` (`PUT` for a modifier group) of items, categories, product brands, modifier groups and menus. `Validate-Only: true` or `?validateOnly=true` runs the real call inside a transaction that is rolled back, so every check is the real one (body, code uniqueness, state, `If-Match`) and nothing is written: no version is bumped, nothing is audited, no event is published, the `Idempotency-Key` is not consumed (send one anyway: it is validated). The answer is always 200 with `data.valid` and the problems the real call would answer, each exactly its `problem+json`:

```json
{ "data": { "valid": true, "problems": [] }, "meta": {} }
```

```json
{
  "data": {
    "valid": false,
    "problems": [
      {
        "type": "https://api.ninaku.io/problems/foundation/precondition_failed",
        "title": "Precondition failed",
        "status": 412,
        "detail": "It changed since the ETag sent in If-Match; read it again before writing.",
        "instance": "/api/v1/catalog/items/01a1e26a-e393-74a4-b126-36dca1967116",
        "code": "foundation.precondition_failed",
        "retryable": false
      }
    ]
  },
  "meta": {}
}
```

Only the statuses 400, 404, 409, 412, 422 and 428 become problems; a refusal of the caller (401, 403, 429) and a server failure stay as they are. Any value of the flag other than `true` or `false` answers 400 instead of guessing, and on a route that is not marked the flag is ignored and the write happens as always.

Decisions and known limits:

* A denial of the caller is audited as always only when the real call runs: a dry run rolls back everything, the denial record included.
* The route that replaces a whole collection keeps its `If-Match` requirement; a dry run answers its 428 as a problem.
* Out of the first cut: the menu structure `PUT`, the transitions and the nested routes of an item (variants, barcodes, images); `lifecycle` has no table for categories and modifier groups, and the metadata does not describe them.
* The ETag of a 304 is computed from the answer, so a 304 costs the same statements as a 200; the saving is the bytes.

### 9.ac Slice D as built: delta routes

Delta routes change one link of an aggregate without sending the whole list. They coexist with the full replacement `PUT` and the structure `PUT`, which stay as they are: both families lock the same `catalog_versions` row first, bump the same aggregate tag and accept the ETag the other answered. Rules shared by every delta route:

* `If-Match` is required (the strong tag of the owning item or menu): 428 without it, 412 when stale; there is no `Idempotency-Key`, because repeating a call is already in effect.
* The answer is lean and carries the new tag twice, in the `ETag` header and in the `etag` field of the body: `{ itemId, outcome, changed, categoryCount | groupCount, etag }` (the combo choice routes answer `{ itemId, bundleGroupId, outcome, changed, choiceCount, etag }`; every id, count and field is named for what it is, never `id` or `count`). `outcome` is `change`, or `already_in_effect` when nothing differed (nothing written, audited or bumped, `changed` null).
* `Validate-Only` works on every route (S2): the answer is `{valid, problems}`.
* A denial of the caller is audited as for any write; a refusal never writes.

#### Item categories

`POST /catalog/items/{itemId}/categories`, `PATCH /catalog/items/{itemId}/categories/{categoryId}`, `DELETE /catalog/items/{itemId}/categories/{categoryId}`.

```http
POST /api/v1/catalog/items/01a1e26a-e393-74a4-b126-36dca1967116/categories
If-Match: "9f2c0d71e8"
{ "categoryId": "01a1e26a-e3a0-7000-8000-0000000000c2", "isPrimary": true }
```

```json
{
  "data": {
    "itemId": "01a1e26a-e393-74a4-b126-36dca1967116",
    "outcome": "change",
    "changed": {
      "added": { "categoryId": "01a1e26a-e3a0-7000-8000-0000000000c2", "isPrimary": true },
      "primary": { "from": null, "to": "01a1e26a-e3a0-7000-8000-0000000000c2" }
    },
    "categoryCount": 1,
    "etag": "3b7a5e0c44"
  },
  "meta": {}
}
```

`isPrimary` of the `POST` body is optional: absent leaves the primary alone (a category the item already has stays as it is, primary or not, and the answer is `already_in_effect`; a new one is added as a non-primary one). `PATCH` takes `{ "isPrimary": true | false }` and moves the primary (the former primary stops being it). `DELETE` unlinks; removing the primary leaves the item without one, as the full replacement allows (a deviation from the proposal, which refused it: the two routes must not disagree about what a valid classification is). Refusals: 404 for an unknown item or category and for a `PATCH` of a category the item does not have; 422 `catalog.category_archived`, `catalog.item_archived` and the new `catalog.item_categories_full` (20 links). Measured with five links: add 271 bytes, set primary 259, remove 240, already in effect 205 (8 statements); the full `PUT` answers 1,005 bytes; every changing call issues 13 statements, as the full `PUT` does.

#### Item modifier groups (offers), including moves

`POST /catalog/items/{itemId}/modifier-groups`, `PATCH` and `DELETE /catalog/items/{itemId}/modifier-groups/{modifierGroupId}`, and `POST /catalog/items/{itemId}/modifier-groups/{modifierGroupId}/moves`. They change the item-level offers only: the variant overrides are never touched, and the full `PUT /catalog/items/{itemId}/modifier-groups` stays and bumps the same item tag. The rule of an offer is judged exactly as in the full replacement (unknown group 404, archived or inactive group, a minimum above the maximum, defaults, quantities and limits 422).

```http
POST /api/v1/catalog/items/01a1e26a-e393-74a4-b126-36dca1967116/modifier-groups
If-Match: "3b7a5e0c44"
{ "modifierGroupId": "01a1e26a-e3b0-7000-8000-0000000000a1", "minSelections": 1, "maxSelections": 1,
  "defaultOptionIds": ["01a1e26a-e3b1-7000-8000-0000000000b1"], "after": null }
```

```json
{ "data": { "itemId": "01a1e26a-e393-74a4-b126-36dca1967116", "outcome": "change",
            "changed": { "added": { "modifierGroupId": "01a1e26a-e3b0-7000-8000-0000000000a1", "position": 1 } },
            "groupCount": 2, "etag": "8d41f0aa17" }, "meta": {} }
```

* `after` names the group the new one follows, `null` puts it first, absent puts it last (the same `after` rule moves a group).
* `PATCH` takes any of `minSelections`, `maxSelections`, `defaultOptionIds`, `defaultQuantities`, `optionLimits`, `suspended` and answers `changed: { "updated": ["maxSelections"] }`, the fields that really differ.
* A move answers `changed: { "moved": { "modifierGroupId": "...", "from": 3, "to": 1 } }` with 1-based positions.
* A group already offered with the same rule is `already_in_effect`; with another rule `409 catalog.modifier_group_already_offered`. The 21st group answers `422 catalog.item_offers_full`. A group, or an anchor, the item does not offer answers 404.
* Measured with five groups: add 268 bytes, update 216, move 271, remove 237, already in effect 202 (8 statements); the full `PUT` answers 3,461 bytes; a changing call issues 14 to 15 statements, as the full `PUT` does.

#### Bundle choices

`POST /catalog/items/{itemId}/bundle-groups/{bundleGroupId}/choices`, `PATCH` and `DELETE .../choices/{choiceId}`. They change one choice of one group of a combo; the full `PUT /catalog/items/{itemId}/bundle-groups` stays. The tag is not the item tag but the one `GET` and `PUT` of the bundle groups use (a hash of the composition as answered), so both families bump it and accept what the other answered. The composition is judged exactly as in the full replacement (archived or other-catalog component, a combo that would contain itself).

```http
POST /api/v1/catalog/items/01a1e26a-e393-74a4-b126-36dca1967116/bundle-groups/01a1e26a-e3c0-7000-8000-0000000000b1/choices
If-Match: "5e90c2d7b3"
{ "variantId": "01a1e26a-e3c1-7000-8000-0000000000d9", "quantityPerSelection": "1", "isDefault": false, "after": null }
```

```json
{ "data": { "itemId": "01a1e26a-e393-74a4-b126-36dca1967116", "bundleGroupId": "01a1e26a-e3c0-7000-8000-0000000000b1",
            "outcome": "change",
            "changed": { "added": { "choiceId": "01a1e26a-e3c2-7000-8000-0000000000c9", "variantId": "01a1e26a-e3c1-7000-8000-0000000000d9", "position": 1 } },
            "choiceCount": 3, "etag": "a7c4e1f093" }, "meta": {} }
```

* `PATCH` takes any of `quantityPerSelection`, `maxSelectionCount`, `isDefault`, `suspended` and names the fields that really changed.
* A variant that already is a choice of the group with the same settings is `already_in_effect`; with other settings `409 catalog.bundle_choice_exists`. The 51st choice answers `422 catalog.bundle_choices_full`.
* The last choice of a group cannot be removed: `422 catalog.bundle_group_would_be_empty` (the full replacement requires at least one choice per group and removes whole groups instead). A group, choice, anchor or variant that does not exist answers 404.
* Measured with five choices: add 368 bytes, update 268, remove 293, already in effect 258 (8 statements); the full `PUT` answers 2,006 bytes; every changing call issues 16 statements, as the full `PUT` does. There is no move route for choices in this slice: `after` places a new one and the full `PUT` reorders.

#### Menu entries, including moves

`POST /catalog/menus/{menuId}/sections/{sectionId}/entries`, `PATCH` and `DELETE /catalog/menus/{menuId}/entries/{entryId}`, and `POST /catalog/menus/{menuId}/entries/{entryId}/moves`. They share the menu tag with `GET` and `PATCH /catalog/menus/{menuId}` and with the structure `PUT`, which stays; a section may be a top section or a subsection.

```http
POST /api/v1/catalog/menus/01a1e26a-e3d0-7000-8000-0000000000a1/sections/01a1e26a-e3d1-7000-8000-0000000000a2/entries
If-Match: "c41d90b7e2"
{ "itemId": "01a1e26a-e393-74a4-b126-36dca1967116", "variantMode": "selected", "variantIds": ["01a1e26a-e393-74a4-b126-36dca1967117"], "after": null }
```

```json
{ "data": { "menuId": "01a1e26a-e3d0-7000-8000-0000000000a1", "outcome": "change",
            "changed": { "added": { "entryId": "01a1e26a-e3d2-7000-8000-0000000000a3", "sectionId": "01a1e26a-e3d1-7000-8000-0000000000a2",
                                    "itemId": "01a1e26a-e393-74a4-b126-36dca1967116", "position": 1 } },
            "entryCount": 12, "etag": "2f8a6c1d55" }, "meta": {} }
```

* `after` is an entry id, `null` for the first place, absent for the last (a move needs it). `PATCH` takes `variantMode`, `variantIds`, `suspended` (at least one); going back to `all` clears the selected variants; the answer names the fields that changed.
* A move inside a section keeps the entry id. A move into another section retires the entry there and shows the item in the new section under a new id: the answer gives the new `entryId` and the `previousEntryId`, because the structure keeps an entry id tied to its section.
* An item already in the section with the same settings is `already_in_effect`; with other settings (or a move into a section that already shows it) `409 catalog.menu_entry_exists`. The 201st entry of a section is `422 catalog.menu_section_full`, the 1001st of a menu `422 catalog.menu_entries_full`; `selected` without variants or `all` with variants `422 catalog.menu_entry_variants_invalid`. The rest is judged as in the structure `PUT`: an archived item `menu_item_unavailable`, a variant of another item `menu_variant_mismatch`, an archived menu, and an active menu cannot lose its last entry (`menu_empty`).
* Measured with ten entries: add 361 bytes (17 statements), update 213 (17), remove 238 (17), already in effect 203 (8); the full `PUT` that adds one entry answers 3,672 bytes and issues the same 17 statements.

## 10. Owner decisions

Ordered by when they are needed. **On 2026-10-04 the owner approved the
recommended default of OD1 to OD9**, so all nine are *Decided*, not open:
restaurant first; the item code optional and generated from the name; shared
products edited only by organization-wide members while business-unit
managers curate their unit's assortment; one catalog per organization now; a
new business unit sells everything, plus a workspace warning; the catalog
included in `pionero` without an item limit; categories now and menus later;
archived items restorable; the generic tag tables dropped. The options stay
below as the record of what was weighed.

| #       | Needed before | Decision                                                             | Options and consequences                                                                                                                                                                                                                                                                                | Decided (approved 2026-10-04)                                                                                                                                                                                                                                                                                                        |
| ------- | ------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **OD1** | K4/K5 order   | Which vertical's needs ship first after the common core?             | (a) Restaurant first: modifiers (K5) before barcodes (K4); a café can sell "latte, oat milk, large" sooner. (b) Retail first: barcodes before modifiers; a shop can scan sooner. Both are small; the order only moves a week                                                                            | (a) Restaurant first, since restaurant is the product origin (`APP_SHELL_AND_ONBOARDING.md` reuses `ninaku-pos`)                                                                                                                                                                                                                     |
| **OD2** | K2            | Is the item `code` required from the person creating a product?      | (a) Required: zero ambiguity, natural idempotency, but friction for a small restaurant that thinks in names. (b) Optional, server-generated from the name (`hamburguesa-clasica`, `-2` on collision): simple UX, needs G3 (`Idempotency-Key` + one column)                                              | (b) Optional and generated; codes remain editable                                                                                                                                                                                                                                                                                    |
| **OD3** | K2/K6         | Who may edit the shared product data?                                | (a) Only organization-wide members (manager or owner assigned to the whole organization); business-unit managers curate their unit's assortment only. (b) Business units own their own products: needs an "owner business unit" on items or one catalog per unit (OD4) and makes shared items ambiguous | (a) Organization-wide edits, BU-level assortment                                                                                                                                                                                                                                                                                     |
| **OD4** | before C25    | One catalog per organization or several?                             | (a) One default catalog (v1). (b) Several catalogs assigned to business units (`access_mode = 'assigned'` already exists): real for a hotel group whose shop and restaurant share nothing, but doubles every screen's context                                                                           | (a) One catalog now; several behind a separate capability later                                                                                                                                                                                                                                                                      |
| **OD5** | K6            | What does a newly registered business unit sell?                     | (a) Everything in the organization catalog (current SQL default: no row = listed). (b) Nothing until someone lists items. (a) surprises a hotel whose new "Shop" unit suddenly sells restaurant dishes; (b) surprises a restaurant opening its second unit with an empty POS                            | **Superseded by D1 (revision 109)** for new units: `all` only for the first unit or one whose verticals already run in another unit, `none` otherwise (see "D1 as built"). Original decision: (a) Everything, plus a one-line warning in the workspace when an organization has more than one business unit with different verticals |
| **OD6** | K1            | Is the catalog part of the `pionero` plan, and is its size limited?  | (a) Included, no item limit. (b) Included with a limit (e.g. 1,000 active items) via `catalog.active_items`. (c) A paid add-on                                                                                                                                                                          | (a) Included, unlimited; a limit needs a business reason first                                                                                                                                                                                                                                                                       |
| **OD7** | C21           | How does a restaurant POS organise products: by category or by menu? | (a) Categories only (v1, no new table). (b) Menus with sections and an outlet-menu assignment (G1): needed for "lunch menu vs dinner menu" and dayparts                                                                                                                                                 | (a) now; (b) when the first restaurant asks for two menus                                                                                                                                                                                                                                                                            |
| **OD8** | K2            | Can an archived product be brought back?                             | (a) Yes, back to `inactive` (restoration). (b) No, archive is final; recreate instead (new variant ids break history continuity for reports)                                                                                                                                                            | (a) Restorable                                                                                                                                                                                                                                                                                                                       |
| **OD9** | K1            | Generic tags (`tags`, `tag_groups`, `item_tags`, `menu_tags`): drop? | (a) Drop in a reviewed migration. (b) Keep for a named use case (e.g. "vegan" filter, which `dietary_tags` already covers)                                                                                                                                                                              | (a) Drop, unless the owner names a use                                                                                                                                                                                                                                                                                               |

**On 2026-10-05 the owner decided the category lifecycle** ("the best for
the business"): a category keeps its own status, its effective visibility
is derived from its ancestors, an inactive category stays organizable and
classifiable, an archived one is read-only. The ten rules are in §5.3,
"Category lifecycle and effective visibility".

Everything else in this document is *Decided* by the author and can be
changed by review without owner input.

***

## 11. Risks and what the existing SQL gets wrong or leaves open

| #   | Finding                                                                                                                                                                                                                                                        | Evidence                                                                      | Recommendation                                                                                                                                                                                                                                               |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| R1  | **The runtime cannot reach the schema.** No `USAGE` on `catalog`; no table grants                                                                                                                                                                              | `runtime_grants.sql` ≈ line 35                                                | K1, with contract tests for what runtime must *not* do (DELETE on master tables, EXECUTE on worker-only functions)                                                                                                                                           |
| R2  | **Dual meaning of `business_unit_items`.** In `all` mode an inactive row excludes; in `selected` mode an active row includes. A row that is "active" in `all` mode does nothing                                                                                | `variant_is_listed`, 4487–4502                                                | Encapsulate in C15; document in SQL test names; consider a `listing_kind` column later only if the dual meaning causes a bug                                                                                                                                 |
| R3  | **Row-at-a-time listing predicate** unsuitable for the POS read                                                                                                                                                                                                | `variant_is_listed` is called per variant, including inside `resolve_barcode` | G4: set-based twin + equivalence test                                                                                                                                                                                                                        |
| R4  | **No `updated_at` maintenance**, and three tables without `updated_at`                                                                                                                                                                                         | no assignment in 0080; `catalogs` 4229, `business_unit_*` 4433/4446           | Application sets it; ETags never rely on it                                                                                                                                                                                                                  |
| R5  | **Organization-wide catalog version** invalidates every outlet's POS cache on any catalog edit                                                                                                                                                                 | G2 design                                                                     | Accepted: edits are rare relative to reads; a `200` re-read is ≤ 6 statements. Revisit with per-business-unit versions if `perf:http` shows refresh storms                                                                                                   |
| R6  | **Item "default variant" deferred trigger** only fires at commit: a use case that forgets the default variant fails with `23514` at `COMMIT`, after audit and other writes                                                                                     | 2979–2991                                                                     | Domain rule in TypeScript prevents it before SQL; the trigger stays as backstop; map its constraint to `catalog.default_variant_required`                                                                                                                    |
| R7  | **READ COMMITTED is asserted** by `ensure_default_catalog`, `lock_hierarchy`, `guard_assortment_change`, `assert_variant_listed`, `resolve_barcode`                                                                                                            | 4245, 2999, 4460, 4504, 4528                                                  | Assumption: the tenant transaction runner uses READ COMMITTED (PostgreSQL default). K1 adds a test that would fail if it changed                                                                                                                             |
| R8  | **`resolve_barcode` takes `FOR SHARE` locks** even for a pure lookup                                                                                                                                                                                           | 4504–4545                                                                     | C18 uses a lock-free read query, and `admit` (K8) does not call it either: no application path uses it, but it stays with its grant (the database contracts exercise it, and its `assert_variant_listed` is called by the Sales schema's order-line trigger) |
| R9  | **`guard_assortment_change` locks the business unit row `FOR UPDATE` per row**; a 200-item listing locks the same row 200 times and contends with Organization structure writes on that unit                                                                   | 4460–4485                                                                     | Bound calls to 200 ids; measure; acceptable for configuration traffic                                                                                                                                                                                        |
| R10 | **`catalogs.code` check is weaker** than every other code (only non-blank, no pattern)                                                                                                                                                                         | 4229–4243                                                                     | Tighten in a later migration when additional catalogs ship (OD4)                                                                                                                                                                                             |
| R11 | **Generic tags have no reader**                                                                                                                                                                                                                                | §3.1                                                                          | OD9                                                                                                                                                                                                                                                          |
| R12 | **Food data shape may move** (`catalog_food`) while production, crm and sales already reference `allergens`/`dietary_tags`                                                                                                                                     | `DOMAIN_MAP.md` lines 38, 78; FKs in 0110, 0180, 0200                         | Decide the boundary before C24; do not expose these tables before                                                                                                                                                                                            |
| R13 | **No menu-to-outlet assignment** (closed: M2a assigns menus to outlets, M2b reads them in the till; kept as the original design finding)                                                                                                                       | G1                                                                            | OD7                                                                                                                                                                                                                                                          |
| R14 | **`modifier_groups` has no default selection rule**: min/max live only on each item link, so "Choose a side (1 required)" is repeated per item                                                                                                                 | 1672 vs 1937                                                                  | Accepted for v1 (one place to read); a group-level default can be added if owners complain                                                                                                                                                                   |
| R15 | **Canonical SQL keeps comments**; new migrations cannot add any (`lint:no-comments`, shrinking allowlist)                                                                                                                                                      | `AGENTS.md` §4                                                                | K1 SQL is comment-free; intent lives in test names and this document                                                                                                                                                                                         |
| R16 | **Audit retention class** for tenant configuration actions: organization actions use `administration.platform`                                                                                                                                                 | migration `0039`                                                              | Assumption: reuse it for catalog `configuration` actions unless the audit owner defines a tenant configuration class                                                                                                                                         |
| R17 | **Deleting link rows.** `item_categories` and `item_modifier_groups` have `FOR ALL` policies, so DELETE is RLS-allowed once granted (since revision 101 only `item_categories` is granted: K9c); the audit trail must carry before/after since the rows vanish | 3980, `item_modifier_groups_tenant_policy`                                    | C8 and C13 audit the complete before/after lists                                                                                                                                                                                                             |
| R19 | **The Sales order-line trigger is unit-keyed.** It calls `catalog.assert_variant_listed`, which does not know the outlet, so it enforces neither the hiding of an outlet nor the listing of an option target                                                   | `0110_sales.sql`; K16, K16b                                                   | Known limit, a Sales decision: Catalog refuses at `resolve` and `admit`, which Sales calls first; moving the trigger to `catalog.variant_is_listed_at_outlet` is Sales'                                                                                      |
| R18 | `organization.effective_business_unit` returns `NULL` for an outlet with no active assignment on the date; C17 and C19 answer an empty list (not `500`) for a caller the permission step admits                                                                | `0020_organization.sql`, function and comment (verified)                      | K7 test rows (C17, C19)                                                                                                                                                                                                                                      |

What this document could not verify: the full body of
`catalog.check_item_default_variant` (only its constraint-trigger
declaration was read), the retention classes available in `audit`, and any
real tenant cardinalities (§8.1 is an estimate).

***

## 12. Glossary

| Term                        | Meaning here                                                                                                                                                   |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Catalog (namespace)**     | A `catalog.catalogs` row grouping master data; v1 uses only the organization's default one                                                                     |
| **Item**                    | The commercial thing a business sells (dish, product, service). Not stock, not a recipe, not a price                                                           |
| **Variant**                 | A concrete sellable form of an item (size, colour). Every item has exactly one default variant; downstream modules always reference variants                   |
| **Default variant**         | The variant used when an item has no visible variants; hidden in simple UX                                                                                     |
| **SKU**                     | Tenant-chosen stock-keeping code of a variant, unique per catalog                                                                                              |
| **Barcode**                 | A scannable value of a variant; several per variant, unique per catalog, never re-pointed                                                                      |
| **Category**                | Classification node; items have one primary category used to group the POS                                                                                     |
| **Modifier group / option** | A choice offered when selling an item; an option is an instruction ("no onion") or a reference to another variant ("extra cheese")                             |
| **Selection rule**          | `minSelections`/`maxSelections` of a modifier group on one item                                                                                                |
| **Assortment**              | Which items a business unit sells: `all` (with exclusions), `selected` (with inclusions) or `none`                                                             |
| **Hidden item**             | An item one outlet does not sell although its business unit lists it (K16, C30); an outlet can only hide, never add                                            |
| **Listed / sellable**       | An active item and variant, in an active catalog, included by the assortment of the business unit that operates the outlet today and not hidden by that outlet |
| **Sellable read**           | The compact, ETagged list an outlet's POS loads (C17)                                                                                                          |
| **Admission**               | The locked check that a variant is sellable at the moment a sale line is created (C20)                                                                         |
| **Anchor**                  | The place where a permission is checked: organization-wide, business unit or outlet (`identity.effective_permission_at`)                                       |
| **Catalog version**         | Per-organization counter bumped on any catalog write; the base of the POS ETag (G2)                                                                            |

### S3 as built: sort, search inside the text and facets of the item list (migration `0121_catalog_item_search_and_sort.sql`)

Decision record: `docs/reference/DECISIONS.md` D51.

`GET /catalog/items` takes four additions, all optional and all keyset: `sort` (`name` default, `code`, `createdAt`, `updatedAt`, `status`), `order` (`asc` default, `desc`), a `q` that finds the text inside the name, the code, any SKU or the brand name (and inside an active barcode when the text is only digits) from 3 characters, and `facets`.

```
GET /catalog/items?sort=updatedAt&order=desc&q=latte&limit=2&facets=status,brand,attr.processor
```

```json
{
  "data": [
    { "itemId": "…", "code": "BEV-007", "name": "Café Latte", "status": "active" },
    { "itemId": "…", "code": "BEV-009", "name": "Latte grande", "status": "inactive" }
  ],
  "meta": {
    "pageInfo": { "hasNextPage": false, "endCursor": "…" },
    "facets": {
      "capped": false,
      "total": 2,
      "counts": {
        "status": [{ "value": "active", "count": 1 }, { "value": "inactive", "count": 1 }],
        "brand": [{ "value": "01930000-0000-7000-8000-0000000000b1", "count": 2 }]
      }
    }
  }
}
```

* The cursor is signed with the route, the organization, every filter and, when it is not the default, the sort and the order; a cursor of another sort, order, filter or organization is refused with 400 `collection.cursor_incompatible` and a tampered one with `collection.cursor_tampered`. The default order (name ascending) adds nothing to the binding, so the first page of the workspace and cursors already issued keep working.
* One statement per page whatever the sort: every status is a branch read in index order with its own `LIMIT`, merged and limited again. `code` uses `(organization_id, catalog_id, status, code_search_key, id)` and `createdAt`, `updatedAt` and `status` their own `(…, status, <column>, id)` indexes, so no order sorts the catalog.
* `q` shorter than 3 characters is a prefix of the name, the code or a SKU (index range); from 3 characters it uses the trigram GIN indexes `(organization_id, <key> gin_trgm_ops)`. `%`, `_` and `\` are literal. The till search (`GET /catalog/outlets/{outletId}/sellable-item-search`) uses the same candidates, restricted to active variants and to what the outlet sells.
* `facets` costs one extra statement over a `LIMIT 5001` materialization of the filtered ids, so the counts are those of the whole filtered set, not of the page; `meta.facets.capped` is true when the set has more than 5,000 items. Attribute facets (up to 3) need a filterable, active definition; their value is the option code, text, number or boolean, and an item with the value on several variants counts once. Without `facets` nothing is read or sent.

Measured (`npm run perf:http`, one client, 500 requests per row, three runs alternating the previous commit and this one on the same database, load average 5 to 12 on a shared development machine; budgets p50 < 15, p90 < 35, p95 < 50, p99 < 100 ms; no known breach was edited):

| Row | Before p50 / p95 / p99 (ms) | After p50 / p95 / p99 (ms) | Bytes |
| :-- | :-- | :-- | :-- |
| till search, first page of 50 | 12.6-13.7 / 13.7-14.9 / 16.0-18.0 | 12.4-13.9 / 13.9-15.4 / 16.0-21.1 | 24,860 both |
| till search `q=cerv` (prefix) | 13.0-14.1 / 14.2-15.2 / 16.6-23.0 | 13.4-15.5 / 15.2-18.4 / 18.0-32.9 | 21,688 both |
| till search `q=erve` (inside) | 9.6-10.4 (finds nothing) / 10.7-11.3 / 13.2-14.7 | 13.8-14.1 / 15.2-15.4 / 16.9-22.5 | 165, now 21,688 |

The inside search costs the same as the prefix search it replaces for a text that finds the same 45 items (p50 about 14 ms). Its p50 sits close to the 15 ms budget on a loaded machine, so a regression there should be read against the prefix row measured in the same run. The item list is an administrative route and is not in `perf:http`; its plans are guarded by `item-list.plan.integration-spec.ts` (rows and buffers read for every sort, direction, status set and text, after a 2,001-item import with stale statistics).

Note: `meta.facets` is optional in the 200 schema of `GET /catalog/items` (present only with `facets=`); it was `required` before the envelope generator learned optional extra meta entries.

### S4 as built: bulk operations over items (migration `0124_catalog_bulk_operations.sql`)

Decision record: `docs/reference/DECISIONS.md` D52.

`POST /catalog/bulk-operations` applies one operation to 1 to 200 distinct items of the organization in one transaction, all or nothing. The request is the operation, the ids and only what changes; the server reads the rest.

| `op` | `params` | Rule |
|---|---|---|
| `activate`, `deactivate`, `archive`, `restore` | none | the status rules of the item lifecycle (`domain/items/item-lifecycle.ts`, no copy); an item already in the target status is `unchanged`; any other step is `transition_invalid`; `archive` releases the active barcodes of the item |
| `categories.add`, `categories.remove`, `categories.set` | `categoryIds` (at most 50; `set` accepts an empty list) | deltas only; a category added has to exist and not be archived; the primary category is never chosen here |
| `brand.set` | `brandId` (`null` clears) | the brand has to exist and not be archived |

Listing in and out of the assortment of a business unit is not part of this first cut: `POST /catalog/business-units/{id}/assortment` curation already takes up to many ids all or nothing.

```json
{
  "op": "archive",
  "ids": ["01930000-0000-7000-8000-0000000000a1", "01930000-0000-7000-8000-0000000000a2"],
  "ifMatch": { "01930000-0000-7000-8000-0000000000a1": "\"3f2a...\"" },
  "dryRun": false
}
```

```json
{
  "data": {
    "operation": "archive",
    "dryRun": false,
    "applied": true,
    "counts": { "requested": 2, "changed": 2, "unchanged": 0, "failed": 0 },
    "results": [
      { "id": "01930000-0000-7000-8000-0000000000a1", "ok": true, "changed": true },
      { "id": "01930000-0000-7000-8000-0000000000a2", "ok": true, "changed": true }
    ]
  }
}
```

Rules, each proved in `CATALOG_CASE_MATRIX.md` S4:

* Atomicity is decided as all or nothing per request. An apply with any failing id answers `422 catalog.bulk_operation_rejected`, `meta.errors` names each failing id (`ids.<id>`, code `not_found`, `archived`, `transition_invalid` or `precondition_failed`) and nothing is written. `dryRun: true` answers `200` with the per-id results and the counts, reads the Idempotency-Key never, and writes, records and audits nothing.
* An unknown id and an id of another organization are both `not_found`.
* `ifMatch` is an optional map from an id of `ids` to its ETag; a stale tag is `precondition_failed` for that id.
* An apply needs an `Idempotency-Key`: the same key and body answer the stored report with `Idempotent-Replayed: true` and write nothing; the same key with another body is `409 idempotency.key_reused`. The report is stored in `catalog.bulk_operations` in the same transaction as the change.
* One audit record `catalog.bulk_operation.applied` keeps the operation and its counts, never one per item.
* Lock order: the catalog version row first, then the items in id order, then the shared locks of the categories and the brand, the order of the other item writers, so a bulk operation never deadlocks with imports, clones or category writers (proved with concurrent writers, no `40P01`).
* Every write is one set based statement whatever the number of items (status, category links, brand, barcodes released), plus the change feed rows the existing statement triggers write.

Measurements, local, 200 items in an organization with an active assortment (a change event per item): `categories.add` 88 ms, `archive` 78 ms and `restore` 75 ms with 200 change events each, a 200 id dry run 10 ms, a response of 14 KB. The cap of 200 stays: it is about 25 times under the 2 s budget.

### S5 as built: reorder and move categories (no migration)

Decision record: `docs/reference/DECISIONS.md` D53.

`POST /catalog/categories/{categoryId}/moves` takes `{ "parentId": "<uuid>|null", "before": "<sibling uuid>" }` (at least one; `parentId` left out keeps the parent, `before` left out places the category last) and answers the category with its new ETag. `PUT /catalog/categories/order` takes `{ "parentId": "<uuid>|null", "ids": [...] }`, the whole ordered list of the children of that parent (archived children included), and answers `{ parentId, ids, changed }` where `changed` is the number of children of the parent.

The position is the `sort_order` of the children of the parent, renumbered from 0 in one `UPDATE ... FROM unnest` that writes only the categories whose number changes. Lock order: the catalog version row, the category (and the parent for an order), then the children of the target parent in id order. A move under another parent is judged by the same placement rules as `PATCH /catalog/categories/{categoryId}` (cycle, depth, archived). One audit record `catalog.category.moved` keeps the parent and the order before and after; a request that changes nothing records nothing.

```json
{ "parentId": "01930000-0000-7000-8000-0000000000b1", "before": "01930000-0000-7000-8000-0000000000b4" }
```

### CD1 as built: duplicate an item, a modifier group or a menu (migration `0125_catalog_clone_and_duplications.sql`)

Decision record: `docs/reference/DECISIONS.md` D54.

Three actions, one shape: `POST /catalog/items/{itemId}/duplications`, `POST /catalog/modifier-groups/{modifierGroupId}/duplications` and `POST /catalog/menus/{menuId}/duplications`. The request is `{code?, name?}` (`{}` is valid) with a required `Idempotency-Key`; the server derives everything else. Needs the permission that creates the same kind of resource.

```json
POST /api/v1/catalog/items/01930000-0000-7000-8000-0000000000d0/duplications
Idempotency-Key: 01930000-0000-7000-8000-0000000000e1

{ "name": "Lomo saltado doble" }
```

```json
201 Created
ETag: "4b1c0f3a9d2e7a64"

{
  "data": {
    "id": "01930000-0000-7000-8000-0000000000d1",
    "code": "lomo-saltado-copy",
    "name": "Lomo saltado doble",
    "duplicatedFrom": { "id": "01930000-0000-7000-8000-0000000000d0" },
    "counts": { "variants": 3, "categories": 2, "modifierOffers": 1, "attributeValues": 0, "images": 1, "bundleGroups": 0 }
  }
}
```

| Entity | What is copied | What is not | The copy is |
|---|---|---|---|
| Item | variants (SKUs regenerated), categories, modifier offers with defaults and overrides, attributes, regulatory flags, variant dimensions, bundle groups, image references | barcodes, variant identifiers, menu entries | the status of the source |
| Modifier group | the group and its options | the offers on items | the status of the source |
| Menu | the menu, its sections and entries | | `draft` |

The name left out is the source name plus ` (copy)`. The code left out is the source code plus `-copy`, then `-copy-2`, `-copy-3` until it is free in the catalog ignoring case; a code sent that is taken answers `409 catalog.code_taken`. A replay of the same key and body answers `201` with `Idempotent-Replayed: true` and writes nothing; the same key with another body answers `409 idempotency.key_reused`. An archived source answers `422`, a source of another organization `404`, a catalog at its cap (100 menus, 500 modifier groups, 1,200 items) `422`. Measured: 11 statements for an item of 2 or 20 variants, a body of about 330 bytes, 40 to 70 ms.

### S7 as built: the catalog health report (no migration)

Decision record: `docs/reference/DECISIONS.md` D55.

`GET /catalog/health` answers what is wrong or incomplete in one catalog. It needs `catalog.items.view` like every catalog read (organization-wide, or at `businessUnitId`), never needs the plan, records nothing and changes nothing.

| Query | Rule |
|---|---|
| `catalogId` | the catalog to read; the default catalog when absent; a catalog the organization does not have is `404 catalog.not_found` |
| `include` | comma separated checks, each once, in the order asked; every check when absent; an unknown or repeated one is `400` |
| `limit` | ids named per check, 1 to 50, 5 by default; the `count` is always the full count |

| Check | Severity | Names |
|---|---|---|
| `items_without_category` | warning | items not archived with no category link |
| `items_without_image` | info | items not archived with no image |
| `items_without_sellable_variant` | warning | items not archived with no active variant (an active item always keeps an active default variant, so these are inactive items that cannot be activated yet) |
| `empty_modifier_groups` | warning | active modifier groups with no active option |
| `unsatisfiable_modifier_offers` | error | active offers of a group on an active item whose minimum is above the active options |
| `unsatisfiable_combo_groups` | error | active combo groups of an active item whose minimum is above the active choices whose variant is active |
| `empty_menus` | warning | active menus with no active entry of an item that is not archived |
| `archived_targets_in_active_offers` | error | active modifier offers on an archived item or group, active options and combo choices on an archived variant |
| `duplicate_identifiers` | warning | active barcodes that an archived barcode also holds, active variants whose trimmed lowercase SKU an archived variant holds |
| `items_offered_nowhere` | info | active items with no active menu entry in an active menu and no business unit assortment (a unit that takes the whole catalog offers every item) |
| `retired_variants_in_menus` | error | entries of a menu that is not archived that still list an inactive or archived variant |

Statement cap: one statement per check, each set based over the whole catalog (a `count` and the `limit` smallest ids from the same violations), plus one header statement that reads the catalog version and resolves the default catalog. A read is therefore 6 statements of the request plus 1 plus the number of checks asked (18 for the default catalog, 19 when `catalogId` is sent because the scope is checked first), whatever the number of items. A check never adds a statement per item.

```json
GET /api/v1/catalog/health?include=items_without_category,empty_menus&limit=2

{
  "data": {
    "catalogId": "01930000-0000-7000-8000-0000000000c1",
    "checks": [
      {
        "check": "items_without_category",
        "severity": "warning",
        "count": 12,
        "sampleIds": ["01930000-0000-7000-8000-0000000000a1", "01930000-0000-7000-8000-0000000000a2"]
      },
      { "check": "empty_menus", "severity": "warning", "count": 0, "sampleIds": [] }
    ]
  }
}
```

The strong ETag derives from the organization, the catalog version, the catalog, the checks and the limit: the version moves on every catalog write, so the tag changes exactly when the report can, and `If-None-Match` with the current tag answers `304`.

Measured on 5,000 items (`catalog-health-scale.e2e-spec.ts`, `catalog-health.plan.integration-spec.ts`): the same number of statements as an empty catalog, a body under 3,000 bytes, and at most 4.1 buffers per item and check against a ceiling of 6, with the statistics frozen before the import and no sequential scan of the catalog tables.

Rules, each proved in `CATALOG_CASE_MATRIX.md` S7; each check fails a test when its rule is broken (one mutation per branch, listed in D55).

### MW1 as built: the dates and the sales channels of a menu (migration 0122)

Decision record: `docs/reference/DECISIONS.md` D56.

A menu is offered between two dates and on a list of sales channels, both optional. `catalog.menus` gets `valid_from` and `valid_until` (dates, nullable, both ends inclusive, `valid_until >= valid_from`, both between 2000-01-01 and 2100-12-31) and the table `catalog.menu_channels (menu_id, sales_channel_id)` lists the channels; no row means every channel. The dates are read as dates of the outlet that shows the menu, in its site time zone, the same local clock the time-of-day windows use. Two active menus may overlap: nothing excludes it.

Three routes change them, all with the same contract: `If-Match` with the tag of `GET /catalog/menus/{menuId}` is required (`428 precondition.required` without it or with `*`, `412 foundation.precondition_failed` when stale), there is no `Idempotency-Key`, an archived menu is `422 catalog.menu_archived`, and the answer is lean.

| Route | Body | Notes |
|---|---|---|
| `PUT /catalog/menus/{menuId}/window` | `{ "validFrom"?: "YYYY-MM-DD" \| null, "validUntil"?: "YYYY-MM-DD" \| null }` | replaces both dates; an omitted or null date leaves that end open; `validUntil` before `validFrom`, an impossible date or one outside the horizon is `400` |
| `POST /catalog/menus/{menuId}/channels` | `{ "salesChannelId": "<uuid>" }` | a channel that does not exist or belongs to another organization is `404 catalog.not_found` |
| `DELETE /catalog/menus/{menuId}/channels/{salesChannelId}` | none | removing a channel the menu does not list is `already_in_effect`; never needs the plan |

```http
PUT /catalog/menus/01930000-0000-7000-8000-0000000000d0/window
If-Match: "9c1f…"
{ "validFrom": "2026-03-01", "validUntil": "2026-09-30" }
```

```json
{
  "data": {
    "menuId": "01930000-0000-7000-8000-0000000000d0",
    "outcome": "change",
    "changed": true,
    "etag": "\"3f9a1c0d…\""
  }
}
```

The same call again answers `"outcome": "already_in_effect"`, `"changed": false` and the same tag: nothing is written, audited or versioned. A real change is audited as `catalog.menu.window_set`, `catalog.menu.channel_added` or `catalog.menu.channel_removed` and moves the catalog version once.

`GET /catalog/menus/{menuId}` also answers `validFrom`, `validUntil` and `channelIds` (sorted by id), all part of the tag. The till read `GET /catalog/outlets/{outletId}/sellable-items` lists only the menus whose dates contain the local date of the outlet (the shown mask, and so the entity tag, follows the date) and takes an optional `salesChannelId`: absent, the menus are not narrowed; present, only the menus with no channel or listing it. The channel is part of the entity tag, and the items are never narrowed. Cloning a catalog and duplicating a menu copy the dates and the channels.

| Measured | Statements | Body |
|---|---:|---:|
| window, add or remove channel, a real change | 10 | 180 bytes |
| the same call already in effect | 8 | 192 bytes |
| till read: statements of `sellable-items` | unchanged | unchanged |

Rules, each proved in `CATALOG_CASE_MATRIX.md` MW1.

## 13. Change sets as built (slice S10.1)

A change set is a draft of one catalog: a journal of delta commands recorded without touching live data. This slice records, removes, discards, lists, reads and compares; publishing and the till preview come later. Change sets are for evolving the live catalog; a parallel catalog is still a clone assigned with CA3. They do not compete.

| Route | Needs | Answer |
|---|---|---|
| `POST /catalog/change-sets` | `catalog.change_sets.write` | `201`, the draft and its ETag |
| `GET /catalog/change-sets?status=&limit=&after=&before=` | `catalog.change_sets.read` | `200`, a keyset page, newest first |
| `GET /catalog/change-sets/{changeSetId}` | `catalog.change_sets.read` | `200` with the ETag, `304` on `If-None-Match` |
| `POST /catalog/change-sets/{changeSetId}/operations` | `catalog.change_sets.write`, `If-Match` | `200`, up to 50 operations, `Validate-Only` |
| `DELETE /catalog/change-sets/{changeSetId}/operations/{seq}` | `catalog.change_sets.write`, `If-Match` | `200`, the draft |
| `POST /catalog/change-sets/{changeSetId}/discard` | `catalog.change_sets.write`, `If-Match` | `200`, `changed` or `already_in_effect` |
| `GET /catalog/change-sets/{changeSetId}/diff` | `catalog.change_sets.read` | `200`, the journal diff |

The permissions `catalog.change_sets.write`, `read`, `preview` and `publish` go to `organization_owner` and `manager`; `preview` and `publish` are only seeded. The ETag is a hash of the id and the revision, which moves with every accepted write.

Operations. `op` is one of the live delta routes and `body` is that route's own request schema, reused by reference, so the two cannot drift (a spec fails when a live write route of menus or outlet menus is neither registered nor excluded with a reason). `target` holds the ids of the route path.

| `op` | Live route | `target` |
|---|---|---|
| `menu.entry.add` | `POST /catalog/menus/{menuId}/sections/{sectionId}/entries` | `menuId`, `sectionId` |
| `menu.entry.change` | `PATCH /catalog/menus/{menuId}/entries/{entryId}` | `menuId`, `entryId` |
| `menu.entry.move` | `POST /catalog/menus/{menuId}/entries/{entryId}/moves` | `menuId`, `entryId` |
| `menu.entry.remove` | `DELETE /catalog/menus/{menuId}/entries/{entryId}` | `menuId`, `entryId` |
| `outlet.menus.set` | `PUT /catalog/outlets/{outletId}/menus` | `outletId` |

Create:

```json
POST /catalog/change-sets
{"catalogId": "01930000-0000-7000-8000-0000000000c1", "name": "Summer menu", "expiresInDays": 30}

201  ETag: "9f2c..."
{"data": {"changeSetId": "01930000-0000-7000-8000-0000000000d1", "catalogId": "01930000-0000-7000-8000-0000000000c1",
  "name": "Summer menu", "status": "draft", "opCount": 0, "createdAt": "2026-11-16T10:00:00.000Z",
  "expiresAt": "2026-12-16T10:00:00.000Z", "etag": "9f2c...", "baseCatalogVersion": 812, "updatedAt": "2026-11-16T10:00:00.000Z"}}
```

Record commands (request = ids and what changes):

```json
POST /catalog/change-sets/{changeSetId}/operations     If-Match: "9f2c..."
{"operations": [
  {"clientOpId": "01930000-0000-7000-8000-0000000000d2", "op": "menu.entry.add",
   "target": {"menuId": "...", "sectionId": "..."}, "body": {"itemId": "..."}},
  {"clientOpId": "01930000-0000-7000-8000-0000000000d3", "op": "menu.entry.remove",
   "target": {"menuId": "...", "entryId": "..."}}]}

200  ETag: "a41b..."
{"data": {"etag": "a41b...", "opCount": 2, "accepted": [
  {"clientOpId": "01930000-0000-7000-8000-0000000000d2", "seq": 1, "outcome": "recorded"},
  {"clientOpId": "01930000-0000-7000-8000-0000000000d3", "seq": 2, "outcome": "recorded"}]}}
```

Sending the same operation again with the same `clientOpId` answers `already_recorded` with the original `seq`, writes nothing and leaves the ETag alone; the same `clientOpId` with other content is `409 catalog.change_set_client_op_reused`. `ifMatch` on an operation is the ETag of the aggregate the client saw; absent, the server reads the live one when it records the operation.

Diff (journal diff, no replay):

```json
GET /catalog/change-sets/{changeSetId}/diff
200 {"data": {"changeSetId": "...", "status": "draft", "etag": "a41b...",
  "aggregates": [{"kind": "menu", "id": "...", "ops": [1, 2], "exists": true, "stale": false}],
  "counts": {"menu.entry.add": 1, "menu.entry.remove": 1}}}
```

`stale` is true when the live ETag of the aggregate is no longer the one recorded with its first operation.

Validation at record time uses the rules of the live route against the live state: the menu structure rules (section and menu caps, repeated entries, variants), the items of the same catalog, and the outlet menu rules (menu status, windows). A sequence of commands that only works together is proven when it is published, not here. A target of another catalog is `422 catalog.change_set_target_other_catalog`; an archived catalog refuses writes (`422 catalog.catalog_archived`) and still discards.

Limits (also in `GET /catalog/metadata`, section `limits.changeSets`): 100 operations per draft, 50 per request, 16 KiB of target and body per operation, a body of 1 MiB, 30 days of life by default and 90 at most, a name of 200 characters. One open change set (`draft` or `ready`) per catalog.

| Measured | Statements | Request | Response |
|---|---:|---:|---:|
| create | 11 | 68 bytes | 384 bytes |
| read | 7 | - | 384 bytes |
| list | 7 | - | 957 bytes for one row |
| record 1, 10 or 50 operations on one menu | 14 | 203, 1,886, 9,366 bytes | 202, 952, 4,320 bytes |
| remove one | 12 | - | 385 bytes |
| discard | 10 | - | 188 bytes |
| diff of one aggregate | 9 | - | 483 bytes |

Rules, each proved in `CATALOG_CASE_MATRIX.md` CS1.

## 14. Ready and publish as built (slice S10.2)

| Route | Permission and headers | Answer |
|---|---|---|
| `POST /catalog/change-sets/{changeSetId}/ready` | `catalog.change_sets.write`, `If-Match`, `Validate-Only` | `200` with the new ETag and `validatedAtVersion` |
| `POST /catalog/change-sets/{changeSetId}/publish` | `catalog.change_sets.publish`, `If-Match`, `Idempotency-Key`, `Validate-Only` | `200` with the ETag, the version range and the counts; `Idempotent-Replayed: true` on a repeat |

Ready replays the journal inside a savepoint that is rolled back: nothing live is written, the catalog version does not move and no feed event stays. Any later edit sends the set back to draft. Publish takes the catalog version row first, then the change set row, compares the base tag of every operation with the live tag of its target (one `412 catalog.change_set_conflict` lists up to 50 operations as field errors `operations.N`, `meta.truncated` says more exist, nothing is applied), refuses a set that costs more than the budget (`422 catalog.change_set_too_costly`, before applying), replays the operations in seq order through the live use cases with the permission of each live route checked for the publisher, aborts and rolls back when the wall clock budget is spent (`503` with `Retry-After 5`; the body is the generic platform problem, never a catalog code), writes one audit record and stores its answer on the change set. A publisher who holds only `catalog.change_sets.publish` is refused with `403` by the live admission of the first operation. A member may publish their own set only when they hold write and publish.

```
POST /catalog/change-sets/0195.../publish   If-Match: "9f2c..."   Idempotency-Key: 0195...
200 {"data": {"changeSetId": "0195...", "status": "published", "etag": "7ab1...",
  "catalogVersion": {"from": 815, "to": 836},
  "applied": {"menu.entry.add": 12, "outlet.menus.set": 1}, "operationCount": 13,
  "publishedAt": "2026-11-16T10:00:00.000Z"}, "meta": {...}}
412 {"code": "catalog.change_set_conflict", "meta": {"errors": [{"location": "body", "field": "operations.7",
  "code": "catalog.change_set_conflict", "message": "The menu 0195... changed after this operation was recorded: it expected 3fa0... and the live one is 91bc...."}], "truncated": false}}
```

The catalog version moves exactly once per publish that changed something (slice S10.5; before it moved about once per write of each operation, 1.1 per operation measured), so `catalogVersion.to - from` is 1, or 0 for a publish that changed nothing, and the change feed receives one event per distinct change at that version.

| Measured (one client, loaded laptop) | Statements | Response | Time |
|---|---:|---:|---:|
| ready, 10 / 50 / 100 operations | 117 / 533 / 1,053 | about 380 bytes | 237 / 1,335 / 2,873 ms |
| publish, 10 / 50 / 100 operations | 118 / 534 / 1,054 | 382 / 385 / 389 bytes | 255 / 1,367 / 2,975 ms |
| replay only, 200 operations | 2,079 | - | 3.7 to 6.6 s |

Limits: 100 operations per draft (lowered from 200 by the measurement), a cost budget of 1,200 units (menu entry operations weigh 11, `outlet.menus.set` 15), a wall clock budget of 4,000 ms, at most 50 conflicts reported (all in `GET /catalog/metadata`, `limits.changeSets`). Rules, each proved in `CATALOG_CASE_MATRIX.md` CS2.

## 15. Preview and resolved diff as built (slice S10.3)

| Route | Permission and headers | Answer |
|---|---|---|
| `GET /catalog/change-sets/{changeSetId}/preview/outlets/{outletId}/sellables?locale&salesChannelId&at` | `catalog.change_sets.read`, `catalog.change_sets.preview`, the permission of every recorded operation and `catalog.sellables.view` at the outlet | `200` with the till sellables document of the replayed state and `previewOf`; `Cache-Control: no-store`, no `ETag`, never `304` |
| `GET /catalog/change-sets/{changeSetId}/diff?mode=resolved` | the same | `200` with the journal diff and, per aggregate, `resolved`, plus `resolvedAgainst`; `mode=journal` (default) is unchanged and needs only `catalog.change_sets.read` |

Both replay the journal through the same use cases as publish inside a transaction that is always rolled back: no row, no change feed event and no audit record of success stays, and the catalog version does not move. The preview then runs the very same till read (`GET /catalog/outlets/{outletId}/sellable-items`: same use case, SQL and projection) in that transaction, so it sees the replayed state; `at` (ISO-8601 instant, default now) evaluates the menu windows and the local date of the outlet at that instant, a parameter the live read does not have. The outlet must run, through its business unit, the catalog of the change set (any other outlet, foreign or unknown, is the same `404`). The permission rule is deliberately strict (D63): a previewer needs the permission of each live operation, so nobody sees through a preview what they could not read or change directly.

```
GET /catalog/change-sets/0195.../preview/outlets/0196.../sellables?at=2026-12-24T12:00:00Z
200 Cache-Control: no-store
{"data": {"businessUnitId": "0197...", "categories": [...], "items": [...], "modifierGroups": [...],
  "menus": [{"menuId": "0198...", "name": "Almuerzo", "sections": [{"name": "Entradas", "entries": [{"itemId": "0199..."}]}]}],
  "previewOf": {"changeSetId": "0195...", "etag": "9f2c...", "baseCatalogVersion": 812, "liveCatalogVersion": 815, "stale": true}},
 "meta": {"truncated": false, "omittedItems": 0, "media": {"tileUrlTemplate": "https://media.ninaku.io/a/{imageRef}/tile.webp"}}}
429 {"code": "rate_limit.exceeded"}   Retry-After: 4
503 Retry-After: 1   (the catalog lock was not free in time, or the replay ran longer than 4,000 ms)
409 {"code": "catalog.change_set_not_open"}   (published, discarded or expired)
```

```
GET /catalog/change-sets/0195.../diff?mode=resolved
200 {"data": {"changeSetId": "0195...", "status": "ready", "etag": "9f2c...",
  "aggregates": [{"kind": "menu", "id": "0198...", "ops": [1, 2, 3], "exists": true, "stale": false,
    "resolved": {"entity": "menuEntry", "before": 3, "after": 3,
      "created": [{"id": "01a0...", "name": "Chicha morada"}],
      "changed": [{"id": "01a1...", "name": "Flan", "fields": ["suspended"]}],
      "removed": [{"id": "01a2...", "name": "Agua"}], "reordered": false, "truncated": false}}],
  "counts": {"menu.entry.add": 1, "menu.entry.change": 1, "menu.entry.remove": 1},
  "resolvedAgainst": {"baseCatalogVersion": 812, "liveCatalogVersion": 812, "stale": false}}}
```

Each list holds ids and names only (at most 100 per list, `truncated` says more exist); `reordered` compares only the entities that exist before and after, so adding or removing one never sets it. A replay is limited to one per member and change set every 5 seconds for the preview and, apart, for the resolved diff.

| Measured (60 entries and 45 spare items, one client) | Statements | Response | Time | A live write started 15 ms later waited |
|---|---:|---:|---:|---:|
| preview, 10 operations | 137 | 35,875 bytes | 237 ms | 223 ms |
| preview, 50 operations | 553 | 35,875 bytes | 605 ms | 589 ms |
| preview, 100 operations | 1,073 | 35,875 bytes | 1,932 ms | 1,917 ms |

Until slice S10.5 the preview held the catalog version lock until the rollback and live catalog writes waited that long (section 17 removes the lock). The cost is bounded by the 100 operation cap, the 4 second budget (`limits.changeSets.publishWallClockMs` in `GET /catalog/metadata`; a heavily loaded machine takes longer for the same journal, so a client must not assume that 100 operations always fit), the rate limit and the 2 second `lock_timeout`.

## 16. Item operations and creations as built (slice S10.4)

`POST /catalog/change-sets/{changeSetId}/operations` accepts fourteen more operation codes. Each takes the path ids in `target` and exactly the live request body in `body`; the aggregate it changes is named by the target kind of the journal and compared with the live ETag of that aggregate when the set is published.

| `op` | Live route | Target kind | Live ETag |
|---|---|---|---|
| `item.category.add`, `item.category.change`, `item.category.remove` | `POST`, `PATCH`, `DELETE /catalog/items/{itemId}/categories[/{categoryId}]` | `item_categories` | item |
| `item.offer.add`, `item.offer.change`, `item.offer.remove`, `item.offer.move` | `POST`, `PATCH`, `DELETE /catalog/items/{itemId}/modifier-groups[/{modifierGroupId}[/moves]]` | `item_offers` | item |
| `item.status.change` | `POST /catalog/items/{itemId}/transitions` | `item_status` | item |
| `bundle.choice.add`, `bundle.choice.change`, `bundle.choice.remove` | `POST`, `PATCH`, `DELETE /catalog/items/{itemId}/bundle-groups/{bundleGroupId}/choices[/{choiceId}]` | `bundle_choices` | bundle composition |
| `menu.create`, `item.create`, `category.create` | `POST /catalog/menus`, `/catalog/items`, `/catalog/categories` | `menu_creation`, `item_creation`, `category_creation` | none (the entity does not exist yet) |

A creation has no `target` and no `ifMatch`: only `clientOpId`, `op` and `body`. Recording it reserves the id of the new entity (a uuid v7) and answers it, so later operations of the same change set can name it, in `target` or in a body:

```
POST /catalog/change-sets/0195.../operations   If-Match: "1"
{"operations": [
  {"clientOpId": "0195...a", "op": "category.create", "body": {"code": "postres", "name": "Postres"}},
  {"clientOpId": "0195...b", "op": "item.create", "body": {"name": "Flan"}}]}
200 ETag: "2"  {"data": {"etag": "2", "opCount": 2, "accepted": [
  {"clientOpId": "0195...a", "seq": 1, "entityId": "0196...c", "outcome": "recorded"},
  {"clientOpId": "0195...b", "seq": 2, "entityId": "0196...d", "outcome": "recorded"}]}}

POST /catalog/change-sets/0195.../operations   If-Match: "2"
{"operations": [{"clientOpId": "0195...e", "op": "item.category.add",
  "target": {"itemId": "0196...d"}, "body": {"categoryId": "0196...c", "isPrimary": true}}]}
```

Operations are validated in order against live data and the operations before them: a target that is neither live nor created by an earlier operation is `404`, a target or a creation of another catalog is `422 catalog.change_set_target_other_catalog`. Ids inside a body are not read when recording (ready replays them through the live use case and answers what the live route would: `404` for another organization). Removing a creation that a later operation uses is `409 catalog.change_set_operation_in_use`. At ready and publish, an entity already holding a reserved id answers `409 catalog.change_set_entity_id_taken` and nothing is applied. The resolved diff lists each created entity as an aggregate of kind `menu_creation`, `item_creation` or `category_creation` with `exists: false` and `created: [{id, name}]`; `GET /catalog/metadata` lists the operation codes (`enumerations.changeSetOperation`) and their cost (`limits.changeSets.operationCosts`).

| Measured (one client, per operation) | Statements | Time |
|---|---:|---:|
| category add, change, remove | 8, 8, 6 | 6 to 8 ms |
| offer add, change, move, remove | 10, 4, 10, 9 | 3 to 10 ms |
| item status change | 5 | 6 ms |
| combo choice add, change, remove | 11 | 10 to 13 ms |
| menu, item, category creation | 9, 10, 10 | 3 to 8 ms |
| mixed replay of 10, 50, 100 operations | 73, 349, 694 | 7 ms per operation |

## 17. Replay isolation, expiry, payload purge and hardening as built (slice S10.5)

**A replay no longer holds the catalog version.** The preview, the resolved diff and the dry run of ready replay in a `preview` scope: no version bump, no change feed event, no lock on the catalog version row (the version is read, not locked). Publish replays in a `publish` scope: one version increment when the replay closes, only if some statement changed a row, and the feed receives the net changes at that version. Request and response shapes do not change; `catalogVersion.to - from` of a publish is now 1.

```
POST /catalog/change-sets/0195.../publish   (a ready set of 100 menu operations)
200 {"data": {"changeSetId": "0195...", "status": "published", "etag": "7ab1...",
  "catalogVersion": {"from": 815, "to": 816},
  "applied": {"menu.entry.add": 100}, "operationCount": 100,
  "publishedAt": "2026-11-16T10:00:00.000Z"}, "meta": {...}}
```

| Measured by HTTP (one client, a menu of 160 entries), before then after | 10 operations | 50 operations | 100 operations |
|---|---:|---:|---:|
| live write beside a preview, wait in ms | 119 then 106 | 545 then 7 | 1,700 then 6 |
| preview, statements | 137 then 139 | 617 then 619 | 1,217 then 1,219 |
| preview, response bytes (grows with the menu, about 150 bytes per entry) | 173,385 | 175,885 | 180,885 |
| preview, time in ms | 248 then 238 | 739 then 597 | 1,896 then 1,680 |
| ready, time in ms | 120 then 85 | 568 then 428 | 1,678 then 1,485 |
| publish, statements | 138 then 140 | 618 then 620 | 1,218 then 1,220 |
| publish, response bytes | 298 | 298 | 300 |
| publish, time in ms | 88 then 69 | 514 then 479 | 1,717 then 1,511 |
| publish, version bumps then feed events (distinct menu change) | 10 then 1, 10 then 1 | 50 then 1, 50 then 1 | 100 then 1, 100 then 1 |

The caps do not change (100 operations, cost budget 1,200, wall clock 4,000 ms, 2 second `lock_timeout`, one replay every 5 seconds per member and change set): `GET /catalog/metadata` is as before. `ready` still takes the version row first (the lock order of every change set write) and holds it for the dry run.

**Expiry.** An open change set past its `expiresAt` already read as `expired` and refused writes; since this slice a sweep of the worker process (every 60 seconds, at most 100 change sets per run, oldest first) stores the status, bumps the revision (the ETag changes) and writes one `catalog.change_set.expired` audit record, so the catalog accepts a new draft. Writes, ready, publish, discard, preview and the resolved diff of an expired set answer `409 catalog.change_set_not_open`; the journal diff and the reads still answer.

```
GET /catalog/change-sets/0195...
200 ETag: "9c4e..."  {"data": {"changeSetId": "0195...", "catalogId": "0195...", "name": "Summer menu",
  "status": "expired", "opCount": 12, "createdAt": "2026-10-01T09:00:00.000Z",
  "expiresAt": "2026-10-31T09:00:00.000Z", "purgedAt": null, "etag": "9c4e...", ...}}
409 {"code": "catalog.change_set_not_open"}   (any write, ready, publish, discard or preview of it)
```

**Payload purge.** After the retention in the data (`catalog.change_set_settings`, `payload_retention_days` 90) a published, discarded or expired change set loses the bodies of its operations (they read as `{}` in storage and are never part of a response); ids, operation types, targets, status, timestamps, the stored publish result and the audit link stay, so the journal diff still lists the same aggregates and operations. Reads answer `purgedAt`, null while the bodies are kept.

```
GET /catalog/change-sets/0195...
200 ETag: "d1a0..."  {"data": {"changeSetId": "0195...", "status": "published", "opCount": 12,
  "purgedAt": "2027-02-14T10:03:00.000Z", ...}}
```

**Validate-Only.** `POST /catalog/change-sets`, `DELETE .../operations/{seq}` and `POST .../discard` now accept `Validate-Only: true` like operations, ready and publish: `200 {"data": {"valid": true, "problems": []}}`, nothing written, the ETag unchanged; a problem the real call would answer comes back as `valid: false` with that problem (`404`, `400`, `412`, `428`). Before this slice the header was ignored on those three routes and the write happened.

```
POST /catalog/change-sets   Validate-Only: true   {"catalogId": "0195...", "name": ""}
200 {"data": {"valid": false, "problems": [{"status": 400, "code": "foundation.validation_failed", ...}]}}
```

An empty journal is marked ready and published (`operationCount` 0): the catalog version, its feed and the live data do not move; one publish audit record is written.
